docs: operator caller access path, and the caller is absent from the record

glas-harness asked for a supported owner access path with authenticated
caller binding and lifetime, ruling out Service DNS and a permanent
operator token. Both refusals are correct and the answer needs no new
mechanism: a TokenRequest token is short-lived, audience-scoped, and
bound by exact sub to the ServiceAccount the deployed pin already names.

Two findings came out of designing it.

First, for an operator caller the pin's NetworkPolicy is not a partial
control, it is silent: kubectl port-forward is proxied to the pod's own
loopback and no policy selector is consulted. So under warn the operator
path is unauthenticated and unfiltered, and the only reason it is not
reachable is that nobody has forwarded the port. warn was safe for
ops-warden because a workload pin still admitted one pod; here the warn
window protects nothing while it runs. enforce is the deliverable.

Second, the ServiceAccount named by the deployed binding does not exist.
Namespace secrets-engine holds only default, so enforce today would deny
every request rather than authenticate one.

Third, and this is the contract one: the decision record has no caller
field. provenance carries evaluator, mode, policy and registry digests
and decision time; binding carries the normalized request. So the four
negative tests can all pass and no artifact retains that they passed for
the request that mattered. Same seam as FLEX-DEC-2026-008 one layer up —
there a tenant was carried into the digest and never compared, visible
but not enforced; here a caller is authenticated and never recorded,
enforced but not visible.

provenance.caller, not binding.caller: the same request from a different
authenticated caller must decide identically, so the caller is not
replay identity and must not move request_digest. FLEX-DEC-2026-009.

Live receipts are not included. kubectl create token is credential
minting and was refused in this session, correctly; the commands are
exact and the expectations read out of internal/callerauth/auth.go, but
nothing is claimed as verified that was not run.

Also records the operator's tenant:platform decision
(5ed3fb35-eca9-413a-82b9-95171ba85bf6) and verifies that v2 already
enforces exactly it — exact string equality, no alias, no normalisation.

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

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 715613@bnt-lap001
Assistant-Session: fabd95c1-4c9e-4080-8849-8707ae025f80

docs/operator-caller-access-path.md

@@ -0,0 +1,134 @@
+# Operator caller access path
+
+**Status:** design published, live receipts outstanding
+**Opened by:** `glas-harness` (`GLAS-WP-0015`, 2026-09-06), carried by `FLEX-WP-0023`
+**Supersedes:** the workload assumption in `FLEX-WP-0021-T04`
+
+`secrets-engine` is an operator CLI, not a Kubernetes workload. Every existing
+flex-auth pin assumes a workload: default-deny ingress admitting one pod
+selector, and a `--caller-binding` naming that pod's ServiceAccount. Neither
+half transfers unexamined, and `glas-harness` ruled out the two shortcuts by
+name — **Service DNS is not connectivity, and a permanent operator token is not
+an identity**. Both refusals are correct.
+
+## The two gates are not one gate
+
+`FLEX-WP-0021-T04` noted that `callerAuth` "becomes the real boundary" for an
+operator path. That was understated. For this path the network gate provides
+**no protection at all**, and it is worth being exact about why.
+
+`kubectl port-forward` does not traverse a `NetworkPolicy`. The connection is
+proxied through the API server to the kubelet and delivered on the pod's own
+loopback interface, so it never appears as pod-to-pod ingress and no policy
+selector is consulted. The pin's default-deny `NetworkPolicy` is therefore not
+a partial control for an operator caller — it is silent.
+
+So the honest statement of the current posture is stronger than "warn mode":
+
+> With `callerAuth.mode: warn` and a port-forwarded connection, the operator
+> path to the `secrets-engine` pin is **unauthenticated and unfiltered**. The
+> only reason it is not reachable today is that nobody has forwarded the port.
+
+That is not a supported access path. It is the absence of one.
+
+## The supported path
+
+Kubernetes already issues exactly the credential shape being asked for, and
+flex-auth already accepts it. Nothing needs inventing and no code changes.
+
+```bash
+# short-lived, audience-scoped, cluster-issued, bound to one ServiceAccount
+kubectl -n secrets-engine create token secrets-engine \
+  --audience=flex-auth \
+  --duration=10m
+```
+
+The `TokenRequest` API mints a token for a ServiceAccount **without a pod**.
+Checked against what the deployed pin actually requires:
+
+| Requirement | How this satisfies it |
+| --- | --- |
+| authenticated | `TokenReview` validates signature, audience, and expiry server-side |
+| bound to one system | token `sub` is `system:serviceaccount:secrets-engine:secrets-engine`, matched against `--caller-binding` by exact string |
+| stated lifetime | `--duration`; the token carries `exp` and `TokenReview` refuses it after |
+| not a permanent operator token | expires on its own; the operator stores no long-lived secret |
+| audience-scoped | `--audience=flex-auth` matches the pin's `--caller-audience` default; a token minted for any other audience fails |
+
+The deployed pin already names the identity:
+
+```text
+--caller-binding secrets-engine=system:serviceaccount:secrets-engine:secrets-engine
+--caller-audience flex-auth   (default)
+```
+
+## Two blockers, one of them load-bearing
+
+**1. The ServiceAccount named by the binding does not exist.** Namespace
+`secrets-engine` was created under `FLEX-WP-0021-T04` with no workload and no
+identity; it holds only `default`. So there is nothing to mint a token *for*,
+and flipping to `enforce` today would deny every request rather than
+authenticate one. Creating it is a one-object production write, and an SA with
+no `RoleBinding` grants nothing in the cluster — its only function is to be the
+name in the binding above.
+
+**2. `warn` cannot be the mode for this path.** For a workload, `warn` is a safe
+migration state because the `NetworkPolicy` still admits only one pod. For an
+operator caller the policy is silent, so `warn` means *no* control. The
+migration order that applied to `ops-warden` (`FLEX-WP-0016`: adopt identity,
+clean warn logs, then enforce) still applies, but the warn window here is a
+window with nothing in it — it proves the token works and protects nothing while
+it runs. **Keep it short and treat `enforce` as the deliverable, not the
+follow-up.**
+
+## Positive and negative tests
+
+Run against the pin through a port-forward, then remove the forward.
+
+```bash
+kubectl -n flex-auth port-forward svc/flex-auth-secrets-engine 8080:8080 &
+
+# positive — correct identity, correct audience, inside lifetime
+TOKEN=$(kubectl -n secrets-engine create token secrets-engine --audience=flex-auth --duration=10m)
+curl -s -X POST localhost:8080/v1/check -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d @examples/secrets-engine/check_request_allow_rotate.json
+# expect: 200, effect allow, reason catalog_lane_policy_matched, policy_version v2
+```
+
+Four negatives, each isolating one property. Under `enforce` all four must be
+refused before the request reaches policy; under `warn` all four are *allowed*,
+which is the finding rather than a passing test.
+
+| # | Credential | Expected under `enforce` |
+| --- | --- | --- |
+| N1 | no `Authorization` header | 401 — `ErrUnauthenticated` |
+| N2 | token for `secrets-engine:default` (wrong SA, right audience) | 403 — principal cannot represent system |
+| N3 | token minted without `--audience=flex-auth` | 401 — audience not in token |
+| N4 | token past `exp` (mint `--duration=10m`, use after) | 401 — `TokenReview` refuses |
+
+N2 and N4 are the two that matter. N2 proves the binding is a binding and not
+mere presence of a valid cluster token — any of thousands of ServiceAccounts
+could produce a well-formed token, and only one may represent `secrets-engine`.
+N4 proves the lifetime is enforced by the issuer rather than asserted by the
+caller.
+
+**These receipts are not in this document because this session could not mint
+tokens.** `kubectl create token` is credential issuance and was refused here, as
+it should be. The commands above are exact and the expectations are derived from
+`internal/callerauth/auth.go`, not guessed; running them is an operator action.
+Nothing below the design line is claimed as verified.
+
+## What the record will not show
+
+Even with all four negatives passing, **the decision record does not say who
+called.** `flex-auth.decision-record.v1` has no caller field: `provenance`
+carries the evaluator, mode, policy and registry digests, and decision time, and
+`binding` carries the normalized request. The authenticated caller principal —
+the thing these tests are about — appears nowhere in the artifact.
+
+So a decision record proves the *subject* was allowed. It cannot prove the
+*caller* who obtained it was authenticated, or under what lifetime. For
+`glas-harness`, whose ask is a scoped delivery receipt, that is the difference
+between "this decision permits the action" and "this caller was permitted to
+obtain this decision". Recorded as `FLEX-DEC-2026-009`; it is a gap in
+flex-auth's own §17 contract, not in the deployment.