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

package/src/functions/verify.ts

@@ -0,0 +1,123 @@
+import { badRequest, log, notFound } from "@flink-app/flink";
+import { OtpInternalContext } from "../OtpInternalContext";
+
+export interface VerifyOptions {
+    /** The session ID from the initiate response */
+    sessionId: string;
+    /** The OTP code entered by the user */
+    code: string;
+}
+
+export interface VerifyResponse {
+    /** Verification status */
+    status: "success" | "invalid_code" | "expired" | "locked" | "not_found";
+    /** JWT token if successful */
+    token?: string;
+    /** User object if successful */
+    user?: any;
+    /** Remaining attempts if code was invalid */
+    remainingAttempts?: number;
+    /** Error message */
+    message?: string;
+}
+
+export async function verify(ctx: OtpInternalContext, options: VerifyOptions): Promise<VerifyResponse> {
+    const { sessionId, code } = options;
+    const { options: pluginOptions } = ctx.plugins.otpAuth;
+
+    // Validate input
+    if (!sessionId || !code) {
+        throw badRequest("Session ID and code are required");
+    }
+
+    // Find session
+    const session = await ctx.repos.otpSessionRepo.getSession(sessionId);
+
+    if (!session) {
+        log.warn(`OTP session not found: ${sessionId}`);
+        return {
+            status: "not_found",
+            message: "Session not found or expired",
+        };
+    }
+
+    // Check if session is already verified
+    if (session.status === "verified") {
+        log.warn(`Attempt to verify already verified session: ${sessionId}`);
+        throw badRequest("Session already verified");
+    }
+
+    // Check if session is locked
+    if (session.status === "locked") {
+        log.warn(`Attempt to verify locked session: ${sessionId}`);
+        return {
+            status: "locked",
+            message: "Too many failed attempts. Session is locked.",
+        };
+    }
+
+    // Check if session has expired
+    if (session.status === "expired" || new Date() > session.expiresAt) {
+        if (session.status !== "expired") {
+            await ctx.repos.otpSessionRepo.markAsExpired(sessionId);
+        }
+        log.warn(`Attempt to verify expired session: ${sessionId}`);
+        return {
+            status: "expired",
+            message: "Verification code has expired",
+        };
+    }
+
+    // Verify the code
+    const codeMatches = session.code === code;
+
+    if (!codeMatches) {
+        // Increment attempts
+        const updatedSession = await ctx.repos.otpSessionRepo.incrementAttempts(sessionId);
+
+        const remainingAttempts = updatedSession!.maxAttempts - updatedSession!.attempts;
+
+        log.warn(`Invalid OTP code for session ${sessionId}. Remaining attempts: ${remainingAttempts}`);
+
+        if (updatedSession!.status === "locked") {
+            return {
+                status: "locked",
+                message: "Too many failed attempts. Session is locked.",
+                remainingAttempts: 0,
+            };
+        }
+
+        return {
+            status: "invalid_code",
+            message: "Invalid verification code",
+            remainingAttempts,
+        };
+    }
+
+    // Code is valid - mark session as verified
+    await ctx.repos.otpSessionRepo.markAsVerified(sessionId);
+
+    // Get user via callback
+    const user = await pluginOptions.onGetUser(session.identifier, session.method, session.payload);
+
+    if (!user) {
+        log.error(`User not found for identifier ${session.identifier} after successful OTP verification`);
+        throw notFound("User not found");
+    }
+
+    // Generate token via callback
+    try {
+        const authResult = await pluginOptions.onVerifySuccess(user, session.identifier, session.method, session.payload);
+
+        log.info(`OTP verification successful for session ${sessionId}, identifier: ${session.identifier}`);
+
+        return {
+            status: "success",
+            token: authResult.token,
+            user: authResult.user,
+        };
+    } catch (error) {
+        log.error(`Error in onVerifySuccess callback: ${error}`);
+        throw new Error("Failed to complete authentication");
+    }
+}

package/src/handlers/PostOtpInitiate.ts

@@ -0,0 +1,28 @@
+import { Handler, HttpMethod, RouteProps, internalServerError } from "@flink-app/flink";
+import InitiateRequest from "../schemas/InitiateRequest";
+import InitiateResponse from "../schemas/InitiateResponse";
+import { OtpInternalContext } from "../OtpInternalContext";
+import { initiate } from "../functions/initiate";
+
+export const Route: RouteProps = {
+    path: "/otp/initiate",
+    method: HttpMethod.post,
+};
+
+const PostOtpInitiate: Handler<OtpInternalContext, InitiateRequest, InitiateResponse> = async ({ ctx, req }) => {
+    try {
+        const response = await initiate(ctx, {
+            identifier: req.body.identifier,
+            method: req.body.method,
+            payload: req.body.payload,
+        });
+
+        return {
+            data: response,
+        };
+    } catch (error: any) {
+        return internalServerError(error.message || "Failed to initiate OTP authentication");
+    }
+};
+
+export default PostOtpInitiate;

package/src/handlers/PostOtpVerify.ts

@@ -0,0 +1,42 @@
+import { Handler, HttpMethod, RouteProps } from "@flink-app/flink";
+import { OtpInternalContext } from "../OtpInternalContext";
+import { verify } from "../functions/verify";
+import VerifyRequest from "../schemas/VerifyRequest";
+import VerifyResponse from "../schemas/VerifyResponse";
+
+export const Route: RouteProps = {
+    path: "/otp/verify",
+    method: HttpMethod.post,
+};
+
+const PostOtpVerify: Handler<OtpInternalContext, VerifyRequest, VerifyResponse> = async ({ ctx, req }) => {
+    const response = await verify(ctx, {
+        sessionId: req.body.sessionId,
+        code: req.body.code,
+    });
+
+    // Return appropriate HTTP status based on verification result
+    if (response.status === "success") {
+        return {
+            data: response,
+        };
+    } else if (response.status === "not_found") {
+        return {
+            status: 404,
+            data: response,
+        };
+    } else if (response.status === "locked" || response.status === "expired") {
+        return {
+            status: 403,
+            data: response,
+        };
+    } else {
+        // invalid_code
+        return {
+            status: 401,
+            data: response,
+        };
+    }
+};
+
+export default PostOtpVerify;

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./OtpAuthPlugin";
+export * from "./OtpAuthPluginContext";
+export * from "./OtpAuthPluginOptions";
+
+// Functions
+export * from "./functions/initiate";
+export * from "./functions/verify";
+
+// Schemas
+export type { default as OtpSession } from "./schemas/OtpSession";
+export type { default as InitiateRequest } from "./schemas/InitiateRequest";
+export type { default as InitiateResponse } from "./schemas/InitiateResponse";
+export type { default as VerifyRequest } from "./schemas/VerifyRequest";
+export type { default as VerifyResponse } from "./schemas/VerifyResponse";
+
+// Utils
+export * from "./utils/otp-utils";

package/src/repos/OtpSessionRepo.ts

@@ -0,0 +1,47 @@
+import { FlinkRepo, log } from "@flink-app/flink";
+import OtpSession from "../schemas/OtpSession";
+
+class OtpSessionRepo extends FlinkRepo<any, OtpSession> {
+    async getSession(sessionId: string) {
+        return this.getOne({ sessionId });
+    }
+
+    async createSession(session: Omit<OtpSession, "_id">) {
+        return await this.create(session);
+    }
+
+    async incrementAttempts(sessionId: string) {
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            throw new Error("Session not found");
+        }
+
+        const newAttempts = session.attempts + 1;
+        const newStatus = newAttempts >= session.maxAttempts ? "locked" : session.status;
+
+        await this.collection.updateOne({ sessionId }, { $set: { attempts: newAttempts, status: newStatus } });
+
+        return this.getSession(sessionId);
+    }
+
+    async markAsVerified(sessionId: string) {
+        await this.collection.updateOne({ sessionId }, { $set: { status: "verified", verifiedAt: new Date() } });
+        return this.getSession(sessionId);
+    }
+
+    async markAsExpired(sessionId: string) {
+        await this.collection.updateOne({ sessionId }, { $set: { status: "expired" } });
+        return this.getSession(sessionId);
+    }
+
+    async ensureExpiringIndex(ttlSec: number) {
+        try {
+            await this.collection.createIndex({ createdAt: 1 }, { expireAfterSeconds: ttlSec });
+            log.info(`OTP Auth Plugin: Created TTL index with ${ttlSec}s expiration`);
+        } catch (err) {
+            log.error("Error creating expiring index for OTP sessions:", err);
+        }
+    }
+}
+
+export default OtpSessionRepo;

package/src/schemas/InitiateRequest.ts

@@ -0,0 +1,8 @@
+export default interface InitiateRequest {
+    /** 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>;
+}

package/src/schemas/InitiateResponse.ts

@@ -0,0 +1,8 @@
+export default interface InitiateResponse {
+    /** Unique session ID for this OTP session */
+    sessionId: string;
+    /** When the code expires */
+    expiresAt: Date;
+    /** Time-to-live in seconds */
+    ttl: number;
+}

package/src/schemas/OtpSession.ts

@@ -0,0 +1,25 @@
+export default interface OtpSession {
+    _id?: string;
+    /** Unique identifier for the OTP session */
+    sessionId: string;
+    /** User identifier (phone number, email, or user ID) */
+    identifier: string;
+    /** The delivery method for this session */
+    method: "sms" | "email";
+    /** The generated OTP code */
+    code: string;
+    /** Number of verification attempts made */
+    attempts: number;
+    /** Maximum allowed attempts before session is locked */
+    maxAttempts: number;
+    /** Session status */
+    status: "pending" | "verified" | "expired" | "locked";
+    /** When the session was created */
+    createdAt: Date;
+    /** When the session expires */
+    expiresAt: Date;
+    /** When the session was verified (if verified) */
+    verifiedAt?: Date;
+    /** Optional custom payload passed during initiation */
+    payload?: Record<string, any>;
+}

package/src/schemas/VerifyRequest.ts

@@ -0,0 +1,6 @@
+export default interface VerifyRequest {
+    /** The session ID from the initiate response */
+    sessionId: string;
+    /** The OTP code entered by the user */
+    code: string;
+}

package/src/schemas/VerifyResponse.ts

@@ -0,0 +1,12 @@
+export default interface VerifyResponse {
+    /** Verification status */
+    status: "success" | "invalid_code" | "expired" | "locked" | "not_found";
+    /** JWT token if successful */
+    token?: string;
+    /** User object if successful */
+    user?: any;
+    /** Remaining attempts if code was invalid */
+    remainingAttempts?: number;
+    /** Error message */
+    message?: string;
+}

package/src/utils/otp-utils.ts

@@ -0,0 +1,89 @@
+import crypto from "crypto";
+
+/**
+ * Generates a random numeric OTP code.
+ *
+ * @param length - Number of digits (4-8)
+ * @returns A numeric string of the specified length
+ */
+export function generateOtpCode(length: number = 6): string {
+    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
+    const min = Math.pow(10, length - 1);
+    const max = Math.pow(10, length) - 1;
+
+    // Use crypto.randomInt for cryptographically secure random numbers
+    return crypto.randomInt(min, max + 1).toString();
+}
+
+/**
+ * Generates a unique session ID.
+ *
+ * @returns A cryptographically secure random hex string
+ */
+export function generateSessionId(): string {
+    return crypto.randomBytes(16).toString("hex");
+}
+
+/**
+ * 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
+ */
+export function validateIdentifier(identifier: string, method: "sms" | "email"): boolean {
+    if (!identifier || typeof identifier !== "string") {
+        return false;
+    }
+
+    if (method === "email") {
+        // Basic email validation
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(identifier);
+    } else {
+        // Phone number validation (allow various formats)
+        // This accepts: digits, spaces, dashes, parentheses, and + prefix
+        const phoneRegex = /^\+?[\d\s\-()]{8,20}$/;
+        return phoneRegex.test(identifier);
+    }
+}
+
+/**
+ * Normalizes a phone number by removing formatting characters.
+ *
+ * @param phoneNumber - The phone number to normalize
+ * @returns Normalized phone number (digits and + only)
+ */
+export function normalizePhoneNumber(phoneNumber: string): string {
+    // Remove all characters except digits and +
+    return phoneNumber.replace(/[^\d+]/g, "");
+}
+
+/**
+ * Normalizes an email by converting to lowercase and trimming.
+ *
+ * @param email - The email to normalize
+ * @returns Normalized email
+ */
+export function normalizeEmail(email: string): string {
+    return email.toLowerCase().trim();
+}
+
+/**
+ * Normalizes an identifier based on the delivery method.
+ *
+ * @param identifier - The identifier to normalize
+ * @param method - The delivery method
+ * @returns Normalized identifier
+ */
+export function normalizeIdentifier(identifier: string, method: "sms" | "email"): string {
+    if (method === "email") {
+        return normalizeEmail(identifier);
+    } else {
+        return normalizePhoneNumber(identifier);
+    }
+}

package/tsconfig.dist.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig",
+  "exclude": ["spec/**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["esnext", "es2016"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "checkJs": true,
+    "outDir": "dist",
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "include": ["./src/*", "./spec/*"],
+  "exclude": ["./node_modules/*"]
+}