informed-decision/docs/browser-authentication.md

# Browser authentication and Approval Engine transport

Implemented under `INFD-WP-0001-T08`. The service supplies sign-in and sign-out;
explicit owner configuration enables the protected memo and human-response
routes described in [protected-browser-review.md](protected-browser-review.md).

Install and exercise from the repository:

```sh
uv venv
uv pip install -e '.[dev]'
uv run python -m pytest -q
INFD_APPROVAL_ENGINE_SOURCE=/home/worsch/approval-engine uv run python -m pytest -q
uv run python tools/smoke_browser_shell.py
INFD_KEYCAPE_ISSUER=https://kc.coulomb.social uv run informed-decision-web
```

The component checks require the explicit Approval Engine source path. They use
its actual JWT verifier and API with locally signed synthetic identity fixtures.
They are not native human authentication or custody proof. The smoke script
needs free loopback port 8080, checks the installed entrypoint and stops it. It
never follows the authorization redirect or contacts KeyCape. `--receipt PATH`
writes metadata-only results.

The entrypoint listens on `127.0.0.1:8080` for a local reverse proxy. The public
origin/callback is fixed at `https://decisions.coulomb.social/auth/callback`;
Host, forwarded headers and return URLs cannot replace it. A development HTTP
listener does not replace this HTTPS callback registration. Deployment and
registration rollout remain pending. `/healthz` checks this process; `/readyz`
returns 503 without owner review configuration and recent audit delivery health.
Readiness is not a declaration of native policy/login/custody admission.

## Identity boundary

`KeyCapeLogin` uses a configured HTTPS issuer with its `/authorize`, `/token`
and `/jwks` endpoints. No discovery or JWT header can substitute an endpoint.
It requests only `openid approval:read approval:approve`, with public-client
S256 PKCE. State, a separate browser cookie and nonce are random; the callback
consumes its five-minute pending state before token exchange. The access token
never enters a browser cookie, HTML, URL or error message.

The verifier accepts RS256 only and checks both tokens against the issuer JWKS:
ID-token audience is the client, access-token audience is `approval-engine`.
Subject, tenant, provenance and assurance must agree. Nonce, time bounds, exact
scopes, human principal, platform tenant and the published KeyCape MFA facts are
required. JWKS refresh failure refuses login; expired cached keys are not a
fallback. Login does not decide entitlement to view or approve anything.

KeyCape source `f9812ab3b2bfe8f0817185f44071e612264ec3ee`, specifically
`src/internal/server/oidc/token.go`, is the provenance contract reviewed here:
the code handler looks up the authenticated user and emits `human`; client
credentials emit `service`. `tenant_source=directory` and `registration` stay
distinct. Unknown/default provenance is refused in this flow. A verified
registration-supplied tenant remains the bounded GH-DEC-2026-013 gap.

MFA `at` is preserved as authentication time. A successful login does not assert
that MFA meets an action-specific freshness policy; the policy integration must
use these facts for the action. No local approval verdict is inferred.

Sessions last at most fifteen minutes and never outlive either token. They are
bounded to 1,024 entries, protected by a process lock, rotated on sign-in and
deleted on sign-out/expiry. Restart requires reauthentication. This is a
single-process design; replicas need a separate shared-session design. These
sessions contain no approval current state or evidence. Cookies are Secure,
HttpOnly, SameSite=Lax with the `__Host-` prefix. Sign-out requires POST, the
exact origin and a session CSRF token. Responses prohibit caching and framing.
The proxy must omit callback query strings, bearer headers and cookies from
access logs. Waitress has no request-target access log enabled by this entrypoint.

## Approval transport boundary

`ApprovalHTTPClient` implements get-by-id and add-entry using the session's
access token. Each read reaches the engine. It requires exact
`binding.human_control=true` for this first factory integration and preserves
the native `sha256:<64 hex>` act digest. A pre-entry read rejects an undeclared
object before mutation. Identifiers cannot inject extra paths or query strings.

The default origin is HTTPS. The current in-cluster service can be wired with
explicit `allow_internal_http=True` and a fixed `.svc`/`.svc.cluster.local`
origin; that option also permits numeric loopback for component tests. Public
HTTP origins are refused. Redirects are never followed, response bodies are
limited to 256 KiB, and socket operations use a five-second timeout. No ambient
proxy credentials are inherited.

POST bodies are empty objects: Approval Engine derives identity and evidence
from its verified token and discards caller content. The adapter extracts
`(approval_id, subject_id, approved_at)` from the matching actual human entry,
never `updated_at` or local time. A `409 duplicate_approver` triggers a GET of
that original entry and returns `duplicate=True`. The controller preserves
the original presentation correlation; it cannot attach a new presentation to
an old entry just because a duplicate exists. Other conflicts remain refusals.

A transport failure after POST is ambiguous: the engine may have committed.
There is no automatic POST retry. Durable disposition processing must reconcile
the current engine entry and its correlation before reporting success or
offering a retry. A failed dependency must never be recorded as a human decline.

The client is an internal seam. `review.py` now connects fresh PDP entitlement,
durable presentations, actor/version/acknowledgment guards, local responses,
the transactional outbox and the original-entry recovery rules. `runtime.py`
schedules bounded delivery and reconciliation. No consume route exists.

The legacy `evidence.Outbox` is an in-memory test double; `Store` supplies
durable atomic state/evidence. See [durable-review-evidence.md](durable-review-evidence.md).
Native policy/caller assignment, registered human login, deployment and
independent custody remain in T08. Disposable browser success does not close them.