@mcp-z/oauth-google 1.0.0

package/dist/cjs/providers/loopback-oauth.d.cts

@@ -0,0 +1,119 @@
+/**
+ * Loopback OAuth Implementation (RFC 8252)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE using loopback interface redirection.
+ * Uses ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+ */
+import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
+import { OAuth2Client } from 'google-auth-library';
+import { type LoopbackOAuthConfig } from '../types.js';
+/**
+ * Loopback OAuth Client (RFC 8252 Section 7.3)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE for native applications
+ * using loopback interface redirection. Manages ephemeral OAuth flows and token persistence
+ * with Keyv for key-based token storage using compound keys.
+ *
+ * Token key format: {accountId}:{service}:token (e.g., "user@example.com:gmail:token")
+ */
+export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider {
+    private config;
+    constructor(config: LoopbackOAuthConfig);
+    /**
+     * Get access token from Keyv using compound key
+     *
+     * @param accountId - Account identifier (email address). Required for loopback OAuth.
+     * @returns Access token for API requests
+     */
+    getAccessToken(accountId?: string): Promise<string>;
+    /**
+     * Convert to googleapis-compatible OAuth2Client
+     *
+     * @param accountId - Account identifier for multi-account support (e.g., 'user@example.com')
+     * @returns OAuth2Client configured for the specified account
+     */
+    toAuth(accountId?: string): OAuth2Client;
+    /**
+     * Authenticate new account with OAuth flow
+     * Triggers account selection, stores token, registers account
+     *
+     * @returns Email address of newly authenticated account
+     * @throws Error in headless mode (cannot open browser for OAuth)
+     */
+    authenticateNewAccount(): Promise<string>;
+    /**
+     * Get user email from Google's userinfo endpoint (pure query)
+     * Used to query email for existing authenticated account
+     *
+     * @param accountId - Account identifier to get email for
+     * @returns User's email address
+     */
+    getUserEmail(accountId?: string): Promise<string>;
+    /**
+     * Check for existing accounts in token storage (incremental OAuth detection)
+     *
+     * Uses key-utils helper for forward compatibility with key format changes.
+     *
+     * @returns Array of account IDs that have tokens for this service
+     */
+    private getExistingAccounts;
+    private isTokenValid;
+    /**
+     * Fetch user email from Google OAuth2 userinfo endpoint
+     * Called during OAuth flow to get email for accountId
+     *
+     * @param accessToken - Fresh access token from OAuth exchange
+     * @returns User's email address
+     */
+    private fetchUserEmailFromToken;
+    private performEphemeralOAuthFlow;
+    private exchangeCodeForToken;
+    private refreshAccessToken;
+    /**
+     * Create authentication middleware for MCP tools, resources, and prompts
+     *
+     * Returns position-aware middleware wrappers that enrich handlers with authentication context.
+     * The middleware handles token retrieval, refresh, and AuthRequiredError automatically.
+     *
+     * Single-user middleware for desktop/CLI apps where ONE user runs the entire process:
+     * - Desktop applications (Claude Desktop)
+     * - CLI tools (Gmail CLI)
+     * - Personal automation scripts
+     *
+     * All requests use token lookups based on the active account or account override.
+     *
+     * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+     *
+     * @example
+     * ```typescript
+     * const loopback = new LoopbackOAuthProvider({ service: 'gmail', ... });
+     * const authMiddleware = loopback.authMiddleware();
+     * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);
+     * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);
+     * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);
+     * ```
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}
+/**
+ * Create a loopback OAuth client for Google services
+ * Works for both stdio and HTTP transports
+ */
+export declare function createGoogleFileAuth(config: LoopbackOAuthConfig): OAuth2TokenStorageProvider;

package/dist/cjs/providers/loopback-oauth.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Loopback OAuth Implementation (RFC 8252)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE using loopback interface redirection.
+ * Uses ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+ */
+import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
+import { OAuth2Client } from 'google-auth-library';
+import { type LoopbackOAuthConfig } from '../types.js';
+/**
+ * Loopback OAuth Client (RFC 8252 Section 7.3)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE for native applications
+ * using loopback interface redirection. Manages ephemeral OAuth flows and token persistence
+ * with Keyv for key-based token storage using compound keys.
+ *
+ * Token key format: {accountId}:{service}:token (e.g., "user@example.com:gmail:token")
+ */
+export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider {
+    private config;
+    constructor(config: LoopbackOAuthConfig);
+    /**
+     * Get access token from Keyv using compound key
+     *
+     * @param accountId - Account identifier (email address). Required for loopback OAuth.
+     * @returns Access token for API requests
+     */
+    getAccessToken(accountId?: string): Promise<string>;
+    /**
+     * Convert to googleapis-compatible OAuth2Client
+     *
+     * @param accountId - Account identifier for multi-account support (e.g., 'user@example.com')
+     * @returns OAuth2Client configured for the specified account
+     */
+    toAuth(accountId?: string): OAuth2Client;
+    /**
+     * Authenticate new account with OAuth flow
+     * Triggers account selection, stores token, registers account
+     *
+     * @returns Email address of newly authenticated account
+     * @throws Error in headless mode (cannot open browser for OAuth)
+     */
+    authenticateNewAccount(): Promise<string>;
+    /**
+     * Get user email from Google's userinfo endpoint (pure query)
+     * Used to query email for existing authenticated account
+     *
+     * @param accountId - Account identifier to get email for
+     * @returns User's email address
+     */
+    getUserEmail(accountId?: string): Promise<string>;
+    /**
+     * Check for existing accounts in token storage (incremental OAuth detection)
+     *
+     * Uses key-utils helper for forward compatibility with key format changes.
+     *
+     * @returns Array of account IDs that have tokens for this service
+     */
+    private getExistingAccounts;
+    private isTokenValid;
+    /**
+     * Fetch user email from Google OAuth2 userinfo endpoint
+     * Called during OAuth flow to get email for accountId
+     *
+     * @param accessToken - Fresh access token from OAuth exchange
+     * @returns User's email address
+     */
+    private fetchUserEmailFromToken;
+    private performEphemeralOAuthFlow;
+    private exchangeCodeForToken;
+    private refreshAccessToken;
+    /**
+     * Create authentication middleware for MCP tools, resources, and prompts
+     *
+     * Returns position-aware middleware wrappers that enrich handlers with authentication context.
+     * The middleware handles token retrieval, refresh, and AuthRequiredError automatically.
+     *
+     * Single-user middleware for desktop/CLI apps where ONE user runs the entire process:
+     * - Desktop applications (Claude Desktop)
+     * - CLI tools (Gmail CLI)
+     * - Personal automation scripts
+     *
+     * All requests use token lookups based on the active account or account override.
+     *
+     * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+     *
+     * @example
+     * ```typescript
+     * const loopback = new LoopbackOAuthProvider({ service: 'gmail', ... });
+     * const authMiddleware = loopback.authMiddleware();
+     * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);
+     * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);
+     * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);
+     * ```
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}
+/**
+ * Create a loopback OAuth client for Google services
+ * Works for both stdio and HTTP transports
+ */
+export declare function createGoogleFileAuth(config: LoopbackOAuthConfig): OAuth2TokenStorageProvider;