feat: bind the destroy gate to approval_binding_digest and pdp_path

The vocabulary mapping this path was waiting on is not coming: gate-house
rejected it in GH-DEC-2026-008, because a translation can be confidently
wrong and fails open by accepting a claim approved for a different action.
The stronger option arrived instead, and both halves are enforced here.

flex-auth published binding.approval_binding_digest (FLEX-DEC-2026-007) to
fix the circularity this repo reported: a pdp_digest recorded at issue time
can never equal the request_digest of the request that carries the claim in
its hashed context, so with GH-DEC-2026-008 requiring that equality, destroy
would have failed closed forever on a check no correct record could pass.

- authorization.approval_binding_digest implements the published exclusion
  rule, including Go's context,omitempty behaviour when stripping empties
  the context; digest_material drops an empty context for the same reason.
- validate_decision_envelope recomputes the field rather than trusting it,
  refuses a claim-bearing request whose decision records none, and compares
  the claim's digest from step 1 against it -- never against request_digest,
  which still covers the claim so it stays a sound replay identity.
- validate_approval_claim requires binding.pdp_path true before using
  pdp_digest at all. Path intent is never inferred from a digest that
  happens to be present; pre-schema-v3 approvals carry pdp_path false
  regardless of any digest they hold.

Replay fixtures re-vendored from dd3ce4c. The destroy pins moved a second
and final time; approval_binding_digest did not, which is the point. The
fixture now demonstrates the property instead of asserting it: we rederive
fa07becf... from its own request through our canonical implementation,
proving we hash the same material flex-auth does rather than pinning a
constant we cannot reproduce.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E4tNMAYcSQmZWUE4wqP4ij

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 715726@bnt-lap001
Assistant-Session: 80a42b32-cba6-4b23-8be0-68819b1a6092

tests/authorization_stub.py

@@ -40,6 +40,9 @@ class AuthorizationStub:
         self.claim_valid_now = True
         self.claim_reason_code = "ok"
         self.include_pdp_digest = True
+        #: approval-engine schema v3 declares whether the approval was
+        #: requested against a bound CheckRequest; false is the pre-v3 shape
+        self.claim_pdp_path = True
         self.effect = "allow"
         self.consume_status = 200
         self._pdp_digest = ""
@@ -118,6 +121,7 @@ class AuthorizationStub:
             "target": {"id": "lane-under-test", "stage": "prod"},
             "digest": "sha256:" + "3" * 64,
         }
+        binding["pdp_path"] = self.claim_pdp_path
         if self.include_pdp_digest:
             binding["pdp_digest"] = self._pdp_digest
         return {

tests/fixtures/flex-auth-replay/PROVENANCE.md

@@ -8,16 +8,29 @@ published `secrets-engine.catalog-lane.lifecycle` v1 package via
 Vendored so the digest contract test is hermetic. Regenerate upstream and
 re-copy if the contract version changes.
 
-Re-copied 2026-09-06 after flex-auth regenerated `decision_destroy_dual_control`
-to carry a **complete** approval-claim on `context.approval` (including the
-now-required `binding.pdp_digest`). Because `context` is part of the digest
-material, completing the claim changed both the request digest and the context
-input-claim digest. The pins below are the post-regeneration values.
+Re-copied 2026-09-06 (twice, both upstream regenerations):
+
+1. commit `9f3e7e3` completed the approval-claim on `context.approval`. Because
+   `context` is hashed material, completing the claim moved the request digest.
+2. commit `dd3ce4c` (`FLEX-DEC-2026-007`) published
+   `binding.approval_binding_digest` and set the embedded claim's
+   `binding.pdp_digest` to it with `binding.pdp_path` true. The request digest
+   moved once more with the claim's contents; the approval-binding digest did
+   **not**, which is the property the fixture now demonstrates rather than
+   asserts.
+
+`decision_rotate.json` is unchanged and carries no `approval_binding_digest` —
+the field is omitted on claim-free decisions rather than duplicated onto them.
 
 **Pinned here** (stable across runs, per the upstream README):
-`binding.request_digest`, `provenance.policy_package_digest`,
-`provenance.registry_snapshot_digest`, and the presence/absence of
-`provenance.input_claim_digests.context`.
+`binding.request_digest`, `binding.approval_binding_digest`,
+`provenance.policy_package_digest`, `provenance.registry_snapshot_digest`, and
+the presence/absence of `provenance.input_claim_digests.context`.
+
+`approval_binding_digest` is not only pinned but **rederived** by
+`test_pdp_digest_equals_the_published_approval_binding_digest`: our canonical
+implementation must reproduce it from the fixture's own request. A pin asserts
+the constant; rederiving it proves we hash the same material flex-auth does.
 
 **Never pin:** `id`, `provenance.decision_time`, `lifetime.not_before`,
 `lifetime.expires_at` — all move with the clock.

tests/fixtures/flex-auth-replay/decision_destroy_dual_control.json

@@ -1,5 +1,5 @@
 {
-  "id": "decision:395efe37c5066e8a",
+  "id": "decision:44a40c339a020772",
   "contract_version": "flex-auth.decision-record.v1",
   "request_id": "check:secrets-engine-destroy",
   "effect": "allow",
@@ -72,7 +72,8 @@
           "action": "secrets.kv.destroy",
           "actor": "agt-secrets-engine",
           "digest": "sha256:3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f",
-          "pdp_digest": "sha256:570d112890586d3cbf00c0e81c85ae7806f40f00afa1a2c0a23fd5e077a27f56",
+          "pdp_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56",
+          "pdp_path": true,
           "principal": "bernd",
           "purpose": "rotate-exposed-key",
           "target": {
@@ -98,13 +99,14 @@
         }
       }
     },
-    "request_digest": "sha256:fc155dba88f8ab18b3032ed086ba2f455158c6981106e7829d520ab7b036bdf3"
+    "request_digest": "sha256:c749ee2dc3cdf927a70a3e5b27cff4d97a438d3264153b4b2e3bcacbaf82091a",
+    "approval_binding_digest": "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56"
   },
   "lifetime": {
     "kind": "ttl",
     "ttl": "15m",
-    "not_before": "2026-09-06T12:18:21Z",
-    "expires_at": "2026-09-06T12:33:21Z"
+    "not_before": "2026-09-06T12:51:16Z",
+    "expires_at": "2026-09-06T13:06:16Z"
   },
   "diagnostics": {
     "action": "destroy",
@@ -122,9 +124,9 @@
     "policy_package_digest": "sha256:fe0070b79f66442ae6c218697a49c470c6c8f670aa57a30c078a5284d097bd8c",
     "registry_snapshot_digest": "sha256:f5a309bc0b36721fd6d9ad7f53eb21222162bc2eac62a0ab0802a9a1d51340bb",
     "input_claim_digests": {
-      "context": "sha256:b0d2203cd2b43a9ba573c21c038154c131afba4255e313affd7ecf810e2cc221"
+      "context": "sha256:8b73d29ecef286d42e03d2420531d6c45219f325a7ae004c1ecfc781203a2800"
     },
-    "decision_time": "2026-09-06T12:18:21Z"
+    "decision_time": "2026-09-06T12:51:16Z"
   },
   "caring": {
     "profile": "caring-0.4.0-rc2",

tests/test_approval_claim.py

@@ -122,6 +122,7 @@ def test_principal_falls_back_to_actor_when_absent():
 def test_pdp_digest_is_preferred_when_the_issuer_recorded_one():
     claim = _claim()
     claim["binding"]["pdp_digest"] = "sha256:" + "a" * 64
+    claim["binding"]["pdp_path"] = True
     claim["binding"]["digest"] = "sha256:" + "b" * 64  # native no longer matches
     assert _validate(claim, expected_pdp_digest="sha256:" + "a" * 64)
 

tests/test_consume_binding_join.py

@@ -84,6 +84,7 @@ def _served(entry=None, action="deactivate", fields=("api_token",), **over):
             # comparison usable today: the native digest speaks
             # approval-engine's vocabulary and no mapping to ours is published.
             "pdp_digest": request_digest(request),
+            "pdp_path": True,
         },
         "freshness": {
             "observed_at": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
@@ -191,6 +192,30 @@ def test_superseded_claim_fails_closed(tmp_path):
         _resolve(_Cfg(_token(tmp_path)), _entry(), _served(valid_now=False, reason_code="superseded"))
 
 
+def test_claim_without_pdp_path_fails_closed(tmp_path):
+    """pdp_path is a declaration, and it is never inferred from a digest.
+
+    approval-engine schema v3 refuses to issue pdp_path true without a
+    pdp_digest, so a true declaration guarantees the digest. The converse does
+    not hold: a digest recorded for some other reason is not a statement that
+    this approval was requested against a bound CheckRequest, and approvals
+    issued before v3 carry pdp_path false regardless of any digest they hold
+    (GH-DEC-2026-008).
+    """
+    claim = _served()
+    claim["binding"]["pdp_path"] = False
+    with pytest.raises(DecisionError, match="does not declare binding.pdp_path"):
+        _resolve(_Cfg(_token(tmp_path)), _entry(), claim)
+
+
+def test_claim_omitting_pdp_path_fails_closed(tmp_path):
+    """An absent declaration is not a true one."""
+    claim = _served()
+    claim["binding"].pop("pdp_path")
+    with pytest.raises(DecisionError, match="does not declare binding.pdp_path"):
+        _resolve(_Cfg(_token(tmp_path)), _entry(), claim)
+
+
 def test_claim_without_pdp_digest_fails_closed_naming_the_missing_mapping(tmp_path):
     """No published vocabulary mapping means the claim cannot be tied to this action.
 

tests/test_decision_replay.py

@@ -17,6 +17,7 @@ from pathlib import Path
 import pytest
 
 from secrets_engine.authorization import (
+    approval_binding_digest,
     digest_material,
     request_digest,
     validate_decision_envelope,
@@ -37,9 +38,9 @@ CASES = {
     },
     "destroy": {
         "file": "decision_destroy_dual_control.json",
-        "digest": "sha256:fc155dba88f8ab18b3032ed086ba2f455158c6981106e7829d520ab7b036bdf3",
+        "digest": "sha256:c749ee2dc3cdf927a70a3e5b27cff4d97a438d3264153b4b2e3bcacbaf82091a",
         "action": "destroy",
-        "context_claim_digest": "sha256:b0d2203cd2b43a9ba573c21c038154c131afba4255e313affd7ecf810e2cc221",
+        "context_claim_digest": "sha256:8b73d29ecef286d42e03d2420531d6c45219f325a7ae004c1ecfc781203a2800",
     },
 }
 
@@ -180,14 +181,19 @@ def test_embedded_claim_uses_approval_engine_vocabulary_not_ours():
     assert claim["binding"]["target"]["id"] != envelope["resource"]["id"]
 
 
+APPROVAL_BINDING_DIGEST = (
+    "sha256:fa07becfaa471394d06aee5fa3cd66352bf0cc69ef24900240489684cda8cd56"
+)
+
+
 def test_embedded_claim_pdp_digest_cannot_equal_the_carrying_request_digest():
     """Carrying the claim inside a hashed context makes the two unequal.
 
     context is part of the digest material, so embedding an approval-claim
     changes the request digest of the very request that carries it. A
     pdp_digest recorded at issue time therefore cannot equal the final digest
-    of the dual-control request. Raised with approval-engine and flex-auth; this
-    test records the property so a future change is visible rather than silent.
+    of the dual-control request. This is why comparing pdp_digest against
+    request_digest can never pass and would fail destroy closed forever.
     """
     envelope = _envelope("destroy")
     binding = envelope["binding"]
@@ -195,8 +201,112 @@ def test_embedded_claim_pdp_digest_cannot_equal_the_carrying_request_digest():
     request = _request_from(envelope)
     assert request_digest(request) == binding["request_digest"]
     assert pdp != binding["request_digest"]
-    without_claim = dict(request)
-    without_claim["context"] = {
-        k: v for k, v in binding["context"].items() if k != "approval"
-    }
-    assert pdp != request_digest(without_claim)
+
+
+def test_pdp_digest_equals_the_published_approval_binding_digest():
+    """FLEX-DEC-2026-007 closed the circularity, and we reproduce the value.
+
+    ``approval_binding_digest`` is the canonical digest with context.approval
+    removed. Recomputing it here from our own canonical implementation is the
+    hermetic proof that this engine hashes the same material flex-auth does --
+    a pin alone would only assert the constant, not that we can derive it.
+    """
+    envelope = _envelope("destroy")
+    binding = envelope["binding"]
+    pdp = binding["context"]["approval"]["binding"]["pdp_digest"]
+    assert binding["approval_binding_digest"] == APPROVAL_BINDING_DIGEST
+    assert pdp == APPROVAL_BINDING_DIGEST
+
+    assert approval_binding_digest(_request_from(envelope)) == APPROVAL_BINDING_DIGEST
+
+
+def test_approval_binding_digest_is_not_a_replay_identity():
+    """It must not collapse into request_digest, or an allow becomes replayable.
+
+    Two requests differing only in which approval was presented share an
+    approval_binding_digest while their decisions differ -- one allows, one
+    denies dual_control_required. The fixture asserts the two digests disagree
+    on a claim-bearing request so the distinction stays real.
+    """
+    envelope = _envelope("destroy")
+    binding = envelope["binding"]
+    assert binding["approval_binding_digest"] != binding["request_digest"]
+
+
+def test_ordinary_decision_carries_no_approval_binding_digest():
+    """The field is omitted, not duplicated, on a claim-free decision."""
+    binding = _envelope("rotate")["binding"]
+    assert "approval" not in binding.get("context", {})
+    assert "approval_binding_digest" not in binding
+
+
+def test_embedded_claim_declares_the_pdp_path():
+    """pdp_path is the issuer's declaration, and it is what our PEP requires.
+
+    Path intent is never inferred from a pdp_digest that happens to be present;
+    approvals issued before approval-engine schema v3 carry pdp_path false
+    regardless of any digest they hold.
+    """
+    claim = _envelope("destroy")["binding"]["context"]["approval"]
+    assert claim["binding"]["pdp_path"] is True
+
+
+def test_decision_validation_ties_the_claim_to_the_approval_binding_digest():
+    """Step 2 checks the identity against the real envelope, not a local guess.
+
+    The PEP knows the claim's pdp_digest from step 1. When the request it sent
+    carried that claim, the decision must name the same claim-free envelope, or
+    the approval was issued against some other request.
+    """
+    envelope = _refresh_lifetime(_envelope("destroy"))
+    request = _request_from(envelope)
+    result = validate_decision_envelope(
+        envelope,
+        request,
+        accepted_policy_packages={"secrets-engine.catalog-lane.lifecycle"},
+        accepted_policy_versions={"v1"},
+        expected_approval_binding_digest=APPROVAL_BINDING_DIGEST,
+    )
+    assert result.action == "destroy"
+
+    with pytest.raises(DecisionError, match="approval binding digest"):
+        validate_decision_envelope(
+            envelope,
+            request,
+            accepted_policy_packages={"secrets-engine.catalog-lane.lifecycle"},
+            accepted_policy_versions={"v1"},
+            expected_approval_binding_digest="sha256:" + "c" * 64,
+        )
+
+
+def test_claim_bearing_request_without_a_binding_digest_fails_closed():
+    """A decision that records no binding digest cannot tie the claim to itself.
+
+    Comparing against request_digest instead would be the fail-open direction
+    the whole field exists to prevent, so the absence is refused outright.
+    """
+    envelope = _refresh_lifetime(_envelope("destroy"))
+    request = _request_from(envelope)
+    del envelope["binding"]["approval_binding_digest"]
+    with pytest.raises(DecisionError, match="records no approval_binding_digest"):
+        validate_decision_envelope(
+            envelope,
+            request,
+            accepted_policy_packages={"secrets-engine.catalog-lane.lifecycle"},
+            accepted_policy_versions={"v1"},
+            expected_approval_binding_digest=APPROVAL_BINDING_DIGEST,
+        )
+
+
+def test_a_forged_binding_digest_is_recomputed_not_trusted():
+    """The field is verified against our own canonical digest, never taken on faith."""
+    envelope = _refresh_lifetime(_envelope("destroy"))
+    request = _request_from(envelope)
+    envelope["binding"]["approval_binding_digest"] = "sha256:" + "d" * 64
+    with pytest.raises(DecisionError, match="does not match this request"):
+        validate_decision_envelope(
+            envelope,
+            request,
+            accepted_policy_packages={"secrets-engine.catalog-lane.lifecycle"},
+            accepted_policy_versions={"v1"},
+        )