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