@xenterprises/fastify-xauth-local 1.0.0

package/src/services/middleware.js

@@ -0,0 +1,177 @@
+/**
+ * Auth Middleware Service
+ *
+ * Provides JWT authentication middleware with route exclusion support.
+ * Compatible with express-jwt `.unless()` pattern.
+ */
+
+/**
+ * Check if a route should be excluded from authentication
+ *
+ * @param {string} url - Request URL
+ * @param {string} method - Request method
+ * @param {Array} excludedPaths - Array of path exclusion rules
+ * @returns {boolean} True if route should be excluded
+ */
+function isExcludedRoute(url, method, excludedPaths) {
+  if (!excludedPaths || excludedPaths.length === 0) {
+    return false;
+  }
+
+  for (const rule of excludedPaths) {
+    // String pattern - exact prefix match
+    if (typeof rule === "string") {
+      if (url.startsWith(rule)) {
+        return true;
+      }
+      continue;
+    }
+
+    // RegExp pattern
+    if (rule instanceof RegExp) {
+      if (rule.test(url)) {
+        return true;
+      }
+      continue;
+    }
+
+    // Object pattern with url and optional methods (express-jwt style)
+    if (typeof rule === "object" && rule.url) {
+      let urlMatches = false;
+
+      // Check URL match
+      if (typeof rule.url === "string") {
+        urlMatches = url.startsWith(rule.url);
+      } else if (rule.url instanceof RegExp) {
+        urlMatches = rule.url.test(url);
+      }
+
+      if (!urlMatches) {
+        continue;
+      }
+
+      // Check method match if specified
+      if (rule.methods && Array.isArray(rule.methods)) {
+        const upperMethod = method.toUpperCase();
+        if (rule.methods.map((m) => m.toUpperCase()).includes(upperMethod)) {
+          return true;
+        }
+      } else {
+        // No method restriction, URL match is sufficient
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Create authentication middleware
+ *
+ * @param {Object} jwtService - JWT service instance
+ * @param {Object} options - Middleware options
+ * @param {Array} [options.excludedPaths] - Paths to exclude from auth
+ * @param {string} [options.requestProperty] - Property to attach auth to request (default: 'auth')
+ * @param {boolean} [options.credentialsRequired] - Whether credentials are required (default: true)
+ * @param {Function} [options.getToken] - Custom function to extract token
+ * @returns {Function} Fastify onRequest hook
+ */
+export function createAuthMiddleware(jwtService, options = {}) {
+  const { excludedPaths = [], requestProperty = "auth", credentialsRequired = true, getToken } = options;
+
+  return async function authMiddleware(request, reply) {
+    // Check if route is excluded
+    if (isExcludedRoute(request.url, request.method, excludedPaths)) {
+      return;
+    }
+
+    // Extract token
+    let token;
+    if (getToken) {
+      token = getToken(request);
+    } else {
+      // Default: extract from Authorization header
+      const authHeader = request.headers.authorization;
+      if (authHeader && authHeader.startsWith("Bearer ")) {
+        token = authHeader.slice(7);
+      }
+    }
+
+    // Handle missing token
+    if (!token) {
+      if (credentialsRequired) {
+        reply.code(401).send({
+          statusCode: 401,
+          error: "Unauthorized",
+          message: "No authorization token was found",
+        });
+        return;
+      }
+      // Token not required, continue without auth
+      return;
+    }
+
+    // Verify token
+    try {
+      const decoded = jwtService.verify(token);
+
+      // Attach to request (compatible with express-jwt's requestProperty)
+      request[requestProperty] = decoded;
+    } catch (error) {
+      reply.code(401).send({
+        statusCode: 401,
+        error: "Unauthorized",
+        message: error.message || "Invalid token",
+      });
+    }
+  };
+}
+
+/**
+ * Create role-based access control middleware
+ *
+ * @param {string|string[]} allowedRoles - Role(s) that can access the route
+ * @param {Object} options - Options
+ * @param {string} [options.requestProperty] - Property where auth is attached (default: 'auth')
+ * @param {string} [options.roleProperty] - Property in auth that contains role(s) (default: 'scope')
+ * @returns {Function} Fastify preHandler hook
+ */
+export function createRoleMiddleware(allowedRoles, options = {}) {
+  const { requestProperty = "auth", roleProperty = "scope" } = options;
+
+  // Normalize to array
+  const roles = Array.isArray(allowedRoles) ? allowedRoles : [allowedRoles];
+
+  return async function roleMiddleware(request, reply) {
+    const auth = request[requestProperty];
+
+    if (!auth) {
+      reply.code(401).send({
+        statusCode: 401,
+        error: "Unauthorized",
+        message: "Authentication required",
+      });
+      return;
+    }
+
+    // Get user's roles from auth
+    const userRoles = auth[roleProperty];
+
+    // Normalize user roles to array
+    const userRoleArray = Array.isArray(userRoles) ? userRoles : userRoles ? [userRoles] : [];
+
+    // Check if user has any of the allowed roles
+    const hasRole = roles.some((role) => userRoleArray.includes(role));
+
+    if (!hasRole) {
+      reply.code(403).send({
+        statusCode: 403,
+        error: "Forbidden",
+        message: `Access denied. Required role(s): ${roles.join(", ")}`,
+      });
+    }
+  };
+}
+
+export { isExcludedRoute };

package/src/xAuthLocal.js

@@ -0,0 +1,242 @@
+/**
+ * xAuthLocal - Fastify JWT Authentication Plugin
+ *
+ * Provides JWT authentication with role-based access control,
+ * compatible with express-jwt patterns.
+ * Supports multiple auth configurations for different route prefixes.
+ */
+
+import fp from "fastify-plugin";
+import { createJwtService } from "./services/jwt.js";
+import { createAuthMiddleware, createRoleMiddleware, isExcludedRoute } from "./services/middleware.js";
+import { createLocalRoutes, hashPassword, comparePassword } from "./routes/local.js";
+
+/**
+ * Generate a key from prefix for the configs object
+ * @param {string} prefix - Route prefix
+ * @returns {string} Config key
+ */
+function getConfigKey(prefix) {
+  return prefix.replace(/^\//, "").replace(/\//g, "_") || "root";
+}
+
+/**
+ * xAuthLocal Plugin
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {boolean} [options.active=true] - Enable/disable the plugin
+ * @param {Array} options.configs - Array of auth configurations
+ * @param {string} options.configs[].name - Unique name for this config
+ * @param {string} options.configs[].prefix - Route prefix to guard (e.g., '/api', '/admin')
+ * @param {string} [options.configs[].secret] - Symmetric secret for HS256
+ * @param {string} [options.configs[].publicKey] - Public key for RS256
+ * @param {string} [options.configs[].privateKey] - Private key for RS256
+ * @param {string} [options.configs[].algorithm] - Algorithm (default: RS256 for keys, HS256 for secret)
+ * @param {string} [options.configs[].expiresIn] - Token expiration (default: '4d')
+ * @param {string} [options.configs[].audience] - JWT audience claim
+ * @param {string} [options.configs[].issuer] - JWT issuer claim
+ * @param {string} [options.configs[].requestProperty] - Property to attach auth (default: 'auth')
+ * @param {boolean} [options.configs[].credentialsRequired] - Whether credentials are required (default: true)
+ * @param {Array} [options.configs[].excludedPaths] - Additional paths to exclude from auth
+ * @param {Object} [options.configs[].local] - Local routes configuration
+ * @param {boolean} [options.configs[].local.enabled] - Enable local auth routes
+ * @param {string} [options.configs[].local.loginPath] - Login route path (default: prefix + '/local')
+ * @param {string} [options.configs[].local.mePath] - Me route path (default: prefix + '/local/me')
+ * @param {boolean} [options.configs[].local.skipUserLookup] - Skip userLookup, use token data only for /me
+ * @param {Function} [options.configs[].local.userLookup] - Function to lookup user by email
+ * @param {Function} [options.configs[].local.createUser] - Function to create new user
+ * @param {Function} [options.configs[].local.passwordReset] - Function to handle password reset
+ * @param {number} [options.configs[].local.saltRounds] - bcrypt salt rounds (default: 10)
+ * @param {string} [options.basePath] - Base path for relative key paths
+ */
+async function xAuthLocalPlugin(fastify, options) {
+  const { active = true, configs = [], basePath = process.cwd() } = options;
+
+  // Early return if disabled
+  if (!active) {
+    fastify.log.info("xAuthLocal: Plugin disabled");
+    return;
+  }
+
+  // Validate configs
+  if (!Array.isArray(configs) || configs.length === 0) {
+    throw new Error("xAuthLocal: configs array is required and must not be empty");
+  }
+
+  // Store all auth instances
+  const authInstances = {};
+
+  // Process each config
+  for (const config of configs) {
+    const {
+      name,
+      prefix,
+      secret,
+      publicKey,
+      privateKey,
+      algorithm,
+      expiresIn = "4d",
+      audience,
+      issuer,
+      requestProperty = "auth",
+      credentialsRequired = true,
+      excludedPaths = [],
+      local = {},
+      getToken,
+    } = config;
+
+    // Validate required fields
+    if (!name) {
+      throw new Error("xAuthLocal: Each config must have a 'name'");
+    }
+    if (!prefix) {
+      throw new Error(`xAuthLocal: Config '${name}' must have a 'prefix'`);
+    }
+    if (!secret && !publicKey && !privateKey) {
+      throw new Error(`xAuthLocal: Config '${name}' requires secret or publicKey/privateKey`);
+    }
+
+    // Create JWT service for this config
+    const jwtService = createJwtService({
+      publicKey,
+      privateKey,
+      secret,
+      algorithm,
+      expiresIn,
+      audience,
+      issuer,
+      basePath,
+    });
+
+    // Build excluded paths for this config
+    let configExcludedPaths = [...excludedPaths];
+
+    // Local route paths
+    const localPrefix = local.loginPath || `${prefix}/local`;
+    const mePath = local.mePath || `${localPrefix}/me`;
+
+    // Add local routes to excluded paths if enabled
+    if (local.enabled) {
+      configExcludedPaths.push(
+        { url: new RegExp(`^${localPrefix}$`), methods: ["POST"] }, // Login
+        { url: new RegExp(`^${localPrefix}/register$`), methods: ["POST"] }, // Register
+        { url: new RegExp(`^${localPrefix}/password-reset$`), methods: ["POST", "PUT"] } // Password reset
+      );
+    }
+
+    // Create auth middleware for routes matching this prefix
+    const authMiddleware = createAuthMiddleware(jwtService, {
+      excludedPaths: configExcludedPaths,
+      requestProperty,
+      credentialsRequired,
+      getToken,
+    });
+
+    // Register route-specific auth hook
+    fastify.addHook("onRequest", async (request, reply) => {
+      // Only apply to routes matching this prefix
+      if (request.url.startsWith(prefix)) {
+        await authMiddleware(request, reply);
+      }
+    });
+
+    // Register local routes if enabled
+    if (local.enabled) {
+      const localRoutes = createLocalRoutes({
+        jwtService,
+        userLookup: local.userLookup,
+        createUser: local.createUser,
+        passwordReset: local.passwordReset,
+        saltRounds: local.saltRounds,
+        skipUserLookup: local.skipUserLookup,
+        mePath,
+        requestProperty,
+      });
+
+      await fastify.register(localRoutes, { prefix: localPrefix });
+      fastify.log.info(`xAuthLocal: Local routes for '${name}' registered at ${localPrefix}`);
+    }
+
+    // Store instance info
+    authInstances[name] = {
+      name,
+      prefix,
+      jwt: jwtService,
+      requestProperty,
+      credentialsRequired,
+      hasLocalRoutes: local.enabled || false,
+      localPrefix: local.enabled ? localPrefix : null,
+      mePath: local.enabled ? mePath : null,
+
+      /**
+       * Create role-based middleware for this config
+       */
+      requireRole: (roles, opts = {}) => {
+        return createRoleMiddleware(roles, {
+          requestProperty,
+          ...opts,
+        });
+      },
+
+      /**
+       * Create custom auth middleware for this config
+       */
+      createMiddleware: (opts = {}) => {
+        return createAuthMiddleware(jwtService, {
+          requestProperty,
+          credentialsRequired,
+          ...opts,
+        });
+      },
+
+      /**
+       * Check if a route is excluded from auth for this config
+       */
+      isExcluded: (url, method) => {
+        return isExcludedRoute(url, method, configExcludedPaths);
+      },
+    };
+  }
+
+  // Decorate fastify with xauthlocal namespace
+  fastify.decorate("xauthlocal", {
+    /**
+     * All auth configurations by name
+     */
+    configs: authInstances,
+
+    /**
+     * Get a specific auth config by name
+     */
+    get: (name) => authInstances[name],
+
+    /**
+     * Password utilities
+     */
+    password: {
+      hash: hashPassword,
+      compare: comparePassword,
+    },
+
+    /**
+     * Summary config (read-only)
+     */
+    config: {
+      configCount: configs.length,
+      configNames: Object.keys(authInstances),
+    },
+  });
+
+  fastify.log.info(`xAuthLocal: Plugin registered with ${configs.length} config(s)`);
+}
+
+export default fp(xAuthLocalPlugin, {
+  fastify: "5.x",
+  name: "xauthlocal",
+});
+
+// Named exports for convenience
+export { createJwtService } from "./services/jwt.js";
+export { createAuthMiddleware, createRoleMiddleware, isExcludedRoute } from "./services/middleware.js";
+export { createLocalRoutes, hashPassword, comparePassword } from "./routes/local.js";