onehitter 2.0.7 → 2.0.9

package/README.md

@@ -28,7 +28,7 @@ It generates an OTP, stores a hashed record, emails it to the user, then validat
   - create(...): persist a hashed OTP document
   - send(to, otp): email the OTP via SES (customizable template)
   - validate / validateStatus(...): consume once and return success or a detailed status
-- Storage adapter: MongoDB (default) or SQLite (experimental). Choose with `DB_DRIVER`.
+- Storage adapter: MongoDB (default) or SQLite (experimental). Choose with `OTP_DB_DRIVER` (`mongodb` or `sqlite`).
 - Expiry: checked at validation time; MongoDB users should also create a TTL index on `createdAt` for cleanup.
 - Rate limiting: bring your own limiter or enable a built-in in-memory limiter via env flags.
 
@@ -102,7 +102,12 @@ if (status === 'ok') {
 
 ## Databases
 - Default: MongoDB. Your app owns the `MongoClient` (construct, connect/close, pass to `create`/`validate`).
-- Optional: SQLite (`DB_DRIVER=sqlite`, optional `SQLITE_PATH`); good for tests/small apps.
+- Optional: SQLite (`OTP_DB_DRIVER=sqlite`, optional `SQLITE_PATH`); good for tests/small apps.
+
+### Database driver env
+- `OTP_DB_DRIVER` (optional): selects the storage driver.
+  - `mongodb` (default): uses the MongoDB adapter and only requires the `mongodb` dependency.
+  - `sqlite`: uses the built-in SQLite adapter and requires the host app to install `sqlite3` (for example, `npm install sqlite3`). When `OTP_DB_DRIVER=mongodb`, `sqlite3` is not required and is not loaded.
 
 Details and tradeoffs: docs/DB.md
 

package/dist/cjs/db/mongodb-functions.js

@@ -15,7 +15,7 @@ const otpCreate = async (client, otp) => {
         throw new Error('otpCreate does not accept an _id; it will be generated by MongoDB');
     }
     const doc = {
-        contact: otp.contact,
+        contactId: (0, shared_1.computeContactId)(otp.contact),
         otpHash: (0, shared_1.computeOtpHash)(otp.contact, otp.otp),
         createdAt: otp.createdAt,
     };
@@ -35,8 +35,9 @@ const otpValidateWithStatus = async (client, otp, now = new Date(), ttlSeconds)
     const database = client.db(process.env.OTP_MONGO_DATABASE);
     const cursor = database.collection(process.env.OTP_MONGO_COLLECTION);
     const otpHash = (0, shared_1.computeOtpHash)(otp.contact, otp.otp);
+    const contactId = (0, shared_1.computeContactId)(otp.contact);
     // Delete matching doc and retrieve the deleted document for inspection
-    const res = await cursor.findOneAndDelete({ contact: otp.contact, otpHash });
+    const res = await cursor.findOneAndDelete({ contactId, otpHash });
     const deleted = res && (res.createdAt ? res : (res.value ?? null));
     if (!deleted)
         return 'not_found';

package/dist/cjs/db/shared.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeOtpHash = exports.SQLITE_PATH = void 0;
+exports.computeContactId = exports.computeOtpHash = exports.SQLITE_PATH = void 0;
 exports.currentDriver = currentDriver;
 function currentDriver() {
     const d = (process.env.OTP_DB_DRIVER);
@@ -26,3 +26,26 @@ const computeOtpHash = (contact, otp, opts) => {
     return crypto.createHash('sha256').update(message, 'utf8').digest('hex');
 };
 exports.computeOtpHash = computeOtpHash;
+/**
+ * Deterministic contact identifier used in storage.
+ *
+ * This function derives a pseudonymous ID from the contact string using the
+ * same peppered HMAC/Hash strategy as `computeOtpHash`, but without the OTP
+ * component. It allows equality comparison (lookups) without storing the
+ * original contact value in the database.
+ */
+const computeContactId = (contact, opts) => {
+    const pepper = process.env.OTP_PEPPER || '';
+    const salt = opts?.salt || '';
+    const allowInsecure = process.env.ONEHITTER_ALLOW_INSECURE_HASH === 'true';
+    if (process.env.NODE_ENV === 'production' && !pepper && !allowInsecure) {
+        throw new Error('Security requirement: OTP_PEPPER must be set in production to HMAC-protect contact identifiers and OTP hashes (override with ONEHITTER_ALLOW_INSECURE_HASH=true for non-prod-like runs)');
+    }
+    const message = salt ? `${contact}|${salt}` : contact;
+    const crypto = require('crypto');
+    if (pepper) {
+        return crypto.createHmac('sha256', pepper).update(message, 'utf8').digest('hex');
+    }
+    return crypto.createHash('sha256').update(message, 'utf8').digest('hex');
+};
+exports.computeContactId = computeContactId;

package/dist/cjs/db/sqlite-functions.js

@@ -4,20 +4,38 @@ exports.otpValidateWithStatus = exports.otpCreate = void 0;
 const shared_1 = require("./shared");
 let sqlite3;
 let db = null;
+// Bundler-safe loader for optional sqlite3 dependency.
+// Using eval('require') prevents bundlers from eagerly resolving the sqlite3
+// module when the SQLite driver is not used (e.g. when OTP_DB_DRIVER=mongodb).
+function loadSqlite3() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        const req = eval('require');
+        return req('sqlite3');
+    }
+    catch (err) {
+        // Provide a clear error when the SQLite driver is selected but sqlite3
+        // is not installed in the host application.
+        const message = err && err.code === 'MODULE_NOT_FOUND'
+            ? 'The sqlite3 package is not installed. Install it with "npm install sqlite3" to use OTP_DB_DRIVER=sqlite.'
+            : `Failed to load sqlite3 driver: ${String(err)}`;
+        throw new Error(message);
+    }
+}
 function getDb() {
     if (db)
         return db;
     // Lazy-load sqlite3 only when the SQLite driver is actually used
-    const s = sqlite3 ?? (sqlite3 = require('sqlite3'));
+    const s = sqlite3 ?? (sqlite3 = loadSqlite3());
     db = new s.Database(shared_1.SQLITE_PATH);
     db.serialize(() => {
         db.run('CREATE TABLE IF NOT EXISTS otp (\n' +
             '  id INTEGER PRIMARY KEY AUTOINCREMENT,\n' +
-            '  contact TEXT NOT NULL,\n' +
+            '  contactId TEXT NOT NULL,\n' +
             '  otpHash TEXT NOT NULL,\n' +
             '  createdAt INTEGER NOT NULL\n' +
             ')');
-        db.run('CREATE INDEX IF NOT EXISTS idx_otp_contact_hash ON otp(contact, otpHash)');
+        db.run('CREATE INDEX IF NOT EXISTS idx_otp_contact_hash ON otp(contactId, otpHash)');
         db.run('CREATE INDEX IF NOT EXISTS idx_otp_createdAt ON otp(createdAt)');
     });
     return db;
@@ -26,8 +44,9 @@ const otpCreate = async (otp) => {
     const database = getDb();
     const createdAt = otp.createdAt ? otp.createdAt.getTime() : Date.now();
     const otpHash = (0, shared_1.computeOtpHash)(otp.contact, otp.otp);
+    const contactId = (0, shared_1.computeContactId)(otp.contact);
     return await new Promise((resolve, reject) => {
-        database.run('INSERT INTO otp (contact, otpHash, createdAt) VALUES (?, ?, ?)', [otp.contact, otpHash, createdAt], function (err) {
+        database.run('INSERT INTO otp (contactId, otpHash, createdAt) VALUES (?, ?, ?)', [contactId, otpHash, createdAt], function (err) {
             if (err)
                 return reject(err);
             // Shape it like a Mongo InsertOneResult enough for callers
@@ -39,10 +58,11 @@ exports.otpCreate = otpCreate;
 const otpValidateWithStatus = async (otp, now = new Date(), ttlSeconds) => {
     const database = getDb();
     const otpHash = (0, shared_1.computeOtpHash)(otp.contact, otp.otp);
+    const contactId = (0, shared_1.computeContactId)(otp.contact);
     return await new Promise((resolve, reject) => {
         // Single-statement atomicity: select the newest id, then conditionally delete it.
         // We avoid explicit BEGIN/COMMIT to prevent nested transaction errors under concurrency.
-        database.get('SELECT id, createdAt FROM otp WHERE contact = ? AND otpHash = ? ORDER BY id DESC LIMIT 1', [otp.contact, otpHash], function (err, row) {
+        database.get('SELECT id, createdAt FROM otp WHERE contactId = ? AND otpHash = ? ORDER BY id DESC LIMIT 1', [contactId, otpHash], function (err, row) {
             if (err)
                 return reject(err);
             if (!row)

package/dist/cjs/sender.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSesV2Transport = createSesV2Transport;
 const nodemailer_1 = __importDefault(require("nodemailer"));
 const config_1 = require("./config");
 /**
@@ -113,20 +114,16 @@ Once used, this one-time password can not be used again. That's why it's called
  * @throws {Error} If the recipient (`to`) or the sender (`from`) address is missing.
  */
 function createSesTransport(region) {
-    // Prefer Nodemailer v7 SESv2 client when available; fall back to legacy SES config
+    // Force SESv2 path only; do not use legacy SES
     try {
         // eslint-disable-next-line @typescript-eslint/no-var-requires
         const sesv2 = require('@aws-sdk/client-sesv2');
         const client = new sesv2.SESv2Client({ region });
-        // Nodemailer v7 expects SESv2 via options.SES with { sesClient, SendEmailCommand }
         const opts = { SES: { sesClient: client, SendEmailCommand: sesv2.SendEmailCommand } };
         return nodemailer_1.default.createTransport(opts);
     }
-    catch {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const aws = require('@aws-sdk/client-ses');
-        const legacy = new aws.SES({ apiVersion: '2010-12-01', region });
-        return nodemailer_1.default.createTransport({ SES: { ses: legacy, aws } });
+    catch (err) {
+        throw new Error('SESv2 client not available. Install @aws-sdk/client-sesv2 to use OneHitter sender, or pass a Nodemailer transporter explicitly.');
     }
 }
 async function send(to, otp, url, expiry, message, opts) {
@@ -147,4 +144,7 @@ async function send(to, otp, url, expiry, message, opts) {
         ...(text ? { text } : {}),
     });
 }
+function createSesV2Transport(region) {
+    return createSesTransport(region);
+}
 exports.default = send;

package/dist/esm/db/mongodb-functions.js

@@ -1,4 +1,4 @@
-import { computeOtpHash } from './shared';
+import { computeOtpHash, computeContactId } from './shared';
 export const otpCreate = async (client, otp) => {
     if (!process.env.OTP_MONGO_DATABASE || !process.env.OTP_MONGO_COLLECTION) {
         throw new Error('Missing OTP_MONGO_DATABASE or OTP_MONGO_COLLECTION');
@@ -12,7 +12,7 @@ export const otpCreate = async (client, otp) => {
         throw new Error('otpCreate does not accept an _id; it will be generated by MongoDB');
     }
     const doc = {
-        contact: otp.contact,
+        contactId: computeContactId(otp.contact),
         otpHash: computeOtpHash(otp.contact, otp.otp),
         createdAt: otp.createdAt,
     };
@@ -31,8 +31,9 @@ export const otpValidateWithStatus = async (client, otp, now = new Date(), ttlSe
     const database = client.db(process.env.OTP_MONGO_DATABASE);
     const cursor = database.collection(process.env.OTP_MONGO_COLLECTION);
     const otpHash = computeOtpHash(otp.contact, otp.otp);
+    const contactId = computeContactId(otp.contact);
     // Delete matching doc and retrieve the deleted document for inspection
-    const res = await cursor.findOneAndDelete({ contact: otp.contact, otpHash });
+    const res = await cursor.findOneAndDelete({ contactId, otpHash });
     const deleted = res && (res.createdAt ? res : (res.value ?? null));
     if (!deleted)
         return 'not_found';

package/dist/esm/db/shared.js

@@ -21,3 +21,25 @@ export const computeOtpHash = (contact, otp, opts) => {
     const crypto = require('crypto');
     return crypto.createHash('sha256').update(message, 'utf8').digest('hex');
 };
+/**
+ * Deterministic contact identifier used in storage.
+ *
+ * This function derives a pseudonymous ID from the contact string using the
+ * same peppered HMAC/Hash strategy as `computeOtpHash`, but without the OTP
+ * component. It allows equality comparison (lookups) without storing the
+ * original contact value in the database.
+ */
+export const computeContactId = (contact, opts) => {
+    const pepper = process.env.OTP_PEPPER || '';
+    const salt = opts?.salt || '';
+    const allowInsecure = process.env.ONEHITTER_ALLOW_INSECURE_HASH === 'true';
+    if (process.env.NODE_ENV === 'production' && !pepper && !allowInsecure) {
+        throw new Error('Security requirement: OTP_PEPPER must be set in production to HMAC-protect contact identifiers and OTP hashes (override with ONEHITTER_ALLOW_INSECURE_HASH=true for non-prod-like runs)');
+    }
+    const message = salt ? `${contact}|${salt}` : contact;
+    const crypto = require('crypto');
+    if (pepper) {
+        return crypto.createHmac('sha256', pepper).update(message, 'utf8').digest('hex');
+    }
+    return crypto.createHash('sha256').update(message, 'utf8').digest('hex');
+};

package/dist/esm/db/sqlite-functions.js

@@ -1,20 +1,38 @@
-import { SQLITE_PATH, computeOtpHash } from './shared';
+import { SQLITE_PATH, computeOtpHash, computeContactId } from './shared';
 let sqlite3;
 let db = null;
+// Bundler-safe loader for optional sqlite3 dependency.
+// Using eval('require') prevents bundlers from eagerly resolving the sqlite3
+// module when the SQLite driver is not used (e.g. when OTP_DB_DRIVER=mongodb).
+function loadSqlite3() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        const req = eval('require');
+        return req('sqlite3');
+    }
+    catch (err) {
+        // Provide a clear error when the SQLite driver is selected but sqlite3
+        // is not installed in the host application.
+        const message = err && err.code === 'MODULE_NOT_FOUND'
+            ? 'The sqlite3 package is not installed. Install it with "npm install sqlite3" to use OTP_DB_DRIVER=sqlite.'
+            : `Failed to load sqlite3 driver: ${String(err)}`;
+        throw new Error(message);
+    }
+}
 function getDb() {
     if (db)
         return db;
     // Lazy-load sqlite3 only when the SQLite driver is actually used
-    const s = sqlite3 ?? (sqlite3 = require('sqlite3'));
+    const s = sqlite3 ?? (sqlite3 = loadSqlite3());
     db = new s.Database(SQLITE_PATH);
     db.serialize(() => {
         db.run('CREATE TABLE IF NOT EXISTS otp (\n' +
             '  id INTEGER PRIMARY KEY AUTOINCREMENT,\n' +
-            '  contact TEXT NOT NULL,\n' +
+            '  contactId TEXT NOT NULL,\n' +
             '  otpHash TEXT NOT NULL,\n' +
             '  createdAt INTEGER NOT NULL\n' +
             ')');
-        db.run('CREATE INDEX IF NOT EXISTS idx_otp_contact_hash ON otp(contact, otpHash)');
+        db.run('CREATE INDEX IF NOT EXISTS idx_otp_contact_hash ON otp(contactId, otpHash)');
         db.run('CREATE INDEX IF NOT EXISTS idx_otp_createdAt ON otp(createdAt)');
     });
     return db;
@@ -23,8 +41,9 @@ export const otpCreate = async (otp) => {
     const database = getDb();
     const createdAt = otp.createdAt ? otp.createdAt.getTime() : Date.now();
     const otpHash = computeOtpHash(otp.contact, otp.otp);
+    const contactId = computeContactId(otp.contact);
     return await new Promise((resolve, reject) => {
-        database.run('INSERT INTO otp (contact, otpHash, createdAt) VALUES (?, ?, ?)', [otp.contact, otpHash, createdAt], function (err) {
+        database.run('INSERT INTO otp (contactId, otpHash, createdAt) VALUES (?, ?, ?)', [contactId, otpHash, createdAt], function (err) {
             if (err)
                 return reject(err);
             // Shape it like a Mongo InsertOneResult enough for callers
@@ -35,10 +54,11 @@ export const otpCreate = async (otp) => {
 export const otpValidateWithStatus = async (otp, now = new Date(), ttlSeconds) => {
     const database = getDb();
     const otpHash = computeOtpHash(otp.contact, otp.otp);
+    const contactId = computeContactId(otp.contact);
     return await new Promise((resolve, reject) => {
         // Single-statement atomicity: select the newest id, then conditionally delete it.
         // We avoid explicit BEGIN/COMMIT to prevent nested transaction errors under concurrency.
-        database.get('SELECT id, createdAt FROM otp WHERE contact = ? AND otpHash = ? ORDER BY id DESC LIMIT 1', [otp.contact, otpHash], function (err, row) {
+        database.get('SELECT id, createdAt FROM otp WHERE contactId = ? AND otpHash = ? ORDER BY id DESC LIMIT 1', [contactId, otpHash], function (err, row) {
             if (err)
                 return reject(err);
             if (!row)

package/dist/esm/sender.js

@@ -108,20 +108,16 @@ Once used, this one-time password can not be used again. That's why it's called
  * @throws {Error} If the recipient (`to`) or the sender (`from`) address is missing.
  */
 function createSesTransport(region) {
-    // Prefer Nodemailer v7 SESv2 client when available; fall back to legacy SES config
+    // Force SESv2 path only; do not use legacy SES
     try {
         // eslint-disable-next-line @typescript-eslint/no-var-requires
         const sesv2 = require('@aws-sdk/client-sesv2');
         const client = new sesv2.SESv2Client({ region });
-        // Nodemailer v7 expects SESv2 via options.SES with { sesClient, SendEmailCommand }
         const opts = { SES: { sesClient: client, SendEmailCommand: sesv2.SendEmailCommand } };
         return nodemailer.createTransport(opts);
     }
-    catch {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const aws = require('@aws-sdk/client-ses');
-        const legacy = new aws.SES({ apiVersion: '2010-12-01', region });
-        return nodemailer.createTransport({ SES: { ses: legacy, aws } });
+    catch (err) {
+        throw new Error('SESv2 client not available. Install @aws-sdk/client-sesv2 to use OneHitter sender, or pass a Nodemailer transporter explicitly.');
     }
 }
 async function send(to, otp, url, expiry, message, opts) {
@@ -142,4 +138,7 @@ async function send(to, otp, url, expiry, message, opts) {
         ...(text ? { text } : {}),
     });
 }
+export function createSesV2Transport(region) {
+    return createSesTransport(region);
+}
 export default send;

package/dist/types/db/mongodb-functions.d.ts

@@ -1,7 +1,7 @@
 import type { MongoClient, InsertOneResult, ObjectId } from 'mongodb';
 import { type ValidateStatus, type OtpDoc } from './shared';
 interface StoredOtpDoc {
-    contact: string;
+    contactId: string;
     otpHash: string;
     createdAt: Date;
     _id?: ObjectId;

package/dist/types/db/shared.d.ts

@@ -21,3 +21,14 @@ export interface DbAdapter {
 export declare const computeOtpHash: (contact: string, otp: string, opts?: {
     salt?: string;
 }) => string;
+/**
+ * Deterministic contact identifier used in storage.
+ *
+ * This function derives a pseudonymous ID from the contact string using the
+ * same peppered HMAC/Hash strategy as `computeOtpHash`, but without the OTP
+ * component. It allows equality comparison (lookups) without storing the
+ * original contact value in the database.
+ */
+export declare const computeContactId: (contact: string, opts?: {
+    salt?: string;
+}) => string;

package/dist/types/sender.d.ts

@@ -24,4 +24,5 @@ export interface MessageConfig {
     template?: MessageTemplate;
 }
 declare function send(to: string, otp: string, url: string, expiry?: number | string, message?: MessageConfig | MessageTemplate, opts?: SendOptions): Promise<void>;
+export declare function createSesV2Transport(region: string): nodemailer.Transporter;
 export default send;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onehitter",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "One-time password user validation package.",
   "main": "dist/cjs/onehitter.js",
   "module": "dist/esm/onehitter.js",