# flex-auth caller identity contract

Status: source implemented; production promotion pending.

user-engine calls `flex-auth-user-engine` with a projected Kubernetes
ServiceAccount token whose audience is exactly `flex-auth`. The adapter reads
the token file for every decision so hourly projection rotation requires no
restart. A missing, empty or unreadable file fails closed as an authorization
denial; the token value is never logged.

flex-auth binds protected system `user-engine` to principal
`system:serviceaccount:user-engine:user-engine`. The token authenticates the
calling workload only. It does not replace the IAM actor/tenant/assurance facts
inside the authorization request and grants no Kubernetes API permission to
user-engine.

Runtime configuration requires `USER_ENGINE_FLEX_AUTH_TOKEN_FILE`. Local
construction keeps the adapter argument optional so unit tests and explicit
non-production adapters remain usable.

The tenant authority seam is distinct: user-engine identifies itself as actor
`user-engine` on tenant lifecycle reads and writes; tenant-engine performs its
own flex-auth decision before store access. Tenant ids remain opaque and are
URL-encoded. No client may infer existence from an unauthorized read.

The current deployed image predates this file-based caller token. Promote only
with the matching flex-auth A2 image and bindings; otherwise enforcing flex-auth
will correctly return 401 to the old caller.