redis-otp-manager 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay prakash
+
+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,132 @@
+# redis-otp-manager
+
+Lightweight, Redis-backed OTP manager for Node.js apps.
+
+## Current MVP
+
+This first implementation includes:
+- OTP generation
+- OTP verification
+- SHA-256 OTP hashing
+- Redis-compatible storage adapter
+- In-memory adapter for tests
+- Intent-aware key strategy
+- Rate limiting
+- Max-attempt protection
+
+## Install
+
+```bash
+npm install redis-otp-manager
+```
+
+## Quality Checks
+
+```bash
+npm run check
+```
+
+## Quick Start
+
+```ts
+import { OTPManager, RedisAdapter } from "redis-otp-manager";
+
+const redisClient = /* your redis client */;
+
+const otp = new OTPManager({
+  store: new RedisAdapter(redisClient),
+  ttl: 300,
+  maxAttempts: 5,
+  rateLimit: {
+    window: 60,
+    max: 3,
+  },
+  devMode: process.env.NODE_ENV !== "production",
+});
+
+const generated = await otp.generate({
+  type: "email",
+  identifier: "abc@gmail.com",
+  intent: "login",
+});
+
+await otp.verify({
+  type: "email",
+  identifier: "abc@gmail.com",
+  intent: "login",
+  otp: generated.otp ?? "123456",
+});
+```
+
+## API
+
+### `new OTPManager(options)`
+
+```ts
+type OTPManagerOptions = {
+  store: StoreAdapter;
+  ttl: number;
+  maxAttempts: number;
+  rateLimit?: {
+    window: number;
+    max: number;
+  };
+  devMode?: boolean;
+  otpLength?: number;
+};
+```
+
+### `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
+
+- `OTPRateLimitExceededError`
+- `OTPExpiredError`
+- `OTPInvalidError`
+- `OTPMaxAttemptsExceededError`
+
+## Key Design
+
+```txt
+otp:{intent}:{type}:{identifier}
+attempts:{intent}:{type}:{identifier}
+rate:{type}:{identifier}
+```
+
+## Next Roadmap
+
+- NestJS module and decorator
+- alphanumeric tokens
+- hooks/events
+- email token helpers
+

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

@@ -0,0 +1,8 @@
+import type { StoreAdapter } from "../core/otp.types.js";
+export declare class MemoryAdapter implements StoreAdapter {
+    private readonly storage;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    increment(key: string, ttlSeconds: number): Promise<number>;
+}

package/dist/adapters/memory.adapter.js

@@ -0,0 +1,36 @@
+export class MemoryAdapter {
+    storage = new Map();
+    async get(key) {
+        const record = this.storage.get(key);
+        if (!record) {
+            return null;
+        }
+        if (record.expiresAt <= Date.now()) {
+            this.storage.delete(key);
+            return null;
+        }
+        return record.value;
+    }
+    async set(key, value, ttlSeconds) {
+        this.storage.set(key, {
+            value,
+            expiresAt: Date.now() + ttlSeconds * 1000,
+        });
+    }
+    async del(key) {
+        this.storage.delete(key);
+    }
+    async increment(key, ttlSeconds) {
+        const currentRecord = this.storage.get(key);
+        if (!currentRecord || currentRecord.expiresAt <= Date.now()) {
+            await this.set(key, "1", ttlSeconds);
+            return 1;
+        }
+        const nextValue = Number(currentRecord.value) + 1;
+        this.storage.set(key, {
+            value: String(nextValue),
+            expiresAt: currentRecord.expiresAt,
+        });
+        return nextValue;
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { StoreAdapter } from "../core/otp.types.js";
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+    }): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<unknown>;
+}
+export declare class RedisAdapter implements StoreAdapter {
+    private readonly client;
+    constructor(client: RedisLikeClient);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    increment(key: string, ttlSeconds: number): Promise<number>;
+}

package/dist/adapters/redis.adapter.js

@@ -0,0 +1,22 @@
+export class RedisAdapter {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async get(key) {
+        return this.client.get(key);
+    }
+    async set(key, value, ttlSeconds) {
+        await this.client.set(key, value, { EX: ttlSeconds });
+    }
+    async del(key) {
+        await this.client.del(key);
+    }
+    async increment(key, ttlSeconds) {
+        const nextValue = await this.client.incr(key);
+        if (nextValue === 1) {
+            await this.client.expire(key, ttlSeconds);
+        }
+        return nextValue;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function generateNumericOtp(length?: number): string;

package/dist/core/otp.generator.js

@@ -0,0 +1,11 @@
+import { randomInt } from "node:crypto";
+export function generateNumericOtp(length = 6) {
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new TypeError("OTP length must be a positive integer.");
+    }
+    let otp = "";
+    for (let index = 0; index < length; index += 1) {
+        otp += randomInt(0, 10).toString();
+    }
+    return otp;
+}

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

@@ -0,0 +1,2 @@
+export declare function hashOtp(otp: string): string;
+export declare function verifyOtpHash(otp: string, expectedHash: string): boolean;

package/dist/core/otp.hash.js

@@ -0,0 +1,12 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+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) {
+        return false;
+    }
+    return timingSafeEqual(actualBuffer, expectedBuffer);
+}

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

@@ -0,0 +1,7 @@
+import type { GenerateOTPInput, GenerateOTPResult, OTPManagerOptions, VerifyOTPInput } from "./otp.types.js";
+export declare class OTPManager {
+    private readonly options;
+    constructor(options: OTPManagerOptions);
+    generate(input: GenerateOTPInput): Promise<GenerateOTPResult>;
+    verify(input: VerifyOTPInput): Promise<true>;
+}

package/dist/core/otp.service.js

@@ -0,0 +1,84 @@
+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 { assertWithinRateLimit } from "../utils/rate-limiter.js";
+export class OTPManager {
+    options;
+    constructor(options) {
+        validateManagerOptions(options);
+        this.options = {
+            ...options,
+            otpLength: options.otpLength ?? 6,
+            devMode: options.devMode ?? false,
+        };
+    }
+    async generate(input) {
+        validatePayload(input);
+        const otpKey = buildOtpKey(input);
+        const attemptsKey = buildAttemptsKey(input);
+        const rateLimitKey = buildRateLimitKey(input);
+        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);
+        return {
+            expiresIn: this.options.ttl,
+            otp: this.options.devMode ? otp : undefined,
+        };
+    }
+    async verify(input) {
+        validatePayload(input);
+        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 storedHash = await this.options.store.get(otpKey);
+        if (!storedHash) {
+            throw new OTPExpiredError();
+        }
+        const isValid = verifyOtpHash(input.otp, storedHash);
+        if (!isValid) {
+            const attempts = await this.options.store.increment(attemptsKey, this.options.ttl);
+            if (attempts >= this.options.maxAttempts) {
+                await this.options.store.del(otpKey);
+                await this.options.store.del(attemptsKey);
+                throw new OTPMaxAttemptsExceededError();
+            }
+            throw new OTPInvalidError();
+        }
+        await this.options.store.del(otpKey);
+        await this.options.store.del(attemptsKey);
+        return true;
+    }
+}
+function validateManagerOptions(options) {
+    if (!Number.isInteger(options.ttl) || options.ttl <= 0) {
+        throw new TypeError("ttl must be a positive integer.");
+    }
+    if (!Number.isInteger(options.maxAttempts) || options.maxAttempts <= 0) {
+        throw new TypeError("maxAttempts must be a positive integer.");
+    }
+    if (options.otpLength !== undefined &&
+        (!Number.isInteger(options.otpLength) || options.otpLength <= 0)) {
+        throw new TypeError("otpLength 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.");
+        }
+        if (!Number.isInteger(options.rateLimit.max) || options.rateLimit.max <= 0) {
+            throw new TypeError("rateLimit.max must be a positive integer.");
+        }
+    }
+}
+function validatePayload(input) {
+    if (!input.type || !input.type.trim()) {
+        throw new TypeError("type must be a non-empty string.");
+    }
+    if (!input.identifier || !input.identifier.trim()) {
+        throw new TypeError("identifier must be a non-empty string.");
+    }
+}

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

@@ -0,0 +1,33 @@
+export type OTPChannel = "email" | "sms" | "token" | (string & {});
+export interface OTPPayload {
+    type: OTPChannel;
+    identifier: string;
+    intent?: string;
+}
+export interface GenerateOTPInput extends OTPPayload {
+}
+export interface VerifyOTPInput extends OTPPayload {
+    otp: string;
+}
+export interface RateLimitConfig {
+    window: number;
+    max: number;
+}
+export interface OTPManagerOptions {
+    store: StoreAdapter;
+    ttl: number;
+    maxAttempts: number;
+    rateLimit?: RateLimitConfig;
+    devMode?: boolean;
+    otpLength?: number;
+}
+export interface GenerateOTPResult {
+    expiresIn: number;
+    otp?: string;
+}
+export interface StoreAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    increment(key: string, ttlSeconds: number): Promise<number>;
+}

package/dist/core/otp.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+export declare class OTPError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class OTPRateLimitExceededError extends OTPError {
+    constructor(message?: string);
+}
+export declare class OTPExpiredError extends OTPError {
+    constructor(message?: string);
+}
+export declare class OTPInvalidError extends OTPError {
+    constructor(message?: string);
+}
+export declare class OTPMaxAttemptsExceededError extends OTPError {
+    constructor(message?: string);
+}

package/dist/errors/otp.errors.js

@@ -0,0 +1,28 @@
+export class OTPError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+export class OTPRateLimitExceededError extends OTPError {
+    constructor(message = "OTP request rate limit exceeded.") {
+        super(message, "OTP_RATE_LIMIT_EXCEEDED");
+    }
+}
+export class OTPExpiredError extends OTPError {
+    constructor(message = "OTP has expired or does not exist.") {
+        super(message, "OTP_EXPIRED");
+    }
+}
+export class OTPInvalidError extends OTPError {
+    constructor(message = "OTP is invalid.") {
+        super(message, "OTP_INVALID");
+    }
+}
+export class OTPMaxAttemptsExceededError extends OTPError {
+    constructor(message = "Maximum OTP verification attempts exceeded.") {
+        super(message, "OTP_MAX_ATTEMPTS_EXCEEDED");
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

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

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

package/dist/utils/key-builder.js

@@ -0,0 +1,12 @@
+function normalizeIntent(intent) {
+    return intent ?? "default";
+}
+export function buildOtpKey(payload) {
+    return `otp:${normalizeIntent(payload.intent)}:${payload.type}:${payload.identifier}`;
+}
+export function buildAttemptsKey(payload) {
+    return `attempts:${normalizeIntent(payload.intent)}:${payload.type}:${payload.identifier}`;
+}
+export function buildRateLimitKey(payload) {
+    return `rate:${payload.type}:${payload.identifier}`;
+}

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,2 @@
+import type { RateLimitConfig, StoreAdapter } from "../core/otp.types.js";
+export declare function assertWithinRateLimit(store: StoreAdapter, key: string, config?: RateLimitConfig): Promise<void>;

package/dist/utils/rate-limiter.js

@@ -0,0 +1,10 @@
+import { OTPRateLimitExceededError } from "../errors/otp.errors.js";
+export async function assertWithinRateLimit(store, key, config) {
+    if (!config) {
+        return;
+    }
+    const nextCount = await store.increment(key, config.window);
+    if (nextCount > config.max) {
+        throw new OTPRateLimitExceededError();
+    }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "redis-otp-manager",
+  "version": "0.1.0",
+  "description": "Lightweight, Redis-backed OTP manager for Node.js apps",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/prakashu51/otp-generator.git"
+  },
+  "homepage": "https://github.com/prakashu51/otp-generator#readme",
+  "bugs": {
+    "url": "https://github.com/prakashu51/otp-generator/issues"
+  },
+  "license": "MIT",
+  "author": "Prakash",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "tsx --test test/**/*.test.ts",
+    "check": "npm run build && npm run test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "otp",
+    "redis",
+    "nodejs",
+    "authentication",
+    "security",
+    "verification",
+    "one-time-password"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "redis": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "redis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}
+