@synthigy/sdk 0.1.2 → 0.2.1

package/src/index.js

@@ -5,8 +5,10 @@
  * Handles service-identity token acquisition (client credentials) and
  * user impersonation via `acting_as`.
  *
+ * `client.login` covers the OAuth2 authorization-code + PKCE exchange for a
+ * server-side (confidential) app; sessions and routing stay yours.
+ *
  * Intentionally out of scope — leave to the user's chosen libraries:
- *   - OAuth2 authorization-code redirect (framework concern)
  *   - ID-token JWT verification (pick `jose`, `jsonwebtoken`, etc.)
  *   - HTTP pooling / retry / backoff (wrap `fetch` as you see fit)
  *
@@ -34,8 +36,18 @@
 
 import { watch as _watch, watchSchema as _watchSchema, getMultiplexer, Watch, SchemaWatch, WatchError } from './watch.js'
 import { watchQuery as _watchQuery, watchSqlTemplate as _watchSqlTemplate, QueryWatch, SqlTemplateWatch } from './watch-query.js'
+import { createLoginApi, rejectingLoginStore, MemoryLoginStore } from './login.js'
+import { createBrowserLogin as _createBrowserLogin, silentCallback } from './browser-login.js'
+
+export { Watch, SchemaWatch, WatchError, QueryWatch, SqlTemplateWatch, MemoryLoginStore, silentCallback }
 
-export { Watch, SchemaWatch, WatchError, QueryWatch, SqlTemplateWatch }
+/**
+ * Browser login as a public client (PKCE, silent renew, tokens in memory).
+ * Pass `login.tokenProvider()` to `createClient({ tokenProvider })`.
+ */
+export function createBrowserLogin(config) {
+  return _createBrowserLogin(config, { SynthigyError })
+}
 
 // ============================================================================
 // Operators — helper functions for building where clauses
@@ -403,10 +415,7 @@ class TokenManager {
       body: params,
     })
 
-    if (!resp.ok) {
-      const text = await resp.text()
-      throw new Error(`Token request failed (${resp.status}): ${text}`)
-    }
+    if (!resp.ok) throw _tokenRefusal(resp.status, await resp.text())
 
     const data = await resp.json()
     this._tokens.set(key, {
@@ -422,9 +431,30 @@ class TokenManager {
   }
 }
 
+/** RFC 6749 §5.2 / RFC 8707 refusals with their own code; any other refusal is UNAUTHORIZED. */
+const REFUSAL_CODES = {
+  invalid_client: 'INVALID_CLIENT',
+  invalid_scope:  'INVALID_SCOPE',
+  invalid_target: 'INVALID_AUDIENCE',
+}
+
+function _tokenRefusal(status, text) {
+  let oauth = null
+  try { oauth = JSON.parse(text) } catch {}
+  if (typeof oauth?.error !== 'string' || oauth.error === '') {
+    return new SynthigyError(`Token request failed (${status}): ${text}`, 'UNAUTHORIZED', undefined, { status })
+  }
+  const code = Object.hasOwn(REFUSAL_CODES, oauth.error) ? REFUSAL_CODES[oauth.error] : 'UNAUTHORIZED'
+  const desc = typeof oauth.error_description === 'string' && oauth.error_description !== ''
+    ? ` — ${oauth.error_description}` : ''
+  return new SynthigyError(`Token request refused (${status}): ${oauth.error}${desc}`, code, oauth, {
+    status,
+    hint: code === 'INVALID_CLIENT' ? 'check the client id and secret, and that the client is active' : undefined,
+  })
+}
+
 // ============================================================================
-// Supervised stdio — SYNTHIGY_SUPERVISED=1, see
-// docs/plans/PLAN-EXEC-IDENTITY.md steps 2-4. The SDK never mints locally
+// Supervised stdio — SYNTHIGY_SUPERVISED=1. The SDK never mints locally
 // under this mode: the CLI/commander is the platform's stdio owner, so a
 // token is asked for over JSON-RPC on the process's OWN stdio (supervise
 // grammar) instead. {token, expires_in} is deliberately byte-compatible
@@ -520,6 +550,7 @@ class SupervisedIO {
   _ask(method, params, timeoutMs) {
     this._ensureReader()
     this._ensureWriteGuard()
+    process.stdin.ref?.()
     const id = ++this._nextId
     return new Promise((resolve) => {
       let settled = false
@@ -529,6 +560,8 @@ class SupervisedIO {
         settled = true
         clearTimeout(timer)
         this._pending.delete(id)
+        // a ref'd stdin keeps the event loop alive — the process would never exit
+        if (this._pending.size === 0) process.stdin.unref?.()
         resolve(v)
       }
       timer = setTimeout(() => deliver(null), timeoutMs)
@@ -592,8 +625,7 @@ function _getSupervisedIO() {
 /**
  * Token source for SYNTHIGY_SUPERVISED=1 — asks `auth.token` over the
  * process's own stdio instead of minting locally (the CLI/commander is
- * the platform's stdio owner; this SDK never mints, per
- * PLAN-EXEC-IDENTITY step 2). Same public shape as TokenManager
+ * the platform's stdio owner; this SDK never mints). Same public shape as TokenManager
  * (getToken/clear) so call sites don't care which source is installed —
  * a thin handle onto the real, process-wide SupervisedIO singleton
  * (cache and all), so multiple clients in one process share one cache
@@ -609,7 +641,7 @@ class SupervisedTokenSource {
   }
 }
 
-/** The teaching throw — PLAN-EXEC-IDENTITY step 3: the error IS the UX, no flag, no silent anonymous fallback. */
+/** The teaching throw: the error IS the UX, no flag, no silent anonymous fallback. */
 function _noTokenError() {
   return new SynthigyError(
     'no Synthigy token: set token, or clientId + clientSecret, or set ' +
@@ -647,12 +679,32 @@ const ERROR_CATEGORIES = {
   PROVISION_FORBIDDEN:        'auth',
   CLAIM_INVALID:              'auth',
   NO_TOKEN:                   'auth', // client-side: no token source configured — retrying can't fix it
+  NO_ENDPOINT:                'validation', // client-side: no endpoint configured — retrying can't fix it
+  NO_LOGIN_STORE:             'auth', // client-side: no login store registered — retrying can't fix it
+  LOGIN_NONCE_MISMATCH:       'auth',
+  LOGIN_EXCHANGE_FAILED:      'auth',
+  SILENT_TIMEOUT:             'auth',
+  USERINFO_SUB_MISMATCH:      'auth',
+  INVALID_CLIENT:             'auth',
+  INVALID_SCOPE:              'auth',
+  INVALID_AUDIENCE:           'auth',
+  // OAuth error codes the IdP redirects back with (RFC 6749 4.1.2.1, OIDC 3.1.2.6)
+  access_denied:              'auth',
+  login_required:             'auth',
+  consent_required:           'auth',
+  interaction_required:       'auth',
   // iam
   FORBIDDEN:                  'iam',
   FORBIDDEN_OP:               'iam',
   ENTITY_FORBIDDEN:           'iam',
   ENTITY_NOT_READABLE:        'iam',
   RELATION_NOT_READABLE:      'iam',
+  RELATION_FORBIDDEN:         'iam',
+  ATTRIBUTE_FORBIDDEN:        'iam',
+  ROW_FORBIDDEN:              'iam',
+  CREATE_FORBIDDEN:           'iam',
+  DELETE_FORBIDDEN:           'iam',
+  SLOT_OCCUPIED:              'iam',
   // validation
   INVALID_BODY:               'validation',
   NO_OPERATIONS:              'validation',
@@ -681,7 +733,13 @@ const ERROR_CATEGORIES = {
   PARAM_MISSING:              'validation',
   PARAM_TYPE_MISMATCH:        'validation',
   NOT_CONNECTED:              'validation', // client-side guard — retrying without connecting can't fix it
+  LOGIN_STATE_UNKNOWN:        'validation',
+  LOGIN_REQUIRES_CONFIDENTIAL_CLIENT: 'validation',
   XID_REQUIRED:               'validation',
+  NAMESPACE_REQUIRED:         'validation',
+  DUPLICATE_OPERATION:        'validation',
+  BATCH_MEMBER_UNRESOLVED:    'validation',
+  CONFIG_ERROR:               'validation',
   CLAIM_METHOD_NOT_ALLOWED:   'validation',
   PASSWORD_TOO_WEAK:          'validation',
   RETURN_URL_NOT_REGISTERED:  'validation',
@@ -703,11 +761,14 @@ const ERROR_CATEGORIES = {
   INTERNAL_ERROR:             'internal',
   OPERATION_ERROR:            'internal',
   HTTP_ERROR:                 'internal',
+  OPERATION_FAILED:           'internal',
+  USERINFO_FAILED:            'internal',
 }
 
 /**
  * Codes whose category is automatically retryable. Any other code is
- * one-shot: the caller must fix something before retrying.
+ * one-shot: the caller must fix something before retrying. A code missing
+ * from ERROR_CATEGORIES is retryable only when the server marks it so.
  */
 const RETRYABLE_CATEGORIES = new Set(['network', 'rate_limit', 'internal'])
 
@@ -748,7 +809,9 @@ export class SynthigyError extends Error {
     this.name      = 'SynthigyError'
     this.code      = code
     this.category  = ERROR_CATEGORIES[code] ?? 'internal'
-    this.retryable = RETRYABLE_CATEGORIES.has(this.category)
+    this.retryable = typeof extras?.retryable === 'boolean'
+      ? extras.retryable
+      : Object.hasOwn(ERROR_CATEGORIES, code) && RETRYABLE_CATEGORIES.has(this.category)
     if (details !== undefined) this.details = details
     if (extras) {
       if (extras.hint        !== undefined) this.hint        = extras.hint
@@ -804,6 +867,7 @@ function _errorFromServer(err, status, requestId) {
     start:       err.start,
     end:         err.end,
     diagnostics: err.diagnostics,
+    retryable:   err.retryable,
     requestId,
     status,
   })
@@ -831,15 +895,17 @@ async function onboardError(resp) {
 class SynthigyClient {
   /**
    * @param {Object} config
-   * @param {string} config.endpoint - Synthigy base URL
+   * @param {string} [config.endpoint] - Synthigy base URL (default $SYNTHIGY_ENDPOINT)
    * @param {string} [config.clientId] - OAuth client ID (for client credentials)
    * @param {string} [config.clientSecret] - OAuth client secret
    * @param {string} [config.token] - Static bearer token (alternative to client credentials)
+   * @param {{getToken: (audience?: string) => string|null|Promise<string|null>, clear: () => void}} [config.tokenProvider]
+   *   - Caller-owned token source; `clear()` is called on a 401 before the one retry
    *
    * On Node, with none of the above, the constructor also falls back to —
    * when SYNTHIGY_SUPERVISED=1 — a supervised-stdio auth.token ask (the
    * pipe beats the env var: it can refresh mid-run), then the
-   * SYNTHIGY_TOKEN env var (see docs/plans/PLAN-EXEC-IDENTITY.md step 3).
+   * SYNTHIGY_TOKEN env var.
    * With no source at all it throws a SynthigyError whose code is
    * NO_TOKEN and whose message teaches the fix. A browser has neither
    * env vars nor a stdio parent, so it always requires an explicit source.
@@ -863,17 +929,24 @@ class SynthigyClient {
    *       fetch: (url, init) => fetch(url, { ...init, dispatcher: agent }),
    *     })
    */
-  constructor(config) {
-    this._endpoint = config.endpoint.replace(/\/$/, '')
+  constructor(config = {}) {
+    const endpoint = config.endpoint
+      ?? (typeof process !== 'undefined' ? process.env?.SYNTHIGY_ENDPOINT : undefined)
+    if (!endpoint) {
+      throw new SynthigyError(
+        'no endpoint — pass config.endpoint, or set SYNTHIGY_ENDPOINT (run under `synthigy exec`)',
+        'NO_ENDPOINT')
+    }
+    this._endpoint = endpoint.replace(/\/$/, '')
     this._dataUrl = `${this._endpoint}/data`
     this._defaultActingAs = config.actingAs ?? null
     this._defaultKeyFormat = config.keyFormat ?? null
     this._timeout = config.timeout ?? null
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis)
-    // Stored so the OIDC helpers can authenticate code-exchange and
-    // default the ID-token audience to this client's own id.
+    // Stored so `client.login` can authenticate the code exchange.
     this._clientId = config.clientId ?? null
     this._clientSecret = config.clientSecret ?? null
+    this._loginStore = config.loginStore ?? rejectingLoginStore(SynthigyError)
     // Long-lived contexts (BFFs, Node services) want the upstream SSE pinned
     // open across user-watch churn so the plug session keyed by
     // [sub, client_id] isn't torn down between watches. Replaces the
@@ -890,7 +963,12 @@ class SynthigyClient {
       ?? (typeof process !== 'undefined' ? process.env?.SYNTHIGY_AUDIENCE : undefined)
       ?? PLATFORM_AUDIENCE
 
-    if (config.token !== undefined && config.token !== null) {
+    if (config.tokenProvider) {
+      // Caller-owned source ({ getToken(audience), clear() }) — e.g. the
+      // browser login. clear() on a 401 is its cue to refresh.
+      this._tokenManager = config.tokenProvider
+      this._getToken = () => this._tokenManager.getToken(this._defaultAudience)
+    } else if (config.token !== undefined && config.token !== null) {
       // Static token mode — empty string allowed for unauth / dev servers.
       this._tokenManager = null
       this._getToken = async () => config.token
@@ -1774,6 +1852,55 @@ class SynthigyClient {
     return json.diagnostics ?? []
   }
 
+  /**
+   * Compile an XSQL source to the wire operation the engine would execute,
+   * via `POST /compile` — nothing runs. The compiler is the authority on
+   * the wire format, so this is how you take programmatic control of a
+   * query instead of hand-writing the JSON: edit the returned map and send
+   * it through `batch()`.
+   *
+   * `params` bind exactly as they do on `query()`, so what comes back IS
+   * what the engine receives.
+   *
+   * @param {string} source - XSQL source (bare body or full `@verb` document)
+   * @param {Object} [opts]
+   * @param {Object} [opts.params] - `?name:type` bindings
+   * @param {'search'|'get'|'slice'|'purge'} [opts.op='search'] - verb for a bare body
+   * @returns {Promise<Object>} the wire op `{op, entity, args, selections}`
+   *
+   * @example
+   * ```js
+   * const op = await client.compile('movie (limit ?n:int=5)\n  title\n',
+   *                                 { params: { n: 2 } })
+   * op.args._limit = 10
+   * const [rows] = await client.batch([op])
+   * ```
+   */
+  async compile(source, opts) {
+    const op = { op: 'xsql', xsql: xsqlDocument(source, opts?.op ?? 'search') }
+    if (opts?.params) op.params = opts.params
+    const resp = await this._fetchAuth(`${this._endpoint}/compile`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ operations: [op] }),
+    })
+    const json = await resp.json().catch(() => ({}))
+    if (!resp.ok) {
+      throw new SynthigyError(
+        json.error?.message || `Compile request failed (${resp.status})`,
+        json.error?.code || 'HTTP_ERROR'
+      )
+    }
+    const [result] = json.results ?? []
+    if (!result?.ok) {
+      throw new SynthigyError(
+        result?.error?.message || 'Compile failed',
+        result?.error?.code || 'XSQL_PARSE_ERROR'
+      )
+    }
+    return result.operation
+  }
+
   /**
    * Mint a one-time account-claim link via `POST /oauth/onboard`.
    * Confidential client whose principal administers the account — RBAC
@@ -1961,6 +2088,11 @@ class SynthigyClient {
     return body.result
   }
 
+  get login() {
+    if (!this._login) this._login = createLoginApi(this, { SynthigyError })
+    return this._login
+  }
+
   // Defined as a regular property so the .d.ts namespace `client.history.foo`
   // shape works at edit time.
   get history() {
@@ -2426,6 +2558,7 @@ export const op = {
   searchTree:  (entity, on, args, sel)   => ({ op: 'search-tree', entity, on, args, selections: normalizeSelection(sel) }),
   getTree:     (entity, root, on, sel)   => ({ op: 'get-tree',    entity, root, on, selections: normalizeSelection(sel) }),
   sqlTemplate: (template, params)        => ({ op: 'sql-template', template, params: params || [] }),
+  query:       (xsql, params, verb = 'search') => ({ op: 'xsql', xsql: xsqlDocument(xsql, verb), ...(params !== undefined && { params }) }),
   deployedModel: () => ({ op: 'deployed-model' }),
   runtimeModel: () => ({ op: 'runtime-model' }),
   deploy:       (exportContents)         => ({ op: 'deploy', data: exportContents }),
@@ -2440,7 +2573,7 @@ export const op = {
  * Create a Synthigy client.
  *
  * @param {Object} config
- * @param {string} config.endpoint - Synthigy base URL
+ * @param {string} [config.endpoint] - Synthigy base URL (default $SYNTHIGY_ENDPOINT)
  * @param {string} [config.clientId] - OAuth client ID
  * @param {string} [config.clientSecret] - OAuth client secret
  * @param {string} [config.token] - Static bearer token (alternative to client credentials)
@@ -2467,7 +2600,7 @@ export const op = {
  * })
  * ```
  */
-export function createClient(config) {
+export function createClient(config = {}) {
   return new SynthigyClient(config)
 }
 
@@ -2496,7 +2629,7 @@ let _defaultClient = null
  * @param {Object} config - same shape as {@link createClient}
  * @returns {SynthigyClient} the installed client (for introspection)
  */
-export function connect(config) {
+export function connect(config = {}) {
   const prev = _defaultClient
   _defaultClient = new SynthigyClient(config)
   if (prev) prev.close() // destroy the old one, server-restart style
@@ -2553,6 +2686,7 @@ export { _delete as delete }
 // Schema / introspection
 export const schema        = (...a) => _dflt().schema(...a)
 export const lint          = (...a) => _dflt().lint(...a)
+export const compile       = (...a) => _dflt().compile(...a)
 export const onboard       = (...a) => _dflt().onboard(...a)
 export const onboardComplete = (...a) => _dflt().onboardComplete(...a)
 export const deploy        = (...a) => _dflt().deploy(...a)
@@ -2561,6 +2695,7 @@ export const deployedModel = (...a) => _dflt().deployedModel(...a)
 export const runtimeModel  = (...a) => _dflt().runtimeModel(...a)
 export const token         = (...a) => _dflt().token(...a)
 export const history       = () => _dflt().history
+export const login         = () => _dflt().login
 
 // Streaming + live watches
 export const listen           = (...a) => _dflt().listen(...a)

package/src/login.js

@@ -0,0 +1,244 @@
+/**
+ * OIDC authorization-code + PKCE — the protocol half of a browser login.
+ *
+ * What this owns: the PKCE pair, the authorize URL, the code exchange, and
+ * reading the subject out of the id_token. What it deliberately does NOT own:
+ * sessions, cookies, redirects, routing. Those are your app's, and they are
+ * where a framework dependency would come from. The one piece of state the
+ * protocol itself needs — the in-flight login, from /login until the callback
+ * comes back — you supply as a `loginStore`.
+ *
+ * Zero dependencies and no Node built-ins: WebCrypto, btoa/atob, URL.
+ */
+
+const PKCE_VERIFIER_BYTES = 32
+const STATE_BYTES = 24
+// must exceed the server's 8-minute login window, or slow logins fail LOGIN_STATE_UNKNOWN
+const LOGIN_TTL_MS = 10 * 60_000
+
+function base64urlEncode(bytes) {
+  let binary = ''
+  for (const b of bytes) binary += String.fromCharCode(b)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function base64urlDecode(text) {
+  const padded = text.replace(/-/g, '+').replace(/_/g, '/')
+  const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4))
+  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0))
+  return new TextDecoder().decode(bytes)
+}
+
+function randomToken(bytes) {
+  return base64urlEncode(globalThis.crypto.getRandomValues(new Uint8Array(bytes)))
+}
+
+/** A fresh PKCE verifier and its S256 challenge (RFC 7636). */
+export async function pkce() {
+  const codeVerifier = randomToken(PKCE_VERIFIER_BYTES)
+  const digest = await globalThis.crypto.subtle.digest(
+    'SHA-256', new TextEncoder().encode(codeVerifier))
+  return { codeVerifier, codeChallenge: base64urlEncode(new Uint8Array(digest)) }
+}
+
+/**
+ * Read a JWT's payload without verifying its signature.
+ *
+ * Safe here and nowhere else: this token arrived in the body of our own
+ * client-authenticated POST to the token endpoint, over TLS, so its origin is
+ * already established by the channel. A signature check would be guarding
+ * against an attacker who can already answer as the IdP. Never use this on a
+ * token that reached you any other way — verifying those stays out of the
+ * SDK's scope, and `jose` is the library for it.
+ */
+export function decodeJwtPayload(jwt) {
+  const parts = String(jwt ?? '').split('.')
+  if (parts.length < 2) return null
+  try {
+    return JSON.parse(base64urlDecode(parts[1]))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * In-flight logins in a Map — SINGLE PROCESS ONLY.
+ *
+ * Every instance behind a load balancer gets its own Map, so a callback that
+ * lands on a different instance than the one that started the login fails with
+ * LOGIN_STATE_UNKNOWN. Real deployments back the store with whatever already
+ * holds their sessions (Redis, Postgres, a signed cookie).
+ */
+export class MemoryLoginStore {
+  constructor({ ttlMs = LOGIN_TTL_MS } = {}) {
+    this._ttlMs = ttlMs
+    this._pending = new Map()
+  }
+
+  put(state, login) {
+    // Swept on write rather than on a timer: a timer would keep a Node
+    // process alive and would have to be torn down by someone.
+    const cutoff = Date.now() - this._ttlMs
+    for (const [key, value] of this._pending) {
+      if (value.createdAt <= cutoff) this._pending.delete(key)
+    }
+    this._pending.set(state, login)
+  }
+
+  take(state) {
+    const login = this._pending.get(state)
+    if (!login) return null
+    this._pending.delete(state)
+    return login.createdAt <= Date.now() - this._ttlMs ? null : login
+  }
+}
+
+export function noLoginStoreError(SynthigyError) {
+  return new SynthigyError(
+    'no login store: pass createClient({ loginStore }) — an object with ' +
+    'put(state, login) and take(state), backed by whatever already holds ' +
+    'your sessions. For a single-process dev server, import ' +
+    '{ MemoryLoginStore } and pass new MemoryLoginStore().',
+    'NO_LOGIN_STORE')
+}
+
+/** A store that refuses rather than silently keeping logins in one process. */
+export function rejectingLoginStore(SynthigyError) {
+  return {
+    put() { throw noLoginStoreError(SynthigyError) },
+    take() { throw noLoginStoreError(SynthigyError) },
+  }
+}
+
+/**
+ * The `client.login` namespace: start / complete / cancel.
+ *
+ * Takes the client rather than importing it, so this module never depends on
+ * index.js and the two can't cycle.
+ */
+export function createLoginApi(client, { SynthigyError }) {
+  const requireConfidential = () => {
+    if (!client._clientId || !client._clientSecret) {
+      throw new SynthigyError(
+        'login needs clientId + clientSecret: the code exchange authenticates ' +
+        'this process as a confidential client. A browser or native app is a ' +
+        'public client and drives the same flow with a PKCE library of its ' +
+        'own — see docs/AUTH.md.',
+        'LOGIN_REQUIRES_CONFIDENTIAL_CLIENT')
+    }
+  }
+
+  // the store's own expiry is not trusted: one that never expires would accept a login of any age
+  const takePending = async (state) => {
+    const pending = state ? await client._loginStore.take(state) : null
+    return pending && pending.createdAt > Date.now() - LOGIN_TTL_MS ? pending : null
+  }
+
+  return {
+    /**
+     * Begin a login: returns the URL to redirect the browser to, and stashes
+     * the PKCE verifier under a fresh `state` in the login store.
+     */
+    async start({ redirectUri, returnTo = '/', scope = 'openid', publicEndpoint } = {}) {
+      requireConfidential()
+      if (!redirectUri) {
+        throw new SynthigyError(
+          'login.start needs redirectUri — the URL on YOUR server the IdP ' +
+          'sends the browser back to, registered on this OAuth client.',
+          'LOGIN_REQUIRES_CONFIDENTIAL_CLIENT')
+      }
+      const state = randomToken(STATE_BYTES)
+      const nonce = randomToken(STATE_BYTES)
+      const { codeVerifier, codeChallenge } = await pkce()
+      // Stored BEFORE the URL is handed out: a browser that follows the
+      // redirect faster than the store commits would come back to nothing.
+      await client._loginStore.put(state, { codeVerifier, nonce, returnTo, createdAt: Date.now() })
+
+      const url = new URL(`${publicEndpoint ?? client._endpoint}/oauth/authorize`)
+      url.searchParams.set('response_type', 'code')
+      url.searchParams.set('client_id', client._clientId)
+      url.searchParams.set('redirect_uri', redirectUri)
+      url.searchParams.set('scope', scope)
+      url.searchParams.set('state', state)
+      url.searchParams.set('code_challenge', codeChallenge)
+      url.searchParams.set('code_challenge_method', 'S256')
+      url.searchParams.set('nonce', nonce)
+      return { url: url.toString() }
+    },
+
+    /**
+     * Exchange the callback's code for tokens and the user behind them.
+     *
+     * `user.xid` comes straight out of the id_token — the engine puts it on
+     * every token it signs — so this costs no /data round-trip.
+     */
+    async complete({ code, state, redirectUri } = {}) {
+      requireConfidential()
+      const pending = await takePending(state)
+      if (!pending) {
+        throw new SynthigyError(
+          'unknown or expired login state: the store never saw it, it was ' +
+          'already consumed, or it timed out. A callback landing on a ' +
+          'different instance than the one that served /login does this.',
+          'LOGIN_STATE_UNKNOWN')
+      }
+
+      const params = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        client_id: client._clientId,
+        client_secret: client._clientSecret,
+        code_verifier: pending.codeVerifier,
+      })
+      const resp = await client._fetch(`${client._endpoint}/oauth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params,
+      })
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => '')
+        throw new SynthigyError(
+          `authorization-code exchange failed (${resp.status})`,
+          'LOGIN_EXCHANGE_FAILED', text, { status: resp.status })
+      }
+      const tokens = await resp.json()
+      const claims = decodeJwtPayload(tokens.id_token)
+      if (!claims) {
+        throw new SynthigyError(
+          'token response carried no readable id_token — request the openid ' +
+          'scope, which is what names the user.',
+          'LOGIN_EXCHANGE_FAILED')
+      }
+      if (claims.nonce !== pending.nonce) {
+        throw new SynthigyError(
+          'id_token nonce does not match the one this login started with',
+          'LOGIN_NONCE_MISMATCH')
+      }
+
+      return {
+        user: {
+          xid: claims.xid ?? null,
+          name: claims.sub ?? null,
+          // Granted scopes live in the token response; the id_token carries
+          // them only when the IdP chose to mirror them.
+          scopes: String(tokens.scope ?? claims.scope ?? '').split(' ').filter(Boolean),
+        },
+        tokens,
+        returnTo: pending.returnTo,
+      }
+    },
+
+    /**
+     * Discard an in-flight login and recover where the visitor was headed.
+     *
+     * Cancelling on the IdP's login page is a normal outcome (RFC 6749
+     * §4.1.2.1 sends `error` back with no code), so an unknown state is null
+     * here rather than a throw.
+     */
+    async cancel(state) {
+      const pending = await takePending(state)
+      return pending ? { returnTo: pending.returnTo } : null
+    },
+  }
+}