Plan: Universe Onboarding — PR3 (Broker device flow)

Sub-plan for plan §PR3 of /plans/universe-onboarding.md. Picked up after PR2 (#136, broker discovery doc) merged 2026-05-15. Ready to start cold tomorrow: this doc plus /plans/universe-onboarding.md + /journal/2026-05-15.md is sufficient context.

Goal

Broker hosts the RFC 8628 device flow end to end. After PR3 lands, a curl client can drive:

1. POST /device/authorize → receives device_code + user_code + verification_uri.
2. User opens verification_uri in a browser, types user_code, completes OIDC.
3. Curl polls POST /device/token with device_code and eventually gets a success response containing the IdP's raw id_token + access_token.

That id_token can already be used as a bearer against the broker's existing /tokens endpoint via the verifier infra — no plugin work yet, but the device-flow surface is fully operational. PR4 layers refresh tokens on top of the same response shape; PR5 adds /me/install; PR6 is the plugin binary.

Non-Negotiables Inherited

• No protocol changes. Same as the parent plan.
• No demarkus-server changes. All work in tools/demarkus-broker/.
• No MVPs, no shortcuts. Full RFC 8628 — all error codes, slow_down, expiry, denial.
• Single broker. State lives in-memory; no Lease, no Secret-backed persistence. Plan §"Single broker only for now."

Out of Scope (explicit, for PR3 specifically)

• Broker-signed id_tokens. PR3 forwards the IdP's id_token verbatim. Broker re-signing is PR4's job.
• Refresh tokens. PR3's /device/token success response omits refresh_token. PR4 adds it.
• /me/install. Tokens minted from device flow are consumable via the existing /tokens endpoint in PR3. PR5 adds the install flow on top.
• Plugin work. PR6 is the tools/demarkus-join binary; PR7 is the Claude Code plugin slash commands.
• Multi-replica device store. In-memory map only; multi-replica routing is out of scope. The plan locked single-broker for now; if a customer ever asks for HA broker, the device store becomes a stateful piece needing a backing store (Redis / Secret / DB) — not now.

Architecture

┌───────────┐  POST /device/authorize ┌────────────┐
│  client   │ ──────────────────────► │            │
│ (curl,    │ ◄────────────────────── │   broker   │
│  plugin)  │   {device_code,         │            │
│           │    user_code,           │  deviceStore (in-mem map)
│           │    verification_uri,    │  ────────────────────
│           │    expires_in,          │  key:   device_code
│           │    interval}            │  value: deviceCodeState
│           │                         │           ├ user_code
│           │                         │           ├ status: pending |
│           │                         │           │   complete | expired |
│           │                         │           │   denied
│           │                         │           ├ createdAt + expiresAt
│           │                         │           ├ lastPolledAt (slow_down)
│           │                         │           └ on success:
│           │                         │             • claims
│           │                         │             • raw id_token
│           │                         │             • raw access_token
│           │                         │             • IdP token expiry
│           │                         │
│           │                         │  /device → HTML form
│           │  GET /device            │  POST /device → set cookie, 302 /auth/login
│           │ ──────────────────────► │  GET /auth/callback (existing, plus
│           │  (user types user_code, │    new branch on device_code cookie)
│           │   completes OIDC)       │
│           │                         │
│           │  POST /device/token     │  Returns RFC 8628 error codes
│           │  (poll loop)            │  while pending; success with
│           │ ──────────────────────► │  raw id_token + access_token
│           │ ◄────────────────────── │  on complete.
└───────────┘                         └────────────┘

Layer responsibilities

Pre-Flight Interface Refactor

Verifier.Exchange currently returns (Claims, error) and throws away the raw id_token + access_token. The device-flow POST /device/token success response needs both raw tokens to forward to the plugin.

Decision (open for confirmation tomorrow): change the interface signature, update three call sites. Parallel-method alternative (ExchangeWithTokens) duplicates the OAuth dance for no real benefit and we'd refactor in PR4 anyway.

type ExchangeResult struct {
    Claims      Claims
    RawIDToken  string    // forwarded into /device/token success body
    AccessToken string    // ditto; OAuth access_token from IdP
    Expiry      time.Time // when the IdP-issued tokens expire
}

type Verifier interface {
    AuthCodeURL(state string) string
    Exchange(ctx context.Context, code string) (ExchangeResult, error) // was (Claims, error)
    VerifyIDToken(ctx context.Context, raw string) (Claims, error)
}