approval-engine/docs/approver-surface-requirements.md

Requirements on the approver surface (informed-decision)

Status: issued by approval-engine 2026-09-09, against APPROVAL-WP-0002-T01. Addressed to informed-decision (INFD-WP-0001), copied to key-cape (KEY-WP-0013-T02).

informed-decision has claimed the browser-facing approver surface that docs/keycape-service-registrations.md named as an unassigned dependency on 2026-09-08. This file states what this engine requires of that surface, and — more usefully — the three places where the current contract does not yet fit and someone has to decide rather than guess.

This engine owns the approval object and its lifecycle. It does not decide whether an actor may approve (access-engine), does not author approval doctrine (gate-house), and does not authenticate anyone (key-cape). Nothing below asks informed-decision to take on any of those either.

1. The surface we actually expose

There are exactly two routes an approver surface needs, and one it must never call:

Route	Method	Scope	Purpose
/v1/approvals/{id}	GET	approval:read	fetch the approval object to render
/v1/approvals/{id}/claim	GET	approval:read	fetch the published claim
/v1/approvals/{id}/entries	POST	approval:approve	record one approver's entry
/v1/approvals/{id}/consume	POST	approval:consume	never — service/agent principals only, refused in code for principal_type: human

approval_engine/api.py rejects any path containing check or ending in /authorize with 404 on purpose. There is no "may this person approve" surface here and there will not be one.

2. Hard requirements on the access token

The token presented as Authorization: Bearer on every call must verify against the deployed issuer's /jwks (RS256) and carry:

• aud — exactly approval-engine (the resource server, never the OAuth client id)
• tenant — exactly tenant:platform, compared with exact string equality against the store tenant before any object lookup (approval_engine/api.py:66). No alias, no normalisation, no prefix handling. platform and tenant:coulomb are refused (tests/test_auth.py::test_near_miss_tenant_spellings_are_forbidden).
• principal_type — human for an approver. service and agent are the only values accepted at /consume; human is refused there.
• sub — non-empty; this becomes the approver's identity in the entry. It is the only thing that identifies the approver: see §5.
• scope — non-empty, and containing the exact scope for the route.
• assurance — a JSON object, and non-null. See §4.
• iss, exp, iat — verified, 30s leeway.
• roles — may be empty, but the claim must be present and well-formed.

The access token is what we validate. id_token appears nowhere in this codebase; the ID token belongs to the login client and is never evidence here.

Correction to our 2026-09-09 message. We said an agent token cannot hold approval:approve under the requested registrations. That is wrong twice: the approval-engine-operator service client holds approval:approve, and this engine does not restrict /entries by principal type at all — only /consume is restricted, to service/agent. So a non-human principal can supply approver evidence today.

Whether it should be able to is approval doctrine and belongs to gate-house, not to us and not to you. What we have done instead is make it visible: schema v4 records the verified principal_type on every entry (tests/test_auth.py::test_entry_records_the_verified_principal_type, ::test_non_human_approver_is_recorded_as_such). Your design principle 10 ("humans bind, agents draft") is therefore enforceable in the evidence chain rather than assumed — read entries[].principal_type and do not infer the answer from the shape of subject_id. Entries written before v4 are null and must not be read as human.

3. Open question A — the human client cannot read the approval it renders

key-cape specified the human client as allowedScopes exactly [openid, approval:approve], with every other approval grant deliberately excluded. But rendering a decision memo requires GET /v1/approvals/{id}, which requires approval:read. As specified, the approver surface can submit an entry it was never able to display.

Two ways out, and this engine does not get to pick:

1. Add approval:read to the human client. Simplest, and keeps the read attributable to the human who saw it — which matters, because informed-decision's whole thesis is evidence of what this person was shown. A read performed under a different identity weakens that.
2. Read through a confidential service client owned by informed-decision (backend-for-frontend), with the human token used only for the entry.

If (2) is chosen, note the trap explicitly: this engine answering 200 to a service client is not a statement that the human on the other side is entitled to see that approval. approval-engine never answers "may this actor do X". Under (2), informed-decision owes an access-engine check before rendering; under (1) it still owes one, but at least the read is not impersonated. We recommend (1).

This needs a key-cape decision, since it changes the registration they have already implemented.

4. Open question B — assurance is what we record, so it must mean something

add_entry persists the verified assurance claim verbatim (approval_engine/api.py, store.add_entry), serialized as sorted JSON. This engine validates only that it is an object; it does not interpret the contents.

That makes assurance the single place where "this approval was bound under MFA" survives into the approval record. key-cape specified mfaRequired: true on the human client — the requirement here is that the resulting token's assurance object actually carries that fact in a stable, documented shape (authentication method, acr/amr, auth_time at minimum), rather than leaving MFA as a property of the login that nothing downstream can see.

informed-decision and key-cape own that shape between them. To be exact about what this engine does and does not do: an empty assurance object ({}) is accepted — validation checks only that the claim is present and is an object. So an empty assurance is not refused here; it simply produces an entry that evidences nothing about how the person authenticated. If MFA has to be provable from the approval record, the shape has to carry it, because nothing downstream reconstructs it.

5. Open question C — view_hash has nowhere to go today

POST /v1/approvals/{id}/entries reads the request body and discards it. Approver identity, assurance and evidence_ref come only from the verified token; evidence_ref is jwt-sha256:<digest of the presented token>. This is deliberate — an API-supplied approver field is provenance, not evidence — but it means informed-decision's view_hash cannot currently ride into the approval entry.

For v1 the workable arrangement, requiring no change here:

• informed-decision holds the presentation record and computes view_hash / awareness_hash;
• it emits that record to audit-core as its own evidence;
• correlation to the approval entry is by (approval_id, subject, approved_at), all three of which this engine returns in the object after a successful entry.

If the estate decides the binding must be inside the approval object — that an entry is not admissible without the hash of the view that produced it — that is a real change request against this engine (an optional, verified-alongside-token view_hash on the entry), and it is doctrine, so it goes to gate-house before it goes to us. We are not going to add an unauthenticated free-text field to the one record that currently contains no caller-supplied data.

6. There is no inbox endpoint, by construction

This engine exposes get-by-id only. There is no GET /v1/approvals list, no search, and no "approvals awaiting me" query. An approvals inbox is named twice in this repo's INTENT.md Non-Goals.

So informed-decision must receive approval ids from whatever requested the approval (or from gate-house doctrine), not by polling this engine. If a listing surface is genuinely needed, raise it as a change request — but note that "which approvals may this person see" is an authorization question, so any such endpoint would have to be scoped by something other than this engine's own judgment.

7. Behaviour the surface must handle

Map these to the disposition vocabulary rather than swallowing them:

Status	Reason code	Means
401	unauthenticated	missing/expired/unverifiable token — re-auth, never retry blindly
403	forbidden	wrong scope, wrong tenant, or human principal at /consume
404	not_found	no such approval in this tenant's store
409	duplicate_approver	this subject already has an entry — the person is done, not failed
409	conflict	approval is in a terminal status (revoked, superseded, consumed, expired) — cannot add entries
422	unprocessable	malformed request
503	store_unavailable	store down; fail closed, do not present success

duplicate_approver deserves particular care: a double-submit from a browser is routine, and rendering it as an error is a lie. The first entry stands.

An entry that satisfies required_count flips the approval to approved in the same transaction; the response body is the updated object. Read the status from the response rather than inferring it from the fact that the POST returned 200.

The engine never returns a decision. _assert_not_decision actively refuses to serialize one. approved is a state of an object, not permission to act; the permission question is access-engine's. A surface that renders "approved" as "you may now do the thing" has re-implemented a PDP in the browser.

8. What we need back, and what we do not

We need nothing from informed-decision to unblock our own work — T01's repository half is complete. What key-cape needs, and what only informed-decision can now supply, is the pair it asked for on 2026-09-08:

1. the exact client_id string, and
2. the full callback URI, scheme and path included.

Redirects are matched exactly at /authorize, so a near-miss fails closed. Those two strings are informed-decision's to choose and, once chosen, to keep stable — they are deployment inputs, not implementation details, and changing one silently breaks the login rather than degrading it.

We do not need to review the UI, the disposition vocabulary, or the memo schema. return, discuss, escalate and the rest are dispositions of a memo; this engine models only entries against an approval object and knows nothing of them. That separation is correct and we would rather it stayed that way — but it means a memo return must not be represented here as anything at all, and a memo accept is the only disposition that becomes a POST …/entries.