informed-decision/docs/keycape-client-registration.md

OIDC browser-client registration — informed-decision approver surface

Workplan task: INFD-WP-0001-T07 For: key-cape (KEY-WP-0013-T02, KEY-WP-0013-T05) Status: draft — not yet submitted. One input outstanding: the deployed origin (§2). Everything else is fixed and stable. Rulings: GH-DEC-2026-012, GH-DEC-2026-013 Contracts cited: key-cape/docs/approval-engine-auth-contract.md, key-cape/docs/tenant-claim-contract.md, approval-engine/docs/approver-surface-requirements.md

---

1. What this closes

On 2026-09-08 key-cape asked approval-engine for the human approver client's client_id and full callback URI. approval-engine correctly declined to invent them: it is a bearer-token resource server with no Ingress, no redirect endpoint, and no browser client. It recorded that the two strings belong to whichever browser-facing approver UI presents approval:approve tokens to it.

That component is this repository. These are the two strings.

---

2. The two strings

Field	Value
client_id	informed-decision-approver
Redirect URI	https://<origin>/auth/callback

client_id is fixed and stable. It will not change.

The origin is the one outstanding input. Redirects match exactly at /authorize, so a near-miss fails closed — which is precisely why approval-engine refused to guess and why this document is not yet submitted.

• Proposed: decide.coulomb.social, giving https://decide.coulomb.social/auth/callback.
• Consistent with the estate's existing pattern (forgejo.coulomb.social, hub.coulomb.social, kc.coulomb.social), Traefik ingressClassName, TLS secret per host.
• Requires, in railiance-apps rather than here: a DNS A record for decide.coulomb.social, an Ingress manifest, and a certificate.

This document is submitted to key-cape when that origin resolves — not before. The path component /auth/callback is fixed now so only the host remains variable.

---

3. Client shape

Property	Value
Grant	Authorization code
PKCE	Required, S256
Client type	Public
Redirect matching	Exact
Scopes	openid, approval:read, approval:approve
mfaRequired	true

approval:read is required and was missing from the original specification. Without it this surface could submit an approval entry it was never able to display — raised by approval-engine, confirmed by key-cape, now in their published contract.

approval:consume is never requested. approval-engine refuses it for human principals, and consumption belongs to the PEP that causes the side effect (GH-DEC-2026-003).

---

4. Expected access token

Verified by approval-engine (RS256 against the issuer's /jwks):

Claim	Value
aud	approval-engine — the resource server, never the OAuth client id
tenant	tenant:platform — exact string equality, no alias or prefix handling
principal_type	human
sub	non-empty; becomes the approver identity in the entry
scope	non-empty, containing the exact scope for the route
assurance	a non-null JSON object — shape below
iss, exp, iat	verified, 30s leeway

The access token is the evidence. id_token is never presented to approval-engine and appears nowhere in that codebase.

assurance

The shape is key-cape's, defined in their docs/approval-engine-auth-contract.md — level (aal1|aal2), methods, mfa, source, at. Cited here rather than restated, so it cannot drift.

Two properties matter to this surface and are recorded rather than assumed:

• at is the authentication time, not the token mint time. key-cape fixed a defect here on 2026-09-09; the two differ by hours when a browser session is reused, and approval-engine stores this object verbatim as the only downstream record that MFA happened. Freshness is judged by comparing at, never by assuming it.
• key-cape emits assurance on every human token and never empty. This surface nevertheless requires the object to carry authentication facts rather than relying on it always arriving populated — approval-engine accepts an empty object, so an empty one would produce an entry evidencing nothing.

---

5. Tenant provenance — declared, not assumed

This registration declares a tenant the directory record does not carry, and says so here rather than letting it read as a directory-asserted fact.

GH-DEC-2026-013 ruled directory-sourced tenancy the terminal state and granted key-cape's registration-bound shape (329e48f) as a declared bounded gap — admissible because its distinguishing case fails closed: registration and directory disagreeing refuses issuance with 403 tenant_binding rather than relabelling.

Nothing populates domain.User.Tenant for approver users. So a registration declaring tenant:platform reaches the token by the gap route by construction, not by accident. Gate House was explicit: do not declare a tenant the directory does not carry unless prepared to say so in the record.

Consequences accepted here:

1. This is transitional. When the directory carries tenants, the same key-cape code stops supplying and starts enforcing agreement, with no second migration. This registration is expected to survive that unchanged.
2. The claim is stored with its provenance. key-cape emits tenant as a bare string, so a consumer cannot distinguish a directory-asserted tenant from a registration-supplied one. Until the claim carries its own provenance (GH-DEC-2026-013 §5, second field deliberately undesigned), this surface records which route the value arrived by. See PR-09.
3. The tenant claim is never used as the act-scope. binding.target is the act-scope and is committed inside view_hash. Two different facts — which scope this act enters, and which tenant this person belongs to — must not share one field here just because they share one upstream. See EvidenceModel.md §8c and PR-08.

---

6. What this surface does with the token

• GET /v1/approvals/{id} and /claim — approval:read, to render.
• POST /v1/approvals/{id}/entries — approval:approve, to record a binding.
• Never /consume.
• Never any path containing check or ending /authorize — they 404 by design, and there is no "may this person approve" surface to call.

A 200 from approval-engine is not entitlement to view. A decision is obtained from access-engine before an approval is rendered to a person (PR-05) — noting that decision attributability is a declared open gap (GH-DEC-2026-010, FLEX-WP-0024) and this path is not described as validated while it stands.

---

7. Outstanding

#	Item	Owner
1	DNS A record + Ingress + TLS for the chosen origin	railiance-apps / deployment
2	Submit this document to key-cape, closing KEY-WP-0013-T02	this repo, once 1 lands
3	Prove a token issued against the registration is accepted by approval-engine	T08