@prsm/auth 1.0.0

package/src/__tests__/totp.test.js

@@ -0,0 +1,158 @@
+import { describe, it, expect } from "vitest"
+import Otp, { InvalidSecretError, InvalidOtpLengthError, InvalidHashFunctionError, InvalidIntervalError } from "../totp.js"
+
+// the totp primitive is inlined into @prsm/auth (not re-exported from the package
+// index), but it is the crypto backing all 2fa, so it gets a direct suite. these
+// port the @eaccess/totp tests and pin the RFC 6238 vectors, which also prove the
+// self-contained base32 (decode) matches the @scure/base implementation it replaced
+
+// base32 of the RFC 6238 ASCII seeds (verified equal to @scure/base output)
+const SHA1 = "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ" // "12345678901234567890"
+const SHA256 = "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZA" // ...12 bytes more
+const SHA512 = "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNA"
+
+describe("totp - secret generation", () => {
+  it("generates base32 secrets sized by strength", () => {
+    expect(Otp.createSecret(Otp.SHARED_SECRET_STRENGTH_LOW).length).toBe(16)
+    expect(Otp.createSecret(Otp.SHARED_SECRET_STRENGTH_MODERATE).length).toBe(26)
+    expect(Otp.createSecret(Otp.SHARED_SECRET_STRENGTH_HIGH).length).toBe(32)
+    expect(Otp.createSecret().length).toBe(32) // default high
+  })
+
+  it("only emits base32 alphabet characters", () => {
+    expect(Otp.createSecret()).toMatch(/^[A-Z2-7]+$/)
+  })
+})
+
+describe("totp - generate and verify round-trip", () => {
+  it("generates a 6-digit code that verifies (exercises base32 encode + decode)", () => {
+    const secret = Otp.createSecret()
+    const code = Otp.generateTotp(secret)
+    expect(code).toHaveLength(6)
+    expect(Otp.verifyTotp(secret, code)).toBe(true)
+  })
+
+  it("rejects a wrong code", () => {
+    const secret = Otp.createSecret()
+    expect(Otp.verifyTotp(secret, "000000")).toBe(false)
+  })
+
+  it("supports custom 8-digit length", () => {
+    const secret = Otp.createSecret()
+    const code = Otp.generateTotp(secret, undefined, 8)
+    expect(code).toHaveLength(8)
+    expect(Otp.verifyTotp(secret, code, undefined, undefined, undefined, 8)).toBe(true)
+  })
+})
+
+describe("totp - QR provisioning URI", () => {
+  it("builds an otpauth uri", () => {
+    const uri = Otp.createTotpKeyUriForQrCode("app.example.com", "john.doe@example.org", "SECRET")
+    expect(uri).toContain("otpauth://totp/app.example.com:john.doe%40example.org")
+    expect(uri).toContain("secret=SECRET")
+    expect(uri).toContain("issuer=app.example.com")
+  })
+
+  it("url-encodes issuer special characters", () => {
+    const uri = Otp.createTotpKeyUriForQrCode("My App/Service", "user@example.com", "SECRET")
+    expect(uri).toContain("otpauth://totp/My%20App%2FService:")
+    expect(uri).toContain("issuer=My%20App%2FService")
+  })
+})
+
+describe("totp - input validation", () => {
+  it("throws on a secret shorter than 16 chars", () => {
+    expect(() => Otp.generateTotp("shortsecret")).toThrow(InvalidSecretError)
+  })
+
+  it("throws on an out-of-range otp length", () => {
+    const secret = Otp.createSecret()
+    expect(() => Otp.generateTotp(secret, undefined, 5)).toThrow(InvalidOtpLengthError)
+    expect(() => Otp.generateTotp(secret, undefined, 9)).toThrow(InvalidOtpLengthError)
+  })
+
+  it("throws on an unknown hash function", () => {
+    const secret = Otp.createSecret()
+    expect(() => Otp.generateTotp(secret, undefined, undefined, undefined, undefined, 999)).toThrow(InvalidHashFunctionError)
+  })
+
+  it("throws on a non-positive interval", () => {
+    const secret = Otp.createSecret()
+    expect(() => Otp.generateTotp(secret, undefined, 6, 0)).toThrow(InvalidIntervalError)
+    expect(() => Otp.generateTotp(secret, undefined, 6, -30)).toThrow(InvalidIntervalError)
+  })
+
+  it("rejects codes of the wrong length without throwing", () => {
+    const secret = Otp.createSecret()
+    expect(Otp.verifyTotp(secret, "12345")).toBe(false) // too short
+    expect(Otp.verifyTotp(secret, "123456789")).toBe(false) // too long
+  })
+})
+
+describe("totp - drift window", () => {
+  const now = 1000000000
+  const step = 30
+
+  it("accepts a one-step-ahead code within a symmetric window", () => {
+    const secret = Otp.createSecret()
+    const ahead = Otp.generateTotp(secret, now + step)
+    expect(Otp.verifyTotp(secret, ahead, 0, undefined, now)).toBe(false) // window 0
+    expect(Otp.verifyTotp(secret, ahead, 1, undefined, now)).toBe(true) // window 1 (symmetric)
+  })
+
+  it("honors an explicit asymmetric window", () => {
+    const secret = Otp.createSecret()
+    const ahead = Otp.generateTotp(secret, now + step)
+    expect(Otp.verifyTotp(secret, ahead, 2, 0, now)).toBe(false) // look only behind
+    expect(Otp.verifyTotp(secret, ahead, 0, 1, now)).toBe(true) // look ahead 1
+  })
+
+  it("is strict with a window of 0", () => {
+    const secret = Otp.createSecret()
+    const code = Otp.generateTotp(secret, now)
+    expect(Otp.verifyTotp(secret, code, 0, undefined, now)).toBe(true)
+    const old = Otp.generateTotp(secret, now - step)
+    expect(Otp.verifyTotp(secret, old, 0, undefined, now)).toBe(false)
+  })
+
+  it("rejects codes well outside the window (expired and future)", () => {
+    const secret = Otp.createSecret()
+    expect(Otp.verifyTotp(secret, Otp.generateTotp(secret, now - 300), 2, 2, now)).toBe(false)
+    expect(Otp.verifyTotp(secret, Otp.generateTotp(secret, now + 300), 2, 2, now)).toBe(false)
+  })
+})
+
+describe("totp - RFC 6238 test vectors", () => {
+  // exact generated values from RFC 6238 Appendix B; deterministic, no clock dependence
+  it("matches the SHA-1 vectors (8 digits)", () => {
+    const cases = [
+      [59, "94287082"],
+      [1111111109, "07081804"],
+      [1111111111, "14050471"],
+      [1234567890, "89005924"],
+      [2000000000, "69279037"],
+      [20000000000, "65353130"],
+    ]
+    for (const [t, expected] of cases) {
+      expect(Otp.generateTotp(SHA1, t, 8, 30, 0, Otp.HASH_FUNCTION_SHA_1)).toBe(expected)
+    }
+  })
+
+  it("matches the SHA-256 vector (8 digits)", () => {
+    expect(Otp.generateTotp(SHA256, 59, 8, 30, 0, Otp.HASH_FUNCTION_SHA_256)).toBe("46119246")
+  })
+
+  it("matches the SHA-512 vector (8 digits)", () => {
+    expect(Otp.generateTotp(SHA512, 59, 8, 30, 0, Otp.HASH_FUNCTION_SHA_512)).toBe("90693936")
+  })
+
+  it("verifies an RFC vector through verifyTotp at a fixed time", () => {
+    expect(Otp.verifyTotp(SHA1, "94287082", 0, 0, 59, 8, 30, 0, Otp.HASH_FUNCTION_SHA_1)).toBe(true)
+    expect(Otp.verifyTotp(SHA1, "94287082", 0, 0, 59 + 60, 8, 30, 0, Otp.HASH_FUNCTION_SHA_1)).toBe(false)
+  })
+
+  it("truncates to 6 digits consistently with the 8-digit vector", () => {
+    // RFC 6238 6-digit value at t=59 is the last 6 digits of the 8-digit one
+    expect(Otp.generateTotp(SHA1, 59, 6, 30, 0, Otp.HASH_FUNCTION_SHA_1)).toBe("287082")
+  })
+})

package/src/__tests__/two-factor-test-setup.js

@@ -0,0 +1,331 @@
+import express from "express"
+import session from "express-session"
+import cookieParser from "cookie-parser"
+import pg from "pg"
+import { createAuthMiddleware, createAuthTables, dropAuthTables, closeInvalidationListeners } from "../index.js"
+
+const { Pool } = pg
+
+export async function createTestDatabase() {
+  const url = process.env.AUTH_TEST_POSTGRES_URL
+  const poolOptions = { max: 15, idleTimeoutMillis: 1000 }
+  const pool = url
+    ? new Pool({ connectionString: url, ...poolOptions })
+    : new Pool({
+        host: process.env.PGHOST || "localhost",
+        port: parseInt(process.env.PGPORT || "5432"),
+        database: process.env.PGDATABASE || "auth_test",
+        user: process.env.PGUSER || "auth",
+        password: process.env.PGPASSWORD || "auth_password",
+        ...poolOptions,
+      })
+
+  try {
+    await pool.query("SELECT NOW()")
+  } catch (error) {
+    throw new Error("Failed to connect to test database. Make sure to run: make up")
+  }
+
+  return pool
+}
+
+export async function createTwoFactorTestApp() {
+  const pool = await createTestDatabase()
+
+  const app = express()
+
+  app.use(express.json())
+  app.use(cookieParser())
+  app.use(
+    session({
+      secret: "2fa-test-secret-key-for-testing-only",
+      resave: false,
+      saveUninitialized: false,
+      cookie: { secure: false, httpOnly: true },
+    }),
+  )
+
+  const authConfig = {
+    db: pool,
+    tablePrefix: "mfa_test_",
+    minPasswordLength: 6,
+    maxPasswordLength: 50,
+    rememberDuration: "7d",
+    rememberCookieName: "2fa_test_remember_token",
+    resyncInterval: "30s",
+    twoFactor: {
+      enabled: true,
+      issuer: "EasyAccess Test",
+      totpWindow: 1,
+      backupCodesCount: 10,
+    },
+  }
+
+  await dropAuthTables(authConfig)
+  await createAuthTables(authConfig)
+
+  app.use(createAuthMiddleware(authConfig))
+
+  // standard auth routes
+  app.post("/register", async (req, res) => {
+    try {
+      const { email, password, requireConfirmation } = req.body
+      let confirmationToken
+
+      const account = await req.auth.register(
+        email,
+        password,
+        "2fa-test-user-123",
+        requireConfirmation
+          ? (token) => {
+              confirmationToken = token
+            }
+          : undefined,
+      )
+
+      res.json({
+        success: true,
+        account: {
+          id: account.id,
+          email: account.email,
+          verified: account.verified,
+          status: account.status,
+        },
+        confirmationToken,
+      })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.post("/login", async (req, res) => {
+    try {
+      const { email, password, remember } = req.body
+      await req.auth.login(email, password, remember)
+      res.json({ success: true })
+    } catch (error) {
+      if (error.constructor.name === "SecondFactorRequiredError") {
+        // capture the OTP value from the challenge for testing
+        if (error.availableMethods.email?.otpValue) {
+          lastGeneratedOtp = error.availableMethods.email.otpValue
+        } else if (error.availableMethods.sms?.otpValue) {
+          lastGeneratedOtp = error.availableMethods.sms.otpValue
+        }
+
+        return res.status(202).json({
+          requiresTwoFactor: true,
+          availableMethods: error.availableMethods,
+        })
+      }
+      res.status(401).json({ error: error.message })
+    }
+  })
+
+  app.post("/logout", async (req, res) => {
+    try {
+      await req.auth.logout()
+      res.json({ success: true })
+    } catch (error) {
+      res.status(500).json({ error: error.message })
+    }
+  })
+
+  app.post("/verify-2fa", async (req, res) => {
+    try {
+      const { code } = req.body || {}
+      await req.auth.twoFactor.verify.otp(code)
+      await req.auth.completeTwoFactorLogin()
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message, errorType: error.constructor.name })
+    }
+  })
+
+  app.post("/verify-2fa-totp", async (req, res) => {
+    try {
+      const { code } = req.body || {}
+      await req.auth.twoFactor.verify.totp(code)
+      await req.auth.completeTwoFactorLogin()
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message, errorType: error.constructor.name })
+    }
+  })
+
+  app.post("/verify-2fa-backup", async (req, res) => {
+    try {
+      const { code } = req.body || {}
+      await req.auth.twoFactor.verify.backupCode(code)
+      await req.auth.completeTwoFactorLogin()
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message, errorType: error.constructor.name })
+    }
+  })
+
+  app.get("/2fa/contact/:mechanism", async (req, res) => {
+    try {
+      const mechanism = parseInt(req.params.mechanism)
+      const contact = await req.auth.twoFactor.getContact(mechanism)
+      res.json({ contact })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.get("/2fa/totp-uri", async (req, res) => {
+    try {
+      const uri = await req.auth.twoFactor.getTotpUri()
+      res.json({ uri })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.get("/2fa/is-enabled", async (req, res) => {
+    try {
+      const enabled = await req.auth.twoFactor.isEnabled()
+      const totp = await req.auth.twoFactor.totpEnabled()
+      const email = await req.auth.twoFactor.emailEnabled()
+      const sms = await req.auth.twoFactor.smsEnabled()
+      res.json({ enabled, totp, email, sms })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.get("/profile", async (req, res) => {
+    if (!req.auth.isLoggedIn()) {
+      return res.status(401).json({ error: "Not logged in" })
+    }
+
+    res.json({
+      id: req.auth.getId(),
+      email: req.auth.getEmail(),
+      status: req.auth.getStatus(),
+      statusName: req.auth.getStatusName(),
+      verified: req.auth.getVerified(),
+      roles: req.auth.getRoleNames(),
+      remembered: req.auth.isRemembered(),
+      isAdmin: await req.auth.isAdmin(),
+    })
+  })
+
+  // 2FA setup routes
+  app.post("/2fa/setup-totp", async (req, res) => {
+    try {
+      const { requireVerification } = req.body || {}
+      const result = await req.auth.twoFactor.setup.totp(requireVerification)
+      res.json(result)
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.post("/2fa/verify-totp-setup", async (req, res) => {
+    try {
+      const { code } = req.body
+      const backupCodes = await req.auth.twoFactor.complete.totp(code)
+      res.json({ success: true, backupCodes })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.post("/2fa/setup-email", async (req, res) => {
+    try {
+      const { requireVerification } = req.body || {}
+      await req.auth.twoFactor.setup.email(undefined, requireVerification)
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.post("/2fa/setup-sms", async (req, res) => {
+    try {
+      const { phoneNumber, requireVerification } = req.body || {}
+      await req.auth.twoFactor.setup.sms(phoneNumber, requireVerification !== false)
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.post("/2fa/verify-setup", async (req, res) => {
+    try {
+      const { code, mechanism } = req.body || {}
+      if (mechanism === "email") {
+        await req.auth.twoFactor.complete.email(code)
+      } else if (mechanism === "sms") {
+        await req.auth.twoFactor.complete.sms(code)
+      }
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.get("/2fa/methods", async (req, res) => {
+    try {
+      const methods = await req.auth.twoFactor.getEnabledMethods()
+      res.json({ methods })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.delete("/2fa/method/:mechanism", async (req, res) => {
+    try {
+      const mechanism = parseInt(req.params.mechanism)
+      await req.auth.twoFactor.disable(mechanism)
+      res.json({ success: true })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  app.post("/2fa/regenerate-backup-codes", async (req, res) => {
+    try {
+      const codes = await req.auth.twoFactor.generateNewBackupCodes()
+      res.json({ codes })
+    } catch (error) {
+      res.status(400).json({ error: error.message })
+    }
+  })
+
+  // utility routes for tests
+  app.post("/set-user-session", (req, res) => {
+    req.session.userId = req.body.userId || "2fa-test-user-123"
+    req.session.save((err) => {
+      if (err) {
+        return res.status(500).json({ error: "Failed to save session" })
+      }
+      res.json({ success: true })
+    })
+  })
+
+  app.get("/session-info", (req, res) => {
+    res.json({
+      sessionId: req.sessionID,
+      userId: req.session.userId,
+      auth: req.session.auth || null,
+    })
+  })
+
+  let lastGeneratedOtp = null
+
+  app.get("/test-otp", (_req, res) => {
+    res.json({ otp: lastGeneratedOtp })
+  })
+
+  return {
+    app,
+    pool,
+    authConfig,
+    cleanup: async () => {
+      await closeInvalidationListeners()
+      await pool.end()
+    },
+  }
+}