coulomb/approval-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

State pdp_digest explicitly; decline to publish a vocabulary mapping

Browse source 
flex-auth asked whether this engine should publish an action/target
mapping between the claim binding's vocabulary (secrets.kv.destroy,
{"id": "lane-openbao-root"}) and a policy package's (destroy, lane:...),
since their package makes no cross-check that a claim was approved for
the action being decided.

Answered no. A PIP asserting that one vocabulary's action means
another's would author policy semantics it does not own, over
vocabularies it does not own, and the failure mode is asymmetric: a wrong
mapping silently accepts a claim approved for a different action, which
is worse than no mapping. binding.pdp_digest is the correspondence and
sidesteps vocabulary entirely -- it compares the PDP's own digest to the
PDP's own digest, with no translation by anyone.

Implemented the part that was ours. pdp_digest was emitted only when
recorded, so a consumer could not distinguish "not issued against a
decision" from "we forgot to look". It is now always present and null in
that case, required-but-nullable in the schema, and documented as
something a PEP on a privileged lane must refuse. This engine states the
fact; enforcing the lane's policy stays with the consumer.

Both published examples were already contradicting the updated schema by
omitting the field -- the same fixture-versus-contract defect flex-auth
hit twice this week and that secrets-engine implemented. Fixed both, made
them cover the PDP-bound and unbound shapes so neither is inferred from
the other, and added tests/test_examples.py to validate every example
against the schema so the class cannot recur here. jsonschema added as a
dev dependency.

94 tests pass (6 new).

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

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 411227@bnt-lap001
Assistant-Session: d566f6d3-bcaf-43c3-bc5e-3ddd0f64b535
This commit is contained in:
tegwick 2026-09-06 09:32:11 +02:00
parent 87e55e2bca
commit 6d0dfc8010
8 changed files with 224 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

136
schemas/approval_claim.schema.json
View file

@ -2,7 +2,7 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://approval-engine.netkingdom/schemas/approval_claim.schema.json",
"title": "ApprovalClaim",
"description": "Input claim that access-engine consumes. This is a fact about an approval object, not a decision. Yields to the Taxonomy request-claim schema (statute §17) when that artifact exists and is assented; do not treat this local shape as permanent.",
"description": "Input claim that access-engine consumes. This is a fact about an approval object, not a decision. Yields to the Taxonomy request-claim schema (statute \u00a717) when that artifact exists and is assented; do not treat this local shape as permanent.",
"type": "object",
"additionalProperties": false,
"required": [
@ -19,14 +19,23 @@
"reason_code"
],
"properties": {
"schema_version": { "const": "0.1" },
"kind": { "const": "approval-claim" },
"schema_version": {
"const": "0.1"
},
"kind": {
"const": "approval-claim"
},
"yields_to": {
"type": "string",
"description": "Taxonomy artifact this contract yields to. Informational; consumers must not branch on it."
},
"issuer": { "const": "approval-engine" },
"approval_id": { "type": "string", "format": "uuid" },
"issuer": {
"const": "approval-engine"
},
"approval_id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
@ -43,10 +52,18 @@
"type": "boolean",
"description": "True only when the object is approved, inside its validity window, and not consumed, superseded, revoked, or expired. Not a permission."
},
"consumed": { "type": "boolean" },
"binding": { "$ref": "#/$defs/binding" },
"freshness": { "$ref": "#/$defs/freshness" },
"validity": { "$ref": "#/$defs/validity" },
"consumed": {
"type": "boolean"
},
"binding": {
"$ref": "#/$defs/binding"
},
"freshness": {
"$ref": "#/$defs/freshness"
},
"validity": {
"$ref": "#/$defs/validity"
},
"reason_code": {
"type": "string",
"enum": [
@ -63,52 +80,115 @@
},
"not": {
"anyOf": [
{ "required": ["effect"] },
{ "required": ["decision"] },
{ "required": ["allow"] },
{ "required": ["deny"] }
{
"required": [
"effect"
]
},
{
"required": [
"decision"
]
},
{
"required": [
"allow"
]
},
{
"required": [
"deny"
]
}
]
},
"$defs": {
"binding": {
"type": "object",
"additionalProperties": false,
"required": ["action", "target", "actor", "principal", "purpose", "digest"],
"required": [
"action",
"target",
"actor",
"principal",
"purpose",
"digest",
"pdp_digest"
],
"properties": {
"action": { "type": "string", "minLength": 1 },
"target": { "type": "object" },
"actor": { "type": "string", "minLength": 1 },
"principal": { "type": "string", "minLength": 1 },
"purpose": { "type": "string", "minLength": 1 },
"action": {
"type": "string",
"minLength": 1
},
"target": {
"type": "object"
},
"actor": {
"type": "string",
"minLength": 1
},
"principal": {
"type": "string",
"minLength": 1
},
"purpose": {
"type": "string",
"minLength": 1
},
"digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$",
"description": "SHA-256 over the canonical JSON of action, actor, principal, purpose, target (sorted keys, RFC 8259). Distinguishes approved from approved-for-this-exact-request."
},
"pdp_digest": {
"type": "string",
"type": [
"string",
"null"
],
"pattern": "^sha256:[0-9a-f]{64}$",
"description": "Optional. The flex-auth NewDecisionBinding request_digest recorded at issue time. When present, access-engine MUST compare this to the digest it already computes, not re-derive our native digest as a substitute."
"description": "The flex-auth NewDecisionBinding request_digest recorded at issue time, or null when the approval was not issued against a PDP decision. Always present so its absence is a stated fact rather than a missing key. When non-null, access-engine MUST compare this to the digest it already computes and MUST NOT re-derive the native digest as a substitute. A PEP on a privileged lane MUST refuse a claim whose pdp_digest is null."
}
}
},
"freshness": {
"type": "object",
"additionalProperties": false,
"required": ["observed_at", "ttl_seconds", "not_after"],
"required": [
"observed_at",
"ttl_seconds",
"not_after"
],
"properties": {
"observed_at": { "type": "string", "format": "date-time" },
"ttl_seconds": { "type": "integer", "minimum": 1 },
"not_after": { "type": "string", "format": "date-time" }
"observed_at": {
"type": "string",
"format": "date-time"
},
"ttl_seconds": {
"type": "integer",
"minimum": 1
},
"not_after": {
"type": "string",
"format": "date-time"
}
}
},
"validity": {
"type": "object",
"additionalProperties": false,
"required": ["not_before", "expires_at"],
"required": [
"not_before",
"expires_at"
],
"properties": {
"not_before": { "type": "string", "format": "date-time" },
"expires_at": { "type": "string", "format": "date-time" }
"not_before": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}
}