flex-auth/workplans/FLEX-WP-0023-operator-caller-access-path.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	related_workplans	created	updated	state_hub_workstream_id
FLEX-WP-0023	workplan	Operator caller access path and caller identity in the decision record	infotech	flex-auth	active	claude	netkingdom	P1	230	FLEX-WP-0021	FLEX-WP-0016 SECRETS-WP-0009	2026-09-06	2026-09-06	ad011f92-786c-51ad-b3f6-c06ad77e7af7

FLEX-WP-0023 — Operator caller access path and caller identity in the decision record

Opened by glas-harness (GLAS-WP-0015, 2026-09-06), which asked flex-auth to keep the access-path gate live work despite FLEX-WP-0021-T05 closing, and to return "a supported owner access path and authenticated caller binding/lifetime with positive and negative tests". They ruled out Service DNS and a permanent operator token by name. Both refusals are correct.

Design: ../docs/operator-caller-access-path.md. Contract gap: FLEX-DEC-2026-009.

The finding that reframes the task

For an operator caller the pin's default-deny 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 with callerAuth.mode: warn, the operator path is unauthenticated and unfiltered, and the only reason it is not reachable today is that nobody has forwarded the port.

warn was a safe migration state for ops-warden because a workload pin still admitted exactly one pod. Here the warn window protects nothing while it runs. enforce is the deliverable, not the follow-up.

1. Create the ServiceAccount the deployed binding already names

id: FLEX-WP-0023-T01
status: done
priority: high
state_hub_task_id: "10e5a40c-f142-55b9-ab15-fc77c0064ce0"

Owner: flex-auth; production write, operator approval required.

The pin runs with --caller-binding secrets-engine=system:serviceaccount:secrets-engine:secrets-engine and namespace secrets-engine holds only default. There is nothing to mint a token for, and enforce today would deny every request rather than authenticate one.

• Create ServiceAccount secrets-engine in namespace secrets-engine.
• No Role, no RoleBinding, no automountServiceAccountToken. An SA with no binding grants nothing in the cluster; its only function is to be the name in the binding above.
• Add it to the overlay rather than applying it loose, following deploy/caller-auth-rbac.yaml.

Gate: kubectl -n secrets-engine create token secrets-engine --audience=flex-auth --duration=10m returns a token whose sub equals the bound principal exactly.

2. Run the positive and negative tests and return the receipts

id: FLEX-WP-0023-T02
status: done
priority: high
state_hub_task_id: "79a8d82d-777c-5462-b49d-098f4b7a3b9c"

Owner: flex-auth to run; glas-harness to receive.

Procedure and expectations are in the design doc. One positive (correct SA, correct audience, inside lifetime, expecting allow at policy_version: v2) and four negatives, each isolating one property:

#	Credential	Expected under enforce
N1	no Authorization header	401
N2	token for secrets-engine:default	403, principal cannot represent system
N3	token minted without --audience=flex-auth	401
N4	token past exp	401

N2 and N4 are the load-bearing ones. N2 proves the binding is a binding rather than mere possession of a valid cluster token — thousands of ServiceAccounts can produce a well-formed one and only one may represent secrets-engine. N4 proves the lifetime is enforced by the issuer rather than asserted by the caller.

Blocked on credential issuance, not on design. kubectl create token is credential minting and was refused in the 2026-09-06 session that wrote this plan, correctly. The commands are exact and the expectations are read out of internal/callerauth/auth.go; running them is an operator action. Under warn all four negatives are allowed, so running them before T03 records the finding rather than a passing test.

Gate: five receipts returned to glas-harness, each naming which property it isolates. Nothing is reported as verified that was not run.

3. Flip callerAuth.mode to enforce

id: FLEX-WP-0023-T03
status: done
priority: high
state_hub_task_id: "8117c9d8-6efa-5ccf-8ed4-4da2519c3de3"

Owner: flex-auth; deployment approval required.

• Flip only the flex-auth-secrets-engine pin. Do not roll the other three; they are pinned to their own digests so one change does not move another consumer (FLEX-WP-0016).
• Confirm the warn logs are clean for the adopted identity first, as FLEX-WP-0016 did for ops-warden — but keep the window short, per the finding above.
• Re-run T02's four negatives after the flip. Before it they document the gap; after it they are the test.

Gate: N1–N4 refused, positive still allowed, other three pins unchanged. glas-harness's standing instruction — do not turn warn into enforce before caller adoption is proved — is satisfied by T02, not bypassed by this task.

4. Record the authenticated caller in the decision record

id: FLEX-WP-0023-T04
status: todo
priority: high
state_hub_task_id: "c0e4f31a-cc42-5bd2-b938-d140ecd52e1a"

Owner: flex-auth.

FLEX-DEC-2026-009: the verification in T02/T03 is real and leaves no trace. flex-auth.decision-record.v1 has no caller field, so a record proves the subject was allowed and cannot prove the caller who obtained it was authenticated.

• Add provenance.caller — mode (required), principal, audience, not_after. Not binding: the caller is deliberately not decision material, and putting it there would change request_digest and break every consumer's replay join.
• mode is load-bearing. A principal recorded under warn was observed, not enforced, and a reader who cannot tell those apart reads an unverified string as verification. Under disabled, emit {"mode": "disabled"} — absence stated, following the pdp_digest precedent.
• Capture the reviewed token's exp for not_after. internal/callerauth.Identity carries only Username and Audiences, so the expiry is validated by TokenReview and then discarded. This is the one real code change.
• Update schemas/decision_envelope.schema.json and docs/decision-record-contract.md; state in both that request_digest is unaffected, so nobody re-pins in response.

Gate: a decision obtained under enforce names its caller and lifetime; the same request's request_digest is byte-identical to the pre-change value.

5. Report the gap to gate-house as a v0.8 finding

id: FLEX-WP-0023-T05
status: wait
priority: medium
state_hub_task_id: "d685abfc-cf86-50c8-ad5e-2c04e1531ddd"

Owner: flex-auth.

§17 makes the decision-record schema flex-auth's, so this gap is ours to have missed — and the standard does not ask for what §9.7.2's own argument implies. §9.7.2 promoted registry-snapshot provenance to a conformance prerequisite because a decision turning on registry content must be replayable from its own record. A decision gated by caller authentication is not auditable from its own record by the same argument. Carry it into the outstanding v0.8 assent review rather than as a separate message.

Operator execution from Glas — 2026-09-06

Standing production authorization applied to this bounded owner procedure. Added deploy/secrets-engine-operator-caller.yaml and applied it after server validation: SA secrets-engine/secrets-engine, automount disabled, no role or role binding added. Ten-minute TokenRequest token has exact bound sub and flex-auth audience; token values remain only in proof-process memory.

Positive adoption passed under warn with zero authentication warnings. Helm lint/server dry-run passed; dedicated release upgraded to revision 3 with callerAuth.mode=enforce. Correct caller gets 200 allow v2; missing token 401, wrong principal 403, wrong audience 401. Expiry proof passed against an actually issued token: 401 after its exp plus 65 seconds, followed by a fresh-token 200 allow v2. Other three Deployment specs were compared and are unchanged. The temporary forward binds 127.0.0.1 and is removed when the proof finishes. Value-free receipts are in glas-harness: docs/evidence/GLAS-WP-0015-caller-auth-2026-09-06.json.

The initial proof reader assumed JSON error responses; the server correctly returns plain-text authentication failures. Corrected the temporary reader and reran the checks; this was a proof-harness failure, not a production code change.

T04 caller provenance and FLEX-WP-0024 signatures remain separate open work. An authenticated API-server port-forward authenticates the responder for this operator path; it does not produce a signed portable decision artifact.

Final receipt: T01–T03 complete; N4 expired-token 401 at epoch 1788730498, fresh-token positive 200 at 1788730499. Temporary forward closed and proof process exited, discarding its in-memory credentials. No port-forward remains as an implicit runtime dependency. T04 and T05 remain open; plan stays active.