coulomb/flex-auth
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Publish approval_binding_digest: a claim cannot name the request carrying it
Some checks are pending
CI Smoke / host-smoke (push) Waiting to run
Details
CI Smoke / container-smoke (push) Waiting to run
Details
Build and Publish Container Image / build-and-push (push) Successful in 52s
Details

Browse source 
secrets-engine confirmed T03, and re-verifying against the regenerated
destroy fixture found something neither repository can fix alone: a
pdp_digest recorded at issue time can never equal the request_digest of a
request that carries the claim in its context, because the claim is part
of the context that is hashed. Embedding the claim changes the very
digest the claim would need to name.

Not fixture staleness. It holds for every dual-control request whose
claim travels in context -- the shape GH-DEC-2026-008 had just ruled
mandatory. Left unresolved that ruling was unimplementable for exactly
the case it was written for, and destroy would have been permanently
un-allowable in production, failing closed forever on a check that could
never pass.

flex-auth owns the canonical request digest, so the fix is ours.
binding.approval_binding_digest is the same material with
context.approval removed, emitted only when a claim was carried. An
approval issued against a claim-free Check records that Check's
request_digest; the claim-bearing request reproduces it here.

DELIBERATELY ADDITIVE, and the reason matters. The tempting fix is to
drop context.approval from request_digest entirely. That is wrong:
request_digest is the replay identity, and two requests differing only in
which approval was presented must not share one, because their decisions
differ -- one allows, the other denies dual_control_required. Collapsing
them would let an allow obtained with a valid claim be replayed against a
request carrying none. So request_digest still covers the claim and still
moves; approval_binding_digest deliberately does not, and is documented
as not a replay identity. The tests assert the two functions DISAGREE on
a claim-bearing request, which is approval-engine's formulation of how to
defend a distinction that looks like duplication.

The fixture now demonstrates the property rather than asserting it: its
claim's pdp_digest equals the envelope's approval_binding_digest with
pdp_path true, and changing the claim's contents moved request_digest
while leaving approval_binding_digest untouched. Two files a consumer can
diff.

Also picked up approval-engine's new required binding.pdp_path via the
cross-repo schema test added yesterday -- which is the test doing exactly
what it was built for, one day later.

T03 is done. secrets-engine's own digest-material defect, which our two
real envelopes caught, is recorded in the workplan.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JTbVXpEiXA7mNJVpDnEPcB

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 412054@bnt-lap001
Assistant-Session: 3968fae1-8d59-4209-9bd6-c22594b8ab19
This commit is contained in:
tegwick 2026-09-06 14:52:33 +02:00
parent 9f3e7e363a
commit dd3ce4c109
13 changed files with 631 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

58
.repo-manager/index.json
View file

@ -2,9 +2,9 @@
"schema": "repo_manager.index.v1",
"slug": "flex-auth",
"repo_root": "/home/worsch/flex-auth",
"head_sha": "d144feb2e9b74df39a085ce752335c1169ffac9a",
"observed_at": "2026-09-05T23:29:23.679186Z",
"source_fingerprint": "8708283bc20e40a97e9193fcf6de5b81cb3174f0cac5af6665ecc62d6c716c7e",
"head_sha": "9f3e7e363a11f611e13d4d798dba575c56168521",
"observed_at": "2026-09-06T12:52:08.174834Z",
"source_fingerprint": "a19f5aa8b0f293bbd5d768adaa50c8afff5c0f0be3757e1b7af62ac791ab228f",
"source_files": [
".repo-classification.yaml",
"INTENT.md",
@ -1220,7 +1220,7 @@
{
"kind": "workplan",
"id": "FLEX-WP-0021",
"status": "proposed",
"status": "active",
"title": "secrets-engine consumer policy package and cluster-local pin",
"source_path": "workplans/FLEX-WP-0021-secrets-engine-consumer-policy-gate.md",
"uuid": "b01f655e-f71a-50ae-b110-178557f07c63",
@ -1230,7 +1230,7 @@
{
"kind": "task",
"id": "FLEX-WP-0021-T01",
"status": "todo",
"status": "done",
"title": "1. Obtain the real action vocabulary from secrets-engine",
"source_path": "workplans/FLEX-WP-0021-secrets-engine-consumer-policy-gate.md",
"uuid": "3c191808-6fe5-5a9b-9a68-a4ce4a672dbd",
@ -1240,7 +1240,7 @@
{
"kind": "task",
"id": "FLEX-WP-0021-T02",
"status": "todo",
"status": "done",
"title": "2. Publish `secrets-engine.catalog-lane.lifecycle` v1",
"source_path": "workplans/FLEX-WP-0021-secrets-engine-consumer-policy-gate.md",
"uuid": "38770813-dfcc-5711-bba3-0db50d3af135",
@ -1250,7 +1250,7 @@
{
"kind": "task",
"id": "FLEX-WP-0021-T03",
"status": "todo",
"status": "progress",
"title": "3. Confirm the digest join against a real decision record",
"source_path": "workplans/FLEX-WP-0021-secrets-engine-consumer-policy-gate.md",
"uuid": "8f7e5cdd-777e-5f54-9b92-c72b79f65672",
@ -1473,7 +1473,7 @@
"status": "resolved",
"title": "ActionAuthorization deferral accepted; G3 is closed and does not argue for ratifying it",
"source_path": "decisions/decisions.md",
"uuid": null,
"uuid": "762e5d75-2377-4e1a-bcea-c57398ef636b",
"parent_id": null,
"extra": {
"record": {
@ -1497,7 +1497,41 @@
"decided_by": "flex-auth (access-engine / PDP)",
"rationale": "Accepted, and flex-auth argues against its own proposal. The composed ActionAuthorization object was never ratified; the approval-claim plus DecisionEnvelope split lands each check on the layer that owns it and drops none. approval-engine asked whether the open G3 finding (DecisionEnvelope carries no lifetime) argues for ratifying the composed object now. It does not, because G3 is already closed the other way: FLEX-WP-0019 added lifetime to the DecisionEnvelope itself, required on every allow by schema conditional, published 2026-09-02. The revisit trigger is spent, and it resolved by adding a field rather than by composition, so the decision now stands alone and needs no bundle. Separately, the provenance.authority == state-hub constant is flex-auth defect: it came from examples/caring/action_authorization.json, which contradicted our own ownership section. Corrected at source, with the schema and contract doc marked deferred-not-withdrawn so no other consumer builds a validator against them.",
"created": "2026-09-05T23:29:20.156770Z",
"updated": "2026-09-05T23:29:20.156770Z"
"updated": "2026-09-05T23:29:20.156770Z",
"state_hub_decision_id": "762e5d75-2377-4e1a-bcea-c57398ef636b"
}
}
},
{
"kind": "decision",
"id": "FLEX-DEC-2026-007",
"status": "resolved",
"title": "A claim cannot name the request that carries it: publish approval_binding_digest",
"source_path": "decisions/decisions.md",
"uuid": null,
"parent_id": null,
"extra": {
"record": {
"id": "FLEX-DEC-2026-007",
"kind": "decision",
"title": "A claim cannot name the request that carries it: publish approval_binding_digest",
"status": "resolved",
"origin": "cross-repo",
"origin_ref": "secrets-engine T03 re-verification / GH-DEC-2026-008",
"owner": "flex-auth",
"affects": [
"flex-auth",
"secrets-engine",
"approval-engine",
"gate-house"
],
"requested_dispositions": [
"resolve"
],
"decided_by": "flex-auth (access-engine / PDP)",
"rationale": "secrets-engine found that an approval pdp_digest recorded at issue time can never equal the request_digest of a request that carries the claim inside its hashed context, because the claim is part of the context that is hashed. The circularity is structural, not a fixture defect, and it made GH-DEC-2026-008 unimplementable for exactly the dual-control case it was written for. flex-auth owns the canonical request digest, so the resolution is ours. Publishing binding.approval_binding_digest: the same digest computed with context.approval removed, present only when a claim was carried, stable across attaching the claim, and therefore nameable by a pdp_digest recorded at issue. Deliberately additive rather than a redefinition: request_digest keeps covering the claim and remains the replay identity, because two requests differing only in which approval was presented must not share a replay identity when one allows and the other denies dual_control_required. Tests assert the two functions disagree on a claim-bearing request and agree on a claim-free one.",
"created": "2026-09-06T12:52:06.960329Z",
"updated": "2026-09-06T12:52:06.960329Z"
}
}
},
@ -1578,15 +1612,15 @@
"type": "repo.command.applied",
"command": "repo.work.create_decision",
"operation": "create",
"correlation_id": "ead04d14-441f-4ecd-8ee8-12ae0cd23362",
"correlation_id": "e76636be-b773-46de-9bef-eb962c96cf2b",
"kind": "decision",
"id": "FLEX-DEC-2026-006",
"id": "FLEX-DEC-2026-007",
"git_sha": null,
"files_touched": [
"decisions/decisions.md"
],
"source": "repo-manager",
"emitted_at": "2026-09-05T23:29:23.679390Z"
"emitted_at": "2026-09-06T12:52:08.174961Z"
}
]
}

127
decisions/decisions.md
View file

@ -879,3 +879,130 @@ reserved-but-unpublished coordinate from `FLEX-DEC-2026-005`.
- No revisit trigger remains open on flex-auth's side. If the composed object is
ever revisited, it needs a fresh argument, not G3.
## FLEX-DEC-2026-007 — A claim cannot name the request that carries it: publish approval_binding_digest
```yaml
id: FLEX-DEC-2026-007
kind: decision
title: 'A claim cannot name the request that carries it: publish approval_binding_digest'
status: resolved
origin: cross-repo
origin_ref: secrets-engine T03 re-verification / GH-DEC-2026-008
owner: flex-auth
affects:
- flex-auth
- secrets-engine
- approval-engine
- gate-house
requested_dispositions:
- resolve
decided_by: flex-auth (access-engine / PDP)
rationale: 'secrets-engine found that an approval pdp_digest recorded at issue time
can never equal the request_digest of a request that carries the claim inside its
hashed context, because the claim is part of the context that is hashed. The circularity
is structural, not a fixture defect, and it made GH-DEC-2026-008 unimplementable
for exactly the dual-control case it was written for. flex-auth owns the canonical
request digest, so the resolution is ours. Publishing binding.approval_binding_digest:
the same digest computed with context.approval removed, present only when a claim
was carried, stable across attaching the claim, and therefore nameable by a pdp_digest
recorded at issue. Deliberately additive rather than a redefinition: request_digest
keeps covering the claim and remains the replay identity, because two requests differing
only in which approval was presented must not share a replay identity when one allows
and the other denies dual_control_required. Tests assert the two functions disagree
on a claim-bearing request and agree on a claim-free one.'
created: '2026-09-06T12:52:06.960329Z'
updated: '2026-09-06T12:52:06.960329Z'
```
## Context
`secrets-engine` confirmed `FLEX-WP-0021-T03` — both replay envelopes reproduce
— and in doing so found a defect in their own digest join: they were hashing
`id`, `policy_version`, and `caring_context`, which
[`canonical-request-digest.md`](../docs/canonical-request-digest.md) excludes.
Their previously pinned constant had been computed with `id` inside the
material, so it was wrong and its passing proved nothing. Two real envelopes
caught it.
Re-verifying against the regenerated `destroy` fixture, they then found
something neither repository can fix alone.
## The finding
> A `pdp_digest` recorded at issue time cannot equal the `request_digest` of a
> request that carries the claim in its context.
Completing `context.approval` to a full approval-claim is what moved the
`destroy` fixture's digest — because context is part of the digest material.
That is correct behaviour, and it is circular: embedding the claim changes the
very digest the claim would need to name.
It is not fixture staleness. It holds for every dual-control request whose claim
travels in context, which is the shape `GH-DEC-2026-008` had just ruled
mandatory: `claim.binding.pdp_digest` must equal the decision's request digest,
and a claim without one must not be used on the PDP path. Left unresolved, the
ruling would have been unimplementable for exactly the case it was written for —
and `destroy` would have been permanently un-allowable in production, failing
closed forever on a check that could never pass.
## Disposition
**flex-auth resolves it, because flex-auth owns the digest.** `secrets-engine`
raised it correctly and could not fix it; `approval-engine` records the value but
does not define it; gate-house ruled on the correspondence but the mechanism is
the PDP's.
`binding.approval_binding_digest` is published: the same canonical material with
`context.approval` removed, emitted only when the request carried a claim.
```text
claim.binding.pdp_digest == decision.binding.approval_binding_digest
```
An approval issued against a claim-free Check records that Check's
`request_digest`; the later claim-bearing request reproduces the same value in
`approval_binding_digest`. The circularity is broken because the excluded key is
exactly the one whose contents would otherwise perturb it.
### Why this is a second digest and not a redefinition
The tempting fix is to drop `context.approval` from `request_digest` entirely.
That is wrong, and the reason is worth recording because it is not obvious.
`request_digest` is the §6.4.2 replay identity. Two requests differing only in
which approval was presented **must not share one**, because their decisions
differ: one allows, the other denies `dual_control_required`. Collapsing the two
digests would let an allow obtained with a valid claim be replayed against a
request carrying none. The decision is not a function of the approval-excluded
material, so the approval-excluded material cannot be the replay identity.
So `request_digest` still covers the claim and still moves when it changes.
`approval_binding_digest` deliberately does not move, and is documented as **not
a replay identity**. `pkg/api/approval_binding_test.go` asserts the two
functions *disagree* on a claim-bearing request — a test that a distinction is
real is how a distinction that looks like duplication is defended, which is
`approval-engine`'s formulation and it applies here.
### The fixture demonstrates it rather than asserting it
`examples/secrets-engine/replay/decision_destroy_dual_control.json` now carries a
claim whose `pdp_digest` equals the envelope's `approval_binding_digest`, with
`pdp_path: true`. Changing the claim's contents moved `request_digest` and left
`approval_binding_digest` untouched, which is the whole property, visible in two
files a consumer can diff.
## Consequences
- Additive to `flex-auth.decision-record.v1`. No existing digest changed
meaning, and no consumer that never sends `context.approval` sees the field
at all — `approval_binding_digest` is omitted rather than duplicated onto
every ordinary decision.
- `secrets-engine` must compare `pdp_digest` to `approval_binding_digest`, never
to `request_digest`. Their fixture pins move because the fixture's claim
changed; the property does not.
- `approval-engine` needs no change. The value they record at issue is already
the right one.
- The three shapes `secrets-engine` offered are answered by the first: the
digest an approval names is computed without `context.approval`, and it is now
stated in the contract rather than left to be discovered.

46
docs/canonical-request-digest.md
View file

@ -96,3 +96,49 @@ Any of the following refuses replay:
Local fixtures, State Hub `/decisions/{uuid}` records, and free-form
`decided_by` values are not this test.
## The approval-binding digest
`binding.approval_binding_digest` is this same digest computed with an approval
claim removed from `context`. It appears only when the request carried one on
`context.approval`.
### Why a second digest exists
An approval's `pdp_digest` is recorded **at issue time**. The request that later
carries that claim inside its hashed context has a different `request_digest` by
construction, because the claim is part of the context that is hashed. So:
> A `pdp_digest` recorded at issue time can never equal the `request_digest` of
> the request that carries the claim.
`secrets-engine` found this while verifying a replay fixture, and it is not a
fixture defect — it is circular by construction. Left unresolved it would make
`GH-DEC-2026-008` unimplementable for exactly the case it was written for: a
dual-control action whose claim travels in context.
`approval_binding_digest` is stable across attaching the claim. An approval
issued against a claim-free Check records that Check's `request_digest`, and the
later claim-bearing request reproduces the same value here.
### The comparison
```text
claim.binding.pdp_digest == decision.binding.approval_binding_digest
```
Never against `request_digest`. Comparing to `request_digest` cannot succeed on a
claim-bearing request.
### It is not a replay identity
`request_digest` remains the §6.4.2 replay test and still covers the approval
claim. `approval_binding_digest` deliberately does not: two requests differing
only in which approval was presented share it, **and their decisions do not** —
one allows, the other denies `dual_control_required`.
Collapsing the two would let an allow obtained with a valid claim be replayed
against a request carrying none. That is why this is an additional field rather
than a redefinition of the existing one, and why `pkg/api/approval_binding_test.go`
asserts the two functions **disagree** on a claim-bearing request. A test that a
distinction is real is how a distinction that looks like duplication is defended.

1
docs/decision-record-contract.md
View file

@ -29,6 +29,7 @@ same shape.
| --- | --- |
| `contract_version` | `flex-auth.decision-record.v1` |
| `binding` | Structured subject, action, resource, context, and `request_digest` |
| `binding.approval_binding_digest` | Present only when the request carried `context.approval`. The digest an approval's `pdp_digest` must equal — see [`canonical-request-digest.md`](canonical-request-digest.md). Not a replay identity |
| `lifetime` | **Required on every allow.** A TTL with `not_before` and `expires_at` |
| `provenance.policy_package` / `policy_version` | Named package pin |
| `provenance.policy_package_digest` | SHA-256 of package metadata plus compiled Rego |

3
examples/secrets-engine/check_request_allow_destroy_dual_control.json
View file

@ -36,7 +36,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",

21
examples/secrets-engine/policy_fixtures.yaml
View file

@ -355,7 +355,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",
@ -443,7 +444,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",
@ -503,7 +505,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",
@ -563,7 +566,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",
@ -623,7 +627,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",
@ -683,7 +688,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",
@ -743,7 +749,8 @@
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",

3
examples/secrets-engine/policy_package.md
View file

@ -347,7 +347,8 @@ valid_claim := {
"principal": "bernd",
"purpose": "rotate-exposed-key",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56"
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true
},
"freshness": {
"observed_at": "2026-09-06T12:00:00+00:00",

21
examples/secrets-engine/replay/README.md
View file

@ -23,13 +23,30 @@ go run ./cmd/flex-auth check \
| Field | `rotate` | `destroy` |
| --- | --- | --- |
| `binding.request_digest` | `sha256:de67324f…4345` | `sha256:fc155db…bdf3` |
| `binding.request_digest` | `sha256:de67324f…4345` | `sha256:c749ee2…091a` |
| `provenance.policy_package_digest` | `sha256:fe0070b7…bd8c` | same |
| `provenance.registry_snapshot_digest` | `sha256:f5a309bc…40bb` | same |
| `provenance.input_claim_digests.context` | absent (empty context) | `sha256:b0d2203…c221` |
| `provenance.input_claim_digests.context` | absent (empty context) | `sha256:8b73d29…2800` |
Verified identical across two runs.
| `binding.approval_binding_digest` | absent (no claim) | `sha256:fa07bec…cd56` |
That last row is the value an approval's `pdp_digest` must equal — never
`request_digest`, which a claim can never match on the request that carries it.
It equals the `request_digest` of the same request with `context.approval`
removed, which is verifiable from this directory: strip the context from
`../check_request_allow_destroy_dual_control.json`, re-run `check`, and the
claim-free request digest is the same value (it denies `dual_control_required`,
which is the point).
**This fixture verifies itself.** The claim inside the request carries
`binding.pdp_digest` equal to the envelope's `approval_binding_digest`, and
`binding.pdp_path: true`. Compare the two values in the two files. Note that
`request_digest` moved when the claim's contents changed while
`approval_binding_digest` did not — that is the stability property, demonstrated
in the artifact rather than asserted in prose.
**Not stable:** `id`, `provenance.decision_time`, and `lifetime.not_before` /
`lifetime.expires_at` move with the clock. `lifetime.ttl` is `15m` from the
package's `allow_ttl`. Do not pin the record as a whole.

16
examples/secrets-engine/replay/decision_destroy_dual_control.json
View file

@ -1,5 +1,5 @@
{
"id": "decision:395efe37c5066e8a",
"id": "decision:44a40c339a020772",
"contract_version": "flex-auth.decision-record.v1",
"request_id": "check:secrets-engine-destroy",
"effect": "allow",
@ -72,7 +72,8 @@
"action": "secrets.kv.destroy",
"actor": "agt-secrets-engine",
"digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
"pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56",
"pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
"pdp_path": true,
"principal": "bernd",
"purpose": "rotate-exposed-key",
"target": {
@ -98,13 +99,14 @@
}
}
},
"request_digest": "sha256:fc155dba88f8ab18b3032ed086ba2f455158c6981106e7829d520ab7b036bdf3"
"request_digest": "sha256:c749ee2dc3cdf927a70a3e5b27cff4d97a438d3264153b4b2e3bcacbaf82091a",
"approval_binding_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56"
},
"lifetime": {
"kind": "ttl",
"ttl": "15m",
"not_before": "2026-09-06T12:18:21Z",
"expires_at": "2026-09-06T12:33:21Z"
"not_before": "2026-09-06T12:51:16Z",
"expires_at": "2026-09-06T13:06:16Z"
},
"diagnostics": {
"action": "destroy",
@ -122,9 +124,9 @@
"policy_package_digest": "sha256:fe0070b79f66442ae6c218697a49c470c6c8f670aa57a30c078a5284d097bd8c",
"registry_snapshot_digest": "sha256:f5a309bc0b36721fd6d9ad7f53eb21222162bc2eac62a0ab0802a9a1d51340bb",
"input_claim_digests": {
"context": "sha256:b0d2203cd2b43a9ba573c21c038154c131afba4255e313affd7ecf810e2cc221"
"context": "sha256:8b73d29ecef286d42e03d2420531d6c45219f325a7ae004c1ecfc781203a2800"
},
"decision_time": "2026-09-06T12:18:21Z"
"decision_time": "2026-09-06T12:51:16Z"
},
"caring": {
"profile": "caring-0.4.0-rc2",

86
pkg/api/approval_binding_test.go Normal file
View file

@ -0,0 +1,86 @@
package api
import "testing"
func claimBearing() CheckRequest {
return CheckRequest{
Tenant: "tenant:platform",
Subject: SubjectRef{ID: "secrets-engine", Type: "service"},
Action: "destroy",
Resource: ResourceRef{ID: "lane:glas-primary", Type: "secret-catalog-lane", System: "secrets-engine"},
Context: map[string]any{
"approval": map[string]any{"kind": "approval-claim", "valid_now": true},
},
}
}
func claimFree() CheckRequest {
r := claimBearing()
r.Context = nil
return r
}
// TestApprovalBindingDigestSurvivesAttachingTheClaim is the property the whole
// field exists for. An approval's pdp_digest is recorded at issue time against a
// claim-free Check; the request that later carries the claim must still be able
// to name it.
func TestApprovalBindingDigestSurvivesAttachingTheClaim(t *testing.T) {
atIssue := RequestDigest(claimFree())
atExecute := ApprovalBindingDigest(claimBearing())
if atIssue != atExecute {
t.Fatalf("approval binding digest moved when the claim was attached:\n issue: %s\n execute: %s", atIssue, atExecute)
}
}
// TestRequestDigestStillMovesWhenTheClaimIsAttached guards the reason this is a
// second digest rather than a redefinition of the first. request_digest remains
// the full replay identity: attaching a claim changes the request, so it must
// change the digest. Collapsing the two would let an allow obtained with a valid
// claim be replayed against a request carrying none.
func TestRequestDigestStillMovesWhenTheClaimIsAttached(t *testing.T) {
if RequestDigest(claimFree()) == RequestDigest(claimBearing()) {
t.Fatal("request_digest ignored context.approval — replay identity must cover the claim")
}
}
// TestTheTwoDigestsDisagreeOnAClaimBearingRequest asserts the distinction is
// real rather than decorative. A test that the two functions disagree is how a
// distinction that looks like duplication is defended.
func TestTheTwoDigestsDisagreeOnAClaimBearingRequest(t *testing.T) {
req := claimBearing()
if RequestDigest(req) == ApprovalBindingDigest(req) {
t.Fatal("the two digests agree on a claim-bearing request; one of them is not doing its job")
}
}
// TestApprovalBindingDigestEqualsRequestDigestWithoutAClaim keeps the field
// honest for every consumer that never sends one.
func TestApprovalBindingDigestEqualsRequestDigestWithoutAClaim(t *testing.T) {
req := claimFree()
if RequestDigest(req) != ApprovalBindingDigest(req) {
t.Fatal("digests differ on a claim-free request; they must be the same value")
}
}
// TestBindingOmitsApprovalDigestWhenNoClaimIsPresent avoids publishing a field
// that would read as a second identity on every ordinary decision.
func TestBindingOmitsApprovalDigestWhenNoClaimIsPresent(t *testing.T) {
if got := NewDecisionBinding(claimFree()).ApprovalBindingDigest; got != "" {
t.Fatalf("expected no approval_binding_digest on a claim-free request, got %q", got)
}
if got := NewDecisionBinding(claimBearing()).ApprovalBindingDigest; got == "" {
t.Fatal("expected approval_binding_digest on a claim-bearing request")
}
}
// TestOtherContextClaimsStillBindUnderTheApprovalDigest confirms the exclusion is
// surgical: only the approval key leaves the material.
func TestOtherContextClaimsStillBindUnderTheApprovalDigest(t *testing.T) {
a := claimBearing()
a.Context["purpose"] = "rotate-exposed-key"
b := claimBearing()
b.Context["purpose"] = "something-else"
if ApprovalBindingDigest(a) == ApprovalBindingDigest(b) {
t.Fatal("approval binding digest ignored a non-approval context claim")
}
}

55
pkg/api/canonical.go
View file

@ -264,8 +264,25 @@ type DecisionBinding struct {
Resource ResourceRef `json:"resource" yaml:"resource"`
Context map[string]any `json:"context,omitempty" yaml:"context,omitempty"`
RequestDigest string `json:"request_digest" yaml:"request_digest"`
// ApprovalBindingDigest is RequestDigest computed with the approval claim
// removed from context. It exists to break a circularity: an approval's
// pdp_digest is recorded at issue time, but the request that later carries
// the claim inside its hashed context has a different RequestDigest by
// construction, so a claim can never name the request that carries it.
//
// This digest is stable across attaching the claim, so it is the value
// claim.binding.pdp_digest must equal (GH-DEC-2026-008). It is NOT a replay
// identity and must not be used as one: two requests differing only in
// which approval was presented share it, and the decision does not.
ApprovalBindingDigest string `json:"approval_binding_digest,omitempty" yaml:"approval_binding_digest,omitempty"`
}
// ApprovalContextKey is the context key carrying an approval-engine
// approval-claim. It is excluded from ApprovalBindingDigest and from nothing
// else.
const ApprovalContextKey = "approval"
// requestDigestMaterial is the exact tuple hashed for §6.4.2 replay. Request
// id, policy version, and caring_context are excluded: id is correlation, the
// version is provenance, and caring_context is an input-claim digest.
@ -284,7 +301,7 @@ func NewDecisionBinding(request CheckRequest) *DecisionBinding {
for key, value := range request.Context {
contextCopy[key] = value
}
return &DecisionBinding{
binding := &DecisionBinding{
Tenant: request.Tenant,
Subject: request.Subject,
Action: request.Action,
@ -292,6 +309,42 @@ func NewDecisionBinding(request CheckRequest) *DecisionBinding {
Context: contextCopy,
RequestDigest: RequestDigest(request),
}
if _, carries := request.Context[ApprovalContextKey]; carries {
binding.ApprovalBindingDigest = ApprovalBindingDigest(request)
}
return binding
}
// ApprovalBindingDigest is RequestDigest over the same material with the
// approval claim removed from context.
//
// When a request carries no approval claim the two are identical, which is the
// point: an approval issued against a claim-free Check records that Check's
// request_digest, and the later claim-bearing request reproduces the same value
// here. Comparing it to claim.binding.pdp_digest establishes correspondence by
// identity rather than by translating between two action vocabularies
// (GH-DEC-2026-008).
func ApprovalBindingDigest(request CheckRequest) string {
if _, carries := request.Context[ApprovalContextKey]; !carries {
return RequestDigest(request)
}
stripped := make(map[string]any, len(request.Context))
for key, value := range request.Context {
if key == ApprovalContextKey {
continue
}
stripped[key] = value
}
if len(stripped) == 0 {
stripped = nil
}
return CanonicalDigest(requestDigestMaterial{
Tenant: request.Tenant,
Subject: request.Subject,
Action: request.Action,
Resource: request.Resource,
Context: stripped,
})
}
// RequestDigest is the mechanical §6.4.2 replay test: SHA-256 over canonical

263
schemas/decision_envelope.schema.json
View file

@ -2,112 +2,271 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://flex-auth.netkingdom/schemas/decision_envelope.schema.json",
"title": "DecisionEnvelope",
"description": "Published flex-auth decision-record contract (flex-auth.decision-record.v1). This is the PDP's output artifact under security-layer-model_v0.7 §17.",
"description": "Published flex-auth decision-record contract (flex-auth.decision-record.v1). This is the PDP's output artifact under security-layer-model_v0.7 \u00a717.",
"type": "object",
"additionalProperties": false,
"required": ["id", "effect", "resource", "subject", "provenance"],
"required": [
"id",
"effect",
"resource",
"subject",
"provenance"
],
"properties": {
"id": {"type": "string", "minLength": 1},
"contract_version": {"const": "flex-auth.decision-record.v1"},
"request_id": {"type": "string", "minLength": 1},
"effect": {"enum": ["allow", "deny", "redact", "audit_only", "not_applicable"]},
"reason": {"type": "string"},
"matched_policy_version": {"type": "string", "minLength": 1},
"matched_rule": {"type": "string", "minLength": 1},
"resource": {"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/resource_ref"},
"subject": {"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/subject_ref"},
"binding": {"$ref": "#/$defs/decision_binding"},
"lifetime": {"$ref": "#/$defs/lifetime"},
"obligations": {"type": "array", "items": {"$ref": "#/$defs/obligation"}},
"diagnostics": {"type": "object", "additionalProperties": true},
"provenance": {"$ref": "#/$defs/provenance"},
"caring": {"$ref": "#/$defs/caring_decision_metadata"}
"id": {
"type": "string",
"minLength": 1
},
"contract_version": {
"const": "flex-auth.decision-record.v1"
},
"request_id": {
"type": "string",
"minLength": 1
},
"effect": {
"enum": [
"allow",
"deny",
"redact",
"audit_only",
"not_applicable"
]
},
"reason": {
"type": "string"
},
"matched_policy_version": {
"type": "string",
"minLength": 1
},
"matched_rule": {
"type": "string",
"minLength": 1
},
"resource": {
"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/resource_ref"
},
"subject": {
"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/subject_ref"
},
"binding": {
"$ref": "#/$defs/decision_binding"
},
"lifetime": {
"$ref": "#/$defs/lifetime"
},
"obligations": {
"type": "array",
"items": {
"$ref": "#/$defs/obligation"
}
},
"diagnostics": {
"type": "object",
"additionalProperties": true
},
"provenance": {
"$ref": "#/$defs/provenance"
},
"caring": {
"$ref": "#/$defs/caring_decision_metadata"
}
},
"allOf": [
{
"if": {"properties": {"effect": {"const": "allow"}}, "required": ["effect"]},
"then": {"required": ["lifetime"]}
"if": {
"properties": {
"effect": {
"const": "allow"
}
},
"required": [
"effect"
]
},
"then": {
"required": [
"lifetime"
]
}
}
],
"$defs": {
"decision_binding": {
"type": "object",
"additionalProperties": false,
"required": ["subject", "action", "resource", "request_digest"],
"required": [
"subject",
"action",
"resource",
"request_digest"
],
"properties": {
"tenant": {"type": "string", "minLength": 1},
"subject": {"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/subject_ref"},
"action": {"type": "string", "minLength": 1},
"resource": {"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/resource_ref"},
"context": {"type": "object", "additionalProperties": true},
"request_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
"tenant": {
"type": "string",
"minLength": 1
},
"subject": {
"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/subject_ref"
},
"action": {
"type": "string",
"minLength": 1
},
"resource": {
"$ref": "https://flex-auth.netkingdom/schemas/check_request.schema.json#/$defs/resource_ref"
},
"context": {
"type": "object",
"additionalProperties": true
},
"request_digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"approval_binding_digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$",
"description": "Present only when the request carried an approval claim on context.approval. The request digest computed with that claim removed from context, so it is stable across attaching the claim and can therefore be named by an approval's pdp_digest recorded at issue time (GH-DEC-2026-008, FLEX-DEC-2026-007). Compare claim.binding.pdp_digest to THIS value, never to request_digest: a claim can never equal the digest of the request that carries it. Not a replay identity -- two requests differing only in which approval was presented share this value and their decisions do not. request_digest remains the replay identity."
}
}
},
"obligation": {
"type": "object",
"additionalProperties": false,
"required": ["type"],
"required": [
"type"
],
"properties": {
"type": {"type": "string", "minLength": 1},
"parameters": {"type": "object", "additionalProperties": true}
"type": {
"type": "string",
"minLength": 1
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
},
"lifetime": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "expires_at"],
"required": [
"kind",
"expires_at"
],
"properties": {
"kind": {"enum": ["ttl"]},
"ttl": {"type": "string", "minLength": 1},
"not_before": {"type": "string", "minLength": 1},
"expires_at": {"type": "string", "minLength": 1}
"kind": {
"enum": [
"ttl"
]
},
"ttl": {
"type": "string",
"minLength": 1
},
"not_before": {
"type": "string",
"minLength": 1
},
"expires_at": {
"type": "string",
"minLength": 1
}
}
},
"provenance": {
"type": "object",
"additionalProperties": false,
"required": ["evaluator", "mode"],
"required": [
"evaluator",
"mode"
],
"properties": {
"evaluator": {"type": "string", "minLength": 1},
"mode": {"type": "string", "minLength": 1},
"policy_package": {"type": "string", "minLength": 1},
"policy_version": {"type": "string", "minLength": 1},
"policy_package_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"registry_snapshot_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"directory_etag": {"type": "string", "minLength": 1},
"evaluator": {
"type": "string",
"minLength": 1
},
"mode": {
"type": "string",
"minLength": 1
},
"policy_package": {
"type": "string",
"minLength": 1
},
"policy_version": {
"type": "string",
"minLength": 1
},
"policy_package_digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"registry_snapshot_digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"directory_etag": {
"type": "string",
"minLength": 1
},
"input_claim_digests": {
"type": "object",
"additionalProperties": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
"additionalProperties": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
}
},
"decision_time": {"type": "string", "minLength": 1}
"decision_time": {
"type": "string",
"minLength": 1
}
}
},
"caring_decision_metadata": {
"type": "object",
"additionalProperties": false,
"required": ["profile"],
"required": [
"profile"
],
"properties": {
"profile": {"const": "caring-0.4.0-rc2"},
"descriptor": {"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json"},
"profile": {
"const": "caring-0.4.0-rc2"
},
"descriptor": {
"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json"
},
"restrictions_evaluated": {
"type": "array",
"items": {"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/restriction"},
"items": {
"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/restriction"
},
"uniqueItems": true
},
"exposure_modes": {
"type": "array",
"items": {"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/exposure_mode"},
"items": {
"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/exposure_mode"
},
"uniqueItems": true
},
"derived_capabilities": {
"type": "array",
"items": {"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/derived_capability"}
"items": {
"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/derived_capability"
}
},
"conformance_findings": {
"type": "array",
"items": {"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/conformance_finding"}
"items": {
"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/conformance_finding"
}
},
"exposure_event": {"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/exposure_event"}
"exposure_event": {
"$ref": "https://flex-auth.netkingdom/schemas/caring_access_descriptor.schema.json#/$defs/exposure_event"
}
}
}
}

16
workplans/FLEX-WP-0021-secrets-engine-consumer-policy-gate.md
View file

@ -126,7 +126,7 @@ all twelve actions could never reach it.
```task
id: FLEX-WP-0021-T03
status: progress
status: done
priority: high
state_hub_task_id: "8f7e5cdd-777e-5f54-9b92-c72b79f65672"
```
@ -143,7 +143,19 @@ Owner: `flex-auth` to emit; `secrets-engine` to verify.
Gate: secrets-engine confirms its validator accepts the real record unchanged.
A validator change on their side is their work-record, not closed from here.
**Emitted 2026-09-06**, awaiting their confirmation.
**Done 2026-09-06.** `secrets-engine` confirmed both envelopes reproduce, and
running them found a defect in *their* digest join: they were hashing `id`,
`policy_version`, and `caring_context`, which the canonical digest excludes.
Their previously pinned constant had been computed with `id` in the material, so
it was wrong and its passing proved nothing — two real envelopes were what caught
it. That is the value of handing over a real record rather than a described one.
Re-verification then surfaced a structural finding resolved in
`FLEX-DEC-2026-007`: a `pdp_digest` recorded at issue cannot equal the
`request_digest` of a request carrying the claim in its hashed context.
`binding.approval_binding_digest` is now published for that comparison.
Original emission note follows.
`examples/secrets-engine/replay/` carries two real envelopes — a plain allow
(`rotate`, empty context) and the dual-control allow (`destroy` with a valid
approval-claim). All three digests plus `input_claim_digests.context` verified