key-cape/docs/approval-engine-auth-contract.md

Approval-engine token contract

Static client registrations may set audience: approval-engine. This selects only the access-token audience; OIDC ID tokens retain aud=clientId. Omitting audience preserves the existing client-ID access audience, including OpenBao consumers. Request audience and resource parameters cannot override it. Access tokens contain the granted scope string for both supported grant types.

config/service-clients.example.yaml provides the two requested confidential clients: secrets-engine-approval gets read/consume, and approval-engine-operator gets lifecycle/observation scopes without consume. Service tokens contain principal_type=service, tenant, roles, scope, assurance, issuer, subject, audience, issue time and expiry; the lifetime is 15 minutes. The issuer signs with RS256 and publishes its public key through /jwks.

Human approvers use the informed-decision-approver registration, submitted by informed-decision on 2026-09-10 (INFD-WP-0001-T07) and published in config/service-clients.example.yaml:

Field	Value
clientId	informed-decision-approver
redirectUris	https://decisions.coulomb.social/auth/callback (exact, sole)
clientType	public — PKCE is the whole proof; no secret
grantTypes	authorization_code with S256 PKCE
audience	approval-engine
allowedScopes	openid, approval:read, approval:approve
mfaRequired	true
tenant	tenant:platform, declared

The host is decisions.coulomb.social, not the decide.coulomb.social an earlier draft proposed; the origin was verified live before submission. The path currently serves a placeholder while the surface is gated on APPROVAL-WP-0002-T01, which does not affect the registration — the redirect is matched as an exact string at /authorize and never fetched.

Do not add consume or other approval grants to that client. The ID token is for the login client; present the access token to approval-engine. TestApproverRegistrationShapeIsExact pins every field above, so widening a scope or relaxing the MFA requirement fails the build rather than passing as an edit.

That client must also declare tenant: tenant:platform. A human token's tenant comes from the directory record, which assigns none today, so without the declaration the token would carry tenant:coulomb and be refused here. See the tenant contract for the four resolution rules and for why a declared zone can never relabel a user the directory has placed.

approval:read is present because approval-engine showed the surface cannot render a decision without it: GET /v1/approvals/{id} and /claim both require it, so the earlier [openid, approval:approve] would have let an approver submit an entry they were never able to display. Reading through the owning component's own service identity would also work, but it weakens the one claim that surface exists to make — evidence of what this person was shown — so the read is granted to the human principal instead. approval:consume stays excluded: human principals are refused consume in approval-engine's code regardless, and consumption belongs to the PEP causing the side effect.

The assurance object

KeyCape emits assurance on every human token, unscoped. approval-engine stores it verbatim into the approval entry, where it is the only place mfaRequired: true survives into the record, so its shape is a contract:

Field	Type	Meaning
level	string	aal1 or aal2. aal2 exactly when MFA was verified in this authorization. The closest thing to acr.
methods	string[]	["pwd"], or ["pwd","otp"] when MFA was verified. The closest thing to amr.
mfa	bool	Whether MFA was verified. Redundant with level by construction, and kept because a consumer asserting on one should not have to know the mapping.
source	string	Always key-cape. Names which issuer made the assertion.
at	number	Unix seconds at which the user authenticated — not when the token was minted.

at is authentication time on purpose. A reused browser session can be hours old, and a record saying MFA happened at mint time would overstate how recently the person proved anything. Where an authorization rides an existing session, the original login instant is carried through.

The level is derived from what happened in this authorization, never from enrollment state: a user with MFA enrolled who was not challenged gets aal1. A consumer that needs a maximum age should compare at, not assume freshness.

These fragments are not live registrations. The two service registrations require custody-managed values for the named environment references and a reviewed rollout of this version, including the upstream issuer precondition. Platform's CCR-2026-0017/0018 use OpenBao field CLIENT_SECRET; their approval remains open. The human registration now carries its real UI-owned callback (above); a bearer-only approval resource server never owned that string, which is why it came from informed-decision. Service credentials still cannot be counted as human approval evidence. Never log the token or secret. Verify the resulting access token against the deployed issuer's /jwks, checking issuer, audience, expiry, subject, principal type, tenant, roles, scope and assurance. Verify that operator consume and human consume requests are rejected. Local tests verify signatures against the JWKS handler; they do not constitute live issuance proof.

Negative verification requires the token endpoint's typed refusal: HTTP 400, invalid_profile_usage, feature scope for excess scope; HTTP 401 with feature Authorization for a predecessor secret. A timeout, 5xx, malformed response, invalid signature or JWKS failure is not proof of denial.

KeyCape owns issuance and client grants/disablement. OpenBao and the deployment operator own credential custody; approval-engine enforces its resource policy.