@connexa/mcp-oauth-firebase-middleware 1.0.0

package/README.md

@@ -0,0 +1,632 @@
+# MCP OAuth Firebase Middleware
+
+OAuth 2.0 middleware for Model Context Protocol (MCP) servers, using Firebase Authentication as the backend. This middleware translates Claude's OAuth requests into Firebase Auth operations, enabling OAuth-compliant MCP servers.
+
+## Features
+
+✅ **OAuth 2.0 Compliant** - Implements authorization code flow with PKCE  
+✅ **Firebase Auth Backend** - Uses Firebase for user authentication and token management  
+✅ **Token Validation** - Middleware for protecting MCP endpoints  
+✅ **Role-Based Access Control** - Built-in support for roles and permissions via Firebase custom claims  
+✅ **Easy Integration** - Drop-in middleware for Express.js applications  
+✅ **Automatic Token Refresh** - Supports refresh token grant type  
+
+## Architecture
+
+```
+┌─────────────┐         ┌──────────────────┐         ┌──────────────┐
+│   Claude    │ OAuth   │  This Middleware │ Firebase│   Firebase   │
+│   Desktop   │────────▶│  (OAuth Layer)   │────────▶│     Auth     │
+└─────────────┘         └──────────────────┘         └──────────────┘
+```
+
+The middleware implements three core OAuth 2.0 endpoints:
+- `GET /.well-known/oauth-authorization-server` - Server metadata
+- `GET /oauth/authorize` - Authorization endpoint
+- `POST /oauth/token` - Token exchange and refresh
+
+## Installation
+
+```bash
+npm install @connexa/mcp-oauth-firebase-middleware
+```
+
+## Prerequisites
+
+- Node.js 18+
+- Express.js application
+- Firebase project with Authentication enabled
+- Firebase service account credentials
+
+## Quick Start
+
+### 1. Set Up Firebase
+
+1. Create a Firebase project at [console.firebase.google.com](https://console.firebase.google.com)
+2. Enable **Email/Password** authentication
+3. Create a test user in Firebase Authentication
+4. Download service account key:
+   - Go to Project Settings → Service Accounts
+   - Click "Generate New Private Key"
+   - Save as `serviceAccountKey.json`
+
+### 2. Basic Integration
+
+```javascript
+const express = require('express');
+const { createOAuthMiddleware } = require('@connexa/mcp-oauth-firebase-middleware');
+
+const app = express();
+
+// Create OAuth middleware
+const oauth = createOAuthMiddleware({
+  firebase: {
+    apiKey: process.env.FIREBASE_API_KEY,
+    authDomain: process.env.FIREBASE_AUTH_DOMAIN,
+    projectId: process.env.FIREBASE_PROJECT_ID,
+    serviceAccountPath: './serviceAccountKey.json'
+  },
+  baseUrl: process.env.BASE_URL || 'https://your-app.com',
+  clientSecret: process.env.OAUTH_CLIENT_SECRET,
+  clientEmail: process.env.OAUTH_CLIENT_EMAIL
+});
+
+// Add OAuth endpoints
+app.get('/.well-known/oauth-authorization-server', oauth.metadata);
+app.get('/oauth/authorize', oauth.authorize);
+app.post('/oauth/token', oauth.token);
+
+// Protect your MCP endpoints
+app.post('/mcp', oauth.validateToken, (req, res) => {
+  // Your MCP handler - req.user contains authenticated user info
+  res.json({ 
+    message: 'Protected endpoint',
+    user: req.user 
+  });
+});
+
+app.listen(8080);
+```
+
+### 3. Configure Environment
+
+Create a `.env` file:
+
+```env
+FIREBASE_API_KEY=your_api_key
+FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
+FIREBASE_PROJECT_ID=your-project-id
+BASE_URL=https://your-app.com
+OAUTH_CLIENT_SECRET=user_password
+OAUTH_CLIENT_EMAIL=user@example.com
+```
+
+
+## API Reference
+
+### createOAuthMiddleware(config)
+
+Creates OAuth middleware instance with handlers for all OAuth endpoints.
+
+**Parameters:**
+
+```javascript
+{
+  firebase: {
+    apiKey: string,              // Firebase API key
+    authDomain: string,          // Firebase auth domain
+    projectId: string,           // Firebase project ID
+    serviceAccountPath: string,  // Path to service account JSON (optional)
+    serviceAccountJson: string   // Service account JSON string (optional)
+  },
+  baseUrl: string,              // Base URL for OAuth endpoints (optional, auto-detected)
+  clientId: string,             // OAuth client ID for validation (optional)
+  clientSecret: string,         // User password for Firebase auth
+  clientEmail: string,          // User email for Firebase auth
+  redirectUri: string           // Allowed redirect URI (optional)
+}
+```
+
+**Returns:**
+
+```javascript
+{
+  metadata: Function,        // GET /.well-known/oauth-authorization-server
+  authorize: Function,       // GET /oauth/authorize
+  token: Function,          // POST /oauth/token
+  validateToken: Function   // Middleware for protecting endpoints
+}
+```
+
+### validateToken Middleware
+
+Express middleware that validates Firebase ID tokens from the `Authorization` header.
+
+**Usage:**
+
+```javascript
+// Basic usage - any authenticated user
+app.post('/protected', oauth.validateToken(), (req, res) => {
+  // req.user contains:
+  // - uid: User's Firebase UID
+  // - email: User's email
+  // - emailVerified: Email verification status
+  // - role: User's role (from custom claims)
+  // - permissions: Array of user permissions (from custom claims)
+  // - customClaims: Full decoded token with all custom claims
+});
+
+// Require specific role
+app.get('/admin', oauth.validateToken({ role: 'admin' }), handler);
+
+// Require specific permission(s)
+app.post('/write', oauth.validateToken({ permissions: 'write' }), handler);
+app.delete('/item', oauth.validateToken({ permissions: ['write', 'delete'] }), handler);
+
+// Custom validation
+app.get('/premium', oauth.validateToken({
+  customCheck: (token) => token.subscriptionTier === 'premium'
+}), handler);
+```
+
+**Convenience Methods:**
+
+```javascript
+// Require specific role
+app.get('/admin', oauth.requireRole('admin'), handler);
+
+// Require admin role
+app.get('/admin', oauth.requireAdmin(), handler);
+
+// Require permission(s)
+app.post('/write', oauth.requirePermissions('write'), handler);
+app.delete('/item', oauth.requirePermissions(['write', 'delete']), handler);
+```
+
+**Error Response:**
+
+Returns `401 Unauthorized` with `WWW-Authenticate` header if token is invalid or missing.
+Returns `403 Forbidden` if user lacks required role/permissions.
+
+### Custom Claims Management
+
+Helper functions for managing user roles and permissions:
+
+```javascript
+const { setCustomClaims, getCustomClaims, updateCustomClaims } = require('@connexa/mcp-oauth-firebase-middleware');
+
+// Set complete custom claims
+await setCustomClaims('user-uid', {
+  role: 'admin',
+  permissions: ['read', 'write', 'delete']
+});
+
+// Get user's custom claims
+const claims = await getCustomClaims('user-uid');
+// Returns: { role: 'admin', permissions: [...] }
+
+// Update specific claims (merges with existing)
+await updateCustomClaims('user-uid', {
+  permissions: ['read', 'write', 'delete', 'manage']
+});
+
+// Remove all custom claims
+await removeCustomClaims('user-uid');
+```
+
+## OAuth Endpoints
+
+#### Server Metadata
+```http
+GET /.well-known/oauth-authorization-server
+```
+
+Returns OAuth server configuration.
+
+#### Authorization
+```http
+GET /oauth/authorize?client_id=...&code_challenge=...&code_challenge_method=S256&redirect_uri=...&response_type=code&state=...
+```
+
+Authenticates user and returns authorization code.
+
+#### Token Exchange
+```http
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&code=...&client_id=...&code_verifier=...&redirect_uri=...
+```
+
+Exchanges authorization code for access token.
+
+#### Token Refresh
+```http
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token&refresh_token=...&client_id=...
+```
+
+Refreshes expired access token.
+
+### Protected Endpoints
+
+#### MCP Handler (Example)
+```http
+POST /mcp
+Authorization: Bearer <access_token>
+
+{
+  "jsonrpc": "2.0",
+  "method": "your_method",
+  "params": {},
+  "id": 1
+}
+```
+
+#### Resources (Example)
+```http
+GET /resources
+Authorization: Bearer <access_token>
+```
+
+### Utility Endpoints
+
+#### Health Check
+```http
+GET /health
+```
+
+Returns server status.
+
+## Example Server
+
+The package includes an example server (`server.js`) for testing:
+
+```bash
+npm start
+```
+
+This runs a complete OAuth server on `http://localhost:8080` with example protected endpoints.
+
+## Advanced Usage
+
+### Custom Client Validation
+
+Implement database-backed client validation:
+
+```javascript
+const oauth = createOAuthMiddleware({
+  firebase: { /* ... */ },
+  validateClient: async (clientId, redirectUri) => {
+    const client = await db.clients.findOne({ clientId });
+    return client && client.redirectUris.includes(redirectUri);
+  }
+});
+```
+
+### Using Service Account JSON from Environment
+
+For cloud deployments, pass service account as JSON string:
+
+```javascript
+const oauth = createOAuthMiddleware({
+  firebase: {
+    apiKey: process.env.FIREBASE_API_KEY,
+    authDomain: process.env.FIREBASE_AUTH_DOMAIN,
+    projectId: process.env.FIREBASE_PROJECT_ID,
+    serviceAccountJson: process.env.FIREBASE_SERVICE_ACCOUNT_JSON
+  }
+});
+```
+
+### Auto-Detecting Base URL
+
+When deployed (e.g., on Cloud Run), the middleware auto-detects the base URL from request headers:
+
+```javascript
+const oauth = createOAuthMiddleware({
+  firebase: { /* ... */ },
+  // baseUrl omitted - will auto-detect from x-forwarded-proto and host headers
+});
+```
+
+## Role-Based Access Control (RBAC)
+
+This middleware supports role-based and permission-based access control using Firebase custom claims.
+
+### Setting Up Roles and Permissions
+
+Custom claims are stored directly in the Firebase user token and are automatically included when the token is validated. They must be set using the Firebase Admin SDK:
+
+```javascript
+const { setCustomClaims } = require('@connexa/mcp-oauth-firebase-middleware');
+
+// Set user role and permissions
+await setCustomClaims('user-firebase-uid', {
+  role: 'admin',
+  permissions: ['read', 'write', 'delete'],
+  subscriptionTier: 'premium' // Any custom data
+});
+```
+
+**Important:** After setting custom claims, users must refresh their tokens (or wait up to 1 hour for automatic refresh) to see the changes. Users can force a refresh by:
+- Logging out and back in
+- Calling `user.getIdToken(true)` on the client
+
+### Using Roles in Your Application
+
+```javascript
+const { createOAuthMiddleware, setCustomClaims } = require('@connexa/mcp-oauth-firebase-middleware');
+
+// Method 1: Using validateToken with options
+app.get('/admin/dashboard', oauth.validateToken({ role: 'admin' }), (req, res) => {
+  res.json({ message: 'Admin dashboard', user: req.user });
+});
+
+// Method 2: Using convenience helpers
+app.get('/admin/users', oauth.requireAdmin(), handler);
+app.get('/editor/content', oauth.requireRole('editor'), handler);
+
+// Method 3: Using permissions
+app.post('/api/write', oauth.requirePermissions('write'), handler);
+app.delete('/api/item', oauth.requirePermissions(['write', 'delete']), handler);
+
+// Method 4: Custom validation logic
+app.get('/premium/feature', oauth.validateToken({
+  customCheck: (token) => {
+    return token.subscriptionTier === 'premium' && token.emailVerified;
+  }
+}), handler);
+
+// Method 5: Manual check in handler
+app.get('/resource', oauth.validateToken(), (req, res) => {
+  if (req.user.role !== 'admin' && !req.user.permissions.includes('read')) {
+    return res.status(403).json({ error: 'Insufficient permissions' });
+  }
+  
+  res.json({ data: 'sensitive data' });
+});
+```
+
+### Role Management Endpoints
+
+Create admin endpoints to manage user roles:
+
+```javascript
+const { setCustomClaims, getCustomClaims } = require('@connexa/mcp-oauth-firebase-middleware');
+
+// Set user role (admin only)
+app.post('/admin/users/:uid/role', oauth.requireAdmin(), async (req, res) => {
+  const { uid } = req.params;
+  const { role, permissions } = req.body;
+  
+  await setCustomClaims(uid, { role, permissions });
+  res.json({ message: 'Role updated', uid, role, permissions });
+});
+
+// Get user's current role
+app.get('/admin/users/:uid/role', oauth.requireAdmin(), async (req, res) => {
+  const claims = await getCustomClaims(req.params.uid);
+  res.json(claims);
+});
+```
+
+### Common Role Patterns
+
+```javascript
+// Basic roles
+const roles = {
+  USER: 'user',
+  EDITOR: 'editor',
+  ADMIN: 'admin',
+  SUPER_ADMIN: 'super_admin'
+};
+
+// Permission-based (more flexible)
+const permissions = {
+  READ: 'read',
+  WRITE: 'write',
+  DELETE: 'delete',
+  MANAGE_USERS: 'manage_users',
+  MANAGE_SETTINGS: 'manage_settings'
+};
+
+// Set permissions by role
+await setCustomClaims(userId, {
+  role: 'editor',
+  permissions: ['read', 'write']
+});
+
+await setCustomClaims(adminId, {
+  role: 'admin',
+  permissions: ['read', 'write', 'delete', 'manage_users']
+});
+```
+
+### Best Practices
+
+1. **Use permissions over roles** when possible for more granular control
+2. **Keep custom claims under 1000 bytes** (Firebase limit)
+3. **Cache role checks** at the application level if needed for performance
+4. **Implement role hierarchy** in your application logic if needed
+5. **Always validate on the server** - never trust client-side role checks
+6. **Log role changes** for audit trails
+7. **Force token refresh** after role updates for immediate effect
+
+## Project Structure
+
+```
+mcp-oauth-firebase-middleware/
+├── lib/
+│   ├── index.js              # Main module export
+│   ├── metadata.js           # OAuth metadata endpoint
+│   ├── authorize.js          # Authorization endpoint
+│   ├── token.js              # Token endpoint
+│   ├── firebase-client.js    # Firebase Auth operations
+│   ├── pkce.js              # PKCE utilities
+│   └── storage.js           # Authorization code storage
+├── middleware/
+│   └── validate-token.js    # Token validation middleware
+├── server.js                # Example Express server
+├── package.json
+├── .env.example
+└── README.md
+```
+
+## Security Considerations
+
+🔒 **PKCE Required** - All authorization requests must use PKCE with S256  
+🔒 **Single-Use Codes** - Authorization codes are invalidated after use  
+🔒 **Code Expiration** - Authorization codes expire after 10 minutes  
+🔒 **HTTPS Only** - All production endpoints must use HTTPS  
+🔒 **Token Verification** - All protected endpoints validate Firebase ID tokens  
+
+## Publishing to npm
+
+1. Update `package.json` with your details:
+   - Set `author` field
+   - Update `repository` URL
+   - Choose appropriate `name` (check availability on npm)
+
+2. Login to npm:
+   ```bash
+   npm login
+   ```
+
+3. Publish:
+   ```bash
+   npm publish
+   ```
+
+The `files` field in `package.json` ensures only necessary files are included in the package.
+
+## Development
+
+### Running the Example Server
+
+```bash
+# Install dependencies
+npm install
+
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your Firebase credentials
+
+# Run server
+npm start
+```
+
+### Testing with MCP Inspector
+
+1. Install MCP Inspector:
+```bash
+npm install -g @modelcontextprotocol/inspector
+```
+
+2. Test OAuth flow:
+```bash
+mcp-inspector http://localhost:8080
+```
+
+3. Verify:
+   - ✅ Metadata endpoint returns correct URLs
+   - ✅ Authorization redirects with code
+   - ✅ Token exchange returns valid tokens
+   - ✅ Protected endpoints accept access token
+   - ✅ Token refresh works
+
+## Project Structure
+
+```
+mcp-oauth-firebase-middleware/
+├── lib/
+│   ├── index.js              # Main module export
+│   ├── metadata.js           # OAuth metadata endpoint
+│   ├── authorize.js          # Authorization endpoint
+│   ├── token.js              # Token endpoint
+│   ├── firebase-client.js    # Firebase Auth operations
+│   ├── pkce.js              # PKCE utilities
+│   └── storage.js           # Authorization code storage
+├── middleware/
+│   └── validate-token.js    # Token validation middleware
+├── server.js                # Example Express server
+├── package.json
+├── .env.example
+└── README.md
+```
+
+## Security Considerations
+
+🔒 **PKCE Required** - All authorization requests must use PKCE with S256  
+🔒 **Single-Use Codes** - Authorization codes are invalidated after use  
+🔒 **Code Expiration** - Authorization codes expire after 10 minutes  
+🔒 **HTTPS Only** - All production endpoints must use HTTPS  
+🔒 **Token Verification** - All protected endpoints validate Firebase ID tokens  
+
+## Publishing to npm
+
+1. Update `package.json` with your details:
+   - Set `author` field
+   - Update `repository` URL
+   - Choose appropriate `name` (check availability on npm)
+
+2. Login to npm:
+   ```bash
+   npm login
+   ```
+
+3. Publish:
+   ```bash
+   npm publish
+   ```
+
+The `files` field in `package.json` ensures only necessary files are included in the package.
+
+## Development
+
+### Running the Example Server
+
+```bash
+# Install dependencies
+npm install
+
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your Firebase credentials
+
+# Run server
+npm start
+```
+
+### Testing with MCP Inspector
+
+## Troubleshooting
+
+### Firebase Authentication Error
+- Verify Firebase credentials in `.env`
+- Ensure user exists in Firebase Authentication
+- Check that Email/Password provider is enabled
+
+### PKCE Validation Failed
+- Ensure client is using S256 method
+- Verify code_verifier matches code_challenge
+
+### Token Verification Failed
+- Check Firebase Admin SDK is initialized correctly
+- Verify service account has proper permissions
+- Ensure token hasn't expired (3600s lifetime)
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- Check [MCP Documentation](https://modelcontextprotocol.io)
+- Review Firebase Auth [documentation](https://firebase.google.com/docs/auth)
+- Open an issue in this repository