@uploadista/client-core 0.0.3

package/src/auth/__tests__/saas-auth.test.ts

@@ -0,0 +1,337 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SaasAuthManager } from "../saas-auth";
+import type { SaasAuthConfig } from "../types";
+
+// Mock fetch globally
+global.fetch = vi.fn();
+
+describe("SaasAuthManager", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("fetchToken", () => {
+    it("should fetch token from auth server", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({
+          username: "user",
+          password: "pass",
+        }),
+      };
+
+      vi.mocked(global.fetch).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          token: "jwt-token-123",
+          expiresIn: 3600,
+        }),
+      });
+
+      const manager = new SaasAuthManager(config);
+      const result = await manager.fetchToken();
+
+      expect(result).toEqual({
+        token: "jwt-token-123",
+        expiresIn: 3600,
+      });
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://auth.example.com/token",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ username: "user", password: "pass" }),
+        },
+      );
+    });
+
+    it("should handle auth server errors", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "wrong" }),
+      };
+
+      vi.mocked(global.fetch).mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        text: async () => JSON.stringify({ error: "Invalid credentials" }),
+      });
+
+      const manager = new SaasAuthManager(config);
+
+      await expect(manager.fetchToken()).rejects.toThrow(
+        "Failed to fetch auth token: Invalid credentials",
+      );
+    });
+
+    it("should handle network errors", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch).mockRejectedValueOnce(new Error("Network error"));
+
+      const manager = new SaasAuthManager(config);
+
+      await expect(manager.fetchToken()).rejects.toThrow(
+        "Failed to fetch auth token: Network error",
+      );
+    });
+
+    it("should validate token response format", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ noToken: "here" }), // Missing token field
+      });
+
+      const manager = new SaasAuthManager(config);
+
+      await expect(manager.fetchToken()).rejects.toThrow(
+        "Auth server response missing 'token' field",
+      );
+    });
+  });
+
+  describe("attachToken", () => {
+    it("should attach token as Bearer header", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ token: "jwt-token-123" }),
+      });
+
+      const manager = new SaasAuthManager(config);
+      const result = await manager.attachToken({
+        "Content-Type": "application/json",
+      });
+
+      expect(result).toEqual({
+        "Content-Type": "application/json",
+        Authorization: "Bearer jwt-token-123",
+      });
+    });
+
+    it("should cache token and reuse it", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ token: "jwt-token-123" }),
+      });
+
+      const manager = new SaasAuthManager(config);
+
+      // First call - should fetch token
+      await manager.attachToken();
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+
+      // Second call - should use cached token
+      await manager.attachToken();
+      expect(global.fetch).toHaveBeenCalledTimes(1); // Still 1, not 2
+    });
+
+    it("should cache tokens per job ID", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch)
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-1" }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-2" }),
+        });
+
+      const manager = new SaasAuthManager(config);
+
+      // Fetch token for job 1
+      const result1 = await manager.attachToken({}, "job-1");
+      expect(result1.Authorization).toBe("Bearer jwt-token-1");
+
+      // Fetch token for job 2
+      const result2 = await manager.attachToken({}, "job-2");
+      expect(result2.Authorization).toBe("Bearer jwt-token-2");
+
+      // Reuse token for job 1
+      const result3 = await manager.attachToken({}, "job-1");
+      expect(result3.Authorization).toBe("Bearer jwt-token-1");
+
+      // Should have fetched twice (once per job)
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+    });
+
+    it("should refetch expired tokens", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      // First token expires in 1 second
+      vi.mocked(global.fetch)
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({
+            token: "jwt-token-old",
+            expiresIn: 0.001, // Expires very soon
+          }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-new" }),
+        });
+
+      const manager = new SaasAuthManager(config);
+
+      // First call - fetch initial token
+      await manager.attachToken();
+
+      // Wait for token to expire
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Second call - should fetch new token because old one expired
+      const result = await manager.attachToken();
+      expect(result.Authorization).toBe("Bearer jwt-token-new");
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("clearToken", () => {
+    it("should clear cached token for specific job", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch)
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-1" }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-2" }),
+        });
+
+      const manager = new SaasAuthManager(config);
+
+      // Cache token for job
+      await manager.attachToken({}, "job-1");
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+
+      // Clear token
+      manager.clearToken("job-1");
+
+      // Next call should fetch new token
+      await manager.attachToken({}, "job-1");
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("clearAllTokens", () => {
+    it("should clear all cached tokens", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch)
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-1" }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-2" }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-3" }),
+        });
+
+      const manager = new SaasAuthManager(config);
+
+      // Cache tokens for multiple jobs
+      await manager.attachToken({}, "job-1");
+      await manager.attachToken(); // Global token
+
+      // Clear all
+      manager.clearAllTokens();
+
+      // Next calls should fetch new tokens
+      await manager.attachToken();
+      expect(global.fetch).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("getCacheStats", () => {
+    it("should return cache statistics", async () => {
+      const config: SaasAuthConfig = {
+        mode: "saas",
+        authServerUrl: "https://auth.example.com/token",
+        getCredentials: () => ({ username: "user", password: "pass" }),
+      };
+
+      vi.mocked(global.fetch)
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-1" }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-2" }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ token: "jwt-token-3" }),
+        });
+
+      const manager = new SaasAuthManager(config);
+
+      // Initially empty
+      expect(manager.getCacheStats()).toEqual({
+        cachedJobCount: 0,
+        hasGlobalToken: false,
+      });
+
+      // Cache tokens
+      await manager.attachToken({}, "job-1");
+      await manager.attachToken({}, "job-2");
+      await manager.attachToken(); // Global
+
+      expect(manager.getCacheStats()).toEqual({
+        cachedJobCount: 2,
+        hasGlobalToken: true,
+      });
+    });
+  });
+});

package/src/auth/auth-http-client.ts

@@ -0,0 +1,150 @@
+import type {
+  HttpClient,
+  HttpRequestOptions,
+  HttpResponse,
+} from "../services/http-client";
+import type { DirectAuthManager } from "./direct-auth";
+import type { NoAuthManager } from "./no-auth";
+import type { SaasAuthManager } from "./saas-auth";
+
+/**
+ * Union type of all auth managers
+ */
+export type AuthManager = DirectAuthManager | SaasAuthManager | NoAuthManager;
+
+/**
+ * Auth-aware HTTP client wrapper.
+ *
+ * Wraps a standard HttpClient and automatically attaches authentication
+ * credentials/tokens to all HTTP requests based on the configured auth manager.
+ *
+ * The wrapper delegates all non-auth concerns (connection pooling, metrics, etc.)
+ * to the underlying HttpClient and only adds the auth layer on top.
+ */
+export class AuthHttpClient implements HttpClient {
+  constructor(
+    private httpClient: HttpClient,
+    private authManager: AuthManager,
+  ) {}
+
+  /**
+   * Make an HTTP request with authentication credentials attached.
+   * Calls the auth manager to attach credentials before delegating to the underlying client.
+   */
+  async request(
+    url: string,
+    options: HttpRequestOptions = {},
+  ): Promise<HttpResponse> {
+    try {
+      // Attach auth credentials to request headers
+      const authenticatedHeaders = await this.attachAuthCredentials(
+        options.headers || {},
+        url,
+      );
+
+      // Delegate to underlying HTTP client with authenticated headers
+      return await this.httpClient.request(url, {
+        ...options,
+        headers: authenticatedHeaders,
+        // include credentials for cors if needed
+        credentials:
+          this.authManager.getType() === "no-auth" ||
+          this.authManager.getType() === "saas"
+            ? "omit"
+            : (options.credentials ?? "include"),
+      });
+    } catch (error) {
+      // If auth fails, wrap error with context
+      if (error instanceof Error && error.message.includes("auth")) {
+        throw error; // Re-throw auth errors as-is
+      }
+
+      // For other errors, let them propagate
+      throw error;
+    }
+  }
+
+  /**
+   * Attach authentication credentials to request headers.
+   * Delegates to the appropriate auth manager method.
+   */
+  private async attachAuthCredentials(
+    headers: Record<string, string>,
+    url: string,
+  ): Promise<Record<string, string>> {
+    // Check if this is a DirectAuthManager or SaasAuthManager
+    if ("attachCredentials" in this.authManager) {
+      // DirectAuthManager or NoAuthManager
+      return await this.authManager.attachCredentials(headers);
+    }
+
+    if ("attachToken" in this.authManager) {
+      // SaasAuthManager - extract job ID from URL if present
+      const jobId = this.extractJobIdFromUrl(url);
+      return await this.authManager.attachToken(headers, jobId);
+    }
+
+    // Fallback - return headers unchanged
+    return headers;
+  }
+
+  /**
+   * Extract job ID from URL for SaaS mode token caching.
+   * Looks for patterns like /upload/{id} or /jobs/{id} in the URL.
+   */
+  private extractJobIdFromUrl(url: string): string | undefined {
+    // Match patterns like:
+    // - /api/upload/{uploadId}
+    // - /api/flow/{flowId}/{storageId}
+    // - /api/jobs/{jobId}/status
+    // - /api/jobs/{jobId}/continue/{nodeId}
+
+    const uploadMatch = url.match(/\/api\/upload\/([^/?]+)/);
+    if (uploadMatch) {
+      return uploadMatch[1];
+    }
+
+    const flowMatch = url.match(/\/api\/flow\/([^/?]+)/);
+    if (flowMatch) {
+      return flowMatch[1];
+    }
+
+    const jobMatch = url.match(/\/api\/jobs\/([^/?]+)/);
+    if (jobMatch) {
+      return jobMatch[1];
+    }
+
+    // No job ID found - SaaS mode will use global token
+    return undefined;
+  }
+
+  /**
+   * Delegate metrics methods to underlying HTTP client
+   */
+  getMetrics() {
+    return this.httpClient.getMetrics();
+  }
+
+  getDetailedMetrics() {
+    return this.httpClient.getDetailedMetrics();
+  }
+
+  reset() {
+    this.httpClient.reset();
+  }
+
+  async close() {
+    await this.httpClient.close();
+  }
+
+  async warmupConnections(urls: string[]) {
+    await this.httpClient.warmupConnections(urls);
+  }
+
+  /**
+   * Get the underlying auth manager for advanced use cases
+   */
+  getAuthManager(): AuthManager {
+    return this.authManager;
+  }
+}

package/src/auth/direct-auth.ts

@@ -0,0 +1,121 @@
+import type { Logger } from "../logger";
+import type { PlatformService } from "../services/platform-service";
+import type { DirectAuthConfig } from "./types";
+import { BaseAuthManager } from "./types";
+
+/**
+ * Direct auth manager - handles credential attachment for "bring your own auth" mode.
+ *
+ * This manager calls the user-provided getCredentials() function before each request
+ * and attaches the returned credentials (headers, cookies) to the HTTP request.
+ *
+ * Supports any authentication protocol: OAuth, JWT, API keys, session cookies, etc.
+ */
+export class DirectAuthManager extends BaseAuthManager {
+  constructor(
+    private config: DirectAuthConfig,
+    private platformService: PlatformService,
+    private logger: Logger,
+  ) {
+    super("direct");
+  }
+
+  /**
+   * Attach credentials to an HTTP request by calling getCredentials() and
+   * merging the returned headers/cookies with the request.
+   *
+   * @param headers - Existing request headers
+   * @returns Updated headers with credentials attached
+   * @throws Error if getCredentials() throws or returns invalid data
+   */
+  async attachCredentials(
+    headers: Record<string, string> = {},
+  ): Promise<Record<string, string>> {
+    try {
+      if (!this.config.getCredentials) {
+        return headers;
+      }
+
+      // Call user's credential provider (may be async)
+      const credentials = await Promise.resolve(this.config.getCredentials());
+
+      // Validate credentials
+      if (!credentials || typeof credentials !== "object") {
+        throw new Error(
+          "getCredentials() must return an object with headers and/or cookies",
+        );
+      }
+
+      // Merge credential headers with existing headers
+      const updatedHeaders = { ...headers };
+
+      if (credentials.headers) {
+        this.validateHeaders(credentials.headers);
+        Object.assign(updatedHeaders, credentials.headers);
+      }
+
+      // Note: Cookie handling would be browser-specific
+      // For now, we only support headers as cookies are automatically
+      // handled by the browser when using fetch()
+      if (credentials.cookies) {
+        this.attachCookies(updatedHeaders, credentials.cookies);
+      }
+
+      return updatedHeaders;
+    } catch (error) {
+      // Wrap errors with context
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to attach auth credentials: ${message}`);
+    }
+  }
+
+  /**
+   * Validate that headers is a valid object with string keys and values
+   */
+  private validateHeaders(headers: Record<string, string>): void {
+    if (typeof headers !== "object" || headers === null) {
+      throw new Error("headers must be an object");
+    }
+
+    for (const [key, value] of Object.entries(headers)) {
+      if (typeof key !== "string" || typeof value !== "string") {
+        throw new Error(
+          `Invalid header: key and value must be strings (got ${key}: ${typeof value})`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Attach cookies to request headers.
+   * In browser environments, cookies are automatically handled by fetch().
+   * In Node.js, we need to manually add them to the Cookie header.
+   */
+  private attachCookies(
+    headers: Record<string, string>,
+    cookies: Record<string, string>,
+  ): void {
+    // Check if we're in a browser environment
+    const isBrowser = this.platformService.isBrowser();
+
+    if (isBrowser) {
+      // In browsers, fetch() automatically sends cookies for same-origin requests
+      // For cross-origin, the server needs to set CORS headers and credentials: 'include'
+      // We can't manually set cookies in headers for security reasons
+      // So we just warn if cookies are provided in direct mode
+      this.logger.warn(
+        "DirectAuth: Cookies are automatically handled by the browser. " +
+          "Ensure your server has proper CORS configuration with credentials support.",
+      );
+    } else {
+      // In Node.js, we can manually build the Cookie header
+      const cookieString = Object.entries(cookies)
+        .map(([key, value]) => `${key}=${value}`)
+        .join("; ");
+
+      if (cookieString) {
+        headers.Cookie = cookieString;
+      }
+    }
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,5 @@
+export * from "./auth-http-client";
+export * from "./direct-auth";
+export * from "./no-auth";
+export * from "./saas-auth";
+export * from "./types";

package/src/auth/no-auth.ts

@@ -0,0 +1,39 @@
+import { BaseAuthManager } from "./types";
+
+/**
+ * No-auth manager - pass-through implementation for backward compatibility.
+ *
+ * When no auth configuration is provided, this manager is used to maintain
+ * a consistent interface without adding any authentication to requests.
+ */
+export class NoAuthManager extends BaseAuthManager {
+  constructor() {
+    super("no-auth");
+  }
+
+  /**
+   * Pass through headers without modification.
+   *
+   * @param headers - Existing request headers
+   * @returns Same headers unchanged
+   */
+  async attachCredentials(
+    headers: Record<string, string> = {},
+  ): Promise<Record<string, string>> {
+    return headers;
+  }
+
+  /**
+   * No-op for clearing tokens (NoAuthManager doesn't cache anything)
+   */
+  clearToken(_jobId: string): void {
+    // No-op
+  }
+
+  /**
+   * No-op for clearing all tokens
+   */
+  clearAllTokens(): void {
+    // No-op
+  }
+}