[Bccorb]

Implements ADR 0003: a first-party native client signed in through the OpenID Provider reaches the admin API by exchanging a single-use provider token for a child first-party session.

Refs #544, #551. Unblocks fells-code/seamless-cli#316.

Draft until @seamless-auth/types with the new schemas is released. Then run npm i @seamless-auth/types@^0.36.0 and commit package.json and the lock. Until then CI fails at typecheck; local checks used a packed tarball.

What it does

• Flag: sessionExchangeEnabled for first-party public native clients, with step-up and audit. Turning it off, or disabling or deleting the client, revokes its exchanged sessions.
• Token: /oidc/sign signs session:exchange only with the exact scope, the built-in audience, a jti and at most 120 seconds, and writes the record the exchange consumes.
• Exchange: POST /sessions/exchange consumes the token once in one transaction. A replay answers 400 invalid_request and revokes what the first use created.
• Child session: its own refresh chain and step-up state, capped at the parent's lifetime, ended when the parent ends. Child refreshes count as parent activity.
• Step-up copy: an authorization code child copies a parent step-up from the last five minutes. A device child copies nothing.

Device sessions (added during the build)

The record's first version gated only admin routes. A device session could enroll its own TOTP and then pass that check, and could replace a victim's TOTP; both were run against real Postgres. requireDeviceSessionStepUp now answers 403 step_up_required without a fresh step-up on:

• /admin/* and everything behind requireAdmin
• /totp/enroll/*, /totp/disable, /webauthn/register/*, POST /recovery-codes, DELETE /users/credentials
• /registration/phone, /registration/phone/verify, DELETE /recovery/requests/:id
• every organization route except POST /organizations/:id/switch, for global admins and ordinary members alike

A device sign-in with no TOTP cannot enroll one; the user does it from a browser. Signing out other sessions stays open, because it gains no access; the known cost is that it could slow the owner's response. A real passkey assertion is accepted as a step-up on a device session. All recorded in the ADR.

For review

Choices the ADR left open:

• Children do not count toward max_concurrent_sessions and are never evicted.
• The exchange refuses a parent that is itself a child.
• /oidc/sign refuses session:exchange on a refresh grant.
• Signing records are insert-only.
• Deleting a client revokes its exchanged sessions.

Ship with fells-code/seamless-auth-oidc-provider#61. X8 (no silent sign-in, and the confirmation names the account) is enforced at the edge. Without it, a local program using the CLI's client id could get a silent sign-in for a user with a live browser session.

Security review

A static /security-review of this branch reported nothing at or above its bar. It traced token verification, single use, grant type, the gates, revocation, client eligibility and data exposure. It ran no exploits and did not read the edge repo. It noted, below the bar: the X8 dependency above; isSessionExchangeClient accepts a client with both native and https redirects (admin-configured only); and a phished device child can keep the approver's browser session alive up to its absolute lifetime (accepted as X4).

Checks

From the implementer's final run: lint, typecheck, format and generate:api clean; unit and coverage 2913 passed, 99.07% lines; TEST_DB=postgres on a cold cache 3133 passed, 188 of 188 files, 158 in sessionExchange.spec.ts. Re-run in review: unit tests under tests/unit (1810) and typecheck; the Postgres suite was not repeated. Test commits precede their implementations; each piece's Postgres tests were seen failing first. 8f2ff8f also seeds system_config in oidcApplications.spec.ts, which failed whenever it ran first.