oauth wip

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

.env.oauth.example

@@ -0,0 +1,47 @@
+# OAuth Configuration for Basic Memory MCP Server
+# Copy this file to .env and update the values
+
+# Enable OAuth authentication
+FASTMCP_AUTH_ENABLED=true
+
+# OAuth provider type: basic, github, or google
+# - basic: Built-in OAuth provider with in-memory storage
+# - github: Integrate with GitHub OAuth
+# - google: Integrate with Google OAuth  
+FASTMCP_AUTH_PROVIDER=basic
+
+# OAuth issuer URL (your MCP server URL)
+FASTMCP_AUTH_ISSUER_URL=http://localhost:8000
+
+# Documentation URL for OAuth endpoints
+FASTMCP_AUTH_DOCS_URL=http://localhost:8000/docs/oauth
+
+# Required scopes (comma-separated)
+# Examples: read,write,admin
+FASTMCP_AUTH_REQUIRED_SCOPES=read,write
+
+# Secret key for JWT tokens (auto-generated if not set)
+# FASTMCP_AUTH_SECRET_KEY=your-secret-key-here
+
+# Enable client registration endpoint
+FASTMCP_AUTH_CLIENT_REGISTRATION_ENABLED=true
+
+# Enable token revocation endpoint  
+FASTMCP_AUTH_REVOCATION_ENABLED=true
+
+# Default scopes for new clients
+FASTMCP_AUTH_DEFAULT_SCOPES=read
+
+# Valid scopes that can be requested
+FASTMCP_AUTH_VALID_SCOPES=read,write,admin
+
+# Client secret expiry in seconds (optional)
+# FASTMCP_AUTH_CLIENT_SECRET_EXPIRY=86400
+
+# GitHub OAuth settings (if using github provider)
+# GITHUB_CLIENT_ID=your-github-client-id
+# GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# Google OAuth settings (if using google provider)
+# GOOGLE_CLIENT_ID=your-google-client-id  
+# GOOGLE_CLIENT_SECRET=your-google-client-secret

AUTH.md

@@ -0,0 +1,147 @@
+To test the built-in OAuth flow locally, here's what you need to do:
+
+1. Set Environment Variables
+
+  First, create a .env file based on the example:
+
+  cp .env.oauth.example .env
+
+  Then edit .env to enable OAuth:
+
+  # Enable OAuth authentication
+  FASTMCP_AUTH_ENABLED=true
+
+  # Use the basic (built-in) provider
+  FASTMCP_AUTH_PROVIDER=basic
+
+  # OAuth issuer URL (your MCP server URL)
+  FASTMCP_AUTH_ISSUER_URL=http://localhost:8000
+
+2. Start the MCP Server with OAuth
+
+  Start the server using the streamable-http transport (OAuth works best with HTTP):
+
+  # Run with OAuth enabled
+  FASTMCP_AUTH_ENABLED=true basic-memory mcp --transport streamable-http
+
+  # Or if you have the env vars in .env file:
+  basic-memory mcp --transport streamable-http
+
+  You should see:
+  OAuth authentication is ENABLED
+  Issuer URL: http://localhost:8000
+
+3. Register an OAuth Client
+
+  In a new terminal, register a test client:
+
+  basic-memory auth register-client
+
+  This will output something like:
+  Client registered successfully!
+  Client ID: AbCdEfGhIjKlMnOp
+  Client Secret: QrStUvWxYz123456789...
+
+  Save these credentials!
+
+4. Test the OAuth Flow
+
+  Run the built-in test command:
+
+  basic-memory auth test-auth
+
+  This will:
+1. Register a test client
+2. Generate an authorization URL
+3. Exchange the auth code for tokens
+4. Validate the access token
+
+  You'll see output like:
+  Registered test client: ABC123...
+  Authorization URL: http://localhost:3000/callback?code=XYZ&state=test-state
+  Access token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+  Refresh token: QrStUvWxYz...
+  Expires in: 3600 seconds
+  Access token validated successfully!
+
+5. Test with a Real Client
+
+  To test with an actual MCP client, you'll need to:
+
+1. Make an authorization request:
+  # Use the client_id from step 3
+  curl "http://localhost:8000/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback&response_type=code&code_challenge=test-challenge&code_challenge_method=S256"
+
+2. Exchange the code for tokens:
+  # Use the code from the redirect URL
+  curl -X POST http://localhost:8000/token \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    -d "grant_type=authorization_code&code=YOUR_AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code_verifier=test-verifier"
+
+3. Use the access token to call MCP endpoints:
+curl http://localhost:8000/mcp \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+
+6. Quick Test Script
+
+  Here's a simple Python script to test the flow:
+
+  import httpx
+  import asyncio
+  from urllib.parse import urlparse, parse_qs
+
+  async def test_oauth():
+      client = httpx.AsyncClient()
+
+      # Your client credentials
+      client_id = "YOUR_CLIENT_ID"
+      client_secret = "YOUR_CLIENT_SECRET"
+
+      # 1. Get authorization URL
+      auth_response = await client.get(
+          "http://localhost:8000/authorize",
+          params={
+              "client_id": client_id,
+              "redirect_uri": "http://localhost:3000/callback",
+              "response_type": "code",
+              "code_challenge": "test-challenge",
+              "code_challenge_method": "S256",
+          }
+      )
+
+      # Extract code from redirect
+      redirect_url = auth_response.headers.get("Location")
+      parsed = urlparse(redirect_url)
+      code = parse_qs(parsed.query)["code"][0]
+
+      # 2. Exchange code for tokens
+      token_response = await client.post(
+          "http://localhost:8000/token",
+          data={
+              "grant_type": "authorization_code",
+              "code": code,
+              "client_id": client_id,
+              "client_secret": client_secret,
+              "code_verifier": "test-verifier",
+          }
+      )
+      tokens = token_response.json()
+
+      # 3. Use access token
+      mcp_response = await client.get(
+          "http://localhost:8000/mcp",
+          headers={"Authorization": f"Bearer {tokens['access_token']}"}
+      )
+
+      print(f"MCP Response: {mcp_response.status_code}")
+
+  asyncio.run(test_oauth())
+
+7. Debug Tips
+
+- Check the server logs for OAuth-related messages
+- The basic provider stores everything in memory, so clients/tokens are lost on restart
+- You can modify the log level for more details:
+FASTMCP_AUTH_ENABLED=true basic-memory mcp --transport streamable-http
+
+  That's it! The built-in OAuth provider is perfect for local development and testing. For production, you'd want to use an external provider (GitHub/Google) or implement persistent storage for the basic provider.

docs/OAuth Authentication.md

@@ -0,0 +1,187 @@
+# OAuth Authentication for Basic Memory MCP Server
+
+Basic Memory supports OAuth 2.1 authentication for secure access to the MCP server. This guide explains how to configure and use OAuth authentication.
+
+## Overview
+
+OAuth support in Basic Memory includes:
+- Built-in OAuth provider with in-memory storage
+- Integration with external OAuth providers (GitHub, Google)
+- OAuth client management via CLI
+- Support for PKCE (Proof Key for Code Exchange)
+- Token validation and revocation
+
+## Configuration
+
+### Environment Variables
+
+Copy `.env.oauth.example` to `.env` and configure:
+
+```bash
+# Enable OAuth authentication
+FASTMCP_AUTH_ENABLED=true
+
+# OAuth provider type: basic, github, or google
+FASTMCP_AUTH_PROVIDER=basic
+
+# OAuth issuer URL (your MCP server URL)
+FASTMCP_AUTH_ISSUER_URL=http://localhost:8000
+
+# Required scopes (comma-separated)
+FASTMCP_AUTH_REQUIRED_SCOPES=read,write
+```
+
+### Provider Types
+
+1. **Basic Provider** (default)
+   - Built-in OAuth implementation
+   - In-memory storage (not suitable for production)
+   - Good for development and testing
+
+2. **GitHub Provider**
+   - Integrates with GitHub OAuth
+   - Requires GitHub OAuth app configuration
+   - Set `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`
+
+3. **Google Provider**
+   - Integrates with Google OAuth
+   - Requires Google OAuth app configuration  
+   - Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
+
+## Usage
+
+### Start the MCP Server with OAuth
+
+```bash
+# Start with OAuth enabled
+FASTMCP_AUTH_ENABLED=true bm mcp
+
+# Check OAuth status
+# The server will display:
+# "OAuth authentication is ENABLED"
+# "Issuer URL: http://localhost:8000"
+```
+
+### Managing OAuth Clients
+
+Register a new OAuth client:
+
+```bash
+# Auto-generate client credentials
+bm auth register-client
+
+# Specify custom client ID
+bm auth register-client --client-id my-client-id
+```
+
+Test the OAuth flow:
+
+```bash
+bm auth test-auth
+```
+
+### OAuth Flow
+
+1. **Authorization Request**
+   ```
+   GET /authorize?client_id=xxx&redirect_uri=xxx&response_type=code&state=xxx&code_challenge=xxx
+   ```
+
+2. **Token Exchange**
+   ```
+   POST /token
+   Content-Type: application/x-www-form-urlencoded
+   
+   grant_type=authorization_code&code=xxx&client_id=xxx&client_secret=xxx
+   ```
+
+3. **Access Protected Resources**
+   ```
+   GET /mcp
+   Authorization: Bearer <access_token>
+   ```
+
+4. **Refresh Token**
+   ```
+   POST /token
+   grant_type=refresh_token&refresh_token=xxx&client_id=xxx&client_secret=xxx
+   ```
+
+## HTTP Transport with OAuth
+
+When using streamable-http transport with OAuth:
+
+```bash
+# Start server with OAuth
+FASTMCP_AUTH_ENABLED=true bm mcp --transport streamable-http --host 0.0.0.0 --port 8000
+
+# The server provides these endpoints:
+# - /authorize - OAuth authorization
+# - /token - Token exchange
+# - /mcp - Protected MCP endpoint
+```
+
+## Security Considerations
+
+1. **HTTPS Required**: Always use HTTPS in production
+2. **Secret Storage**: Store client secrets securely
+3. **Token Expiration**: Access tokens expire after 1 hour
+4. **Scope Validation**: Configure required scopes appropriately
+5. **PKCE**: Always use PKCE for enhanced security
+
+## External Provider Setup
+
+### GitHub OAuth
+
+1. Create a GitHub OAuth App:
+   - Go to GitHub Settings > Developer settings > OAuth Apps
+   - Create new OAuth App
+   - Set Authorization callback URL to `http://localhost:8000/callback`
+
+2. Configure environment:
+   ```bash
+   FASTMCP_AUTH_PROVIDER=github
+   GITHUB_CLIENT_ID=your-client-id
+   GITHUB_CLIENT_SECRET=your-client-secret
+   ```
+
+### Google OAuth
+
+1. Create Google OAuth credentials:
+   - Go to Google Cloud Console
+   - Create OAuth 2.0 Client ID
+   - Add redirect URI: `http://localhost:8000/callback`
+
+2. Configure environment:
+   ```bash
+   FASTMCP_AUTH_PROVIDER=google
+   GOOGLE_CLIENT_ID=your-client-id
+   GOOGLE_CLIENT_SECRET=your-client-secret
+   ```
+
+## Development
+
+For development, use the basic provider with test clients:
+
+```bash
+# Enable OAuth with basic provider
+FASTMCP_AUTH_ENABLED=true FASTMCP_AUTH_PROVIDER=basic bm mcp
+
+# Register test client
+bm auth register-client
+
+# Test the flow
+bm auth test-auth
+```
+
+## Troubleshooting
+
+- **401 Unauthorized**: Check token validity and expiration
+- **403 Forbidden**: Verify required scopes are present
+- **Invalid client**: Ensure client credentials are correct
+- **Token expired**: Use refresh token to get new access token
+
+## API Reference
+
+See the MCP Authorization specification:
+https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization