diff --git a/docs/gate-house-decision-request-claim-envelope.md b/docs/gate-house-decision-request-claim-envelope.md new file mode 100644 index 0000000..6b9f6f9 --- /dev/null +++ b/docs/gate-house-decision-request-claim-envelope.md @@ -0,0 +1,138 @@ +# Decision request to gate-house — the claim envelope on the PEP path + +**Requested by:** approval-engine +**Date:** 2026-09-06 +**Governs:** `GH-DEC-2026-003` (approval consumption ordering) +**Blocks:** first live consume for `SECRETS-WP-0007-T04`; recorded on +`APPROVAL-WP-0002-T05` +**Does not block:** `APPROVAL-WP-0002-T03` (see "Scope" below) + +This is a drafted request, not a decision. gate-house owns the outcome. + +## The question + +secrets-engine's PEP validator (`validate_action_authorization`) expects an +`ActionAuthorization` envelope, but calls +`GET /v1/approvals/{id}/claim`, which serves approval-engine's approval-claim. +The two are different objects. Which one is the step-1 artifact on the governed +PEP path? + +## Why this is a confirmation, not a redesign + +`GH-DEC-2026-003` already names step 1 by endpoint and by field: + +```text +1. PIP GET /v1/approvals/{id}/claim → valid_now (a fact, not permission) +``` + +`valid_now` is an approval-claim field. `ActionAuthorization` has no `valid_now`. + +`ActionAuthorization` is not a governed object. It appears zero times in +gate-house and zero times in state-hub. It originates in flex-auth's +`docs/action-bound-authorization-contract.md` (2026-08-23), whose own status +line calls it *"the **proposed** `ActionAuthorization` storage and transport +object"* — a proposed shape for the durable approval object, which the same +document assigns to approval-engine. It was never ratified, and +`GH-DEC-2026-003` was issued six days later without it. + +One further conflict worth recording: the validator hard-requires +`provenance.authority == "state-hub"`, while flex-auth's own contract states +that State Hub decision records *"are not the runtime approval authority."* +The constant contradicts the document it came from. + +## Requested disposition — confirm the claim (option A) + +Confirm that: + +1. The approval-claim (`approval-engine/docs/approval-claim.md`) is the step-1 + artifact on the `GH-DEC-2026-003` path. +2. `ActionAuthorization` is **not** required on the claim path, and + approval-engine is not expected to serve it there. +3. A PEP validates across the two artifacts it already fetches: the claim for + approval fact (binding digest, validity window, consumption state, + freshness, issuer), and the flex-auth `DecisionEnvelope` from step 2 for + exact `CheckRequest` match and policy package/version pin. + +No safety property is dropped by (3). `ActionAuthorization` is a *bundle* of +approval fact plus decision envelope; splitting validation returns each check +to the layer that owns the data, rather than having the PIP republish the PDP's +decision. + +### What changes if approved + +| Repo | Change | +| --- | --- | +| approval-engine | none — the claim schema stands as published | +| secrets-engine | split `validate_action_authorization` into a claim check and a decision check; drop the `authority == "state-hub"` requirement | +| flex-auth | acknowledge the proposed `ActionAuthorization` is shelved on this path (see "Deferred option" — it is not withdrawn) | +| gate-house | record the confirmation against `GH-DEC-2026-003` | + +## Deferred option D — a ratified post-decision `ActionAuthorization` + +Recorded so it is not rediscovered. **Not** requested now. + +A single composed post-decision artifact — canonical UUID, lifecycle status, +one complete `CheckRequest`, bounded validity, approval evidence, and the +matching `DecisionEnvelope` — remains a coherent design. flex-auth's schema and +its secrets-engine profile already exist as a starting point. + +**Why not now:** it needs a named issuer and lifecycle owner (nobody holds +that today), and `GH-DEC-2026-003` already settles the sequence without it. The +cost is months; the present problem is resolved by a confirmation. + +**Revisit if any of these appear:** + +- a third or fourth PEP-shaped consumer, where per-consumer two-artifact + validation starts duplicating logic worth centralizing; +- a requirement for a single signed, forwardable authorization artifact + (offline verification, or an audit that must replay one object rather than a + join); +- resolution of flex-auth's open G3 finding — `DecisionEnvelope` carries no + lifetime — if that is settled by composition rather than by adding a lifetime + field to the envelope; +- assent of the statute §17 Taxonomy request-claim schema (`APPROVAL-IN-0001`), + which the approval-claim already declares it yields to. If Taxonomy lands + first, converge there and **do not** revive this separately. + +**Constraint on any future adoption:** such an object is post-decision by +construction. It cannot be served from the step-1 claim call, because a step-1 +response cannot contain a step-2 decision. It would be a new artifact at a new +endpoint, not a change to the claim. + +## Also considered and rejected + +- **approval-engine serves `ActionAuthorization` at the claim endpoint.** + Structurally impossible for step 1, per the constraint above, and it would + require asserting a `state-hub` authority that this engine does not hold. +- **Additively extend the claim** with `approvals.required_count` / `entries`. + Publishing approver identities to consumers is a deliberate least-disclosure + non-goal, and it still would not satisfy `id`, `authority`, or `request`, so + the consumer's validator changes regardless. + +## Scope + +This does not gate `APPROVAL-WP-0002-T03`. secrets-engine is fail-closed until +T03 and its own T04 both land; deploying publishes a URL and commits no one to +an envelope. The question gates the first live consume, not the deployment. + +## Proposed record + +```yaml +kind: decision +title: The approval-claim is the step-1 artifact on the PEP consumption path +status: proposed +owner: Bernd Worsch +repo: gate-house +standard: net-kingdom/canon/standards/security-layer-model_v0.7.md +source_note: docs/contracts/approval-consumption.md +requested_dispositions: +- approved +- revised +- rejected +affects: +- gate-house +- approval-engine +- flex-auth +- secrets-engine +- ops-warden +``` diff --git a/intakes/intakes.md b/intakes/intakes.md index c94d959..2c067a1 100644 --- a/intakes/intakes.md +++ b/intakes/intakes.md @@ -25,3 +25,34 @@ description: >- assigned; preserve mechanical replay and freshness semantics during adoption. state_hub_intake_id: "01a05ef0-a034-7ef8-bae1-45840392f40e" ``` + +## APPROVAL-IN-0002 — Confirm the claim envelope on the PEP consumption path + +```yaml +id: APPROVAL-IN-0002 +kind: intake +title: Confirm the claim envelope on the PEP consumption path +status: open +origin: coordination +origin_ref: APPROVAL-WP-0002-T05 +priority: high +owner: gate-house +repo: approval-engine +lane: blue +tags: +- decision-request +- cross-repo +created: '2026-09-06' +updated: '2026-09-06' +description: >- + secrets-engine's PEP validator expects a flex-auth ActionAuthorization but + calls GET /v1/approvals/{id}/claim, which serves approval-engine's governed + approval-claim. GH-DEC-2026-003 already names the claim as the step-1 + artifact, and ActionAuthorization is an unratified flex-auth proposal absent + from gate-house and state-hub. Requests gate-house confirm the claim is the + step-1 artifact and that ActionAuthorization is not required on that path; + a ratified post-decision ActionAuthorization is recorded as a deferred + option with revisit triggers. Full request in + docs/gate-house-decision-request-claim-envelope.md. Does not gate + APPROVAL-WP-0002-T03. +```