flex-auth/docs/decision-record-contract.md

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
provenance.caller	How the request was authenticated to the PDP. Additive; not decision material. mode is required (disabled / warn / enforce). A principal recorded under warn was observed, not enforced. Under disabled the object is {"mode":"disabled"} with no principal. not_after is the reviewed token exp. Does not affect request_digest. See FLEX-DEC-2026-009
signature	Detached Ed25519 signature over the canonical envelope with this field omitted. mode is signed or unsigned (absence stated). Additive; does not affect request_digest. See decision-envelope-signature.md (FLEX-WP-0024)

reason, diagnostics, and CARING prose are not an authorization contract.

Caller provenance is not a digest input

provenance.caller records who obtained the decision. The caller is deliberately absent from binding, so two requests that differ only in the authenticated principal produce the same request_digest. Consumers must not re-pin replay joins because this field appeared (FLEX-DEC-2026-009).

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).