@antseed/provider-core 0.1.0

package/src/http-relay.ts

@@ -0,0 +1,187 @@
+import type { TokenProvider } from '@antseed/node';
+import type { SerializedHttpRequest, SerializedHttpResponse, SerializedHttpResponseChunk } from '@antseed/node';
+import { swapAuthHeader, validateRequestModel } from './auth-swap.js';
+
+/** Hop-by-hop headers that must not be forwarded. */
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailers', 'transfer-encoding', 'upgrade',
+]);
+
+/** Internal headers used only within Antseed routing. */
+const INTERNAL_HEADERS = new Set([
+  'x-antseed-provider',
+]);
+
+export interface RelayConfig {
+  baseUrl: string;
+  authHeaderName: string;
+  authHeaderValue: string;
+  tokenProvider?: TokenProvider;
+  extraHeaders?: Record<string, string>;
+  maxConcurrency: number;
+  allowedModels: string[];
+  timeoutMs?: number;
+}
+
+export interface RelayCallbacks {
+  onResponse: (response: SerializedHttpResponse) => void;
+  onResponseChunk?: (chunk: SerializedHttpResponseChunk) => void;
+}
+
+export class HttpRelay {
+  private readonly _config: RelayConfig;
+  private readonly _callbacks: RelayCallbacks;
+  private _activeCount = 0;
+
+  constructor(config: RelayConfig, callbacks: RelayCallbacks) {
+    this._config = config;
+    this._callbacks = callbacks;
+  }
+
+  getActiveCount(): number {
+    return this._activeCount;
+  }
+
+  private _sendError(requestId: string, statusCode: number, error: string): void {
+    this._callbacks.onResponse({
+      requestId,
+      statusCode,
+      headers: { 'content-type': 'application/json' },
+      body: new TextEncoder().encode(JSON.stringify({ error })),
+    });
+  }
+
+  async handleRequest(request: SerializedHttpRequest): Promise<void> {
+    // Validate model against allowedModels
+    const validationError = validateRequestModel(request, this._config.allowedModels);
+    if (validationError) {
+      this._sendError(request.requestId, 403, validationError);
+      return;
+    }
+
+    // Check concurrency
+    if (this._activeCount >= this._config.maxConcurrency) {
+      this._sendError(request.requestId, 429, 'Max concurrency reached');
+      return;
+    }
+
+    // Increment active count
+    this._activeCount++;
+
+    try {
+      // Resolve dynamic auth token if provider uses OAuth / keychain
+      let effectiveConfig: { authHeaderName: string; authHeaderValue: string; extraHeaders?: Record<string, string> } = {
+        authHeaderName: this._config.authHeaderName,
+        authHeaderValue: this._config.authHeaderValue,
+        extraHeaders: this._config.extraHeaders,
+      };
+      if (this._config.tokenProvider) {
+        const freshToken = await this._config.tokenProvider.getToken();
+        // Preserve Bearer prefix for OAuth providers that use Authorization header
+        const isBearer = this._config.authHeaderName === 'authorization';
+        const headerValue = isBearer ? `Bearer ${freshToken}` : freshToken;
+        effectiveConfig = { ...effectiveConfig, authHeaderValue: headerValue };
+      }
+
+      // Swap auth headers
+      const swappedRequest = swapAuthHeader(request, effectiveConfig);
+
+      // Build upstream URL
+      const base = this._config.baseUrl.replace(/\/+$/, '');
+      const path = request.path.startsWith('/') ? request.path : `/${request.path}`;
+      const url = `${base}${path}`;
+
+      // Build fetch headers, stripping hop-by-hop
+      const fetchHeaders: Record<string, string> = {};
+      for (const [key, value] of Object.entries(swappedRequest.headers)) {
+        const lower = key.toLowerCase();
+        if (!HOP_BY_HOP_HEADERS.has(lower) && !INTERNAL_HEADERS.has(lower) && lower !== 'host' && lower !== 'content-length' && lower !== 'accept-encoding') {
+          fetchHeaders[key] = value;
+        }
+      }
+
+      const timeoutMs = this._config.timeoutMs ?? 120_000;
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      let fetchResponse: Response;
+      try {
+        fetchResponse = await fetch(url, {
+          method: swappedRequest.method,
+          headers: fetchHeaders,
+          body: swappedRequest.method !== 'GET' && swappedRequest.method !== 'HEAD'
+            ? Buffer.from(swappedRequest.body)
+            : undefined,
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+
+      const contentType = fetchResponse.headers.get('content-type') ?? '';
+      const isSSE = contentType.includes('text/event-stream');
+
+      // Build response headers, stripping hop-by-hop and encoding headers.
+      // Node.js fetch auto-decompresses gzip/br responses, so we must strip
+      // content-encoding to prevent the client from double-decompressing.
+      const responseHeaders: Record<string, string> = {};
+      fetchResponse.headers.forEach((value, key) => {
+        const lower = key.toLowerCase();
+        if (!HOP_BY_HOP_HEADERS.has(lower) && lower !== 'content-encoding' && lower !== 'content-length') {
+          responseHeaders[lower] = value;
+        }
+      });
+
+      if (isSSE && fetchResponse.body) {
+        // Accumulate SSE body and send as a complete response so that
+        // upstream response headers (request-id, usage metadata, etc.)
+        // are preserved for the buyer.
+        const reader = fetchResponse.body.getReader();
+        const chunks: Uint8Array[] = [];
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            chunks.push(value);
+          }
+        } catch (err) {
+          chunks.push(
+            new TextEncoder().encode(
+              `event: error\ndata: ${err instanceof Error ? err.message : 'stream error'}\n\n`
+            ),
+          );
+        }
+
+        const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+        const body = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const c of chunks) {
+          body.set(c, offset);
+          offset += c.length;
+        }
+
+        this._callbacks.onResponse({
+          requestId: request.requestId,
+          statusCode: fetchResponse.status,
+          headers: responseHeaders,
+          body,
+        });
+      } else {
+        // Complete response
+        const body = new Uint8Array(await fetchResponse.arrayBuffer());
+        this._callbacks.onResponse({
+          requestId: request.requestId,
+          statusCode: fetchResponse.status,
+          headers: responseHeaders,
+          body,
+        });
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const sanitized = errMsg.replace(/sk-ant-[a-zA-Z0-9_-]+/g, 'sk-***');
+      this._sendError(request.requestId, 502, `Upstream error: ${sanitized}`);
+    } finally {
+      this._activeCount--;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { HttpRelay, type RelayConfig, type RelayCallbacks } from './http-relay.js';
+export { swapAuthHeader, validateRequestModel, KNOWN_AUTH_HEADERS } from './auth-swap.js';
+export { StaticTokenProvider, OAuthTokenProvider, createTokenProvider, type AuthType } from './token-providers.js';
+export type { TokenProvider, TokenProviderState } from './token-providers.js';
+export { BaseProvider, type BaseProviderConfig } from './base-provider.js';

package/src/token-providers.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { StaticTokenProvider, OAuthTokenProvider, createTokenProvider } from './token-providers.js';
+
+describe('StaticTokenProvider', () => {
+  it('returns the static token', async () => {
+    const provider = new StaticTokenProvider('sk-test-key');
+    const token = await provider.getToken();
+    expect(token).toBe('sk-test-key');
+  });
+
+  it('returns the same token on multiple calls', async () => {
+    const provider = new StaticTokenProvider('sk-test-key');
+    expect(await provider.getToken()).toBe('sk-test-key');
+    expect(await provider.getToken()).toBe('sk-test-key');
+  });
+
+  it('getState returns token state', () => {
+    const provider = new StaticTokenProvider('sk-test-key');
+    expect(provider.getState()).toEqual({ accessToken: 'sk-test-key' });
+  });
+
+  it('stop is a no-op', () => {
+    const provider = new StaticTokenProvider('sk-test-key');
+    expect(() => provider.stop()).not.toThrow();
+  });
+});
+
+describe('OAuthTokenProvider', () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    globalThis.fetch = fetchMock;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('returns access token when not expired', async () => {
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() + 60 * 60 * 1000, // 1 hour from now
+    });
+
+    const token = await provider.getToken();
+    expect(token).toBe('access-1');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('refreshes token when expired', async () => {
+    fetchMock.mockResolvedValueOnce(new Response(
+      JSON.stringify({
+        access_token: 'access-2',
+        refresh_token: 'refresh-2',
+        expires_in: 3600,
+      }),
+      { status: 200 },
+    ));
+
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() - 1000, // already expired
+    });
+
+    const token = await provider.getToken();
+    expect(token).toBe('access-2');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('refreshes when within 5 minute buffer', async () => {
+    fetchMock.mockResolvedValueOnce(new Response(
+      JSON.stringify({
+        access_token: 'access-refreshed',
+        expires_in: 3600,
+      }),
+      { status: 200 },
+    ));
+
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-old',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() + 2 * 60 * 1000, // 2 minutes from now (within 5 min buffer)
+    });
+
+    const token = await provider.getToken();
+    expect(token).toBe('access-refreshed');
+  });
+
+  it('deduplicates concurrent refresh calls', async () => {
+    let resolveRefresh!: (value: Response) => void;
+    const refreshPromise = new Promise<Response>((resolve) => { resolveRefresh = resolve; });
+    fetchMock.mockReturnValueOnce(refreshPromise);
+
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() - 1000,
+    });
+
+    // Start two concurrent getToken calls
+    const p1 = provider.getToken();
+    const p2 = provider.getToken();
+
+    resolveRefresh(new Response(
+      JSON.stringify({ access_token: 'access-new', expires_in: 3600 }),
+      { status: 200 },
+    ));
+
+    const [t1, t2] = await Promise.all([p1, p2]);
+    expect(t1).toBe('access-new');
+    expect(t2).toBe('access-new');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws on refresh failure', async () => {
+    fetchMock.mockResolvedValueOnce(new Response('Unauthorized', { status: 401 }));
+
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() - 1000,
+    });
+
+    await expect(provider.getToken()).rejects.toThrow('OAuth refresh failed (401)');
+  });
+
+  it('getState returns current state', () => {
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: 1234567890,
+    });
+
+    const state = provider.getState();
+    expect(state).toEqual({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: 1234567890,
+    });
+  });
+
+  it('updates refresh token when provided in response', async () => {
+    fetchMock.mockResolvedValueOnce(new Response(
+      JSON.stringify({
+        access_token: 'access-2',
+        refresh_token: 'refresh-2',
+        expires_in: 3600,
+      }),
+      { status: 200 },
+    ));
+
+    const provider = new OAuthTokenProvider({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() - 1000,
+    });
+
+    await provider.getToken();
+    const state = provider.getState();
+    expect(state.refreshToken).toBe('refresh-2');
+  });
+});
+
+describe('createTokenProvider', () => {
+  it('creates StaticTokenProvider for apikey type', () => {
+    const provider = createTokenProvider({ authType: 'apikey', authValue: 'sk-key' });
+    expect(provider).toBeInstanceOf(StaticTokenProvider);
+  });
+
+  it('defaults to StaticTokenProvider when authType is omitted', () => {
+    const provider = createTokenProvider({ authValue: 'sk-key' });
+    expect(provider).toBeInstanceOf(StaticTokenProvider);
+  });
+
+  it('creates OAuthTokenProvider for oauth type with refresh token', () => {
+    const provider = createTokenProvider({
+      authType: 'oauth',
+      authValue: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() + 3600_000,
+    });
+    expect(provider).toBeInstanceOf(OAuthTokenProvider);
+  });
+
+  it('creates StaticTokenProvider for oauth type without refresh token', () => {
+    const provider = createTokenProvider({
+      authType: 'oauth',
+      authValue: 'access-1',
+    });
+    expect(provider).toBeInstanceOf(StaticTokenProvider);
+  });
+});

package/src/token-providers.ts

@@ -0,0 +1,211 @@
+import type { TokenProvider, TokenProviderState } from '@antseed/node';
+
+export type { TokenProvider, TokenProviderState };
+
+const REFRESH_BUFFER_MS = 5 * 60 * 1000; // refresh 5 min before expiry
+const DEFAULT_REFRESH_TIMEOUT_MS = 15_000;
+const DEFAULT_OAUTH_TOKEN_ENDPOINT = 'https://console.anthropic.com/v1/oauth/token';
+
+function getRefreshTimeoutMs(): number {
+  const raw = process.env['ANTSEED_OAUTH_REFRESH_TIMEOUT_MS'];
+  if (!raw) {
+    return DEFAULT_REFRESH_TIMEOUT_MS;
+  }
+  const parsed = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_REFRESH_TIMEOUT_MS;
+  }
+  return parsed;
+}
+
+// ---------------------------------------------------------------------------
+// StaticTokenProvider
+// ---------------------------------------------------------------------------
+
+/** Wraps a static API key. No refresh logic. */
+export class StaticTokenProvider implements TokenProvider {
+  constructor(private readonly token: string) {}
+  async getToken(): Promise<string> {
+    return this.token;
+  }
+  stop(): void {}
+  getState(): TokenProviderState {
+    return { accessToken: this.token };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OAuthTokenProvider
+// ---------------------------------------------------------------------------
+
+interface OAuthState {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number; // epoch ms
+}
+
+type RefreshRequestEncoding = 'form' | 'json';
+
+/**
+ * Manages an OAuth access/refresh token pair.
+ * Transparently refreshes the access token when it nears expiry.
+ */
+export class OAuthTokenProvider implements TokenProvider {
+  private state: OAuthState;
+  private refreshPromise: Promise<string> | null = null;
+  private readonly tokenEndpoint: string;
+  private readonly requestEncoding: RefreshRequestEncoding;
+  private readonly clientId: string | undefined;
+
+  constructor(opts: {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    tokenEndpoint?: string;
+    requestEncoding?: RefreshRequestEncoding;
+    clientId?: string;
+  }) {
+    this.state = {
+      accessToken: opts.accessToken,
+      refreshToken: opts.refreshToken,
+      expiresAt: opts.expiresAt,
+    };
+    this.tokenEndpoint = opts.tokenEndpoint ?? DEFAULT_OAUTH_TOKEN_ENDPOINT;
+    this.requestEncoding = opts.requestEncoding ?? 'form';
+    this.clientId = opts.clientId;
+  }
+
+  async getToken(): Promise<string> {
+    if (!this.isExpiringSoon()) {
+      return this.state.accessToken;
+    }
+    // Deduplicate concurrent refresh calls
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.refresh().finally(() => {
+        this.refreshPromise = null;
+      });
+    }
+    return this.refreshPromise;
+  }
+
+  stop(): void {}
+
+  /** Expose current state for persistence. */
+  getState(): TokenProviderState {
+    return { ...this.state };
+  }
+
+  private isExpiringSoon(): boolean {
+    return Date.now() >= this.state.expiresAt - REFRESH_BUFFER_MS;
+  }
+
+  private async refresh(): Promise<string> {
+    const payload: Record<string, string> = {
+      grant_type: 'refresh_token',
+      refresh_token: this.state.refreshToken,
+    };
+    if (this.clientId) {
+      payload['client_id'] = this.clientId;
+    }
+
+    const headers =
+      this.requestEncoding === 'json'
+        ? { 'Content-Type': 'application/json' }
+        : { 'Content-Type': 'application/x-www-form-urlencoded' };
+    const body =
+      this.requestEncoding === 'json'
+        ? JSON.stringify(payload)
+        : new URLSearchParams(payload).toString();
+
+    const timeoutMs = getRefreshTimeoutMs();
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+    let res: Response;
+    try {
+      res = await fetch(this.tokenEndpoint, {
+        method: 'POST',
+        headers,
+        body,
+        signal: controller.signal,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (err instanceof Error && err.name === 'AbortError') {
+        throw new Error(
+          `OAuth refresh timed out after ${timeoutMs}ms while reaching ${this.tokenEndpoint}. ` +
+            'Check network/proxy/firewall access or use apikey auth.'
+        );
+      }
+      throw new Error(`OAuth refresh request failed: ${message}`);
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`OAuth refresh failed (${res.status}): ${text}`);
+    }
+
+    const data = (await res.json()) as {
+      access_token?: string;
+      accessToken?: string;
+      refresh_token?: string;
+      refreshToken?: string;
+      expires_in?: number;
+      expires_at?: number;
+      expiresAt?: number;
+    };
+
+    const newAccess = data.access_token ?? data.accessToken;
+    if (!newAccess) {
+      throw new Error('OAuth refresh response missing access token');
+    }
+
+    this.state.accessToken = newAccess;
+    if (data.refresh_token ?? data.refreshToken) {
+      this.state.refreshToken = (data.refresh_token ?? data.refreshToken)!;
+    }
+    if (data.expires_at ?? data.expiresAt) {
+      this.state.expiresAt = (data.expires_at ?? data.expiresAt)!;
+    } else if (data.expires_in) {
+      this.state.expiresAt = Date.now() + data.expires_in * 1000;
+    }
+
+    return this.state.accessToken;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export type AuthType = 'apikey' | 'oauth';
+
+/**
+ * Create the appropriate TokenProvider from config values.
+ */
+export function createTokenProvider(opts: {
+  authType?: AuthType;
+  authValue: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}): TokenProvider {
+  const authType = opts.authType ?? 'apikey';
+
+  switch (authType) {
+    case 'oauth':
+      if (!opts.refreshToken) {
+        // No refresh token — treat as static (works until expiry)
+        return new StaticTokenProvider(opts.authValue);
+      }
+      return new OAuthTokenProvider({
+        accessToken: opts.authValue,
+        refreshToken: opts.refreshToken,
+        expiresAt: opts.expiresAt ?? Date.now() + 3600_000,
+      });
+
+    default:
+      return new StaticTokenProvider(opts.authValue);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}