s3db.js 13.5.1 → 13.6.0

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;