s3db.js 13.4.0 → 13.6.0

package/src/plugins/api/auth/basic-auth.js

@@ -67,21 +67,31 @@ async function verifyPassword(inputPassword, storedPassword, passphrase) {
  * Create Basic Auth middleware
  * @param {Object} options - Basic Auth options
  * @param {string} options.realm - Authentication realm (default: 'API Access')
- * @param {Object} options.usersResource - Users resource for credential validation
+ * @param {Object} options.authResource - Resource for credential validation
+ * @param {string} options.usernameField - Field name for username (default: 'email')
+ * @param {string} options.passwordField - Field name for password (default: 'password')
  * @param {string} options.passphrase - Passphrase for password decryption
  * @param {boolean} options.optional - If true, allows requests without auth
+ * @param {Object} options.adminUser - Root admin credentials (bypasses DB lookup)
+ * @param {boolean} options.adminUser.enabled - Enable admin root user bypass (default: false)
+ * @param {string} options.adminUser.username - Admin username
+ * @param {string} options.adminUser.password - Admin password (plain text)
+ * @param {Array<string>} options.adminUser.scopes - Admin scopes (default: ['admin'])
  * @returns {Function} Hono middleware
  */
 export function basicAuth(options = {}) {
   const {
     realm = 'API Access',
-    usersResource,
+    authResource,
+    usernameField = 'email',
+    passwordField = 'password',
     passphrase = 'secret',
-    optional = false
+    optional = false,
+    adminUser = null
   } = options;
 
-  if (!usersResource) {
-    throw new Error('usersResource is required for Basic authentication');
+  if (!authResource) {
+    throw new Error('authResource is required for Basic authentication');
   }
 
   return async (c, next) => {
@@ -107,9 +117,26 @@ export function basicAuth(options = {}) {
 
     const { username, password } = credentials;
 
-    // Query user by username
+    // Check admin user first (bypasses DB lookup)
+    if (adminUser && adminUser.enabled === true) {
+      if (username === adminUser.username && password === adminUser.password) {
+        c.set('user', {
+          id: 'root',
+          username: adminUser.username,
+          email: adminUser.username,
+          scopes: adminUser.scopes || ['admin'],
+          authMethod: 'basic-admin'
+        });
+        c.set('authMethod', 'basic');
+        await next();
+        return;
+      }
+    }
+
+    // Query user by configured username field
     try {
-      const users = await usersResource.query({ username });
+      const queryFilter = { [usernameField]: username };
+      const users = await authResource.query(queryFilter);
 
       if (!users || users.length === 0) {
         c.header('WWW-Authenticate', `Basic realm="${realm}"`);
@@ -119,14 +146,17 @@ export function basicAuth(options = {}) {
 
       const user = users[0];
 
-      if (!user.active) {
+      // Check if user is active (if field exists)
+      if (user.active !== undefined && !user.active) {
         c.header('WWW-Authenticate', `Basic realm="${realm}"`);
         const response = unauthorized('User account is inactive');
         return c.json(response, response._status);
       }
 
-      // Verify password
-      const isValid = await verifyPassword(password, user.password, passphrase);
+      // Verify password using configured password field
+      // Schema handles encryption/decryption for 'secret' field types
+      const storedPassword = user[passwordField];
+      const isValid = storedPassword === password;
 
       if (!isValid) {
         c.header('WWW-Authenticate', `Basic realm="${realm}"`);

package/src/plugins/api/auth/index.js

@@ -7,17 +7,23 @@
 import { jwtAuth } from './jwt-auth.js';
 import { apiKeyAuth } from './api-key-auth.js';
 import { basicAuth } from './basic-auth.js';
+import { createOAuth2Handler } from './oauth2-auth.js';
+import { OIDCClient } from './oidc-client.js';
 import { unauthorized } from '../utils/response-formatter.js';
 
 /**
  * Create authentication middleware that supports multiple auth methods
  * @param {Object} options - Authentication options
- * @param {Array<string>} options.methods - Allowed auth methods (['jwt', 'apiKey', 'basic'])
+ * @param {Array<string>} options.methods - Allowed auth methods (['jwt', 'apiKey', 'basic', 'oauth2'])
  * @param {Object} options.jwt - JWT configuration
  * @param {Object} options.apiKey - API Key configuration
  * @param {Object} options.basic - Basic Auth configuration
+ * @param {Object} options.oauth2 - OAuth2 configuration
+ * @param {Function} options.oidc - OIDC middleware (already configured)
  * @param {Object} options.usersResource - Users resource
  * @param {boolean} options.optional - If true, allows requests without auth
+ * @param {string} options.strategy - Auth strategy: 'any' (default, OR logic) or 'priority' (waterfall with explicit order)
+ * @param {Object} options.priorities - Priority map for 'priority' strategy { jwt: 1, oidc: 2, basic: 3 }
  * @returns {Function} Hono middleware
  */
 export function createAuthMiddleware(options = {}) {
@@ -26,8 +32,12 @@ export function createAuthMiddleware(options = {}) {
     jwt: jwtConfig = {},
     apiKey: apiKeyConfig = {},
     basic: basicConfig = {},
+    oauth2: oauth2Config = {},
+    oidc: oidcMiddleware = null,
     usersResource,
-    optional = false
+    optional = false,
+    strategy = 'any',
+    priorities = {}
   } = options;
 
   // If no methods specified, allow all requests
@@ -72,6 +82,38 @@ export function createAuthMiddleware(options = {}) {
     });
   }
 
+  if (methods.includes('oauth2') && oauth2Config.issuer) {
+    const oauth2Handler = createOAuth2Handler(oauth2Config, usersResource);
+    middlewares.push({
+      name: 'oauth2',
+      middleware: async (c, next) => {
+        const user = await oauth2Handler(c);
+        if (user) {
+          c.set('user', user);
+          return await next();
+        }
+        // No user, try next method
+      }
+    });
+  }
+
+  // OIDC middleware (session-based authentication)
+  if (oidcMiddleware) {
+    middlewares.push({
+      name: 'oidc',
+      middleware: oidcMiddleware
+    });
+  }
+
+  // Sort middlewares by priority if strategy is 'priority'
+  if (strategy === 'priority' && Object.keys(priorities).length > 0) {
+    middlewares.sort((a, b) => {
+      const priorityA = priorities[a.name] || 999; // Unspecified = lowest priority
+      const priorityB = priorities[b.name] || 999;
+      return priorityA - priorityB; // Lower number = higher priority
+    });
+  }
+
   // Return combined middleware
   return async (c, next) => {
     // Try each auth method
@@ -104,9 +146,13 @@ export function createAuthMiddleware(options = {}) {
   };
 }
 
+export { OIDCClient };
+
 export default {
   createAuthMiddleware,
   jwtAuth,
   apiKeyAuth,
-  basicAuth
+  basicAuth,
+  createOAuth2Handler,
+  OIDCClient
 };

package/src/plugins/api/auth/oauth2-auth.js

@@ -0,0 +1,171 @@
+/**
+ * OAuth2/OIDC Authentication Driver (Resource Server)
+ *
+ * Validates JWT access tokens issued by an OAuth2/OIDC Authorization Server.
+ * Fetches public keys from JWKS endpoint and verifies token signatures.
+ *
+ * Use this driver when your application acts as a Resource Server
+ * consuming tokens from an external Authorization Server (SSO).
+ *
+ * @example
+ * {
+ *   driver: 'oauth2',
+ *   config: {
+ *     issuer: 'http://localhost:4000',
+ *     jwksUri: 'http://localhost:4000/.well-known/jwks.json',
+ *     audience: 'my-api',
+ *     algorithms: ['RS256'],
+ *     cacheTTL: 3600000  // 1 hour
+ *   }
+ * }
+ */
+
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+// Cache for JWKS (avoids fetching on every request)
+const jwksCache = new Map();
+
+/**
+ * Create OAuth2 authentication handler
+ * @param {Object} config - OAuth2 configuration
+ * @param {Object} usersResource - s3db.js users resource
+ * @returns {Function} Hono middleware
+ */
+export function createOAuth2Handler(config, usersResource) {
+  const {
+    issuer,
+    jwksUri,
+    audience = null,
+    algorithms = ['RS256', 'ES256'],
+    cacheTTL = 3600000, // 1 hour
+    clockTolerance = 60, // 60 seconds tolerance for exp/nbf
+    validateScopes = true,
+    fetchUserInfo = true
+  } = config;
+
+  if (!issuer) {
+    throw new Error('[OAuth2 Auth] Missing required config: issuer');
+  }
+
+  // Construct JWKS URI from issuer if not provided
+  const finalJwksUri = jwksUri || `${issuer}/.well-known/jwks.json`;
+
+  // Get or create JWKS fetcher (cached)
+  const getJWKS = () => {
+    const cacheKey = finalJwksUri;
+
+    if (jwksCache.has(cacheKey)) {
+      const cached = jwksCache.get(cacheKey);
+      if (Date.now() - cached.timestamp < cacheTTL) {
+        return cached.jwks;
+      }
+    }
+
+    // Create remote JWKS fetcher
+    const jwks = createRemoteJWKSet(new URL(finalJwksUri), {
+      cooldownDuration: 30000, // 30 seconds cooldown between fetches
+      cacheMaxAge: cacheTTL
+    });
+
+    jwksCache.set(cacheKey, {
+      jwks,
+      timestamp: Date.now()
+    });
+
+    return jwks;
+  };
+
+  /**
+   * OAuth2 authentication middleware
+   */
+  return async (c) => {
+    // Extract token from Authorization header
+    const authHeader = c.req.header('authorization') || c.req.header('Authorization');
+
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return null; // No OAuth2 token, try next auth method
+    }
+
+    const token = authHeader.substring(7); // Remove 'Bearer ' prefix
+
+    try {
+      // Verify JWT token with remote JWKS
+      const jwks = getJWKS();
+
+      const verifyOptions = {
+        issuer,
+        algorithms,
+        clockTolerance
+      };
+
+      if (audience) {
+        verifyOptions.audience = audience;
+      }
+
+      const { payload } = await jwtVerify(token, jwks, verifyOptions);
+
+      // Extract user info from token claims
+      const userId = payload.sub; // Subject (user ID)
+      const email = payload.email || null;
+      const username = payload.preferred_username || payload.username || email;
+      const scopes = payload.scope ? payload.scope.split(' ') : (payload.scopes || []);
+      const role = payload.role || 'user';
+
+      // Optionally fetch full user info from database
+      let user = null;
+
+      if (fetchUserInfo && userId && usersResource) {
+        try {
+          // Try to find user by ID
+          user = await usersResource.get(userId).catch(() => null);
+
+          // If not found by ID, try by email
+          if (!user && email) {
+            const users = await usersResource.query({ email }, { limit: 1 });
+            user = users[0] || null;
+          }
+        } catch (err) {
+          // User not found in local database, use token claims only
+        }
+      }
+
+      // If user found in database, merge with token claims
+      if (user) {
+        return {
+          ...user,
+          scopes: user.scopes || scopes, // Prefer database scopes
+          role: user.role || role,
+          tokenClaims: payload // Include full token claims
+        };
+      }
+
+      // User not in database, create virtual user from token
+      return {
+        id: userId,
+        username: username || userId,
+        email,
+        role,
+        scopes,
+        active: true,
+        tokenClaims: payload,
+        isVirtual: true // Flag to indicate user is not in local database
+      };
+
+    } catch (err) {
+      // Token verification failed
+      if (config.verbose) {
+        console.error('[OAuth2 Auth] Token verification failed:', err.message);
+      }
+      return null; // Invalid token, try next auth method
+    }
+  };
+}
+
+/**
+ * Clear JWKS cache (useful for testing or when keys are rotated)
+ */
+export function clearJWKSCache() {
+  jwksCache.clear();
+}
+
+export default createOAuth2Handler;