@prsm/auth 1.0.0

package/src/schema.js

@@ -0,0 +1,261 @@
+/**
+ * @typedef {import("./types.js").AuthConfig} AuthConfig
+ */
+
+/**
+ * Create all auth tables and indexes. Must run before the first request uses auth.
+ * @param {AuthConfig} config
+ * @returns {Promise<void>}
+ */
+export async function createAuthTables(config) {
+  const prefix = config.tablePrefix || "user_"
+  const { db } = config
+
+  const accountsTable = `${prefix}accounts`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${accountsTable} (
+      id SERIAL PRIMARY KEY,
+      user_id VARCHAR(255) NOT NULL,
+      email VARCHAR(255) NOT NULL UNIQUE,
+      password VARCHAR(255),
+      verified BOOLEAN DEFAULT FALSE,
+      status INTEGER DEFAULT 0,
+      rolemask INTEGER DEFAULT 0,
+      last_login TIMESTAMPTZ,
+      force_logout INTEGER DEFAULT 0,
+      resettable BOOLEAN DEFAULT TRUE,
+      registered TIMESTAMPTZ DEFAULT NOW(),
+      CONSTRAINT ${prefix}unique_user_id_per_account UNIQUE(user_id)
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}accounts_user_id ON ${accountsTable}(user_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}accounts_email ON ${accountsTable}(email)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}accounts_status ON ${accountsTable}(status)`)
+
+  const confirmationsTable = `${prefix}confirmations`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${confirmationsTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER NOT NULL,
+      token VARCHAR(255) NOT NULL,
+      email VARCHAR(255) NOT NULL,
+      expires TIMESTAMPTZ NOT NULL,
+      CONSTRAINT fk_${prefix}confirmations_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}confirmations_token ON ${confirmationsTable}(token)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}confirmations_email ON ${confirmationsTable}(email)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}confirmations_account_id ON ${confirmationsTable}(account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}confirmations_expires ON ${confirmationsTable}(expires)`)
+
+  const remembersTable = `${prefix}remembers`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${remembersTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER NOT NULL,
+      token VARCHAR(255) NOT NULL,
+      expires TIMESTAMPTZ NOT NULL,
+      CONSTRAINT fk_${prefix}remembers_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}remembers_token ON ${remembersTable}(token)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}remembers_account_id ON ${remembersTable}(account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}remembers_expires ON ${remembersTable}(expires)`)
+
+  const resetsTable = `${prefix}resets`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${resetsTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER NOT NULL,
+      token VARCHAR(255) NOT NULL,
+      expires TIMESTAMPTZ NOT NULL,
+      CONSTRAINT fk_${prefix}resets_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}resets_token ON ${resetsTable}(token)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}resets_account_id ON ${resetsTable}(account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}resets_expires ON ${resetsTable}(expires)`)
+
+  const providersTable = `${prefix}providers`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${providersTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER NOT NULL,
+      provider VARCHAR(50) NOT NULL,
+      provider_id VARCHAR(255) NOT NULL,
+      provider_email VARCHAR(255),
+      provider_username VARCHAR(255),
+      provider_name VARCHAR(255),
+      provider_avatar VARCHAR(500),
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      updated_at TIMESTAMPTZ DEFAULT NOW(),
+      CONSTRAINT fk_${prefix}providers_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE,
+      CONSTRAINT ${prefix}unique_provider_identity
+        UNIQUE(provider, provider_id)
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}providers_account_id ON ${providersTable}(account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}providers_provider ON ${providersTable}(provider)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}providers_provider_id ON ${providersTable}(provider_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}providers_email ON ${providersTable}(provider_email)`)
+
+  const activityTable = `${prefix}activity_log`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${activityTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER,
+      actor_account_id INTEGER,
+      action VARCHAR(255) NOT NULL,
+      ip_address INET,
+      user_agent TEXT,
+      browser VARCHAR(255),
+      os VARCHAR(255),
+      device VARCHAR(255),
+      success BOOLEAN DEFAULT TRUE,
+      metadata JSONB,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      CONSTRAINT fk_${prefix}activity_log_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE,
+      CONSTRAINT fk_${prefix}activity_log_actor
+        FOREIGN KEY (actor_account_id) REFERENCES ${accountsTable}(id) ON DELETE SET NULL
+    )
+  `)
+
+  // migration for pre-existing deployments that have activity_log without actor_account_id
+  await db.query(`ALTER TABLE ${activityTable} ADD COLUMN IF NOT EXISTS actor_account_id INTEGER`)
+  await db.query(`
+    DO $$
+    BEGIN
+      IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'fk_${prefix}activity_log_actor'
+      ) THEN
+        ALTER TABLE ${activityTable}
+          ADD CONSTRAINT fk_${prefix}activity_log_actor
+          FOREIGN KEY (actor_account_id) REFERENCES ${accountsTable}(id) ON DELETE SET NULL;
+      END IF;
+    END$$;
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}activity_log_created_at ON ${activityTable}(created_at DESC)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}activity_log_account_id ON ${activityTable}(account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}activity_log_actor_account_id ON ${activityTable}(actor_account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}activity_log_action ON ${activityTable}(action)`)
+
+  const twoFactorMethodsTable = `${prefix}2fa_methods`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${twoFactorMethodsTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER NOT NULL,
+      mechanism INTEGER NOT NULL,
+      secret VARCHAR(255),
+      backup_codes TEXT[],
+      verified BOOLEAN DEFAULT FALSE,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      last_used_at TIMESTAMPTZ,
+      CONSTRAINT fk_${prefix}2fa_methods_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE,
+      CONSTRAINT ${prefix}unique_account_mechanism
+        UNIQUE(account_id, mechanism)
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}2fa_methods_account_id ON ${twoFactorMethodsTable}(account_id)`)
+
+  const twoFactorTokensTable = `${prefix}2fa_tokens`
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS ${twoFactorTokensTable} (
+      id SERIAL PRIMARY KEY,
+      account_id INTEGER NOT NULL,
+      mechanism INTEGER NOT NULL,
+      selector VARCHAR(32) NOT NULL,
+      token_hash VARCHAR(255) NOT NULL,
+      expires_at TIMESTAMPTZ NOT NULL,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      CONSTRAINT fk_${prefix}2fa_tokens_account
+        FOREIGN KEY (account_id) REFERENCES ${accountsTable}(id) ON DELETE CASCADE
+    )
+  `)
+
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}2fa_tokens_selector ON ${twoFactorTokensTable}(selector)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}2fa_tokens_account_id ON ${twoFactorTokensTable}(account_id)`)
+  await db.query(`CREATE INDEX IF NOT EXISTS idx_${prefix}2fa_tokens_expires ON ${twoFactorTokensTable}(expires_at)`)
+}
+
+/**
+ * @param {AuthConfig} config
+ * @returns {Promise<void>}
+ */
+export async function dropAuthTables(config) {
+  const prefix = config.tablePrefix || "user_"
+  const { db } = config
+
+  await db.query(`DROP TABLE IF EXISTS ${prefix}2fa_tokens CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}2fa_methods CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}activity_log CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}providers CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}resets CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}remembers CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}confirmations CASCADE`)
+  await db.query(`DROP TABLE IF EXISTS ${prefix}accounts CASCADE`)
+}
+
+/**
+ * @param {AuthConfig} config
+ * @returns {Promise<void>}
+ */
+export async function cleanupExpiredTokens(config) {
+  const prefix = config.tablePrefix || "user_"
+  const { db } = config
+
+  await db.query(`DELETE FROM ${prefix}confirmations WHERE expires < NOW()`)
+  await db.query(`DELETE FROM ${prefix}remembers WHERE expires < NOW()`)
+  await db.query(`DELETE FROM ${prefix}resets WHERE expires < NOW()`)
+  await db.query(`DELETE FROM ${prefix}2fa_tokens WHERE expires_at < NOW()`)
+}
+
+/**
+ * @param {AuthConfig} config
+ * @returns {Promise<{ accounts: number, providers: number, confirmations: number, remembers: number, resets: number, twoFactorMethods: number, twoFactorTokens: number, expiredConfirmations: number, expiredRemembers: number, expiredResets: number, expiredTwoFactorTokens: number }>}
+ */
+export async function getAuthTableStats(config) {
+  const prefix = config.tablePrefix || "user_"
+  const { db } = config
+
+  const [accountsResult, providersResult, confirmationsResult, remembersResult, resetsResult, twoFactorMethodsResult, twoFactorTokensResult, expiredConfirmationsResult, expiredRemembersResult, expiredResetsResult, expiredTwoFactorTokensResult] =
+    await Promise.all([
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}accounts`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}providers`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}confirmations`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}remembers`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}resets`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}2fa_methods`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}2fa_tokens`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}confirmations WHERE expires < NOW()`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}remembers WHERE expires < NOW()`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}resets WHERE expires < NOW()`),
+      db.query(`SELECT COUNT(*) as count FROM ${prefix}2fa_tokens WHERE expires_at < NOW()`),
+    ])
+
+  return {
+    accounts: parseInt(accountsResult.rows[0]?.count || "0"),
+    providers: parseInt(providersResult.rows[0]?.count || "0"),
+    confirmations: parseInt(confirmationsResult.rows[0]?.count || "0"),
+    remembers: parseInt(remembersResult.rows[0]?.count || "0"),
+    resets: parseInt(resetsResult.rows[0]?.count || "0"),
+    twoFactorMethods: parseInt(twoFactorMethodsResult.rows[0]?.count || "0"),
+    twoFactorTokens: parseInt(twoFactorTokensResult.rows[0]?.count || "0"),
+    expiredConfirmations: parseInt(expiredConfirmationsResult.rows[0]?.count || "0"),
+    expiredRemembers: parseInt(expiredRemembersResult.rows[0]?.count || "0"),
+    expiredResets: parseInt(expiredResetsResult.rows[0]?.count || "0"),
+    expiredTwoFactorTokens: parseInt(expiredTwoFactorTokensResult.rows[0]?.count || "0"),
+  }
+}

package/src/totp.js

@@ -0,0 +1,221 @@
+import * as crypto from "node:crypto"
+
+// inlined RFC 6238 TOTP, ported from @eaccess/totp. internal to @prsm/auth -
+// not re-exported, since a standalone totp primitive has no use outside 2fa.
+// base32 (RFC 4648, no padding) is implemented here to avoid a dependency
+
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+
+/**
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ */
+function base32Encode(bytes) {
+  let bits = 0
+  let value = 0
+  let output = ""
+  for (const byte of bytes) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      output += BASE32_ALPHABET[(value >>> (bits - 5)) & 31]
+      bits -= 5
+    }
+    value &= (1 << bits) - 1
+  }
+  if (bits > 0) {
+    output += BASE32_ALPHABET[(value << (5 - bits)) & 31]
+  }
+  return output
+}
+
+/**
+ * decodes a base32 string, ignoring any non-alphabet characters (padding, separators)
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+function base32Decode(str) {
+  let bits = 0
+  let value = 0
+  /** @type {number[]} */
+  const output = []
+  for (const char of str) {
+    const idx = BASE32_ALPHABET.indexOf(char)
+    if (idx === -1) continue
+    value = (value << 5) | idx
+    bits += 5
+    if (bits >= 8) {
+      output.push((value >>> (bits - 8)) & 0xff)
+      bits -= 8
+    }
+    value &= (1 << bits) - 1
+  }
+  return Uint8Array.from(output)
+}
+
+export class InvalidOtpLengthError extends Error {}
+export class InvalidSecretError extends Error {}
+export class InvalidHashFunctionError extends Error {}
+export class InvalidSecretStrengthError extends Error {}
+export class InvalidIntervalError extends Error {}
+
+class Otp {
+  static OTP_LENGTH_MIN = 6
+  static OTP_LENGTH_MAX = 8
+  static OTP_LENGTH_DEFAULT = 6
+  static INTERVAL_LENGTH_DEFAULT = 30
+  static EPOCH_DEFAULT = 0
+  static HASH_FUNCTION_SHA_1 = 1
+  static HASH_FUNCTION_SHA_256 = 2
+  static HASH_FUNCTION_SHA_512 = 3
+  static HASH_FUNCTION_DEFAULT = Otp.HASH_FUNCTION_SHA_1
+  static SHARED_SECRET_STRENGTH_LOW = 1
+  static SHARED_SECRET_STRENGTH_MODERATE = 2
+  static SHARED_SECRET_STRENGTH_HIGH = 3
+
+  /**
+   * Generate a random Base32 shared secret (without padding).
+   * @param {number} [strength] one of the SHARED_SECRET_STRENGTH_* constants, defaults to high (160 bits)
+   * @returns {string}
+   * @throws {InvalidSecretStrengthError}
+   */
+  static createSecret(strength = Otp.SHARED_SECRET_STRENGTH_HIGH) {
+    const bits = this.determineBitsForSharedSecretStrength(strength)
+    const bytes = Math.ceil(bits / 8)
+    const buffer = crypto.randomBytes(bytes)
+    return base32Encode(buffer).replace(/=+$/, "")
+  }
+
+  /**
+   * Build an otpauth:// URI for QR-code provisioning in authenticator apps.
+   * @param {string} issuer
+   * @param {string} accountName
+   * @param {string} secret
+   * @returns {string}
+   */
+  static createTotpKeyUriForQrCode(issuer, accountName, secret) {
+    return `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(accountName)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}`
+  }
+
+  /**
+   * Generate a TOTP value.
+   * @param {string} secret base32 shared secret, at least 16 chars after sanitization
+   * @param {number} [t] unix time in seconds, defaults to now
+   * @param {number} [otpLength] number of digits (6-8), defaults to 6
+   * @param {number} [t_x] time step in seconds, defaults to 30
+   * @param {number} [t_0] epoch start in seconds, defaults to 0
+   * @param {number} [hashFunction] one of the HASH_FUNCTION_* constants, defaults to SHA-1
+   * @returns {string}
+   * @throws {InvalidOtpLengthError|InvalidIntervalError|InvalidSecretError|InvalidHashFunctionError}
+   */
+  static generateTotp(secret, t = Math.floor(Date.now() / 1000), otpLength = Otp.OTP_LENGTH_DEFAULT, t_x = Otp.INTERVAL_LENGTH_DEFAULT, t_0 = Otp.EPOCH_DEFAULT, hashFunction = Otp.HASH_FUNCTION_DEFAULT) {
+    if (otpLength < Otp.OTP_LENGTH_MIN || otpLength > Otp.OTP_LENGTH_MAX) {
+      throw new InvalidOtpLengthError()
+    }
+
+    if (t_x <= 0) {
+      throw new InvalidIntervalError()
+    }
+
+    secret = secret ?? ""
+    t = t ?? Math.floor(Date.now() / 1000)
+
+    const c_t = Math.max(0, Math.floor((t - t_0) / t_x))
+
+    secret = secret.replace(/[^A-Za-z2-7]/g, "").toUpperCase()
+
+    if (secret.length < 16) {
+      throw new InvalidSecretError()
+    }
+
+    const k = base32Decode(secret)
+
+    const counter64BitBigEndian = Buffer.alloc(8)
+    counter64BitBigEndian.writeUInt32BE(Math.floor(c_t / Math.pow(2, 32)), 0)
+    counter64BitBigEndian.writeUInt32BE(c_t % Math.pow(2, 32), 4)
+
+    let hashFunctionNameForHmac
+    switch (hashFunction) {
+      case Otp.HASH_FUNCTION_SHA_1:
+        hashFunctionNameForHmac = "sha1"
+        break
+      case Otp.HASH_FUNCTION_SHA_256:
+        hashFunctionNameForHmac = "sha256"
+        break
+      case Otp.HASH_FUNCTION_SHA_512:
+        hashFunctionNameForHmac = "sha512"
+        break
+      default:
+        throw new InvalidHashFunctionError()
+    }
+
+    const hmac = crypto.createHmac(hashFunctionNameForHmac, Buffer.from(k))
+    hmac.update(counter64BitBigEndian)
+    const mac = hmac.digest()
+
+    const offset = mac[mac.length - 1] & 0x0f
+    const macSubstring4Bytes = mac.slice(offset, offset + 4)
+
+    const integer32Bit = macSubstring4Bytes.readUInt32BE(0) & 0x7fffffff
+
+    const hotp = integer32Bit % Math.pow(10, otpLength)
+
+    return hotp.toString().padStart(otpLength, "0")
+  }
+
+  /**
+   * Verify a user-supplied TOTP across a drift window using a constant-time compare.
+   * @param {string} secret
+   * @param {string} otpValue
+   * @param {number} [lookBehindSteps] defaults to 2
+   * @param {number} [lookAheadSteps] defaults to lookBehindSteps (symmetric)
+   * @param {number} [t]
+   * @param {number} [otpLength]
+   * @param {number} [t_x]
+   * @param {number} [t_0]
+   * @param {number} [hashFunction]
+   * @returns {boolean}
+   */
+  static verifyTotp(secret, otpValue, lookBehindSteps = 2, lookAheadSteps, t = Math.floor(Date.now() / 1000), otpLength = Otp.OTP_LENGTH_DEFAULT, t_x = Otp.INTERVAL_LENGTH_DEFAULT, t_0 = Otp.EPOCH_DEFAULT, hashFunction = Otp.HASH_FUNCTION_DEFAULT) {
+    const ahead = lookAheadSteps ?? lookBehindSteps
+
+    otpValue = otpValue.replace(/[^0-9]/g, "")
+
+    if (otpValue.length < Otp.OTP_LENGTH_MIN || otpValue.length > Otp.OTP_LENGTH_MAX) {
+      return false
+    }
+
+    if (otpValue.length !== otpLength) {
+      return false
+    }
+
+    for (let s = -lookBehindSteps; s <= ahead; s++) {
+      const expectedOtpValue = this.generateTotp(secret, t + t_x * s, otpLength, t_x, t_0, hashFunction)
+      if (crypto.timingSafeEqual(Buffer.from(expectedOtpValue), Buffer.from(otpValue))) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * @param {number} strength
+   * @returns {number}
+   * @throws {InvalidSecretStrengthError}
+   */
+  static determineBitsForSharedSecretStrength(strength) {
+    switch (strength) {
+      case 1:
+        return 80
+      case 2:
+        return 128
+      case 3:
+        return 160
+      default:
+        throw new InvalidSecretStrengthError()
+    }
+  }
+}
+
+export default Otp

package/src/two-factor/index.js

@@ -0,0 +1,3 @@
+export { TwoFactorManager } from "./two-factor-manager.js"
+export { TotpProvider } from "./totp-provider.js"
+export { OtpProvider } from "./otp-provider.js"

package/src/two-factor/otp-provider.js

@@ -0,0 +1,128 @@
+import ms from "@prsm/ms"
+import hash from "@prsm/hash"
+import { AuthQueries } from "../queries.js"
+
+/**
+ * @typedef {import("../types.js").AuthConfig} AuthConfig
+ * @typedef {import("../types.js").TwoFactorToken} TwoFactorToken
+ */
+
+export class OtpProvider {
+  /**
+   * @param {AuthConfig} config
+   */
+  constructor(config) {
+    this.config = config
+    this.queries = new AuthQueries(config)
+  }
+
+  /**
+   * Generate a numeric one-time password.
+   * @returns {string}
+   */
+  generateOTP() {
+    const length = this.config.twoFactor?.codeLength || 6
+    const bytes = crypto.getRandomValues(new Uint8Array(length))
+    return Array.from(bytes, (b) => (b % 10).toString()).join("")
+  }
+
+  /**
+   * Generate a random opaque selector for an OTP token.
+   * @returns {string}
+   */
+  generateSelector() {
+    return crypto.randomUUID().replace(/-/g, "")
+  }
+
+  /**
+   * Create, hash, and store a new OTP for an account and mechanism.
+   * @param {number} accountId
+   * @param {number} mechanism EMAIL or SMS
+   * @returns {Promise<{ otp: string, selector: string }>}
+   */
+  async createAndStoreOTP(accountId, mechanism) {
+    const otp = this.generateOTP()
+    const selector = this.generateSelector()
+    const tokenHash = await hash.encode(otp)
+
+    const expiryDuration = this.config.twoFactor?.tokenExpiry || "5m"
+    const expiresAt = new Date(Date.now() + ms(expiryDuration))
+
+    // delete any existing tokens for this account and mechanism
+    await this.queries.deleteTwoFactorTokensByAccountAndMechanism(accountId, mechanism)
+
+    // store the new token
+    await this.queries.createTwoFactorToken({
+      accountId,
+      mechanism,
+      selector,
+      tokenHash,
+      expiresAt,
+    })
+
+    return { otp, selector }
+  }
+
+  /**
+   * Verify an OTP by selector, consuming the token on success.
+   * @param {string} selector
+   * @param {string} inputCode
+   * @returns {Promise<{ isValid: boolean, token?: TwoFactorToken }>}
+   */
+  async verifyOTP(selector, inputCode) {
+    const token = await this.queries.findTwoFactorTokenBySelector(selector)
+
+    if (!token) {
+      return { isValid: false }
+    }
+
+    // check if token has expired (extra check, even though query filters expired tokens)
+    if (token.expires_at <= new Date()) {
+      // clean up expired token
+      await this.queries.deleteTwoFactorToken(token.id)
+      return { isValid: false }
+    }
+
+    const isValid = await hash.verify(token.token_hash, inputCode)
+
+    if (isValid) {
+      // clean up used token
+      await this.queries.deleteTwoFactorToken(token.id)
+      return { isValid: true, token }
+    }
+
+    return { isValid: false }
+  }
+
+  /**
+   * Mask a phone number for display.
+   * @param {string} phone
+   * @returns {string}
+   */
+  maskPhone(phone) {
+    if (phone.length < 4) {
+      return phone.replace(/./g, "*")
+    }
+
+    // show first digit and last 2 digits: +1234567890 -> +1*****90
+    if (phone.startsWith("+")) {
+      return phone[0] + phone[1] + "*".repeat(phone.length - 3) + phone.slice(-2)
+    }
+
+    // for regular numbers: 1234567890 -> 1*****90
+    return phone[0] + "*".repeat(phone.length - 3) + phone.slice(-2)
+  }
+
+  /**
+   * Mask an email address for display.
+   * @param {string} email
+   * @returns {string}
+   */
+  maskEmail(email) {
+    const [username, domain] = email.split("@")
+    if (username.length <= 2) {
+      return `${username[0]}***@${domain}`
+    }
+    return `${username[0]}${"*".repeat(username.length - 2)}${username[username.length - 1]}@${domain}`
+  }
+}