matimo 0.1.0-alpha.1

package/docs/tool-development/PROVIDER_CONFIGURATION.md

@@ -0,0 +1,458 @@
+# Provider Configuration Guide
+
+## Overview
+
+Matimo uses a **configuration-driven** approach to OAuth2 provider endpoints. Instead of hardcoding provider information into the application, all provider definitions are stored in **YAML files**. This enables:
+
+- ✅ Support for **infinite providers** without code changes
+- ✅ **Configuration-driven design** - no coupling between code and provider endpoints
+- ✅ **Easy customization** - override endpoints via environment variables or runtime config
+- ✅ **Zero code modifications** - users can add new providers just by creating YAML files
+
+## Provider Definition Structure
+
+Each OAuth2 provider must have a `definition.yaml` file in its provider folder:
+
+```
+tools/
+├── gmail/
+│   └── definition.yaml          ← Provider definition
+├── github/
+│   └── definition.yaml
+├── slack/
+│   └── definition.yaml
+└── [your-provider]/
+    └── definition.yaml
+```
+
+### Provider Definition Format
+
+```yaml
+name: google-provider           # Unique name for this provider definition
+type: provider                  # MUST be "provider" to indicate this is an OAuth2 config
+version: '1.0.0'               # Semantic version of the provider config
+description: Google OAuth2 provider  # Optional description
+
+provider:
+  name: google                  # Provider identifier (used in code)
+  displayName: Google           # Human-readable name
+  
+  endpoints:
+    authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
+    tokenUrl: https://oauth2.googleapis.com/token
+    revokeUrl: https://oauth2.googleapis.com/revoke  # Optional
+  
+  defaultScopes:                # Optional default scopes
+    - https://www.googleapis.com/auth/gmail.send
+    - https://www.googleapis.com/auth/gmail.readonly
+  
+  documentation: https://developers.google.com/identity/protocols/oauth2
+```
+
+## Configuration Priority
+
+Matimo resolves OAuth2 endpoints using a **3-tier priority system**:
+
+### 1. Runtime Configuration (Highest Priority)
+User provides endpoints directly in code:
+
+```typescript
+const oauth2 = new OAuth2Handler({
+  provider: 'google',
+  clientId: '...',
+  clientSecret: '...',
+  redirectUri: '...',
+  endpoints: {  // ← These override everything else
+    authorizationUrl: 'https://custom.company.com/auth',
+    tokenUrl: 'https://custom.company.com/token',
+  }
+});
+```
+
+**Use case:** Custom or internal OAuth2 servers
+
+### 2. Environment Variables (Medium Priority)
+Deploy-time configuration via environment variables:
+
+```bash
+export OAUTH_GOOGLE_AUTH_URL=https://custom.company.com/auth
+export OAUTH_GOOGLE_TOKEN_URL=https://custom.company.com/token
+export OAUTH_GOOGLE_REVOKE_URL=https://custom.company.com/revoke
+```
+
+**Use case:** Different endpoints per deployment (dev, staging, prod)
+
+### 3. YAML Configuration (Default)
+Default endpoints defined in `tools/[provider]/definition.yaml`:
+
+```yaml
+provider:
+  endpoints:
+    authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
+    tokenUrl: https://oauth2.googleapis.com/token
+```
+
+**Use case:** Standard provider defaults
+
+### Resolution Example
+
+```typescript
+// If config.endpoints is provided → Use that (Priority 1)
+const handler = new OAuth2Handler({
+  provider: 'google',
+  clientId: '...',
+  endpoints: { authorizationUrl: 'https://custom/auth', ... }  // ← Used
+});
+
+// Else if OAUTH_GOOGLE_AUTH_URL env var is set → Use that (Priority 2)
+process.env.OAUTH_GOOGLE_AUTH_URL = 'https://custom/auth';
+const handler = new OAuth2Handler({
+  provider: 'google',
+  clientId: '...',
+  // No endpoints provided, env var checked
+});
+
+// Else use tools/google/definition.yaml (Priority 3)
+const handler = new OAuth2Handler({
+  provider: 'google',
+  clientId: '...',
+  // No endpoints or env vars, loads from YAML
+});
+```
+
+## Adding a New Provider
+
+### Step 1: Create Provider Definition File
+
+Create `tools/[provider-name]/definition.yaml`:
+
+```yaml
+name: microsoft-provider
+type: provider
+version: '1.0.0'
+description: Microsoft Azure AD OAuth2 provider
+
+provider:
+  name: microsoft
+  displayName: Microsoft
+  
+  endpoints:
+    authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
+    tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
+    revokeUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token/revoke
+  
+  defaultScopes:
+    - https://graph.microsoft.com/Mail.Send
+    - https://graph.microsoft.com/user.read
+  
+  documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
+```
+
+### Step 2: Use in Code
+
+The provider loader automatically discovers the provider:
+
+```typescript
+import { OAuth2Handler } from '@matimo/oauth2';
+
+const oauth2 = new OAuth2Handler({
+  provider: 'microsoft',  // Provider name from definition.yaml
+  clientId: process.env.MICROSOFT_CLIENT_ID,
+  clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
+  redirectUri: 'http://localhost:3000/callback',
+});
+
+// Get authorization URL
+const authUrl = oauth2.getAuthorizationUrl({
+  scopes: ['https://graph.microsoft.com/Mail.Send'],
+  userId: 'user-123',
+});
+```
+
+### Step 3: (Optional) Override with Environment Variables
+
+For deployment-specific endpoints:
+
+```bash
+export OAUTH_MICROSOFT_AUTH_URL=https://custom-idp.company.com/authorize
+export OAUTH_MICROSOFT_TOKEN_URL=https://custom-idp.company.com/token
+export OAUTH_MICROSOFT_REVOKE_URL=https://custom-idp.company.com/revoke
+```
+
+## Built-in Provider Examples
+
+### Google (Gmail)
+
+**File:** `tools/gmail/definition.yaml`
+
+```yaml
+name: google-provider
+type: provider
+version: '1.0.0'
+
+provider:
+  name: google
+  displayName: Google
+  
+  endpoints:
+    authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
+    tokenUrl: https://oauth2.googleapis.com/token
+    revokeUrl: https://oauth2.googleapis.com/revoke
+  
+  defaultScopes:
+    - https://www.googleapis.com/auth/gmail.send
+    - https://www.googleapis.com/auth/gmail.readonly
+    - https://www.googleapis.com/auth/gmail.compose
+  
+  documentation: https://developers.google.com/identity/protocols/oauth2
+```
+
+### GitHub
+
+**File:** `tools/github/definition.yaml`
+
+```yaml
+name: github-provider
+type: provider
+version: '1.0.0'
+
+provider:
+  name: github
+  displayName: GitHub
+  
+  endpoints:
+    authorizationUrl: https://github.com/login/oauth/authorize
+    tokenUrl: https://github.com/login/oauth/access_token
+  
+  defaultScopes:
+    - user:email
+    - repo
+    - gist
+  
+  documentation: https://docs.github.com/en/developers/apps/building-oauth-apps
+```
+
+### Slack
+
+**File:** `tools/slack/definition.yaml`
+
+```yaml
+name: slack-provider
+type: provider
+version: '1.0.0'
+
+provider:
+  name: slack
+  displayName: Slack
+  
+  endpoints:
+    authorizationUrl: https://slack.com/oauth/v2/authorize
+    tokenUrl: https://slack.com/api/oauth.v2.access
+  
+  defaultScopes:
+    - chat:write
+    - channels:read
+    - users:read
+  
+  documentation: https://api.slack.com/authentication/oauth-v2
+```
+
+## Token Management
+
+Matimo handles OAuth2 flows but **does NOT store tokens**. Token storage is your responsibility:
+
+```typescript
+import { OAuth2Handler } from '@matimo/oauth2';
+
+// 1. Initialize handler
+const oauth2 = new OAuth2Handler({
+  provider: 'google',
+  clientId: '...',
+  clientSecret: '...',
+  redirectUri: 'http://localhost:3000/callback',
+});
+
+// 2. Generate auth URL
+const authUrl = oauth2.getAuthorizationUrl({
+  scopes: ['https://www.googleapis.com/auth/gmail.send'],
+  userId: 'user-123',
+});
+// → Redirect user to authUrl
+
+// 3. Exchange code for token
+const token = await oauth2.exchangeCodeForToken('user-123', authCode);
+// Result: { accessToken, refreshToken, expiresAt, ... }
+
+// 4. YOU store the token (database, Redis, file, etc.)
+await database.saveToken('user-123', token);
+
+// 5. Later, retrieve and use the token with Matimo tools
+const stored = await database.getToken('user-123');
+await matimo.execute('gmail-send-email', {
+  to: 'recipient@example.com',
+  GMAIL_ACCESS_TOKEN: stored.accessToken,  // ← Pass token here
+});
+```
+
+## Dynamic Provider Discovery
+
+The provider loader automatically discovers all providers from YAML files:
+
+```typescript
+import { OAuth2ProviderLoader } from '@matimo/auth';
+
+const loader = new OAuth2ProviderLoader('./tools');
+const providers = await loader.loadProviders();
+
+// List all discovered providers
+const providerNames = providers.keys();
+// Output: ['google', 'github', 'slack', 'microsoft', ...]
+
+// Get endpoints for specific provider
+const googleEndpoints = providers.get('google');
+console.log(googleEndpoints);
+// Output: {
+//   authorizationUrl: 'https://accounts.google.com/...',
+//   tokenUrl: 'https://oauth2.googleapis.com/token',
+//   revokeUrl: '...'
+// }
+```
+
+## Custom OAuth2 Server
+
+Use runtime configuration to connect to a custom OAuth2 server:
+
+```typescript
+const oauth2 = new OAuth2Handler({
+  provider: 'internal-oauth',  // Any name
+  clientId: 'internal-client',
+  clientSecret: 'internal-secret',
+  redirectUri: 'http://localhost:3000/callback',
+  endpoints: {
+    authorizationUrl: 'https://oauth.company.internal/authorize',
+    tokenUrl: 'https://oauth.company.internal/token',
+    revokeUrl: 'https://oauth.company.internal/revoke',
+  }
+});
+```
+
+Or use environment variables:
+
+```bash
+export OAUTH_INTERNAL_AUTH_URL=https://oauth.company.internal/authorize
+export OAUTH_INTERNAL_TOKEN_URL=https://oauth.company.internal/token
+export OAUTH_INTERNAL_REVOKE_URL=https://oauth.company.internal/revoke
+```
+
+```typescript
+const oauth2 = new OAuth2Handler({
+  provider: 'internal',
+  clientId: '...',
+  clientSecret: '...',
+  redirectUri: '...',
+  // Endpoints loaded from env vars automatically
+});
+```
+
+## Best Practices
+
+### 1. Use Configuration-Driven Approach
+❌ Don't hardcode endpoints:
+```typescript
+const oauth2 = new OAuth2Handler({
+  provider: 'custom',
+  clientId: '...',
+  endpoints: {
+    authorizationUrl: 'https://hardcoded.example.com/auth',  // ❌ Bad
+  }
+});
+```
+
+✅ Use YAML or environment variables:
+```yaml
+# tools/custom/definition.yaml
+provider:
+  endpoints:
+    authorizationUrl: https://custom.example.com/auth
+```
+
+### 2. Document Provider Requirements
+Include setup instructions in provider definition:
+
+```yaml
+provider:
+  documentation: https://docs.example.com/oauth2-setup
+  # Include links to:
+  # - How to register OAuth app
+  # - Where to get client ID/secret
+  # - Required scopes for different use cases
+```
+
+### 3. Use Semantic Versioning
+Update version when endpoints change:
+
+```yaml
+version: '1.1.0'  # Increment for breaking changes
+```
+
+### 4. Never Hardcode Secrets
+Always use environment variables:
+
+```typescript
+const oauth2 = new OAuth2Handler({
+  provider: 'google',
+  clientId: process.env.GOOGLE_CLIENT_ID,        // ✅ From env vars
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET, // ✅ From env vars
+  redirectUri: process.env.GOOGLE_REDIRECT_URI,   // ✅ From env vars
+});
+```
+
+### 5. Validate Provider Definition
+Matimo automatically validates YAML structure:
+
+```typescript
+// This throws MatimoError if definition is invalid
+const loader = new OAuth2ProviderLoader('./tools');
+await loader.loadProviders();
+```
+
+## Troubleshooting
+
+### Provider Not Found
+```
+MatimoError: Unsupported OAuth2 provider: custom. Provide endpoints via:
+  1. config.endpoints (runtime override)
+  2. OAUTH_CUSTOM_AUTH_URL env var (deployment config)
+  3. tools/custom/definition.yaml (YAML configuration)
+```
+
+**Solution:** Create `tools/custom/definition.yaml` with provider definition
+
+### Invalid Provider Definition
+```
+MatimoError: Invalid provider definition: Missing required field 'endpoints'
+```
+
+**Solution:** Ensure YAML has required fields:
+- `name`
+- `type: provider`
+- `provider.endpoints.authorizationUrl`
+- `provider.endpoints.tokenUrl`
+
+### Environment Variable Not Read
+Make sure env var name matches the pattern:
+```bash
+# For provider: 'google'
+export OAUTH_GOOGLE_AUTH_URL=...
+export OAUTH_GOOGLE_TOKEN_URL=...
+export OAUTH_GOOGLE_REVOKE_URL=...  # Optional
+
+# For provider: 'microsoft'
+export OAUTH_MICROSOFT_AUTH_URL=...
+```
+
+## See Also
+
+- [OAuth2Handler API](./src/auth/oauth2-handler.ts)
+- [Provider Loader Implementation](./src/auth/oauth2-provider-loader.ts)
+- [Integration Examples](./test/integration/)