tegwick
a73da29093
informed-decision and approval-engine both asked to hear problems with the human
approver registration now rather than at handover. Checking their requested shape
against the source rather than agreeing it on paper turned up three things.
Scope gap, accepted: [openid, approval:approve] cannot render a decision, since
GET /v1/approvals/{id} and /claim both need approval:read -- the surface could
submit an entry it was never able to display. Published
[openid, approval:read, approval:approve]. Reading through a service identity was
the alternative and is worse: it weakens the evidence-of-what-this-person-saw
claim the component exists to make. approval:consume stays excluded.
Assurance shape, published and a defect fixed. Both asked for a documented shape
and KeyCape already emitted one, so it is written down rather than renegotiated.
Writing it down surfaced that `at` was the token mint time rather than the
authentication time. Those differ by hours whenever a browser session is reused,
and approval-engine persists this object verbatim as the only downstream record
that MFA happened -- so a stored approval could have evidenced MFA at a moment
the person proved nothing. PKCESession.AuthTime now carries the original login
instant through session reuse, with mint time as the fallback.
Blocker found before anyone built on it: a human token cannot carry
tenant:platform. effectiveTenant resolves the human tenant from the directory
user, no adapter populates User.Tenant, and the per-client tenant field is read
only on the client_credentials path -- so every human token defaults to
tenant:coulomb, which approval-engine refuses by exact string equality. It would
have presented as a failed approval rather than a registration defect. Two
resolutions sent to the owners and neither implemented here: the choice decides
whether a human's tenant is a property of the person or of the registration, and
that is not KeyCape's alone to make.
Also recorded ops-warden's answers to KEY-WP-0014-T04, including their finding
that `warden plan` returns `autonomous` for a need containing generate and
CAS-write, because it has no read-versus-mutate intent. Their standing
instruction -- treat a warden plan verdict on any write, rotate or provision need
as unreliable until WARDEN-WP-0038 lands -- is recorded in the workplan rather
than left in an inbox.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uV8zoCKpA1WRAxsKRYbdH
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1182213@bnt-lap001
Assistant-Session: 966597b9-ae61-46a4-8b9e-1594ab3ec4ad
4.7 KiB
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 need a separate authorization-code/PKCE registration with an
exact deployment-owned callback, audience: approval-engine,
allowedScopes: [openid, approval:read, approval:approve], and
mfaRequired: true. Do not add consume or other approval grants to that client.
No callback is invented here. The ID token is for the login client; present the
access token to approval-engine.
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 separate human registration needs its actual UI-owned callback. A bearer-only
approval resource server has no such callback; its absence does not prevent
service-client issuance or service startup, and service credentials 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.