@flink-app/otp-auth-plugin 0.12.1-alpha.40

package/dist/utils/otp-utils.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeIdentifier = exports.normalizeEmail = exports.normalizePhoneNumber = exports.validateIdentifier = exports.generateSessionId = exports.generateOtpCode = void 0;
+var crypto_1 = __importDefault(require("crypto"));
+/**
+ * Generates a random numeric OTP code.
+ *
+ * @param length - Number of digits (4-8)
+ * @returns A numeric string of the specified length
+ */
+function generateOtpCode(length) {
+    if (length === void 0) { length = 6; }
+    if (length < 4 || length > 8) {
+        throw new Error("OTP code length must be between 4 and 8 digits");
+    }
+    // Generate a random number with the specified number of digits
+    var min = Math.pow(10, length - 1);
+    var max = Math.pow(10, length) - 1;
+    // Use crypto.randomInt for cryptographically secure random numbers
+    return crypto_1.default.randomInt(min, max + 1).toString();
+}
+exports.generateOtpCode = generateOtpCode;
+/**
+ * Generates a unique session ID.
+ *
+ * @returns A cryptographically secure random hex string
+ */
+function generateSessionId() {
+    return crypto_1.default.randomBytes(16).toString("hex");
+}
+exports.generateSessionId = generateSessionId;
+/**
+ * Validates that an identifier looks like a valid phone number or email.
+ *
+ * @param identifier - The identifier to validate
+ * @param method - The expected delivery method
+ * @returns true if valid, false otherwise
+ */
+function validateIdentifier(identifier, method) {
+    if (!identifier || typeof identifier !== "string") {
+        return false;
+    }
+    if (method === "email") {
+        // Basic email validation
+        var emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(identifier);
+    }
+    else {
+        // Phone number validation (allow various formats)
+        // This accepts: digits, spaces, dashes, parentheses, and + prefix
+        var phoneRegex = /^\+?[\d\s\-()]{8,20}$/;
+        return phoneRegex.test(identifier);
+    }
+}
+exports.validateIdentifier = validateIdentifier;
+/**
+ * Normalizes a phone number by removing formatting characters.
+ *
+ * @param phoneNumber - The phone number to normalize
+ * @returns Normalized phone number (digits and + only)
+ */
+function normalizePhoneNumber(phoneNumber) {
+    // Remove all characters except digits and +
+    return phoneNumber.replace(/[^\d+]/g, "");
+}
+exports.normalizePhoneNumber = normalizePhoneNumber;
+/**
+ * Normalizes an email by converting to lowercase and trimming.
+ *
+ * @param email - The email to normalize
+ * @returns Normalized email
+ */
+function normalizeEmail(email) {
+    return email.toLowerCase().trim();
+}
+exports.normalizeEmail = normalizeEmail;
+/**
+ * Normalizes an identifier based on the delivery method.
+ *
+ * @param identifier - The identifier to normalize
+ * @param method - The delivery method
+ * @returns Normalized identifier
+ */
+function normalizeIdentifier(identifier, method) {
+    if (method === "email") {
+        return normalizeEmail(identifier);
+    }
+    else {
+        return normalizePhoneNumber(identifier);
+    }
+}
+exports.normalizeIdentifier = normalizeIdentifier;

package/examples/basic-usage.ts

@@ -0,0 +1,145 @@
+/**
+ * Basic OTP Auth Plugin Usage Example
+ *
+ * This example demonstrates how to set up the OTP Auth Plugin
+ * with both SMS and email support.
+ */
+
+import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { otpAuthPlugin } from "@flink-app/otp-auth-plugin";
+
+// Example: Define your context
+interface Context {
+    // Your context definition
+}
+
+async function start() {
+    const app = new FlinkApp<Context>({
+        name: "OTP Auth Example",
+
+        // JWT Auth Plugin (required)
+        auth: jwtAuthPlugin({
+            secret: process.env.JWT_SECRET || "your-secret-key",
+            getUser: async (tokenData) => {
+                // Retrieve user from database
+                const user = await app.ctx.repos.userRepo.getById(tokenData.userId);
+                return {
+                    id: user._id,
+                    username: user.username,
+                    roles: user.roles,
+                };
+            },
+            rolePermissions: {
+                user: ["read", "write"],
+                admin: ["read", "write", "delete"],
+            },
+        }),
+
+        db: {
+            uri: process.env.MONGODB_URI || "mongodb://localhost:27017/otp-example",
+        },
+
+        plugins: [
+            // OTP Auth Plugin
+            otpAuthPlugin({
+                // Configuration
+                codeLength: 6, // 6-digit code
+                codeTTL: 300, // 5 minutes
+                maxAttempts: 3, // Lock after 3 failed attempts
+
+                // Callback to send OTP code
+                onSendCode: async (code, identifier, method, payload) => {
+                    console.log(`[OTP] Sending code ${code} to ${identifier} via ${method}`);
+
+                    if (method === "sms") {
+                        // In production, use a real SMS service:
+                        // await app.ctx.plugins.sms.send({
+                        //   to: identifier,
+                        //   body: `Your verification code is: ${code}`
+                        // });
+
+                        // For demo purposes, just log
+                        console.log(`[SMS] To: ${identifier}, Code: ${code}`);
+                    } else {
+                        // In production, use a real email service:
+                        // await app.ctx.plugins.email.send({
+                        //   to: identifier,
+                        //   subject: 'Your Verification Code',
+                        //   text: `Your verification code is: ${code}`
+                        // });
+
+                        // For demo purposes, just log
+                        console.log(`[EMAIL] To: ${identifier}, Code: ${code}`);
+                    }
+
+                    return true;
+                },
+
+                // Callback to get user by identifier
+                onGetUser: async (identifier, method, payload) => {
+                    console.log(`[OTP] Getting user by ${method}: ${identifier}`);
+
+                    // Find user by phone or email
+                    if (method === "sms") {
+                        return await app.ctx.repos.userRepo.findOne({
+                            phoneNumber: identifier,
+                        });
+                    } else {
+                        return await app.ctx.repos.userRepo.findOne({
+                            email: identifier,
+                        });
+                    }
+                },
+
+                // Callback after successful verification
+                onVerifySuccess: async (user, identifier, method, payload) => {
+                    console.log(`[OTP] Verification successful for user: ${user._id}`);
+
+                    // Generate JWT token
+                    const token = await app.ctx.auth.createToken(
+                        {
+                            userId: user._id,
+                            username: user.username,
+                        },
+                        user.roles
+                    );
+
+                    // Return user and token
+                    return {
+                        user: {
+                            id: user._id,
+                            username: user.username,
+                            email: user.email,
+                            phoneNumber: user.phoneNumber,
+                        },
+                        token,
+                    };
+                },
+            }),
+        ],
+    });
+
+    await app.start();
+
+    console.log("\n=== OTP Auth Plugin Example ===");
+    console.log("API Endpoints:");
+    console.log("  POST /otp/initiate - Initiate OTP authentication");
+    console.log("  POST /otp/verify   - Verify OTP code");
+    console.log("\nExample requests:");
+    console.log('\n1. Initiate SMS OTP:');
+    console.log('   POST /otp/initiate');
+    console.log('   { "identifier": "+46701234567", "method": "sms" }');
+    console.log('\n2. Initiate Email OTP:');
+    console.log('   POST /otp/initiate');
+    console.log('   { "identifier": "user@example.com", "method": "email" }');
+    console.log('\n3. Verify OTP:');
+    console.log('   POST /otp/verify');
+    console.log('   { "sessionId": "...", "code": "123456" }');
+    console.log("\n================================\n");
+}
+
+start().catch((error) => {
+    console.error("Failed to start application:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@flink-app/otp-auth-plugin",
+    "version": "0.12.1-alpha.40",
+    "description": "Flink plugin for OTP (One-Time Password) authentication via SMS or email",
+    "scripts": {
+        "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
+        "test:watch": "nodemon --ext ts --exec 'jasmine-ts  --config=./spec/support/jasmine.json'",
+        "prepare": "tsc --project tsconfig.dist.json",
+        "watch": "tsc-watch --project tsconfig.dist.json"
+    },
+    "author": "joel@frost.se",
+    "license": "MIT",
+    "types": "dist/index.d.ts",
+    "main": "dist/index.js",
+    "publishConfig": {
+        "access": "public"
+    },
+    "peerDependencies": {
+        "mongodb": "^6.15.0"
+    },
+    "overrides": {
+        "@types/node": "22.13.10"
+    },
+    "devDependencies": {
+        "@flink-app/flink": "^0.12.1-alpha.40",
+        "@types/jasmine": "^3.7.1",
+        "@types/node": "22.13.10",
+        "jasmine": "^3.7.0",
+        "jasmine-spec-reporter": "^7.0.0",
+        "mongodb": "6.15.0",
+        "nodemon": "^2.0.7",
+        "ts-node": "^9.1.1",
+        "tsc-watch": "^4.2.9",
+        "typescript": "5.4.5"
+    },
+    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
+}

package/spec/OtpAuthPlugin.spec.ts

@@ -0,0 +1,159 @@
+/**
+ * OTP Auth Plugin Initialization Tests
+ *
+ * Tests for plugin configuration and initialization
+ */
+
+import { otpAuthPlugin } from "../src/OtpAuthPlugin";
+
+describe("OtpAuthPlugin", () => {
+    describe("Plugin Initialization", () => {
+        it("should throw error if onSendCode callback is missing", () => {
+            expect(() => {
+                otpAuthPlugin({
+                    onGetUser: async () => null,
+                    onVerifySuccess: async () => ({ user: {}, token: "" }),
+                } as any);
+            }).toThrowError(/onSendCode callback is required/);
+        });
+
+        it("should throw error if onGetUser callback is missing", () => {
+            expect(() => {
+                otpAuthPlugin({
+                    onSendCode: async () => true,
+                    onVerifySuccess: async () => ({ user: {}, token: "" }),
+                } as any);
+            }).toThrowError(/onGetUser callback is required/);
+        });
+
+        it("should throw error if onVerifySuccess callback is missing", () => {
+            expect(() => {
+                otpAuthPlugin({
+                    onSendCode: async () => true,
+                    onGetUser: async () => null,
+                } as any);
+            }).toThrowError(/onVerifySuccess callback is required/);
+        });
+
+        it("should throw error if codeLength is less than 4", () => {
+            expect(() => {
+                otpAuthPlugin({
+                    codeLength: 3,
+                    onSendCode: async () => true,
+                    onGetUser: async () => null,
+                    onVerifySuccess: async () => ({ user: {}, token: "" }),
+                });
+            }).toThrowError(/codeLength must be between 4 and 8/);
+        });
+
+        it("should throw error if codeLength is greater than 8", () => {
+            expect(() => {
+                otpAuthPlugin({
+                    codeLength: 9,
+                    onSendCode: async () => true,
+                    onGetUser: async () => null,
+                    onVerifySuccess: async () => ({ user: {}, token: "" }),
+                });
+            }).toThrowError(/codeLength must be between 4 and 8/);
+        });
+
+        it("should throw error if maxAttempts is invalid", () => {
+            // Note: maxAttempts validation happens after default is applied
+            // So 0 becomes the default 3, but we can test > 10
+            expect(() => {
+                otpAuthPlugin({
+                    maxAttempts: 11,
+                    onSendCode: async () => true,
+                    onGetUser: async () => null,
+                    onVerifySuccess: async () => ({ user: {}, token: "" }),
+                });
+            }).toThrowError(/maxAttempts must be between 1 and 10/);
+        });
+
+
+        it("should create plugin with valid configuration", () => {
+            const plugin = otpAuthPlugin({
+                codeLength: 6,
+                codeTTL: 300,
+                maxAttempts: 3,
+                onSendCode: async (code, identifier, method) => {
+                    return true;
+                },
+                onGetUser: async (identifier, method) => {
+                    return null;
+                },
+                onVerifySuccess: async (user, identifier, method) => {
+                    return { user: {}, token: "" };
+                },
+            });
+
+            expect(plugin).toBeDefined();
+            expect(plugin.id).toBe("otpAuth");
+            expect(plugin.db).toBeDefined();
+            expect(plugin.db?.useHostDb).toBe(true);
+            expect(plugin.ctx).toBeDefined();
+            expect(plugin.init).toBeDefined();
+        });
+
+        it("should use default values when optional config is omitted", () => {
+            const plugin = otpAuthPlugin({
+                onSendCode: async () => true,
+                onGetUser: async () => null,
+                onVerifySuccess: async () => ({ user: {}, token: "" }),
+            });
+
+            expect(plugin).toBeDefined();
+            // Options are frozen with original values, defaults are applied internally
+            expect(plugin.ctx.options.codeLength).toBeUndefined();
+            expect(plugin.ctx.options.codeTTL).toBeUndefined();
+            expect(plugin.ctx.options.maxAttempts).toBeUndefined();
+        });
+
+        it("should accept custom configuration values", () => {
+            const plugin = otpAuthPlugin({
+                codeLength: 4,
+                codeTTL: 600,
+                maxAttempts: 5,
+                keepSessionsSec: 3600,
+                otpSessionsCollectionName: "custom_otp",
+                registerRoutes: false,
+                onSendCode: async () => true,
+                onGetUser: async () => null,
+                onVerifySuccess: async () => ({ user: {}, token: "" }),
+            });
+
+            expect(plugin.ctx.options.codeLength).toBe(4);
+            expect(plugin.ctx.options.codeTTL).toBe(600);
+            expect(plugin.ctx.options.maxAttempts).toBe(5);
+            expect(plugin.ctx.options.keepSessionsSec).toBe(3600);
+            expect(plugin.ctx.options.otpSessionsCollectionName).toBe("custom_otp");
+            expect(plugin.ctx.options.registerRoutes).toBe(false);
+        });
+
+        it("should provide context API methods", () => {
+            const plugin = otpAuthPlugin({
+                onSendCode: async () => true,
+                onGetUser: async () => null,
+                onVerifySuccess: async () => ({ user: {}, token: "" }),
+            });
+
+            expect(plugin.ctx.initiate).toBeDefined();
+            expect(typeof plugin.ctx.initiate).toBe("function");
+            expect(plugin.ctx.verify).toBeDefined();
+            expect(typeof plugin.ctx.verify).toBe("function");
+        });
+
+        it("should freeze options object to prevent modification", () => {
+            const plugin = otpAuthPlugin({
+                codeLength: 6,
+                onSendCode: async () => true,
+                onGetUser: async () => null,
+                onVerifySuccess: async () => ({ user: {}, token: "" }),
+            });
+
+            expect(() => {
+                (plugin.ctx.options as any).codeLength = 4;
+            }).toThrow();
+        });
+    });
+});

package/spec/OtpSessionRepo.spec.ts

@@ -0,0 +1,194 @@
+import { MongoClient, Db } from "mongodb";
+import OtpSessionRepo from "../src/repos/OtpSessionRepo";
+import OtpSession from "../src/schemas/OtpSession";
+
+/**
+ * OTP Session Repository Tests
+ *
+ * Tests critical repository methods with actual MongoDB connection.
+ */
+describe("OtpSessionRepo", () => {
+    let client: MongoClient;
+    let db: Db;
+    let sessionRepo: OtpSessionRepo;
+
+    beforeAll(async () => {
+        // Connect to test database
+        const mongoUrl = process.env.TEST_MONGO_URL || "mongodb://localhost:27017";
+        client = new MongoClient(mongoUrl);
+        await client.connect();
+        db = client.db("otp_auth_plugin_test");
+
+        // Initialize repository
+        sessionRepo = new OtpSessionRepo("otp_sessions", db);
+    });
+
+    afterAll(async () => {
+        // Clean up and close connection
+        await db.dropDatabase();
+        await client.close();
+    });
+
+    afterEach(async () => {
+        // Clear collection between tests
+        await db.collection("otp_sessions").deleteMany({});
+    });
+
+    it("should create and retrieve session by sessionId", async () => {
+        // Arrange
+        const session: Omit<OtpSession, "_id"> = {
+            sessionId: "test-session-123",
+            identifier: "+46701234567",
+            method: "sms",
+            code: "123456",
+            attempts: 0,
+            maxAttempts: 3,
+            status: "pending",
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + 300000), // 5 minutes
+        };
+
+        // Act
+        const created = await sessionRepo.createSession(session);
+        const found = await sessionRepo.getSession("test-session-123");
+
+        // Assert
+        expect(created._id).toBeDefined();
+        expect(found).toBeDefined();
+        expect(found?.sessionId).toBe("test-session-123");
+        expect(found?.identifier).toBe("+46701234567");
+        expect(found?.method).toBe("sms");
+        expect(found?.code).toBe("123456");
+        expect(found?.status).toBe("pending");
+    });
+
+    it("should increment attempts counter", async () => {
+        // Arrange
+        const session: Omit<OtpSession, "_id"> = {
+            sessionId: "increment-test",
+            identifier: "user@example.com",
+            method: "email",
+            code: "654321",
+            attempts: 0,
+            maxAttempts: 3,
+            status: "pending",
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + 300000),
+        };
+        await sessionRepo.createSession(session);
+
+        // Act
+        const updated = await sessionRepo.incrementAttempts("increment-test");
+
+        // Assert
+        expect(updated).toBeDefined();
+        expect(updated?.attempts).toBe(1);
+        expect(updated?.status).toBe("pending");
+    });
+
+    it("should lock session after max attempts reached", async () => {
+        // Arrange
+        const session: Omit<OtpSession, "_id"> = {
+            sessionId: "lock-test",
+            identifier: "+46701234567",
+            method: "sms",
+            code: "111111",
+            attempts: 2,
+            maxAttempts: 3,
+            status: "pending",
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + 300000),
+        };
+        await sessionRepo.createSession(session);
+
+        // Act - increment to reach max attempts
+        const updated = await sessionRepo.incrementAttempts("lock-test");
+
+        // Assert
+        expect(updated?.attempts).toBe(3);
+        expect(updated?.status).toBe("locked");
+    });
+
+    it("should mark session as verified", async () => {
+        // Arrange
+        const session: Omit<OtpSession, "_id"> = {
+            sessionId: "verify-test",
+            identifier: "user@example.com",
+            method: "email",
+            code: "999999",
+            attempts: 1,
+            maxAttempts: 3,
+            status: "pending",
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + 300000),
+        };
+        await sessionRepo.createSession(session);
+
+        // Act
+        const updated = await sessionRepo.markAsVerified("verify-test");
+
+        // Assert
+        expect(updated).toBeDefined();
+        expect(updated?.status).toBe("verified");
+        expect(updated?.verifiedAt).toBeDefined();
+    });
+
+    it("should mark session as expired", async () => {
+        // Arrange
+        const session: Omit<OtpSession, "_id"> = {
+            sessionId: "expire-test",
+            identifier: "+46701234567",
+            method: "sms",
+            code: "888888",
+            attempts: 0,
+            maxAttempts: 3,
+            status: "pending",
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() - 1000), // Already expired
+        };
+        await sessionRepo.createSession(session);
+
+        // Act
+        const updated = await sessionRepo.markAsExpired("expire-test");
+
+        // Assert
+        expect(updated).toBeDefined();
+        expect(updated?.status).toBe("expired");
+    });
+
+    it("should return null when session not found", async () => {
+        // Act
+        const found = await sessionRepo.getSession("non-existent-session");
+
+        // Assert
+        expect(found).toBeNull();
+    });
+
+    it("should handle custom payload in session", async () => {
+        // Arrange
+        const session: Omit<OtpSession, "_id"> = {
+            sessionId: "payload-test",
+            identifier: "user@example.com",
+            method: "email",
+            code: "777777",
+            attempts: 0,
+            maxAttempts: 3,
+            status: "pending",
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + 300000),
+            payload: {
+                action: "password-reset",
+                returnUrl: "/new-password",
+            },
+        };
+
+        // Act
+        const created = await sessionRepo.createSession(session);
+        const found = await sessionRepo.getSession("payload-test");
+
+        // Assert
+        expect(found?.payload).toBeDefined();
+        expect(found?.payload?.action).toBe("password-reset");
+        expect(found?.payload?.returnUrl).toBe("/new-password");
+    });
+});