coulomb/approval-engine
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Retain verified tenant provenance and reconcile production blockers

Browse source 
Assistant: codex
Assistant-Model: gpt-6.1-sol
Assistant-Session: 01a1046e-fdbf-7b93-a267-5f72b9b24526
This commit is contained in:
tegwick 2026-10-04 11:26:32 +02:00
parent 931e0b3249
commit c9ad5c2dd7
12 changed files with 274 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/approver-surface-requirements.md
View file

@ -1,6 +1,12 @@
# Requirements on the approver surface (`informed-decision`)
Status: issued by approval-engine 2026-09-09, against `APPROVAL-WP-0002-T01`.
Status: issued 2026-09-09; current acceptance reviewed 2026-10-04 against
`APPROVAL-WP-0002-T01`. Sections 3 and 4 retain the original questions:
KeyCape has since published approval:read and the assurance shape, registered
`informed-decision-approver`, and Informed Decision has recorded native human
acceptance. Current remaining receipts are in [production-dependencies.md](production-dependencies.md).
Schema-v6 source additionally preserves verified tenant_source; the deployed
schema-v5 image awaits separately approved promotion.
Addressed to `informed-decision` (`INFD-WP-0001`), copied to `key-cape`
(`KEY-WP-0013-T02`).

13
docs/caller-authentication.md
View file

@ -28,9 +28,12 @@ Consequences this engine accepts deliberately:
platform zone" is a fact about the person, and this claim cannot carry it.
No such doctrine exists today; if `gate-house` issues one, it needs a
directory-sourced claim and this check does not become that claim by matching.
- When key-cape emits provenance alongside the tenant, this engine records it on
the approver entry the way schema v4 records `principal_type` — an evidence
reader should not have to infer provenance from a string that cannot carry it.
- Schema v6 records verified `tenant_source` on approver entries and issuance/use
threshold evidence. KeyCape publishes `directory`, `registration`, or `default`.
An absent claim remains null; an explicit malformed or unknown value is refused.
Legacy entries remain null, never inferred from their subject or tenant.
Provenance does not change store isolation or establish zone membership.
The deployed schema-v5 image does not yet record this field.
| Route | Required scope |
|---|---|
@ -44,8 +47,8 @@ Consequences this engine accepts deliberately:
| explicit heartbeat | `approval:emit` |
Create additionally requires `binding.actor == sub`. Approval-entry subject,
assurance, evidence reference, and **principal type** are derived from the
verified JWT, never the request body.
assurance, evidence reference, **principal type**, and **tenant source** derive
from the verified JWT, never the request body.
`principal_type` is recorded from verified identity (since schema v4). Schema v5
implements GH-DEC-2026-016: when an approval declares `human_control: true`,

62
docs/production-dependencies.md Normal file
View file

@ -0,0 +1,62 @@
# Production dependency requirements
Reviewed 2026-10-04 for APPROVAL-WP-0002. Task status `wait` means blocked;
the workplan remains `blocked` after completing reachable source work.
| Task | Owner return required | Evidence that clears the wait |
| --- | --- | --- |
| T01 — authenticated approver evidence | key-cape and informed-decision; founder for release rollout | Exact deployed issuer revision and client/profile receipt for requester and human paths; human sub/type, tenant/source, resource audience, scopes and assurance captured as non-secret facts and correlated with a stored human-control entry. Promote scanned schema-v6 image under per-change approval, back up/migrate once, then verify native entry and issuance/use provenance. No tokens or secrets in receipts. |
| T04 — delivery and reconciliation | audit-core, with railiance-platform for deployed sender/custody acceptance | Accept current cadence.yaml inventory for source approval-engine and tenant tenant:platform, explicit redact policy and four transition heartbeat classes at the requested 172800s bound. Return actual lifecycle event ids/drain acknowledgment and independent accepted counts for the same bounded time window, with pending rows accounted separately. Prove startup beats, missing-class and lag findings (depth 100 / age 3600s), and scoped sender bearer revocation. |
| T05 — live PEP consumption | secrets-engine, with informed-decision for the act-specific human review and access-engine for decision binding | Name the served PEP route/workload, immutable component revision, engine image/endpoint, authenticated caller identities and exact binding. Prove claim-before-decision and CAS consume after ALLOW before protected side effect; same-digest retry, different-digest conflict, spent-on-failure, revoked/expired/superseded/wrong-binding/unavailable denial with no protected callback. Preserve the native approval and decision digests, declared human_control where required, and consumer-owned side-effect/refusal evidence. |
For live whitehat T-06 only, T05's named surface must additionally be covered by
a complete engagement and plane admission naming identities, bounded window
and technique. Neither an in-process client nor this dependency document
admits a test or authorizes a packet. WHITEHAT-WP-0008 remains blocked.
## Delivered prerequisites
- Approval Engine deployment, schema-v5 persistence, restart and restore:
[deployment receipt](evidence/2026-09-14-approval-engine-deployment.json).
Image sha256:251941a5cb2724b57cc32cff6b693b1ab0be695bee4f56f02d51961189c0fa49.
- KeyCape: KEY-WP-0013 publishes `informed-decision-approver`, callback
https://decisions.coulomb.social/auth/callback, scopes openid/approval:read/
approval:approve, S256 PKCE, MFA and tenant:platform. KEY-WP-0031 is finished
and publishes directory/registration/default provenance. A source fragment
is insufficient to pin the exact deployed issuer/profile used by an entry.
- Informed Decision: archived INFD-WP-0001-T08 reports real human acceptance.
Its docs/evidence/2026-09-27-tool-budget-approval-create.json records requester
actor informed-decision and human_control=true; the corresponding
2026-09-27-tool-budget-acceptance.json confirms approval
e9521804-8fce-4fbc-bfdf-8a1aa959fd61, subject
uid=platform-root,ou=people,dc=netkingdom,dc=local at 18:05:35Z.
These discharge the historical absence of a requester/human flow. They do
not prove the new v6 field or admit a different protected action. Standing
requester runtime composition remains INFD-WP-0005-T05's platform dependency.
- Secrets Engine: SECRETS-WP-0010's native reader acceptance records existing
CCR-2026-0019 delivery and separate native read/consume scopes, an engine 404
for an unknown approval and 403 for consume-only read. Credential delivery is
complete; that test explicitly created, bound and consumed no approval.
- Audit Core: AUDIT-WP-0009 is finished. Native producer/readback receipts from
2026-09-11 and engine startup heartbeat drain are delivered. Current class
admission, actual lifecycle reconciliation and observed findings still need
their own receipt; implementation completion is insufficient evidence.
## Approval Engine source completion and release boundary
Schema v6 retains verified tenant provenance without treating registration or
default provenance as directory membership. Entries and issuance/use evidence
carry null for absent provenance; historic rows/events are preserved. Signed
HTTP tests cover all three sources, absent/malformed claims and body spoofing;
on-disk tests cover migration, restart, binding preservation and rollback.
The production pin remains schema v5. Release preparation uses the existing
image-build/image-scan targets and immutable matching migration/server pins.
Production migration/rollout requires founder approval per change, a verified
backup and native readback; this review performs none of those live operations.
The [deployment runbook](../deploy/README.md) and
[storage operations](storage-operations.md) specify that boundary and recovery.
APPROVAL-IN-0001 also remains open for the unassigned shared Taxonomy schema
owner. It does not block this workplan's local claim contract and is not a
substitute for the three owner returns above.

16
docs/storage-operations.md
View file

@ -78,3 +78,19 @@ and verify the existing backup before migration. The old v3 image must not serve
a v5 database; rollback requires the matching pre-migration backup and the
existing single-writer recovery procedure. No live database is migrated by the
source test run.
## Schema v6 — verified tenant provenance
`entries.tenant_source` is nullable TEXT, recording only the verified issuer claim
(`directory`, `registration`, or `default`). Missing claims and pre-v6 entries
stay NULL; migration never infers membership or changes bindings, quorum,
human-control declarations, or existing outbox evidence. New issuance/use
threshold evidence retains this field, including null for unknown provenance.
Migration is additive and must precede serving the v6 release. The deployed
schema-v5 image remains pinned; source changes do not migrate production.
Publish/scan and pin the same v6 artifact for both containers, take and verify
the pre-migration backup, and obtain per-change rollout approval. An old v5
server refuses a v6 store; rollback uses the verified pre-migration backup with
the matching release and the stopped single-writer restore procedure above.