cb9752b1a2
Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
147 lines
5.2 KiB
Markdown
147 lines
5.2 KiB
Markdown
---
|
|
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.
|