flex-auth/docs/canonical-request-digest.md

Canonical request digest

Status: published Date: 2026-09-02 Standard: security-layer-model_v0.7 §6.4.2

The digest is the mechanical test for replaying a flex-auth verdict. A consumer may reuse an allow iff a new request produces the same digest and the decision's lifetime still holds. Negative caching of a deny uses the same test.

Constructor: api.NewDecisionBinding / api.RequestDigest. Field: DecisionEnvelope.binding.request_digest. Format: sha256: plus 64 lowercase hex characters.

What is hashed

Canonical JSON (Go encoding/json, which sorts map keys) of:

Field	Source
tenant	CheckRequest.tenant
subject	normalized CheckRequest.subject
action	CheckRequest.action
resource	normalized CheckRequest.resource
context	CheckRequest.context

Empty optional maps and omitempty strings are omitted. Attribute maps inside subject and resource are part of the material once the evaluator has enriched them from the registry.

Not hashed: id, policy_version, and caring_context. The request id is correlation only. Policy version is recorded in provenance. CARING context is hashed separately as provenance.input_claim_digests.caring_context.

Normalization

1. Tenant on the request is copied onto subject and resource when those refs omit it.
2. A registry hit copies type, tenant, and selected attributes onto the refs the digest sees.
3. Context is a shallow copy. Key order is not significant.

A consumer that re-hashes the original unenriched request will not match a decision that turned on registry attributes. Compare structured binding fields to the proposed action, and treat request_digest as the evaluator's statement of what it hashed. To recompute independently, hash the same normalized tuple the binding carries (tenant, subject, action, resource, context).

Stability

The digest is stable across process restarts for the same normalized tuple. It is not stable across:

• a change to any hashed field, including registry-enriched attributes
• a change to this contract (would require a new contract_version)

It does not include the policy package, snapshot, or clock. Those live in provenance and lifetime. Two allows over the same tuple but different snapshots share a digest and differ in registry_snapshot_digest.

Worked example — permitted retry

Request (after enrichment):

{
  "tenant": "tenant:alpha",
  "subject": {"id": "user:alice", "type": "Human", "tenant": "tenant:alpha"},
  "action": "read",
  "resource": {
    "id": "document:internal-note",
    "type": "document",
    "system": "markitect-tool",
    "tenant": "tenant:alpha"
  },
  "context": {"purpose": "project-delivery"}
}

The evaluator stores binding.request_digest for that tuple and lifetime.expires_at in the future. The same subject, action, resource, and context presented again before expiry is a permitted retry of that allow.

Worked example — refused replay

Any of the following refuses replay:

• action changes from read to destroy (digest mismatch)
• resource.attributes.stage changes from build to production (digest mismatch)
• lifetime.expires_at is in the past (lifetime does not hold)
• the stored effect is deny and the consumer is attempting to treat a cached refusal as still binding after a policy change — negative cache is valid only for the same digest and while the recorded lifetime would have held; a new Check is required once either fails

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

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.