@crombolo/auth 0.13.2 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.13.2",
+  "version": "0.14.4",
   "description": "OAuth2 authorization server, password hashing, cookies and member tickets for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.13.2",
-    "@crombolo/data": "0.13.2"
+    "@crombolo/core": "0.14.4",
+    "@crombolo/data": "0.14.4",
+    "jose": "^6.2.12",
+    "uqr": "^0.1.3"
   }
 }

package/src/cookies.ts

@@ -17,6 +17,8 @@ export interface CookieNames {
   accessToken: string
   refreshToken: string
   session: string
+  /** A sign-in whose password was right, waiting for its two-factor code. */
+  twoFactorPending: string
 }
 
 export interface CookieOptions {
@@ -32,6 +34,7 @@ export function cookieNames(options: CookieOptions): CookieNames {
     accessToken: `${prefix}umbAccessToken${options.siteName}`,
     refreshToken: `${prefix}umbRefreshToken${options.siteName}`,
     session: `${prefix}umbSession${options.siteName}`,
+    twoFactorPending: `${prefix}umbTwoFactor${options.siteName}`,
   }
 }
 

package/src/device.ts

@@ -0,0 +1,183 @@
+/**
+ * The OAuth 2.0 device authorization grant (RFC 8628), for the `crombolo` CLI
+ * signing in to a remote (story 107): the CLI shows a short code, the person
+ * approves it in a browser where they are already signed in, and the CLI
+ * receives tokens for that person, with that person's permissions.
+ *
+ * The device code is a bearer credential and is stored hashed; the user code is
+ * what a person types, short and unambiguous, and is single-use. An approved
+ * authorization becomes a session of its own, so "signed-in devices" is the
+ * list of those sessions and revoking one ends it.
+ */
+import { randomInt } from 'node:crypto'
+import { type Db, DbDate } from '@crombolo/data'
+import { generateToken, hashToken } from './pkce.ts'
+
+/** The client id the CLI signs in as. */
+export const REMOTE_CLIENT_ID = 'crombolo-cli'
+export const DEVICE_CODE_SECONDS = 10 * 60
+export const DEVICE_POLL_SECONDS = 5
+
+/** No vowels or look-alikes, so a code never spells a word or reads two ways. */
+const USER_CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ'
+
+export type DeviceStatus = 'pending' | 'approved' | 'denied' | 'issued'
+
+export interface DeviceAuthorizationRow {
+  id: number
+  userCode: string
+  clientId: string
+  clientName: string | null
+  scope: string
+  status: DeviceStatus
+  userId: number | null
+  sessionId: string | null
+  intervalSeconds: number
+  lastPolledAt: Date | undefined
+  expiresAt: Date
+  decidedAt: Date | undefined
+  createdAt: Date
+}
+
+export interface SignedInDevice {
+  id: number
+  clientName: string | null
+  signedInAt: Date
+  lastUsedAt: Date | undefined
+}
+
+function userCode(): string {
+  const pick = () => USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)] as string
+  return `${Array.from({ length: 4 }, pick).join('')}-${Array.from({ length: 4 }, pick).join('')}`
+}
+
+/** A code as typed: case, spaces and the dash do not matter. */
+export const normaliseUserCode = (code: string): string => {
+  const plain = code.toUpperCase().replace(/[^A-Z]/g, '')
+  return plain.length === 8 ? `${plain.slice(0, 4)}-${plain.slice(4)}` : plain
+}
+
+function mapRow(row: Record<string, unknown>): DeviceAuthorizationRow {
+  return {
+    id: Number(row.id),
+    userCode: String(row.user_code),
+    clientId: String(row.client_id),
+    clientName:
+      row.client_name === null || row.client_name === undefined ? null : String(row.client_name),
+    scope: String(row.scope),
+    status: String(row.status) as DeviceStatus,
+    userId: row.user_id === null || row.user_id === undefined ? null : Number(row.user_id),
+    sessionId:
+      row.session_id === null || row.session_id === undefined ? null : String(row.session_id),
+    intervalSeconds: Number(row.interval_seconds),
+    lastPolledAt: DbDate.fromDb(row.last_polled_at),
+    expiresAt: DbDate.fromDb(row.expires_at) ?? new Date(0),
+    decidedAt: DbDate.fromDb(row.decided_at),
+    createdAt: DbDate.fromDb(row.create_date) ?? new Date(0),
+  }
+}
+
+export class DeviceStore {
+  #db: Db
+
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  async create(init: {
+    clientId: string
+    clientName: string | null
+    scope: string
+  }): Promise<{ deviceCode: string; userCode: string; expiresAt: Date }> {
+    const deviceCode = generateToken()
+    const expiresAt = new Date(Date.now() + DEVICE_CODE_SECONDS * 1000)
+    // A clash with a live code is vanishingly rare; another draw settles it.
+    for (let attempt = 0; ; attempt++) {
+      const code = userCode()
+      try {
+        await this.#db.exec(
+          `INSERT INTO device_authorization
+             (device_code_hash, user_code, client_id, client_name, scope, status, interval_seconds, expires_at, create_date)
+           VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, ?)`,
+          [
+            hashToken(deviceCode),
+            code,
+            init.clientId,
+            init.clientName,
+            init.scope,
+            DEVICE_POLL_SECONDS,
+            DbDate.toDb(expiresAt),
+            DbDate.toDb(new Date()),
+          ],
+        )
+        return { deviceCode, userCode: code, expiresAt }
+      } catch (error) {
+        if (attempt >= 4) throw error
+      }
+    }
+  }
+
+  async byDeviceCode(deviceCode: string): Promise<DeviceAuthorizationRow | undefined> {
+    const rows = await this.#db.query(
+      'SELECT * FROM device_authorization WHERE device_code_hash = ?',
+      [hashToken(deviceCode)],
+    )
+    return rows[0] ? mapRow(rows[0]) : undefined
+  }
+
+  async byUserCode(code: string): Promise<DeviceAuthorizationRow | undefined> {
+    const rows = await this.#db.query('SELECT * FROM device_authorization WHERE user_code = ?', [
+      normaliseUserCode(code),
+    ])
+    return rows[0] ? mapRow(rows[0]) : undefined
+  }
+
+  async polled(id: number, intervalSeconds: number): Promise<void> {
+    await this.#db.exec(
+      'UPDATE device_authorization SET last_polled_at = ?, interval_seconds = ? WHERE id = ?',
+      [DbDate.toDb(new Date()), intervalSeconds, id],
+    )
+  }
+
+  /** Approves or denies a pending one; false when it was no longer pending. */
+  async decide(id: number, userId: number, approve: boolean): Promise<boolean> {
+    const rows = await this.#db.query<{ id: number }>(
+      `UPDATE device_authorization SET status = ?, user_id = ?, decided_at = ?
+       WHERE id = ? AND status = 'pending' RETURNING id`,
+      [approve ? 'approved' : 'denied', userId, DbDate.toDb(new Date()), id],
+    )
+    return rows.length > 0
+  }
+
+  /** Marks an approved one as having had its tokens issued, once; false if it already had. */
+  async issued(id: number, sessionId: string): Promise<boolean> {
+    const rows = await this.#db.query<{ id: number }>(
+      `UPDATE device_authorization SET status = 'issued', session_id = ?
+       WHERE id = ? AND status = 'approved' RETURNING id`,
+      [sessionId, id],
+    )
+    return rows.length > 0
+  }
+
+  /** The devices signed in as this user, whose sessions are still open. */
+  async signedIn(userId: number): Promise<SignedInDevice[]> {
+    const rows = await this.#db.query<Record<string, unknown>>(
+      `SELECT d.id, d.client_name, s.logged_in_utc, s.last_validated_utc
+       FROM device_authorization d JOIN user_login_session s ON s.session_id = d.session_id
+       WHERE d.user_id = ? AND d.status = 'issued' AND s.logged_out_utc IS NULL
+       ORDER BY s.logged_in_utc DESC`,
+      [userId],
+    )
+    return rows.map((row) => ({
+      id: Number(row.id),
+      clientName: row.client_name === null ? null : String(row.client_name),
+      signedInAt: DbDate.fromDb(row.logged_in_utc) ?? new Date(0),
+      lastUsedAt: DbDate.fromDb(row.last_validated_utc),
+    }))
+  }
+
+  async byId(id: number): Promise<DeviceAuthorizationRow | undefined> {
+    const rows = await this.#db.query('SELECT * FROM device_authorization WHERE id = ?', [id])
+    return rows[0] ? mapRow(rows[0]) : undefined
+  }
+}

package/src/index.ts

@@ -1,9 +1,13 @@
 export * from './admin.ts'
 export * from './cookies.ts'
+export * from './device.ts'
 export * from './member-session.ts'
+export * from './oidc.ts'
 export * from './password.ts'
 export * from './pkce.ts'
 export * from './routes.ts'
 export * from './service.ts'
+export * from './short-lived.ts'
 export * from './store.ts'
+export * from './totp.ts'
 export * from './umbraco-passwords.ts'

package/src/oidc.ts

@@ -0,0 +1,223 @@
+/**
+ * Signing in through an external identity provider (story 031): OpenID Connect,
+ * authorization code with PKCE. Discovery, the redirect and the code exchange
+ * are plain `fetch`; the ID token is verified with `jose` against the
+ * provider's published keys — signature, issuer, audience, expiry and nonce.
+ *
+ * What the browser carries between leaving for the provider and coming back —
+ * `state`, `nonce`, the PKCE verifier and where to return — is a short-lived
+ * token signed with the site's own key, so nothing is stored server side.
+ */
+import { createRemoteJWKSet, type JWTPayload, jwtVerify, SignJWT } from 'jose'
+import { deriveChallenge, generateToken } from './pkce.ts'
+
+/** How a provider's claims are read. Each names a claim in the ID token. */
+export interface OidcClaims {
+  email: string
+  name: string
+  /** Where group or role values come from, for mapping onto groups. */
+  groups?: string
+}
+
+/** One provider, as a preset describes it. */
+export interface OidcProviderOptions {
+  /** The provider's id: what `external_login` records, and part of its URLs. */
+  id: string
+  /** What a sign-in button says: "Sign in with {name}". */
+  name: string
+  issuer: string
+  clientId: string
+  clientSecret?: string
+  scopes: readonly string[]
+  claims: OidcClaims
+}
+
+/** Who the provider says signed in. */
+export interface OidcIdentity {
+  /** The provider's stable id for the account (`sub`). */
+  subject: string
+  email: string | undefined
+  emailVerified: boolean
+  name: string | undefined
+  /** The values of the provider's groups claim, when it names one. */
+  groups: string[]
+  claims: JWTPayload
+}
+
+interface Discovery {
+  issuer: string
+  authorization_endpoint: string
+  token_endpoint: string
+  jwks_uri: string
+}
+
+/** What a sign-in carries while the browser is away at the provider. */
+export interface OidcFlowState {
+  provider: string
+  state: string
+  nonce: string
+  verifier: string
+  returnUrl: string
+}
+
+const DISCOVERY_TTL_MS = 60 * 60 * 1000
+const FLOW_SECONDS = 10 * 60
+
+export class OidcError extends Error {}
+
+const stringClaim = (claims: JWTPayload, name: string): string | undefined => {
+  const value = claims[name]
+  return typeof value === 'string' && value ? value : undefined
+}
+
+const listClaim = (claims: JWTPayload, name: string | undefined): string[] => {
+  if (!name) return []
+  const value = claims[name]
+  if (Array.isArray(value)) return value.filter((v): v is string => typeof v === 'string')
+  return typeof value === 'string' && value ? [value] : []
+}
+
+/** A provider's sign-in, from discovery to a verified identity. */
+export class OidcClient {
+  readonly options: OidcProviderOptions
+  #discovery: { value: Discovery; at: number } | undefined
+  #keys: ReturnType<typeof createRemoteJWKSet> | undefined
+
+  constructor(options: OidcProviderOptions) {
+    this.options = options
+  }
+
+  /** The provider's endpoints, from its discovery document, cached for an hour. */
+  async discovery(): Promise<Discovery> {
+    if (this.#discovery && Date.now() - this.#discovery.at < DISCOVERY_TTL_MS)
+      return this.#discovery.value
+    const url = `${this.options.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`
+    const response = await fetch(url, { headers: { accept: 'application/json' } })
+    if (!response.ok)
+      throw new OidcError(`${this.options.name} discovery failed: ${response.status} from ${url}`)
+    const value = (await response.json()) as Discovery
+    for (const field of ['authorization_endpoint', 'token_endpoint', 'jwks_uri'] as const)
+      if (typeof value[field] !== 'string')
+        throw new OidcError(`${this.options.name} discovery has no ${field}`)
+    this.#discovery = { value, at: Date.now() }
+    this.#keys = createRemoteJWKSet(new URL(value.jwks_uri))
+    return value
+  }
+
+  /** A new flow: its state, nonce and PKCE verifier, and the URL to send the browser to. */
+  async start(
+    redirectUri: string,
+    returnUrl: string,
+  ): Promise<{ url: string; flow: OidcFlowState }> {
+    const { authorization_endpoint } = await this.discovery()
+    const flow: OidcFlowState = {
+      provider: this.options.id,
+      state: generateToken(),
+      nonce: generateToken(),
+      verifier: generateToken(),
+      returnUrl,
+    }
+    const url = new URL(authorization_endpoint)
+    url.searchParams.set('response_type', 'code')
+    url.searchParams.set('client_id', this.options.clientId)
+    url.searchParams.set('redirect_uri', redirectUri)
+    url.searchParams.set('scope', this.options.scopes.join(' '))
+    url.searchParams.set('state', flow.state)
+    url.searchParams.set('nonce', flow.nonce)
+    url.searchParams.set('code_challenge', await deriveChallenge(flow.verifier))
+    url.searchParams.set('code_challenge_method', 'S256')
+    return { url: url.href, flow }
+  }
+
+  /**
+   * The provider's answer, checked against the flow that started it, turned
+   * into a verified identity. Throws `OidcError` with a reason fit to log.
+   */
+  async finish(callback: URL, flow: OidcFlowState, redirectUri: string): Promise<OidcIdentity> {
+    const error = callback.searchParams.get('error')
+    if (error)
+      throw new OidcError(
+        `${this.options.name} refused the sign-in: ${callback.searchParams.get('error_description') ?? error}`,
+      )
+    if (callback.searchParams.get('state') !== flow.state)
+      throw new OidcError('the sign-in came back with a state it did not start with')
+    const code = callback.searchParams.get('code')
+    if (!code) throw new OidcError(`${this.options.name} sent no code`)
+
+    const { token_endpoint } = await this.discovery()
+    const body = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+      client_id: this.options.clientId,
+      code_verifier: flow.verifier,
+    })
+    if (this.options.clientSecret) body.set('client_secret', this.options.clientSecret)
+    const response = await fetch(token_endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body,
+    })
+    if (!response.ok)
+      throw new OidcError(`${this.options.name} would not exchange the code: ${response.status}`)
+    const tokens = (await response.json()) as { id_token?: string }
+    if (!tokens.id_token) throw new OidcError(`${this.options.name} sent no ID token`)
+    return this.verify(tokens.id_token, flow.nonce)
+  }
+
+  /** An ID token, verified: signed by the provider's keys, for us, current, and this flow's. */
+  async verify(idToken: string, nonce: string): Promise<OidcIdentity> {
+    const discovery = await this.discovery()
+    const keys = this.#keys as ReturnType<typeof createRemoteJWKSet>
+    let claims: JWTPayload
+    try {
+      ;({ payload: claims } = await jwtVerify(idToken, keys, {
+        issuer: discovery.issuer ?? this.options.issuer,
+        audience: this.options.clientId,
+      }))
+    } catch (error) {
+      throw new OidcError(
+        `the ID token from ${this.options.name} is not valid: ${(error as Error).message}`,
+      )
+    }
+    if (claims.nonce !== nonce) throw new OidcError('the ID token was not issued for this sign-in')
+    if (!claims.sub) throw new OidcError(`the ID token from ${this.options.name} names no subject`)
+    const verified = claims.email_verified
+    return {
+      subject: claims.sub,
+      email: stringClaim(claims, this.options.claims.email)?.toLowerCase(),
+      emailVerified: verified === true || verified === 'true',
+      name: stringClaim(claims, this.options.claims.name),
+      groups: listClaim(claims, this.options.claims.groups),
+      claims,
+    }
+  }
+}
+
+const secretKey = (secret: string) => new TextEncoder().encode(secret)
+
+/** The flow, signed, for the cookie the browser carries to the provider and back. */
+export async function signFlowState(secret: string, flow: OidcFlowState): Promise<string> {
+  return new SignJWT({ ...flow })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(`${FLOW_SECONDS}s`)
+    .sign(secretKey(secret))
+}
+
+/** The flow back from its cookie, or undefined when it is missing, altered or stale. */
+export async function readFlowState(
+  secret: string,
+  value: string | undefined,
+): Promise<OidcFlowState | undefined> {
+  if (!value) return undefined
+  try {
+    const { payload } = await jwtVerify(value, secretKey(secret), { algorithms: ['HS256'] })
+    const flow = payload as unknown as OidcFlowState
+    for (const field of ['provider', 'state', 'nonce', 'verifier', 'returnUrl'] as const)
+      if (typeof flow[field] !== 'string') return undefined
+    return flow
+  } catch {
+    return undefined
+  }
+}

package/src/routes.ts

@@ -15,18 +15,33 @@ import {
   resolveRedacted,
   serializeCookie,
 } from './cookies.ts'
+import { REMOTE_CLIENT_ID } from './device.ts'
 import type { AuthService } from './service.ts'
 import { BACKOFFICE_CLIENT_ID, DEFAULT_SCOPE } from './service.ts'
+import { readShortLived, signShortLived } from './short-lived.ts'
 import type { UserRow } from './store.ts'
 
+/** How long a sign-in waits for its two-factor code. */
+const TWO_FACTOR_PENDING_SECONDS = 5 * 60
+
 export const SECURITY_PREFIX = `${MANAGEMENT_API_PATH}/security/back-office`
 
+/** RFC 8628's grant type. */
+export const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+
 export interface AuthRouteOptions {
   backOfficePath: string
   service: AuthService
   cookies: CookieOptions
   /** Told about every sign-in, failed sign-in and sign-out, for the audit log. */
   onAudit?: (event: AuthAuditEvent, request: Request) => Promise<void>
+  /** Two-factor sign-in (story 032): who has a provider on, and whether a code is theirs. */
+  twoFactor?: {
+    providersFor(userKey: string): Promise<string[]>
+    verify(userKey: string, provider: string, code: string): Promise<boolean>
+    /** The key the pending cookie is signed with. */
+    secret(): Promise<string>
+  }
 }
 
 export interface AuthAuditEvent {
@@ -175,6 +190,32 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
       })
     }
 
+    // The CLI (story 107): tokens in the body, as a client with no cookie jar needs.
+    if (clientId === REMOTE_CLIENT_ID) {
+      const result =
+        grantType === DEVICE_CODE_GRANT
+          ? await service.pollDevice(form.get('device_code') ?? '', clientId)
+          : grantType === 'refresh_token'
+            ? await service.refresh(form.get('refresh_token') ?? '', clientId)
+            : {
+                ok: false as const,
+                error: 'unsupported_grant_type' as const,
+                description: `Unsupported grant_type '${grantType}'.`,
+              }
+      if (!result.ok) return oauthError(result.error, result.description, 400)
+      const signedIn = (result as { user?: UserRow }).user
+      if (grantType === DEVICE_CODE_GRANT && signedIn)
+        await audit({ action: 'SignIn', user: signedIn, detail: 'Device sign-in' }, request)
+      return Response.json({
+        access_token: result.grant.accessToken,
+        refresh_token: result.grant.refreshToken,
+        token_type: 'Bearer',
+        expires_in: result.grant.expiresIn,
+        issued_at: result.grant.issuedAt,
+        scope: DEFAULT_SCOPE,
+      })
+    }
+
     if (clientId !== BACKOFFICE_CLIENT_ID) {
       return oauthError('invalid_client', `Unknown client '${clientId}'.`)
     }
@@ -281,6 +322,9 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
       username,
       password,
       request.headers.get('x-forwarded-for') ?? undefined,
+      options.twoFactor
+        ? async (user) => (await options.twoFactor?.providersFor(user.key)) ?? []
+        : undefined,
     )
 
     if (result.status === 'success') await audit({ action: 'SignIn', user: result.user }, request)
@@ -322,12 +366,31 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
         problemDetails({ title: 'Login not allowed', status: 403, operationStatus: result.reason }),
       )
     }
-    if (result.status === 'twoFactorRequired') {
+    if (result.status === 'twoFactorRequired' && options.twoFactor) {
+      // The password was right; the session waits for the code. The pending
+      // cookie names who is part-way in, for five minutes.
+      const pending = await signShortLived(
+        await options.twoFactor.secret(),
+        { sub: result.user.key, login: result.user.login },
+        TWO_FACTOR_PENDING_SECONDS,
+      )
       return Response.json(
         { twoFactorLoginView: null, enabledTwoFactorProviderNames: result.providers },
-        { status: 402 },
+        {
+          status: 402,
+          headers: {
+            'set-cookie': serializeCookie({
+              name: names.twoFactorPending,
+              value: pending,
+              secure,
+              maxAgeSeconds: TWO_FACTOR_PENDING_SECONDS,
+            }),
+          },
+        },
       )
     }
+    if (result.status === 'twoFactorRequired')
+      return oauthError('server_error', 'Two-factor sign-in is not set up.', 500)
 
     return new Response(null, {
       status: 200,
@@ -337,6 +400,60 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
     })
   }
 
+  /** The second step of a sign-in: the code, against the pending cookie the password set. */
+  async function handleVerifyTwoFactor(request: Request): Promise<Response> {
+    const twoFactor = options.twoFactor
+    if (!twoFactor)
+      return problemResponse(
+        problemDetails({ title: 'Two-factor sign-in is not set up', status: 400 }),
+      )
+    const pending = await readShortLived(
+      await twoFactor.secret(),
+      readCookie(request, names.twoFactorPending),
+    )
+    const userKey = typeof pending?.sub === 'string' ? pending.sub : undefined
+    const login = typeof pending?.login === 'string' ? pending.login : undefined
+    if (!userKey || !login)
+      return problemResponse(
+        problemDetails({
+          title: 'Sign in again',
+          status: 401,
+          detail: 'The sign-in took too long. Enter your password again.',
+        }),
+      )
+    const body = (await request.json().catch(() => ({}))) as { provider?: unknown; code?: unknown }
+    const provider = typeof body.provider === 'string' ? body.provider : ''
+    const code = typeof body.code === 'string' ? body.code.trim() : ''
+    const ok = provider && code ? await twoFactor.verify(userKey, provider, code) : false
+    if (!ok) {
+      const { lockedOut } = await service.twoFactorFailed(login)
+      await audit({ action: 'SignInFailed', login, detail: 'Wrong two-factor code' }, request)
+      return problemResponse(
+        problemDetails({
+          title: lockedOut ? 'Login not allowed' : 'Invalid code',
+          status: lockedOut ? 403 : 400,
+          operationStatus: lockedOut ? 'lockedOut' : 'InvalidCode',
+        }),
+      )
+    }
+    const result = await service.signInExternally(
+      login,
+      request.headers.get('x-forwarded-for') ?? undefined,
+    )
+    if (result.status !== 'success')
+      return problemResponse(
+        problemDetails({ title: 'Login not allowed', status: 403, operationStatus: result.reason }),
+      )
+    await audit({ action: 'SignIn', user: result.user, detail: 'With two-factor sign-in' }, request)
+    const headers = new Headers()
+    headers.append(
+      'set-cookie',
+      sessionCookie(result.sessionId, service.settings.refreshTokenSeconds),
+    )
+    headers.append('set-cookie', expireCookie(names.twoFactorPending, secure))
+    return new Response(null, { status: 200, headers })
+  }
+
   async function handleRevoke(request: Request): Promise<Response> {
     const form = new URLSearchParams(await request.text())
     const token = resolveRedacted(form.get('token'), readCookie(request, names.accessToken))
@@ -360,6 +477,101 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
     return response
   }
 
+  /** RFC 8628's device authorization endpoint: the codes the CLI shows and polls with. */
+  async function handleDeviceAuthorization(request: Request, url: URL): Promise<Response> {
+    const form = new URLSearchParams(await request.text())
+    if ((form.get('client_id') ?? '') !== REMOTE_CLIENT_ID)
+      return oauthError('invalid_client', `Unknown client '${form.get('client_id') ?? ''}'.`, 401)
+    const name = form.get('client_name')?.slice(0, 200) || null
+    const started = await service.startDeviceAuthorization(REMOTE_CLIENT_ID, name)
+    const verification = `${url.origin}${options.backOfficePath}/device`
+    return Response.json({
+      device_code: started.deviceCode,
+      user_code: started.userCode,
+      verification_uri: verification,
+      verification_uri_complete: `${verification}?user_code=${encodeURIComponent(started.userCode)}`,
+      expires_in: started.expiresIn,
+      interval: started.interval,
+    })
+  }
+
+  /** The signed-in back-office person, from the session cookie, or undefined. */
+  async function sessionUser(request: Request): Promise<number | undefined> {
+    const sessionId = readCookie(request, names.session)
+    return sessionId ? (await service.resolveSession(sessionId))?.userId : undefined
+  }
+
+  /** A cookie-authenticated write must come from this site, not a form elsewhere. */
+  const sameSite = (request: Request) => {
+    const site = request.headers.get('sec-fetch-site')
+    if (site) return site === 'same-origin'
+    const origin = request.headers.get('origin')
+    return !origin || origin === new URL(request.url).origin
+  }
+
+  const signInFirst = () => problemResponse(problemDetails({ title: 'Sign in first', status: 401 }))
+
+  /** What the approval page shows for a code, and its decision. */
+  async function handleDevicePage(
+    request: Request,
+    url: URL,
+    action: string,
+  ): Promise<Response | undefined> {
+    const userId = await sessionUser(request)
+    if (!userId) return signInFirst()
+    if (action === 'device/pending' && request.method === 'GET') {
+      const pending = await service.pendingDevice(url.searchParams.get('user_code') ?? '')
+      if (!pending)
+        return problemResponse(
+          problemDetails({
+            title: 'That code is not waiting',
+            status: 404,
+            detail:
+              'It may have expired or been used. Start the sign-in again from the command line.',
+          }),
+        )
+      return Response.json({
+        userCode: pending.userCode,
+        clientName: pending.clientName,
+        expiresAt: pending.expiresAt.toISOString(),
+      })
+    }
+    if (action === 'device/decide' && request.method === 'POST') {
+      if (!sameSite(request)) return new Response('Forbidden', { status: 403 })
+      const body = (await request.json().catch(() => ({}))) as {
+        userCode?: unknown
+        approve?: unknown
+      }
+      const decided = await service.decideDevice(
+        typeof body.userCode === 'string' ? body.userCode : '',
+        userId,
+        body.approve === true,
+      )
+      return decided
+        ? new Response(null, { status: 204 })
+        : problemResponse(problemDetails({ title: 'That code is not waiting', status: 404 }))
+    }
+    if (action === 'devices' && request.method === 'GET') {
+      const devices = await service.signedInDevices(userId)
+      return Response.json(
+        devices.map((device) => ({
+          id: device.id,
+          name: device.clientName,
+          signedInAt: device.signedInAt.toISOString(),
+          lastUsedAt: device.lastUsedAt?.toISOString() ?? null,
+        })),
+      )
+    }
+    const revoking = /^devices\/(\d+)$/.exec(action)
+    if (revoking && request.method === 'DELETE') {
+      if (!sameSite(request)) return new Response('Forbidden', { status: 403 })
+      return (await service.revokeDevice(Number(revoking[1]), userId))
+        ? new Response(null, { status: 204 })
+        : problemResponse(problemDetails({ title: 'No such device', status: 404 }))
+    }
+    return undefined
+  }
+
   return {
     async handle(request, pathname) {
       if (!pathname.startsWith(`${prefix}/`)) return undefined
@@ -371,13 +583,12 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
       if (action === 'login' && request.method === 'POST') return handleLogin(request)
       if (action === 'revoke' && request.method === 'POST') return handleRevoke(request)
       if (action === 'signout') return handleSignOut(request, url)
-      if (action === 'verify-2fa' && request.method === 'POST') {
-        return oauthError(
-          'unsupported_grant_type',
-          'Two-factor authentication is not implemented.',
-          400,
-        )
-      }
+      if (action === 'verify-2fa' && request.method === 'POST')
+        return handleVerifyTwoFactor(request)
+      if (action === 'device' && request.method === 'POST')
+        return handleDeviceAuthorization(request, url)
+      if (action.startsWith('device/') || action === 'devices' || action.startsWith('devices/'))
+        return handleDevicePage(request, url, action)
       return undefined
     },
   }

package/src/service.ts

@@ -3,6 +3,12 @@
  * actually sends. See docs/backoffice-hosting.md for the wire contract.
  */
 import { type ExtensionSectionAlias, type SectionAlias, toSectionAliases } from '@crombolo/core'
+import {
+  DEVICE_CODE_SECONDS,
+  DEVICE_POLL_SECONDS,
+  type DeviceAuthorizationRow,
+  type SignedInDevice,
+} from './device.ts'
 import { hashPassword, isNativeHash, passwordConfigJson, verifyPassword } from './password.ts'
 import { type CodeChallengeMethod, generateToken, verifyChallenge } from './pkce.ts'
 import type { AuthStore, UserRow } from './store.ts'
@@ -45,7 +51,7 @@ export const DEFAULT_AUTH_SETTINGS: AuthSettings = {
 export type LoginResult =
   | { status: 'success'; user: UserRow; sessionId: string }
   | { status: 'invalid'; user?: UserRow; lockedOut?: boolean }
-  | { status: 'twoFactorRequired'; providers: string[] }
+  | { status: 'twoFactorRequired'; providers: string[]; user: UserRow }
   | { status: 'notAllowed'; reason: 'disabled' | 'lockedOut' | 'notApproved'; user?: UserRow }
 
 export interface AuthorizationRequest {
@@ -71,6 +77,11 @@ export type TokenError =
   | 'invalid_request'
   | 'invalid_client'
   | 'unauthorized_client'
+  // RFC 8628's answers while a device sign-in waits.
+  | 'authorization_pending'
+  | 'slow_down'
+  | 'expired_token'
+  | 'access_denied'
 
 export type TokenResult =
   | { ok: true; grant: TokenGrant }
@@ -114,7 +125,17 @@ export class AuthService {
     return this.#settings
   }
 
-  async login(login: string, password: string, ipAddress?: string): Promise<LoginResult> {
+  /**
+   * `twoFactorProviders`, when given, names the two-factor providers a user has
+   * turned on (story 032): with any, a correct password stops short of a session
+   * and the caller asks for a code.
+   */
+  async login(
+    login: string,
+    password: string,
+    ipAddress?: string,
+    twoFactorProviders?: (user: UserRow) => Promise<string[]>,
+  ): Promise<LoginResult> {
     return withMinimumDuration(120, async () => {
       const user = await this.#store.findUserByLogin(login)
       if (!user) {
@@ -155,12 +176,50 @@ export class AuthService {
           passwordConfigJson(),
         )
 
+      const providers = (await twoFactorProviders?.(user)) ?? []
+      if (providers.length > 0) return { status: 'twoFactorRequired', providers, user } as const
+
       const sessionId = crypto.randomUUID()
       await this.#store.recordLoginSuccess(user.id, sessionId, ipAddress)
       return { status: 'success', user, sessionId } as const
     })
   }
 
+  /**
+   * A wrong second factor counts as a wrong password does, towards lockout, so a
+   * stolen password cannot be followed by guessing codes for free.
+   */
+  async twoFactorFailed(login: string): Promise<{ lockedOut: boolean }> {
+    const user = await this.#store.findUserByLogin(login)
+    if (!user) return { lockedOut: false }
+    const attempts = await this.#store.recordLoginFailure(user.id)
+    const lockedOut =
+      this.#settings.maxFailedLoginAttempts > 0 && attempts >= this.#settings.maxFailedLoginAttempts
+    if (lockedOut) await this.#store.lockOut(user.id)
+    return { lockedOut }
+  }
+
+  /**
+   * Signs a user in whom an external identity provider has vouched for (story
+   * 031): no password, but the same refusals a password sign-in has — locked out
+   * or not approved — and the same session afterwards.
+   */
+  async signInExternally(
+    login: string,
+    ipAddress?: string,
+  ): Promise<
+    | { status: 'success'; user: UserRow; sessionId: string }
+    | { status: 'notAllowed'; reason: 'lockedOut' | 'notApproved' | 'unknown' }
+  > {
+    const user = await this.#store.findUserByLogin(login)
+    if (!user) return { status: 'notAllowed', reason: 'unknown' }
+    if (user.isLockedOut) return { status: 'notAllowed', reason: 'lockedOut' }
+    if (!user.isApproved) return { status: 'notAllowed', reason: 'notApproved' }
+    const sessionId = crypto.randomUUID()
+    await this.#store.recordLoginSuccess(user.id, sessionId, ipAddress)
+    return { status: 'success', user, sessionId }
+  }
+
   /** Issues a single-use authorization code for an already-authenticated session. */
   async authorize(
     sessionId: string,
@@ -329,6 +388,83 @@ export class AuthService {
     return this.signOut(token.sessionId)
   }
 
+  /** Starts a device sign-in (RFC 8628): the codes, and how often the client may poll. */
+  async startDeviceAuthorization(
+    clientId: string,
+    clientName: string | null,
+  ): Promise<{ deviceCode: string; userCode: string; expiresIn: number; interval: number }> {
+    const created = await this.#store.devices.create({ clientId, clientName, scope: DEFAULT_SCOPE })
+    return {
+      deviceCode: created.deviceCode,
+      userCode: created.userCode,
+      expiresIn: DEVICE_CODE_SECONDS,
+      interval: DEVICE_POLL_SECONDS,
+    }
+  }
+
+  /** A device sign-in waiting for a person, by the code they typed; undefined once it is not. */
+  async pendingDevice(userCode: string): Promise<DeviceAuthorizationRow | undefined> {
+    const row = await this.#store.devices.byUserCode(userCode)
+    if (row?.status !== 'pending' || row.expiresAt.getTime() < Date.now()) return undefined
+    return row
+  }
+
+  /** Approves or denies a waiting device sign-in for the signed-in person. */
+  async decideDevice(userCode: string, userId: number, approve: boolean): Promise<boolean> {
+    const row = await this.pendingDevice(userCode)
+    return row ? this.#store.devices.decide(row.id, userId, approve) : false
+  }
+
+  /**
+   * The device's poll: pending until a person decides, then the tokens, once.
+   * Polling faster than the interval answers `slow_down` and lengthens it, as
+   * RFC 8628 says.
+   */
+  async pollDevice(
+    deviceCode: string,
+    clientId: string,
+  ): Promise<TokenResult & { user?: UserRow }> {
+    const row = await this.#store.devices.byDeviceCode(deviceCode)
+    if (!row || row.clientId !== clientId)
+      return { ok: false, error: 'invalid_grant', description: 'Unknown device code.' }
+    if (row.status === 'denied')
+      return { ok: false, error: 'access_denied', description: 'The sign-in was declined.' }
+    if (row.status === 'issued')
+      return { ok: false, error: 'invalid_grant', description: 'This device code has been used.' }
+    if (row.expiresAt.getTime() < Date.now())
+      return { ok: false, error: 'expired_token', description: 'The device code has expired.' }
+    if (row.status === 'pending') {
+      const tooSoon =
+        row.lastPolledAt !== undefined &&
+        Date.now() - row.lastPolledAt.getTime() < row.intervalSeconds * 1000
+      await this.#store.devices.polled(row.id, row.intervalSeconds + (tooSoon ? 5 : 0))
+      return tooSoon
+        ? { ok: false, error: 'slow_down', description: 'Poll less often.' }
+        : { ok: false, error: 'authorization_pending', description: 'Waiting for approval.' }
+    }
+    const user = row.userId === null ? undefined : await this.#store.findUserById(row.userId)
+    if (!user || user.isLockedOut || !user.isApproved)
+      return { ok: false, error: 'access_denied', description: 'This account cannot sign in.' }
+    const sessionId = crypto.randomUUID()
+    if (!(await this.#store.devices.issued(row.id, sessionId)))
+      return { ok: false, error: 'invalid_grant', description: 'This device code has been used.' }
+    await this.#store.recordLoginSuccess(user.id, sessionId)
+    return { ok: true, grant: await this.#issue(user.id, sessionId, clientId, row.scope), user }
+  }
+
+  /** The devices signed in as this user. */
+  signedInDevices(userId: number): Promise<SignedInDevice[]> {
+    return this.#store.devices.signedIn(userId)
+  }
+
+  /** Signs a device out, ending its session; false when it is not this user's. */
+  async revokeDevice(id: number, userId: number): Promise<boolean> {
+    const row = await this.#store.devices.byId(id)
+    if (!row || row.userId !== userId || !row.sessionId) return false
+    await this.#store.endSession(row.sessionId)
+    return true
+  }
+
   async #issue(
     userId: number,
     sessionId: string,

package/src/short-lived.ts

@@ -0,0 +1,33 @@
+/**
+ * A small signed token for a step between two requests — the browser holding
+ * it while it fetches a two-factor code, say — so nothing is stored server
+ * side. HS256 with the site's own key; it expires on its own.
+ */
+import { type JWTPayload, jwtVerify, SignJWT } from 'jose'
+
+const keyOf = (secret: string) => new TextEncoder().encode(secret)
+
+export async function signShortLived(
+  secret: string,
+  payload: Record<string, string | number>,
+  seconds: number,
+): Promise<string> {
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(`${seconds}s`)
+    .sign(keyOf(secret))
+}
+
+/** The payload back, or undefined when the token is missing, altered or expired. */
+export async function readShortLived(
+  secret: string,
+  value: string | undefined,
+): Promise<JWTPayload | undefined> {
+  if (!value) return undefined
+  try {
+    return (await jwtVerify(value, keyOf(secret), { algorithms: ['HS256'] })).payload
+  } catch {
+    return undefined
+  }
+}

package/src/store.ts

@@ -5,6 +5,7 @@
  * usable credential.
  */
 import { type Db, DbDate, fromDbBool, Locks } from '@crombolo/data'
+import { DeviceStore } from './device.ts'
 import { hashToken } from './pkce.ts'
 
 export interface UserRow {
@@ -88,9 +89,12 @@ const USER_COLUMNS =
 
 export class AuthStore {
   #db: Db
+  /** Device sign-ins (story 107), beside the sessions they become. */
+  readonly devices: DeviceStore
 
   constructor(db: Db) {
     this.#db = db
+    this.devices = new DeviceStore(db)
   }
 
   async findUserByLogin(login: string): Promise<UserRow | undefined> {

package/src/totp.ts

@@ -0,0 +1,136 @@
+/**
+ * Time-based one-time passwords for two-factor sign-in (story 032): RFC 6238
+ * over HMAC-SHA1, 30-second steps and 6 digits, which is what every
+ * authenticator app expects. A code one step either side of now is accepted for
+ * clock drift; a code at or before the last step used is refused, so a code seen
+ * over someone's shoulder cannot be used again.
+ *
+ * Recovery codes stand in for a code once each, and are kept only as hashes.
+ */
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { renderSVG } from 'uqr'
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+export const TOTP_STEP_SECONDS = 30
+export const TOTP_DIGITS = 6
+
+/** Bytes as base32 (RFC 4648, no padding), the form authenticator apps read. */
+export function base32Encode(bytes: Uint8Array): string {
+  let bits = 0
+  let value = 0
+  let out = ''
+  for (const byte of bytes) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      out += ALPHABET[(value >>> (bits - 5)) & 31]
+      bits -= 5
+    }
+  }
+  if (bits > 0) out += ALPHABET[(value << (5 - bits)) & 31]
+  return out
+}
+
+/** Base32 back to bytes; spaces and lower case, as people type it, are fine. */
+export function base32Decode(text: string): Uint8Array {
+  const clean = text.replace(/[\s=-]/g, '').toUpperCase()
+  let bits = 0
+  let value = 0
+  const out: number[] = []
+  for (const char of clean) {
+    const index = ALPHABET.indexOf(char)
+    if (index < 0) throw new Error('not base32')
+    value = (value << 5) | index
+    bits += 5
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 255)
+      bits -= 8
+    }
+  }
+  return Uint8Array.from(out)
+}
+
+/** A new secret: 20 random bytes, as RFC 4226 recommends for HMAC-SHA1. */
+export function generateTotpSecret(): string {
+  return base32Encode(randomBytes(20))
+}
+
+/** The step a moment falls in. */
+export const totpStep = (at: Date = new Date()) =>
+  Math.floor(at.getTime() / 1000 / TOTP_STEP_SECONDS)
+
+/** The code for a step (RFC 4226's HOTP over the step counter). */
+export function totpCode(secret: Uint8Array, step: number, digits = TOTP_DIGITS): string {
+  const counter = Buffer.alloc(8)
+  counter.writeBigUInt64BE(BigInt(step))
+  const hmac = createHmac('sha1', secret).update(counter).digest()
+  const offset = (hmac[hmac.length - 1] as number) & 0x0f
+  const binary = (hmac.readUInt32BE(offset) & 0x7fffffff) % 10 ** digits
+  return binary.toString().padStart(digits, '0')
+}
+
+/**
+ * The step a code matches, within one step of now and after the last step used;
+ * undefined for a wrong, stale or reused code.
+ */
+export function verifyTotp(
+  secretBase32: string,
+  code: string,
+  options: { at?: Date; lastUsedStep?: number | null } = {},
+): number | undefined {
+  const digits = code.replace(/\s/g, '')
+  if (!/^\d{6}$/.test(digits)) return undefined
+  let secret: Uint8Array
+  try {
+    secret = base32Decode(secretBase32)
+  } catch {
+    return undefined
+  }
+  const now = totpStep(options.at)
+  for (const step of [now, now - 1, now + 1]) {
+    if (
+      options.lastUsedStep !== undefined &&
+      options.lastUsedStep !== null &&
+      step <= options.lastUsedStep
+    )
+      continue
+    const expected = Buffer.from(totpCode(secret, step))
+    if (timingSafeEqual(expected, Buffer.from(digits))) return step
+  }
+  return undefined
+}
+
+/** The `otpauth://` URI an authenticator app reads from the QR code. */
+export function otpauthUri(options: { secret: string; account: string; issuer: string }): string {
+  const label = encodeURIComponent(`${options.issuer}:${options.account}`)
+  const query = new URLSearchParams({
+    secret: options.secret,
+    issuer: options.issuer,
+    algorithm: 'SHA1',
+    digits: String(TOTP_DIGITS),
+    period: String(TOTP_STEP_SECONDS),
+  })
+  return `otpauth://totp/${label}?${query}`
+}
+
+/** The QR code for an `otpauth` URI, as an SVG `data:` URL an `<img>` can show. */
+export function qrCodeDataUrl(text: string): string {
+  const svg = renderSVG(text, { border: 2 })
+  return `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`
+}
+
+const RECOVERY_ALPHABET = 'abcdefghjkmnpqrstuvwxyz23456789'
+
+/** Ten recovery codes, `xxxxx-xxxxx`, from an alphabet with nothing to confuse. */
+export function generateRecoveryCodes(count = 10): string[] {
+  return Array.from({ length: count }, () => {
+    const bytes = randomBytes(10)
+    const chars = Array.from(bytes, (b) => RECOVERY_ALPHABET[b % RECOVERY_ALPHABET.length])
+    return `${chars.slice(0, 5).join('')}-${chars.slice(5).join('')}`
+  })
+}
+
+/** How a recovery code is stored, and looked up: its SHA-256, ignoring case and spacing. */
+export function hashRecoveryCode(code: string): string {
+  return createHash('sha256').update(code.replace(/[\s-]/g, '').toLowerCase()).digest('hex')
+}