redis-otp-manager 0.2.1 → 0.2.2

package/README.md

@@ -11,7 +11,9 @@ This package currently includes:
 - Redis-compatible storage adapter
 - In-memory adapter for tests
 - Intent-aware key strategy
+- Conservative identifier normalization
 - Rate limiting
+- Optional resend cooldown
 - Max-attempt protection
 - NestJS module integration via `redis-otp-manager/nest`
 
@@ -44,11 +46,12 @@ const otp = new OTPManager({
   store: new RedisAdapter(redisClient),
   ttl: 300,
   maxAttempts: 5,
+  resendCooldown: 45,
   rateLimit: {
     window: 60,
     max: 3,
   },
-  devMode: process.env.NODE_ENV !== "production",
+  devMode: false,
 });
 
 const generated = await otp.generate({
@@ -83,6 +86,7 @@ const redisClient = createClient({ url: process.env.REDIS_URL });
       store: new RedisAdapter(redisClient),
       ttl: 300,
       maxAttempts: 5,
+      resendCooldown: 45,
       rateLimit: {
         window: 60,
         max: 3,
@@ -104,6 +108,7 @@ OTPModule.forRootAsync({
     store: new RedisAdapter(createClient({ url: config.getOrThrow("REDIS_URL") })),
     ttl: 300,
     maxAttempts: 5,
+    resendCooldown: 45,
   }),
 });
 ```
@@ -130,15 +135,26 @@ type OTPManagerOptions = {
   store: StoreAdapter;
   ttl: number;
   maxAttempts: number;
+  resendCooldown?: number;
   rateLimit?: {
     window: number;
     max: number;
   };
   devMode?: boolean;
   otpLength?: number;
+  identifierNormalization?: {
+    trim?: boolean;
+    lowercase?: boolean;
+    preserveCaseFor?: string[];
+  };
 };
 ```
 
+Normalization is backward-compatible and conservative by default:
+- identifiers are trimmed
+- identifiers are lowercased for most channels
+- `sms` and `token` preserve case by default
+
 ### `generate(input)`
 
 ```ts
@@ -177,6 +193,15 @@ Returns `true` or throws a typed error.
 - `OTPExpiredError`
 - `OTPInvalidError`
 - `OTPMaxAttemptsExceededError`
+- `OTPResendCooldownError`
+
+## Safer Production Defaults
+
+- `devMode: false`
+- `otpLength: 8` for higher-risk flows
+- `maxAttempts: 3`
+- `resendCooldown: 30` or higher to reduce abuse
+- keep Redis private and behind authenticated network access
 
 ## Key Design
 
@@ -184,6 +209,7 @@ Returns `true` or throws a typed error.
 otp:{intent}:{type}:{identifier}
 attempts:{intent}:{type}:{identifier}
 rate:{type}:{identifier}
+cooldown:{intent}:{type}:{identifier}
 ```
 
 ## Release Automation
@@ -204,6 +230,6 @@ git push origin v0.2.0
 
 ## Next Roadmap
 
-- token/email helpers
+- atomic Redis verification
 - hooks/events
 - analytics and observability

package/dist/core/otp.service.js

@@ -1,7 +1,8 @@
 import { generateNumericOtp } from "./otp.generator.js";
 import { hashOtp, verifyOtpHash } from "./otp.hash.js";
-import { OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, } from "../errors/otp.errors.js";
-import { buildAttemptsKey, buildOtpKey, buildRateLimitKey, } from "../utils/key-builder.js";
+import { OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPResendCooldownError, } from "../errors/otp.errors.js";
+import { buildAttemptsKey, buildCooldownKey, buildOtpKey, buildRateLimitKey, } from "../utils/key-builder.js";
+import { normalizePayloadIdentifier } from "../utils/identifier-normalizer.js";
 import { assertWithinRateLimit } from "../utils/rate-limiter.js";
 export class OTPManager {
     options;
@@ -15,14 +16,25 @@ export class OTPManager {
     }
     async generate(input) {
         validatePayload(input);
-        const otpKey = buildOtpKey(input);
-        const attemptsKey = buildAttemptsKey(input);
-        const rateLimitKey = buildRateLimitKey(input);
+        const normalizedInput = normalizePayloadIdentifier(input, this.options.identifierNormalization);
+        const otpKey = buildOtpKey(normalizedInput);
+        const attemptsKey = buildAttemptsKey(normalizedInput);
+        const rateLimitKey = buildRateLimitKey(normalizedInput);
+        const cooldownKey = buildCooldownKey(normalizedInput);
+        if (this.options.resendCooldown) {
+            const cooldownActive = await this.options.store.get(cooldownKey);
+            if (cooldownActive) {
+                throw new OTPResendCooldownError();
+            }
+        }
         await assertWithinRateLimit(this.options.store, rateLimitKey, this.options.rateLimit);
         const otp = generateNumericOtp(this.options.otpLength);
         const hashedOtp = hashOtp(otp);
         await this.options.store.set(otpKey, hashedOtp, this.options.ttl);
         await this.options.store.del(attemptsKey);
+        if (this.options.resendCooldown) {
+            await this.options.store.set(cooldownKey, "1", this.options.resendCooldown);
+        }
         return {
             expiresIn: this.options.ttl,
             otp: this.options.devMode ? otp : undefined,
@@ -30,11 +42,12 @@ export class OTPManager {
     }
     async verify(input) {
         validatePayload(input);
+        const normalizedInput = normalizePayloadIdentifier(input, this.options.identifierNormalization);
         if (!input.otp || !input.otp.trim()) {
             throw new TypeError("OTP must be a non-empty string.");
         }
-        const otpKey = buildOtpKey(input);
-        const attemptsKey = buildAttemptsKey(input);
+        const otpKey = buildOtpKey(normalizedInput);
+        const attemptsKey = buildAttemptsKey(normalizedInput);
         const storedHash = await this.options.store.get(otpKey);
         if (!storedHash) {
             throw new OTPExpiredError();
@@ -65,6 +78,10 @@ function validateManagerOptions(options) {
         (!Number.isInteger(options.otpLength) || options.otpLength <= 0)) {
         throw new TypeError("otpLength must be a positive integer when provided.");
     }
+    if (options.resendCooldown !== undefined &&
+        (!Number.isInteger(options.resendCooldown) || options.resendCooldown <= 0)) {
+        throw new TypeError("resendCooldown must be a positive integer when provided.");
+    }
     if (options.rateLimit) {
         if (!Number.isInteger(options.rateLimit.window) || options.rateLimit.window <= 0) {
             throw new TypeError("rateLimit.window must be a positive integer.");
@@ -73,6 +90,20 @@ function validateManagerOptions(options) {
             throw new TypeError("rateLimit.max must be a positive integer.");
         }
     }
+    if (options.identifierNormalization) {
+        const { trim, lowercase, preserveCaseFor } = options.identifierNormalization;
+        if (trim !== undefined && typeof trim !== "boolean") {
+            throw new TypeError("identifierNormalization.trim must be a boolean.");
+        }
+        if (lowercase !== undefined && typeof lowercase !== "boolean") {
+            throw new TypeError("identifierNormalization.lowercase must be a boolean.");
+        }
+        if (preserveCaseFor !== undefined &&
+            (!Array.isArray(preserveCaseFor) ||
+                preserveCaseFor.some((channel) => typeof channel !== "string" || !channel.trim()))) {
+            throw new TypeError("identifierNormalization.preserveCaseFor must be an array of non-empty strings.");
+        }
+    }
 }
 function validatePayload(input) {
     if (!input.type || !input.type.trim()) {

package/dist/core/otp.types.d.ts

@@ -13,6 +13,11 @@ export interface RateLimitConfig {
     window: number;
     max: number;
 }
+export interface IdentifierNormalizationConfig {
+    trim?: boolean;
+    lowercase?: boolean;
+    preserveCaseFor?: OTPChannel[];
+}
 export interface OTPManagerOptions {
     store: StoreAdapter;
     ttl: number;
@@ -20,6 +25,8 @@ export interface OTPManagerOptions {
     rateLimit?: RateLimitConfig;
     devMode?: boolean;
     otpLength?: number;
+    resendCooldown?: number;
+    identifierNormalization?: IdentifierNormalizationConfig;
 }
 export interface GenerateOTPResult {
     expiresIn: number;

package/dist/errors/otp.errors.d.ts

@@ -14,3 +14,6 @@ export declare class OTPInvalidError extends OTPError {
 export declare class OTPMaxAttemptsExceededError extends OTPError {
     constructor(message?: string);
 }
+export declare class OTPResendCooldownError extends OTPError {
+    constructor(message?: string);
+}

package/dist/errors/otp.errors.js

@@ -26,3 +26,8 @@ export class OTPMaxAttemptsExceededError extends OTPError {
         super(message, "OTP_MAX_ATTEMPTS_EXCEEDED");
     }
 }
+export class OTPResendCooldownError extends OTPError {
+    constructor(message = "OTP resend cooldown is active.") {
+        super(message, "OTP_RESEND_COOLDOWN");
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { OTPManager } from "./core/otp.service.js";
 export { RedisAdapter } from "./adapters/redis.adapter.js";
 export { MemoryAdapter } from "./adapters/memory.adapter.js";
-export type { GenerateOTPInput, GenerateOTPResult, OTPManagerOptions, OTPPayload, RateLimitConfig, StoreAdapter, VerifyOTPInput, } from "./core/otp.types.js";
-export { OTPError, OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPRateLimitExceededError, } from "./errors/otp.errors.js";
+export type { GenerateOTPInput, GenerateOTPResult, IdentifierNormalizationConfig, OTPManagerOptions, OTPPayload, RateLimitConfig, StoreAdapter, VerifyOTPInput, } from "./core/otp.types.js";
+export { OTPError, OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPRateLimitExceededError, OTPResendCooldownError, } from "./errors/otp.errors.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { OTPManager } from "./core/otp.service.js";
 export { RedisAdapter } from "./adapters/redis.adapter.js";
 export { MemoryAdapter } from "./adapters/memory.adapter.js";
-export { OTPError, OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPRateLimitExceededError, } from "./errors/otp.errors.js";
+export { OTPError, OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPRateLimitExceededError, OTPResendCooldownError, } from "./errors/otp.errors.js";

package/dist/utils/identifier-normalizer.d.ts

@@ -0,0 +1,2 @@
+import type { IdentifierNormalizationConfig, OTPPayload } from "../core/otp.types.js";
+export declare function normalizePayloadIdentifier(payload: OTPPayload, config?: IdentifierNormalizationConfig): OTPPayload;

package/dist/utils/identifier-normalizer.js

@@ -0,0 +1,27 @@
+const DEFAULT_IDENTIFIER_NORMALIZATION = {
+    trim: true,
+    lowercase: true,
+    preserveCaseFor: ["sms", "token"],
+};
+export function normalizePayloadIdentifier(payload, config) {
+    const resolvedConfig = resolveNormalizationConfig(config);
+    let identifier = payload.identifier;
+    if (resolvedConfig.trim) {
+        identifier = identifier.trim();
+    }
+    const preserveCase = resolvedConfig.preserveCaseFor.includes(payload.type);
+    if (resolvedConfig.lowercase && !preserveCase) {
+        identifier = identifier.toLowerCase();
+    }
+    return {
+        ...payload,
+        identifier,
+    };
+}
+function resolveNormalizationConfig(config) {
+    return {
+        ...DEFAULT_IDENTIFIER_NORMALIZATION,
+        ...config,
+        preserveCaseFor: config?.preserveCaseFor ?? DEFAULT_IDENTIFIER_NORMALIZATION.preserveCaseFor,
+    };
+}

package/dist/utils/key-builder.d.ts

@@ -2,3 +2,4 @@ import type { OTPPayload } from "../core/otp.types.js";
 export declare function buildOtpKey(payload: OTPPayload): string;
 export declare function buildAttemptsKey(payload: OTPPayload): string;
 export declare function buildRateLimitKey(payload: OTPPayload): string;
+export declare function buildCooldownKey(payload: OTPPayload): string;

package/dist/utils/key-builder.js

@@ -10,3 +10,6 @@ export function buildAttemptsKey(payload) {
 export function buildRateLimitKey(payload) {
     return `rate:${payload.type}:${payload.identifier}`;
 }
+export function buildCooldownKey(payload) {
+    return `cooldown:${normalizeIntent(payload.intent)}:${payload.type}:${payload.identifier}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redis-otp-manager",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Lightweight, Redis-backed OTP manager for Node.js apps",
   "repository": {
     "type": "git",