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

```json
{
  "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

```text
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.

## Correction, 2026-09-07: which digest a consumer computes

This document describes the canonical form. It does **not** follow that
`binding.request_digest` is the value a consumer reproduces.

`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. `secrets-engine` found this on its first live
request.

**The consumer's §6.4.2 replay test is `binding.submitted_request_digest`**: this
same canonical form applied to the request exactly as received. Everything below
about canonicalisation is unchanged and applies to both; what changed is which
*material* a consumer hashes. See
[`request-enrichment.md`](request-enrichment.md) and `FLEX-DEC-2026-012`.