# ADR 0001 — Broker confidential web-client registry

Status: accepted (2026-06-11)

## Context

The broker's `/oauth/authorize` endpoint was loopback-only (RFC 8252 §7.3),
built for native/CLI agents whose MCP SDKs spin up a localhost listener. A
deployed web application (the Universe Library reading room) has no loopback,
so the authorization-code redirect flow was a dead end for server-side apps.
The device flow works without a redirect but gives web users the TV-login
experience (tab hop, code entry, polling) — rejected as the primary web UX.

Every client was public/PKCE: `/oauth/authorize` treated `client_id` as
opaque, `/register` (RFC 7591 DCR) pins `token_endpoint_auth_method=none`,
and the token endpoint never checked a client secret.

The full decision trail lives in the demarkus-soul document
`/demarkus-library/adr/0004-broker-web-sso.md`; this ADR records the
broker-side mechanics.

## Decision

Add a registered **confidential web client** class alongside the existing
native path, as an explicit operator-curated registry — not open DCR.

- **Registry** — `webClients` in broker config: `clientID`, `clientSecretHash`
  (sha256-hex of the secret; plaintext never in config), `redirectURIs`
  (exact-match https allowlist), optional `name`. Validated at load: unique
  ids, 64-hex-char hash, ≥1 redirect, each redirect absolute https with no
  userinfo/fragment and no loopback host.
- **`/oauth/authorize`** — a registered `client_id` validates `redirect_uri`
  by exact match against its allowlist (no loopback exemption); an
  unregistered `client_id` keeps the loopback-only public path unchanged.
- **Token endpoint (`/device/token`)** — the `authorization_code` grant
  requires client authentication (HTTP Basic per RFC 6749 §2.3.1, or
  `client_secret_post`) when the presented `client_id` is registered. The
  secret is verified constant-time against the stored hash *before* the code
  is redeemed, so a failed authentication does not burn the code. Failure →
  `401 invalid_client` + `WWW-Authenticate: Basic`.
- **Refresh binding** — refresh tokens minted through a confidential exchange
  record the `clientID`; the `refresh_token` grant then requires the same
  client to authenticate. A leaked bound refresh token alone mints nothing.
  Tokens from the device flow and the loopback auth-code path stay unbound
  and refresh as before.
- **Discovery** — `token_endpoint_auth_methods_supported` advertises
  `["none","client_secret_basic","client_secret_post"]`.

## Notable choices

- **No `Confidential` flag in the auth-code store.** The plan called for
  stamping pending entries; it is redundant. `Redeem` already binds
  `client_id` constant-time and the registry is immutable for the process
  lifetime, so "entry's client_id is registered" is exactly "entry was issued
  confidential". The token handler's registry lookup of the presented
  client_id is therefore authoritative, and doing the secret check before
  `Redeem` preserves the store's keep-code-on-client-error retry semantics.
- **sha256, not bcrypt, for the secret hash.** The secret is
  operator-generated high-entropy randomness, not a human password — there is
  no low-entropy input for a fast hash to endanger, and it avoids a new
  direct dependency.
- **No per-client `scopes` field.** Scopes are declared-not-enforced
  broker-wide today; a per-client list would be dead config. Add it when
  scope enforcement exists.
- **PKCE stays required for confidential clients** — defense in depth; the
  authorize handler enforces S256 for both client classes.

## Consequences

- Native/CLI clients (Claude Code MCP SDK, demarkus-join) are untouched: no
  registry entry → identical behavior on every endpoint.
- The Universe Library (and future first-party web apps) can run standard
  redirect SSO against the broker with a deploy-time client registration.
- Operators must generate the client secret out of band and put only its
  sha256 into config; the chart needs a values surface for `webClients`
  (follow-up, not in this change).
- A client deregistered from config invalidates its bound refresh tokens at
  the refresh gate until re-registered or users re-authenticate.