@connexa/mcp-oauth-firebase-middleware 1.0.0

package/lib/authorize.js

@@ -0,0 +1,126 @@
+/**
+ * OAuth Authorization Endpoint
+ * Handles authorization requests with PKCE
+ */
+
+const { generateSecureToken } = require('./pkce');
+const { authenticateUser } = require('./firebase-client');
+const storage = require('./storage');
+
+/**
+ * Create authorization endpoint handler
+ */
+function createAuthorizeHandler(config) {
+  return async (req, res) => {
+    try {
+      // Extract and validate OAuth parameters
+      const {
+        client_id,
+        code_challenge,
+        code_challenge_method,
+        redirect_uri,
+        response_type,
+        scope,
+        state
+      } = req.query;
+
+      // Validate required parameters
+      if (!client_id) {
+        return sendError(res, 'invalid_request', 'Missing client_id');
+      }
+
+      if (!code_challenge || code_challenge_method !== 'S256') {
+        return sendError(res, 'invalid_request', 'PKCE with S256 is required');
+      }
+
+      if (!redirect_uri) {
+        return sendError(res, 'invalid_request', 'Missing redirect_uri');
+      }
+
+      if (response_type !== 'code') {
+        return sendError(res, 'unsupported_response_type', 'Only code response type is supported');
+      }
+
+      // Validate client_id and redirect_uri
+      if (!validateClient(client_id, redirect_uri, config)) {
+        return sendError(res, 'invalid_client', 'Invalid client_id or redirect_uri');
+      }
+
+      // Authenticate with Firebase using client credentials
+      // Note: In this implementation, we use email/password stored in config
+      // In production, you might want to store user credentials differently
+      const email = config.clientEmail || client_id;
+      const password = config.clientSecret;
+
+      if (!password) {
+        return sendError(res, 'server_error', 'Client authentication configuration missing');
+      }
+
+      let authResult;
+      try {
+        authResult = await authenticateUser(email, password);
+      } catch (error) {
+        console.error('Firebase auth error in authorize:', error.message);
+        return sendError(res, 'access_denied', 'Authentication failed');
+      }
+
+      // Generate authorization code
+      const authorizationCode = generateSecureToken(32);
+
+      // Store authorization code with associated data
+      storage.store(authorizationCode, {
+        clientId: client_id,
+        codeChallenge: code_challenge,
+        codeChallengeMethod: code_challenge_method,
+        redirectUri: redirect_uri,
+        scope: scope || '',
+        userId: authResult.user.uid,
+        userEmail: authResult.user.email,
+        state: state || ''
+      });
+
+      // Redirect back to client with authorization code
+      const redirectUrl = new URL(redirect_uri);
+      redirectUrl.searchParams.set('code', authorizationCode);
+      if (state) {
+        redirectUrl.searchParams.set('state', state);
+      }
+
+      res.redirect(redirectUrl.toString());
+
+    } catch (error) {
+      console.error('Authorization endpoint error:', error);
+      return sendError(res, 'server_error', 'Internal server error');
+    }
+  };
+}
+
+/**
+ * Validate client_id and redirect_uri
+ */
+function validateClient(clientId, redirectUri, config) {
+  // In production, validate against registered clients from database
+  // For now, check against environment variables or config
+  const validClientId = config.clientId || process.env.OAUTH_CLIENT_ID;
+  const validRedirectUri = config.redirectUri || process.env.OAUTH_REDIRECT_URI;
+
+  // Allow any client if not configured (for testing)
+  if (!validClientId) {
+    console.warn('No client validation configured - accepting all clients');
+    return true;
+  }
+
+  return clientId === validClientId && redirectUri === validRedirectUri;
+}
+
+/**
+ * Send OAuth error response
+ */
+function sendError(res, error, errorDescription) {
+  res.status(400).json({
+    error,
+    error_description: errorDescription
+  });
+}
+
+module.exports = { createAuthorizeHandler };

package/lib/firebase-client.js

@@ -0,0 +1,250 @@
+/**
+ * Firebase Authentication Client
+ * Handles Firebase Auth operations for OAuth flows
+ */
+
+const { initializeApp } = require('firebase/app');
+const { getAuth, signInWithEmailAndPassword } = require('firebase/auth');
+const admin = require('firebase-admin');
+
+let firebaseApp = null;
+let firebaseAuth = null;
+let adminInitialized = false;
+
+/**
+ * Initialize Firebase Client SDK
+ */
+function initializeFirebaseClient(config) {
+  if (!firebaseApp) {
+    firebaseApp = initializeApp({
+      apiKey: config.apiKey,
+      authDomain: config.authDomain,
+      projectId: config.projectId
+    });
+    firebaseAuth = getAuth(firebaseApp);
+  }
+  return firebaseAuth;
+}
+
+/**
+ * Initialize Firebase Admin SDK
+ */
+function initializeFirebaseAdmin(config) {
+  if (!adminInitialized) {
+    // Check if running in Cloud Run with default credentials
+    if (process.env.K_SERVICE) {
+      admin.initializeApp();
+    } else if (config.serviceAccountPath) {
+      // Use service account file
+      const serviceAccount = require(config.serviceAccountPath);
+      admin.initializeApp({
+        credential: admin.credential.cert(serviceAccount),
+        projectId: config.projectId
+      });
+    } else if (config.serviceAccountJson) {
+      // Use service account JSON from environment variable
+      const serviceAccount = JSON.parse(config.serviceAccountJson);
+      admin.initializeApp({
+        credential: admin.credential.cert(serviceAccount),
+        projectId: config.projectId
+      });
+    } else {
+      throw new Error('Firebase Admin SDK configuration missing');
+    }
+    adminInitialized = true;
+  }
+  return admin.auth();
+}
+
+/**
+ * Authenticate user with email and password
+ * @param {string} email - User email
+ * @param {string} password - User password
+ * @returns {Promise<Object>} - User credential with tokens
+ */
+async function authenticateUser(email, password) {
+  if (!firebaseAuth) {
+    throw new Error('Firebase Auth not initialized');
+  }
+
+  try {
+    const userCredential = await signInWithEmailAndPassword(
+      firebaseAuth,
+      email,
+      password
+    );
+
+    const user = userCredential.user;
+    const idToken = await user.getIdToken();
+    const refreshToken = user.refreshToken;
+
+    return {
+      user: {
+        uid: user.uid,
+        email: user.email,
+        emailVerified: user.emailVerified
+      },
+      idToken,
+      refreshToken
+    };
+  } catch (error) {
+    console.error('Firebase authentication error:', error.code, error.message);
+    throw new Error(`Authentication failed: ${error.message}`);
+  }
+}
+
+/**
+ * Verify Firebase ID token
+ * @param {string} idToken - Firebase ID token
+ * @returns {Promise<Object>} - Decoded token
+ */
+async function verifyIdToken(idToken) {
+  if (!adminInitialized) {
+    throw new Error('Firebase Admin not initialized');
+  }
+
+  try {
+    const decodedToken = await admin.auth().verifyIdToken(idToken);
+    return decodedToken;
+  } catch (error) {
+    console.error('Token verification error:', error.code, error.message);
+    throw new Error(`Token verification failed: ${error.message}`);
+  }
+}
+
+/**
+ * Refresh Firebase tokens using refresh token
+ * @param {string} refreshToken - Firebase refresh token
+ * @returns {Promise<Object>} - New tokens
+ */
+async function refreshTokens(refreshToken) {
+  // Firebase refresh token exchange requires REST API call
+  const apiKey = process.env.FIREBASE_API_KEY;
+  
+  try {
+    const response = await fetch(
+      `https://securetoken.googleapis.com/v1/token?key=${apiKey}`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          grant_type: 'refresh_token',
+          refresh_token: refreshToken
+        })
+      }
+    );
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error?.message || 'Token refresh failed');
+    }
+
+    const data = await response.json();
+    
+    return {
+      idToken: data.id_token,
+      refreshToken: data.refresh_token,
+      expiresIn: parseInt(data.expires_in)
+    };
+  } catch (error) {
+    console.error('Token refresh error:', error.message);
+    throw new Error(`Token refresh failed: ${error.message}`);
+  }
+}
+
+/**
+ * Set custom claims (roles/permissions) for a user
+ * Requires Firebase Admin SDK
+ * @param {string} uid - User's Firebase UID
+ * @param {Object} claims - Custom claims object (e.g., { role: 'admin', permissions: ['read', 'write'] })
+ * @returns {Promise<void>}
+ */
+async function setCustomClaims(uid, claims) {
+  if (!adminInitialized) {
+    throw new Error('Firebase Admin not initialized');
+  }
+
+  try {
+    await admin.auth().setCustomUserClaims(uid, claims);
+    console.log(`Custom claims set for user ${uid}:`, claims);
+  } catch (error) {
+    console.error('Set custom claims error:', error.code, error.message);
+    throw new Error(`Failed to set custom claims: ${error.message}`);
+  }
+}
+
+/**
+ * Get custom claims for a user
+ * @param {string} uid - User's Firebase UID
+ * @returns {Promise<Object>} - User's custom claims
+ */
+async function getCustomClaims(uid) {
+  if (!adminInitialized) {
+    throw new Error('Firebase Admin not initialized');
+  }
+
+  try {
+    const user = await admin.auth().getUser(uid);
+    return user.customClaims || {};
+  } catch (error) {
+    console.error('Get custom claims error:', error.code, error.message);
+    throw new Error(`Failed to get custom claims: ${error.message}`);
+  }
+}
+
+/**
+ * Remove custom claims from a user
+ * @param {string} uid - User's Firebase UID
+ * @returns {Promise<void>}
+ */
+async function removeCustomClaims(uid) {
+  if (!adminInitialized) {
+    throw new Error('Firebase Admin not initialized');
+  }
+
+  try {
+    await admin.auth().setCustomUserClaims(uid, null);
+    console.log(`Custom claims removed for user ${uid}`);
+  } catch (error) {
+    console.error('Remove custom claims error:', error.code, error.message);
+    throw new Error(`Failed to remove custom claims: ${error.message}`);
+  }
+}
+
+/**
+ * Update specific custom claims (merge with existing)
+ * @param {string} uid - User's Firebase UID
+ * @param {Object} newClaims - Claims to add/update
+ * @returns {Promise<void>}
+ */
+async function updateCustomClaims(uid, newClaims) {
+  if (!adminInitialized) {
+    throw new Error('Firebase Admin not initialized');
+  }
+
+  try {
+    const user = await admin.auth().getUser(uid);
+    const currentClaims = user.customClaims || {};
+    const mergedClaims = { ...currentClaims, ...newClaims };
+    
+    await admin.auth().setCustomUserClaims(uid, mergedClaims);
+    console.log(`Custom claims updated for user ${uid}:`, mergedClaims);
+  } catch (error) {
+    console.error('Update custom claims error:', error.code, error.message);
+    throw new Error(`Failed to update custom claims: ${error.message}`);
+  }
+}
+
+module.exports = {
+  initializeFirebaseClient,
+  initializeFirebaseAdmin,
+  authenticateUser,
+  verifyIdToken,
+  refreshTokens,
+  setCustomClaims,
+  getCustomClaims,
+  removeCustomClaims,
+  updateCustomClaims
+};

package/lib/index.js

@@ -0,0 +1,70 @@
+/**
+ * MCP OAuth Middleware - Main Export
+ * Provides OAuth 2.0 middleware for MCP servers using Firebase Auth
+ */
+
+const { createMetadataHandler } = require('./metadata');
+const { createAuthorizeHandler } = require('./authorize');
+const { createTokenHandler } = require('./token');
+const { 
+  initializeFirebaseClient, 
+  initializeFirebaseAdmin,
+  setCustomClaims,
+  getCustomClaims,
+  removeCustomClaims,
+  updateCustomClaims
+} = require('./firebase-client');
+const validateToken = require('../middleware/validate-token');
+const { requireRole, requirePermissions, requireAdmin } = require('../middleware/validate-token');
+
+/**
+ * Create OAuth middleware with configuration
+ * @param {Object} config - Configuration options
+ * @param {Object} config.firebase - Firebase configuration
+ * @param {string} config.firebase.apiKey - Firebase API key
+ * @param {string} config.firebase.authDomain - Firebase auth domain
+ * @param {string} config.firebase.projectId - Firebase project ID
+ * @param {string} config.firebase.serviceAccountPath - Path to service account JSON (optional)
+ * @param {string} config.firebase.serviceAccountJson - Service account JSON string (optional)
+ * @param {string} config.baseUrl - Base URL for OAuth endpoints (optional, auto-detected)
+ * @param {string} config.clientId - OAuth client ID for validation (optional)
+ * @param {string} config.clientSecret - Client secret / user password
+ * @param {string} config.clientEmail - Client email for Firebase auth
+ * @param {string} config.redirectUri - Allowed redirect URI (optional)
+ */
+function createOAuthMiddleware(config) {
+  if (!config || !config.firebase) {
+    throw new Error('Firebase configuration is required');
+  }
+
+  // Initialize Firebase
+  initializeFirebaseClient(config.firebase);
+  initializeFirebaseAdmin(config.firebase);
+
+  // Create handlers
+  const metadata = createMetadataHandler(config);
+  const authorize = createAuthorizeHandler(config);
+  const token = createTokenHandler(config);
+
+  return {
+    metadata,
+    authorize,
+    token,
+    validateToken,
+    requireRole,
+    requirePermissions,
+    requireAdmin
+  };
+}
+
+module.exports = {
+  createOAuthMiddleware,
+  validateToken,
+  requireRole,
+  requirePermissions,
+  requireAdmin,
+  setCustomClaims,
+  getCustomClaims,
+  removeCustomClaims,
+  updateCustomClaims
+};

package/lib/metadata.js

@@ -0,0 +1,36 @@
+/**
+ * OAuth Authorization Server Metadata Endpoint
+ * Returns server metadata according to RFC 8414
+ */
+
+function createMetadataHandler(config) {
+  return (req, res) => {
+    // Auto-detect base URL from request (for Cloud Run)
+    const baseUrl = config.baseUrl || getBaseUrl(req);
+
+    const metadata = {
+      issuer: baseUrl,
+      authorization_endpoint: `${baseUrl}/oauth/authorize`,
+      token_endpoint: `${baseUrl}/oauth/token`,
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      response_types_supported: ['code'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['none'],
+      scopes_supported: ['openid', 'profile', 'email']
+    };
+
+    res.json(metadata);
+  };
+}
+
+/**
+ * Helper to construct base URL from request headers
+ * Works with Cloud Run's X-Forwarded-* headers
+ */
+function getBaseUrl(req) {
+  const protocol = req.get('x-forwarded-proto') || req.protocol || 'https';
+  const host = req.get('host');
+  return `${protocol}://${host}`;
+}
+
+module.exports = { createMetadataHandler, getBaseUrl };

package/lib/pkce.js

@@ -0,0 +1,53 @@
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities
+ * Implements SHA256 validation for OAuth 2.0 PKCE extension
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Validate PKCE code verifier against code challenge
+ * @param {string} codeVerifier - The code verifier from token request
+ * @param {string} codeChallenge - The stored code challenge from authorization request
+ * @param {string} method - Challenge method (should be 'S256')
+ * @returns {boolean} - True if verification succeeds
+ */
+function validatePKCE(codeVerifier, codeChallenge, method = 'S256') {
+  if (method !== 'S256') {
+    throw new Error('Only S256 code challenge method is supported');
+  }
+
+  const hash = crypto
+    .createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url');
+
+  return hash === codeChallenge;
+}
+
+/**
+ * Generate a cryptographically secure random string
+ * @param {number} length - Length in bytes (default 32)
+ * @returns {string} - Base64url encoded random string
+ */
+function generateSecureToken(length = 32) {
+  return crypto.randomBytes(length).toString('base64url');
+}
+
+/**
+ * Generate code challenge from verifier (for testing)
+ * @param {string} codeVerifier - The code verifier
+ * @returns {string} - Base64url encoded SHA256 hash
+ */
+function generateCodeChallenge(codeVerifier) {
+  return crypto
+    .createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url');
+}
+
+module.exports = {
+  validatePKCE,
+  generateSecureToken,
+  generateCodeChallenge
+};

package/lib/storage.js

@@ -0,0 +1,109 @@
+/**
+ * In-Memory Storage for Authorization Codes and State
+ * For production with multiple instances, consider using Redis
+ */
+
+class AuthCodeStorage {
+  constructor() {
+    this.codes = new Map();
+    this.cleanupInterval = null;
+    
+    // Start cleanup interval (every 5 minutes)
+    this.startCleanup();
+  }
+
+  /**
+   * Store authorization code with associated data
+   * @param {string} code - Authorization code
+   * @param {Object} data - Associated data
+   * @param {number} ttl - Time to live in milliseconds (default 10 minutes)
+   */
+  store(code, data, ttl = 10 * 60 * 1000) {
+    this.codes.set(code, {
+      ...data,
+      expiresAt: Date.now() + ttl,
+      used: false
+    });
+  }
+
+  /**
+   * Retrieve and mark code as used (single-use only)
+   * @param {string} code - Authorization code
+   * @returns {Object|null} - Stored data or null if invalid/expired
+   */
+  consume(code) {
+    const data = this.codes.get(code);
+
+    if (!data) {
+      return null;
+    }
+
+    // Check expiration
+    if (Date.now() > data.expiresAt) {
+      this.codes.delete(code);
+      return null;
+    }
+
+    // Check if already used
+    if (data.used) {
+      this.codes.delete(code);
+      return null;
+    }
+
+    // Mark as used and return
+    data.used = true;
+    this.codes.set(code, data);
+    
+    // Delete after short grace period to prevent replay
+    setTimeout(() => this.codes.delete(code), 5000);
+
+    return data;
+  }
+
+  /**
+   * Remove expired codes from storage
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [code, data] of this.codes.entries()) {
+      if (now > data.expiresAt) {
+        this.codes.delete(code);
+      }
+    }
+  }
+
+  /**
+   * Start automatic cleanup interval
+   */
+  startCleanup() {
+    if (this.cleanupInterval) {
+      return;
+    }
+    this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+  }
+
+  /**
+   * Stop cleanup interval (for graceful shutdown)
+   */
+  stopCleanup() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /**
+   * Get storage statistics (for monitoring)
+   */
+  getStats() {
+    return {
+      totalCodes: this.codes.size,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+// Singleton instance
+const storage = new AuthCodeStorage();
+
+module.exports = storage;