redis-otp-manager 0.2.3 → 0.4.0

package/README.md

@@ -7,7 +7,9 @@ Lightweight, Redis-backed OTP manager for Node.js and NestJS apps.
 This package currently includes:
 - OTP generation
 - OTP verification
-- SHA-256 OTP hashing
+- Keyed HMAC support with app secret configuration
+- Secret rotation support for verification
+- Legacy SHA-256 verification compatibility for migrations
 - Redis-compatible storage adapter
 - In-memory adapter for tests
 - Intent-aware key strategy
@@ -15,6 +17,7 @@ This package currently includes:
 - Rate limiting
 - Optional resend cooldown
 - Max-attempt protection
+- Atomic Redis generate and verify paths using Lua scripts
 - NestJS module integration via `redis-otp-manager/nest`
 - Dual package support for ESM and CommonJS consumers
 
@@ -32,24 +35,10 @@ npm install @nestjs/common @nestjs/core reflect-metadata rxjs
 
 ## Module Support
 
-This package now supports both:
+This package supports both:
 - ESM imports
 - CommonJS/Nest `ts-node/register` style resolution
 
-ESM:
-
-```ts
-import { OTPManager } from "redis-otp-manager";
-import { OTPModule } from "redis-otp-manager/nest";
-```
-
-CommonJS:
-
-```js
-const { OTPManager } = require("redis-otp-manager");
-const { OTPModule } = require("redis-otp-manager/nest");
-```
-
 ## Quality Checks
 
 ```bash
@@ -73,25 +62,52 @@ const otp = new OTPManager({
     max: 3,
   },
   devMode: false,
+  hashing: {
+    secret: process.env.OTP_HMAC_SECRET,
+  },
 });
+```
 
-const generated = await otp.generate({
-  type: "email",
-  identifier: "abc@gmail.com",
-  intent: "login",
-});
+## Cryptographic Hardening
 
-await otp.verify({
-  type: "email",
-  identifier: "abc@gmail.com",
-  intent: "login",
-  otp: generated.otp ?? "123456",
+When `hashing.secret` is configured, new OTPs are stored using keyed HMAC instead of plain SHA-256.
+
+```ts
+const otp = new OTPManager({
+  store: new RedisAdapter(redisClient),
+  ttl: 300,
+  maxAttempts: 3,
+  hashing: {
+    secret: process.env.OTP_HMAC_SECRET,
+    previousSecrets: [process.env.OTP_PREVIOUS_SECRET ?? ""].filter(Boolean),
+    allowLegacyVerify: true,
+  },
 });
 ```
 
-## NestJS
+Recommended migration strategy:
+- deploy `hashing.secret`
+- keep `allowLegacyVerify: true` during migration
+- optionally add `previousSecrets` during secret rotation
+- after old in-flight OTPs naturally expire, you can disable legacy verification if desired
+
+Secure secret management guidance:
+- store secrets in environment variables or your secret manager
+- never hardcode secrets in source control
+- rotate secrets deliberately and keep the previous secret only as long as needed
+- use different secrets across environments
+
+## Production Security Notes
 
-Import the Nest integration from the dedicated subpath so non-Nest users do not pull Nest dependencies unless they need them.
+When you use `RedisAdapter`, the package takes the Redis-specific atomic path for:
+- OTP generation plus rate-limit/cooldown checks
+- OTP verification plus attempt tracking and OTP deletion
+
+That prevents the most important race condition from earlier versions where two parallel correct verification requests could both succeed.
+
+Simpler adapters like `MemoryAdapter` intentionally stay on the non-atomic fallback path to keep tests and local development lightweight.
+
+## NestJS
 
 ```ts
 import { Module } from "@nestjs/common";
@@ -112,6 +128,9 @@ const redisClient = createClient({ url: process.env.REDIS_URL });
         window: 60,
         max: 3,
       },
+      hashing: {
+        secret: process.env.OTP_HMAC_SECRET,
+      },
       isGlobal: true,
     }),
   ],
@@ -119,34 +138,6 @@ const redisClient = createClient({ url: process.env.REDIS_URL });
 export class AppModule {}
 ```
 
-Async setup is also supported:
-
-```ts
-OTPModule.forRootAsync({
-  isGlobal: true,
-  inject: [ConfigService],
-  useFactory: (config: ConfigService) => ({
-    store: new RedisAdapter(createClient({ url: config.getOrThrow("REDIS_URL") })),
-    ttl: 300,
-    maxAttempts: 5,
-    resendCooldown: 45,
-  }),
-});
-```
-
-Inject in services:
-
-```ts
-import { Injectable } from "@nestjs/common";
-import { OTPManager } from "redis-otp-manager";
-import { InjectOTPManager } from "redis-otp-manager/nest";
-
-@Injectable()
-export class AuthService {
-  constructor(@InjectOTPManager() private readonly otpManager: OTPManager) {}
-}
-```
-
 ## API
 
 ### `new OTPManager(options)`
@@ -168,47 +159,15 @@ type OTPManagerOptions = {
     lowercase?: boolean;
     preserveCaseFor?: string[];
   };
+  hashing?: {
+    secret?: string;
+    previousSecrets?: string[];
+    allowLegacyVerify?: boolean;
+  };
 };
 ```
 
-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
-const result = await otp.generate({
-  type: "email",
-  identifier: "abc@gmail.com",
-  intent: "login",
-});
-```
-
-Returns:
-
-```ts
-{
-  expiresIn: 300,
-  otp?: "123456"
-}
-```
-
-### `verify(input)`
-
-```ts
-await otp.verify({
-  type: "email",
-  identifier: "abc@gmail.com",
-  intent: "login",
-  otp: "123456",
-});
-```
-
-Returns `true` or throws a typed error.
-
-## Errors
+### Errors
 
 - `OTPRateLimitExceededError`
 - `OTPExpiredError`
@@ -221,7 +180,9 @@ Returns `true` or throws a typed error.
 - `devMode: false`
 - `otpLength: 8` for higher-risk flows
 - `maxAttempts: 3`
-- `resendCooldown: 30` or higher to reduce abuse
+- `resendCooldown: 30` or higher
+- `hashing.secret` configured in production
+- prefer `RedisAdapter` in production to get the atomic security path
 - keep Redis private and behind authenticated network access
 
 ## Key Design
@@ -237,7 +198,7 @@ cooldown:{intent}:{type}:{identifier}
 
 Publishing on every `main` merge is not recommended for npm packages because npm versions are immutable. The safer setup is:
 - merge to `main` runs CI only
-- publish happens when you push a version tag like `v0.2.0`
+- publish happens when you push a version tag like `v0.4.0`
 
 Required GitHub secrets:
 - `NPM_TOKEN`
@@ -245,12 +206,12 @@ Required GitHub secrets:
 Tag-based publish:
 
 ```bash
-git tag v0.2.0
-git push origin v0.2.0
+git tag v0.4.0
+git push origin v0.4.0
 ```
 
 ## Next Roadmap
 
-- atomic Redis verification
 - hooks/events
 - analytics and observability
+- delivery helper integrations

package/dist/adapters/redis.adapter.d.ts

@@ -7,7 +7,31 @@ export interface RedisLikeClient {
     del(key: string): Promise<unknown>;
     incr(key: string): Promise<number>;
     expire(key: string, seconds: number): Promise<unknown>;
+    eval?(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<string | number | null>;
 }
+export interface AtomicGenerateParams {
+    otpKey: string;
+    attemptsKey: string;
+    rateLimitKey: string;
+    cooldownKey: string;
+    hashedOtp: string;
+    ttl: number;
+    rateWindow?: number;
+    rateMax?: number;
+    resendCooldown?: number;
+}
+export interface AtomicVerifyParams {
+    otpKey: string;
+    attemptsKey: string;
+    candidateHashes: string[];
+    ttl: number;
+    maxAttempts: number;
+}
+export type AtomicGenerateResult = "ok" | "rate_limit" | "cooldown";
+export type AtomicVerifyResult = "verified" | "expired" | "invalid" | "max_attempts";
 export declare class RedisAdapter implements StoreAdapter {
     private readonly client;
     constructor(client: RedisLikeClient);
@@ -15,4 +39,6 @@ export declare class RedisAdapter implements StoreAdapter {
     set(key: string, value: string, ttlSeconds: number): Promise<void>;
     del(key: string): Promise<void>;
     increment(key: string, ttlSeconds: number): Promise<number>;
+    generateOtpAtomically(params: AtomicGenerateParams): Promise<AtomicGenerateResult | null>;
+    verifyOtpAtomically(params: AtomicVerifyParams): Promise<AtomicVerifyResult | null>;
 }

package/dist/adapters/redis.adapter.js

@@ -1,3 +1,60 @@
+const ATOMIC_GENERATE_SCRIPT = `
+if ARGV[5] ~= '' then
+  local cooldownExists = redis.call('GET', KEYS[4])
+  if cooldownExists then
+    return 'cooldown'
+  end
+end
+
+if ARGV[3] ~= '' and ARGV[4] ~= '' then
+  local nextCount = redis.call('INCR', KEYS[3])
+  if nextCount == 1 then
+    redis.call('EXPIRE', KEYS[3], tonumber(ARGV[3]))
+  end
+  if nextCount > tonumber(ARGV[4]) then
+    return 'rate_limit'
+  end
+end
+
+redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[2]))
+redis.call('DEL', KEYS[2])
+
+if ARGV[5] ~= '' then
+  redis.call('SET', KEYS[4], '1', 'EX', tonumber(ARGV[5]))
+end
+
+return 'ok'
+`;
+const ATOMIC_VERIFY_SCRIPT = `
+local storedHash = redis.call('GET', KEYS[1])
+if not storedHash then
+  return 'expired'
+end
+
+local candidateCount = tonumber(ARGV[1])
+for index = 1, candidateCount do
+  if storedHash == ARGV[index + 1] then
+    redis.call('DEL', KEYS[1])
+    redis.call('DEL', KEYS[2])
+    return 'verified'
+  end
+end
+
+local ttlIndex = candidateCount + 2
+local maxAttemptsIndex = candidateCount + 3
+local attempts = redis.call('INCR', KEYS[2])
+if attempts == 1 then
+  redis.call('EXPIRE', KEYS[2], tonumber(ARGV[ttlIndex]))
+end
+
+if attempts >= tonumber(ARGV[maxAttemptsIndex]) then
+  redis.call('DEL', KEYS[1])
+  redis.call('DEL', KEYS[2])
+  return 'max_attempts'
+end
+
+return 'invalid'
+`;
 export class RedisAdapter {
     client;
     constructor(client) {
@@ -19,4 +76,44 @@ export class RedisAdapter {
         }
         return nextValue;
     }
+    async generateOtpAtomically(params) {
+        if (!this.client.eval) {
+            return null;
+        }
+        const result = await this.client.eval(ATOMIC_GENERATE_SCRIPT, {
+            keys: [params.otpKey, params.attemptsKey, params.rateLimitKey, params.cooldownKey],
+            arguments: [
+                params.hashedOtp,
+                String(params.ttl),
+                params.rateWindow ? String(params.rateWindow) : "",
+                params.rateMax ? String(params.rateMax) : "",
+                params.resendCooldown ? String(params.resendCooldown) : "",
+            ],
+        });
+        if (result === "ok" || result === "rate_limit" || result === "cooldown") {
+            return result;
+        }
+        return null;
+    }
+    async verifyOtpAtomically(params) {
+        if (!this.client.eval) {
+            return null;
+        }
+        const result = await this.client.eval(ATOMIC_VERIFY_SCRIPT, {
+            keys: [params.otpKey, params.attemptsKey],
+            arguments: [
+                String(params.candidateHashes.length),
+                ...params.candidateHashes,
+                String(params.ttl),
+                String(params.maxAttempts),
+            ],
+        });
+        if (result === "verified" ||
+            result === "expired" ||
+            result === "invalid" ||
+            result === "max_attempts") {
+            return result;
+        }
+        return null;
+    }
 }

package/dist/cjs/adapters/redis.adapter.js

@@ -1,6 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisAdapter = void 0;
+const ATOMIC_GENERATE_SCRIPT = `
+if ARGV[5] ~= '' then
+  local cooldownExists = redis.call('GET', KEYS[4])
+  if cooldownExists then
+    return 'cooldown'
+  end
+end
+
+if ARGV[3] ~= '' and ARGV[4] ~= '' then
+  local nextCount = redis.call('INCR', KEYS[3])
+  if nextCount == 1 then
+    redis.call('EXPIRE', KEYS[3], tonumber(ARGV[3]))
+  end
+  if nextCount > tonumber(ARGV[4]) then
+    return 'rate_limit'
+  end
+end
+
+redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[2]))
+redis.call('DEL', KEYS[2])
+
+if ARGV[5] ~= '' then
+  redis.call('SET', KEYS[4], '1', 'EX', tonumber(ARGV[5]))
+end
+
+return 'ok'
+`;
+const ATOMIC_VERIFY_SCRIPT = `
+local storedHash = redis.call('GET', KEYS[1])
+if not storedHash then
+  return 'expired'
+end
+
+local candidateCount = tonumber(ARGV[1])
+for index = 1, candidateCount do
+  if storedHash == ARGV[index + 1] then
+    redis.call('DEL', KEYS[1])
+    redis.call('DEL', KEYS[2])
+    return 'verified'
+  end
+end
+
+local ttlIndex = candidateCount + 2
+local maxAttemptsIndex = candidateCount + 3
+local attempts = redis.call('INCR', KEYS[2])
+if attempts == 1 then
+  redis.call('EXPIRE', KEYS[2], tonumber(ARGV[ttlIndex]))
+end
+
+if attempts >= tonumber(ARGV[maxAttemptsIndex]) then
+  redis.call('DEL', KEYS[1])
+  redis.call('DEL', KEYS[2])
+  return 'max_attempts'
+end
+
+return 'invalid'
+`;
 class RedisAdapter {
     client;
     constructor(client) {
@@ -22,5 +79,45 @@ class RedisAdapter {
         }
         return nextValue;
     }
+    async generateOtpAtomically(params) {
+        if (!this.client.eval) {
+            return null;
+        }
+        const result = await this.client.eval(ATOMIC_GENERATE_SCRIPT, {
+            keys: [params.otpKey, params.attemptsKey, params.rateLimitKey, params.cooldownKey],
+            arguments: [
+                params.hashedOtp,
+                String(params.ttl),
+                params.rateWindow ? String(params.rateWindow) : "",
+                params.rateMax ? String(params.rateMax) : "",
+                params.resendCooldown ? String(params.resendCooldown) : "",
+            ],
+        });
+        if (result === "ok" || result === "rate_limit" || result === "cooldown") {
+            return result;
+        }
+        return null;
+    }
+    async verifyOtpAtomically(params) {
+        if (!this.client.eval) {
+            return null;
+        }
+        const result = await this.client.eval(ATOMIC_VERIFY_SCRIPT, {
+            keys: [params.otpKey, params.attemptsKey],
+            arguments: [
+                String(params.candidateHashes.length),
+                ...params.candidateHashes,
+                String(params.ttl),
+                String(params.maxAttempts),
+            ],
+        });
+        if (result === "verified" ||
+            result === "expired" ||
+            result === "invalid" ||
+            result === "max_attempts") {
+            return result;
+        }
+        return null;
+    }
 }
 exports.RedisAdapter = RedisAdapter;

package/dist/cjs/core/otp.hash.js

@@ -1,16 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hashOtp = hashOtp;
+exports.createStoredOtpHash = createStoredOtpHash;
+exports.buildVerificationHashes = buildVerificationHashes;
 exports.verifyOtpHash = verifyOtpHash;
 const node_crypto_1 = require("node:crypto");
+const LEGACY_PREFIX = "sha256:";
+const HMAC_PREFIX = "hmac-sha256:";
 function hashOtp(otp) {
     return (0, node_crypto_1.createHash)("sha256").update(otp).digest("hex");
 }
-function verifyOtpHash(otp, expectedHash) {
-    const actualBuffer = Buffer.from(hashOtp(otp), "hex");
-    const expectedBuffer = Buffer.from(expectedHash, "hex");
-    if (actualBuffer.length !== expectedBuffer.length) {
+function createStoredOtpHash(otp, payload, hashing) {
+    if (hashing?.secret) {
+        return `${HMAC_PREFIX}${hashOtpWithSecret(otp, payload, hashing.secret)}`;
+    }
+    return `${LEGACY_PREFIX}${hashOtp(otp)}`;
+}
+function buildVerificationHashes(otp, payload, hashing) {
+    const candidates = new Set();
+    if (hashing?.secret) {
+        candidates.add(`${HMAC_PREFIX}${hashOtpWithSecret(otp, payload, hashing.secret)}`);
+        for (const secret of hashing.previousSecrets ?? []) {
+            candidates.add(`${HMAC_PREFIX}${hashOtpWithSecret(otp, payload, secret)}`);
+        }
+    }
+    const allowLegacyVerify = hashing?.allowLegacyVerify ?? true;
+    if (!hashing?.secret || allowLegacyVerify) {
+        const legacyHash = hashOtp(otp);
+        candidates.add(legacyHash);
+        candidates.add(`${LEGACY_PREFIX}${legacyHash}`);
+    }
+    return [...candidates];
+}
+function verifyOtpHash(otp, payload, expectedHash, hashing) {
+    const candidates = buildVerificationHashes(otp, payload, hashing);
+    return candidates.some((candidate) => safeCompareHashes(candidate, expectedHash));
+}
+function hashOtpWithSecret(otp, payload, secret) {
+    return (0, node_crypto_1.createHmac)("sha256", secret).update(buildHmacMaterial(otp, payload)).digest("hex");
+}
+function buildHmacMaterial(otp, payload) {
+    return [payload.intent ?? "default", payload.type, payload.identifier, otp].join(":");
+}
+function safeCompareHashes(candidate, expectedHash) {
+    const candidateBuffer = Buffer.from(candidate);
+    const expectedBuffer = Buffer.from(expectedHash);
+    if (candidateBuffer.length !== expectedBuffer.length) {
         return false;
     }
-    return (0, node_crypto_1.timingSafeEqual)(actualBuffer, expectedBuffer);
+    return (0, node_crypto_1.timingSafeEqual)(candidateBuffer, expectedBuffer);
 }

package/dist/cjs/core/otp.service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OTPManager = void 0;
+const redis_adapter_js_1 = require("../adapters/redis.adapter.js");
 const otp_generator_js_1 = require("./otp.generator.js");
 const otp_hash_js_1 = require("./otp.hash.js");
 const otp_errors_js_1 = require("../errors/otp.errors.js");
@@ -24,6 +25,33 @@ class OTPManager {
         const attemptsKey = (0, key_builder_js_1.buildAttemptsKey)(normalizedInput);
         const rateLimitKey = (0, key_builder_js_1.buildRateLimitKey)(normalizedInput);
         const cooldownKey = (0, key_builder_js_1.buildCooldownKey)(normalizedInput);
+        const otp = (0, otp_generator_js_1.generateNumericOtp)(this.options.otpLength);
+        const storedHash = (0, otp_hash_js_1.createStoredOtpHash)(otp, normalizedInput, this.options.hashing);
+        if (this.options.store instanceof redis_adapter_js_1.RedisAdapter) {
+            const atomicResult = await this.options.store.generateOtpAtomically({
+                otpKey,
+                attemptsKey,
+                rateLimitKey,
+                cooldownKey,
+                hashedOtp: storedHash,
+                ttl: this.options.ttl,
+                rateWindow: this.options.rateLimit?.window,
+                rateMax: this.options.rateLimit?.max,
+                resendCooldown: this.options.resendCooldown,
+            });
+            if (atomicResult === "cooldown") {
+                throw new otp_errors_js_1.OTPResendCooldownError();
+            }
+            if (atomicResult === "rate_limit") {
+                throw new otp_errors_js_1.OTPRateLimitExceededError();
+            }
+            if (atomicResult === "ok") {
+                return {
+                    expiresIn: this.options.ttl,
+                    otp: this.options.devMode ? otp : undefined,
+                };
+            }
+        }
         if (this.options.resendCooldown) {
             const cooldownActive = await this.options.store.get(cooldownKey);
             if (cooldownActive) {
@@ -31,9 +59,7 @@ class OTPManager {
             }
         }
         await (0, rate_limiter_js_1.assertWithinRateLimit)(this.options.store, rateLimitKey, this.options.rateLimit);
-        const otp = (0, otp_generator_js_1.generateNumericOtp)(this.options.otpLength);
-        const hashedOtp = (0, otp_hash_js_1.hashOtp)(otp);
-        await this.options.store.set(otpKey, hashedOtp, this.options.ttl);
+        await this.options.store.set(otpKey, storedHash, this.options.ttl);
         await this.options.store.del(attemptsKey);
         if (this.options.resendCooldown) {
             await this.options.store.set(cooldownKey, "1", this.options.resendCooldown);
@@ -51,11 +77,33 @@ class OTPManager {
         }
         const otpKey = (0, key_builder_js_1.buildOtpKey)(normalizedInput);
         const attemptsKey = (0, key_builder_js_1.buildAttemptsKey)(normalizedInput);
+        const candidateHashes = (0, otp_hash_js_1.buildVerificationHashes)(input.otp, normalizedInput, this.options.hashing);
+        if (this.options.store instanceof redis_adapter_js_1.RedisAdapter) {
+            const atomicResult = await this.options.store.verifyOtpAtomically({
+                otpKey,
+                attemptsKey,
+                candidateHashes,
+                ttl: this.options.ttl,
+                maxAttempts: this.options.maxAttempts,
+            });
+            if (atomicResult === "verified") {
+                return true;
+            }
+            if (atomicResult === "expired") {
+                throw new otp_errors_js_1.OTPExpiredError();
+            }
+            if (atomicResult === "max_attempts") {
+                throw new otp_errors_js_1.OTPMaxAttemptsExceededError();
+            }
+            if (atomicResult === "invalid") {
+                throw new otp_errors_js_1.OTPInvalidError();
+            }
+        }
         const storedHash = await this.options.store.get(otpKey);
         if (!storedHash) {
             throw new otp_errors_js_1.OTPExpiredError();
         }
-        const isValid = (0, otp_hash_js_1.verifyOtpHash)(input.otp, storedHash);
+        const isValid = (0, otp_hash_js_1.verifyOtpHash)(input.otp, normalizedInput, storedHash, this.options.hashing);
         if (!isValid) {
             const attempts = await this.options.store.increment(attemptsKey, this.options.ttl);
             if (attempts >= this.options.maxAttempts) {
@@ -108,6 +156,20 @@ function validateManagerOptions(options) {
             throw new TypeError("identifierNormalization.preserveCaseFor must be an array of non-empty strings.");
         }
     }
+    if (options.hashing) {
+        if (options.hashing.secret !== undefined && !options.hashing.secret.trim()) {
+            throw new TypeError("hashing.secret must be a non-empty string when provided.");
+        }
+        if (options.hashing.previousSecrets !== undefined &&
+            (!Array.isArray(options.hashing.previousSecrets) ||
+                options.hashing.previousSecrets.some((secret) => !secret || !secret.trim()))) {
+            throw new TypeError("hashing.previousSecrets must contain only non-empty strings.");
+        }
+        if (options.hashing.allowLegacyVerify !== undefined &&
+            typeof options.hashing.allowLegacyVerify !== "boolean") {
+            throw new TypeError("hashing.allowLegacyVerify must be a boolean.");
+        }
+    }
 }
 function validatePayload(input) {
     if (!input.type || !input.type.trim()) {

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

@@ -1,2 +1,5 @@
+import type { OTPHashingOptions, OTPPayload } from "./otp.types.js";
 export declare function hashOtp(otp: string): string;
-export declare function verifyOtpHash(otp: string, expectedHash: string): boolean;
+export declare function createStoredOtpHash(otp: string, payload: OTPPayload, hashing?: OTPHashingOptions): string;
+export declare function buildVerificationHashes(otp: string, payload: OTPPayload, hashing?: OTPHashingOptions): string[];
+export declare function verifyOtpHash(otp: string, payload: OTPPayload, expectedHash: string, hashing?: OTPHashingOptions): boolean;

package/dist/core/otp.hash.js

@@ -1,12 +1,46 @@
-import { createHash, timingSafeEqual } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+const LEGACY_PREFIX = "sha256:";
+const HMAC_PREFIX = "hmac-sha256:";
 export function hashOtp(otp) {
     return createHash("sha256").update(otp).digest("hex");
 }
-export function verifyOtpHash(otp, expectedHash) {
-    const actualBuffer = Buffer.from(hashOtp(otp), "hex");
-    const expectedBuffer = Buffer.from(expectedHash, "hex");
-    if (actualBuffer.length !== expectedBuffer.length) {
+export function createStoredOtpHash(otp, payload, hashing) {
+    if (hashing?.secret) {
+        return `${HMAC_PREFIX}${hashOtpWithSecret(otp, payload, hashing.secret)}`;
+    }
+    return `${LEGACY_PREFIX}${hashOtp(otp)}`;
+}
+export function buildVerificationHashes(otp, payload, hashing) {
+    const candidates = new Set();
+    if (hashing?.secret) {
+        candidates.add(`${HMAC_PREFIX}${hashOtpWithSecret(otp, payload, hashing.secret)}`);
+        for (const secret of hashing.previousSecrets ?? []) {
+            candidates.add(`${HMAC_PREFIX}${hashOtpWithSecret(otp, payload, secret)}`);
+        }
+    }
+    const allowLegacyVerify = hashing?.allowLegacyVerify ?? true;
+    if (!hashing?.secret || allowLegacyVerify) {
+        const legacyHash = hashOtp(otp);
+        candidates.add(legacyHash);
+        candidates.add(`${LEGACY_PREFIX}${legacyHash}`);
+    }
+    return [...candidates];
+}
+export function verifyOtpHash(otp, payload, expectedHash, hashing) {
+    const candidates = buildVerificationHashes(otp, payload, hashing);
+    return candidates.some((candidate) => safeCompareHashes(candidate, expectedHash));
+}
+function hashOtpWithSecret(otp, payload, secret) {
+    return createHmac("sha256", secret).update(buildHmacMaterial(otp, payload)).digest("hex");
+}
+function buildHmacMaterial(otp, payload) {
+    return [payload.intent ?? "default", payload.type, payload.identifier, otp].join(":");
+}
+function safeCompareHashes(candidate, expectedHash) {
+    const candidateBuffer = Buffer.from(candidate);
+    const expectedBuffer = Buffer.from(expectedHash);
+    if (candidateBuffer.length !== expectedBuffer.length) {
         return false;
     }
-    return timingSafeEqual(actualBuffer, expectedBuffer);
+    return timingSafeEqual(candidateBuffer, expectedBuffer);
 }

package/dist/core/otp.service.js

@@ -1,6 +1,7 @@
+import { RedisAdapter } from "../adapters/redis.adapter.js";
 import { generateNumericOtp } from "./otp.generator.js";
-import { hashOtp, verifyOtpHash } from "./otp.hash.js";
-import { OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPResendCooldownError, } from "../errors/otp.errors.js";
+import { buildVerificationHashes, createStoredOtpHash, verifyOtpHash } from "./otp.hash.js";
+import { OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPRateLimitExceededError, 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";
@@ -21,6 +22,33 @@ export class OTPManager {
         const attemptsKey = buildAttemptsKey(normalizedInput);
         const rateLimitKey = buildRateLimitKey(normalizedInput);
         const cooldownKey = buildCooldownKey(normalizedInput);
+        const otp = generateNumericOtp(this.options.otpLength);
+        const storedHash = createStoredOtpHash(otp, normalizedInput, this.options.hashing);
+        if (this.options.store instanceof RedisAdapter) {
+            const atomicResult = await this.options.store.generateOtpAtomically({
+                otpKey,
+                attemptsKey,
+                rateLimitKey,
+                cooldownKey,
+                hashedOtp: storedHash,
+                ttl: this.options.ttl,
+                rateWindow: this.options.rateLimit?.window,
+                rateMax: this.options.rateLimit?.max,
+                resendCooldown: this.options.resendCooldown,
+            });
+            if (atomicResult === "cooldown") {
+                throw new OTPResendCooldownError();
+            }
+            if (atomicResult === "rate_limit") {
+                throw new OTPRateLimitExceededError();
+            }
+            if (atomicResult === "ok") {
+                return {
+                    expiresIn: this.options.ttl,
+                    otp: this.options.devMode ? otp : undefined,
+                };
+            }
+        }
         if (this.options.resendCooldown) {
             const cooldownActive = await this.options.store.get(cooldownKey);
             if (cooldownActive) {
@@ -28,9 +56,7 @@ export class OTPManager {
             }
         }
         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.set(otpKey, storedHash, this.options.ttl);
         await this.options.store.del(attemptsKey);
         if (this.options.resendCooldown) {
             await this.options.store.set(cooldownKey, "1", this.options.resendCooldown);
@@ -48,11 +74,33 @@ export class OTPManager {
         }
         const otpKey = buildOtpKey(normalizedInput);
         const attemptsKey = buildAttemptsKey(normalizedInput);
+        const candidateHashes = buildVerificationHashes(input.otp, normalizedInput, this.options.hashing);
+        if (this.options.store instanceof RedisAdapter) {
+            const atomicResult = await this.options.store.verifyOtpAtomically({
+                otpKey,
+                attemptsKey,
+                candidateHashes,
+                ttl: this.options.ttl,
+                maxAttempts: this.options.maxAttempts,
+            });
+            if (atomicResult === "verified") {
+                return true;
+            }
+            if (atomicResult === "expired") {
+                throw new OTPExpiredError();
+            }
+            if (atomicResult === "max_attempts") {
+                throw new OTPMaxAttemptsExceededError();
+            }
+            if (atomicResult === "invalid") {
+                throw new OTPInvalidError();
+            }
+        }
         const storedHash = await this.options.store.get(otpKey);
         if (!storedHash) {
             throw new OTPExpiredError();
         }
-        const isValid = verifyOtpHash(input.otp, storedHash);
+        const isValid = verifyOtpHash(input.otp, normalizedInput, storedHash, this.options.hashing);
         if (!isValid) {
             const attempts = await this.options.store.increment(attemptsKey, this.options.ttl);
             if (attempts >= this.options.maxAttempts) {
@@ -104,6 +152,20 @@ function validateManagerOptions(options) {
             throw new TypeError("identifierNormalization.preserveCaseFor must be an array of non-empty strings.");
         }
     }
+    if (options.hashing) {
+        if (options.hashing.secret !== undefined && !options.hashing.secret.trim()) {
+            throw new TypeError("hashing.secret must be a non-empty string when provided.");
+        }
+        if (options.hashing.previousSecrets !== undefined &&
+            (!Array.isArray(options.hashing.previousSecrets) ||
+                options.hashing.previousSecrets.some((secret) => !secret || !secret.trim()))) {
+            throw new TypeError("hashing.previousSecrets must contain only non-empty strings.");
+        }
+        if (options.hashing.allowLegacyVerify !== undefined &&
+            typeof options.hashing.allowLegacyVerify !== "boolean") {
+            throw new TypeError("hashing.allowLegacyVerify must be a boolean.");
+        }
+    }
 }
 function validatePayload(input) {
     if (!input.type || !input.type.trim()) {

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

@@ -18,6 +18,11 @@ export interface IdentifierNormalizationConfig {
     lowercase?: boolean;
     preserveCaseFor?: OTPChannel[];
 }
+export interface OTPHashingOptions {
+    secret?: string;
+    previousSecrets?: string[];
+    allowLegacyVerify?: boolean;
+}
 export interface OTPManagerOptions {
     store: StoreAdapter;
     ttl: number;
@@ -27,6 +32,7 @@ export interface OTPManagerOptions {
     otpLength?: number;
     resendCooldown?: number;
     identifierNormalization?: IdentifierNormalizationConfig;
+    hashing?: OTPHashingOptions;
 }
 export interface GenerateOTPResult {
     expiresIn: number;

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, IdentifierNormalizationConfig, OTPManagerOptions, OTPPayload, RateLimitConfig, StoreAdapter, VerifyOTPInput, } from "./core/otp.types.js";
+export type { GenerateOTPInput, GenerateOTPResult, IdentifierNormalizationConfig, OTPHashingOptions, OTPManagerOptions, OTPPayload, RateLimitConfig, StoreAdapter, VerifyOTPInput, } from "./core/otp.types.js";
 export { OTPError, OTPExpiredError, OTPInvalidError, OTPMaxAttemptsExceededError, OTPRateLimitExceededError, OTPResendCooldownError, } from "./errors/otp.errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redis-otp-manager",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "Lightweight, Redis-backed OTP manager for Node.js apps",
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/prepare-cjs.cjs",
-    "test": "tsx --test test/**/*.test.ts",
+    "test": "tsx --test test/*.test.ts",
     "check": "npm run build && npm run test",
     "prepublishOnly": "npm run build"
   },
@@ -91,3 +91,4 @@
     "typescript": "^5.8.0"
   }
 }
+