Implement approval engine production readiness

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a05e2e-805b-7042-a750-71f473bceea2

docs/caller-authentication.md

@@ -0,0 +1,34 @@
+# Caller authentication
+
+Production accepts only RS256 JWTs verified against KeyCape JWKS with the exact
+configured issuer and `approval-engine` audience. `exp`, `iat`, `sub`,
+`principal_type`, `tenant`, `roles`, `scope`, and `assurance` are mandatory.
+Missing or unverifiable credentials fail closed. The development static-token
+mode is explicit, file-backed, and refused with `--production`.
+The verified `tenant` must exactly match the service's configured store tenant;
+cross-tenant reads and mutations are rejected before object lookup.
+
+| Route | Required scope |
+|---|---|
+| create approval | `approval:create` |
+| get approval or claim | `approval:read` |
+| add approval entry | `approval:approve` |
+| revoke | `approval:revoke` |
+| supersede | `approval:supersede` |
+| consume | `approval:consume` and service/agent principal |
+| cadence, outbox, storage | `approval:observe` |
+| explicit heartbeat | `approval:emit` |
+
+Create additionally requires `binding.actor == sub`. Approval-entry subject,
+assurance, and evidence reference are derived from the verified JWT, never the
+request body. KeyCape owns client registration and scope grants; approval-engine
+only verifies and enforces them. Requested registrations are:
+
+- audience/resource server `approval-engine` with the scopes above;
+- the secrets-engine PEP service client with `approval:read` and
+  `approval:consume`;
+- separately governed lifecycle/operator clients with only their needed
+  mutation or observation scopes.
+
+Client credentials belong in OpenBao/operator custody and must not be placed in
+manifests, logs, State Hub, or this repository.