@svadmin/auth-utils 0.4.1

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@svadmin/auth-utils",
+  "version": "0.4.1",
+  "type": "module",
+  "description": "Zero-dependency auth utility functions — password hashing, session management, TOTP for svadmin",
+  "license": "MIT",
+  "keywords": ["svadmin", "auth", "password", "session", "totp", "mfa"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zuohuadong/svadmin",
+    "directory": "packages/auth-utils"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./password": {
+      "types": "./src/password.ts",
+      "import": "./src/password.ts"
+    },
+    "./session": {
+      "types": "./src/session.ts",
+      "import": "./src/session.ts"
+    },
+    "./totp": {
+      "types": "./src/totp.ts",
+      "import": "./src/totp.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/src/auth-utils.test.ts

@@ -0,0 +1,136 @@
+/**
+ * @svadmin/auth-utils — Unit Tests
+ */
+import { describe, test, expect } from 'bun:test';
+import { hashPassword, verifyPassword } from './password';
+import { createSessionManager } from './session';
+import { generateSecret, generateTOTP, verifyTOTP, generateQRUri } from './totp';
+
+// ─── Password ────────────────────────────────────────────────
+
+describe('password', () => {
+  test('hashPassword → verifyPassword (correct)', async () => {
+    const hash = await hashPassword('test-password-123');
+    expect(hash).toBeTruthy();
+    expect(typeof hash).toBe('string');
+
+    const valid = await verifyPassword('test-password-123', hash);
+    expect(valid).toBe(true);
+  });
+
+  test('hashPassword → verifyPassword (wrong password)', async () => {
+    const hash = await hashPassword('correct-password');
+    const valid = await verifyPassword('wrong-password', hash);
+    expect(valid).toBe(false);
+  });
+
+  test('hash format includes algorithm prefix', async () => {
+    const hash = await hashPassword('test', { algorithm: 'pbkdf2' });
+    expect(hash.startsWith('pbkdf2:')).toBe(true);
+  });
+
+  test('different passwords produce different hashes', async () => {
+    const h1 = await hashPassword('password-1', { algorithm: 'pbkdf2' });
+    const h2 = await hashPassword('password-2', { algorithm: 'pbkdf2' });
+    expect(h1).not.toBe(h2);
+  });
+
+  test('same password produces different hashes (salt)', async () => {
+    const h1 = await hashPassword('same-password', { algorithm: 'pbkdf2' });
+    const h2 = await hashPassword('same-password', { algorithm: 'pbkdf2' });
+    expect(h1).not.toBe(h2); // different salt each time
+  });
+});
+
+// ─── Session ─────────────────────────────────────────────────
+
+describe('session', () => {
+  const sessions = createSessionManager('test-secret-key-at-least-32-chars!!');
+
+  test('create and verify session', async () => {
+    const token = await sessions.create({ userId: 'user-123', role: 'admin' });
+    expect(typeof token).toBe('string');
+    expect(token).toContain('.');
+
+    const payload = await sessions.verify(token);
+    expect(payload).not.toBeNull();
+    expect(payload!.sub).toBe('user-123');
+    expect(payload!.role).toBe('admin');
+  });
+
+  test('verify rejects tampered token', async () => {
+    const token = await sessions.create({ userId: 'user-123' });
+    const tampered = token.replace(/^./, 'X');
+    const payload = await sessions.verify(tampered);
+    expect(payload).toBeNull();
+  });
+
+  test('verify rejects expired token', async () => {
+    const shortSession = createSessionManager('test-secret-key-at-least-32-chars!!', { ttl: -1 });
+    const token = await shortSession.create({ userId: 'user-123' });
+    const payload = await shortSession.verify(token);
+    expect(payload).toBeNull();
+  });
+
+  test('verify rejects malformed token', async () => {
+    expect(await sessions.verify('not-a-valid-token')).toBeNull();
+    expect(await sessions.verify('')).toBeNull();
+    expect(await sessions.verify('a.b.c')).toBeNull();
+  });
+
+  test('generateId produces hex string', () => {
+    const id = sessions.generateId();
+    expect(id).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+// ─── TOTP ────────────────────────────────────────────────────
+
+describe('totp', () => {
+  test('generateSecret produces base32 string', () => {
+    const secret = generateSecret();
+    expect(secret).toBeTruthy();
+    expect(secret).toMatch(/^[A-Z2-7]+$/);
+    expect(secret.length).toBeGreaterThan(20);
+  });
+
+  test('generateTOTP produces 6-digit string', async () => {
+    const secret = generateSecret();
+    const code = await generateTOTP(secret);
+    expect(code).toMatch(/^\d{6}$/);
+  });
+
+  test('verifyTOTP validates correct code', async () => {
+    const secret = generateSecret();
+    const code = await generateTOTP(secret);
+    const valid = await verifyTOTP(code, secret);
+    expect(valid).toBe(true);
+  });
+
+  test('verifyTOTP rejects wrong code', async () => {
+    const secret = generateSecret();
+    const valid = await verifyTOTP('000000', secret);
+    // Might be true by coincidence, but extremely unlikely
+    // Just check it doesn't throw
+    expect(typeof valid).toBe('boolean');
+  });
+
+  test('generateQRUri produces otpauth:// URI', () => {
+    const secret = generateSecret();
+    const uri = generateQRUri(secret, 'user@example.com', 'MyApp');
+    expect(uri).toContain('otpauth://totp/');
+    expect(uri).toContain('MyApp');
+    expect(uri).toContain('user%40example.com');
+    expect(uri).toContain(secret);
+  });
+
+  test('different secrets produce different codes', async () => {
+    const s1 = generateSecret();
+    const s2 = generateSecret();
+    const c1 = await generateTOTP(s1);
+    const c2 = await generateTOTP(s2);
+    // Very unlikely to be the same
+    expect(s1).not.toBe(s2);
+    // Codes might collide, but secrets shouldn't
+  });
+});

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @svadmin/auth-utils — Zero-dependency auth utility functions.
+ *
+ * Provides password hashing, session management, and TOTP for MFA.
+ * Works on any runtime (Bun, Node.js, Deno, Cloudflare Workers) via Web Crypto API.
+ *
+ * @example
+ * ```ts
+ * import { hashPassword, verifyPassword, createSessionManager, generateSecret, verifyTOTP } from '@svadmin/auth-utils';
+ * ```
+ */
+
+// Password
+export { hashPassword, verifyPassword } from './password';
+export type { PasswordOptions } from './password';
+
+// Session
+export { createSessionManager } from './session';
+export type { SessionManager, SessionPayload, SessionOptions } from './session';
+
+// TOTP
+export { generateSecret, generateTOTP, verifyTOTP, generateQRUri } from './totp';
+export type { TOTPOptions } from './totp';

package/src/password.ts

@@ -0,0 +1,138 @@
+/**
+ * Password hashing and verification utilities.
+ *
+ * Uses Bun's native `Bun.password` API when available (Argon2id by default),
+ * with a Web Crypto API fallback using PBKDF2-SHA256 for non-Bun runtimes.
+ *
+ * @example
+ * ```ts
+ * import { hashPassword, verifyPassword } from '@svadmin/auth-utils/password';
+ *
+ * const hash = await hashPassword('my-password');
+ * const valid = await verifyPassword('my-password', hash);
+ * ```
+ */
+
+// ─── Types ────────────────────────────────────────────────────
+
+export interface PasswordOptions {
+  /**
+   * Algorithm to use. Default: 'auto' (uses Bun.password if available, else PBKDF2).
+   * - 'argon2id' — requires Bun runtime
+   * - 'bcrypt' — requires Bun runtime
+   * - 'pbkdf2' — Web Crypto API, works everywhere
+   * - 'auto' — best available
+   */
+  algorithm?: 'argon2id' | 'bcrypt' | 'pbkdf2' | 'auto';
+}
+
+// ─── Bun detection ────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const isBun = typeof (globalThis as any).Bun !== 'undefined';
+
+// ─── PBKDF2 fallback (Web Crypto API) ─────────────────────────
+
+const PBKDF2_ITERATIONS = 310_000; // OWASP recommended
+const PBKDF2_SALT_LENGTH = 32;
+const PBKDF2_KEY_LENGTH = 64;
+
+function toHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer), b => b.toString(16).padStart(2, '0')).join('');
+}
+
+function fromHex(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+async function pbkdf2Hash(password: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(PBKDF2_SALT_LENGTH));
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits'],
+  );
+  const derived = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt: salt as unknown as BufferSource, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
+    key,
+    PBKDF2_KEY_LENGTH * 8,
+  );
+  return `pbkdf2:${PBKDF2_ITERATIONS}:${toHex(salt.buffer)}:${toHex(derived)}`;
+}
+
+async function pbkdf2Verify(password: string, stored: string): Promise<boolean> {
+  const [, iterStr, saltHex, hashHex] = stored.split(':');
+  const iterations = parseInt(iterStr, 10);
+  const salt = fromHex(saltHex);
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits'],
+  );
+  const derived = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt: salt as unknown as BufferSource, iterations, hash: 'SHA-256' },
+    key,
+    PBKDF2_KEY_LENGTH * 8,
+  );
+  return toHex(derived) === hashHex;
+}
+
+// ─── Public API ───────────────────────────────────────────────
+
+/**
+ * Hash a password using the best available algorithm.
+ *
+ * @returns A string containing the algorithm prefix + hash, safe to store in DB.
+ */
+export async function hashPassword(
+  password: string,
+  opts?: PasswordOptions,
+): Promise<string> {
+  const algo = opts?.algorithm ?? 'auto';
+
+  if ((algo === 'auto' || algo === 'argon2id' || algo === 'bcrypt') && isBun) {
+    // Use Bun's native password API
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const BunPassword = (globalThis as any).Bun as { password: { hash: (p: string, opts?: { algorithm: string }) => Promise<string> } };
+    const bunAlgo = algo === 'auto' ? 'argon2id' : algo;
+    return BunPassword.password.hash(password, { algorithm: bunAlgo });
+  }
+
+  // Fallback to PBKDF2
+  return pbkdf2Hash(password);
+}
+
+/**
+ * Verify a password against a stored hash.
+ *
+ * @returns `true` if the password matches, `false` otherwise.
+ */
+export async function verifyPassword(
+  password: string,
+  hash: string,
+): Promise<boolean> {
+  // Auto-detect algorithm from hash format
+  if (hash.startsWith('pbkdf2:')) {
+    return pbkdf2Verify(password, hash);
+  }
+
+  // Argon2 / bcrypt hashes — use Bun.password.verify
+  if (isBun) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const BunPassword = (globalThis as any).Bun as { password: { verify: (p: string, h: string) => Promise<boolean> } };
+    return BunPassword.password.verify(password, hash);
+  }
+
+  throw new Error(
+    `[auth-utils] Cannot verify hash format "${hash.substring(0, 10)}...". ` +
+    'Argon2/bcrypt hashes require the Bun runtime.',
+  );
+}

package/src/session.ts

@@ -0,0 +1,139 @@
+/**
+ * Session token management — generate, validate, and parse session tokens.
+ *
+ * Uses HMAC-SHA256 signatures for stateless session cookies.
+ * The token format is: `base64url(payload).base64url(signature)`
+ *
+ * @example
+ * ```ts
+ * import { createSessionManager } from '@svadmin/auth-utils/session';
+ *
+ * const sessions = createSessionManager('your-secret-key');
+ *
+ * // Generate a session token
+ * const token = await sessions.create({ userId: '123', role: 'admin' });
+ *
+ * // Validate and parse
+ * const payload = await sessions.verify(token);
+ * if (payload) console.log(payload.userId);
+ * ```
+ */
+
+// ─── Types ────────────────────────────────────────────────────
+
+export interface SessionPayload {
+  /** User ID */
+  sub: string;
+  /** Issued at (unix seconds) */
+  iat: number;
+  /** Expiration (unix seconds) */
+  exp: number;
+  /** Custom data */
+  [key: string]: unknown;
+}
+
+export interface SessionOptions {
+  /** Session TTL in seconds. Default: 86400 (24 hours) */
+  ttl?: number;
+  /** Cookie name. Default: 'svadmin_session' */
+  cookieName?: string;
+}
+
+export interface SessionManager {
+  /** Create a new signed session token */
+  create: (data: Record<string, unknown>) => Promise<string>;
+  /** Verify and decode a session token. Returns null if invalid/expired. */
+  verify: (token: string) => Promise<SessionPayload | null>;
+  /** Generate a random session ID (32 bytes, hex) */
+  generateId: () => string;
+}
+
+// ─── Base64url helpers ────────────────────────────────────────
+
+function base64urlEncode(data: string): string {
+  return btoa(data).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlDecode(str: string): string {
+  const padded = str + '='.repeat((4 - (str.length % 4)) % 4);
+  return atob(padded.replace(/-/g, '+').replace(/_/g, '/'));
+}
+
+// ─── Factory ──────────────────────────────────────────────────
+
+/**
+ * Create a session manager with HMAC-SHA256 signed tokens.
+ *
+ * @param secret - Secret key for signing (minimum 32 characters recommended)
+ * @param options - Configuration options
+ */
+export function createSessionManager(
+  secret: string,
+  options?: SessionOptions,
+): SessionManager {
+  const ttl = options?.ttl ?? 86400;
+  let cryptoKey: CryptoKey | null = null;
+
+  async function getKey(): Promise<CryptoKey> {
+    if (cryptoKey) return cryptoKey;
+    cryptoKey = await crypto.subtle.importKey(
+      'raw',
+      new TextEncoder().encode(secret),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign', 'verify'],
+    );
+    return cryptoKey;
+  }
+
+  function toHex(buffer: ArrayBuffer): string {
+    return Array.from(new Uint8Array(buffer), b => b.toString(16).padStart(2, '0')).join('');
+  }
+
+  async function sign(payload: string): Promise<string> {
+    const key = await getKey();
+    const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload));
+    return toHex(sig);
+  }
+
+  return {
+    async create(data: Record<string, unknown>): Promise<string> {
+      const now = Math.floor(Date.now() / 1000);
+      const payload: SessionPayload = {
+        sub: (data.userId as string) ?? (data.sub as string) ?? '',
+        iat: now,
+        exp: now + ttl,
+        ...data,
+      };
+      const payloadStr = base64urlEncode(JSON.stringify(payload));
+      const signature = await sign(payloadStr);
+      return `${payloadStr}.${signature}`;
+    },
+
+    async verify(token: string): Promise<SessionPayload | null> {
+      const parts = token.split('.');
+      if (parts.length !== 2) return null;
+
+      const [payloadStr, signature] = parts;
+
+      // Verify signature
+      const expectedSig = await sign(payloadStr);
+      if (signature !== expectedSig) return null;
+
+      // Decode and check expiry
+      try {
+        const payload = JSON.parse(base64urlDecode(payloadStr)) as SessionPayload;
+        const now = Math.floor(Date.now() / 1000);
+        if (payload.exp && payload.exp < now) return null;
+        return payload;
+      } catch {
+        return null;
+      }
+    },
+
+    generateId(): string {
+      const bytes = crypto.getRandomValues(new Uint8Array(32));
+      return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    },
+  };
+}

package/src/totp.ts

@@ -0,0 +1,221 @@
+/**
+ * TOTP (Time-based One-Time Password) utilities for MFA.
+ *
+ * Implements RFC 6238 (TOTP) using Web Crypto API — zero dependencies.
+ *
+ * @example
+ * ```ts
+ * import { generateSecret, generateTOTP, verifyTOTP, generateQRUri } from '@svadmin/auth-utils/totp';
+ *
+ * // Setup: generate a secret and show QR code
+ * const secret = generateSecret();
+ * const qrUri = generateQRUri(secret, 'user@example.com', 'MyApp');
+ *
+ * // Verify user's code
+ * const valid = await verifyTOTP('123456', secret);
+ * ```
+ */
+
+// ─── Types ────────────────────────────────────────────────────
+
+export interface TOTPOptions {
+  /** Number of digits. Default: 6 */
+  digits?: number;
+  /** Time step in seconds. Default: 30 */
+  period?: number;
+  /** HMAC algorithm. Default: 'SHA-1' (per RFC 6238) */
+  algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+  /** Number of time steps to check before/after current. Default: 1 */
+  window?: number;
+}
+
+// ─── Base32 encoding/decoding ─────────────────────────────────
+
+const BASE32_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+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) {
+      result += BASE32_CHARS[(value >>> (bits - 5)) & 0x1f];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    result += BASE32_CHARS[(value << (5 - bits)) & 0x1f];
+  }
+  return result;
+}
+
+function base32Decode(encoded: string): Uint8Array {
+  const cleaned = encoded.toUpperCase().replace(/[^A-Z2-7]/g, '');
+  const output: number[] = [];
+  let bits = 0;
+  let value = 0;
+  for (const char of cleaned) {
+    const idx = BASE32_CHARS.indexOf(char);
+    if (idx === -1) continue;
+    value = (value << 5) | idx;
+    bits += 5;
+    if (bits >= 8) {
+      output.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(output);
+}
+
+// ─── HMAC ─────────────────────────────────────────────────────
+
+async function hmac(
+  algorithm: string,
+  key: Uint8Array,
+  data: Uint8Array,
+): Promise<Uint8Array> {
+  // Map algo names for Web Crypto
+  const algoMap: Record<string, string> = {
+    'SHA-1': 'SHA-1',
+    'SHA-256': 'SHA-256',
+    'SHA-512': 'SHA-512',
+  };
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    key as unknown as BufferSource,
+    { name: 'HMAC', hash: algoMap[algorithm] ?? 'SHA-1' },
+    false,
+    ['sign'],
+  );
+  const sig = await crypto.subtle.sign('HMAC', cryptoKey, data as unknown as BufferSource);
+  return new Uint8Array(sig);
+}
+
+// ─── HOTP (base for TOTP) ─────────────────────────────────────
+
+async function hotp(
+  secret: Uint8Array,
+  counter: number,
+  digits: number,
+  algorithm: string,
+): Promise<string> {
+  // Convert counter to 8-byte big-endian buffer
+  const buffer = new ArrayBuffer(8);
+  const view = new DataView(buffer);
+  view.setBigUint64(0, BigInt(counter));
+
+  const hash = await hmac(algorithm, secret, new Uint8Array(buffer));
+
+  // Dynamic truncation (RFC 4226 §5.4)
+  const offset = hash[hash.length - 1] & 0x0f;
+  const code =
+    ((hash[offset] & 0x7f) << 24) |
+    ((hash[offset + 1] & 0xff) << 16) |
+    ((hash[offset + 2] & 0xff) << 8) |
+    (hash[offset + 3] & 0xff);
+
+  return (code % 10 ** digits).toString().padStart(digits, '0');
+}
+
+// ─── Public API ───────────────────────────────────────────────
+
+/**
+ * Generate a random TOTP secret (20 bytes, base32 encoded).
+ */
+export function generateSecret(byteLength = 20): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(byteLength));
+  return base32Encode(bytes);
+}
+
+/**
+ * Generate a TOTP code for the current time.
+ *
+ * @param secret - Base32-encoded secret
+ * @param opts - TOTP options
+ * @returns The current TOTP code string
+ */
+export async function generateTOTP(
+  secret: string,
+  opts?: TOTPOptions,
+): Promise<string> {
+  const period = opts?.period ?? 30;
+  const digits = opts?.digits ?? 6;
+  const algorithm = opts?.algorithm ?? 'SHA-1';
+
+  const counter = Math.floor(Date.now() / 1000 / period);
+  const secretBytes = base32Decode(secret);
+  return hotp(secretBytes, counter, digits, algorithm);
+}
+
+/**
+ * Verify a TOTP code against the secret.
+ *
+ * Checks the current time step ± window.
+ *
+ * @param code - The code to verify
+ * @param secret - Base32-encoded secret
+ * @param opts - TOTP options
+ * @returns `true` if the code is valid
+ */
+export async function verifyTOTP(
+  code: string,
+  secret: string,
+  opts?: TOTPOptions,
+): Promise<boolean> {
+  const period = opts?.period ?? 30;
+  const digits = opts?.digits ?? 6;
+  const algorithm = opts?.algorithm ?? 'SHA-1';
+  const window = opts?.window ?? 1;
+
+  const now = Math.floor(Date.now() / 1000 / period);
+  const secretBytes = base32Decode(secret);
+
+  for (let i = -window; i <= window; i++) {
+    const expected = await hotp(secretBytes, now + i, digits, algorithm);
+    if (timingSafeEqual(code, expected)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Generate an `otpauth://` URI for QR code generation.
+ *
+ * @param secret - Base32-encoded secret
+ * @param accountName - User identifier (e.g., email)
+ * @param issuer - App name displayed in authenticator
+ * @param opts - TOTP options
+ */
+export function generateQRUri(
+  secret: string,
+  accountName: string,
+  issuer: string,
+  opts?: TOTPOptions,
+): string {
+  const period = opts?.period ?? 30;
+  const digits = opts?.digits ?? 6;
+  const algorithm = opts?.algorithm ?? 'SHA-1';
+
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: algorithm.replace('-', ''),
+    digits: String(digits),
+    period: String(period),
+  });
+
+  return `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(accountName)}?${params}`;
+}
+
+// ─── Timing-safe comparison ───────────────────────────────────
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}