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

package/spec/otp-utils.spec.ts

@@ -0,0 +1,172 @@
+/**
+ * OTP Utils Test Suite
+ *
+ * Tests for OTP code generation, identifier validation, and normalization
+ */
+
+import {
+    generateOtpCode,
+    generateSessionId,
+    validateIdentifier,
+    normalizePhoneNumber,
+    normalizeEmail,
+    normalizeIdentifier,
+} from "../src/utils/otp-utils";
+
+describe("OTP Utils", () => {
+    describe("OTP Code Generation", () => {
+        it("should generate a 6-digit code by default", () => {
+            const code = generateOtpCode();
+
+            expect(code).toBeDefined();
+            expect(typeof code).toBe("string");
+            expect(code.length).toBe(6);
+            expect(/^\d{6}$/.test(code)).toBe(true);
+        });
+
+        it("should generate a 4-digit code", () => {
+            const code = generateOtpCode(4);
+
+            expect(code.length).toBe(4);
+            expect(/^\d{4}$/.test(code)).toBe(true);
+        });
+
+        it("should generate an 8-digit code", () => {
+            const code = generateOtpCode(8);
+
+            expect(code.length).toBe(8);
+            expect(/^\d{8}$/.test(code)).toBe(true);
+        });
+
+        it("should generate unique codes", () => {
+            const code1 = generateOtpCode();
+            const code2 = generateOtpCode();
+
+            // Very unlikely to be the same (1 in 1,000,000)
+            expect(code1).not.toBe(code2);
+        });
+
+        it("should throw error for code length < 4", () => {
+            expect(() => generateOtpCode(3)).toThrow();
+        });
+
+        it("should throw error for code length > 8", () => {
+            expect(() => generateOtpCode(9)).toThrow();
+        });
+
+        it("should generate codes within valid range", () => {
+            // 6-digit code should be between 100000 and 999999
+            for (let i = 0; i < 10; i++) {
+                const code = generateOtpCode(6);
+                const num = parseInt(code, 10);
+                expect(num).toBeGreaterThanOrEqual(100000);
+                expect(num).toBeLessThanOrEqual(999999);
+            }
+        });
+    });
+
+    describe("Session ID Generation", () => {
+        it("should generate a 32-character hex session ID", () => {
+            const sessionId = generateSessionId();
+
+            expect(sessionId).toBeDefined();
+            expect(typeof sessionId).toBe("string");
+            expect(sessionId.length).toBe(32); // 16 bytes = 32 hex chars
+            expect(/^[0-9a-f]{32}$/.test(sessionId)).toBe(true);
+        });
+
+        it("should generate unique session IDs", () => {
+            const id1 = generateSessionId();
+            const id2 = generateSessionId();
+
+            expect(id1).not.toBe(id2);
+        });
+    });
+
+    describe("Identifier Validation", () => {
+        describe("Email Validation", () => {
+            it("should validate correct email addresses", () => {
+                expect(validateIdentifier("user@example.com", "email")).toBe(true);
+                expect(validateIdentifier("test.user@company.co.uk", "email")).toBe(true);
+                expect(validateIdentifier("admin+tag@domain.org", "email")).toBe(true);
+            });
+
+            it("should reject invalid email addresses", () => {
+                expect(validateIdentifier("notanemail", "email")).toBe(false);
+                expect(validateIdentifier("missing@domain", "email")).toBe(false);
+                expect(validateIdentifier("@example.com", "email")).toBe(false);
+                expect(validateIdentifier("user@", "email")).toBe(false);
+                expect(validateIdentifier("", "email")).toBe(false);
+            });
+        });
+
+        describe("Phone Number Validation", () => {
+            it("should validate correct phone numbers", () => {
+                expect(validateIdentifier("+46701234567", "sms")).toBe(true);
+                expect(validateIdentifier("555-123-4567", "sms")).toBe(true);
+                expect(validateIdentifier("+1 (555) 123-4567", "sms")).toBe(true);
+                expect(validateIdentifier("5551234567", "sms")).toBe(true);
+            });
+
+            it("should reject invalid phone numbers", () => {
+                expect(validateIdentifier("abc", "sms")).toBe(false);
+                expect(validateIdentifier("123", "sms")).toBe(false); // Too short
+                expect(validateIdentifier("", "sms")).toBe(false);
+                expect(validateIdentifier("12345678901234567890123", "sms")).toBe(false); // Too long
+            });
+        });
+
+        it("should reject null/undefined identifiers", () => {
+            expect(validateIdentifier(null as any, "email")).toBe(false);
+            expect(validateIdentifier(undefined as any, "email")).toBe(false);
+            expect(validateIdentifier(null as any, "sms")).toBe(false);
+            expect(validateIdentifier(undefined as any, "sms")).toBe(false);
+        });
+    });
+
+    describe("Phone Number Normalization", () => {
+        it("should remove formatting characters from phone numbers", () => {
+            expect(normalizePhoneNumber("+1 (555) 123-4567")).toBe("+15551234567");
+            expect(normalizePhoneNumber("555-123-4567")).toBe("5551234567");
+            expect(normalizePhoneNumber("+46 70 123 45 67")).toBe("+46701234567");
+        });
+
+        it("should preserve + prefix", () => {
+            expect(normalizePhoneNumber("+46701234567")).toBe("+46701234567");
+            expect(normalizePhoneNumber("+1234567890")).toBe("+1234567890");
+        });
+
+        it("should handle already normalized numbers", () => {
+            expect(normalizePhoneNumber("5551234567")).toBe("5551234567");
+            expect(normalizePhoneNumber("+15551234567")).toBe("+15551234567");
+        });
+    });
+
+    describe("Email Normalization", () => {
+        it("should convert email to lowercase", () => {
+            expect(normalizeEmail("User@Example.COM")).toBe("user@example.com");
+            expect(normalizeEmail("ADMIN@COMPANY.ORG")).toBe("admin@company.org");
+        });
+
+        it("should trim whitespace", () => {
+            expect(normalizeEmail("  user@example.com  ")).toBe("user@example.com");
+            expect(normalizeEmail("user@example.com\n")).toBe("user@example.com");
+        });
+
+        it("should handle already normalized emails", () => {
+            expect(normalizeEmail("user@example.com")).toBe("user@example.com");
+        });
+    });
+
+    describe("Identifier Normalization", () => {
+        it("should normalize email identifiers", () => {
+            expect(normalizeIdentifier("User@Example.COM", "email")).toBe("user@example.com");
+            expect(normalizeIdentifier("  test@domain.org  ", "email")).toBe("test@domain.org");
+        });
+
+        it("should normalize phone identifiers", () => {
+            expect(normalizeIdentifier("+1 (555) 123-4567", "sms")).toBe("+15551234567");
+            expect(normalizeIdentifier("555-123-4567", "sms")).toBe("5551234567");
+        });
+    });
+});

package/spec/support/jasmine.json

@@ -0,0 +1,7 @@
+{
+  "spec_dir": "spec",
+  "spec_files": ["**/*[sS]pec.ts"],
+  "helpers": ["helpers/**/*.ts"],
+  "stopSpecOnExpectationFailure": false,
+  "random": true
+}

package/src/OtpAuthPlugin.ts

@@ -0,0 +1,163 @@
+import { FlinkApp, FlinkPlugin, log } from "@flink-app/flink";
+import { Db } from "mongodb";
+import { initiate } from "./functions/initiate";
+import { verify } from "./functions/verify";
+import * as PostOtpInitiate from "./handlers/PostOtpInitiate";
+import * as PostOtpVerify from "./handlers/PostOtpVerify";
+import { OtpAuthPluginContext } from "./OtpAuthPluginContext";
+import { OtpAuthPluginOptions } from "./OtpAuthPluginOptions";
+import { OtpInternalContext } from "./OtpInternalContext";
+import OtpSessionRepo from "./repos/OtpSessionRepo";
+
+/**
+ * OTP Auth Plugin Factory Function
+ *
+ * Creates a Flink plugin for OTP (One-Time Password) authentication via SMS or email.
+ * Integrates with JWT Auth Plugin for token generation.
+ *
+ * @param options - OTP auth plugin configuration options
+ * @returns FlinkPlugin instance
+ *
+ * @example
+ * ```typescript
+ * import { jwtAuthPlugin } from '@flink-app/jwt-auth-plugin';
+ * import { otpAuthPlugin } from '@flink-app/otp-auth-plugin';
+ *
+ * const app = new FlinkApp({
+ *   auth: jwtAuthPlugin({
+ *     secret: process.env.JWT_SECRET!,
+ *     getUser: async (tokenData) => {
+ *       return ctx.repos.userRepo.getById(tokenData.userId);
+ *     },
+ *     rolePermissions: {
+ *       user: ['read', 'write']
+ *     }
+ *   }),
+ *
+ *   plugins: [
+ *     otpAuthPlugin({
+ *       codeLength: 6,
+ *       codeTTL: 300, // 5 minutes
+ *       maxAttempts: 3,
+ *       onSendCode: async (code, identifier, method) => {
+ *         if (method === 'sms') {
+ *           await ctx.plugins.sms.send(identifier, `Your code: ${code}`);
+ *         } else {
+ *           await ctx.plugins.email.send({
+ *             to: identifier,
+ *             subject: 'Your verification code',
+ *             text: `Your code: ${code}`
+ *           });
+ *         }
+ *         return true;
+ *       },
+ *       onGetUser: async (identifier, method) => {
+ *         if (method === 'sms') {
+ *           return await ctx.repos.userRepo.findOne({ phoneNumber: identifier });
+ *         } else {
+ *           return await ctx.repos.userRepo.findOne({ email: identifier });
+ *         }
+ *       },
+ *       onVerifySuccess: async (user, identifier, method) => {
+ *         const token = await ctx.auth.createToken(
+ *           { userId: user._id, email: user.email },
+ *           user.roles
+ *         );
+ *         return { user, token };
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export function otpAuthPlugin(options: OtpAuthPluginOptions): FlinkPlugin {
+    // Validation
+    if (!options.onSendCode) {
+        throw new Error("OTP Auth Plugin: onSendCode callback is required");
+    }
+
+    if (!options.onGetUser) {
+        throw new Error("OTP Auth Plugin: onGetUser callback is required");
+    }
+
+    if (!options.onVerifySuccess) {
+        throw new Error("OTP Auth Plugin: onVerifySuccess callback is required");
+    }
+
+    // Validate code length
+    const codeLength = options.codeLength || 6;
+    if (codeLength < 4 || codeLength > 8) {
+        throw new Error("OTP Auth Plugin: codeLength must be between 4 and 8");
+    }
+
+    // Validate code TTL
+    const codeTTL = options.codeTTL || 300;
+    if (codeTTL < 30 || codeTTL > 3600) {
+        log.warn("OTP Auth Plugin: codeTTL should be between 30 and 3600 seconds for security");
+    }
+
+    // Validate max attempts
+    const maxAttempts = options.maxAttempts || 3;
+    if (maxAttempts < 1 || maxAttempts > 10) {
+        throw new Error("OTP Auth Plugin: maxAttempts must be between 1 and 10");
+    }
+
+    let flinkApp: FlinkApp<OtpInternalContext>;
+    let sessionRepo: OtpSessionRepo;
+
+    /**
+     * Plugin initialization
+     */
+    async function init(app: FlinkApp<any>, db?: Db) {
+        log.info("Initializing OTP Auth Plugin...");
+
+        flinkApp = app as FlinkApp<OtpInternalContext>;
+
+        try {
+            if (!db) {
+                throw new Error("OTP Auth Plugin: Database connection is required");
+            }
+
+            // Initialize repository
+            const collectionName = options.otpSessionsCollectionName || "otp_sessions";
+            sessionRepo = new OtpSessionRepo(collectionName, db);
+
+            flinkApp.addRepo("otpSessionRepo", sessionRepo);
+
+            // Create TTL index for automatic session cleanup
+            const keepSessionsSec = options.keepSessionsSec || 86400; // Default 24 hours
+            await sessionRepo.ensureExpiringIndex(keepSessionsSec);
+
+            // Register OTP handlers
+            // Only register handlers if registerRoutes is enabled (default: true)
+            if (options.registerRoutes !== false) {
+                flinkApp.addHandler(PostOtpInitiate);
+                flinkApp.addHandler(PostOtpVerify);
+                log.info("OTP Auth Plugin: Registered HTTP endpoints");
+            }
+
+            log.info(`OTP Auth Plugin initialized (codeLength: ${codeLength}, codeTTL: ${codeTTL}s, maxAttempts: ${maxAttempts})`);
+        } catch (error) {
+            log.error("Failed to initialize OTP Auth Plugin:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Plugin context exposed via ctx.plugins.otpAuth
+     */
+    const pluginCtx: OtpAuthPluginContext["otpAuth"] = {
+        options: Object.freeze({ ...options }),
+        initiate: (initiateOptions) => initiate(flinkApp.ctx as OtpInternalContext, initiateOptions),
+        verify: (verifyOptions) => verify(flinkApp.ctx as OtpInternalContext, verifyOptions),
+    };
+
+    return {
+        id: "otpAuth",
+        db: {
+            useHostDb: true,
+        },
+        ctx: pluginCtx,
+        init,
+    };
+}

package/src/OtpAuthPluginContext.ts

@@ -0,0 +1,11 @@
+import { OtpAuthPluginOptions } from "./OtpAuthPluginOptions";
+import { InitiateOptions, InitiateResponse } from "./functions/initiate";
+import { VerifyOptions, VerifyResponse } from "./functions/verify";
+
+export interface OtpAuthPluginContext {
+    otpAuth: {
+        options: OtpAuthPluginOptions;
+        initiate: (options: InitiateOptions) => Promise<InitiateResponse>;
+        verify: (options: VerifyOptions) => Promise<VerifyResponse>;
+    };
+}

package/src/OtpAuthPluginOptions.ts

@@ -0,0 +1,135 @@
+export interface AuthSuccessCallbackResponse {
+    user: any;
+    token: string;
+}
+
+export interface OtpAuthPluginOptions {
+    /**
+     * Number of digits in the OTP code (4-8).
+     * Default is 6.
+     */
+    codeLength?: number;
+
+    /**
+     * How long the OTP code is valid in seconds.
+     * Default is 300 (5 minutes).
+     */
+    codeTTL?: number;
+
+    /**
+     * Maximum number of verification attempts before session is locked.
+     * Default is 3.
+     */
+    maxAttempts?: number;
+
+    /**
+     * Callback to send the OTP code via SMS or email.
+     * Should return true if sending succeeded, false otherwise.
+     *
+     * @param code - The OTP code to send
+     * @param identifier - The user identifier (phone number or email)
+     * @param method - The delivery method ('sms' or 'email')
+     * @param payload - Optional custom payload from initiation
+     * @returns Promise that resolves to true if sent successfully
+     *
+     * @example
+     * ```typescript
+     * onSendCode: async (code, identifier, method, payload) => {
+     *   if (method === 'sms') {
+     *     await ctx.plugins.sms.send(identifier, `Your code is: ${code}`);
+     *   } else {
+     *     await ctx.plugins.email.send({
+     *       to: identifier,
+     *       subject: 'Your verification code',
+     *       text: `Your code is: ${code}`
+     *     });
+     *   }
+     *   return true;
+     * }
+     * ```
+     */
+    onSendCode: (
+        code: string,
+        identifier: string,
+        method: "sms" | "email",
+        payload?: Record<string, any>
+    ) => Promise<boolean>;
+
+    /**
+     * Callback to retrieve user by identifier (phone number or email).
+     * Return null if user is not found.
+     *
+     * @param identifier - The user identifier (phone number or email)
+     * @param method - The delivery method ('sms' or 'email')
+     * @param payload - Optional custom payload from initiation
+     * @returns Promise that resolves to user object or null
+     *
+     * @example
+     * ```typescript
+     * onGetUser: async (identifier, method) => {
+     *   if (method === 'sms') {
+     *     return await ctx.repos.userRepo.findOne({ phoneNumber: identifier });
+     *   } else {
+     *     return await ctx.repos.userRepo.findOne({ email: identifier });
+     *   }
+     * }
+     * ```
+     */
+    onGetUser: (
+        identifier: string,
+        method: "sms" | "email",
+        payload?: Record<string, any>
+    ) => Promise<any | null>;
+
+    /**
+     * Callback invoked when OTP verification is successful.
+     * Must return user object and JWT token.
+     *
+     * @param user - The user object returned from onGetUser
+     * @param identifier - The user identifier (phone number or email)
+     * @param method - The delivery method ('sms' or 'email')
+     * @param payload - Optional custom payload from initiation
+     * @returns Promise that resolves to user and token
+     *
+     * @example
+     * ```typescript
+     * onVerifySuccess: async (user, identifier, method, payload) => {
+     *   const token = await ctx.auth.createToken(
+     *     { userId: user._id, email: user.email },
+     *     user.roles
+     *   );
+     *   return { user, token };
+     * }
+     * ```
+     */
+    onVerifySuccess: (
+        user: any,
+        identifier: string,
+        method: "sms" | "email",
+        payload?: Record<string, any>
+    ) => Promise<AuthSuccessCallbackResponse>;
+
+    /**
+     * For how long to keep sessions in database (in seconds).
+     * This is for data retention purposes only.
+     *
+     * An expiring index will be created in the database to automatically
+     * remove old sessions based on this.
+     *
+     * Default is 86400 (24 hours).
+     */
+    keepSessionsSec?: number;
+
+    /**
+     * The name of the MongoDB collection to use for storing OTP sessions.
+     * Default is "otp_sessions".
+     */
+    otpSessionsCollectionName?: string;
+
+    /**
+     * Whether to register the default HTTP routes for OTP operations.
+     * If false, you'll need to implement your own handlers using the functions.
+     * Default is true.
+     */
+    registerRoutes?: boolean;
+}

package/src/OtpInternalContext.ts

@@ -0,0 +1,12 @@
+import { FlinkContext } from "@flink-app/flink";
+import { OtpAuthPluginContext } from "./OtpAuthPluginContext";
+import OtpSessionRepo from "./repos/OtpSessionRepo";
+
+export interface OtpInternalContext extends FlinkContext {
+    plugins: {
+        otpAuth: OtpAuthPluginContext["otpAuth"];
+    };
+    repos: {
+        otpSessionRepo: OtpSessionRepo;
+    };
+}

package/src/functions/initiate.ts

@@ -0,0 +1,86 @@
+import { badRequest, log } from "@flink-app/flink";
+import { OtpInternalContext } from "../OtpInternalContext";
+import { generateOtpCode, generateSessionId, normalizeIdentifier, validateIdentifier } from "../utils/otp-utils";
+import OtpSession from "../schemas/OtpSession";
+
+export interface InitiateOptions {
+    /** User identifier (phone number or email) */
+    identifier: string;
+    /** Delivery method for the OTP code */
+    method: "sms" | "email";
+    /** Optional custom payload to attach to the session */
+    payload?: Record<string, any>;
+}
+
+export interface InitiateResponse {
+    /** Unique session ID for this OTP session */
+    sessionId: string;
+    /** When the code expires */
+    expiresAt: Date;
+    /** Time-to-live in seconds */
+    ttl: number;
+}
+
+export async function initiate(ctx: OtpInternalContext, options: InitiateOptions): Promise<InitiateResponse> {
+    const { identifier, method, payload } = options;
+    const { options: pluginOptions } = ctx.plugins.otpAuth;
+
+    // Validate identifier format
+    if (!validateIdentifier(identifier, method)) {
+        log.warn(`Invalid identifier format for method ${method}: ${identifier}`);
+        throw badRequest(`Invalid ${method === "email" ? "email address" : "phone number"} format`);
+    }
+
+    // Normalize identifier (lowercase email, remove phone formatting)
+    const normalizedIdentifier = normalizeIdentifier(identifier, method);
+
+    // Generate OTP code
+    const codeLength = pluginOptions.codeLength || 6;
+    if (codeLength < 4 || codeLength > 8) {
+        throw new Error("OTP code length must be between 4 and 8 digits");
+    }
+
+    const code = generateOtpCode(codeLength);
+    const sessionId = generateSessionId();
+
+    // Calculate expiration
+    const codeTTL = pluginOptions.codeTTL || 300; // Default 5 minutes
+    const expiresAt = new Date(Date.now() + codeTTL * 1000);
+
+    // Create session
+    const session: Omit<OtpSession, "_id"> = {
+        sessionId,
+        identifier: normalizedIdentifier,
+        method,
+        code,
+        attempts: 0,
+        maxAttempts: pluginOptions.maxAttempts || 3,
+        status: "pending",
+        createdAt: new Date(),
+        expiresAt,
+        payload,
+    };
+
+    await ctx.repos.otpSessionRepo.createSession(session);
+
+    // Send the code via callback
+    try {
+        const sent = await pluginOptions.onSendCode(code, normalizedIdentifier, method, payload);
+
+        if (!sent) {
+            log.error(`Failed to send OTP code to ${normalizedIdentifier} via ${method}`);
+            throw new Error("Failed to send verification code");
+        }
+
+        log.info(`OTP code sent to ${normalizedIdentifier} via ${method} (session: ${sessionId})`);
+    } catch (error) {
+        log.error(`Error sending OTP code: ${error}`);
+        throw new Error("Failed to send verification code");
+    }
+
+    return {
+        sessionId,
+        expiresAt,
+        ttl: codeTTL,
+    };
+}