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:
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user