feat(plugins): add generic approval ledger and receipts (#3238)

Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Alassane
2026-09-15 18:16:06 -04:00
committed by GitHub
parent 37cea5a8c2
commit cb9752b1a2
27 changed files with 3226 additions and 13 deletions
@@ -0,0 +1,105 @@
---
created: 2026-09-07
status: done
requirements:
- REQ-PLUGINS-CAPABILITY-APPROVAL-001
- REQ-PLUGINS-CAPABILITY-APPROVAL-002
- REQ-PLUGINS-CAPABILITY-APPROVAL-003
- REQ-PLUGINS-CAPABILITY-APPROVAL-004
- REQ-PLUGINS-CAPABILITY-APPROVAL-005
- REQ-PLUGINS-CAPABILITY-APPROVAL-006
system_design:
- ../../specs/plugins/system-design/capability-approval.md
legacy_specs: []
---
# Implementation Plan: Generic Plugin Capability Approval and Audit (H6)
## Overview
Add the generic plugin capability-approval substrate as one vertical work
order: host-minted installation identity, the workspace-scoped approval ledger
with exact-revision admission, the append-only event trail, the fail-closed
authorization decision with typed deny reasons, uninstall tombstones with
reinstall identity, the legacy `v1` fence, and the audit receipt primitives.
Scope is the substrate only: no approval UI, no coordinator surface, and no
host receipt persistence.
## Scope
### In scope
- `installation_id` minting and persistence on the plugin store record.
- One current `CapabilityApproval` per `(installation_id, workspace_id)`.
- Grant, narrow, revoke, and upgrade-review events in an append-only ledger.
- Exact-revision admission and audit-id idempotency.
- Fail-closed `AuthorizeCapability` with stable typed deny reasons.
- Uninstall tombstone and reinstall identity mints.
- The `host.v2` exact-capability fence for legacy `v1` declarations.
- `ApprovalReceipt` and canonical digest primitives.
### Out of scope
- Approval or review UI, coordinator surfaces, dashboards.
- Host adapter persistence of audit or read/write receipts.
- Changes to legacy `v1` runtime behavior beyond fencing it from approval
authority.
- H1-H5 plugin capabilities; this initiative is substrate only.
### No UI changes
This package does not create or change rendered UI, so no ASCII UI preview is
included.
## Technical approach
The ledger (`approvals.json` under the plugins directory) owns approvals,
events, tombstones, and idempotency inputs. One current approval per
installation/workspace pair is stored keyed by the pair with exact next
revision admission; every mutation appends an event carrying before/after
revisions and digests. `installation_id` is minted at install time and
attached to the store record; reinstall mints fresh identity and tombstones
block the old identity permanently.
The authorization path (`approval_service.go`) is a pure decision function
that evaluates in a fixed order — malformed request, human-reserved, missing
approval (including the foreign-workspace alias), revoked or tombstoned,
stale revision, manifest intersection, approved list — and returns a typed
decision carrying the audit identity and a bounded receipt. Legacy `v1`
declarations keep their behavior but are fenced from approval admission and
authorization.
## Tests
- `approval_test.go`, `approval_store_test.go`, `approval_service_test.go`:
canonicalization, exact-revision admission, idempotency, tombstone, and
reinstall-identity coverage.
- `approval_api_test.go`, `approval_query_test.go`: API list/get, grant, and
revoke flows including conflict semantics.
- `approval_dto_test.go`: DTO shape and receipt bounds.
- Store install/sync tests: `installation_id` minting and persistence.
## E2E tests
No new E2E is required: the substrate exposes no UI surface. Go unit and
integration tests exercise the full ledger and decision matrix; a browser
duplicate of that matrix would add cost without observable UI coverage.
## Work orders
- [x] [Task 01: Capability approval substrate](task-01-capability-approval-substrate.md)
## Verification results
- `cd apps/backend && go build ./...` passed on the H6 head and was
re-verified on the merged head.
- `cd apps/backend && go test ./internal/plugins/...` passed in 10 packages
on the H6 head and was re-verified on the merged head.
## Risks
- Ledger file corruption must not grant authority: unknown fields decode
forward-compatibly and missing maps initialize empty, but any decode failure
must fail closed at lookup.
- A future policy revision must not silently reinterpret stored approvals:
the per-row human policy version is the stability point.
@@ -0,0 +1,146 @@
---
id: "01-capability-approval-substrate"
title: "Capability approval substrate"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-PLUGINS-CAPABILITY-APPROVAL-001
- REQ-PLUGINS-CAPABILITY-APPROVAL-002
- REQ-PLUGINS-CAPABILITY-APPROVAL-003
- REQ-PLUGINS-CAPABILITY-APPROVAL-004
- REQ-PLUGINS-CAPABILITY-APPROVAL-005
- REQ-PLUGINS-CAPABILITY-APPROVAL-006
acceptance_criteria:
- AC-PLUGINS-CAPABILITY-APPROVAL-001.1
- AC-PLUGINS-CAPABILITY-APPROVAL-001.2
- AC-PLUGINS-CAPABILITY-APPROVAL-001.3
- AC-PLUGINS-CAPABILITY-APPROVAL-001.4
- AC-PLUGINS-CAPABILITY-APPROVAL-001.5
- AC-PLUGINS-CAPABILITY-APPROVAL-001.6
- AC-PLUGINS-CAPABILITY-APPROVAL-002.1
- AC-PLUGINS-CAPABILITY-APPROVAL-002.2
- AC-PLUGINS-CAPABILITY-APPROVAL-003.1
- AC-PLUGINS-CAPABILITY-APPROVAL-003.2
- AC-PLUGINS-CAPABILITY-APPROVAL-003.3
- AC-PLUGINS-CAPABILITY-APPROVAL-003.4
- AC-PLUGINS-CAPABILITY-APPROVAL-003.5
- AC-PLUGINS-CAPABILITY-APPROVAL-003.6
- AC-PLUGINS-CAPABILITY-APPROVAL-003.7
- AC-PLUGINS-CAPABILITY-APPROVAL-004.1
- AC-PLUGINS-CAPABILITY-APPROVAL-004.2
- AC-PLUGINS-CAPABILITY-APPROVAL-005.1
- AC-PLUGINS-CAPABILITY-APPROVAL-005.2
- AC-PLUGINS-CAPABILITY-APPROVAL-006.1
- AC-PLUGINS-CAPABILITY-APPROVAL-006.2
- AC-PLUGINS-CAPABILITY-APPROVAL-006.3
system_design:
- ../../specs/plugins/system-design/capability-approval.md
---
# Task 01: Capability Approval Substrate
## Summary
Deliver the generic plugin capability-approval substrate: host-minted
installation identity, one current approval per `(installation_id,
workspace_id)`, append-only approval events, exact-revision admission, the
fail-closed authorization decision with typed deny reasons, uninstall
tombstones with fresh reinstall identity, the legacy `v1` fence, and the
audit receipt primitives.
## In scope
- `InstallationID` minting and persistence on the plugin store record.
- `CapabilityApproval` ledger with grant/narrow/revoke/upgrade-review events.
- Exact next-revision admission and audit-id idempotency.
- `AuthorizeCapability` fail-closed decision with stable deny vocabulary.
- Tombstones on uninstall; fresh identity on reinstall.
- `host.v2` exact-capability fence for legacy `v1` declarations.
- `ApprovalReceipt` and canonical digest primitives.
- Service and store APIs for list/get/grant/revoke.
## Out of scope
- Approval UI, coordinator surfaces, dashboards.
- Host adapter persistence of receipts.
- Legacy `v1` behavior changes beyond the fence.
- H1-H5 capabilities.
## Acceptance
- Grants replace the current row for the installation/workspace pair and are
admitted only at the exact next revision with matching manifest digest and
manifest-declared capabilities.
- Every mutation appends an event with before/after revisions and digests;
history is never rewritten.
- Authorization denies missing, revoked, tombstoned, stale, human-reserved,
unavailable, undeclared, and malformed requests with distinct typed reasons;
foreign-workspace requests alias the missing-approval reason.
- Uninstall tombstones the identity permanently; reinstall mints a new
identity, so no approval is inherited.
- Legacy `v1` capabilities are rejected from approval lists and denied at
authorization as unsupported, while retaining their original runtime
behavior.
## Verification
```bash
cd apps/backend && go build ./...
cd apps/backend && go test ./internal/plugins/...
```
## Files likely touched
- `apps/backend/internal/plugins/approval.go`
- `apps/backend/internal/plugins/approval_api.go`
- `apps/backend/internal/plugins/approval_dto.go`
- `apps/backend/internal/plugins/approval_service.go`
- `apps/backend/internal/plugins/approval_store.go`
- `apps/backend/internal/plugins/registry.go`
- `apps/backend/internal/plugins/service.go`
- `apps/backend/internal/plugins/service_install.go`
- `apps/backend/internal/plugins/service_sync.go`
- `apps/backend/internal/plugins/store/store.go`
- `apps/backend/internal/plugins/service_test.go`
- `apps/backend/internal/plugins/store/store_test.go`
## Dependencies
None. This is the substrate initiative; no prior plugin capability wave is
required.
## Risks
- Cross-workspace denial must not leak existence: the foreign-workspace path
intentionally reuses the missing-approval deny reason.
- Ledger decode failures must fail closed at lookup rather than default to
allowing.
## Parallelism
`sequential` — single vertical work order owning the approval files.
## Inputs
- Requirements `REQ-PLUGINS-CAPABILITY-APPROVAL-001` through `-006`.
- System design `docs/specs/plugins/system-design/capability-approval.md`.
- Plan `plan.md`.
- Existing manifest capability derivation (`ManifestCapabilityIDs`) and store
record patterns in `apps/backend/internal/plugins`.
## Results
Implemented the full substrate on the H6 head: installation id minting in the
install path, the approval ledger with events/tombstones/idempotency, the
fail-closed decision path with the typed deny vocabulary, reinstall identity
mints, the `v1` fence, and receipt primitives. Verified with:
```bash
cd apps/backend && go test ./internal/plugins/...
```
Result: all 10 plugin packages pass, including the approval store, service,
API, DTO, and query tests, on the H6 head and re-verified after the merge with
current main.
+6
View File
@@ -268,6 +268,12 @@ curated React, UI, and app-store surface.
- capabilities.auth is the highest-risk capability. A webhook response may
assert a verified external identity with X-Kandev-Auth-Login; only assert an
email the IdP verified as owned by the subject. See [ADR 0050](../decisions/0050-plugin-external-auth-capability.md).
- Plugin installations also carry a host-minted opaque installation identity
and a generic capability-approval ledger. That ledger records approval
history, exact approval revisions, and revocation tombstones for the host
boundary, but there is no public mutation UI in this release. Future exact
Host adapters consume the approval receipt/query surface; they do not derive
authority from plugin IDs, package digests, or workspace state.
An isolated web app has a separate browser boundary. Kandev loads it in a
sandboxed iframe with an opaque origin. It cannot use the host DOM, cookies,
@@ -0,0 +1,193 @@
---
status: active
system: plugins
created: 2026-09-07
owners:
- kandev
---
# Plugin Capability Approval and Audit Requirements
## Overview
Installed plugins request host capabilities. Kandev must gate every capability
request behind an explicit, workspace-scoped human approval, record an
append-only audit trail of approval changes, and evaluate requests against the
intersection of what the installed manifest declares, what the human approved,
and what human policy reserves. This document defines that substrate for
`host.v2` capabilities; it does not define approval UI, coordinator surfaces,
or higher-level plugin features built on it.
## Terminology
- **Installation:** One installed plugin release, identified by a host-minted
opaque `installation_id`. The identity is never derived from the plugin id,
package digest, workspace, or install path.
- **Approval:** One current capability approval row per
`(installation_id, workspace_id)` pair, associating an exact manifest digest
with a canonical list of approved capability ids.
- **Effective authority:** The capability set obtained by intersecting the
installed manifest declaration, the current approval, and the human deny
policy. A capability is allowed only when all three admit it.
- **Human deny policy:** The immutable set of human-reserved capabilities
(merge, deploy, release, history rewrite, cross-workspace access, and
secret-scope expansion) that no approval can ever grant.
- **Tombstone:** The uninstall record that permanently blocks approvals for an
`installation_id` so a reinstall mints a new identity.
## Requirements
### REQ-PLUGINS-CAPABILITY-APPROVAL-001: Workspace-scoped capability approvals
**Intent:** Give each workspace explicit, human-controlled authority over the
capabilities an installed plugin may exercise inside that workspace, with one
current approval per installation and workspace.
**User story:** As a workspace operator, I want to approve exactly the
capabilities a plugin may use in my workspace, so that plugin authority is
explicit, auditable, and never broader than what the installed manifest
declares.
#### Acceptance criteria
- **AC-PLUGINS-CAPABILITY-APPROVAL-001.1:** When a plugin installation is
recorded, the system shall assign it a host-minted opaque `installation_id`
that is not derived from the plugin id, package digest, workspace, or install
path.
- **AC-PLUGINS-CAPABILITY-APPROVAL-001.2:** The system shall keep at most one
current approval per `(installation_id, workspace_id)` pair, and a grant on an
existing pair shall replace the previous current approval.
- **AC-PLUGINS-CAPABILITY-APPROVAL-001.3:** When an approval is recorded, the
system shall reject it unless its manifest digest matches the installed
manifest and every requested capability id is declared by that manifest.
- **AC-PLUGINS-CAPABILITY-APPROVAL-001.4:** When an approval is recorded, the
system shall reject any capability id that is human-reserved, malformed, or
not an exact `host.v2` capability.
- **AC-PLUGINS-CAPABILITY-APPROVAL-001.5:** When a revision differs from the
current approval revision, the system shall reject the write with a revision
conflict and leave the stored approval unchanged.
- **AC-PLUGINS-CAPABILITY-APPROVAL-001.6:** When a grant reuses an audit id with
different inputs, the system shall reject it without changing stored state.
### REQ-PLUGINS-CAPABILITY-APPROVAL-002: Append-only approval events
**Intent:** Preserve a complete, ordered audit trail of every approval change
so authority changes can be reviewed after the fact.
**User story:** As an auditor, I want every grant, narrow, revoke, and
upgrade-review decision recorded with before/after revisions and digests, so
that I can reconstruct how plugin authority changed over time.
#### Acceptance criteria
- **AC-PLUGINS-CAPABILITY-APPROVAL-002.1:** When the system changes an
approval, it shall append an event recording the installation, workspace,
before and after revisions and digests, actor, reason, event type, and an
observed timestamp, without rewriting or removing earlier events.
- **AC-PLUGINS-CAPABILITY-APPROVAL-002.2:** The system shall support the event
types `grant`, `narrow`, `revoke`, and `upgrade_review`.
### REQ-PLUGINS-CAPABILITY-APPROVAL-003: Fail-closed capability authorization
**Intent:** Evaluate every capability request against the manifest ∩ approval
∩ human deny-policy intersection, denying unless all three admit the request.
**User story:** As a workspace operator, I want unauthorized capability requests
to fail closed with a stable machine-readable deny reason, so that stale,
revoked, cross-workspace, or undeclared requests can never succeed and can be
diagnosed reliably.
#### Acceptance criteria
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.1:** When a capability request arrives
whose approval is missing, revoked, or tombstoned, the system shall deny it
with the corresponding stable deny reason and no side effects.
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.2:** When a capability request names a
revision different from the current approval revision, the system shall deny
it as stale.
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.3:** When a capability request comes
from an installation with no approval in the requested workspace, the system
shall deny it with the same deny reason used for missing approvals, without
disclosing that the installation exists in another workspace.
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.4:** When a capability id is
human-reserved, the system shall deny it with the human-reserved deny reason.
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.5:** When the installed manifest no
longer declares the requested capability, or the approval digest no longer
matches the installed manifest, the system shall deny the request as
unavailable.
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.6:** When a request is structurally
malformed (unbounded or NUL-bearing identifiers, invalid digests, or an
unsupported capability form), the system shall deny it as malformed before
any approval lookup.
- **AC-PLUGINS-CAPABILITY-APPROVAL-003.7:** When a request passes every gate,
the system shall allow it and attach the audit identity and a receipt
recording the bounded decision metadata.
### REQ-PLUGINS-CAPABILITY-APPROVAL-004: Uninstall tombstones and reinstall identity
**Intent:** Make uninstalled plugin authority permanently inert and force
reinstalls to start from a fresh installation identity and fresh approvals.
**User story:** As an operator, I want an uninstalled plugin's approvals to be
permanently blocked and a reinstalled copy to require new approvals, so that
stale authority can never be silently inherited.
#### Acceptance criteria
- **AC-PLUGINS-CAPABILITY-APPROVAL-004.1:** When a plugin is uninstalled, the
system shall tombstone the installation identity and deny every later
capability request for it.
- **AC-PLUGINS-CAPABILITY-APPROVAL-004.2:** When a plugin is reinstalled, the
system shall mint a new `installation_id` so no prior approval can attach to
the new installation.
### REQ-PLUGINS-CAPABILITY-APPROVAL-005: Legacy declaration fence
**Intent:** Keep legacy `v1` capability declarations from being granted or
exercised through the H6 approval substrate while preserving their original
runtime behavior.
**User story:** As a maintainer, I want legacy v1 capabilities fenced out of
the approval substrate, so that only explicit `host.v2` capabilities can be
approved and evaluated.
#### Acceptance criteria
- **AC-PLUGINS-CAPABILITY-APPROVAL-005.1:** When a capability id is not an
exact `host.v2` capability, the system shall reject it from approval lists
and deny it at authorization time as unsupported.
- **AC-PLUGINS-CAPABILITY-APPROVAL-005.2:** Legacy `v1` declarations shall
retain their original runtime behavior without gaining H6 approval authority.
### REQ-PLUGINS-CAPABILITY-APPROVAL-006: Generic audit receipts
**Intent:** Give every authorization decision a bounded, deterministic receipt
metadata shape that a future host adapter can persist without carrying
authority.
**User story:** As a host adapter author, I want a typed, bounded receipt on
every decision, so that audit persistence can be added without redefining the
decision contract.
#### Acceptance criteria
- **AC-PLUGINS-CAPABILITY-APPROVAL-006.1:** When the system produces a
decision, the decision shall carry a receipt with bounded installation,
workspace, revision, capability, request and method digests, audit id, and
result values.
- **AC-PLUGINS-CAPABILITY-APPROVAL-006.2:** The receipt digests shall be
deterministic canonical digests of their normalized inputs.
- **AC-PLUGINS-CAPABILITY-APPROVAL-006.3:** When any receipt field would
exceed its bound, the system shall truncate or redact it so the receipt
remains bounded.
## Exclusions
- No approval or review UI (settings pages, coordinator surfaces, or
dashboards) is in scope for this substrate.
- No host adapter persistence of receipts is required; the receipt shape only
defines the metadata contract.
- No changes to legacy `v1` runtime behavior are made beyond fencing it from
approval authority.
- No cross-workspace disclosure surface exists: foreign-workspace requests are
indistinguishable from missing approvals.
@@ -0,0 +1,159 @@
---
status: current
system: plugins
requirements:
- REQ-PLUGINS-CAPABILITY-APPROVAL-001
- REQ-PLUGINS-CAPABILITY-APPROVAL-002
- REQ-PLUGINS-CAPABILITY-APPROVAL-003
- REQ-PLUGINS-CAPABILITY-APPROVAL-004
- REQ-PLUGINS-CAPABILITY-APPROVAL-005
- REQ-PLUGINS-CAPABILITY-APPROVAL-006
created: 2026-09-07
owners:
- kandev
---
# Plugin Capability Approval and Audit System Design
## Purpose and boundaries
This design describes the generic plugin capability-approval substrate in
`apps/backend/internal/plugins`: the host-minted installation identity, the
workspace-scoped approval ledger, the append-only event trail, the
fail-closed authorization decision, uninstall tombstones, the legacy `v1`
fence, and the audit receipt primitives. Higher-level surfaces (approval UI,
coordinator flows, host receipt persistence) consume this substrate without
being part of it.
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `REQ-PLUGINS-CAPABILITY-APPROVAL-001` | [Identity and approval ledger](#identity-and-approval-ledger) |
| `REQ-PLUGINS-CAPABILITY-APPROVAL-002` | [Append-only event trail](#append-only-event-trail) |
| `REQ-PLUGINS-CAPABILITY-APPROVAL-003` | [Fail-closed authorization](#fail-closed-authorization) |
| `REQ-PLUGINS-CAPABILITY-APPROVAL-004` | [Tombstones and reinstall identity](#tombstones-and-reinstall-identity) |
| `REQ-PLUGINS-CAPABILITY-APPROVAL-005` | [Legacy v1 fence](#legacy-v1-fence) |
| `REQ-PLUGINS-CAPABILITY-APPROVAL-006` | [Audit receipts](#audit-receipts) |
## Identity and approval ledger
`store.Record.InstallationID` (`apps/backend/internal/plugins/store/store.go`)
is the host-minted opaque principal for an installed plugin release. It is
minted at install time and persisted with the record; it is never derived from
the plugin id, package digest, workspace, or install path, so a reinstall
necessarily produces a different identity.
`CapabilityApproval` (`apps/backend/internal/plugins/approval_store.go`) is the
current approval row: `(installation_id, workspace_id)` is the ledger key, and
at most one current row exists per pair. A grant replaces the previous
current row for its pair. The row stores the exact `manifest_digest` the
approval was granted against, the canonically sorted and deduplicated
`capability_ids`, the `active`/`revoked` state, the human actor, the immutable
human policy version, and the audit revision. `HumanPolicyVersionImmutable`
records that all current approvals are granted under the one unversioned
human deny policy.
Approval writes are admitted only at the exact next revision. A write naming
any other revision fails with `ErrApprovalRevisionConflict` and leaves stored
state unchanged (`revokeIfRevision` in `approval_store.go`). Reused audit ids
are idempotent only for byte-identical inputs; a different input on the same
audit id fails without changing stored state.
`CanonicalCapabilityList` (`apps/backend/internal/plugins/approval.go`) is the
single canonicalizer for capability lists: trim, bounded length, no NUL,
deduplicate, sort. It rejects human-reserved capabilities and any id that is
not an exact `host.v2` capability. `ManifestCapabilityIDs` derives the exact
`host.v2.read:<resource>` / `host.v2.write:<resource>` capability set from an
installed manifest, and `ManifestCapabilityDigest` derives its canonical
digest. `Service.validateApprovalManifest` rejects a grant whose manifest
digest does not match the installed manifest or that names capabilities the
manifest does not declare: the approval can never be broader than the
manifest.
Ledger state persists as `approvals.json` under the plugins directory through
the `approvalLedger` type (load/migrate semantics in `approval_store.go`).
## Append-only event trail
`CapabilityApprovalEvent` records every approval change after commit:
installation, workspace, before/after revisions and digests, actor, reason, the
`CapabilityApprovalEventType` (`grant`, `narrow`, `revoke`,
`upgrade_review`), and the observed timestamp. Events are appended to the
ledger; grants, narrows, revokes, and upgrade reviews never rewrite or remove
earlier events. The API surface (`apps/backend/internal/plugins/approval_api.go`)
exposes list/get so future audit consumers can replay authority history.
## Fail-closed authorization
`Service.authorizePluginCapability` (`approval_service.go`) is the single
decision path for a capability request. It evaluates in a fixed order and
returns a typed `ApprovalDecision` with a stable `ApprovalDenyReason`:
1. Structural validation (`malformedAuthorizationRequestReason`): bounded
identifiers and digests, NUL-free, and an exact capability form. A
malformed request denies as `malformed_request` (or
`unsupported_capability` for a non-`host.v2` form) before any lookup.
2. Human-reserved capability check denies as `human_reserved`.
3. Ledger lookup. A missing row denies as `missing_capability_approval`; an
unavailable ledger denies as `unavailable_capability`. A foreign workspace
intentionally reuses the missing-approval reason: a more specific
cross-workspace reason would disclose that the installation exists in
another workspace.
4. Revoked state or a non-nil tombstone denies as `capability_revoked`.
5. A requested revision different from the current row denies as
`stale_capability_revision`.
6. Manifest intersection (`manifestIntersectionDenyReason`): the installed
manifest must still declare the capability under the digest the approval
was granted against, otherwise `unavailable_capability`.
7. The capability must appear in the approved list, otherwise
`undeclared_capability`. Otherwise the decision is allowed and carries the
audit identity.
Every denial is side-effect free: no Host operation runs inside the approval
layer. The deny vocabulary is typed (`ApprovalDenyReason` constants in
`approval.go`) so callers can match reasons machine-readably.
## Tombstones and reinstall identity
`Service.approvalTombstoneInstallation` writes a tombstone for an
installation identity at uninstall time. A tombstoned identity denies all
later approvals and requests (`ErrApprovalInstallationTombstoned`,
`capability_revoked`), permanently. Because the reinstall mints a new
`installation_id`, no prior approval can attach to the new installation:
authority cannot be silently inherited across an uninstall/reinstall cycle.
## Legacy v1 fence
`isExactHostV2Capability` gates both grant admission and authorization. A
capability id that is not an exact `host.v2` capability is rejected from
approval lists (`CanonicalCapabilityList`) and denied at authorization time as
`unsupported_capability`. Legacy `v1` manifest declarations keep their original
runtime behavior but cannot be granted or exercised through this substrate.
## Audit receipts
`ApprovalReceipt` (`approval.go`) is the bounded, deterministic metadata a
future host adapter can persist on read or write receipts without carrying
authority: installation, workspace, revision, capability id, request and
method digests, audit id, result, and observed time. `CanonicalApprovalDigest`
builds stable digest identities from trimmed, NUL-joined inputs. Receipt
fields pass through the same safe-bounds helpers as the decision inputs, so a
hostile identifier is truncated or redacted rather than propagated: the
receipt is always bounded and cannot be coerced into authority.
## Persistence and compatibility
The approval ledger file carries approvals, events, tombstones, and idempotency
inputs with forward-compatible JSON decoding (missing maps initialize empty).
Optional fields on `store.Record` (installation id) decode on older records
without migration; a missing installation identity simply has no approvals.
The substrate admits only `HumanPolicyVersionImmutable` today; the stored
per-row policy version is the stable extension point for a future policy
revision.
## Observability
Decisions are pure typed results; the audit id and receipt give future
adapters the exact metadata to persist. Events themselves are the observable
authority history; there is no separate metric emission in this substrate.