@noy-db/on-email-otp 0.2.0-pre.8 → 0.3.0-pre.1

package/README.md

@@ -26,7 +26,7 @@ See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup,
 
 - Source — [`packages/on-email-otp`](https://github.com/vLannaAi/noy-db/tree/main/packages/on-email-otp)
 - Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
-- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db/blob/main/SPEC.md)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db-docs/blob/main/SPEC.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/on-email-otp",
-  "version": "0.2.0-pre.8",
+  "version": "0.3.0-pre.1",
   "description": "Email OTP second factor for noy-db — generates time-boxed one-time codes, delivers via a user-supplied transport (SMTP / SES / Postmark / any fn), and verifies in constant time. Part of the @noy-db/on-* authentication family.",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -17,17 +17,10 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -36,14 +29,14 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "0.2.0-pre.8"
+    "@noy-db/hub": "0.3.0-pre.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@noy-db/hub": "0.2.0-pre.8"
+    "@noy-db/hub": "0.3.0-pre.1"
   },
   "keywords": [
     "noy-db",

package/dist/index.cjs

@@ -1,118 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  issue: () => issue,
-  verify: () => verify
-});
-module.exports = __toCommonJS(index_exports);
-async function issue(options) {
-  const digits = options.digits ?? 6;
-  const ttl = options.ttlSeconds ?? 300;
-  const maxAttempts = options.maxAttempts ?? 5;
-  const code = randomNumericCode(digits);
-  const saltBytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
-  const salt = toHex(saltBytes);
-  const digest = await hashCodeWithSalt(code, salt);
-  const issuedAt = /* @__PURE__ */ new Date();
-  const expiresAt = new Date(issuedAt.getTime() + ttl * 1e3);
-  const record = {
-    email: options.email,
-    digest,
-    salt,
-    issuedAt: issuedAt.toISOString(),
-    expiresAt: expiresAt.toISOString(),
-    maxAttempts,
-    attempts: 0
-  };
-  await options.transport({
-    to: options.email,
-    code,
-    issuedAt: record.issuedAt,
-    expiresAt: record.expiresAt
-  });
-  return { record };
-}
-async function verify(input, record) {
-  if (record.attempts >= record.maxAttempts) {
-    return { ok: false, reason: "locked", remainingAttempts: 0 };
-  }
-  record.attempts += 1;
-  if (new Date(record.expiresAt).getTime() <= Date.now()) {
-    return { ok: false, reason: "expired", remainingAttempts: record.maxAttempts - record.attempts };
-  }
-  const digest = await hashCodeWithSalt(input, record.salt);
-  if (!constantTimeEqual(digest, record.digest)) {
-    return {
-      ok: false,
-      reason: record.attempts >= record.maxAttempts ? "locked" : "mismatch",
-      remainingAttempts: record.maxAttempts - record.attempts
-    };
-  }
-  return { ok: true, remainingAttempts: record.maxAttempts - record.attempts };
-}
-function randomNumericCode(digits) {
-  const max = 10 ** digits;
-  const bytes = new Uint32Array(1);
-  const threshold = Math.floor(4294967295 / max) * max;
-  while (true) {
-    globalThis.crypto.getRandomValues(bytes);
-    if (bytes[0] < threshold) {
-      return (bytes[0] % max).toString().padStart(digits, "0");
-    }
-  }
-}
-async function hashCodeWithSalt(code, saltHex) {
-  const enc = new TextEncoder();
-  const codeBytes = enc.encode(code);
-  const saltBytes = fromHex(saltHex);
-  const combined = new Uint8Array(codeBytes.length + saltBytes.length);
-  combined.set(codeBytes, 0);
-  combined.set(saltBytes, codeBytes.length);
-  const digest = await globalThis.crypto.subtle.digest("SHA-256", combined);
-  return toHex(new Uint8Array(digest));
-}
-function constantTimeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return diff === 0;
-}
-function toHex(bytes) {
-  let out = "";
-  for (const b of bytes) out += b.toString(16).padStart(2, "0");
-  return out;
-}
-function fromHex(hex) {
-  const out = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < out.length; i++) {
-    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  return out;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  issue,
-  verify
-});
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/on-email-otp** — email OTP second factor.\n *\n * Issues short-lived numeric codes, delivers via a **caller-supplied\n * transport** (SMTP / SES / Postmark / Resend / Mailgun / a test\n * sink), and verifies them in constant time with a one-use burn\n * guarantee.\n *\n * **Why no bundled SMTP client?** Every consumer already has an email\n * sender in their stack — coupling noy-db to a specific SMTP library\n * would pull in Node-only dependencies and complicate browser /\n * edge-worker usage. The transport abstraction is a single-method\n * interface; write a 5-line adapter for whatever you use today.\n *\n * ## Usage\n *\n * ```ts\n * import { issue, verify } from '@noy-db/on-email-otp'\n *\n * // Challenge issue (server side, post-passphrase)\n * const challenge = await issue({\n *   email: 'alice@example.com',\n *   ttlSeconds: 300,\n *   transport: async ({ to, code, expiresAt }) => {\n *     await smtp.send({ to, subject: 'Your code', text: `${code} — expires at ${expiresAt}` })\n *   },\n * })\n * // Store `challenge.record` somewhere the verifier can retrieve later.\n *\n * // Verify\n * const ok = await verify('123456', challenge.record)\n * ```\n *\n * ## Security model\n *\n * - Codes are 6-digit random numbers (by default) — 10⁶ space is\n *   fine because verification is rate-limited at the caller (by\n *   burning on success + a `maxAttempts` guard stored in the record).\n * - The record carries `sha256(code + salt)` — the plaintext code is\n *   never written to storage. Verification hashes the input with the\n *   stored salt and compares in constant time.\n * - `expiresAt` is enforced on every `verify()` — expired records are\n *   rejected before the hash comparison.\n * - Burn-on-success is the caller's responsibility — delete the\n *   record after a successful verify returns.\n *\n * @packageDocumentation\n */\n\nexport interface EmailOtpTransportArgs {\n  readonly to: string\n  readonly code: string\n  readonly expiresAt: string\n  readonly issuedAt: string\n}\n\nexport type EmailOtpTransport = (args: EmailOtpTransportArgs) => Promise<void> | void\n\nexport interface IssueOptions {\n  readonly email: string\n  /** Seconds before the challenge expires. Default 300 (5 min). */\n  readonly ttlSeconds?: number\n  /** Code digits. Default 6. */\n  readonly digits?: 6 | 7 | 8\n  /** Maximum failed attempts before the record should be burned. Default 5. */\n  readonly maxAttempts?: number\n  /** Caller delivers the code here. Required. */\n  readonly transport: EmailOtpTransport\n}\n\nexport interface EmailOtpRecord {\n  readonly email: string\n  readonly digest: string        // hex SHA-256(code ⊕ salt)\n  readonly salt: string          // hex\n  readonly issuedAt: string\n  readonly expiresAt: string\n  readonly maxAttempts: number\n  attempts: number\n}\n\nexport interface IssueResult {\n  readonly record: EmailOtpRecord\n}\n\nexport interface VerifyResult {\n  readonly ok: boolean\n  /**\n   * When `ok === false`, `reason` is one of:\n   *  - `'expired'` — the record's `expiresAt` has passed.\n   *  - `'mismatch'` — the digest didn't match.\n   *  - `'locked'` — too many failed attempts; caller should burn.\n   */\n  readonly reason?: 'expired' | 'mismatch' | 'locked'\n  readonly remainingAttempts?: number\n}\n\n/** Issue a new email OTP challenge. Calls the transport in the same tick. */\nexport async function issue(options: IssueOptions): Promise<IssueResult> {\n  const digits = options.digits ?? 6\n  const ttl = options.ttlSeconds ?? 300\n  const maxAttempts = options.maxAttempts ?? 5\n\n  const code = randomNumericCode(digits)\n  const saltBytes = globalThis.crypto.getRandomValues(new Uint8Array(16))\n  const salt = toHex(saltBytes)\n  const digest = await hashCodeWithSalt(code, salt)\n\n  const issuedAt = new Date()\n  const expiresAt = new Date(issuedAt.getTime() + ttl * 1000)\n  const record: EmailOtpRecord = {\n    email: options.email,\n    digest,\n    salt,\n    issuedAt: issuedAt.toISOString(),\n    expiresAt: expiresAt.toISOString(),\n    maxAttempts,\n    attempts: 0,\n  }\n\n  await options.transport({\n    to: options.email,\n    code,\n    issuedAt: record.issuedAt,\n    expiresAt: record.expiresAt,\n  })\n\n  return { record }\n}\n\n/**\n * Verify a user-entered code against a stored record. Increments\n * `attempts` on every call (pass or fail). Caller should delete the\n * record on success or when `remainingAttempts === 0`.\n */\nexport async function verify(input: string, record: EmailOtpRecord): Promise<VerifyResult> {\n  if (record.attempts >= record.maxAttempts) {\n    return { ok: false, reason: 'locked', remainingAttempts: 0 }\n  }\n  record.attempts += 1\n\n  if (new Date(record.expiresAt).getTime() <= Date.now()) {\n    return { ok: false, reason: 'expired', remainingAttempts: record.maxAttempts - record.attempts }\n  }\n\n  const digest = await hashCodeWithSalt(input, record.salt)\n  if (!constantTimeEqual(digest, record.digest)) {\n    return {\n      ok: false,\n      reason: record.attempts >= record.maxAttempts ? 'locked' : 'mismatch',\n      remainingAttempts: record.maxAttempts - record.attempts,\n    }\n  }\n  return { ok: true, remainingAttempts: record.maxAttempts - record.attempts }\n}\n\n// ── internals ─────────────────────────────────────────────────────────\n\nfunction randomNumericCode(digits: number): string {\n  // Rejection sampling to avoid modulo bias.\n  const max = 10 ** digits\n  const bytes = new Uint32Array(1)\n  const threshold = Math.floor(0xffffffff / max) * max\n  while (true) {\n    globalThis.crypto.getRandomValues(bytes)\n    if (bytes[0]! < threshold) {\n      return (bytes[0]! % max).toString().padStart(digits, '0')\n    }\n  }\n}\n\nasync function hashCodeWithSalt(code: string, saltHex: string): Promise<string> {\n  const enc = new TextEncoder()\n  const codeBytes = enc.encode(code)\n  const saltBytes = fromHex(saltHex)\n  const combined = new Uint8Array(codeBytes.length + saltBytes.length)\n  combined.set(codeBytes, 0)\n  combined.set(saltBytes, codeBytes.length)\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', combined as BufferSource)\n  return toHex(new Uint8Array(digest))\n}\n\nfunction constantTimeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false\n  let diff = 0\n  for (let i = 0; i < a.length; i++) {\n    diff |= a.charCodeAt(i) ^ b.charCodeAt(i)\n  }\n  return diff === 0\n}\n\nfunction toHex(bytes: Uint8Array): string {\n  let out = ''\n  for (const b of bytes) out += b.toString(16).padStart(2, '0')\n  return out\n}\n\nfunction fromHex(hex: string): Uint8Array {\n  const out = new Uint8Array(hex.length / 2)\n  for (let i = 0; i < out.length; i++) {\n    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16)\n  }\n  return out\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -1,99 +0,0 @@
-/**
- * **@noy-db/on-email-otp** — email OTP second factor.
- *
- * Issues short-lived numeric codes, delivers via a **caller-supplied
- * transport** (SMTP / SES / Postmark / Resend / Mailgun / a test
- * sink), and verifies them in constant time with a one-use burn
- * guarantee.
- *
- * **Why no bundled SMTP client?** Every consumer already has an email
- * sender in their stack — coupling noy-db to a specific SMTP library
- * would pull in Node-only dependencies and complicate browser /
- * edge-worker usage. The transport abstraction is a single-method
- * interface; write a 5-line adapter for whatever you use today.
- *
- * ## Usage
- *
- * ```ts
- * import { issue, verify } from '@noy-db/on-email-otp'
- *
- * // Challenge issue (server side, post-passphrase)
- * const challenge = await issue({
- *   email: 'alice@example.com',
- *   ttlSeconds: 300,
- *   transport: async ({ to, code, expiresAt }) => {
- *     await smtp.send({ to, subject: 'Your code', text: `${code} — expires at ${expiresAt}` })
- *   },
- * })
- * // Store `challenge.record` somewhere the verifier can retrieve later.
- *
- * // Verify
- * const ok = await verify('123456', challenge.record)
- * ```
- *
- * ## Security model
- *
- * - Codes are 6-digit random numbers (by default) — 10⁶ space is
- *   fine because verification is rate-limited at the caller (by
- *   burning on success + a `maxAttempts` guard stored in the record).
- * - The record carries `sha256(code + salt)` — the plaintext code is
- *   never written to storage. Verification hashes the input with the
- *   stored salt and compares in constant time.
- * - `expiresAt` is enforced on every `verify()` — expired records are
- *   rejected before the hash comparison.
- * - Burn-on-success is the caller's responsibility — delete the
- *   record after a successful verify returns.
- *
- * @packageDocumentation
- */
-interface EmailOtpTransportArgs {
-    readonly to: string;
-    readonly code: string;
-    readonly expiresAt: string;
-    readonly issuedAt: string;
-}
-type EmailOtpTransport = (args: EmailOtpTransportArgs) => Promise<void> | void;
-interface IssueOptions {
-    readonly email: string;
-    /** Seconds before the challenge expires. Default 300 (5 min). */
-    readonly ttlSeconds?: number;
-    /** Code digits. Default 6. */
-    readonly digits?: 6 | 7 | 8;
-    /** Maximum failed attempts before the record should be burned. Default 5. */
-    readonly maxAttempts?: number;
-    /** Caller delivers the code here. Required. */
-    readonly transport: EmailOtpTransport;
-}
-interface EmailOtpRecord {
-    readonly email: string;
-    readonly digest: string;
-    readonly salt: string;
-    readonly issuedAt: string;
-    readonly expiresAt: string;
-    readonly maxAttempts: number;
-    attempts: number;
-}
-interface IssueResult {
-    readonly record: EmailOtpRecord;
-}
-interface VerifyResult {
-    readonly ok: boolean;
-    /**
-     * When `ok === false`, `reason` is one of:
-     *  - `'expired'` — the record's `expiresAt` has passed.
-     *  - `'mismatch'` — the digest didn't match.
-     *  - `'locked'` — too many failed attempts; caller should burn.
-     */
-    readonly reason?: 'expired' | 'mismatch' | 'locked';
-    readonly remainingAttempts?: number;
-}
-/** Issue a new email OTP challenge. Calls the transport in the same tick. */
-declare function issue(options: IssueOptions): Promise<IssueResult>;
-/**
- * Verify a user-entered code against a stored record. Increments
- * `attempts` on every call (pass or fail). Caller should delete the
- * record on success or when `remainingAttempts === 0`.
- */
-declare function verify(input: string, record: EmailOtpRecord): Promise<VerifyResult>;
-
-export { type EmailOtpRecord, type EmailOtpTransport, type EmailOtpTransportArgs, type IssueOptions, type IssueResult, type VerifyResult, issue, verify };