onehitter 2.0.10 → 2.0.12

package/README.md

@@ -43,9 +43,9 @@ npm run build
 
 2) Configure minimal env
 ```env
-MONGO_CONNECTION=mongodb+srv://...
-MONGO_DATABASE=myapp
-MONGO_COLLECTION=otps
+OTP_MONGO_CONNECTION=mongodb+srv://...
+OTP_MONGO_DATABASE=myapp
+OTP_MONGO_COLLECTION=otps
 
 OTP_MESSAGE_FROM=noreply@example.com
 OTP_MESSAGE_SUBJECT=Your verification code
@@ -61,7 +61,7 @@ OTP_DIGITS=true
 const { MongoClient, ServerApiVersion } = require('mongodb')
 const OneHitter = require('onehitter').default
 
-const client = new MongoClient(process.env.MONGO_CONNECTION, {
+const client = new MongoClient(process.env.OTP_MONGO_CONNECTION, {
   serverApi: { version: ServerApiVersion.v1, strict: true, deprecationErrors: true },
 })
 await client.connect()
@@ -79,7 +79,7 @@ await client.close()
 - For detailed validation outcomes (expired/not_found/blocked), use `validateStatus()` (see examples/validate-status.md).
 
 ## API at a glance
-- `make(): string` — generate an OTP according to env flags (`OTP_LENGTH`, `OTP_*`)
+- `make(): string` — generate an OTP according to env flags (`OTP_LENGTH`, `OTP_*`); values greater than 64 are capped at 64 characters
 - `create(client, { contact, otp, createdAt }): Promise<InsertOneResult>` — MongoDB
 - `create({ contact, otp, createdAt }): Promise<InsertOneResult>` — SQLite (no client)
 - `send(to, otp): Promise<void>` — emails via SES; template customizable

package/dist/cjs/auth-otp-service.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtpAuthService = void 0;
+const events_1 = require("events");
+const onehitter_1 = __importDefault(require("./onehitter"));
+/**
+ * The core OTP service. Extends EventEmitter to provide fan-out capabilities
+ * via the 'auth:success' and 'auth:failure' events.
+ *
+ * This class delegates OTP validation to the OneHitter service. On successful
+ * validation it emits a typed AUTH_SUCCESS event, and on failure it emits a
+ * typed AUTH_FAILURE event, allowing multiple listeners (logging, sessions,
+ * metrics, etc.) to react without coupling them to the underlying
+ * authentication logic.
+ */
+class OtpAuthService extends events_1.EventEmitter {
+    constructor(deps) {
+        super();
+        this.oneHitter = deps?.oneHitter ?? new onehitter_1.default();
+        this.buildPayload =
+            deps?.buildPayload ??
+                ((userId, extra) => ({
+                    userId,
+                    authTime: new Date(),
+                    ...(extra ?? {}),
+                }));
+        this.buildFailurePayload =
+            deps?.buildFailurePayload ??
+                ((userId, reason, extra) => ({
+                    userId,
+                    authTime: new Date(),
+                    reason,
+                    ...(extra ?? {}),
+                }));
+    }
+    /**
+     * Authenticates the user and broadcasts the 'auth:success' event upon success.
+     *
+     * This method calls into the OneHitter `validate` API, using the provided
+     * `userId` as the OTP contact identifier (for example, an email address or
+     * phone number). If validation succeeds, a typed payload is emitted via the
+     * AUTH_SUCCESS event.
+     *
+     * @param otp The one-time password provided by the user.
+     * @param userId The logical user identifier (often the same as the OTP
+     *               contact, such as an email address).
+     * @param extra Optional bag of extra fields to attach to the emitted payload.
+     * @returns A promise resolving to true if authentication succeeded, false otherwise.
+     */
+    async authenticateUser(otp, userId, extra) {
+        // In a real application you would remove or route this through a logger.
+        // It is left here as an example of contextual logging around auth attempts.
+        // eslint-disable-next-line no-console
+        console.log(`Attempting authentication for user: ${userId}`);
+        // Delegate to OneHitter for secure OTP validation with status information.
+        // We assume that `userId` maps to the OTP contact identifier (e.g., email
+        // or phone). If your application treats these differently, you can inject a
+        // customized OneHitter instance or wrap this method accordingly.
+        const status = await this.oneHitter.validateStatus({ contact: userId, otp });
+        if (status === 'ok') {
+            // 1. Prepare the payload (base + optional extras) for success
+            const payload = this.buildPayload(userId, extra);
+            // 2. Broadcast the success event (Fan-Out)
+            this.emit(OtpAuthService.AUTH_SUCCESS, payload);
+            return true;
+        }
+        // Map underlying status to a stable, public failure reason
+        const reason = status === 'expired' || status === 'not_found' || status === 'blocked'
+            ? status
+            : 'unknown';
+        const failurePayload = this.buildFailurePayload(userId, reason, extra);
+        // Broadcast the failure event (Fan-Out)
+        this.emit(OtpAuthService.AUTH_FAILURE, failurePayload);
+        return false;
+    }
+}
+exports.OtpAuthService = OtpAuthService;
+// Use static readonly property for event names to prevent typos
+OtpAuthService.AUTH_SUCCESS = 'auth:success';
+OtpAuthService.AUTH_FAILURE = 'auth:failure';

package/dist/cjs/onehitter.js

@@ -107,7 +107,8 @@ class OneHitter {
      *
      * This method ensures safe generation by applying the following configuration rules:
      * 1. **Length Check:** If the global `OTP_LENGTH` is not a positive finite number,
-     * it defaults the OTP length to 6.
+     * it defaults the OTP length to 6. Extremely large values are capped at 64 to
+     * avoid excessive memory usage.
      * 2. **Character Set Guardrail:** It checks which character sets (digits, upper/lower
      * alphabets, special characters) are enabled via global constants. If *no* set
      * is enabled, it defaults to including **only digits** to prevent generating
@@ -118,7 +119,8 @@ class OneHitter {
      * @returns {string} The newly generated OTP string.
      */
     make() {
-        const length = Number.isFinite(config_1.OTP_LENGTH) && config_1.OTP_LENGTH > 0 ? config_1.OTP_LENGTH : 6;
+        const rawLength = Number.isFinite(config_1.OTP_LENGTH) && config_1.OTP_LENGTH > 0 ? config_1.OTP_LENGTH : 6;
+        const length = Math.min(rawLength, 64);
         const base = {
             upperCaseAlphabets: config_1.OTP_LETTERS_UPPER,
             lowerCaseAlphabets: config_1.OTP_LETTERS_LOWER,

package/dist/cjs/sender.js

@@ -87,7 +87,10 @@ ${otp}
 
 Once used, this one-time password can not be used again. That's why it's called one-time password. This password also expires in ${minutesText}.`;
     const html = override.html;
-    const from = override.from ?? config_1.OTP_MESSAGE_FROM;
+    // Prefer explicitly configured from, then library-level config default, and
+    // finally fall back to the live environment variable. This makes tests and
+    // applications resilient when env is loaded after the module is imported.
+    const from = override.from ?? config_1.OTP_MESSAGE_FROM ?? process.env.OTP_MESSAGE_FROM;
     return { subject, text, html, from };
 }
 /**

package/dist/esm/auth-otp-service.js

@@ -0,0 +1,76 @@
+import { EventEmitter } from 'events';
+import OneHitter from './onehitter';
+/**
+ * The core OTP service. Extends EventEmitter to provide fan-out capabilities
+ * via the 'auth:success' and 'auth:failure' events.
+ *
+ * This class delegates OTP validation to the OneHitter service. On successful
+ * validation it emits a typed AUTH_SUCCESS event, and on failure it emits a
+ * typed AUTH_FAILURE event, allowing multiple listeners (logging, sessions,
+ * metrics, etc.) to react without coupling them to the underlying
+ * authentication logic.
+ */
+export class OtpAuthService extends EventEmitter {
+    constructor(deps) {
+        super();
+        this.oneHitter = deps?.oneHitter ?? new OneHitter();
+        this.buildPayload =
+            deps?.buildPayload ??
+                ((userId, extra) => ({
+                    userId,
+                    authTime: new Date(),
+                    ...(extra ?? {}),
+                }));
+        this.buildFailurePayload =
+            deps?.buildFailurePayload ??
+                ((userId, reason, extra) => ({
+                    userId,
+                    authTime: new Date(),
+                    reason,
+                    ...(extra ?? {}),
+                }));
+    }
+    /**
+     * Authenticates the user and broadcasts the 'auth:success' event upon success.
+     *
+     * This method calls into the OneHitter `validate` API, using the provided
+     * `userId` as the OTP contact identifier (for example, an email address or
+     * phone number). If validation succeeds, a typed payload is emitted via the
+     * AUTH_SUCCESS event.
+     *
+     * @param otp The one-time password provided by the user.
+     * @param userId The logical user identifier (often the same as the OTP
+     *               contact, such as an email address).
+     * @param extra Optional bag of extra fields to attach to the emitted payload.
+     * @returns A promise resolving to true if authentication succeeded, false otherwise.
+     */
+    async authenticateUser(otp, userId, extra) {
+        // In a real application you would remove or route this through a logger.
+        // It is left here as an example of contextual logging around auth attempts.
+        // eslint-disable-next-line no-console
+        console.log(`Attempting authentication for user: ${userId}`);
+        // Delegate to OneHitter for secure OTP validation with status information.
+        // We assume that `userId` maps to the OTP contact identifier (e.g., email
+        // or phone). If your application treats these differently, you can inject a
+        // customized OneHitter instance or wrap this method accordingly.
+        const status = await this.oneHitter.validateStatus({ contact: userId, otp });
+        if (status === 'ok') {
+            // 1. Prepare the payload (base + optional extras) for success
+            const payload = this.buildPayload(userId, extra);
+            // 2. Broadcast the success event (Fan-Out)
+            this.emit(OtpAuthService.AUTH_SUCCESS, payload);
+            return true;
+        }
+        // Map underlying status to a stable, public failure reason
+        const reason = status === 'expired' || status === 'not_found' || status === 'blocked'
+            ? status
+            : 'unknown';
+        const failurePayload = this.buildFailurePayload(userId, reason, extra);
+        // Broadcast the failure event (Fan-Out)
+        this.emit(OtpAuthService.AUTH_FAILURE, failurePayload);
+        return false;
+    }
+}
+// Use static readonly property for event names to prevent typos
+OtpAuthService.AUTH_SUCCESS = 'auth:success';
+OtpAuthService.AUTH_FAILURE = 'auth:failure';

package/dist/esm/onehitter.js

@@ -102,7 +102,8 @@ class OneHitter {
      *
      * This method ensures safe generation by applying the following configuration rules:
      * 1. **Length Check:** If the global `OTP_LENGTH` is not a positive finite number,
-     * it defaults the OTP length to 6.
+     * it defaults the OTP length to 6. Extremely large values are capped at 64 to
+     * avoid excessive memory usage.
      * 2. **Character Set Guardrail:** It checks which character sets (digits, upper/lower
      * alphabets, special characters) are enabled via global constants. If *no* set
      * is enabled, it defaults to including **only digits** to prevent generating
@@ -113,7 +114,8 @@ class OneHitter {
      * @returns {string} The newly generated OTP string.
      */
     make() {
-        const length = Number.isFinite(OTP_LENGTH) && OTP_LENGTH > 0 ? OTP_LENGTH : 6;
+        const rawLength = Number.isFinite(OTP_LENGTH) && OTP_LENGTH > 0 ? OTP_LENGTH : 6;
+        const length = Math.min(rawLength, 64);
         const base = {
             upperCaseAlphabets: OTP_LETTERS_UPPER,
             lowerCaseAlphabets: OTP_LETTERS_LOWER,

package/dist/esm/sender.js

@@ -81,7 +81,10 @@ ${otp}
 
 Once used, this one-time password can not be used again. That's why it's called one-time password. This password also expires in ${minutesText}.`;
     const html = override.html;
-    const from = override.from ?? OTP_MESSAGE_FROM;
+    // Prefer explicitly configured from, then library-level config default, and
+    // finally fall back to the live environment variable. This makes tests and
+    // applications resilient when env is loaded after the module is imported.
+    const from = override.from ?? OTP_MESSAGE_FROM ?? process.env.OTP_MESSAGE_FROM;
     return { subject, text, html, from };
 }
 /**

package/dist/types/auth-otp-service.d.ts

@@ -0,0 +1,66 @@
+import { EventEmitter } from 'events';
+import OneHitter from './onehitter';
+export interface AuthSuccessPayload {
+    userId: string;
+    authTime: Date;
+}
+export type AuthExtra = Record<string, unknown>;
+export type AuthSuccessExtra = AuthExtra;
+export type AuthFailureExtra = AuthExtra;
+export type AuthSuccessEventPayload = AuthSuccessPayload & AuthSuccessExtra;
+export type AuthFailureReason = 'not_found' | 'expired' | 'blocked' | 'unknown';
+export interface AuthFailurePayload {
+    userId: string;
+    authTime: Date;
+    reason: AuthFailureReason;
+}
+export type AuthFailureEventPayload = AuthFailurePayload & AuthFailureExtra;
+/**
+ * Optional dependencies for OtpAuthService.
+ *
+ * You can inject an existing OneHitter instance (for example, one that is
+ * already configured with a custom rate limiter or database driver). If not
+ * provided, a default OneHitter instance is created internally.
+ *
+ * You can also override the `buildPayload` function to control the exact
+ * structure of the emitted success event payload (including additional fields),
+ * and `buildFailurePayload` to control the structure of failure payloads.
+ */
+export interface OtpAuthServiceDeps {
+    oneHitter?: OneHitter;
+    buildPayload?: (userId: string, extra?: AuthSuccessExtra) => AuthSuccessEventPayload;
+    buildFailurePayload?: (userId: string, reason: AuthFailureReason, extra?: AuthFailureExtra) => AuthFailureEventPayload;
+}
+/**
+ * The core OTP service. Extends EventEmitter to provide fan-out capabilities
+ * via the 'auth:success' and 'auth:failure' events.
+ *
+ * This class delegates OTP validation to the OneHitter service. On successful
+ * validation it emits a typed AUTH_SUCCESS event, and on failure it emits a
+ * typed AUTH_FAILURE event, allowing multiple listeners (logging, sessions,
+ * metrics, etc.) to react without coupling them to the underlying
+ * authentication logic.
+ */
+export declare class OtpAuthService extends EventEmitter {
+    static readonly AUTH_SUCCESS = "auth:success";
+    static readonly AUTH_FAILURE = "auth:failure";
+    private readonly oneHitter;
+    private readonly buildPayload;
+    private readonly buildFailurePayload;
+    constructor(deps?: OtpAuthServiceDeps);
+    /**
+     * Authenticates the user and broadcasts the 'auth:success' event upon success.
+     *
+     * This method calls into the OneHitter `validate` API, using the provided
+     * `userId` as the OTP contact identifier (for example, an email address or
+     * phone number). If validation succeeds, a typed payload is emitted via the
+     * AUTH_SUCCESS event.
+     *
+     * @param otp The one-time password provided by the user.
+     * @param userId The logical user identifier (often the same as the OTP
+     *               contact, such as an email address).
+     * @param extra Optional bag of extra fields to attach to the emitted payload.
+     * @returns A promise resolving to true if authentication succeeded, false otherwise.
+     */
+    authenticateUser(otp: string, userId: string, extra?: AuthSuccessExtra): Promise<boolean>;
+}

package/dist/types/onehitter.d.ts

@@ -148,7 +148,8 @@ declare class OneHitter {
      *
      * This method ensures safe generation by applying the following configuration rules:
      * 1. **Length Check:** If the global `OTP_LENGTH` is not a positive finite number,
-     * it defaults the OTP length to 6.
+     * it defaults the OTP length to 6. Extremely large values are capped at 64 to
+     * avoid excessive memory usage.
      * 2. **Character Set Guardrail:** It checks which character sets (digits, upper/lower
      * alphabets, special characters) are enabled via global constants. If *no* set
      * is enabled, it defaults to including **only digits** to prevent generating

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onehitter",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "description": "One-time password user validation package.",
   "main": "dist/cjs/onehitter.js",
   "module": "dist/esm/onehitter.js",
@@ -78,7 +78,7 @@
   "author": "Keith Vance <discgolfer@uniflydiscs.com>",
   "license": "MIT",
   "engines": {
-    "node": "^18 || ^20"
+    "node": "^18 || ^20 || ^22"
   },
   "files": [
     "dist/esm",
@@ -92,7 +92,7 @@
     "@aws-sdk/client-sesv2": "^3.716.0",
     "dotenv-safe": "^9.1.0",
     "mongodb": "^7.0.0",
-    "nodemailer": "^7.0.10",
+    "nodemailer": "^7.0.11",
     "otp-generator": "^4.0.1"
   },
   "devDependencies": {