@strav/auth 0.2.13

package/src/totp/totp.ts

@@ -0,0 +1,171 @@
+/**
+ * TOTP (Time-Based One-Time Password) implementation — RFC 6238.
+ * Pure Bun crypto, zero external dependencies.
+ */
+
+import { timingSafeEqual as nodeTimingSafeEqual } from 'node:crypto'
+
+// ---------------------------------------------------------------------------
+// Base32 encoding/decoding (RFC 4648)
+// ---------------------------------------------------------------------------
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+
+export function base32Encode(buffer: Uint8Array): string {
+  let result = ''
+  let bits = 0
+  let value = 0
+
+  for (const byte of buffer) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      bits -= 5
+      result += BASE32_ALPHABET[(value >>> bits) & 0x1f]!
+    }
+  }
+
+  if (bits > 0) {
+    result += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f]!
+  }
+
+  return result
+}
+
+export function base32Decode(encoded: string): Uint8Array {
+  const cleaned = encoded.replace(/=+$/, '').toUpperCase()
+  const bytes: number[] = []
+  let bits = 0
+  let value = 0
+
+  for (const char of cleaned) {
+    const index = BASE32_ALPHABET.indexOf(char)
+    if (index === -1) continue
+    value = (value << 5) | index
+    bits += 5
+    if (bits >= 8) {
+      bits -= 8
+      bytes.push((value >>> bits) & 0xff)
+    }
+  }
+
+  return new Uint8Array(bytes)
+}
+
+// ---------------------------------------------------------------------------
+// HOTP — RFC 4226
+// ---------------------------------------------------------------------------
+
+async function hotp(secret: Uint8Array, counter: bigint, digits: number): Promise<string> {
+  // Counter as 8-byte big-endian buffer
+  const counterBuffer = new ArrayBuffer(8)
+  const view = new DataView(counterBuffer)
+  view.setBigUint64(0, counter)
+
+  // HMAC-SHA1
+  const key = await crypto.subtle.importKey('raw', secret, { name: 'HMAC', hash: 'SHA-1' }, false, [
+    'sign',
+  ])
+  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, counterBuffer))
+
+  // Dynamic truncation
+  const offset = mac[19]! & 0x0f
+  const code =
+    ((mac[offset]! & 0x7f) << 24) |
+    ((mac[offset + 1]! & 0xff) << 16) |
+    ((mac[offset + 2]! & 0xff) << 8) |
+    (mac[offset + 3]! & 0xff)
+
+  return String(code % 10 ** digits).padStart(digits, '0')
+}
+
+// ---------------------------------------------------------------------------
+// TOTP — RFC 6238
+// ---------------------------------------------------------------------------
+
+export interface TotpOptions {
+  digits?: number
+  period?: number
+  /** Number of time steps to check before/after current (handles clock drift). */
+  window?: number
+}
+
+/** Generate a TOTP code for the given secret at the current time. */
+export async function generateTotp(secret: Uint8Array, options: TotpOptions = {}): Promise<string> {
+  const { digits = 6, period = 30 } = options
+  const counter = BigInt(Math.floor(Date.now() / 1000 / period))
+  return hotp(secret, counter, digits)
+}
+
+/** Verify a TOTP code, allowing for clock drift within the window. */
+export async function verifyTotp(
+  secret: Uint8Array,
+  code: string,
+  options: TotpOptions = {}
+): Promise<boolean> {
+  const { digits = 6, period = 30, window = 1 } = options
+  const now = BigInt(Math.floor(Date.now() / 1000 / period))
+
+  for (let i = -window; i <= window; i++) {
+    const expected = await hotp(secret, now + BigInt(i), digits)
+    if (timingSafeEqual(code, expected)) return true
+  }
+
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Secret generation
+// ---------------------------------------------------------------------------
+
+/** Generate a random TOTP secret (20 bytes, returned as base32). */
+export function generateSecret(): { raw: Uint8Array; base32: string } {
+  const raw = crypto.getRandomValues(new Uint8Array(20))
+  return { raw, base32: base32Encode(raw) }
+}
+
+/**
+ * Build an `otpauth://` URI for QR code generation.
+ * Compatible with Google Authenticator, Authy, 1Password, etc.
+ */
+export function totpUri(options: {
+  secret: string // base32
+  issuer: string
+  account: string
+  digits?: number
+  period?: number
+}): string {
+  const { secret, issuer, account, digits = 6, period = 30 } = options
+  const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(account)}`
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: 'SHA1',
+    digits: String(digits),
+    period: String(period),
+  })
+  return `otpauth://totp/${label}?${params}`
+}
+
+// ---------------------------------------------------------------------------
+// Recovery codes
+// ---------------------------------------------------------------------------
+
+/** Generate a set of single-use recovery codes (8-char hex each). */
+export function generateRecoveryCodes(count: number): string[] {
+  const codes: string[] = []
+  for (let i = 0; i < count; i++) {
+    const bytes = crypto.getRandomValues(new Uint8Array(4))
+    codes.push(Array.from(bytes, b => b.toString(16).padStart(2, '0')).join(''))
+  }
+  return codes
+}
+
+// ---------------------------------------------------------------------------
+// Timing-safe string comparison
+// ---------------------------------------------------------------------------
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  return nodeTimingSafeEqual(Buffer.from(a), Buffer.from(b))
+}

package/src/totp/uri.ts

@@ -0,0 +1,26 @@
+/**
+ * QR code URI generation for TOTP authenticators.
+ */
+
+/**
+ * Build an `otpauth://` URI for QR code generation.
+ * Compatible with Google Authenticator, Authy, 1Password, etc.
+ */
+export function totpUri(options: {
+  secret: string // base32
+  issuer: string
+  account: string
+  digits?: number
+  period?: number
+}): string {
+  const { secret, issuer, account, digits = 6, period = 30 } = options
+  const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(account)}`
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: 'SHA1',
+    digits: String(digits),
+    period: String(period),
+  })
+  return `otpauth://totp/${label}?${params}`
+}

package/src/validation/index.ts

@@ -0,0 +1,8 @@
+// Password validation
+export {
+  validatePassword,
+  calculatePasswordStrength,
+  generatePassword,
+  type PasswordStrength,
+  type PasswordPolicy
+} from './password.ts'

package/src/validation/password.ts

@@ -0,0 +1,241 @@
+/**
+ * Password validation utilities for enforcing security policies.
+ */
+
+export interface PasswordStrength {
+  /** Overall score from 0-4 (0 = very weak, 4 = very strong) */
+  score: number
+  /** Human-readable strength label */
+  label: 'Very Weak' | 'Weak' | 'Fair' | 'Strong' | 'Very Strong'
+  /** Specific issues with the password */
+  issues: string[]
+  /** Suggestions for improvement */
+  suggestions: string[]
+}
+
+export interface PasswordPolicy {
+  /** Minimum length (default: 8) */
+  minLength?: number
+  /** Maximum length (default: 128) */
+  maxLength?: number
+  /** Require at least one uppercase letter */
+  requireUppercase?: boolean
+  /** Require at least one lowercase letter */
+  requireLowercase?: boolean
+  /** Require at least one number */
+  requireNumbers?: boolean
+  /** Require at least one special character */
+  requireSpecialChars?: boolean
+  /** List of forbidden passwords/patterns */
+  blacklist?: string[]
+  /** Custom validation function */
+  customValidator?: (password: string) => { valid: boolean; message?: string }
+}
+
+const DEFAULT_POLICY: PasswordPolicy = {
+  minLength: 8,
+  maxLength: 128,
+  requireUppercase: false,
+  requireLowercase: false,
+  requireNumbers: false,
+  requireSpecialChars: false,
+}
+
+/**
+ * Check if a password meets the specified policy requirements.
+ *
+ * @param password - The password to validate
+ * @param policy - The password policy to enforce
+ * @returns Validation result with specific issues
+ */
+export function validatePassword(
+  password: string,
+  policy: PasswordPolicy = DEFAULT_POLICY
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+  const p = { ...DEFAULT_POLICY, ...policy }
+
+  // Length checks
+  if (password.length < p.minLength!) {
+    errors.push(`Password must be at least ${p.minLength} characters long`)
+  }
+  if (password.length > p.maxLength!) {
+    errors.push(`Password must not exceed ${p.maxLength} characters`)
+  }
+
+  // Character requirements
+  if (p.requireUppercase && !/[A-Z]/.test(password)) {
+    errors.push('Password must contain at least one uppercase letter')
+  }
+  if (p.requireLowercase && !/[a-z]/.test(password)) {
+    errors.push('Password must contain at least one lowercase letter')
+  }
+  if (p.requireNumbers && !/\d/.test(password)) {
+    errors.push('Password must contain at least one number')
+  }
+  if (p.requireSpecialChars && !/[!@#$%^&*(),.?":{}|<>]/.test(password)) {
+    errors.push('Password must contain at least one special character')
+  }
+
+  // Blacklist check
+  if (p.blacklist) {
+    const lowerPassword = password.toLowerCase()
+    for (const forbidden of p.blacklist) {
+      if (lowerPassword.includes(forbidden.toLowerCase())) {
+        errors.push(`Password contains forbidden word: ${forbidden}`)
+      }
+    }
+  }
+
+  // Custom validation
+  if (p.customValidator) {
+    const result = p.customValidator(password)
+    if (!result.valid && result.message) {
+      errors.push(result.message)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}
+
+/**
+ * Calculate password strength using various heuristics.
+ *
+ * @param password - The password to analyze
+ * @returns Strength assessment with score and suggestions
+ */
+export function calculatePasswordStrength(password: string): PasswordStrength {
+  let score = 0
+  const issues: string[] = []
+  const suggestions: string[] = []
+
+  // Length scoring
+  if (password.length < 6) {
+    issues.push('Too short')
+    suggestions.push('Use at least 8 characters')
+  } else if (password.length < 8) {
+    score += 0.5
+    suggestions.push('Consider using at least 8 characters')
+  } else if (password.length < 12) {
+    score += 1
+  } else if (password.length < 16) {
+    score += 1.5
+  } else {
+    score += 2
+  }
+
+  // Character diversity
+  const hasLowercase = /[a-z]/.test(password)
+  const hasUppercase = /[A-Z]/.test(password)
+  const hasNumbers = /\d/.test(password)
+  const hasSpecialChars = /[^a-zA-Z0-9]/.test(password)
+
+  const diversity = [hasLowercase, hasUppercase, hasNumbers, hasSpecialChars].filter(Boolean).length
+
+  if (diversity === 1) {
+    issues.push('Uses only one type of character')
+    suggestions.push('Mix uppercase, lowercase, numbers, and symbols')
+  } else if (diversity === 2) {
+    score += 0.5
+    suggestions.push('Add numbers or symbols for better security')
+  } else if (diversity === 3) {
+    score += 1
+  } else if (diversity === 4) {
+    score += 1.5
+  }
+
+  // Common patterns detection
+  if (/^[0-9]+$/.test(password)) {
+    issues.push('Contains only numbers')
+    score = Math.max(0, score - 1)
+  }
+  if (/^[a-zA-Z]+$/.test(password)) {
+    issues.push('Contains only letters')
+    score = Math.max(0, score - 0.5)
+  }
+  if (/(.)\1{2,}/.test(password)) {
+    issues.push('Contains repeated characters')
+    suggestions.push('Avoid repeating characters')
+    score = Math.max(0, score - 0.5)
+  }
+  if (/(?:012|123|234|345|456|567|678|789|890|abc|bcd|cde|def)/i.test(password)) {
+    issues.push('Contains sequential characters')
+    suggestions.push('Avoid sequential patterns')
+    score = Math.max(0, score - 0.5)
+  }
+
+  // Common passwords check
+  const commonPasswords = ['password', '123456', 'qwerty', 'admin', 'letmein', 'welcome', 'monkey', 'dragon']
+  const lowerPassword = password.toLowerCase()
+  if (commonPasswords.some(common => lowerPassword.includes(common))) {
+    issues.push('Contains common password pattern')
+    suggestions.push('Avoid common words and patterns')
+    score = Math.max(0, score - 2)
+  }
+
+  // Normalize score to 0-4 range
+  score = Math.min(4, Math.max(0, score))
+
+  // Determine label
+  let label: PasswordStrength['label']
+  if (score < 1) label = 'Very Weak'
+  else if (score < 2) label = 'Weak'
+  else if (score < 3) label = 'Fair'
+  else if (score < 3.5) label = 'Strong'
+  else label = 'Very Strong'
+
+  return {
+    score: Math.round(score),
+    label,
+    issues,
+    suggestions: suggestions.slice(0, 3), // Limit to top 3 suggestions
+  }
+}
+
+/**
+ * Generate a random strong password.
+ *
+ * @param length - Password length (default: 16)
+ * @param options - Character set options
+ * @returns Generated password
+ */
+export function generatePassword(
+  length: number = 16,
+  options: {
+    uppercase?: boolean
+    lowercase?: boolean
+    numbers?: boolean
+    symbols?: boolean
+  } = {}
+): string {
+  const opts = {
+    uppercase: true,
+    lowercase: true,
+    numbers: true,
+    symbols: true,
+    ...options,
+  }
+
+  let charset = ''
+  if (opts.lowercase) charset += 'abcdefghijklmnopqrstuvwxyz'
+  if (opts.uppercase) charset += 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+  if (opts.numbers) charset += '0123456789'
+  if (opts.symbols) charset += '!@#$%^&*()_+-=[]{}|;:,.<>?'
+
+  if (!charset) {
+    throw new Error('At least one character type must be enabled')
+  }
+
+  let password = ''
+  const array = new Uint8Array(length)
+  crypto.getRandomValues(array)
+
+  for (let i = 0; i < length; i++) {
+    password += charset[array[i]! % charset.length]!
+  }
+
+  return password
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}