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
121 lines
6.4 KiB
Markdown
121 lines
6.4 KiB
Markdown
# 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` |
|
|
| `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`](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`](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.
|
|
|
|
## 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`](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`).
|