approval-engine/docs/caller-authentication.md

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.

This check is store isolation, and it is not a statement about the person. It answers "does this caller belong to the store this engine serves", not "is this human a member of the platform zone". GH-DEC-2026-013 rules that a key-cape human tenant claim may be supplied by the client registration rather than asserted by the directory, and forbids a consumer treating the two as equivalent for a decision turning on a fact about the person. Exact string equality cannot see that difference — a string that matches exactly matches whoever asserted it — so the difference is stated here instead.

Consequences this engine accepts deliberately:

• A registration-supplied tenant is admissible for admission to this store. Admission means "arrived through a channel the platform registered", the approver client is static and deployment-owned, and dynamic client registration is excluded from key-cape by design.
• A registration-supplied tenant is not admissible for any doctrine that turns on the approver's own membership — "an approver must be a member of the platform zone" is a fact about the person, and this claim cannot carry it. No such doctrine exists today; if gate-house issues one, it needs a directory-sourced claim and this check does not become that claim by matching.
• Schema v6 records verified tenant_source on approver entries and issuance/use threshold evidence. KeyCape publishes directory, registration, or default. An absent claim remains null; an explicit malformed or unknown value is refused. Legacy entries remain null, never inferred from their subject or tenant. Provenance does not change store isolation or establish zone membership. The deployed schema-v5 image does not yet record this field.

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, evidence reference, principal type, and tenant source derive from the verified JWT, never the request body.

principal_type is recorded from verified identity (since schema v4). Schema v5 implements GH-DEC-2026-016: when an approval declares human_control: true, /entries refuses a service, agent or unknown principal with 403 before inserting an entry or emitting issuance. The request body cannot supply the approver type or downgrade the declaration. Undeclared approvals retain service-to-service use; a human entry does not retroactively declare a human control.

Requesting and binding are separate operations. POST /v1/approvals creates an unapproved request and records the strict boolean declaration. A service or agent with approval:create may draft that request. The principal contributing judgment is known only at POST /entries; this is the bind/issue boundary where GH-DEC-2026-016's non-human refusal applies. A draft is never a valid approval. No statement about the approver is inferred from binding.principal or the requesting actor's type. Dual control also needs its declared required_count; human control alone does not imply two approvers or decide which acts need it.

Identity provenance: reviewed KeyCape source f9812ab3b2bfe8f0817185f44071e612264ec3ee:src/internal/server/oidc/token.go sets principal_type=human only after consuming a client/redirect-bound PKCE session and looking up the current user. Its separate client-credentials path sets service; no registration field supplies a human principal type. This is different from registration-supplied tenant routing. Production acceptance must pin and prove that issuer behavior with a real human flow; signed fixtures here prove engine enforcement, not native identity admission. If an issuer introduces a registration-supplied route to human, GH-DEC-2026-016 §5 requires independent provenance and refusal of that route before admitting it. A consumer must not relax the identity contract simply because the JWT verifies.

Entries written before v4 stay null; pre-v5 objects have human_control: false. KeyCape owns client registration and scope grants; approval-engine 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.

KeyCape's OpenBao service-auth contract currently emits aud as the OAuth clientId. That pattern must not be reused here. Tokens presented to this API MUST have resource-server audience approval-engine. Requested non-secret client fragments are in docs/keycape-service-registrations.md.