@matimo/core 0.1.0-alpha.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tallclub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/auth/oauth2-config.d.ts

@@ -0,0 +1,104 @@
+/**
+ * OAuth2 Configuration Types - PROVIDER-AGNOSTIC + YAML-DRIVEN
+ *
+ * Matimo supports OAuth2 for any provider via YAML configuration.
+ * Provider definitions are loaded from tools/[provider]/definition.yaml files.
+ *
+ * Matimo's Responsibility:
+ * - Help obtain tokens via standard OAuth2 flow
+ * - Support automatic token refresh
+ * - Work with Google, GitHub, Slack, or any OAuth2 provider
+ * - Load provider configs from YAML (no hardcoded endpoints)
+ *
+ * User's Responsibility:
+ * - Store tokens (DB, file, cache, wherever you want)
+ * - Retrieve and pass tokens to Matimo tools
+ *
+ * Adding a New Provider (e.g., Microsoft Teams):
+ * 1. Create: tools/microsoft/definition.yaml
+ * 2. Add provider section with OAuth endpoints
+ * 3. Done! OAuth2Handler automatically recognizes it.
+ *
+ * Configuration Priority (highest to lowest):
+ * 1. config.endpoints - Runtime override (user provides directly)
+ * 2. OAUTH_PROVIDER_AUTH_URL env var - Deployment override
+ * 3. YAML definition (tools/[provider]/definition.yaml) - Default from config
+ */
+/**
+ * Supported OAuth2 providers
+ *
+ * Type is string (not enum) because providers are discovered from YAML.
+ * Tools define which provider they use via authentication.provider field.
+ */
+export type OAuth2Provider = string;
+/**
+ * OAuth2 token - Returned by OAuth2Handler
+ *
+ * This is what you get after successful authorization.
+ * Store this in your DB/file/cache (Matimo doesn't store it).
+ * Pass accessToken to any Matimo tool that needs OAuth.
+ */
+export interface OAuth2Token {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    scopes: string[];
+    provider: OAuth2Provider;
+    userId: string;
+}
+/**
+ * OAuth2 configuration - PROVIDER-AGNOSTIC + YAML-DRIVEN
+ *
+ * Same interface works for Google, GitHub, Slack, or any OAuth2 provider.
+ * Provider endpoints come from YAML definitions (tools/[provider]/definition.yaml).
+ * Users can override endpoints without touching code.
+ *
+ * Configuration Priority:
+ * 1. endpoints property (runtime override - user provides directly)
+ * 2. OAUTH_PROVIDER_AUTH_URL environment variable (deployment config)
+ * 3. YAML definition from tools/[provider]/definition.yaml (default configuration)
+ */
+export interface OAuth2Config {
+    provider: OAuth2Provider;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    endpoints?: OAuth2Endpoints;
+}
+/**
+ * Authorization request options
+ */
+export interface AuthorizationOptions {
+    scopes: string[];
+    userId: string;
+    state?: string;
+}
+/**
+ * Token exchange response from OAuth2 provider
+ */
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    token_type: string;
+    scope?: string;
+}
+/**
+ * OAuth2 endpoints for a provider
+ */
+export interface OAuth2Endpoints {
+    authorizationUrl: string;
+    tokenUrl: string;
+    revokeUrl?: string;
+}
+/**
+ * NOTE: Provider endpoints are loaded from YAML files, not hardcoded here.
+ * See: tools/[provider]/definition.yaml for provider configurations
+ *
+ * This enables:
+ * - Infinite provider support
+ * - Configuration-driven design
+ * - Easy provider additions without code changes
+ * - Centralized endpoint management
+ */
+//# sourceMappingURL=oauth2-config.d.ts.map

package/dist/src/auth/oauth2-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-config.d.ts","sourceRoot":"","sources":["../../../src/auth/oauth2-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG"}

package/dist/src/auth/oauth2-config.js

@@ -0,0 +1,38 @@
+/**
+ * OAuth2 Configuration Types - PROVIDER-AGNOSTIC + YAML-DRIVEN
+ *
+ * Matimo supports OAuth2 for any provider via YAML configuration.
+ * Provider definitions are loaded from tools/[provider]/definition.yaml files.
+ *
+ * Matimo's Responsibility:
+ * - Help obtain tokens via standard OAuth2 flow
+ * - Support automatic token refresh
+ * - Work with Google, GitHub, Slack, or any OAuth2 provider
+ * - Load provider configs from YAML (no hardcoded endpoints)
+ *
+ * User's Responsibility:
+ * - Store tokens (DB, file, cache, wherever you want)
+ * - Retrieve and pass tokens to Matimo tools
+ *
+ * Adding a New Provider (e.g., Microsoft Teams):
+ * 1. Create: tools/microsoft/definition.yaml
+ * 2. Add provider section with OAuth endpoints
+ * 3. Done! OAuth2Handler automatically recognizes it.
+ *
+ * Configuration Priority (highest to lowest):
+ * 1. config.endpoints - Runtime override (user provides directly)
+ * 2. OAUTH_PROVIDER_AUTH_URL env var - Deployment override
+ * 3. YAML definition (tools/[provider]/definition.yaml) - Default from config
+ */
+export {};
+/**
+ * NOTE: Provider endpoints are loaded from YAML files, not hardcoded here.
+ * See: tools/[provider]/definition.yaml for provider configurations
+ *
+ * This enables:
+ * - Infinite provider support
+ * - Configuration-driven design
+ * - Easy provider additions without code changes
+ * - Centralized endpoint management
+ */
+//# sourceMappingURL=oauth2-config.js.map

package/dist/src/auth/oauth2-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-config.js","sourceRoot":"","sources":["../../../src/auth/oauth2-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;AA2EH;;;;;;;;;GASG"}

package/dist/src/auth/oauth2-handler.d.ts

@@ -0,0 +1,130 @@
+/**
+ * OAuth2 Handler
+ * Manages OAuth2 authentication flows and token exchange
+ */
+import { OAuth2Config, OAuth2Token, OAuth2Endpoints, AuthorizationOptions } from './oauth2-config';
+import { OAuth2ProviderLoader } from './oauth2-provider-loader';
+/**
+ * OAuth2Handler - Provider-Agnostic OAuth2 Flow Manager
+ *
+ * Matimo's OAuth2 Scope:
+ * ✅ Help complete OAuth2 authorization with any provider
+ * ✅ Exchange authorization codes for tokens
+ * ✅ Support automatic token refresh if needed
+ * ✅ Work with Google, GitHub, Slack, or any OAuth2 provider
+ * ❌ Store tokens (User's responsibility)
+ * ❌ Manage token lifecycle (User's responsibility)
+ *
+ * Pattern: Config → Get Auth URL → Exchange Code → Return Token → User Stores It
+ *
+ * Usage:
+ * ```typescript
+ * // 1. Create handler (works for any OAuth2 provider)
+ * const oauth2 = new OAuth2Handler({
+ *   provider: 'google', // or 'github', 'slack', etc.
+ *   clientId: process.env.CLIENT_ID,
+ *   clientSecret: process.env.CLIENT_SECRET,
+ *   redirectUri: 'http://localhost:3000/callback',
+ * });
+ *
+ * // 2. Generate authorization URL
+ * const authUrl = oauth2.getAuthorizationUrl({
+ *   userId: 'user-123',
+ *   scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+ * });
+ * // Send user to authUrl
+ *
+ * // 3. Exchange authorization code for token
+ * const token = await oauth2.exchangeCodeForToken('user-123', authCode);
+ * // Token: { accessToken, refreshToken, expiresAt, ... }
+ *
+ * // 4. User stores token (in DB, file, cache, or wherever they choose)
+ * // Matimo does NOT store tokens - that's the user's responsibility
+ * await myDatabase.saveToken('user-123', token);
+ *
+ * // 5. User retrieves token from their storage and passes to tools
+ * const stored = await myDatabase.getToken('user-123');
+ * await matimo.execute('gmail-send-email', {
+ *   to: 'user@example.com',
+ *   GMAIL_ACCESS_TOKEN: stored.accessToken, // ← User provides token
+ * });
+ * ```
+ */
+export declare class OAuth2Handler {
+    private config;
+    private tokenRefreshBuffer;
+    private endpoints;
+    private providerLoader;
+    /**
+     * Constructor
+     * @param config - OAuth2 configuration (provider, clientId, clientSecret, redirectUri)
+     * @param providerLoader - Optional provider loader (loads from YAML files)
+     */
+    constructor(config: OAuth2Config, providerLoader?: OAuth2ProviderLoader);
+    /**
+     * Resolve OAuth2 endpoints with layered configuration
+     *
+     * Priority (highest to lowest):
+     * 1. config.endpoints - user provided at runtime
+     * 2. Environment variables: OAUTH_{PROVIDER}_AUTH_URL, OAUTH_{PROVIDER}_TOKEN_URL, etc.
+     * 3. YAML definition from provider loader (tools/[provider]/definition.yaml)
+     *
+     * This design allows:
+     * - Runtime override via config
+     * - Deployment-time override via env vars
+     * - Default configuration from YAML files
+     * - Support for infinite providers without code changes
+     */
+    private resolveEndpoints;
+    /**
+     * Get resolved endpoints (for testing or debugging)
+     */
+    getEndpoints(): OAuth2Endpoints;
+    /**
+     * Generate authorization URL for user to visit
+     * @param options - Authorization options (scopes, userId, optional state)
+     * @returns Authorization URL
+     */
+    getAuthorizationUrl(options: AuthorizationOptions): string;
+    /**
+     * Exchange authorization code for access token
+     * @param code - Authorization code from provider
+     * @param userId - User ID to associate token with
+     * @returns OAuth2Token with access and optional refresh token
+     */
+    exchangeCodeForToken(code: string, userId: string): Promise<OAuth2Token>;
+    /**
+     * Refresh a token if it's expired or expiring soon
+     * @param userId - User ID (for context only)
+     * @param currentToken - Current OAuth2Token to refresh
+     * @returns Refreshed OAuth2Token (same token if not expiring soon)
+     */
+    refreshTokenIfNeeded(userId: string, currentToken: OAuth2Token): Promise<OAuth2Token>;
+    /**
+     * Revoke a token (logout)
+     * @param token - OAuth2Token to revoke
+     */
+    revokeToken(token: OAuth2Token): Promise<void>;
+    /**
+     * Check if a token is expired or expiring soon (within 5 minute buffer)
+     */
+    private isTokenExpiringSoon;
+    /**
+     * Parse token response from provider
+     */
+    private parseTokenResponse;
+    /**
+     * Generate random state token for CSRF protection
+     */
+    private generateRandomState;
+    /**
+     * Check if a token is valid (not expired)
+     */
+    isTokenValid(token: OAuth2Token): boolean;
+    /**
+     * Set custom token refresh buffer (milliseconds before expiration)
+     */
+    setTokenRefreshBuffer(milliseconds: number): void;
+}
+export default OAuth2Handler;
+//# sourceMappingURL=oauth2-handler.d.ts.map

package/dist/src/auth/oauth2-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-handler.d.ts","sourceRoot":"","sources":["../../../src/auth/oauth2-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,eAAe,EAEf,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,cAAc,CAAuB;IAE7C;;;;OAIG;gBACS,MAAM,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAoBvE;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,gBAAgB;IA2CxB;;OAEG;IACH,YAAY,IAAI,eAAe;IAI/B;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM;IAmB1D;;;;;OAKG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA2B9E;;;;;OAKG;IACG,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAuC3F;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBpD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAe1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAKzC;;OAEG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;CAGlD;AAED,eAAe,aAAa,CAAC"}

package/dist/src/auth/oauth2-handler.js

@@ -0,0 +1,265 @@
+/**
+ * OAuth2 Handler
+ * Manages OAuth2 authentication flows and token exchange
+ */
+import axios from 'axios';
+import { OAuth2ProviderLoader } from './oauth2-provider-loader';
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+/**
+ * OAuth2Handler - Provider-Agnostic OAuth2 Flow Manager
+ *
+ * Matimo's OAuth2 Scope:
+ * ✅ Help complete OAuth2 authorization with any provider
+ * ✅ Exchange authorization codes for tokens
+ * ✅ Support automatic token refresh if needed
+ * ✅ Work with Google, GitHub, Slack, or any OAuth2 provider
+ * ❌ Store tokens (User's responsibility)
+ * ❌ Manage token lifecycle (User's responsibility)
+ *
+ * Pattern: Config → Get Auth URL → Exchange Code → Return Token → User Stores It
+ *
+ * Usage:
+ * ```typescript
+ * // 1. Create handler (works for any OAuth2 provider)
+ * const oauth2 = new OAuth2Handler({
+ *   provider: 'google', // or 'github', 'slack', etc.
+ *   clientId: process.env.CLIENT_ID,
+ *   clientSecret: process.env.CLIENT_SECRET,
+ *   redirectUri: 'http://localhost:3000/callback',
+ * });
+ *
+ * // 2. Generate authorization URL
+ * const authUrl = oauth2.getAuthorizationUrl({
+ *   userId: 'user-123',
+ *   scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+ * });
+ * // Send user to authUrl
+ *
+ * // 3. Exchange authorization code for token
+ * const token = await oauth2.exchangeCodeForToken('user-123', authCode);
+ * // Token: { accessToken, refreshToken, expiresAt, ... }
+ *
+ * // 4. User stores token (in DB, file, cache, or wherever they choose)
+ * // Matimo does NOT store tokens - that's the user's responsibility
+ * await myDatabase.saveToken('user-123', token);
+ *
+ * // 5. User retrieves token from their storage and passes to tools
+ * const stored = await myDatabase.getToken('user-123');
+ * await matimo.execute('gmail-send-email', {
+ *   to: 'user@example.com',
+ *   GMAIL_ACCESS_TOKEN: stored.accessToken, // ← User provides token
+ * });
+ * ```
+ */
+export class OAuth2Handler {
+    /**
+     * Constructor
+     * @param config - OAuth2 configuration (provider, clientId, clientSecret, redirectUri)
+     * @param providerLoader - Optional provider loader (loads from YAML files)
+     */
+    constructor(config, providerLoader) {
+        if (!config.clientId || !config.clientSecret) {
+            throw new MatimoError('OAuth2 clientId and clientSecret are required', ErrorCode.AUTH_FAILED, { provider: config.provider });
+        }
+        this.config = config;
+        this.tokenRefreshBuffer = 5 * 60 * 1000; // Refresh 5 minutes before expiration
+        this.providerLoader = providerLoader || new OAuth2ProviderLoader('tools');
+        // Resolve endpoints with priority:
+        // 1. Runtime config (highest priority - user provides endpoints directly)
+        // 2. Environment variables (deployment config)
+        // 3. YAML definition (provider loader - configuration-driven)
+        this.endpoints = this.resolveEndpoints(config);
+    }
+    /**
+     * Resolve OAuth2 endpoints with layered configuration
+     *
+     * Priority (highest to lowest):
+     * 1. config.endpoints - user provided at runtime
+     * 2. Environment variables: OAUTH_{PROVIDER}_AUTH_URL, OAUTH_{PROVIDER}_TOKEN_URL, etc.
+     * 3. YAML definition from provider loader (tools/[provider]/definition.yaml)
+     *
+     * This design allows:
+     * - Runtime override via config
+     * - Deployment-time override via env vars
+     * - Default configuration from YAML files
+     * - Support for infinite providers without code changes
+     */
+    resolveEndpoints(config) {
+        // Priority 1: Runtime config (user provides endpoints directly)
+        if (config.endpoints) {
+            return config.endpoints;
+        }
+        // Priority 2: Environment variables
+        const envAuthUrl = process.env[`OAUTH_${config.provider.toUpperCase()}_AUTH_URL`];
+        const envTokenUrl = process.env[`OAUTH_${config.provider.toUpperCase()}_TOKEN_URL`];
+        if (envAuthUrl || envTokenUrl) {
+            if (!envAuthUrl || !envTokenUrl) {
+                throw new MatimoError(`Incomplete OAuth environment config for ${config.provider}. Both OAUTH_${config.provider.toUpperCase()}_AUTH_URL and OAUTH_${config.provider.toUpperCase()}_TOKEN_URL must be set.`, ErrorCode.AUTH_FAILED, { provider: config.provider });
+            }
+            return {
+                authorizationUrl: envAuthUrl,
+                tokenUrl: envTokenUrl,
+                revokeUrl: process.env[`OAUTH_${config.provider.toUpperCase()}_REVOKE_URL`],
+            };
+        }
+        // Priority 3: YAML definition from provider loader
+        const yamlEndpoints = this.providerLoader.getProvider(config.provider);
+        if (yamlEndpoints) {
+            return yamlEndpoints;
+        }
+        // No endpoints found
+        throw new MatimoError(`Unsupported OAuth2 provider: ${config.provider}. Provide endpoints via:
+      1. config.endpoints (runtime override)
+      2. OAUTH_${config.provider.toUpperCase()}_AUTH_URL env var (deployment config)
+      3. tools/${config.provider}/definition.yaml (YAML configuration)`, ErrorCode.AUTH_FAILED, { provider: config.provider });
+    }
+    /**
+     * Get resolved endpoints (for testing or debugging)
+     */
+    getEndpoints() {
+        return this.endpoints;
+    }
+    /**
+     * Generate authorization URL for user to visit
+     * @param options - Authorization options (scopes, userId, optional state)
+     * @returns Authorization URL
+     */
+    getAuthorizationUrl(options) {
+        const state = options.state || this.generateRandomState();
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            response_type: 'code',
+            scope: options.scopes.join(' '),
+            state,
+            // Provider-specific parameters
+            ...(this.config.provider === 'google' && {
+                access_type: 'offline', // Request refresh token
+                prompt: 'consent', // Force consent screen
+            }),
+        });
+        return `${this.endpoints.authorizationUrl}?${params.toString()}`;
+    }
+    /**
+     * Exchange authorization code for access token
+     * @param code - Authorization code from provider
+     * @param userId - User ID to associate token with
+     * @returns OAuth2Token with access and optional refresh token
+     */
+    async exchangeCodeForToken(code, userId) {
+        try {
+            const response = await axios.post(this.endpoints.tokenUrl, {
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                code,
+                redirect_uri: this.config.redirectUri,
+                grant_type: 'authorization_code',
+            });
+            const tokenResponse = response.data;
+            const token = this.parseTokenResponse(tokenResponse, userId);
+            // Return token - user is responsible for storing it
+            return token;
+        }
+        catch (error) {
+            throw new MatimoError('Failed to exchange authorization code for token', ErrorCode.AUTH_FAILED, {
+                provider: this.config.provider,
+                error: error.message,
+            });
+        }
+    }
+    /**
+     * Refresh a token if it's expired or expiring soon
+     * @param userId - User ID (for context only)
+     * @param currentToken - Current OAuth2Token to refresh
+     * @returns Refreshed OAuth2Token (same token if not expiring soon)
+     */
+    async refreshTokenIfNeeded(userId, currentToken) {
+        if (!this.isTokenExpiringSoon(currentToken)) {
+            return currentToken; // Token still valid
+        }
+        if (!currentToken.refreshToken) {
+            throw new MatimoError(`Cannot refresh token for user: ${userId} - no refreshToken available`, ErrorCode.AUTH_FAILED, { userId, provider: this.config.provider });
+        }
+        try {
+            const response = await axios.post(this.endpoints.tokenUrl, {
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                refresh_token: currentToken.refreshToken,
+                grant_type: 'refresh_token',
+            });
+            const tokenResponse = response.data;
+            const refreshedToken = this.parseTokenResponse(tokenResponse, userId, currentToken.refreshToken);
+            // Return refreshed token - user is responsible for storing it
+            return refreshedToken;
+        }
+        catch (error) {
+            throw new MatimoError('Failed to refresh token', ErrorCode.AUTH_FAILED, {
+                userId,
+                provider: this.config.provider,
+                error: error.message,
+            });
+        }
+    }
+    /**
+     * Revoke a token (logout)
+     * @param token - OAuth2Token to revoke
+     */
+    async revokeToken(token) {
+        if (!this.endpoints.revokeUrl) {
+            // Provider doesn't support revocation
+            return;
+        }
+        try {
+            await axios.post(this.endpoints.revokeUrl, {
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                token: token.accessToken,
+            });
+        }
+        catch {
+            // Log but don't fail - token may already be revoked
+        }
+    }
+    /**
+     * Check if a token is expired or expiring soon (within 5 minute buffer)
+     */
+    isTokenExpiringSoon(token) {
+        const now = Date.now();
+        const expiresAt = token.expiresAt;
+        return now >= expiresAt - this.tokenRefreshBuffer;
+    }
+    /**
+     * Parse token response from provider
+     */
+    parseTokenResponse(response, userId, existingRefreshToken) {
+        return {
+            accessToken: response.access_token,
+            refreshToken: response.refresh_token || existingRefreshToken,
+            expiresAt: Date.now() + response.expires_in * 1000,
+            scopes: response.scope ? response.scope.split(' ') : [],
+            provider: this.config.provider,
+            userId,
+        };
+    }
+    /**
+     * Generate random state token for CSRF protection
+     */
+    generateRandomState() {
+        return (Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15));
+    }
+    /**
+     * Check if a token is valid (not expired)
+     */
+    isTokenValid(token) {
+        const now = Date.now();
+        return now < token.expiresAt;
+    }
+    /**
+     * Set custom token refresh buffer (milliseconds before expiration)
+     */
+    setTokenRefreshBuffer(milliseconds) {
+        this.tokenRefreshBuffer = milliseconds;
+    }
+}
+export default OAuth2Handler;
+//# sourceMappingURL=oauth2-handler.js.map

package/dist/src/auth/oauth2-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-handler.js","sourceRoot":"","sources":["../../../src/auth/oauth2-handler.ts"],"names":[],"mappings":"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"}

package/dist/src/auth/oauth2-provider-loader.d.ts

@@ -0,0 +1,68 @@
+/**
+ * OAuth2ProviderLoader - Loads provider definitions from YAML files
+ *
+ * Pattern: Configuration-driven providers
+ * - Loads provider definitions from tools/[provider]/definition.yaml
+ * - Discovers providers with type: provider
+ * - Makes endpoints available to OAuth2Handler
+ * - Supports infinite providers without code changes
+ *
+ * Usage:
+ * ```typescript
+ * const loader = new OAuth2ProviderLoader('./tools');
+ * const providers = await loader.loadProviders();
+ * const googleEndpoints = providers.get('google');
+ * ```
+ */
+import { OAuth2Endpoints } from './oauth2-config';
+import { type ProviderDefinition } from '../core/schema';
+/**
+ * OAuth2ProviderLoader - Loads OAuth2 provider configurations from YAML
+ *
+ * Design Principle:
+ * - Configuration-driven: All provider config in YAML files
+ * - Discoverable: Automatically finds tools/[provider]/definition.yaml with type: provider
+ * - Extensible: Add new providers by adding YAML file, no code changes
+ * - Overridable: Users can override via env vars or runtime config
+ */
+export declare class OAuth2ProviderLoader {
+    private toolsPath;
+    private providers;
+    private definitions;
+    constructor(toolsPath: string);
+    /**
+     * Load all provider definitions from tools directory
+     *
+     * Discovers tools/[provider]/definition.yaml files with type: provider
+     * Validates and stores provider endpoint configurations
+     *
+     * @returns Map of provider name → OAuth2Endpoints
+     * @throws MatimoError if invalid provider definition found
+     */
+    loadProviders(): Promise<Map<string, OAuth2Endpoints>>;
+    /**
+     * Get endpoints for a specific provider
+     * @param providerName - Name of the provider (e.g., 'google', 'github')
+     * @returns OAuth2Endpoints or undefined if provider not found
+     */
+    getProvider(providerName: string): OAuth2Endpoints | undefined;
+    /**
+     * Get full provider definition
+     * @param providerName - Name of the provider
+     * @returns ProviderDefinition or undefined if provider not found
+     */
+    getDefinition(providerName: string): ProviderDefinition | undefined;
+    /**
+     * List all loaded providers
+     */
+    listProviders(): string[];
+    /**
+     * Validate provider definition structure using Zod schema
+     */
+    protected validateProviderDefinition(definition: ProviderDefinition): void;
+    /**
+     * Register a provider definition
+     */
+    private registerProvider;
+}
+//# sourceMappingURL=oauth2-provider-loader.d.ts.map

package/dist/src/auth/oauth2-provider-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-provider-loader.d.ts","sourceRoot":"","sources":["../../../src/auth/oauth2-provider-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErF;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAA2C;IAC5D,OAAO,CAAC,WAAW,CAA8C;gBAErD,SAAS,EAAE,MAAM;IAI7B;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAqC5D;;;;OAIG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI9D;;;;OAIG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAInE;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;IAIzB;;OAEG;IACH,SAAS,CAAC,0BAA0B,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAU1E;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAMzB"}