@crombolo/auth 0.13.1 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "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.1",
-    "@crombolo/data": "0.13.1"
+    "@crombolo/core": "0.14.1",
+    "@crombolo/data": "0.14.1",
+    "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/index.ts

@@ -1,9 +1,12 @@
 export * from './admin.ts'
 export * from './cookies.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

@@ -17,8 +17,12 @@ import {
 } from './cookies.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`
 
 export interface AuthRouteOptions {
@@ -27,6 +31,13 @@ export interface AuthRouteOptions {
   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 {
@@ -281,6 +292,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 +336,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 +370,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))
@@ -371,13 +458,8 @@ 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)
       return undefined
     },
   }

package/src/service.ts

@@ -45,7 +45,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 {
@@ -114,7 +114,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 +165,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,

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/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')
+}