@meith/accounts 0.16.0

package/src/session-service.ts

@@ -0,0 +1,134 @@
+import { ForbiddenError } from '@meith/core'
+
+import { generateToken, hashToken } from './crypto/tokens'
+import type { AccountRecord, AccountStore, Clock } from './ports'
+import type { RequestContext } from './service'
+
+export interface SessionServiceDeps {
+  readonly store: AccountStore
+  readonly rememberDays: number
+  readonly sessionLifetimeDays: number
+  readonly assertSignInAllowed?: (account: AccountRecord) => Promise<void>
+  readonly clock?: Clock
+}
+
+export interface RememberedLogin {
+  readonly userId: number
+  readonly sessionToken: string
+  readonly sessionExpiresAt: Date
+  readonly rememberToken: string
+  readonly rememberExpiresAt: Date
+}
+
+export type ResumeOutcome =
+  | { readonly status: 'ok'; readonly login: RememberedLogin }
+  | { readonly status: 'reuse'; readonly userId: number }
+  | { readonly status: 'invalid' }
+
+const DAY_MS = 86_400_000
+
+export class SessionService {
+  private readonly store: AccountStore
+  private readonly rememberDays: number
+  private readonly sessionLifetimeDays: number
+  private readonly assertSignInAllowed: (account: AccountRecord) => Promise<void>
+  private readonly now: Clock
+
+  constructor(deps: SessionServiceDeps) {
+    this.store = deps.store
+    this.rememberDays = deps.rememberDays
+    this.sessionLifetimeDays = deps.sessionLifetimeDays
+    this.assertSignInAllowed = deps.assertSignInAllowed ?? (async () => undefined)
+    this.now = deps.clock ?? (() => new Date())
+  }
+
+  async start(
+    userId: number,
+    context: RequestContext = {},
+  ): Promise<{ token: string; expiresAt: Date }> {
+    return this.mintSession(userId, this.now(), context)
+  }
+
+  async startRemembered(userId: number, context: RequestContext = {}): Promise<RememberedLogin> {
+    const at = this.now()
+    const familyId = generateToken()
+    const rememberToken = generateToken()
+    const rememberExpiresAt = new Date(at.getTime() + this.rememberDays * DAY_MS)
+    await this.store.remember.issue({
+      tokenHash: await hashToken(rememberToken),
+      familyId,
+      userId,
+      expiresAt: rememberExpiresAt,
+    })
+    const session = await this.mintSession(userId, at, context)
+    return {
+      userId,
+      sessionToken: session.token,
+      sessionExpiresAt: session.expiresAt,
+      rememberToken,
+      rememberExpiresAt,
+    }
+  }
+
+  async resume(rememberToken: string, context: RequestContext = {}): Promise<ResumeOutcome> {
+    const at = this.now()
+    const presentedHash = await hashToken(rememberToken)
+    const held = await this.store.remember.findByTokenHash(presentedHash)
+    if (held === null) return { status: 'invalid' }
+
+    const account = await this.store.accounts.findById(held.userId)
+    if (account === null) return { status: 'invalid' }
+
+    try {
+      await this.assertSignInAllowed(account)
+    } catch (error) {
+      if (error instanceof ForbiddenError) return { status: 'invalid' }
+      throw error
+    }
+
+    const nextToken = generateToken()
+    const rotation = await this.store.remember.rotate({
+      presentedHash,
+      nextHash: await hashToken(nextToken),
+      now: at,
+      nextExpiresAt: new Date(at.getTime() + this.rememberDays * DAY_MS),
+    })
+
+    if (rotation.status === 'invalid') return { status: 'invalid' }
+
+    if (rotation.status === 'reuse') {
+      await this.store.remember.revokeAllForUser(rotation.userId, 'token_reuse', at)
+      await this.store.sessions.revokeAllForUser(rotation.userId)
+      return { status: 'reuse', userId: rotation.userId }
+    }
+
+    const session = await this.mintSession(rotation.userId, at, context)
+    return {
+      status: 'ok',
+      login: {
+        userId: rotation.userId,
+        sessionToken: session.token,
+        sessionExpiresAt: session.expiresAt,
+        rememberToken: nextToken,
+        rememberExpiresAt: new Date(at.getTime() + this.rememberDays * DAY_MS),
+      },
+    }
+  }
+
+  private async mintSession(
+    userId: number,
+    at: Date,
+    context: RequestContext = {},
+  ): Promise<{ token: string; expiresAt: Date }> {
+    const token = generateToken()
+    const expiresAt = new Date(at.getTime() + this.sessionLifetimeDays * DAY_MS)
+    await this.store.sessions.create({
+      tokenHash: await hashToken(token),
+      userId,
+      expiresAt,
+      ipPrefix: context.ipPrefix ?? null,
+      userAgent: context.userAgent ?? null,
+    })
+    return { token, expiresAt }
+  }
+}

package/src/test-support.fixture.ts

@@ -0,0 +1,8 @@
+export async function rejectionMessage(p: Promise<unknown>): Promise<string> {
+  try {
+    await p
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+  throw new Error('expected the promise to reject, but it resolved')
+}

package/src/totp/base32.ts

@@ -0,0 +1,52 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+
+export function encodeBase32(bytes: Uint8Array): string {
+  let out = ''
+  let buffer = 0
+  let bits = 0
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte
+    bits += 8
+
+    while (bits >= 5) {
+      bits -= 5
+      out += ALPHABET[(buffer >> bits) & 0b11111]
+    }
+  }
+
+  if (bits > 0) out += ALPHABET[(buffer << (5 - bits)) & 0b11111]
+
+  return out
+}
+
+export function decodeBase32(value: string): Uint8Array {
+  const clean = value.replace(/[=\s-]/g, '').toUpperCase()
+  const bytes: number[] = []
+
+  let buffer = 0
+  let bits = 0
+
+  for (const character of clean) {
+    const digit = ALPHABET.indexOf(character)
+    if (digit < 0) throw new Error('not base32')
+
+    buffer = (buffer << 5) | digit
+    bits += 5
+
+    if (bits >= 8) {
+      bits -= 8
+      bytes.push((buffer >> bits) & 0xff)
+    }
+  }
+
+  return Uint8Array.from(bytes)
+}
+
+export function isBase32(value: string): boolean {
+  try {
+    return decodeBase32(value).length > 0
+  } catch {
+    return false
+  }
+}

package/src/totp/secret-box.ts

@@ -0,0 +1,83 @@
+import { ConfigurationError } from '@meith/core'
+
+import { decodeBase64Url, encodeBase64Url } from '../crypto/base64url'
+
+const VERSION = 'v1'
+
+const IV_BYTES = 12
+
+const INFO = new TextEncoder().encode('meith/two-factor-secret')
+
+/**
+ * The shared secret an authenticator app holds is a password equivalent: with
+ * it, anybody can mint that member's codes forever. It is sealed with a key
+ * derived from AUTH_SECRET so that a leaked backup, or a read of the table by
+ * anything that never had the environment, is not enough on its own.
+ */
+export async function sealSecret(plaintext: string, passphrase: string): Promise<string> {
+  const key = await deriveKey(passphrase)
+  const iv = new Uint8Array(IV_BYTES)
+  crypto.getRandomValues(iv)
+
+  const sealed = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: iv as unknown as BufferSource },
+      key,
+      new TextEncoder().encode(plaintext) as unknown as BufferSource,
+    ),
+  )
+
+  return `${VERSION}.${encodeBase64Url(iv)}.${encodeBase64Url(sealed)}`
+}
+
+export async function openSecret(sealed: string, passphrase: string): Promise<string | null> {
+  const parts = sealed.split('.')
+  if (parts.length !== 3 || parts[0] !== VERSION) return null
+
+  try {
+    const key = await deriveKey(passphrase)
+
+    const opened = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: decodeBase64Url(parts[1]!) as unknown as BufferSource },
+      key,
+      decodeBase64Url(parts[2]!) as unknown as BufferSource,
+    )
+
+    return new TextDecoder().decode(opened)
+  } catch {
+    return null
+  }
+}
+
+export function assertSealingKey(passphrase: string | undefined): string {
+  if (passphrase === undefined || passphrase.trim() === '') {
+    throw new ConfigurationError(
+      'Two-factor authentication needs AUTH_SECRET set, because the secret an ' +
+        'authenticator app holds is sealed with a key derived from it.',
+    )
+  }
+  return passphrase
+}
+
+async function deriveKey(passphrase: string): Promise<CryptoKey> {
+  const material = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(passphrase) as unknown as BufferSource,
+    'HKDF',
+    false,
+    ['deriveKey'],
+  )
+
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array() as unknown as BufferSource,
+      info: INFO as unknown as BufferSource,
+    },
+    material,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  )
+}

package/src/totp/service.ts

@@ -0,0 +1,252 @@
+import { ConflictError, ForbiddenError, NotFoundError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import { hashToken } from '../crypto/tokens'
+import type {
+  AccountRepository,
+  Clock,
+  RecoveryCodeRepository,
+  TwoFactorRepository,
+} from '../ports'
+import { encodeBase32 } from './base32'
+import { openSecret, sealSecret } from './secret-box'
+import { generateTotpSecret, matchTotp, otpauthUri } from './totp'
+
+export const RECOVERY_CODE_COUNT = 10
+
+export const RECOVERY_CODE_BYTES = 16
+
+export const WRONG_CODE = 'That code is not right. Check your authenticator app and try again.'
+
+export const REPLAYED_CODE =
+  'That code has been used already. Wait for your authenticator app to show the next one.'
+
+export interface TwoFactorDeps {
+  readonly accounts: AccountRepository
+  readonly twoFactor: TwoFactorRepository
+  readonly recoveryCodes: RecoveryCodeRepository
+  readonly sealingKey: string
+  readonly clock?: Clock
+}
+
+export interface Enrolment {
+  readonly secret: string
+  readonly uri: string
+}
+
+export interface TwoFactorState {
+  readonly enrolled: boolean
+  readonly pending: boolean
+  readonly recoveryCodesLeft: number
+}
+
+export type SecondFactorOutcome =
+  | { readonly status: 'ok'; readonly usedRecoveryCode: boolean }
+  | { readonly status: 'wrong' }
+  | { readonly status: 'replayed' }
+
+export async function holdsSecondFactor(
+  twoFactor: TwoFactorRepository,
+  userId: number,
+): Promise<boolean> {
+  const record = await twoFactor.find(userId)
+  return record !== null && record.confirmedAt !== null
+}
+
+export async function clearSecondFactor(
+  store: {
+    readonly twoFactor: TwoFactorRepository
+    readonly recoveryCodes: RecoveryCodeRepository
+  },
+  userId: number,
+): Promise<boolean> {
+  const removed = await store.twoFactor.remove(userId)
+  await store.recoveryCodes.removeAll(userId)
+  return removed
+}
+
+export class TwoFactorService {
+  private readonly accounts: AccountRepository
+  private readonly twoFactor: TwoFactorRepository
+  private readonly recoveryCodes: RecoveryCodeRepository
+  private readonly sealingKey: string
+  private readonly now: Clock
+
+  constructor(deps: TwoFactorDeps) {
+    this.accounts = deps.accounts
+    this.twoFactor = deps.twoFactor
+    this.recoveryCodes = deps.recoveryCodes
+    this.sealingKey = deps.sealingKey
+    this.now = deps.clock ?? (() => new Date())
+  }
+
+  async state(userId: number): Promise<TwoFactorState> {
+    const record = await this.twoFactor.find(userId)
+    const enrolled = record !== null && record.confirmedAt !== null
+
+    return {
+      enrolled,
+      pending: record !== null && record.confirmedAt === null,
+      recoveryCodesLeft: enrolled ? await this.recoveryCodes.countUnused(userId) : 0,
+    }
+  }
+
+  async isEnrolled(userId: number): Promise<boolean> {
+    return holdsSecondFactor(this.twoFactor, userId)
+  }
+
+  async beginEnrolment(userId: number, boardName: string): Promise<Enrolment> {
+    const account = await this.accounts.findById(userId)
+    if (account === null) throw new NotFoundError(msg('error.accounts.account-longer-exists'))
+
+    const existing = await this.twoFactor.find(userId)
+    if (existing !== null && existing.confirmedAt !== null) {
+      throw new ConflictError(msg('error.accounts.account-already-asks-for-code'))
+    }
+
+    const secret = generateTotpSecret()
+    await this.twoFactor.startEnrolment({
+      userId,
+      sealedSecret: await sealSecret(secret, this.sealingKey),
+      now: this.now(),
+    })
+
+    return {
+      secret,
+      uri: otpauthUri({ secret, account: account.username, issuer: boardName }),
+    }
+  }
+
+  /**
+   * The enrolment already under way, so the setup screen survives a reload
+   * without minting a second secret — which would strand whatever the member
+   * had already typed into their authenticator app.
+   */
+  async pendingEnrolment(userId: number, boardName: string): Promise<Enrolment | null> {
+    const record = await this.twoFactor.find(userId)
+    if (record === null || record.confirmedAt !== null) return null
+
+    const account = await this.accounts.findById(userId)
+    if (account === null) return null
+
+    const secret = await this.unseal(record.sealedSecret)
+    return {
+      secret,
+      uri: otpauthUri({ secret, account: account.username, issuer: boardName }),
+    }
+  }
+
+  async confirmEnrolment(input: {
+    readonly userId: number
+    readonly code: string
+  }): Promise<readonly string[]> {
+    const record = await this.twoFactor.find(input.userId)
+    if (record === null) {
+      throw new ConflictError(msg('error.accounts.start-setting-up-authenticator-app'))
+    }
+    if (record.confirmedAt !== null) {
+      throw new ConflictError(msg('error.accounts.account-already-asks-for-code-2'))
+    }
+
+    const secret = await this.unseal(record.sealedSecret)
+    const at = this.now()
+    const matched = await matchTotp({ secret, code: input.code, at })
+
+    if (matched === null) throw new ValidationError(WRONG_CODE)
+
+    await this.twoFactor.confirm(input.userId, matched.step, at)
+    return this.replaceRecoveryCodes(input.userId)
+  }
+
+  async verify(input: {
+    readonly userId: number
+    readonly code: string
+  }): Promise<SecondFactorOutcome> {
+    const record = await this.twoFactor.find(input.userId)
+    if (record === null || record.confirmedAt === null) return { status: 'wrong' }
+
+    const at = this.now()
+    const matched = await matchTotp({
+      secret: await this.unseal(record.sealedSecret),
+      code: input.code,
+      at,
+    })
+
+    if (matched !== null) {
+      const fresh = await this.twoFactor.spendStep(input.userId, matched.step)
+      return fresh ? { status: 'ok', usedRecoveryCode: false } : { status: 'replayed' }
+    }
+
+    const spent = await this.recoveryCodes.spend(
+      input.userId,
+      await hashToken(normaliseRecoveryCode(input.code)),
+      at,
+    )
+
+    return spent ? { status: 'ok', usedRecoveryCode: true } : { status: 'wrong' }
+  }
+
+  async replaceRecoveryCodes(userId: number): Promise<readonly string[]> {
+    const codes = Array.from({ length: RECOVERY_CODE_COUNT }, () => newRecoveryCode())
+
+    await this.recoveryCodes.replaceAll(
+      userId,
+      await Promise.all(codes.map((code) => hashToken(normaliseRecoveryCode(code)))),
+      this.now(),
+    )
+
+    return codes
+  }
+
+  async disable(input: { readonly userId: number; readonly required: boolean }): Promise<void> {
+    if (input.required) {
+      throw new ForbiddenError(msg('error.accounts.board-asks-its-staff-for'))
+    }
+
+    await this.twoFactor.remove(input.userId)
+    await this.recoveryCodes.removeAll(input.userId)
+  }
+
+  async abandonEnrolment(userId: number): Promise<void> {
+    const record = await this.twoFactor.find(userId)
+    if (record === null || record.confirmedAt !== null) return
+
+    await this.twoFactor.remove(userId)
+  }
+
+  private async unseal(sealed: string): Promise<string> {
+    const secret = await openSecret(sealed, this.sealingKey)
+    if (secret === null) {
+      throw new ForbiddenError(msg('error.accounts.board-read-secret-behind-authenticator'))
+    }
+    return secret
+  }
+}
+
+/**
+ * The yes-or-no the login path needs, straight off the repository. Built here
+ * rather than from the whole service so that composing the two does not hand
+ * the login path a key it has no use for.
+ */
+export function enrolmentLookup(repository: TwoFactorRepository): {
+  isEnrolled(userId: number): Promise<boolean>
+} {
+  return {
+    async isEnrolled(userId: number): Promise<boolean> {
+      const record = await repository.find(userId)
+      return record !== null && record.confirmedAt !== null
+    },
+  }
+}
+
+export function newRecoveryCode(): string {
+  const bytes = new Uint8Array(RECOVERY_CODE_BYTES)
+  crypto.getRandomValues(bytes)
+
+  const code = encodeBase32(bytes)
+  return code.match(/.{1,5}/g)?.join('-') ?? code
+}
+
+export function normaliseRecoveryCode(code: string): string {
+  return code.replace(/[\s-]/g, '').toUpperCase()
+}

package/src/totp/totp.ts

@@ -0,0 +1,120 @@
+import { decodeBase32, encodeBase32 } from './base32'
+
+export const TOTP_PERIOD_SECONDS = 30
+
+export const TOTP_DIGITS = 6
+
+export const TOTP_SECRET_BYTES = 20
+
+/**
+ * How far either side of now a code is still taken. One step each way covers a
+ * device whose clock has drifted and a member who started typing at 29 seconds
+ * past; more than that widens the window an intercepted code stays usable in.
+ */
+export const TOTP_SKEW_STEPS = 1
+
+export function generateTotpSecret(byteLength = TOTP_SECRET_BYTES): string {
+  const bytes = new Uint8Array(byteLength)
+  crypto.getRandomValues(bytes)
+  return encodeBase32(bytes)
+}
+
+export function stepAt(at: Date, period = TOTP_PERIOD_SECONDS): number {
+  return Math.floor(at.getTime() / 1000 / period)
+}
+
+export async function totpCode(
+  secret: string,
+  step: number,
+  digits = TOTP_DIGITS,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    decodeBase32(secret) as unknown as BufferSource,
+    { name: 'HMAC', hash: 'SHA-1' },
+    false,
+    ['sign'],
+  )
+
+  const counter = new Uint8Array(8)
+  new DataView(counter.buffer).setBigUint64(0, BigInt(step))
+
+  const mac = new Uint8Array(
+    await crypto.subtle.sign('HMAC', key, counter as unknown as BufferSource),
+  )
+
+  const offset = mac[mac.length - 1]! & 0x0f
+  const binary =
+    ((mac[offset]! & 0x7f) << 24) |
+    (mac[offset + 1]! << 16) |
+    (mac[offset + 2]! << 8) |
+    mac[offset + 3]!
+
+  return String(binary % 10 ** digits).padStart(digits, '0')
+}
+
+export interface TotpMatch {
+  readonly step: number
+}
+
+/**
+ * The step the code belongs to, or null. The step is returned rather than a
+ * bare yes so the caller can refuse a code it has already accepted: a code is
+ * valid for thirty seconds, and anybody who reads it over a shoulder or off a
+ * proxy log has that long to use it first.
+ */
+export async function matchTotp(input: {
+  readonly secret: string
+  readonly code: string
+  readonly at: Date
+  readonly skew?: number
+  readonly digits?: number
+  readonly period?: number
+}): Promise<TotpMatch | null> {
+  const digits = input.digits ?? TOTP_DIGITS
+  const code = input.code.replace(/[\s-]/g, '')
+  if (!new RegExp(`^\\d{${digits}}$`).test(code)) return null
+
+  const skew = input.skew ?? TOTP_SKEW_STEPS
+  const centre = stepAt(input.at, input.period ?? TOTP_PERIOD_SECONDS)
+
+  for (let offset = -skew; offset <= skew; offset += 1) {
+    const step = centre + offset
+    if (step < 0) continue
+
+    if (timingSafeCompare(await totpCode(input.secret, step, digits), code)) {
+      return { step }
+    }
+  }
+
+  return null
+}
+
+export function otpauthUri(input: {
+  readonly secret: string
+  readonly account: string
+  readonly issuer: string
+}): string {
+  const issuer = input.issuer.trim() === '' ? 'Meith' : input.issuer.trim()
+  const label = `${issuer}:${input.account}`
+
+  const parameters = new URLSearchParams({
+    secret: input.secret,
+    issuer,
+    algorithm: 'SHA1',
+    digits: String(TOTP_DIGITS),
+    period: String(TOTP_PERIOD_SECONDS),
+  })
+
+  return `otpauth://totp/${encodeURIComponent(label)}?${parameters.toString()}`
+}
+
+function timingSafeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+
+  let diff = 0
+  for (let index = 0; index < a.length; index += 1) {
+    diff |= a.charCodeAt(index) ^ b.charCodeAt(index)
+  }
+  return diff === 0
+}