kandev/docs/specs/plugins/system-design/capability-approval.md

---
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.