@lobu/gateway 3.0.5 → 3.0.6

package/src/auth/mcp/string-substitution.ts

@@ -0,0 +1,17 @@
+let envResolver: ((key: string) => string | undefined) | null = null;
+
+/**
+ * Register a custom env resolver that takes priority over process.env.
+ * Used by SystemEnvStore to inject Redis-backed env vars.
+ */
+export function setEnvResolver(fn: (key: string) => string | undefined): void {
+  envResolver = fn;
+}
+
+/**
+ * Resolve an environment variable using the registered envResolver (Redis)
+ * with process.env as fallback. Reusable by provider modules.
+ */
+export function resolveEnv(key: string): string | undefined {
+  return envResolver?.(key) ?? process.env[key];
+}

package/src/auth/mcp/tool-cache.ts

@@ -0,0 +1,90 @@
+import { createLogger } from "@lobu/core";
+
+const logger = createLogger("mcp-tool-cache");
+
+export interface McpTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  annotations?: {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
+}
+
+export interface CachedMcpServer {
+  tools: McpTool[];
+  instructions?: string;
+}
+
+const CACHE_TTL_SECONDS = 300; // 5 minutes
+
+export class McpToolCache {
+  constructor(private readonly redisClient: any) {}
+
+  async get(mcpId: string, agentId?: string): Promise<McpTool[] | null> {
+    const info = await this.getServerInfo(mcpId, agentId);
+    return info ? info.tools : null;
+  }
+
+  async set(mcpId: string, tools: McpTool[], agentId?: string): Promise<void> {
+    await this.setServerInfo(mcpId, { tools }, agentId);
+  }
+
+  async getServerInfo(
+    mcpId: string,
+    agentId?: string
+  ): Promise<CachedMcpServer | null> {
+    const key = this.buildKey(mcpId, agentId);
+    try {
+      const cached = await this.redisClient.get(key);
+      if (cached) {
+        const parsed = JSON.parse(cached);
+        // Backward compat: if cached value is an array, it's old format (tools only)
+        if (Array.isArray(parsed)) {
+          return { tools: parsed as McpTool[] };
+        }
+        return parsed as CachedMcpServer;
+      }
+      return null;
+    } catch (error) {
+      logger.error("Failed to read tool cache", { key, error });
+      return null;
+    }
+  }
+
+  async setServerInfo(
+    mcpId: string,
+    info: CachedMcpServer,
+    agentId?: string
+  ): Promise<void> {
+    const key = this.buildKey(mcpId, agentId);
+    try {
+      await this.redisClient.set(
+        key,
+        JSON.stringify(info),
+        "EX",
+        CACHE_TTL_SECONDS
+      );
+    } catch (error) {
+      logger.error("Failed to write tool cache", { key, error });
+    }
+  }
+
+  async getInstructions(
+    mcpId: string,
+    agentId?: string
+  ): Promise<string | undefined> {
+    const info = await this.getServerInfo(mcpId, agentId);
+    return info?.instructions;
+  }
+
+  private buildKey(mcpId: string, agentId?: string): string {
+    if (agentId) {
+      return `mcp:tools:${agentId}:${mcpId}`;
+    }
+    return `mcp:tools:${mcpId}`;
+  }
+}

package/src/auth/oauth/base-client.ts

@@ -0,0 +1,267 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createLogger, type Logger } from "@lobu/core";
+
+/**
+ * Base OAuth2 client with shared token exchange and refresh logic
+ * Supports standard OAuth 2.0 flows including PKCE (RFC 7636)
+ * Subclasses customize authorization URL building and request formatting
+ */
+export abstract class BaseOAuth2Client {
+  protected logger: Logger;
+
+  constructor(loggerName: string) {
+    this.logger = createLogger(loggerName);
+  }
+
+  // ============================================================================
+  // PKCE Support (RFC 7636) - For public clients
+  // ============================================================================
+
+  /**
+   * Generate PKCE code verifier (43-128 characters, base64url encoded)
+   * Used for public OAuth clients (mobile apps, CLIs, SPAs)
+   */
+  generateCodeVerifier(): string {
+    return randomBytes(32).toString("base64url");
+  }
+
+  /**
+   * Generate PKCE code challenge from verifier using SHA256
+   * The challenge is sent in authorization request, verifier in token exchange
+   */
+  generateCodeChallenge(codeVerifier: string): string {
+    return createHash("sha256").update(codeVerifier).digest("base64url");
+  }
+
+  // ============================================================================
+  // Generic OAuth Token Operations
+  // ============================================================================
+
+  /**
+   * Generic refresh token method using provider configuration
+   * Supports both public clients (PKCE) and confidential clients (with secret)
+   *
+   * @param tokenUrl - Token endpoint URL
+   * @param clientId - OAuth client ID
+   * @param refreshToken - Refresh token from initial authorization
+   * @param options - Optional parameters (client secret, custom headers, content type)
+   */
+  async refreshTokenWithConfig<T>(
+    tokenUrl: string,
+    clientId: string,
+    refreshToken: string,
+    options?: {
+      clientSecret?: string;
+      customHeaders?: Record<string, string>;
+      contentType?: "json" | "form";
+      tokenEndpointAuthMethod?: string;
+    }
+  ): Promise<T> {
+    const body: Record<string, string> = {
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+    };
+
+    // Add client_secret if not using PKCE (tokenEndpointAuthMethod !== "none")
+    if (options?.clientSecret && options?.tokenEndpointAuthMethod !== "none") {
+      body.client_secret = options.clientSecret;
+    }
+
+    return this.refreshAccessToken<T>(
+      tokenUrl,
+      body,
+      options?.contentType || "json",
+      options?.customHeaders
+    );
+  }
+
+  // ============================================================================
+  // Low-level HTTP Operations (protected for subclasses)
+  // ============================================================================
+
+  /**
+   * Common token exchange implementation
+   * Subclasses must implement buildTokenExchangeRequest
+   */
+  protected async exchangeToken<T>(
+    tokenUrl: string,
+    requestBody: Record<string, string> | URLSearchParams,
+    contentType: "json" | "form" = "json",
+    additionalHeaders?: Record<string, string>
+  ): Promise<T> {
+    this.logger.info(`Exchanging code for token at ${tokenUrl}`, {
+      contentType,
+    });
+
+    try {
+      const body =
+        contentType === "json"
+          ? JSON.stringify(requestBody)
+          : requestBody instanceof URLSearchParams
+            ? requestBody.toString()
+            : new URLSearchParams(
+                requestBody as Record<string, string>
+              ).toString();
+
+      const headers: Record<string, string> = {
+        Accept: "application/json",
+        ...additionalHeaders,
+      };
+
+      if (contentType === "json") {
+        headers["Content-Type"] = "application/json";
+      } else {
+        headers["Content-Type"] = "application/x-www-form-urlencoded";
+      }
+
+      this.logger.debug(`Token exchange request`, {
+        contentType,
+        tokenUrl,
+      });
+
+      const response = await fetch(tokenUrl, {
+        method: "POST",
+        headers,
+        body,
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        this.logger.error(`Token exchange failed: ${response.status}`, {
+          errorText,
+        });
+        throw new Error(
+          `Token exchange failed: ${response.status} ${response.statusText}`
+        );
+      }
+
+      const responseContentType = response.headers.get("content-type") || "";
+      let tokenData: any;
+
+      // Parse response based on content type
+      if (responseContentType.includes("application/json")) {
+        tokenData = await response.json();
+      } else {
+        // Handle form-encoded responses (e.g., some OAuth providers)
+        const text = await response.text();
+        const params = new URLSearchParams(text);
+        tokenData = {
+          access_token: params.get("access_token") || "",
+          token_type: params.get("token_type") || "Bearer",
+          expires_in: params.get("expires_in")
+            ? parseInt(params.get("expires_in")!, 10)
+            : undefined,
+          refresh_token: params.get("refresh_token") || undefined,
+          scope: params.get("scope") || undefined,
+        };
+      }
+
+      // Check for OAuth error response
+      if ("error" in tokenData) {
+        throw new Error(
+          `OAuth error: ${tokenData.error} - ${tokenData.error_description || ""}`
+        );
+      }
+
+      if (!tokenData.access_token) {
+        throw new Error("No access token in response");
+      }
+
+      this.logger.info(
+        `Token exchange successful, expires_in: ${tokenData.expires_in}s`
+      );
+
+      return tokenData as T;
+    } catch (error) {
+      this.logger.error("Token exchange failed", { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Common token refresh implementation
+   * Subclasses must implement buildRefreshRequest
+   */
+  protected async refreshAccessToken<T>(
+    tokenUrl: string,
+    requestBody: Record<string, string> | URLSearchParams,
+    contentType: "json" | "form" = "json",
+    additionalHeaders?: Record<string, string>
+  ): Promise<T> {
+    this.logger.info(`Refreshing token at ${tokenUrl}`);
+
+    try {
+      const body =
+        contentType === "json"
+          ? JSON.stringify(requestBody)
+          : requestBody instanceof URLSearchParams
+            ? requestBody.toString()
+            : new URLSearchParams(
+                requestBody as Record<string, string>
+              ).toString();
+
+      const headers: Record<string, string> = {
+        Accept: "application/json",
+        ...additionalHeaders,
+      };
+
+      if (contentType === "json") {
+        headers["Content-Type"] = "application/json";
+      } else {
+        headers["Content-Type"] = "application/x-www-form-urlencoded";
+      }
+
+      const response = await fetch(tokenUrl, {
+        method: "POST",
+        headers,
+        body,
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        this.logger.error(`Token refresh failed: ${response.status}`, {
+          errorText,
+        });
+        throw new Error(
+          `Token refresh failed: ${response.status} ${response.statusText}`
+        );
+      }
+
+      const tokenData = (await response.json()) as any;
+
+      if ("error" in tokenData) {
+        throw new Error(
+          `OAuth error: ${tokenData.error} - ${tokenData.error_description || ""}`
+        );
+      }
+
+      if (!tokenData.access_token) {
+        throw new Error("No access token in refresh response");
+      }
+
+      this.logger.info(
+        `Token refresh successful, expires_in: ${tokenData.expires_in}s`
+      );
+
+      return tokenData as T;
+    } catch (error) {
+      this.logger.error("Token refresh failed", { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Calculate token expiration timestamp
+   */
+  protected calculateExpiresAt(expiresIn?: number): number | undefined {
+    return expiresIn ? Date.now() + expiresIn * 1000 : undefined;
+  }
+
+  /**
+   * Parse scopes from string or array
+   */
+  protected parseScopes(scope?: string): string[] {
+    return scope ? scope.split(" ") : [];
+  }
+}

package/src/auth/oauth/client.ts

@@ -0,0 +1,153 @@
+import { BaseOAuth2Client } from "./base-client";
+import type { OAuthCredentials } from "./credentials";
+import type { OAuthProviderConfig } from "./providers";
+
+interface OAuthTokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  token_type?: string;
+  expires_in: number;
+  scope?: string;
+}
+
+/**
+ * Config-driven OAuth client for any provider
+ * Extends BaseOAuth2Client with provider configuration
+ *
+ * Features:
+ * - PKCE support (RFC 7636) for public client security
+ * - Browser-like headers for anti-bot protection
+ * - Configurable via OAuthProviderConfig
+ */
+export class OAuthClient extends BaseOAuth2Client {
+  private config: OAuthProviderConfig;
+
+  constructor(config: OAuthProviderConfig) {
+    super(`${config.id ?? "oauth"}-client`);
+    this.config = config;
+  }
+
+  /**
+   * Build authorization URL with PKCE parameters
+   */
+  buildAuthUrl(
+    state: string,
+    codeVerifier: string,
+    customRedirectUri?: string
+  ): string {
+    const codeChallenge = this.generateCodeChallenge(codeVerifier);
+    const redirectUri = customRedirectUri || this.config.redirectUri;
+
+    const url = new URL(this.config.authUrl);
+    url.searchParams.set("client_id", this.config.clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("response_type", this.config.responseType || "code");
+    url.searchParams.set("state", state);
+    url.searchParams.set("scope", this.config.scope);
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+
+    return url.toString();
+  }
+
+  /**
+   * Exchange authorization code for access token using PKCE
+   */
+  async exchangeCodeForToken(
+    code: string,
+    codeVerifier: string,
+    customRedirectUri?: string,
+    state?: string
+  ): Promise<OAuthCredentials> {
+    const redirectUri = customRedirectUri || this.config.redirectUri;
+
+    const body: Record<string, string> = {
+      grant_type: this.config.grantType || "authorization_code",
+      client_id: this.config.clientId,
+      code,
+      redirect_uri: redirectUri,
+      code_verifier: codeVerifier,
+    };
+
+    // Include state if provided (required by Claude OAuth)
+    if (state) {
+      body.state = state;
+    }
+
+    // Add provider-specific custom headers
+    const tokenData = await this.exchangeToken<OAuthTokenResponse>(
+      this.config.tokenUrl,
+      body,
+      "json",
+      this.config.customHeaders
+    );
+
+    const credentials = this.buildCredentials(tokenData);
+    this.logger.info(
+      `Token exchange successful, expires_in: ${tokenData.expires_in}s`,
+      { scopes: credentials.scopes }
+    );
+
+    return credentials;
+  }
+
+  /**
+   * Refresh access token using refresh token
+   * Uses generic refresh method from base client with Claude-specific config
+   */
+  async refreshToken(refreshToken: string): Promise<OAuthCredentials> {
+    const tokenData = await this.refreshTokenWithConfig<OAuthTokenResponse>(
+      this.config.tokenUrl,
+      this.config.clientId,
+      refreshToken,
+      {
+        customHeaders: this.config.customHeaders,
+        contentType: "json",
+        tokenEndpointAuthMethod: this.config.tokenEndpointAuthMethod,
+      }
+    );
+
+    const credentials = this.buildCredentials(tokenData, refreshToken);
+    this.logger.info(
+      `Token refresh successful, expires_in: ${tokenData.expires_in}s`
+    );
+
+    return credentials;
+  }
+
+  private buildCredentials(
+    tokenData: {
+      access_token: string;
+      refresh_token?: string;
+      token_type?: string;
+      expires_in: number;
+      scope?: string;
+    },
+    fallbackRefreshToken?: string
+  ): OAuthCredentials {
+    const expiresAt = this.calculateExpiresAt(tokenData.expires_in)!;
+    const scopes = this.parseScopes(tokenData.scope);
+    const refreshToken = tokenData.refresh_token ?? fallbackRefreshToken;
+
+    if (!refreshToken && this.config.requireRefreshToken !== false) {
+      throw new Error(
+        `${this.config.name} OAuth response missing refresh token`
+      );
+    }
+
+    return {
+      accessToken: tokenData.access_token,
+      refreshToken,
+      tokenType: tokenData.token_type || "Bearer",
+      expiresAt,
+      scopes,
+    };
+  }
+
+  /**
+   * Get the provider configuration (useful for debugging)
+   */
+  getConfig(): OAuthProviderConfig {
+    return { ...this.config };
+  }
+}

package/src/auth/oauth/credentials.ts

@@ -0,0 +1,7 @@
+export interface OAuthCredentials {
+  accessToken: string;
+  refreshToken?: string;
+  tokenType: string;
+  expiresAt: number; // Unix timestamp in milliseconds
+  scopes: string[];
+}

package/src/auth/oauth/providers.ts

@@ -0,0 +1,69 @@
+/**
+ * OAuth 2.0 Provider Configurations
+ *
+ * Centralizes OAuth provider settings for easy addition of new providers.
+ * Each provider defines its endpoints, client credentials, and OAuth-specific settings.
+ */
+
+export interface OAuthProviderConfig {
+  /** Unique provider identifier */
+  id: string;
+  /** Human-readable provider name */
+  name: string;
+  /** OAuth 2.0 client ID (public identifier) */
+  clientId: string;
+  /** OAuth 2.0 client secret (optional - not used for public clients with PKCE) */
+  clientSecret?: string;
+  /** Authorization endpoint URL */
+  authUrl: string;
+  /** Token exchange endpoint URL */
+  tokenUrl: string;
+  /** OAuth redirect URI */
+  redirectUri: string;
+  /** OAuth scopes (space-separated) */
+  scope: string;
+  /** Use PKCE for public clients (RFC 7636) */
+  usePKCE: boolean;
+  /** Response type (default: "code") */
+  responseType?: string;
+  /** Grant type (default: "authorization_code") */
+  grantType?: string;
+  /** Custom headers to include in token requests */
+  customHeaders?: Record<string, string>;
+  /** Token endpoint auth method */
+  tokenEndpointAuthMethod?:
+    | "none"
+    | "client_secret_post"
+    | "client_secret_basic";
+  /** Whether auth-code exchange must include refresh_token */
+  requireRefreshToken?: boolean;
+}
+
+/**
+ * Claude OAuth Configuration
+ * - Public client (no client secret)
+ * - Uses PKCE for security
+ * - Requires browser-like headers (anti-bot protection)
+ */
+export const CLAUDE_PROVIDER: OAuthProviderConfig = {
+  id: "claude",
+  name: "Claude",
+  clientId: "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+  authUrl: "https://claude.ai/oauth/authorize",
+  tokenUrl: "https://console.anthropic.com/v1/oauth/token",
+  redirectUri: "https://console.anthropic.com/oauth/code/callback",
+  scope: "user:inference",
+  usePKCE: true,
+  responseType: "code",
+  grantType: "authorization_code",
+  tokenEndpointAuthMethod: "none",
+  requireRefreshToken: true,
+  customHeaders: {
+    "User-Agent":
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    Accept: "application/json, text/plain, */*",
+    "Accept-Language": "en-US,en;q=0.9",
+    Referer: "https://claude.ai/",
+    Origin: "https://claude.ai",
+  },
+};