@noy-db/on-email-otp 0.1.0-pre.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+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,33 @@
+# @noy-db/on-email-otp
+
+[![npm](https://img.shields.io/npm/v/%40noy-db/on-email-otp.svg)](https://www.npmjs.com/package/@noy-db/on-email-otp)
+
+> Email OTP second factor for noy-db
+
+Part of [**`@noy-db/hub`**](https://www.npmjs.com/package/@noy-db/hub) — the zero-knowledge, offline-first, encrypted document store.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/on-email-otp
+```
+
+## What it is
+
+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.
+
+## Status
+
+**Pre-release** (`0.1.0-pre.1`). API may change before `1.0`.
+
+## Documentation
+
+See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
+
+- 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)
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/index.cjs

@@ -0,0 +1,118 @@
+"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

@@ -0,0 +1 @@
+{"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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiGA,eAAsB,MAAM,SAA6C;AACvE,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,MAAM,QAAQ,cAAc;AAClC,QAAM,cAAc,QAAQ,eAAe;AAE3C,QAAM,OAAO,kBAAkB,MAAM;AACrC,QAAM,YAAY,WAAW,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;AACtE,QAAM,OAAO,MAAM,SAAS;AAC5B,QAAM,SAAS,MAAM,iBAAiB,MAAM,IAAI;AAEhD,QAAM,WAAW,oBAAI,KAAK;AAC1B,QAAM,YAAY,IAAI,KAAK,SAAS,QAAQ,IAAI,MAAM,GAAI;AAC1D,QAAM,SAAyB;AAAA,IAC7B,OAAO,QAAQ;AAAA,IACf;AAAA,IACA;AAAA,IACA,UAAU,SAAS,YAAY;AAAA,IAC/B,WAAW,UAAU,YAAY;AAAA,IACjC;AAAA,IACA,UAAU;AAAA,EACZ;AAEA,QAAM,QAAQ,UAAU;AAAA,IACtB,IAAI,QAAQ;AAAA,IACZ;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,WAAW,OAAO;AAAA,EACpB,CAAC;AAED,SAAO,EAAE,OAAO;AAClB;AAOA,eAAsB,OAAO,OAAe,QAA+C;AACzF,MAAI,OAAO,YAAY,OAAO,aAAa;AACzC,WAAO,EAAE,IAAI,OAAO,QAAQ,UAAU,mBAAmB,EAAE;AAAA,EAC7D;AACA,SAAO,YAAY;AAEnB,MAAI,IAAI,KAAK,OAAO,SAAS,EAAE,QAAQ,KAAK,KAAK,IAAI,GAAG;AACtD,WAAO,EAAE,IAAI,OAAO,QAAQ,WAAW,mBAAmB,OAAO,cAAc,OAAO,SAAS;AAAA,EACjG;AAEA,QAAM,SAAS,MAAM,iBAAiB,OAAO,OAAO,IAAI;AACxD,MAAI,CAAC,kBAAkB,QAAQ,OAAO,MAAM,GAAG;AAC7C,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,QAAQ,OAAO,YAAY,OAAO,cAAc,WAAW;AAAA,MAC3D,mBAAmB,OAAO,cAAc,OAAO;AAAA,IACjD;AAAA,EACF;AACA,SAAO,EAAE,IAAI,MAAM,mBAAmB,OAAO,cAAc,OAAO,SAAS;AAC7E;AAIA,SAAS,kBAAkB,QAAwB;AAEjD,QAAM,MAAM,MAAM;AAClB,QAAM,QAAQ,IAAI,YAAY,CAAC;AAC/B,QAAM,YAAY,KAAK,MAAM,aAAa,GAAG,IAAI;AACjD,SAAO,MAAM;AACX,eAAW,OAAO,gBAAgB,KAAK;AACvC,QAAI,MAAM,CAAC,IAAK,WAAW;AACzB,cAAQ,MAAM,CAAC,IAAK,KAAK,SAAS,EAAE,SAAS,QAAQ,GAAG;AAAA,IAC1D;AAAA,EACF;AACF;AAEA,eAAe,iBAAiB,MAAc,SAAkC;AAC9E,QAAM,MAAM,IAAI,YAAY;AAC5B,QAAM,YAAY,IAAI,OAAO,IAAI;AACjC,QAAM,YAAY,QAAQ,OAAO;AACjC,QAAM,WAAW,IAAI,WAAW,UAAU,SAAS,UAAU,MAAM;AACnE,WAAS,IAAI,WAAW,CAAC;AACzB,WAAS,IAAI,WAAW,UAAU,MAAM;AACxC,QAAM,SAAS,MAAM,WAAW,OAAO,OAAO,OAAO,WAAW,QAAwB;AACxF,SAAO,MAAM,IAAI,WAAW,MAAM,CAAC;AACrC;AAEA,SAAS,kBAAkB,GAAW,GAAoB;AACxD,MAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,MAAI,OAAO;AACX,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,YAAQ,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC;AAAA,EAC1C;AACA,SAAO,SAAS;AAClB;AAEA,SAAS,MAAM,OAA2B;AACxC,MAAI,MAAM;AACV,aAAW,KAAK,MAAO,QAAO,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;AAC5D,SAAO;AACT;AAEA,SAAS,QAAQ,KAAyB;AACxC,QAAM,MAAM,IAAI,WAAW,IAAI,SAAS,CAAC;AACzC,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,QAAI,CAAC,IAAI,OAAO,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE;AAAA,EAC1D;AACA,SAAO;AACT;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,99 @@
+/**
+ * **@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 };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * **@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 };

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/index.ts
+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;
+}
+export {
+  issue,
+  verify
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"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/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@noy-db/on-email-otp",
+  "version": "0.1.0-pre.3",
+  "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>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/on-email-otp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/on-email-otp"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "keywords": [
+    "noy-db",
+    "on-email-otp",
+    "email",
+    "otp",
+    "2fa",
+    "mfa"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}