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

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

As of source `ff1a13d` (2026-10-16), this consumer requires the producer's
detached Ed25519 signature using independently admitted local keys and exact
signed evaluator/mode/policy pin. The complete CLI wheel-plus-helper bundle and
strict task handoff are implemented in source. Native signer custody, key/pin
admission, installed placement and actual consumer receipts remain unaccepted;
source enforcement does not establish those facts. See
[the scoped native preparation](proposals/native-cli-admission/README.md).

Historical 2026-10-12 finding: prior consumer source did not verify producer
signatures, so a forger could reproduce public request digests. The literal
loopback address restriction limited the destination and did not prove responder
identity. That source defect is repaired; FLEX-DEC-2026-010's historical warning that an absent
PDP and a lying responder require different controls remains relevant. The
independently admitted native trust and rollout obligations in SECRETS-WP-0014 T02/T03 remain open.

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.

## Historical transport procedure and current admission gate

The following transport example records the earlier supported access shape; it
is incomplete for current native use without independently admitted signing trust,
the reviewed CLI bundle and exact owner configuration. It grants no token mint,
installation or live action. 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.

```bash
# 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. Current consumer configuration and signed
trust must explicitly pin the admitted v2 artifact; the validator does not impose
a universal hard-coded package/version default. A v1 configuration is not admitted
by this proposal. 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.

The bullets in earlier revisions described the September structured-enrichment
check. Current source has since moved to the producer's submitted-request replay
contract: `validate_decision_envelope` validates the exact submitted digest,
opaque enriched digest shape, approval-free correspondence, policy pin and
lifetime on an authenticated envelope. It does not independently reconstruct the
full enriched tuple or native five-field claim in the generic CLI path.

The separate strict `task_execution_handoff` additionally recomputes the evaluated
and approval-free digests, verifies exact descriptor/context/native claim joins
(including the served native digest), and binds signed enforced caller provenance.
That source seam is not an `execute-ccr` CLI command and does not admit the proposed
service caller mapping or enable either task policy's runtime false gate.

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.

## Mandatory responder authentication (WP14 source preparation)

Every serving `authorize_action` path requires `SECRETS_ENGINE_PDP_TRUST_FILE`
and `SECRETS_ENGINE_PDP_VERIFIER`. These fail closed before approval/PDP credential
access when a PDP path is configured. Trust must be an absolute regular JSON file,
not group/world writable, admitted independently of the responder or its keys
endpoint. Neither a loopback URL nor installing source admits production keys.
See `verifier/README.md` for build, source pin/update and installation requirements.

Trust schema `secrets-engine.pdp-trust.v1` requires exactly `schema`, `evaluator`,
`mode`, `policy_package`, `policy_version`, `policy_package_digest`, and `keys`
(a map of signer kid to base64url-unpadded Ed25519 public key). The producer has
no separate issuer or instance identifier: issuer binding is the admitted signer
plus signed provenance evaluator/mode; the exact policy coordinate and artifact
digest identify the admitted pin. Deployment key custody must scope the signer to
that responder; shared signing keys cannot prove a distinct pod identity.

Rotation is an explicit reviewed admission update: admit old/new keys for a bounded
overlap, switch producer signer, verify the actual consumer, then remove the old
kid and prove refusal. Keys are reloaded each call; no endpoint discovery, cached
key fallback, unsigned exception, or automatic admission exists. These source
checks do not constitute Platform key admission or native rollout acceptance.