tegwick
0bc624ba62
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
6.4 KiB
Decision-record contract
Status: published
Contract: flex-auth.decision-record.v1
Schema: ../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 |
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 |
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. 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 |
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 and
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.
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.
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
(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
(FLEX-DEC-2026-012).