2026-09-03 23:48:45 +02:00
# Decision-record contract
Status: published
Contract: `flex-auth.decision-record.v1`
Schema: [`../schemas/decision_envelope.schema.json` ](../schemas/decision_envelope.schema.json )
Date: 2026-09-02
This is flex-auth's output artifact under the NetKingdom Security Layer Model
v0.7 §17. Taxonomy holds only the shared field vocabulary. Consumers may rely
on this schema.
A decision record is a `DecisionEnvelope` returned by `POST /v1/check` and the
CLI `check` / `batch-check` / `list-allowed` commands. Standalone evaluation
and every delegated adapter (Topaz, relationship, rule, Keycloak) emit the
same shape.
## Required fields
| Field | Meaning |
| --- | --- |
| `id` | Deterministic decision identifier |
| `effect` | `allow` , `deny` , `redact` , `audit_only` , or `not_applicable` |
| `subject` / `resource` | Normalized refs the evaluator used |
| `provenance` | Who evaluated, over which policy and facts |
## Contract fields consumers may rely on
| Field | Meaning |
| --- | --- |
| `contract_version` | `flex-auth.decision-record.v1` |
| `binding` | Structured subject, action, resource, context, and `request_digest` |
fix(decision): registry facts win over caller-supplied attributes
secrets-engine's first live request rejected our allow: binding.
request_digest is computed over material they never sent, because we
enrich subject and resource from the registry before hashing. Answering
that meant reading the enrichment path, which had a worse defect in it.
Enrichment was additive-if-absent — addAttribute wrote a registry value
only where the request had no value for that key. So where a caller
supplied a key, the caller's value won and the registry's never applied.
Every registry ceiling and allowlist was advisory. Verified against the
shipped ops-warden package, each one added key on an otherwise-denied
request:
max_ttl_hours: 99 registry says 8 -> allowed a 12h certificate
allowed_principals registry allowlist -> disallowed_principal bypassed
allowed_subjects registry allowlist -> unknown_subject bypassed
The third is the one to read twice: a subject the registry does not know
authorized itself by naming itself in the allowlist it was being checked
against.
Not remotely reachable today — the PEP builds the CheckRequest,
ops-warden sends no resource.attributes, and enforce admits one identity.
It is a defence-in-depth failure: any path that lets attacker-influenced
data into a CheckRequest field became a full policy bypass rather than a
bounded input problem. Callers sending resource.attributes is not
hypothetical; secrets-engine does it on every request.
Registry facts now win, and diagnostics.registry_overrode names every
displaced key, because a registry that silently discards a contradicting
claim hides that a caller asserted authority it did not have.
subject.type is carved out, and the reason is a finding of its own.
Making the registry win there denied every secrets-engine allow: the
registry's type is CARING vocabulary (Human, Agent, Automation, Service)
and the request's is the protected system's actor vocabulary (service,
adm, agt, atm). Two fields sharing a name; substituting one for the other
is translation rather than identity, which GH-DEC-2026-008 ruled against.
Note what surfaced it — the registry's type had been dead data since the
field existed, because the caller's value always won.
Also publishes binding.submitted_request_digest, over the request exactly
as sent. request_digest was published as the consumer replay test and
cannot be one. Nothing is lost hashing the pre-enrichment form:
enrichment is a function of the request and the snapshot, and
registry_snapshot_digest already pins the snapshot.
Existing pins do not move. All three replay fixtures' request_digest and
approval_binding_digest values are byte-identical — those requests
contradict no registry fact. A field to add, not a value to correct.
Regression tests verified failing against the old behaviour before being
kept. FLEX-DEC-2026-012; FLEX-WP-0025 carries the residual, that a policy
still cannot tell a fact from an assertion.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014aQMM1dPXaPiXVn6DwwtLd
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 715613@bnt-lap001
Assistant-Session: fabd95c1-4c9e-4080-8849-8707ae025f80
2026-09-07 13:43:33 +02:00
| `binding.submitted_request_digest` | Digest over the request **exactly as sent** , before registry enrichment. **This is the consumer's replay test** for §6.4 obligation 2 |
| `binding.submitted_request_digest` | Digest over the request **exactly as sent** , before registry enrichment. **This is the consumer's replay test** for §6.4 obligation 2 |
Publish approval_binding_digest: a claim cannot name the request carrying it
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
2026-09-06 14:52:33 +02:00
| `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 |
2026-09-03 23:48:45 +02:00
| `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 |
| `provenance.registry_snapshot_digest` | SHA-256 of the canonical registry snapshot |
| `provenance.directory_etag` | Directory consistency token when a delegated directory was joined |
| `provenance.input_claim_digests` | SHA-256 per request-time claim class (`context` , `caring_context` ) |
| `provenance.decision_time` | UTC timestamp used to compute `lifetime` |
`reason` , `diagnostics` , and CARING prose are not an authorization contract.
## Allow lifetime
Every allow carries `lifetime.kind = ttl` . The duration comes from the policy
package `allow_ttl` field, or from the engine default of `15m` when the package
omits it. A package that declares `allow_ttl: none` (or `0s` ) produces a deny
with reason `allow_lifetime_unstated` instead of a standing grant.
Replay is permitted only while `lifetime.expires_at` is still in the future.
See [`canonical-request-digest.md` ](canonical-request-digest.md ) and
[`decision-input-freshness.md` ](decision-input-freshness.md ).
## Versioning
This is contract version 1. Additive optional fields may appear. Removing or
redefining a required field requires a new `contract_version` value and a new
schema id.
fix: the address we published was a misdirection, and the channel is unauthenticated
secrets-engine probed the Service DNS name handed over in FLEX-WP-0021-T05
and found it resolves, from the workstation, to an unrelated public host.
Reproduced here: search ad.binect.de answers wildcard, so
flex-auth-secrets-engine.flex-auth.svc.cluster.local and
this-service-does-not-exist.flex-auth.svc.cluster.local both resolve to
80.158.43.29, while the trailing-dot FQDN correctly fails. A bare Service
name in a handover is not merely unreachable from there, it is a live
misdirection, and the handover was ours.
Had a deployment pointed at it, the CheckRequest body would have gone to
that host: subject, tenant, lane and resource ids, stage, field names,
purpose, plus the caller's bearer token.
Trailing-dot FQDN and "in-cluster only" now replace the bare name in the
example README, SCOPE.md, and the T05 note.
Their real question was how the response channel is authenticated, and
they declined to answer it locally because choosing a transport control
for our service is not a consumer's call. Right boundary, so the answer
is recorded here as FLEX-DEC-2026-010: it is not authenticated. Pins
serve plain HTTP, the envelope carries no signature, and a responder that
knows the package id and version can return a well-formed allow that
passes every check a consumer performs.
The part worth stating in the contract is that the digests do not help
and look like they do. Every input to request_digest,
policy_package_digest and registry_snapshot_digest is either sent by the
caller or published in this repo, so a forger reproduces all three
exactly. They establish integrity of the binding, never authenticity of
the source — and publishing more digests makes a forged envelope look
more authenticated, not less.
For secrets-engine specifically: fail-closed protects against a PDP that
is absent, not against one that lies. An unreachable PDP denies; a lying
PDP allows.
Third instance of one seam in three decisions. 008: a tenant carried
into the digest and never compared — visible, not enforced. 009: a caller
authenticated and never recorded — enforced, not visible. 010: a record
verifiable and unauthentic — checkable, but not evidence.
One nuance that changes the operator recommendation: kubectl port-forward
does authenticate the responder, transitively — no DNS name, one named
pod, API-server TLS. That is the exact reverse of the caller direction,
where it bypasses the NetworkPolicy. Independent properties pointing
opposite ways, so neither can be summarised as "the network protects it".
FLEX-WP-0024 carries signing; key custody routes through warden/OpenBao
rather than minting a key here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014aQMM1dPXaPiXVn6DwwtLd
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 715613@bnt-lap001
Assistant-Session: fabd95c1-4c9e-4080-8849-8707ae025f80
2026-09-06 22:44:45 +02:00
## What this record does not prove: who answered
**A consumer must not read digest recomputation as verification of the
responder.** Recomputing `binding.request_digest` ,
`provenance.policy_package_digest` , and `provenance.registry_snapshot_digest`
and finding all three correct says nothing about who produced the envelope.
Every input to those digests is either sent by the caller or published: the
request material is what the caller just transmitted, and both the package and
registry digests are computable from files in this repo. A responder that knows
the package id and version can reproduce all three exactly. The digests
establish **integrity of the binding** , never **authenticity of the source** .
`flex-auth.decision-record.v1` carries no signature today, and pins serve plain
HTTP. So the response channel is unauthenticated, stated as a stance rather than
left as an assumption (`FLEX-DEC-2026-010` ). For a fail-closed consumer the
distinction that matters is this: **fail-closed protects against a PDP that is
absent, not against one that lies.** An unreachable PDP denies; a lying PDP
allows.
A detached signature over the canonical envelope is the intended fix
(`FLEX-WP-0024` ). Until it lands, responder authenticity comes from the channel
alone — and of the available channels only `kubectl port-forward` supplies it,
by targeting one named pod over the API server's TLS with no DNS name resolved.
fix(decision): registry facts win over caller-supplied attributes
secrets-engine's first live request rejected our allow: binding.
request_digest is computed over material they never sent, because we
enrich subject and resource from the registry before hashing. Answering
that meant reading the enrichment path, which had a worse defect in it.
Enrichment was additive-if-absent — addAttribute wrote a registry value
only where the request had no value for that key. So where a caller
supplied a key, the caller's value won and the registry's never applied.
Every registry ceiling and allowlist was advisory. Verified against the
shipped ops-warden package, each one added key on an otherwise-denied
request:
max_ttl_hours: 99 registry says 8 -> allowed a 12h certificate
allowed_principals registry allowlist -> disallowed_principal bypassed
allowed_subjects registry allowlist -> unknown_subject bypassed
The third is the one to read twice: a subject the registry does not know
authorized itself by naming itself in the allowlist it was being checked
against.
Not remotely reachable today — the PEP builds the CheckRequest,
ops-warden sends no resource.attributes, and enforce admits one identity.
It is a defence-in-depth failure: any path that lets attacker-influenced
data into a CheckRequest field became a full policy bypass rather than a
bounded input problem. Callers sending resource.attributes is not
hypothetical; secrets-engine does it on every request.
Registry facts now win, and diagnostics.registry_overrode names every
displaced key, because a registry that silently discards a contradicting
claim hides that a caller asserted authority it did not have.
subject.type is carved out, and the reason is a finding of its own.
Making the registry win there denied every secrets-engine allow: the
registry's type is CARING vocabulary (Human, Agent, Automation, Service)
and the request's is the protected system's actor vocabulary (service,
adm, agt, atm). Two fields sharing a name; substituting one for the other
is translation rather than identity, which GH-DEC-2026-008 ruled against.
Note what surfaced it — the registry's type had been dead data since the
field existed, because the caller's value always won.
Also publishes binding.submitted_request_digest, over the request exactly
as sent. request_digest was published as the consumer replay test and
cannot be one. Nothing is lost hashing the pre-enrichment form:
enrichment is a function of the request and the snapshot, and
registry_snapshot_digest already pins the snapshot.
Existing pins do not move. All three replay fixtures' request_digest and
approval_binding_digest values are byte-identical — those requests
contradict no registry fact. A field to add, not a value to correct.
Regression tests verified failing against the old behaviour before being
kept. FLEX-DEC-2026-012; FLEX-WP-0025 carries the residual, that a policy
still cannot tell a fact from an assertion.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014aQMM1dPXaPiXVn6DwwtLd
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 715613@bnt-lap001
Assistant-Session: fabd95c1-4c9e-4080-8849-8707ae025f80
2026-09-07 13:43:33 +02:00
## `request_digest` is not the consumer's replay test
Correction, 2026-09-07. `request_digest` is computed over the **enriched**
request — after the evaluator overlays registry facts onto subject and resource —
so a consumer recomputing it over what it sent gets a different value on every
request whose subject or resource the registry knows. It was published as the
§6.4.2 replay test and cannot be one, because the registry is flex-auth's.
**Compare `binding.submitted_request_digest` instead.** It is `RequestDigest`
over the request exactly as received, and together with
`provenance.registry_snapshot_digest` it identifies the evaluated request
completely — enrichment is a function of those two. `request_digest` keeps its
value and its meaning as flex-auth's own audit-replay identity.
What the evaluator may add, which value wins where the two disagree, and the
stated residual are in [`request-enrichment.md` ](request-enrichment.md )
(`FLEX-DEC-2026-012` ).
## `request_digest` is not the consumer's replay test
Correction, 2026-09-07. `request_digest` is computed over the **enriched**
request — after the evaluator overlays registry facts onto subject and resource —
so a consumer recomputing it over what it sent gets a different value on every
request whose subject or resource the registry knows. It was published as the
§6.4.2 replay test and cannot be one, because the registry is flex-auth's.
**Compare `binding.submitted_request_digest` instead.** It is `RequestDigest`
over the request exactly as received, and together with
`provenance.registry_snapshot_digest` it identifies the evaluated request
completely — enrichment is a function of those two. `request_digest` keeps its
value and its meaning as flex-auth's own audit-replay identity.
What the evaluator may add, which value wins where the two disagree, and the
stated residual are in [`request-enrichment.md` ](request-enrichment.md )
(`FLEX-DEC-2026-012` ).
