secrets-engine/docs/pdp-access-path.md

Reaching the access-engine pin

The supported way for this engine to reach flex-auth-secrets-engine, and the reason the address is enforced in code rather than left to configuration.

Never the Service DNS name

SECRETS_ENGINE_PDP_URL=http://flex-auth-secrets-engine.flex-auth.svc.cluster.local:8080

is refused by decision_check.require_supported_pdp_address. From a workstation that name does not fail — it resolves, to the wrong host:

$ getent hosts flex-auth-secrets-engine.flex-auth.svc.cluster.local
80.158.43.29   ...svc.cluster.local.ad.binect.de
$ getent hosts this-service-does-not-exist.flex-auth.svc.cluster.local
80.158.43.29   (identical — proves suffix expansion, not a record)

resolv.conf carries search ad.binect.de, a wildcard zone, so every *.svc.cluster.local name answers with one unrelated public address. Sending there ships the CheckRequest body and our bearer token to a third party.

flex-auth.decision-record.v1 supports a detached Ed25519 signature on the producer side (FLEX-WP-0024), but this consumer does not yet verify it against independently admitted keys. Without that verification, every binding digest is either sent by us or published in flex-auth's repo, so a forger can reproduce those digests. Digests establish integrity of the binding, never authenticity of the source. As flex-auth put it in FLEX-DEC-2026-010:

Fail-closed protects against a PDP that is ABSENT, not against one that LIES.

The literal loopback address restriction limits the destination; it does not prove responder identity. The operator must verify the cluster and named pod behind the port-forward. Signed consumer enforcement, independently admitted verification keys, rotation and downgrade tests remain open in SECRETS-WP-0014 and Custodian G13. Producer support alone does not close that gap.

The Check client disables automatic redirects, environment/system proxies and the process-global urllib opener. A 3xx response fails closed without contacting the redirect destination. URLs must be HTTP(S) bare origins with a literal loopback IP and optional nonzero port: no hostname (including localhost), userinfo, path prefix, query, fragment or whitespace/control characters. Existing localhost configuration must use 127.0.0.1 or [::1]. Invalid configuration is rejected before reading the bearer file. Responses are limited to 512 KiB; oversized, invalid UTF-8 and non-object JSON bodies fail closed. These rules also apply when the approval flow invokes the PDP client.

Regression tests use disposable local HTTP servers and synthetic credentials; they do not demonstrate identity or signature verification on the native pin.

The supported path

Use literal loopback kubectl port-forward to the admitted named pod after verifying the cluster identity and pod identity. That path rides the Kubernetes API server's TLS with the operator's cluster credentials; the client cannot infer that binding from its local URL. Note this is the exact reverse of the caller direction, where port-forward bypasses the NetworkPolicy (FLEX-WP-0023); the two properties point opposite ways and summarising either as "the network protects it" gets one backwards.

# 1. Target the pod by name, not the Service.
POD=$(kubectl -n flex-auth get pods \
        -l app.kubernetes.io/name=flex-auth-secrets-engine \
        -o jsonpath='{.items[0].metadata.name}')
kubectl -n flex-auth port-forward "pod/$POD" 18080:8080 --address 127.0.0.1 &

# 2. Fresh bounded caller token per session. Audience MUST be flex-auth;
#    caller auth is `enforce` as of Helm revision 3.
umask 077
kubectl -n secrets-engine create token secrets-engine \
        --audience flex-auth --duration 10m > "$PDP_TOKEN"
chmod 600 "$PDP_TOKEN"          # outside any Git worktree

# 3. Point the engine at the forward.
export SECRETS_ENGINE_PDP_URL=http://127.0.0.1:18080
export SECRETS_ENGINE_PDP_TOKEN_FILE="$PDP_TOKEN"
export SECRETS_ENGINE_AUTHORIZATION_POLICY_PACKAGE=secrets-engine.catalog-lane.lifecycle
export SECRETS_ENGINE_AUTHORIZATION_POLICY_VERSION=v2

Shred the token file and stop the forward when the session ends. The token is ten minutes; it is a caller credential, not an authorization.

ServiceAccount secrets-engine/secrets-engine has automountServiceAccountToken: false and no role bindings — it exists to be a caller identity and nothing else.

Pin v2, never v1

v1 shipped and was deployed with no input.tenant rule at all; a rotate under tenant:coulomb returned allow. v2 supersedes rather than amends it so the change is visible in the version string, and this engine refuses a v1 decision outright. See docs/tenant-alignment.md.

The digest join, and why it is not a digest comparison

Proved live on 2026-09-07, fixed the same day.

The evaluator normalizes before hashing: the request tenant is copied onto subject and resource, and a registry hit copies type, tenant and selected attributes onto the refs. So binding.request_digest is over material we did not send and cannot reproduce, and the validator's original byte-equality check against our unenriched request rejected every real allow.

flex-auth's canonical-request-digest.md already published the consumer rule, and the fix follows it rather than inventing one:

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.

validate_decision_envelope now does exactly that:

• Structured correspondence. Everything we proposed — tenant, action, context, subject.id/type, resource.id/type/system and every attribute we sent — must survive unchanged in the binding.
• Enrichment only where the contract permits it. A ref may gain type, tenant and attributes; any other added field is refused. An enriched tenant must be the request's tenant, so a cross-tenant binding cannot arrive wearing our request's clothes.
• Digest self-consistency. request_digest is recomputed over the normalized tuple the binding carries, per the contract's own instruction. It is still checked — just for coherence of the binding rather than against material we never sent.

The lesson worth keeping: the replay fixtures could not catch this, because _request_from() rebuilds the request from the binding, so the tests hashed the evaluator's output and compared it to the evaluator's output. Only a real request through this access path exposed it.