@better-forge/auth 0.0.0-stage → 0.1.0

package/src/routeScope.ts

@@ -0,0 +1,50 @@
+import type { FastifyInstance } from 'fastify'
+
+/**
+ * Marks every route registered in `scope` as belonging to a part of the API, which is what an API token is checked
+ * against (`<part>:read` for GET, `<part>:write` otherwise). A route without a part is refused to every token.
+ */
+export function belongsTo(scope: FastifyInstance, part: string): void {
+  scope.addHook('onRoute', (route) => { route.config = { ...route.config, tokenScope: part } })
+}
+
+/** Lets (or, with `false`, stops) the routes registered in `scope` accept an API token. Routes accept none by default. */
+export function acceptApiTokens(scope: FastifyInstance, accept = true): void {
+  scope.addHook('onRoute', (route) => { route.config = { ...route.config, allowApiToken: accept } })
+}
+
+type RoutePlugin = (scope: FastifyInstance) => Promise<void> | void
+type Guard = (...args: never[]) => unknown
+
+/** A group of routes that share a guard and, usually, a part of the API tokens are checked against. */
+export interface AdminRouteGroup {
+  /** The part of the API the routes belong to. Omit it for a group whose routes no token reaches. */
+  part?: string
+  /** The group refuses API tokens even though the rest of the API accepts them. */
+  noTokens?: boolean
+  /** Runs before every route of the group (the role the group needs). */
+  guard: Guard
+  /** The route plugins of the group with the prefix each is mounted at. */
+  routes: ReadonlyArray<readonly [plugin: RoutePlugin, options: { prefix: string }]>
+}
+
+/**
+ * Registers the admin API: the scope accepts API tokens and needs a signed-in caller (`authenticate`), then every group
+ * gets its own scope with its part, its guard and its routes. A token is checked against the part of the group a route
+ * is in; a group with `noTokens` is for what a leaked token must never reach.
+ */
+export async function registerAdminApi(
+  adminApp: FastifyInstance,
+  options: { authenticate: Guard; groups: readonly AdminRouteGroup[] },
+): Promise<void> {
+  acceptApiTokens(adminApp)
+  adminApp.addHook('preHandler', options.authenticate as never)
+  for (const group of options.groups) {
+    await adminApp.register(async (scope) => {
+      if (group.noTokens) acceptApiTokens(scope, false)
+      if (group.part !== undefined) belongsTo(scope, group.part)
+      scope.addHook('preHandler', group.guard as never)
+      for (const [plugin, routeOptions] of group.routes) await scope.register(plugin, routeOptions)
+    })
+  }
+}

package/src/sessions.ts

@@ -0,0 +1,209 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import { and, eq, lt, ne } from 'drizzle-orm'
+import { authSessions, users } from './tables.js'
+import type { AuthOptions } from './context.js'
+import type { ApiTokens } from './apiTokens.js'
+
+const SESSION_SECONDS = 12 * 60 * 60
+
+export type AuthMethod = 'password' | 'oidc'
+
+export interface AuthIdentity {
+  userId: number
+  email: string
+  role: string
+  sessionId: string
+  mustChangePassword: boolean
+  twoFactorEnabled: boolean
+  authMethod: AuthMethod
+  /**
+   * Set when the request is authenticated by an API token instead of a session. A token belongs to no user: `userId`
+   * is 0, `email` is `token: <name>` (it names the token in the audit log) and `sessionId` is a synthetic
+   * `api-token:<id>`. A token has no role: `role` is a placeholder
+   * that lets it through the role checks, and what it may do is decided by `scopes`, checked for every request in
+   * authenticateOrReject.
+   */
+  apiToken?: { id: number; name: string; scopes: string[] }
+}
+
+export interface AuthenticateOptions {
+  /** API tokens are only accepted on routes that opt in; everywhere else they are refused. */
+  allowApiToken?: boolean
+}
+
+export const API_TOKEN_NOT_ACCEPTED = 'API token not accepted here'
+
+interface SessionClaims {
+  userId: number
+  email: string
+  role: string
+  sessionId: string
+}
+
+export function createSessions(ctx: AuthOptions, apiTokens: ApiTokens) {
+  const { db, roles } = ctx
+  const hooks = ctx.hooks ?? {}
+  const SESSION_COOKIE = ctx.cookies.session
+  const CSRF_COOKIE = ctx.cookies.csrf
+  const { findUsableApiToken, isApiToken, parseScopes } = apiTokens
+
+  function cookieOptions(httpOnly: boolean) {
+    return {
+      path: '/',
+      httpOnly,
+      secure: ctx.secureCookies(),
+      sameSite: 'strict' as const,
+      maxAge: SESSION_SECONDS,
+    }
+  }
+
+  function hash(value: string): string {
+    return createHash('sha256').update(value).digest('hex')
+  }
+
+  function equalHash(left: string, right: string): boolean {
+    const a = Buffer.from(left)
+    const b = Buffer.from(right)
+    return a.length === b.length && timingSafeEqual(a, b)
+  }
+
+  async function createAuthSession(
+    app: FastifyInstance,
+    reply: FastifyReply,
+    user: { id: number; email: string; role: string; mustChangePassword: number; totpEnabled: number },
+    authMethod: AuthMethod = 'password',
+  ): Promise<AuthIdentity> {
+    const now = Date.now()
+    const sessionId = randomUUID()
+    const csrfToken = randomBytes(32).toString('base64url')
+    const expiresAt = now + SESSION_SECONDS * 1000
+    await db.delete(authSessions).where(lt(authSessions.expiresAt, now))
+    await db.insert(authSessions).values({
+      id: sessionId,
+      userId: user.id,
+      csrfTokenHash: hash(csrfToken),
+      createdAt: now,
+      lastSeenAt: now,
+      expiresAt,
+      authMethod,
+      verifiedAt: now,
+    })
+
+    const role = roles.normalize(user.role)
+    const token = app.jwt.sign({ userId: user.id, email: user.email, role, sessionId })
+    reply.setCookie(SESSION_COOKIE, token, cookieOptions(true))
+    reply.setCookie(CSRF_COOKIE, csrfToken, cookieOptions(false))
+    return {
+      userId: user.id,
+      email: user.email,
+      role,
+      sessionId,
+      mustChangePassword: mustChangePassword(user, authMethod),
+      twoFactorEnabled: !!user.totpEnabled,
+      authMethod,
+    }
+  }
+
+  /**
+   * A password session must replace a pending temporary password, so the one the administrator handed out stops
+   * working. An SSO session never has to: the SSO sign-in makes the temporary password unusable instead.
+   */
+  function mustChangePassword(user: { mustChangePassword: number }, authMethod: string): boolean {
+    return !!user.mustChangePassword && authMethod !== 'oidc'
+  }
+
+  function clearAuthCookies(reply: FastifyReply): void {
+    const base = { path: '/', secure: ctx.secureCookies(), sameSite: 'strict' as const }
+    reply.clearCookie(SESSION_COOKIE, { ...base, httpOnly: true })
+    reply.clearCookie(CSRF_COOKIE, { ...base, httpOnly: false })
+  }
+
+  function requestToken(req: FastifyRequest): string | null {
+    const authorization = req.headers.authorization
+    if (authorization?.startsWith('Bearer ')) return authorization.slice(7)
+    return req.cookies[SESSION_COOKIE] ?? null
+  }
+
+  async function authenticateApiToken(req: FastifyRequest, token: string): Promise<AuthIdentity> {
+    const found = await findUsableApiToken(token)
+    if (!found) throw new Error('Invalid API token')
+    const identity: AuthIdentity = {
+      userId: 0,
+      email: `token: ${found.name}`,
+      role: 'admin',
+      sessionId: `api-token:${found.id}`,
+      mustChangePassword: false,
+      twoFactorEnabled: false,
+      authMethod: 'password',
+      apiToken: { id: found.id, name: found.name, scopes: parseScopes(found.scopes) },
+    }
+    req.user = identity
+    return identity
+  }
+
+  async function authenticateRequest(req: FastifyRequest, options: AuthenticateOptions = {}): Promise<AuthIdentity> {
+    const token = requestToken(req)
+    if (!token) throw new Error('Missing session')
+    if (isApiToken(token)) {
+      if (!options.allowApiToken) throw new Error(API_TOKEN_NOT_ACCEPTED)
+      return authenticateApiToken(req, token)
+    }
+    const claims = req.server.jwt.verify<SessionClaims>(token)
+    if (!claims.sessionId || !Number.isInteger(claims.userId)) throw new Error('Invalid session')
+
+    const now = Date.now()
+    const session = (await db.select().from(authSessions).where(eq(authSessions.id, claims.sessionId)))[0]
+    if (!session || session.userId !== claims.userId || session.expiresAt <= now) {
+      if (session) await db.delete(authSessions).where(eq(authSessions.id, session.id))
+      throw new Error('Expired session')
+    }
+    const user = (await db.select().from(users).where(eq(users.id, claims.userId)))[0]
+    if (!user) throw new Error('Unknown user')
+
+    if (now - session.lastSeenAt >= 60_000) {
+      await db.update(authSessions).set({ lastSeenAt: now }).where(eq(authSessions.id, session.id))
+    }
+    const identity: AuthIdentity = {
+      userId: user.id,
+      email: user.email,
+      role: roles.normalize(user.role),
+      sessionId: session.id,
+      mustChangePassword: mustChangePassword(user, session.authMethod),
+      twoFactorEnabled: !!user.totpEnabled,
+      authMethod: session.authMethod === 'oidc' ? 'oidc' : 'password',
+    }
+    req.user = identity
+    return identity
+  }
+
+  async function verifyCsrf(req: FastifyRequest, identity: AuthIdentity): Promise<void> {
+    if (req.headers.authorization?.startsWith('Bearer ')) return
+    if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) return
+    const cookie = req.cookies[CSRF_COOKIE]
+    const header = req.headers['x-csrf-token']
+    if (!cookie || typeof header !== 'string' || !equalHash(hash(cookie), hash(header))) {
+      throw new Error('Invalid CSRF token')
+    }
+    const session = (await db.select({ csrfTokenHash: authSessions.csrfTokenHash })
+      .from(authSessions).where(eq(authSessions.id, identity.sessionId)))[0]
+    if (!session || !equalHash(session.csrfTokenHash, hash(header))) throw new Error('Invalid CSRF token')
+  }
+
+  async function revokeSession(sessionId: string): Promise<void> {
+    await db.delete(authSessions).where(eq(authSessions.id, sessionId))
+    hooks.onSessionsRevoked?.({ sessionId })
+  }
+
+  async function revokeUserSessions(userId: number, exceptSessionId?: string): Promise<void> {
+    const condition = exceptSessionId
+      ? and(eq(authSessions.userId, userId), ne(authSessions.id, exceptSessionId))
+      : eq(authSessions.userId, userId)
+    await db.delete(authSessions).where(condition)
+    hooks.onSessionsRevoked?.({ userId, exceptSessionId })
+  }
+
+  return { createAuthSession, clearAuthCookies, authenticateRequest, verifyCsrf, revokeSession, revokeUserSessions }
+}
+
+export type Sessions = ReturnType<typeof createSessions>

package/src/setupRoutes.ts

@@ -0,0 +1,100 @@
+import type { FastifyInstance, FastifyReply } from 'fastify'
+import bcrypt from 'bcryptjs'
+import { eq } from 'drizzle-orm'
+import type { SqliteDatabase } from '@better-forge/db'
+import { users } from './tables.js'
+
+export interface SetupRoutesOptions<Identity extends { sessionId?: string }> {
+  db: SqliteDatabase
+  /** Runs `work` so that all of it is written, or none of it. */
+  withTransaction: <T>(work: () => Promise<T>) => Promise<T>
+  isSetupComplete: () => boolean
+  /** Records that setup is done. Called as the last step inside the transaction: if it throws, the administrator is not kept. */
+  writeSetupComplete: () => void
+  /** Takes the record back, when the transaction fails to commit after it was written. */
+  removeSetupMarker: () => void
+  /** Opens the database and brings its tables up to date; called once the request has been checked. */
+  prepareDatabase: () => void
+  /** Signs the new administrator in. */
+  createSession: (app: FastifyInstance, reply: FastifyReply, user: typeof users.$inferSelect) => Promise<Identity>
+  /** Rate limit of `POST /complete` (the config the rate limit plugin understands). */
+  rateLimit: Record<string, unknown>
+  /** Writes whatever else the application needs on first run, inside the same transaction as the administrator. */
+  onSetup?: () => Promise<void>
+  /** Starts the work that runs only once the application is set up. */
+  startBackgroundServices?: () => void
+  /** Lets setup run although accounts already exist, for an installation that is filled with accounts before its first run. Checked on each request. */
+  allowExistingUsers?: () => boolean
+}
+
+/**
+ * The first-run routes: whether the application still needs setup, and the one request that creates the administrator
+ * and finishes it. Setup is refused once it is done, and only one attempt runs at a time.
+ */
+export function createSetupRoutes<Identity extends { sessionId?: string }>(options: SetupRoutesOptions<Identity>) {
+  const { db } = options
+  let inProgress = false
+
+  return async function setupRoutes(app: FastifyInstance, overrides: { startBackgroundServices?: () => void } = {}) {
+    app.get('/status', async () => ({ needsSetup: !options.isSetupComplete() }))
+
+    app.post<{ Body: { email: string; password: string } }>('/complete', {
+      config: { rateLimit: options.rateLimit },
+    }, async (req, reply) => {
+      if (options.isSetupComplete()) {
+        return reply.code(409).send({ error: 'Setup already completed' })
+      }
+
+      const { email, password } = req.body ?? {}
+      if (typeof email !== 'string' || typeof password !== 'string' || !email || !password) {
+        return reply.code(400).send({ error: 'Email and password are required' })
+      }
+      if (email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        return reply.code(400).send({ error: 'A valid email address is required' })
+      }
+      if (password.length < 8 || password.length > 128) {
+        return reply.code(400).send({ error: 'Password must be between 8 and 128 characters' })
+      }
+
+      if (inProgress) {
+        return reply.code(409).send({ error: 'Setup is already in progress' })
+      }
+
+      inProgress = true
+      try {
+        // Initialize DB and run migrations now that we have a confirmed DB type
+        options.prepareDatabase()
+
+        const hash = await bcrypt.hash(password, 10)
+        let setupMarkerWritten = false
+        const user = await options.withTransaction(async () => {
+          // The marker can be missing while the data is not (a lost volume, a restore). Accounts that already
+          // exist mean setup was done: never create or overwrite an administrator over them.
+          if (!options.allowExistingUsers?.() && (await db.select({ id: users.id }).from(users).limit(1)).length > 0) return null
+
+          await db.insert(users).values({ email, passwordHash: hash, role: 'admin', createdAt: Date.now() })
+
+          await options.onSetup?.()
+
+          const admin = (await db.select().from(users).where(eq(users.email, email)))[0]!
+          // Last step: if writing the marker fails the admin insert rolls back with it.
+          options.writeSetupComplete()
+          setupMarkerWritten = true
+          return admin
+        }).catch((error: unknown) => {
+          // COMMIT itself failed after the marker was written — undo it so setup can be retried.
+          if (setupMarkerWritten) options.removeSetupMarker()
+          throw error
+        })
+        if (!user) return reply.code(409).send({ error: 'Setup already completed' })
+        const startServices = overrides.startBackgroundServices ?? options.startBackgroundServices
+        startServices?.()
+        const identity = await options.createSession(app, reply, user)
+        const { sessionId: _sessionId, ...safeIdentity } = identity
+        return safeIdentity
+      } finally {
+        inProgress = false
+      }
+    })
+  }
+}

package/src/signInAudit.ts

@@ -0,0 +1,43 @@
+import type { AuthOptions } from './context.js'
+
+/** How the user tried to sign in, as recorded in `diff.method` of 'sign_in' audit entries. */
+export type SignInMethod = 'password' | 'sso'
+
+/** Why a password, or the authentication-code step of any sign-in, was refused. SSO refusals use the OIDC codes. */
+export type CredentialDenialCode =
+  | 'password_login_disabled'
+  | 'no_matching_account'
+  | 'wrong_password'
+  | 'two_factor_expired'
+  | 'invalid_two_factor_code'
+
+export interface SignInDenial {
+  code: string
+  reason: string
+  email?: string | undefined
+}
+
+export function createSignInAudit(ctx: AuthOptions) {
+  const { audit } = ctx
+
+  /** Records a successful sign-in; `twoFactor` says whether an authentication code was part of it. */
+  async function auditSignIn(user: { id: number; email: string }, method: SignInMethod, twoFactor: boolean): Promise<void> {
+    await audit.write({ userId: user.id, userEmail: user.email }, 'allow', 'sign_in', user.id, user.email, { method, twoFactor })
+  }
+
+  /**
+   * Records a refused sign-in. Nobody is signed in, so the actor is user 0 with the email that was entered or that
+   * the provider asserted, when there was one. The user only ever sees a generic message; this holds the reason.
+   */
+  async function auditSignInDenial(method: SignInMethod, denial: SignInDenial, extra: Record<string, unknown> = {}): Promise<void> {
+    await audit.write(
+      { userId: 0, userEmail: denial.email ?? `unknown (${method === 'sso' ? 'SSO' : 'password'})` },
+      'deny', 'sign_in', null, denial.email ?? (method === 'sso' ? 'SSO sign-in' : 'Password sign-in'),
+      { method, code: denial.code, reason: denial.reason, ...extra },
+    )
+  }
+
+  return { auditSignIn, auditSignInDenial }
+}
+
+export type SignInAudit = ReturnType<typeof createSignInAudit>

package/src/tables.ts

@@ -0,0 +1,59 @@
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  email: text('email').notNull().unique(),
+  passwordHash: text('password_hash').notNull(),
+  role: text('role').notNull().default('admin'),
+  createdAt: integer('created_at').notNull(),
+  // Additive columns (added via ALTER TABLE, must stay at end for sqlite-proxy position mapping)
+  mustChangePassword: integer('must_change_password').notNull().default(0),
+  totpSecret: text('totp_secret'),
+  totpEnabled: integer('totp_enabled').notNull().default(0),
+  totpRecoveryCodes: text('totp_recovery_codes'),
+  // SSO identity bound on the first OIDC sign-in; later sign-ins match on it instead of the email.
+  oidcIssuer: text('oidc_issuer'),
+  oidcSubject: text('oidc_subject'),
+})
+
+export const authSessions = sqliteTable('auth_sessions', {
+  id: text('id').primaryKey(),
+  userId: integer('user_id').notNull(),
+  csrfTokenHash: text('csrf_token_hash').notNull(),
+  createdAt: integer('created_at').notNull(),
+  lastSeenAt: integer('last_seen_at').notNull(),
+  expiresAt: integer('expires_at').notNull(),
+  // 'password' or 'oidc'. An SSO session never asks for the temporary password to be changed.
+  authMethod: text('auth_method').notNull().default('password'),
+  // When the user last proved who they are in this session: the sign-in, or a later SSO confirmation.
+  verifiedAt: integer('verified_at'),
+})
+
+/** Long-lived bearer credentials for scripts and CI. Only the SHA-256 of the token is stored; revoking deletes the row. */
+export const apiTokens = sqliteTable('api_tokens', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  tokenHash: text('token_hash').notNull().unique(),
+  /** Leading characters of the token, so it can be recognised in the list. */
+  prefix: text('prefix').notNull(),
+  createdAt: integer('created_at').notNull(),
+  expiresAt: integer('expires_at'),
+  lastUsedAt: integer('last_used_at'),
+  /** JSON list of what the token may do, e.g. `["notes:write","tags:read"]` (the permissions are defined by the application). */
+  scopes: text('scopes').notNull(),
+})
+
+export const oidcSettings = sqliteTable('oidc_settings', {
+  id: integer('id').primaryKey(),
+  enabled: integer('enabled').notNull().default(0),
+  issuer: text('issuer').notNull().default(''),
+  clientId: text('client_id').notNull().default(''),
+  /** Stored encrypted by the application's secret box; empty when no secret is set. */
+  clientSecret: text('client_secret').notNull().default(''),
+  scopes: text('scopes').notNull().default(''),
+  redirectUri: text('redirect_uri').notNull().default(''),
+  buttonLabel: text('button_label').notNull().default(''),
+  allowUnverifiedEmail: integer('allow_unverified_email').notNull().default(0),
+  disablePasswordLogin: integer('disable_password_login').notNull().default(0),
+  updatedAt: integer('updated_at').notNull(),
+})

package/src/tokenCatalogue.ts

@@ -0,0 +1,42 @@
+import type { TokenPreset, TokenResource } from '@better-forge/contracts'
+import { VAULT_USE_SCOPE, normalizeScopes } from '@better-forge/contracts'
+
+export interface TokenCatalogue {
+  /** Every permission a token can hold, in the order they are listed: `<part>:read`, `<part>:write`, then the extra ones. */
+  readonly scopes: readonly string[]
+  readonly resources: readonly TokenResource[]
+  readonly presets: readonly TokenPreset[]
+  /** A clean list of known permissions (reading added wherever writing is granted), or null if one is unknown or none is given. */
+  normalize(input: unknown): string[] | null
+  /** The permissions stored with a token. Anything that is not a known permission is dropped. */
+  parse(stored: string): string[]
+}
+
+/**
+ * The permissions an API token can be given. A part is a group of routes (`belongsTo(scope, part)` ties routes to
+ * it); `extraScopes` are single permissions that belong to no part, such as the one to use vault secrets.
+ */
+export function createTokenCatalogue(options: {
+  resources: readonly TokenResource[]
+  extraScopes?: readonly string[]
+  presets?: (scopes: readonly string[]) => readonly TokenPreset[]
+}): TokenCatalogue {
+  const scopes = [
+    ...options.resources.flatMap((resource) => resource.levels.map((level) => `${resource.key}:${level}`)),
+    ...(options.extraScopes ?? [VAULT_USE_SCOPE]),
+  ]
+  return {
+    scopes,
+    resources: options.resources,
+    presets: options.presets?.(scopes) ?? [],
+    normalize: (input) => normalizeScopes(input, scopes),
+    parse(stored) {
+      try {
+        const parsed: unknown = JSON.parse(stored)
+        return Array.isArray(parsed) ? parsed.filter((scope): scope is string => typeof scope === 'string' && scopes.includes(scope)) : []
+      } catch {
+        return []
+      }
+    },
+  }
+}

package/src/totp.ts

@@ -0,0 +1,96 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+const PERIOD_SECONDS = 30
+const DIGITS = 6
+
+function encodeBase32(input: Buffer): string {
+  let bits = 0
+  let value = 0
+  let output = ''
+  for (const byte of input) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      output += ALPHABET[(value >>> (bits - 5)) & 31]
+      bits -= 5
+    }
+  }
+  if (bits > 0) output += ALPHABET[(value << (5 - bits)) & 31]
+  return output
+}
+
+function decodeBase32(input: string): Buffer {
+  let bits = 0
+  let value = 0
+  const bytes: number[] = []
+  for (const character of input.toUpperCase().replace(/=|\s|-/g, '')) {
+    const index = ALPHABET.indexOf(character)
+    if (index < 0) throw new Error('Invalid base32 secret')
+    value = (value << 5) | index
+    bits += 5
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 255)
+      bits -= 8
+    }
+  }
+  return Buffer.from(bytes)
+}
+
+function codeAt(secret: string, counter: number): string {
+  const buffer = Buffer.alloc(8)
+  buffer.writeBigUInt64BE(BigInt(counter))
+  const digest = createHmac('sha1', decodeBase32(secret)).update(buffer).digest()
+  const offset = digest[digest.length - 1]! & 0x0f
+  const binary = ((digest[offset]! & 0x7f) << 24)
+    | ((digest[offset + 1]! & 0xff) << 16)
+    | ((digest[offset + 2]! & 0xff) << 8)
+    | (digest[offset + 3]! & 0xff)
+  return String(binary % (10 ** DIGITS)).padStart(DIGITS, '0')
+}
+
+function safeEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left)
+  const b = Buffer.from(right)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+export function generateTotpSecret(): string {
+  return encodeBase32(randomBytes(20))
+}
+
+export function verifyTotp(secret: string, input: string, now = Date.now()): boolean {
+  const normalized = input.replace(/\s/g, '')
+  const counter = Math.floor(now / 1000 / PERIOD_SECONDS)
+  return [-1, 0, 1].some((offset) => safeEqual(codeAt(secret, counter + offset), normalized))
+}
+
+export function generateTotpCode(secret: string, now = Date.now()): string {
+  return codeAt(secret, Math.floor(now / 1000 / PERIOD_SECONDS))
+}
+
+/** The `otpauth://` URI an authenticator app scans; `issuer` is the name it shows next to the account. */
+export function totpUri(secret: string, email: string, issuer: string): string {
+  const label = `${issuer}:${email}`
+  return `otpauth://totp/${encodeURIComponent(label)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=${DIGITS}&period=${PERIOD_SECONDS}`
+}
+
+export function generateRecoveryCodes(): string[] {
+  return Array.from({ length: 8 }, () => {
+    const value = randomBytes(10).toString('hex').toUpperCase()
+    return value.match(/.{1,5}/g)!.join('-')
+  })
+}
+
+export function hashRecoveryCode(code: string): string {
+  return createHash('sha256').update(code.replace(/\s|-/g, '').toUpperCase()).digest('hex')
+}
+
+export function consumeRecoveryCode(storedJson: string | null, input: string): { valid: boolean; remaining: string[] } {
+  let stored: string[]
+  try { stored = JSON.parse(storedJson ?? '[]') as string[] } catch { return { valid: false, remaining: [] } }
+  const candidate = hashRecoveryCode(input)
+  const index = stored.findIndex((hash) => safeEqual(hash, candidate))
+  if (index < 0) return { valid: false, remaining: stored }
+  return { valid: true, remaining: stored.filter((_, itemIndex) => itemIndex !== index) }
+}

package/src/twoFactor.ts

@@ -0,0 +1,49 @@
+import { and, eq } from 'drizzle-orm'
+import { withImmediateTransaction } from '@better-forge/db'
+import { consumeRecoveryCode, verifyTotp } from './totp.js'
+import { authSessions, users } from './tables.js'
+import type { AuthOptions } from './context.js'
+
+type TwoFactorUser = Pick<typeof users.$inferSelect, 'id' | 'totpEnabled' | 'totpSecret' | 'totpRecoveryCodes'>
+
+export function createTwoFactor(ctx: AuthOptions) {
+  const { db, sqlite, secretBox } = ctx
+
+  /**
+   * Verify a TOTP or consume a recovery code. Recovery-code persistence uses a
+   * compare-and-swap update so the same code cannot win in concurrent requests.
+   */
+  async function verifySecondFactor(user: TwoFactorUser, code: string): Promise<boolean> {
+    if (!user.totpEnabled || !user.totpSecret) return false
+    if (verifyTotp(secretBox.decrypt(user.totpSecret), code)) return true
+
+    const storedCodes = user.totpRecoveryCodes
+    const recovery = consumeRecoveryCode(storedCodes, code)
+    if (!storedCodes || !recovery.valid) return false
+
+    const updated = await db.update(users)
+      .set({ totpRecoveryCodes: JSON.stringify(recovery.remaining) })
+      .where(and(eq(users.id, user.id), eq(users.totpRecoveryCodes, storedCodes)))
+      .returning({ id: users.id })
+    return updated.length === 1
+  }
+
+  /** Clear 2FA credentials and revoke every active session for the user. */
+  async function resetTwoFactor(userId: number): Promise<boolean> {
+    return withImmediateTransaction(sqlite, async () => {
+      const updated = await db.update(users).set({
+        totpSecret: null,
+        totpEnabled: 0,
+        totpRecoveryCodes: null,
+      }).where(and(eq(users.id, userId), eq(users.totpEnabled, 1)))
+        .returning({ id: users.id })
+      if (updated.length !== 1) return false
+      await db.delete(authSessions).where(eq(authSessions.userId, userId))
+      return true
+    })
+  }
+
+  return { verifySecondFactor, resetTwoFactor }
+}
+
+export type TwoFactor = ReturnType<typeof createTwoFactor>