totp-auth-service 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ameya Aklekar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# totp-auth
+
+Self-hostable TOTP MFA library for Node.js. Handles enrollment, verification, and single-use recovery codes — not full authentication (no sessions or JWTs).
+
+Your app owns primary login, sessions, and JWTs. This library only handles the **MFA step**: enroll, confirm, verify, revoke, and backup codes.
+
+---
+
+## Requirements
+
+- **Node.js 18+**
+- A **database** (or other store) where you implement `StorageAdapter`
+- **Server-side only** — do not bundle `TOTPService` or secrets into a browser/React client
+
+---
+
+## Install
+
+```bash
+npm install totp-auth-service
+```
+
+The unscoped name `totp-auth` is already registered on npm; this package publishes as **`totp-auth-service`** (same repo).
+
+### Develop from a git clone
+
+```bash
+git clone https://github.com/ameyaaklekar/totp-auth-service.git
+cd totp-auth-service
+npm install
+npm run build
+```
+
+Link into another project while developing:
+
+```bash
+npm link
+# in your app directory:
+npm link totp-auth-service
+```
+
+---
+
+## Setup guide
+
+### 1. Create a server-side `TOTPService` instance
+
+Instantiate once per process (or per request with a shared adapter) in your Node API layer — Express, Fastify, Next.js Route Handlers, etc.
+
+```typescript
+// lib/totp.ts
+import { TOTPService, TotpAlgorithm } from 'totp-auth-service'
+import { myStorageAdapter } from './totp-storage.js'
+
+export const totp = new TOTPService({
+  storage: myStorageAdapter,
+  issuer: 'MyApp',              // shown in authenticator apps
+  digits: 6,                    // 6 or 8 (default: 6)
+  period: 30,                   // seconds (default: 30)
+  algorithm: TotpAlgorithm.SHA1,
+  window: 1,                    // ±1 period clock drift (default: 1)
+  recoveryCodeCount: 10,        // backup codes on confirm (default: 10)
+})
+```
+
+### 2. Implement `StorageAdapter`
+
+The library does not ship database adapters. Implement the interface for Postgres, Redis, MongoDB, Supabase, etc.
+
+**Tables (conceptual):**
+
+| Table / collection | Fields |
+|--------------------|--------|
+| `totp_enrollments` | `userId`, `secret` (Base32), `status`, `createdAt`, `confirmedAt`, `revokedAt` |
+| `totp_recovery_codes` | `userId`, `codeHash` (SHA-256 hex), `usedAt` |
+
+**Contracts:**
+
+- `saveEnrollment` — upsert by `userId`
+- `getEnrollment` — return `null` if missing (do not throw)
+- `getRecoveryCodes` — return `[]` if none
+- Only **hashed** recovery codes are stored; plaintext is returned once from `confirm()` / `regenerateRecoveryCodes()`
+- Serialize concurrent writes per `userId` in your adapter (DB locks or atomic updates)
+
+```typescript
+import type { StorageAdapter, TOTPEnrollment, RecoveryCode } from 'totp-auth-service'
+
+export const myStorageAdapter: StorageAdapter = {
+  async saveEnrollment(enrollment) { /* upsert */ },
+  async getEnrollment(userId) { /* ... */ },
+  async updateEnrollment(userId, patch) { /* ... */ },
+  async deleteEnrollment(userId) { /* ... */ },
+  async saveRecoveryCodes(codes) { /* replace batch for user */ },
+  async getRecoveryCodes(userId) { /* ... */ },
+  async markRecoveryCodeUsed(userId, codeHash) { /* ... */ },
+  async deleteRecoveryCodes(userId) { /* ... */ },
+}
+```
+
+Use `MemoryAdapter` from `totp-auth-service/testing` only in tests — not in production.
+
+### 3. Expose HTTP routes (your app)
+
+The library has no built-in HTTP layer. Map methods to routes after the user is authenticated (session/JWT with `userId`).
+
+| Route (example) | Method | `TOTPService` |
+|-----------------|--------|----------------|
+| `POST /api/mfa/enroll` | Start setup | `enroll(userId)` |
+| `POST /api/mfa/confirm` | First code from app | `confirm(userId, code)` |
+| `POST /api/mfa/verify` | Login MFA step | `verify(userId, code)` |
+| `GET /api/mfa/status` | Settings UI | `getStatus(userId)` |
+| `POST /api/mfa/revoke` | Disable 2FA | `revoke(userId)` |
+| `POST /api/mfa/recovery/regenerate` | New backup codes | `regenerateRecoveryCodes(userId)` |
+| `DELETE /api/user` (or similar) | Account deletion | `delete(userId)` |
+
+**Example — enroll (Next.js Route Handler):**
+
+```typescript
+import { totp } from '@/lib/totp'
+import { getSessionUserId } from '@/lib/auth'
+
+export async function POST() {
+  const userId = await getSessionUserId()
+  const { otpAuthUri } = await totp.enroll(userId)
+  return Response.json({ otpAuthUri })
+}
+```
+
+**Example — verify after password login:**
+
+```typescript
+export async function POST(req: Request) {
+  const userId = await getPartialLoginUserId()
+  const { code } = await req.json()
+  const result = await totp.verify(userId, code)
+  if (!result.valid) {
+    return Response.json({ valid: false }, { status: 401 })
+  }
+  await issueSession(userId) // your auth — not part of totp-auth
+  return Response.json(result)
+}
+```
+
+Map thrown errors to HTTP status + JSON `{ code: 'ENROLLMENT_NOT_FOUND' }` using `TOTPErrorCode` from `totp-auth-service`.
+
+### 4. React (or any frontend)
+
+React talks to **your API**, not to `TOTPService` directly.
+
+1. **Enroll** — `POST /api/mfa/enroll` → render QR from `otpAuthUri` (e.g. `react-qr-code`).
+2. **Confirm** — user enters 6-digit code → `POST /api/mfa/confirm` → show `recoveryCodes` once; user must save them.
+3. **Login MFA** — after password step, show code input → `POST /api/mfa/verify` → on success, complete session in your API.
+
+Never return the shared secret to the client in production if you can avoid it; `otpAuthUri` alone is enough for QR setup.
+
+```tsx
+// Client — fetch only, no totp-auth import
+const res = await fetch('/api/mfa/enroll', { method: 'POST' })
+const { otpAuthUri } = await res.json()
+```
+
+### 5. Enrollment state machine
+
+```
+[none | revoked] --enroll()--> pending --confirm()--> active --revoke()--> revoked
+```
+
+| Method | Allowed when |
+|--------|----------------|
+| `enroll()` | No row, or `revoked` |
+| `confirm()` | `pending` |
+| `verify()` | `active` |
+| `revoke()` | `pending` or `active` |
+| `regenerateRecoveryCodes()` | `active` |
+| `delete()` | Always (no throw) |
+
+Full API details: [Requirements.md](./Requirements.md).
+
+---
+
+## Quick start (Node script / tests)
+
+```typescript
+import { TOTPService, EnrollmentStatus, TOTPErrorCode } from 'totp-auth-service'
+import { generateCode } from 'totp-auth-service/crypto'
+import { MemoryAdapter } from 'totp-auth-service/testing'
+
+const totp = new TOTPService({
+  storage: new MemoryAdapter(),
+  issuer: 'MyApp',
+})
+
+const userId = 'user-123'
+
+const { secret, otpAuthUri } = await totp.enroll(userId)
+console.log(otpAuthUri) // otpauth://totp/...
+
+const { recoveryCodes } = await totp.confirm(userId, generateCode(secret))
+console.log(recoveryCodes) // save once; not recoverable later
+
+const { valid } = await totp.verify(userId, generateCode(secret))
+console.log(valid) // true
+```
+
+---
+
+## Development (this repository)
+
+```bash
+npm install
+npm run build      # dist/ (CJS + ESM + .d.ts)
+npm test           # unit + service tests
+npm run test:watch
+npm run typecheck
+```
+
+### Manual demo with QR code
+
+Runs the full enroll → confirm → verify flow and prints a scannable QR (terminal + PNG):
+
+```bash
+npm run demo
+```
+
+- Terminal: ASCII QR from `otpauth://` URI
+- File: `totp-qr.png` in the project root (open and scan with Google Authenticator, etc.)
+- The script still uses `generateCode()` for confirm/verify so it finishes without typing a code; scan the QR only if you want to compare with a real app
+
+---
+
+## Entry points
+
+| Import | Purpose |
+|--------|---------|
+| `totp-auth-service` | `TOTPService`, `StorageAdapter`, errors, enums |
+| `totp-auth-service/crypto` | `generateSecret`, `buildOtpAuthUri`, `generateCode`, `verifyCode` |
+| `totp-auth-service/testing` | `MemoryAdapter` (tests only) |
+
+**Public enums:** `EnrollmentStatus`, `TotpAlgorithm`, `TOTPErrorCode`.
+
+---
+
+## Publishing (maintainers)
+
+1. Log in: `npm login`
+2. Dry-run the tarball: `npm pack --dry-run`
+3. Publish: `npm publish` (runs `prepublishOnly` → build + tests)
+
+Or create a [GitHub Release](https://github.com/ameyaaklekar/totp-auth-service/releases) — the `publish-npm` workflow publishes the release tag version when `NPM_TOKEN` is set in repo secrets.
+
+---
+
+## License
+
+MIT

package/dist/crypto.cjs

@@ -0,0 +1,145 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/crypto/secret.ts
+
+// src/crypto/base32.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function encodeBase32(buffer) {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (const byte of buffer) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output += ALPHABET[value << 5 - bits & 31];
+  }
+  return output;
+}
+function decodeBase32(encoded) {
+  const normalized = encoded.replace(/=+$/, "").toUpperCase();
+  let bits = 0;
+  let value = 0;
+  const bytes = [];
+  for (const char of normalized) {
+    const index = ALPHABET.indexOf(char);
+    if (index === -1) {
+      throw new Error(`Invalid base32 character: ${char}`);
+    }
+    value = value << 5 | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(bytes);
+}
+
+// src/crypto/secret.ts
+var DEFAULT_BYTE_LENGTH = 20;
+function generateSecret(options) {
+  const byteLength = options?.length ?? DEFAULT_BYTE_LENGTH;
+  if (byteLength < 16) {
+    throw new Error("Secret length must be at least 16 bytes");
+  }
+  return encodeBase32(crypto.randomBytes(byteLength));
+}
+
+// src/enums/totp-algorithm.ts
+var TotpAlgorithm = /* @__PURE__ */ ((TotpAlgorithm2) => {
+  TotpAlgorithm2["SHA1"] = "SHA1";
+  TotpAlgorithm2["SHA256"] = "SHA256";
+  TotpAlgorithm2["SHA512"] = "SHA512";
+  return TotpAlgorithm2;
+})(TotpAlgorithm || {});
+
+// src/crypto/uri.ts
+function buildOtpAuthUri(options) {
+  const digits = options.digits ?? 6;
+  const period = options.period ?? 30;
+  const algorithm = options.algorithm ?? "SHA1" /* SHA1 */;
+  const label = encodeURIComponent(`${options.issuer}:${options.accountName}`);
+  const params = new URLSearchParams({
+    secret: options.secret,
+    issuer: options.issuer,
+    algorithm,
+    digits: String(digits),
+    period: String(period)
+  });
+  return `otpauth://totp/${label}?${params.toString()}`;
+}
+function algorithmToHashName(algorithm) {
+  switch (algorithm) {
+    case "SHA256" /* SHA256 */:
+      return "sha256";
+    case "SHA512" /* SHA512 */:
+      return "sha512";
+    default:
+      return "sha1";
+  }
+}
+function counterToBuffer(counter) {
+  const buf = Buffer.alloc(8);
+  let value = counter;
+  for (let i = 7; i >= 0; i--) {
+    buf[i] = value & 255;
+    value = Math.floor(value / 256);
+  }
+  return buf;
+}
+function hotp(secret, counter, digits, algorithm) {
+  const hmac = crypto.createHmac(algorithmToHashName(algorithm), secret);
+  hmac.update(counterToBuffer(counter));
+  const digest = hmac.digest();
+  const offset = digest[digest.length - 1] & 15;
+  const binary = (digest[offset] & 127) << 24 | (digest[offset + 1] & 255) << 16 | (digest[offset + 2] & 255) << 8 | digest[offset + 3] & 255;
+  const otp = binary % 10 ** digits;
+  return otp.toString().padStart(digits, "0");
+}
+function resolveTimestamp(timestamp) {
+  return timestamp ?? Date.now();
+}
+function generateCode(secret, options) {
+  const period = options?.period ?? 30;
+  const digits = options?.digits ?? 6;
+  const algorithm = options?.algorithm ?? "SHA1" /* SHA1 */;
+  const timestamp = resolveTimestamp(options?.timestamp);
+  const counter = Math.floor(timestamp / 1e3 / period);
+  const key = decodeBase32(secret);
+  return hotp(key, counter, digits, algorithm);
+}
+function verifyCode(secret, code, options) {
+  const period = options?.period ?? 30;
+  const digits = options?.digits ?? 6;
+  const window = options?.window ?? 0;
+  const algorithm = options?.algorithm ?? "SHA1" /* SHA1 */;
+  const timestamp = resolveTimestamp(options?.timestamp);
+  const counter = Math.floor(timestamp / 1e3 / period);
+  const key = decodeBase32(secret);
+  const normalized = code.replace(/\s/g, "");
+  if (!/^\d+$/.test(normalized) || normalized.length !== digits) {
+    return false;
+  }
+  for (let drift = -window; drift <= window; drift++) {
+    if (hotp(key, counter + drift, digits, algorithm) === normalized) {
+      return true;
+    }
+  }
+  return false;
+}
+
+exports.TotpAlgorithm = TotpAlgorithm;
+exports.buildOtpAuthUri = buildOtpAuthUri;
+exports.generateCode = generateCode;
+exports.generateSecret = generateSecret;
+exports.verifyCode = verifyCode;
+//# sourceMappingURL=crypto.cjs.map
+//# sourceMappingURL=crypto.cjs.map

package/dist/crypto.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/crypto/base32.ts","../src/crypto/secret.ts","../src/enums/totp-algorithm.ts","../src/crypto/uri.ts","../src/crypto/verify.ts"],"names":["randomBytes","TotpAlgorithm","createHmac"],"mappings":"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","file":"crypto.cjs","sourcesContent":["/**\n * RFC 4648 Base32 encode/decode for TOTP shared secrets.\n *\n * Authenticator apps and otpauth:// URIs store secrets as Base32 text (A–Z, 2–7),\n * not raw bytes. generateSecret() encodes random bytes; verifyCode() decodes\n * before HMAC. No padding is required for typical OTP secret lengths.\n */\nconst ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'\n\n/** Pack raw bytes into a Base32 string (5 bits per alphabet character). */\nexport function encodeBase32(buffer: Buffer): string {\n  let bits = 0\n  let value = 0\n  let output = ''\n\n  for (const byte of buffer) {\n    value = (value << 8) | byte\n    bits += 8\n\n    while (bits >= 5) {\n      output += ALPHABET[(value >>> (bits - 5)) & 31]\n      bits -= 5\n    }\n  }\n\n  // Emit final partial quintet if the byte stream did not align on 5-bit boundaries.\n  if (bits > 0) {\n    output += ALPHABET[(value << (5 - bits)) & 31]\n  }\n\n  return output\n}\n\n/** Unpack a Base32 secret string into the raw key bytes used by HMAC. */\nexport function decodeBase32(encoded: string): Buffer {\n  const normalized = encoded.replace(/=+$/, '').toUpperCase()\n  let bits = 0\n  let value = 0\n  const bytes: number[] = []\n\n  for (const char of normalized) {\n    const index = ALPHABET.indexOf(char)\n    if (index === -1) {\n      throw new Error(`Invalid base32 character: ${char}`)\n    }\n\n    value = (value << 5) | index\n    bits += 5\n\n    if (bits >= 8) {\n      bytes.push((value >>> (bits - 8)) & 255)\n      bits -= 8\n    }\n  }\n\n  return Buffer.from(bytes)\n}\n","import { randomBytes } from 'crypto'\nimport { encodeBase32 } from './base32.js'\n\n/** 20 bytes → ~32 Base32 chars; matches common authenticator defaults. */\nconst DEFAULT_BYTE_LENGTH = 20\n\n/**\n * Create a cryptographically random TOTP shared secret (Base32).\n * Consumers persist this via StorageAdapter during enroll().\n */\nexport function generateSecret(options?: { length?: number }): string {\n  const byteLength = options?.length ?? DEFAULT_BYTE_LENGTH\n  // RFC 4226 recommends at least 128 bits (16 bytes) of entropy for the secret.\n  if (byteLength < 16) {\n    throw new Error('Secret length must be at least 16 bytes')\n  }\n  return encodeBase32(randomBytes(byteLength))\n}\n","/** HMAC algorithm for TOTP (otpauth `algorithm` param and HMAC digest). */\nexport enum TotpAlgorithm {\n  SHA1 = 'SHA1',\n  SHA256 = 'SHA256',\n  SHA512 = 'SHA512',\n}\n","import { TotpAlgorithm } from '../enums/totp-algorithm.js'\n\nexport interface BuildOtpAuthUriOptions {\n  secret: string\n  accountName: string\n  issuer: string\n  digits?: number\n  period?: number\n  algorithm?: TotpAlgorithm\n}\n\n/**\n * Build an otpauth://totp/ URI for QR codes and manual entry in authenticator apps.\n * Label format follows the de-facto `Issuer:account` convention (both URL-encoded).\n */\nexport function buildOtpAuthUri(options: BuildOtpAuthUriOptions): string {\n  const digits = options.digits ?? 6\n  const period = options.period ?? 30\n  const algorithm = options.algorithm ?? TotpAlgorithm.SHA1\n\n  const label = encodeURIComponent(`${options.issuer}:${options.accountName}`)\n  const params = new URLSearchParams({\n    secret: options.secret,\n    issuer: options.issuer,\n    algorithm,\n    digits: String(digits),\n    period: String(period),\n  })\n\n  return `otpauth://totp/${label}?${params.toString()}`\n}\n","/**\n * RFC 4226 (HOTP) and RFC 6238 (TOTP) — pure functions, no I/O.\n *\n * TOTP is HOTP with counter = floor(unixTime / period). Injectable `timestamp`\n * keeps tests deterministic without mocking Date or global time.\n */\nimport { createHmac } from 'crypto'\nimport { TotpAlgorithm } from '../enums/totp-algorithm.js'\nimport { decodeBase32 } from './base32.js'\n\nexport interface TotpOptions {\n  period?: number\n  digits?: number\n  /** Defaults to Date.now(); pass in tests for fixed codes. */\n  timestamp?: number\n  algorithm?: TotpAlgorithm\n}\n\nexport interface VerifyCodeOptions extends TotpOptions {\n  /** Drift tolerance in 30s (or custom) periods — checks counter ± window. */\n  window?: number\n}\n\nfunction algorithmToHashName(algorithm: TotpAlgorithm): string {\n  switch (algorithm) {\n    case TotpAlgorithm.SHA256:\n      return 'sha256'\n    case TotpAlgorithm.SHA512:\n      return 'sha512'\n    default:\n      return 'sha1'\n  }\n}\n\n/**\n * RFC 4226 §5.1: counter must be an 8-byte big-endian integer in the HMAC input.\n */\nfunction counterToBuffer(counter: number): Buffer {\n  const buf = Buffer.alloc(8)\n  let value = counter\n  for (let i = 7; i >= 0; i--) {\n    buf[i] = value & 0xff\n    value = Math.floor(value / 256)\n  }\n  return buf\n}\n\n/**\n * HMAC-based One-Time Password (RFC 4226).\n * TOTP calls this with a time-derived counter; verifyCode may call it for\n * neighboring counters when `window` > 0 (clock skew).\n */\nfunction hotp(\n  secret: Buffer,\n  counter: number,\n  digits: number,\n  algorithm: TotpAlgorithm,\n): string {\n  const hmac = createHmac(algorithmToHashName(algorithm), secret)\n  hmac.update(counterToBuffer(counter))\n  const digest = hmac.digest()\n\n  // Dynamic truncation (RFC 4226 §5.3): derive a 31-bit value from the HMAC digest.\n  const offset = digest[digest.length - 1]! & 0x0f\n  const binary =\n    ((digest[offset]! & 0x7f) << 24) |\n    ((digest[offset + 1]! & 0xff) << 16) |\n    ((digest[offset + 2]! & 0xff) << 8) |\n    (digest[offset + 3]! & 0xff)\n\n  const otp = binary % 10 ** digits\n  return otp.toString().padStart(digits, '0')\n}\n\nfunction resolveTimestamp(timestamp?: number): number {\n  return timestamp ?? Date.now()\n}\n\n/** Generate the TOTP code for the current (or injected) time slice. */\nexport function generateCode(\n  secret: string,\n  options?: TotpOptions,\n): string {\n  const period = options?.period ?? 30\n  const digits = options?.digits ?? 6\n  const algorithm = options?.algorithm ?? TotpAlgorithm.SHA1\n  const timestamp = resolveTimestamp(options?.timestamp)\n  const counter = Math.floor(timestamp / 1000 / period)\n  const key = decodeBase32(secret)\n  return hotp(key, counter, digits, algorithm)\n}\n\n/**\n * Constant-time comparison is not used here; timing leaks on OTP verify are a\n * secondary concern vs. rate limiting (out of scope for v1). Returns false for\n * malformed input instead of throwing.\n */\nexport function verifyCode(\n  secret: string,\n  code: string,\n  options?: VerifyCodeOptions,\n): boolean {\n  const period = options?.period ?? 30\n  const digits = options?.digits ?? 6\n  const window = options?.window ?? 0\n  const algorithm = options?.algorithm ?? TotpAlgorithm.SHA1\n  const timestamp = resolveTimestamp(options?.timestamp)\n  const counter = Math.floor(timestamp / 1000 / period)\n  const key = decodeBase32(secret)\n\n  const normalized = code.replace(/\\s/g, '')\n  if (!/^\\d+$/.test(normalized) || normalized.length !== digits) {\n    return false\n  }\n\n  for (let drift = -window; drift <= window; drift++) {\n    if (hotp(key, counter + drift, digits, algorithm) === normalized) {\n      return true\n    }\n  }\n\n  return false\n}\n"]}

package/dist/crypto.d.cts

@@ -0,0 +1,45 @@
+import { T as TotpAlgorithm } from './totp-algorithm-CUpdtI9d.cjs';
+
+/**
+ * Create a cryptographically random TOTP shared secret (Base32).
+ * Consumers persist this via StorageAdapter during enroll().
+ */
+declare function generateSecret(options?: {
+    length?: number;
+}): string;
+
+interface BuildOtpAuthUriOptions {
+    secret: string;
+    accountName: string;
+    issuer: string;
+    digits?: number;
+    period?: number;
+    algorithm?: TotpAlgorithm;
+}
+/**
+ * Build an otpauth://totp/ URI for QR codes and manual entry in authenticator apps.
+ * Label format follows the de-facto `Issuer:account` convention (both URL-encoded).
+ */
+declare function buildOtpAuthUri(options: BuildOtpAuthUriOptions): string;
+
+interface TotpOptions {
+    period?: number;
+    digits?: number;
+    /** Defaults to Date.now(); pass in tests for fixed codes. */
+    timestamp?: number;
+    algorithm?: TotpAlgorithm;
+}
+interface VerifyCodeOptions extends TotpOptions {
+    /** Drift tolerance in 30s (or custom) periods — checks counter ± window. */
+    window?: number;
+}
+/** Generate the TOTP code for the current (or injected) time slice. */
+declare function generateCode(secret: string, options?: TotpOptions): string;
+/**
+ * Constant-time comparison is not used here; timing leaks on OTP verify are a
+ * secondary concern vs. rate limiting (out of scope for v1). Returns false for
+ * malformed input instead of throwing.
+ */
+declare function verifyCode(secret: string, code: string, options?: VerifyCodeOptions): boolean;
+
+export { type BuildOtpAuthUriOptions, TotpAlgorithm, type TotpOptions, type VerifyCodeOptions, buildOtpAuthUri, generateCode, generateSecret, verifyCode };

package/dist/crypto.d.ts

@@ -0,0 +1,45 @@
+import { T as TotpAlgorithm } from './totp-algorithm-CUpdtI9d.js';
+
+/**
+ * Create a cryptographically random TOTP shared secret (Base32).
+ * Consumers persist this via StorageAdapter during enroll().
+ */
+declare function generateSecret(options?: {
+    length?: number;
+}): string;
+
+interface BuildOtpAuthUriOptions {
+    secret: string;
+    accountName: string;
+    issuer: string;
+    digits?: number;
+    period?: number;
+    algorithm?: TotpAlgorithm;
+}
+/**
+ * Build an otpauth://totp/ URI for QR codes and manual entry in authenticator apps.
+ * Label format follows the de-facto `Issuer:account` convention (both URL-encoded).
+ */
+declare function buildOtpAuthUri(options: BuildOtpAuthUriOptions): string;
+
+interface TotpOptions {
+    period?: number;
+    digits?: number;
+    /** Defaults to Date.now(); pass in tests for fixed codes. */
+    timestamp?: number;
+    algorithm?: TotpAlgorithm;
+}
+interface VerifyCodeOptions extends TotpOptions {
+    /** Drift tolerance in 30s (or custom) periods — checks counter ± window. */
+    window?: number;
+}
+/** Generate the TOTP code for the current (or injected) time slice. */
+declare function generateCode(secret: string, options?: TotpOptions): string;
+/**
+ * Constant-time comparison is not used here; timing leaks on OTP verify are a
+ * secondary concern vs. rate limiting (out of scope for v1). Returns false for
+ * malformed input instead of throwing.
+ */
+declare function verifyCode(secret: string, code: string, options?: VerifyCodeOptions): boolean;
+
+export { type BuildOtpAuthUriOptions, TotpAlgorithm, type TotpOptions, type VerifyCodeOptions, buildOtpAuthUri, generateCode, generateSecret, verifyCode };

package/dist/crypto.js

@@ -0,0 +1,139 @@
+import { randomBytes, createHmac } from 'crypto';
+
+// src/crypto/secret.ts
+
+// src/crypto/base32.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function encodeBase32(buffer) {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (const byte of buffer) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output += ALPHABET[value << 5 - bits & 31];
+  }
+  return output;
+}
+function decodeBase32(encoded) {
+  const normalized = encoded.replace(/=+$/, "").toUpperCase();
+  let bits = 0;
+  let value = 0;
+  const bytes = [];
+  for (const char of normalized) {
+    const index = ALPHABET.indexOf(char);
+    if (index === -1) {
+      throw new Error(`Invalid base32 character: ${char}`);
+    }
+    value = value << 5 | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(bytes);
+}
+
+// src/crypto/secret.ts
+var DEFAULT_BYTE_LENGTH = 20;
+function generateSecret(options) {
+  const byteLength = options?.length ?? DEFAULT_BYTE_LENGTH;
+  if (byteLength < 16) {
+    throw new Error("Secret length must be at least 16 bytes");
+  }
+  return encodeBase32(randomBytes(byteLength));
+}
+
+// src/enums/totp-algorithm.ts
+var TotpAlgorithm = /* @__PURE__ */ ((TotpAlgorithm2) => {
+  TotpAlgorithm2["SHA1"] = "SHA1";
+  TotpAlgorithm2["SHA256"] = "SHA256";
+  TotpAlgorithm2["SHA512"] = "SHA512";
+  return TotpAlgorithm2;
+})(TotpAlgorithm || {});
+
+// src/crypto/uri.ts
+function buildOtpAuthUri(options) {
+  const digits = options.digits ?? 6;
+  const period = options.period ?? 30;
+  const algorithm = options.algorithm ?? "SHA1" /* SHA1 */;
+  const label = encodeURIComponent(`${options.issuer}:${options.accountName}`);
+  const params = new URLSearchParams({
+    secret: options.secret,
+    issuer: options.issuer,
+    algorithm,
+    digits: String(digits),
+    period: String(period)
+  });
+  return `otpauth://totp/${label}?${params.toString()}`;
+}
+function algorithmToHashName(algorithm) {
+  switch (algorithm) {
+    case "SHA256" /* SHA256 */:
+      return "sha256";
+    case "SHA512" /* SHA512 */:
+      return "sha512";
+    default:
+      return "sha1";
+  }
+}
+function counterToBuffer(counter) {
+  const buf = Buffer.alloc(8);
+  let value = counter;
+  for (let i = 7; i >= 0; i--) {
+    buf[i] = value & 255;
+    value = Math.floor(value / 256);
+  }
+  return buf;
+}
+function hotp(secret, counter, digits, algorithm) {
+  const hmac = createHmac(algorithmToHashName(algorithm), secret);
+  hmac.update(counterToBuffer(counter));
+  const digest = hmac.digest();
+  const offset = digest[digest.length - 1] & 15;
+  const binary = (digest[offset] & 127) << 24 | (digest[offset + 1] & 255) << 16 | (digest[offset + 2] & 255) << 8 | digest[offset + 3] & 255;
+  const otp = binary % 10 ** digits;
+  return otp.toString().padStart(digits, "0");
+}
+function resolveTimestamp(timestamp) {
+  return timestamp ?? Date.now();
+}
+function generateCode(secret, options) {
+  const period = options?.period ?? 30;
+  const digits = options?.digits ?? 6;
+  const algorithm = options?.algorithm ?? "SHA1" /* SHA1 */;
+  const timestamp = resolveTimestamp(options?.timestamp);
+  const counter = Math.floor(timestamp / 1e3 / period);
+  const key = decodeBase32(secret);
+  return hotp(key, counter, digits, algorithm);
+}
+function verifyCode(secret, code, options) {
+  const period = options?.period ?? 30;
+  const digits = options?.digits ?? 6;
+  const window = options?.window ?? 0;
+  const algorithm = options?.algorithm ?? "SHA1" /* SHA1 */;
+  const timestamp = resolveTimestamp(options?.timestamp);
+  const counter = Math.floor(timestamp / 1e3 / period);
+  const key = decodeBase32(secret);
+  const normalized = code.replace(/\s/g, "");
+  if (!/^\d+$/.test(normalized) || normalized.length !== digits) {
+    return false;
+  }
+  for (let drift = -window; drift <= window; drift++) {
+    if (hotp(key, counter + drift, digits, algorithm) === normalized) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export { TotpAlgorithm, buildOtpAuthUri, generateCode, generateSecret, verifyCode };
+//# sourceMappingURL=crypto.js.map
+//# sourceMappingURL=crypto.js.map