@xenterprises/fastify-xauth-local 1.0.0

package/src/routes/local.js

@@ -0,0 +1,531 @@
+/**
+ * Local Authentication Routes
+ *
+ * Provides local authentication endpoints: login, me, register, password-reset
+ * Compatible with existing frontend patterns.
+ */
+
+import bcrypt from "bcryptjs";
+
+/**
+ * Default user lookup - should be overridden
+ */
+const defaultUserLookup = async () => {
+  throw new Error("xAuthLocal: userLookup function not configured");
+};
+
+/**
+ * Default user creation - should be overridden
+ */
+const defaultCreateUser = async () => {
+  throw new Error("xAuthLocal: createUser function not configured");
+};
+
+/**
+ * Default password reset - should be overridden
+ */
+const defaultPasswordReset = async () => {
+  throw new Error("xAuthLocal: passwordReset function not configured");
+};
+
+/**
+ * Create local auth routes plugin
+ *
+ * @param {Object} options - Route options
+ * @param {Function} options.jwtService - JWT service instance
+ * @param {Function} [options.userLookup] - Function to lookup user by email
+ * @param {Function} [options.createUser] - Function to create new user
+ * @param {Function} [options.passwordReset] - Function to handle password reset
+ * @param {string} [options.prefix] - Route prefix (default: '/local')
+ * @param {number} [options.saltRounds] - bcrypt salt rounds (default: 10)
+ * @param {boolean} [options.skipUserLookup] - Skip userLookup for /me, use token data only
+ * @param {string} [options.requestProperty] - Property where auth is attached (default: 'auth')
+ * @returns {Function} Fastify plugin
+ */
+export function createLocalRoutes(options = {}) {
+  const {
+    jwtService,
+    userLookup = defaultUserLookup,
+    createUser = defaultCreateUser,
+    passwordReset = defaultPasswordReset,
+    saltRounds = 10,
+    skipUserLookup = false,
+    requestProperty = "auth",
+  } = options;
+
+  if (!jwtService) {
+    throw new Error("xAuthLocal: jwtService is required for local routes");
+  }
+
+  return async function localRoutesPlugin(fastify) {
+    /**
+     * POST /local - Login
+     *
+     * Authenticates user with email/password and returns JWT token
+     */
+    fastify.post(
+      "/",
+      {
+        schema: {
+          description: "Authenticate user and get JWT token",
+          tags: ["auth"],
+          body: {
+            type: "object",
+            required: ["email", "password"],
+            properties: {
+              email: { type: "string", format: "email" },
+              password: { type: "string", minLength: 1 },
+            },
+          },
+          response: {
+            200: {
+              type: "object",
+              properties: {
+                token: { type: "string" },
+                user: {
+                  type: "object",
+                  properties: {
+                    id: { type: ["string", "integer"] },
+                    email: { type: "string" },
+                    first_name: { type: "string" },
+                    last_name: { type: "string" },
+                    admin: { type: "boolean" },
+                    color: { type: "string" },
+                    scope: {
+                      oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+                    },
+                  },
+                },
+              },
+            },
+            401: {
+              type: "object",
+              properties: {
+                statusCode: { type: "integer" },
+                error: { type: "string" },
+                message: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+      async (request, reply) => {
+        const { email, password } = request.body;
+
+        try {
+          // Look up user by email
+          const user = await userLookup(email);
+
+          if (!user) {
+            return reply.code(401).send({
+              statusCode: 401,
+              error: "Unauthorized",
+              message: "Invalid email or password",
+            });
+          }
+
+          // Verify password
+          const passwordValid = await bcrypt.compare(password, user.password);
+
+          if (!passwordValid) {
+            return reply.code(401).send({
+              statusCode: 401,
+              error: "Unauthorized",
+              message: "Invalid email or password",
+            });
+          }
+
+          // Create JWT payload (excluding password)
+          const payload = {
+            id: user.id,
+            first_name: user.first_name,
+            last_name: user.last_name,
+            email: user.email,
+            admin: user.admin || false,
+            color: user.color,
+            scope: user.scope || user.roles || [],
+          };
+
+          // Sign token
+          const token = jwtService.sign(payload, {
+            subject: String(user.id),
+          });
+
+          // Return token and user info (without password)
+          const { password: _, ...safeUser } = user;
+
+          return {
+            token,
+            user: {
+              id: safeUser.id,
+              email: safeUser.email,
+              first_name: safeUser.first_name,
+              last_name: safeUser.last_name,
+              admin: safeUser.admin || false,
+              color: safeUser.color,
+              scope: safeUser.scope || safeUser.roles || [],
+            },
+          };
+        } catch (error) {
+          request.log.error(error, "Login error");
+          return reply.code(500).send({
+            statusCode: 500,
+            error: "Internal Server Error",
+            message: "An error occurred during login",
+          });
+        }
+      }
+    );
+
+    /**
+     * GET /local/me - Get current user
+     *
+     * Returns the current authenticated user's information
+     * Requires authentication (request[requestProperty] must be set)
+     * If skipUserLookup is true, returns data from token only
+     * Otherwise, can optionally fetch fresh user data from database
+     */
+    fastify.get(
+      "/me",
+      {
+        schema: {
+          description: "Get current authenticated user",
+          tags: ["auth"],
+          response: {
+            200: {
+              type: "object",
+              properties: {
+                id: { type: ["string", "integer"] },
+                email: { type: "string" },
+                first_name: { type: "string" },
+                last_name: { type: "string" },
+                admin: { type: "boolean" },
+                color: { type: "string" },
+                scope: {
+                  oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+                },
+              },
+            },
+            401: {
+              type: "object",
+              properties: {
+                statusCode: { type: "integer" },
+                error: { type: "string" },
+                message: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+      async (request, reply) => {
+        // Auth middleware should have set request[requestProperty]
+        const auth = request[requestProperty];
+
+        if (!auth) {
+          return reply.code(401).send({
+            statusCode: 401,
+            error: "Unauthorized",
+            message: "Authentication required",
+          });
+        }
+
+        // If skipUserLookup is true, return data from token only
+        if (skipUserLookup) {
+          return {
+            id: auth.id,
+            email: auth.email,
+            first_name: auth.first_name,
+            last_name: auth.last_name,
+            admin: auth.admin || false,
+            color: auth.color,
+            scope: auth.scope || [],
+          };
+        }
+
+        // Otherwise, try to fetch fresh user data if userLookup is configured
+        try {
+          const user = await userLookup(auth.email);
+
+          if (user) {
+            return {
+              id: user.id,
+              email: user.email,
+              first_name: user.first_name,
+              last_name: user.last_name,
+              admin: user.admin || false,
+              color: user.color,
+              scope: user.scope || user.roles || [],
+            };
+          }
+        } catch (error) {
+          // If userLookup fails, fall back to token data
+          request.log.debug(error, "userLookup failed, using token data");
+        }
+
+        // Fall back to token data
+        return {
+          id: auth.id,
+          email: auth.email,
+          first_name: auth.first_name,
+          last_name: auth.last_name,
+          admin: auth.admin || false,
+          color: auth.color,
+          scope: auth.scope || [],
+        };
+      }
+    );
+
+    /**
+     * POST /register - Register new user
+     *
+     * Creates a new user account
+     */
+    fastify.post(
+      "/register",
+      {
+        schema: {
+          description: "Register a new user account",
+          tags: ["auth"],
+          body: {
+            type: "object",
+            required: ["email", "password", "first_name", "last_name"],
+            properties: {
+              email: { type: "string", format: "email" },
+              password: { type: "string", minLength: 8 },
+              first_name: { type: "string", minLength: 1 },
+              last_name: { type: "string", minLength: 1 },
+            },
+          },
+          response: {
+            201: {
+              type: "object",
+              properties: {
+                token: { type: "string" },
+                user: {
+                  type: "object",
+                  properties: {
+                    id: { type: ["string", "integer"] },
+                    email: { type: "string" },
+                    first_name: { type: "string" },
+                    last_name: { type: "string" },
+                  },
+                },
+              },
+            },
+            400: {
+              type: "object",
+              properties: {
+                statusCode: { type: "integer" },
+                error: { type: "string" },
+                message: { type: "string" },
+              },
+            },
+            409: {
+              type: "object",
+              properties: {
+                statusCode: { type: "integer" },
+                error: { type: "string" },
+                message: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+      async (request, reply) => {
+        const { email, password, first_name, last_name } = request.body;
+
+        try {
+          // Check if user already exists
+          const existingUser = await userLookup(email);
+
+          if (existingUser) {
+            return reply.code(409).send({
+              statusCode: 409,
+              error: "Conflict",
+              message: "An account with this email already exists",
+            });
+          }
+
+          // Hash password
+          const hashedPassword = await bcrypt.hash(password, saltRounds);
+
+          // Create user
+          const newUser = await createUser({
+            email,
+            password: hashedPassword,
+            first_name,
+            last_name,
+          });
+
+          // Create JWT payload
+          const payload = {
+            id: newUser.id,
+            first_name: newUser.first_name,
+            last_name: newUser.last_name,
+            email: newUser.email,
+            admin: newUser.admin || false,
+            scope: newUser.scope || newUser.roles || [],
+          };
+
+          // Sign token
+          const token = jwtService.sign(payload, {
+            subject: String(newUser.id),
+          });
+
+          return reply.code(201).send({
+            token,
+            user: {
+              id: newUser.id,
+              email: newUser.email,
+              first_name: newUser.first_name,
+              last_name: newUser.last_name,
+            },
+          });
+        } catch (error) {
+          request.log.error(error, "Registration error");
+          return reply.code(500).send({
+            statusCode: 500,
+            error: "Internal Server Error",
+            message: "An error occurred during registration",
+          });
+        }
+      }
+    );
+
+    /**
+     * POST /password-reset - Request password reset
+     *
+     * Initiates password reset process
+     */
+    fastify.post(
+      "/password-reset",
+      {
+        schema: {
+          description: "Request a password reset",
+          tags: ["auth"],
+          body: {
+            type: "object",
+            required: ["email"],
+            properties: {
+              email: { type: "string", format: "email" },
+            },
+          },
+          response: {
+            200: {
+              type: "object",
+              properties: {
+                message: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+      async (request, reply) => {
+        const { email } = request.body;
+
+        try {
+          // Call password reset handler
+          // The handler is responsible for sending email, creating tokens, etc.
+          await passwordReset(email);
+
+          // Always return success to prevent email enumeration
+          return {
+            message: "If an account with that email exists, a password reset link has been sent",
+          };
+        } catch (error) {
+          request.log.error(error, "Password reset error");
+
+          // Still return success to prevent email enumeration
+          return {
+            message: "If an account with that email exists, a password reset link has been sent",
+          };
+        }
+      }
+    );
+
+    /**
+     * PUT /password-reset - Complete password reset
+     *
+     * Completes password reset with token and new password
+     */
+    fastify.put(
+      "/password-reset",
+      {
+        schema: {
+          description: "Complete password reset with token",
+          tags: ["auth"],
+          body: {
+            type: "object",
+            required: ["token", "password"],
+            properties: {
+              token: { type: "string", minLength: 1 },
+              password: { type: "string", minLength: 8 },
+            },
+          },
+          response: {
+            200: {
+              type: "object",
+              properties: {
+                message: { type: "string" },
+              },
+            },
+            400: {
+              type: "object",
+              properties: {
+                statusCode: { type: "integer" },
+                error: { type: "string" },
+                message: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+      async (request, reply) => {
+        const { token, password } = request.body;
+
+        try {
+          // Hash new password
+          const hashedPassword = await bcrypt.hash(password, saltRounds);
+
+          // Call password reset complete handler
+          // The handler should validate token and update password
+          await passwordReset(null, token, hashedPassword);
+
+          return {
+            message: "Password has been reset successfully",
+          };
+        } catch (error) {
+          request.log.error(error, "Password reset complete error");
+
+          return reply.code(400).send({
+            statusCode: 400,
+            error: "Bad Request",
+            message: error.message || "Invalid or expired reset token",
+          });
+        }
+      }
+    );
+  };
+}
+
+/**
+ * Hash a password using bcrypt
+ *
+ * @param {string} password - Plain text password
+ * @param {number} [rounds] - Salt rounds (default: 10)
+ * @returns {Promise<string>} Hashed password
+ */
+export async function hashPassword(password, rounds = 10) {
+  return bcrypt.hash(password, rounds);
+}
+
+/**
+ * Compare a password with a hash
+ *
+ * @param {string} password - Plain text password
+ * @param {string} hash - Hashed password
+ * @returns {Promise<boolean>} True if password matches
+ */
+export async function comparePassword(password, hash) {
+  return bcrypt.compare(password, hash);
+}

package/src/services/jwt.js

@@ -0,0 +1,143 @@
+/**
+ * JWT Service
+ *
+ * Handles JWT signing and verification with RS256 algorithm support.
+ * Compatible with express-jwt patterns.
+ */
+
+import jwt from "jsonwebtoken";
+import fs from "fs";
+import path from "path";
+
+/**
+ * Load a key from file or return the key if already a string
+ * @param {string} keyOrPath - Key content or file path
+ * @param {string} basePath - Base path for relative paths
+ * @returns {string} Key content
+ */
+function loadKey(keyOrPath, basePath = process.cwd()) {
+  if (!keyOrPath) return null;
+
+  // If it looks like a key (starts with -----BEGIN), return as-is
+  if (keyOrPath.includes("-----BEGIN")) {
+    return keyOrPath;
+  }
+
+  // Otherwise, try to load from file
+  try {
+    const keyPath = path.isAbsolute(keyOrPath) ? keyOrPath : path.join(basePath, keyOrPath);
+    return fs.readFileSync(keyPath, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to load key from ${keyOrPath}: ${error.message}`);
+  }
+}
+
+/**
+ * Create a JWT service instance
+ *
+ * @param {Object} config - Configuration
+ * @param {string} [config.publicKey] - Public key content or path (for verification)
+ * @param {string} [config.privateKey] - Private key content or path (for signing)
+ * @param {string} [config.secret] - Symmetric secret (alternative to key pair)
+ * @param {string} [config.algorithm] - Algorithm (default: RS256 for keys, HS256 for secret)
+ * @param {string} [config.expiresIn] - Default token expiration (e.g., '4d', '1h')
+ * @param {string} [config.audience] - JWT audience claim
+ * @param {string} [config.issuer] - JWT issuer claim
+ * @param {string} [config.basePath] - Base path for relative key paths
+ * @returns {Object} JWT service
+ */
+export function createJwtService(config) {
+  const { publicKey, privateKey, secret, algorithm, expiresIn = "4d", audience, issuer, basePath = process.cwd() } = config;
+
+  // Load keys
+  const loadedPublicKey = publicKey ? loadKey(publicKey, basePath) : null;
+  const loadedPrivateKey = privateKey ? loadKey(privateKey, basePath) : null;
+
+  // Determine algorithm
+  const algo = algorithm || (loadedPrivateKey || loadedPublicKey ? "RS256" : "HS256");
+
+  // Determine signing key
+  const signingKey = loadedPrivateKey || secret;
+  const verifyKey = loadedPublicKey || secret;
+
+  if (!verifyKey) {
+    throw new Error("xAuth: Either publicKey/privateKey or secret is required");
+  }
+
+  /**
+   * Sign a JWT token
+   *
+   * @param {Object} payload - Token payload
+   * @param {Object} [options] - Override options
+   * @returns {string} Signed JWT token
+   */
+  function sign(payload, options = {}) {
+    if (!signingKey) {
+      throw new Error("xAuth: privateKey or secret required for signing");
+    }
+
+    const signOptions = {
+      algorithm: algo,
+      expiresIn: options.expiresIn || expiresIn,
+    };
+
+    // Add audience if configured
+    if (audience || options.audience) {
+      signOptions.audience = options.audience || audience;
+    }
+
+    // Add issuer if configured
+    if (issuer || options.issuer) {
+      signOptions.issuer = options.issuer || issuer;
+    }
+
+    // Add subject if provided
+    if (options.subject) {
+      signOptions.subject = options.subject;
+    }
+
+    return jwt.sign(payload, signingKey, signOptions);
+  }
+
+  /**
+   * Verify a JWT token
+   *
+   * @param {string} token - JWT token
+   * @param {Object} [options] - Verification options
+   * @returns {Object} Decoded token payload
+   */
+  function verify(token, options = {}) {
+    const verifyOptions = {
+      algorithms: [algo],
+    };
+
+    // Add audience verification if configured
+    if (audience || options.audience) {
+      verifyOptions.audience = options.audience || audience;
+    }
+
+    // Add issuer verification if configured
+    if (issuer || options.issuer) {
+      verifyOptions.issuer = options.issuer || issuer;
+    }
+
+    return jwt.verify(token, verifyKey, verifyOptions);
+  }
+
+  /**
+   * Decode a JWT token without verification
+   *
+   * @param {string} token - JWT token
+   * @returns {Object|null} Decoded token or null
+   */
+  function decode(token) {
+    return jwt.decode(token, { complete: true });
+  }
+
+  return {
+    sign,
+    verify,
+    decode,
+    algorithm: algo,
+  };
+}