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](tenant-claim-contract.md) 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.