@anthropic-ai/sdk 0.92.0 → 0.94.0

package/src/lib/credentials/identity-token.ts

@@ -0,0 +1,37 @@
+import { AnthropicError } from '../../core/error';
+import type { IdentityTokenProvider } from './types';
+
+/**
+ * Reads a JWT from a file on every call. Supports automatic rotation
+ * (e.g. Kubernetes projected service-account tokens).
+ */
+export function identityTokenFromFile(path: string): IdentityTokenProvider {
+  if (!path) {
+    throw new AnthropicError('Identity token file path is empty');
+  }
+
+  return async () => {
+    const fs = await import('node:fs');
+    let content: string;
+    try {
+      content = await fs.promises.readFile(path, 'utf-8');
+    } catch (err) {
+      throw new AnthropicError(`Failed to read identity token file at ${path}: ${err}`);
+    }
+    const token = content.trim();
+    if (!token) {
+      throw new AnthropicError(`Identity token file at ${path} is empty`);
+    }
+    return token;
+  };
+}
+
+/**
+ * Wraps a static JWT string as an {@link IdentityTokenProvider}.
+ */
+export function identityTokenFromValue(token: string): IdentityTokenProvider {
+  if (!token) {
+    throw new AnthropicError('Identity token value is empty');
+  }
+  return () => token;
+}

package/src/lib/credentials/oidc-federation.ts

@@ -0,0 +1,140 @@
+import type { Fetch } from '../../internal/builtin-types';
+import type { AccessTokenProvider, IdentityTokenProvider } from './types';
+import {
+  FEDERATION_BETA_HEADER,
+  GRANT_TYPE_JWT_BEARER,
+  OAUTH_API_BETA_HEADER,
+  TOKEN_ENDPOINT,
+  WorkloadIdentityError,
+  parseTokenResponse,
+  redactSensitive,
+  requireSecureTokenEndpoint,
+} from './types';
+import { nowAsSeconds } from '../../internal/utils/time';
+import { VERSION } from '../../version';
+
+export type OIDCFederationConfig = {
+  identityTokenProvider: IdentityTokenProvider;
+  federationRuleId: string;
+  organizationId: string;
+  serviceAccountId?: string | undefined;
+  /**
+   * Optional `wrkspc_*` tagged ID, or the literal `"default"` to scope the
+   * token to the organization's default workspace. When omitted the server
+   * picks the rule's sole enabled workspace, else the org default if the rule
+   * covers it. Required when the rule enables more than one non-default
+   * workspace, or to target a specific workspace other than the one the
+   * server would pick. The minted token is workspace-scoped: per-request
+   * workspace selection (the `anthropic-workspace-id` header) is not supported
+   * for federation tokens — switching workspaces requires a new token exchange
+   * with a different `workspaceId`.
+   */
+  workspaceId?: string | undefined;
+  baseURL: string;
+  fetch: Fetch;
+  /**
+   * Overrides the outgoing User-Agent header on the token exchange. When
+   * empty, sends an SDK-identified UA so the token endpoint's access logs
+   * identify the caller.
+   */
+  userAgent?: string | undefined;
+};
+
+/**
+ * Exchanges an external OIDC JWT for an Anthropic access token via the
+ * RFC 7523 jwt-bearer grant.
+ *
+ * Each invocation performs a fresh token exchange. Wrap in a
+ * {@link TokenCache} to avoid exchanging on every request.
+ *
+ * Federation grants do not return a refresh token — callers re-exchange
+ * their assertion on expiry.
+ */
+export function oidcFederationProvider(config: OIDCFederationConfig): AccessTokenProvider {
+  return async () => {
+    requireSecureTokenEndpoint(config.baseURL);
+
+    const jwt = await config.identityTokenProvider();
+    // The token endpoint enforces a 16 KiB assertion limit; surface a clear
+    // client-side error so misconfigured projected-token sources are
+    // diagnosable without a server round-trip.
+    if (jwt.length > 16 * 1024) {
+      throw new WorkloadIdentityError(
+        `Identity token is ${Math.ceil(jwt.length / 1024)} KiB, exceeds the 16 KiB assertion limit`,
+      );
+    }
+
+    const body: Record<string, string> = {
+      grant_type: GRANT_TYPE_JWT_BEARER,
+      assertion: jwt,
+      federation_rule_id: config.federationRuleId,
+      organization_id: config.organizationId,
+    };
+    if (config.serviceAccountId) {
+      body['service_account_id'] = config.serviceAccountId;
+    }
+    if (config.workspaceId) {
+      body['workspace_id'] = config.workspaceId;
+    }
+
+    const url = `${config.baseURL}${TOKEN_ENDPOINT}`;
+    let resp: Response;
+    try {
+      resp = await config.fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'anthropic-beta': `${OAUTH_API_BETA_HEADER},${FEDERATION_BETA_HEADER}`,
+          'User-Agent': config.userAgent || `anthropic-sdk-typescript/${VERSION} oidcFederationProvider`,
+        },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      throw new WorkloadIdentityError(`Failed to reach token endpoint ${url}: ${err}`);
+    }
+
+    const requestId = resp.headers.get('Request-Id');
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '');
+      const redacted = redactSensitive(text);
+      // A 401 is hard to debug from the status code alone, so surface
+      // guidance: check the federation rule, optionally set a workspace ID
+      // (the most common fix when no workspaceId is configured), and point at
+      // the Workload identity page in Claude Console for the server-side
+      // authentication event log. Other statuses (5xx, 400, ...) get no hint.
+      let hint = '';
+      if (resp.status === 401) {
+        const hintMiddle =
+          config.workspaceId ? '' : (
+            "If your federation rule is scoped to multiple workspaces, set the ANTHROPIC_WORKSPACE_ID environment variable, the 'workspace_id' config key, or the `workspaceId` option. "
+          );
+        hint = ` Ensure your federation rule matches your identity token. ${hintMiddle}View your authentication events in the Workload identity page of Claude Console for more details.`;
+      }
+      throw new WorkloadIdentityError(
+        `Token exchange failed with status ${resp.status}${
+          requestId ? ` (request-id ${requestId})` : ''
+        }: ${redacted}${hint}`,
+        resp.status,
+        redacted,
+        requestId,
+      );
+    }
+
+    const data = await parseTokenResponse(resp, requestId);
+    const expiresIn = Number(data.expires_in);
+    if (!Number.isFinite(expiresIn)) {
+      throw new WorkloadIdentityError(
+        `Token endpoint response missing required fields: ${JSON.stringify(redactSensitive(data))}`,
+        resp.status,
+        redactSensitive(data),
+        requestId,
+      );
+    }
+
+    return {
+      token: data.access_token,
+      expiresAt: nowAsSeconds() + expiresIn,
+    };
+  };
+}

package/src/lib/credentials/token-cache.ts

@@ -0,0 +1,130 @@
+import type { AccessToken, AccessTokenProvider } from './types';
+import {
+  ADVISORY_REFRESH_BACKOFF_IN_SECONDS,
+  ADVISORY_REFRESH_THRESHOLD_IN_SECONDS,
+  MANDATORY_REFRESH_THRESHOLD_IN_SECONDS,
+} from './types';
+import { nowAsSeconds } from '../../internal/utils/time';
+
+/**
+ * Wraps an {@link AccessTokenProvider} with two-tier proactive refresh
+ * and concurrent deduplication.
+ *
+ * Refresh policy on each {@link getToken} call:
+ *
+ * - No cached token → call provider (blocking), cache, return.
+ * - Cached with `expiresAt == null` → return cached forever.
+ * - More than 120s remaining → return cached.
+ * - 30–120s remaining (advisory window) → return stale token immediately,
+ *   kick off background refresh. On failure, log and keep stale.
+ * - Less than 30s remaining or expired (mandatory) → block and refresh.
+ *   On failure, throw.
+ *
+ * Concurrent mandatory callers coalesce into a single provider call.
+ */
+export class TokenCache {
+  private provider: AccessTokenProvider;
+  private cached: AccessToken | null = null;
+  private pendingRefresh: Promise<AccessToken> | null = null;
+  private nextForce = false;
+  private lastAdvisoryError = 0;
+  private onAdvisoryRefreshError: ((err: unknown) => void) | undefined;
+
+  constructor(provider: AccessTokenProvider, onAdvisoryRefreshError?: (err: unknown) => void) {
+    this.provider = provider;
+    this.onAdvisoryRefreshError = onAdvisoryRefreshError;
+  }
+
+  async getToken(): Promise<string> {
+    const force = this.nextForce;
+    this.nextForce = false;
+    const cached = this.cached;
+
+    if (force || cached == null) {
+      const token = await this.refresh(force);
+      return token.token;
+    }
+
+    if (cached.expiresAt == null) {
+      return cached.token;
+    }
+
+    const remaining = cached.expiresAt - nowAsSeconds();
+
+    if (remaining > ADVISORY_REFRESH_THRESHOLD_IN_SECONDS) {
+      return cached.token;
+    }
+
+    if (remaining > MANDATORY_REFRESH_THRESHOLD_IN_SECONDS) {
+      this.backgroundRefresh();
+      return cached.token;
+    }
+
+    const token = await this.refresh();
+    return token.token;
+  }
+
+  /**
+   * Clears the cached token and marks the next {@link getToken} as a forced
+   * refresh, so the underlying provider bypasses any on-disk freshness check.
+   * Called after a 401 — the server has just told us the token is bad even
+   * if its `expires_at` still looks fresh.
+   */
+  invalidate(): void {
+    this.cached = null;
+    this.nextForce = true;
+  }
+
+  /**
+   * Mandatory refresh. Joins any in-flight refresh unless forced — a forced
+   * refresh must not coalesce into a non-forced one that may re-serve the
+   * same stale disk token.
+   */
+  private refresh(force = false): Promise<AccessToken> {
+    if (this.pendingRefresh && !force) {
+      return this.pendingRefresh;
+    }
+    return this.doRefresh(force);
+  }
+
+  /**
+   * Advisory background refresh. Shares the same in-flight promise as
+   * mandatory refreshes for deduplication, but swallows errors so the
+   * stale cached token keeps being served. Backs off for
+   * {@link ADVISORY_REFRESH_BACKOFF_IN_SECONDS} after a failure so an
+   * outage during the advisory window doesn't hammer the token endpoint.
+   */
+  private backgroundRefresh(): void {
+    if (this.pendingRefresh) {
+      return;
+    }
+    if (nowAsSeconds() - this.lastAdvisoryError < ADVISORY_REFRESH_BACKOFF_IN_SECONDS) {
+      return;
+    }
+    this.doRefresh().catch((err) => {
+      this.lastAdvisoryError = nowAsSeconds();
+      // Advisory failure: keep serving the stale cached token, but surface
+      // the error to the caller-provided hook so it can be logged.
+      this.onAdvisoryRefreshError?.(err);
+    });
+  }
+
+  /**
+   * Core refresh. Sets {@link pendingRefresh} so concurrent callers
+   * (both advisory and mandatory) coalesce into a single provider call.
+   */
+  private doRefresh(force = false): Promise<AccessToken> {
+    this.pendingRefresh = this.provider(force ? { forceRefresh: true } : undefined).then(
+      (token) => {
+        this.cached = token;
+        this.pendingRefresh = null;
+        return token;
+      },
+      (err) => {
+        this.pendingRefresh = null;
+        throw err;
+      },
+    );
+    return this.pendingRefresh;
+  }
+}

package/src/lib/credentials/types.ts

@@ -0,0 +1,295 @@
+import { AnthropicError } from '../../core/error';
+
+export type AccessToken = {
+  token: string;
+  /** Unix epoch seconds. `null` means no expiry (cache forever). */
+  expiresAt: number | null;
+};
+
+/**
+ * Mints or returns a cached access token.
+ *
+ * The optional `opts.forceRefresh` flag, set by {@link TokenCache.invalidate}
+ * after a 401, tells providers with on-disk caches (user_oauth, cachedExchange)
+ * to bypass their freshness short-circuit and always fetch fresh. Providers
+ * without a cache can ignore it.
+ */
+export type AccessTokenProvider = (opts?: { forceRefresh?: boolean }) => Promise<AccessToken>;
+
+export type IdentityTokenProvider = () => string | Promise<string>;
+
+export type CredentialResult = {
+  provider: AccessTokenProvider;
+  extraHeaders: Record<string, string>;
+  /**
+   * The `base_url` from the resolved config/profile, if any. The client
+   * applies this to outbound API requests when no explicit `baseURL` (constructor
+   * option or `ANTHROPIC_BASE_URL` env) was given, so a profile pointing at a
+   * non-default API host both mints its token against that host AND sends
+   * subsequent API requests there.
+   */
+  baseURL?: string | undefined;
+};
+
+/** Response body from `POST /v1/oauth/token`. */
+export type TokenEndpointResponse = {
+  access_token?: string;
+  expires_in?: number;
+  refresh_token?: string;
+};
+
+export const GRANT_TYPE_JWT_BEARER = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+export const GRANT_TYPE_REFRESH_TOKEN = 'refresh_token';
+export const TOKEN_ENDPOINT = '/v1/oauth/token';
+
+/**
+ * `anthropic-beta` value required on authenticated API requests using an
+ * OAuth bearer token, and on `refresh_token` grants against the token endpoint.
+ */
+export const OAUTH_API_BETA_HEADER = 'oauth-2025-04-20';
+
+/**
+ * `anthropic-beta` value required on jwt-bearer exchanges against the token
+ * endpoint. It routes the request to the federation service; it must NOT be
+ * sent on `refresh_token` grants, which are handled by a different backend.
+ */
+export const FEDERATION_BETA_HEADER = 'oidc-federation-2026-04-01';
+
+export const ADVISORY_REFRESH_THRESHOLD_IN_SECONDS = 120;
+export const MANDATORY_REFRESH_THRESHOLD_IN_SECONDS = 30;
+export const ADVISORY_REFRESH_BACKOFF_IN_SECONDS = 5;
+
+const MAX_TOKEN_RESPONSE_BYTES = 1 << 20;
+
+/**
+ * Rejects base URLs that would cause a JWT assertion or refresh token to be
+ * sent over cleartext HTTP. Loopback hosts are allowed for local development.
+ */
+export function requireSecureTokenEndpoint(baseURL: string): void {
+  if (!baseURL) return;
+  let u: URL;
+  try {
+    u = new URL(baseURL);
+  } catch (err) {
+    throw new WorkloadIdentityError(`Invalid token endpoint base URL "${baseURL}": ${err}`);
+  }
+  if (u.protocol === 'https:') return;
+  // WHATWG URL.hostname returns bracketed IPv6 ("[::1]"); Go's net/url strips them.
+  const host = u.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (u.protocol === 'http:' && (host === 'localhost' || host === '127.0.0.1' || host === '::1')) {
+    return;
+  }
+  throw new WorkloadIdentityError(`Refusing to send credential over non-https token endpoint "${baseURL}"`);
+}
+
+/**
+ * Reads the response body as text, parses it as a token-endpoint JSON
+ * response, validates `access_token` is present, and rejects a non-Bearer
+ * `token_type` when one is provided. Reads at most
+ * {@link MAX_TOKEN_RESPONSE_BYTES} from the body stream.
+ */
+export async function parseTokenResponse(
+  resp: Response,
+  requestId: string | null,
+): Promise<TokenEndpointResponse & { access_token: string }> {
+  const text = await readLimitedText(resp);
+  let data: TokenEndpointResponse & { token_type?: string };
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new WorkloadIdentityError(
+      `Token endpoint returned non-JSON response (status ${resp.status})`,
+      resp.status,
+      redactSensitive(text),
+      requestId,
+    );
+  }
+  if (!data.access_token) {
+    throw new WorkloadIdentityError(
+      `Token endpoint response missing access_token: ${JSON.stringify(redactSensitive(data))}`,
+      resp.status,
+      redactSensitive(data),
+      requestId,
+    );
+  }
+  if (data.token_type && data.token_type.toLowerCase() !== 'bearer') {
+    throw new WorkloadIdentityError(
+      `Token endpoint response: unsupported token_type "${data.token_type}" (want Bearer)`,
+      resp.status,
+      redactSensitive(data),
+      requestId,
+    );
+  }
+  return data as TokenEndpointResponse & { access_token: string };
+}
+
+const MAX_ERROR_BODY_CHARS = 2000;
+// RFC 6749 §5.2 standard error-response fields. Anything else in a token
+// endpoint error body is potentially echoed input (assertion, refresh_token,
+// access_token, …) and is dropped rather than allowlisted-with-exceptions.
+const SAFE_ERROR_KEYS = new Set(['error', 'error_description', 'error_uri']);
+
+/**
+ * Returns a redacted copy of a token-endpoint error body for safe inclusion
+ * in an exception. Strings are truncated; objects keep only the RFC 6749
+ * §5.2 error fields.
+ */
+export function redactSensitive(body: unknown): unknown {
+  if (body == null) return body;
+  if (typeof body === 'string') {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      if (body.length <= MAX_ERROR_BODY_CHARS) return body;
+      return body.slice(0, MAX_ERROR_BODY_CHARS) + `... <${body.length - MAX_ERROR_BODY_CHARS} more chars>`;
+    }
+    return JSON.stringify(redactSensitive(parsed));
+  }
+  if (typeof body === 'object' && !Array.isArray(body)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(body)) {
+      if (SAFE_ERROR_KEYS.has(k)) out[k] = v;
+    }
+    return out;
+  }
+  return null;
+}
+
+/**
+ * Best-effort safety check on a credentials file before reading it.
+ *
+ * On POSIX: resolves symlinks (so containerized deployments that mount the
+ * credential as a symlink to a tmpfs-backed file keep working), then rejects
+ * the resolved target if it is group- or world- readable or writable. A uid
+ * mismatch on the resolved target is surfaced via `onWarn` since
+ * root-written/app-read is common in init-container setups. No-op on Windows.
+ */
+export async function checkCredentialsFileSafety(
+  path: string,
+  onWarn: (msg: string) => void = (m) => console.warn(`anthropic-sdk: ${m}`),
+): Promise<void> {
+  if (typeof process === 'undefined' || process.platform === 'win32') return;
+  const fs = await import('node:fs');
+  let resolved = path;
+  let st;
+  try {
+    resolved = await fs.promises.realpath(path);
+    st = await fs.promises.stat(resolved);
+  } catch {
+    return; // ENOENT etc — let the subsequent read surface a precise error
+  }
+  const mode = st.mode & 0o777;
+  // 0o022 = group/world write; 0o044 = group/world read.
+  if (mode & 0o022) {
+    throw new WorkloadIdentityError(
+      `Credentials file at ${resolved} is group/world-writable (mode 0o${mode.toString(8)}); ` +
+        `this allows other local users to plant tokens. Run \`chmod 600 ${resolved}\`.`,
+    );
+  }
+  if (mode & 0o044) {
+    throw new WorkloadIdentityError(
+      `Credentials file at ${resolved} is group/world-readable (mode 0o${mode.toString(8)}); ` +
+        `run \`chmod 600 ${resolved}\` before retrying.`,
+    );
+  }
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) {
+    onWarn(
+      `credentials file at ${resolved} is owned by uid ${
+        st.uid
+      } (current process uid ${process.getuid()}); ` + `verify this is intentional.`,
+    );
+  }
+}
+
+/**
+ * Atomically writes JSON to `targetPath` via a `.tmp` sibling + rename,
+ * with fsync on the file and (best-effort) on the parent directory.
+ * Creates the parent directory with mode 0700 and the file with mode 0600.
+ */
+export async function writeCredentialsFileAtomic(targetPath: string, data: unknown): Promise<void> {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const dir = path.dirname(targetPath);
+  await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+  // Unique temp name avoids two concurrent writers (different processes or
+  // SDK instances) racing on the same '.tmp' sibling and corrupting each
+  // other's bytes mid-write before the rename.
+  const tmpPath = `${targetPath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    const fh = await fs.promises.open(tmpPath, 'w', 0o600);
+    try {
+      await fh.writeFile(JSON.stringify(data, null, 2));
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    await fs.promises.rename(tmpPath, targetPath);
+  } catch (err) {
+    // Don't leak the temp file if anything between create and rename failed.
+    await fs.promises.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
+  // fsync the parent directory so the rename survives a crash.
+  try {
+    const dirFh = await fs.promises.open(dir, 'r');
+    try {
+      await dirFh.sync();
+    } finally {
+      await dirFh.close();
+    }
+  } catch {
+    // Directory fsync is best-effort (unsupported on some platforms, e.g. Windows).
+  }
+}
+
+async function readLimitedText(resp: Response): Promise<string> {
+  if (!resp.body) {
+    return '';
+  }
+  const reader = resp.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let received = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (received + value.length > MAX_TOKEN_RESPONSE_BYTES) {
+      const remaining = MAX_TOKEN_RESPONSE_BYTES - received;
+      if (remaining > 0) chunks.push(value.subarray(0, remaining));
+      await reader.cancel();
+      break;
+    }
+    chunks.push(value);
+    received += value.length;
+  }
+  let merged: Uint8Array;
+  if (chunks.length === 1) {
+    merged = chunks[0]!;
+  } else {
+    merged = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let offset = 0;
+    for (const c of chunks) {
+      merged.set(c, offset);
+      offset += c.length;
+    }
+  }
+  return new TextDecoder('utf-8').decode(merged);
+}
+
+export class WorkloadIdentityError extends AnthropicError {
+  readonly statusCode: number | null;
+  readonly body: unknown;
+  readonly requestId: string | null;
+
+  constructor(
+    message: string,
+    statusCode: number | null = null,
+    body: unknown = null,
+    requestId: string | null = null,
+  ) {
+    super(message);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.requestId = requestId;
+  }
+}