@tetral-ai/sdk 0.110.0-alpha.1

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 `TETRAL_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;
+  }
+}

package/src/lib/credentials/user-oauth.ts

@@ -0,0 +1,144 @@
+import type { Fetch } from '../../internal/builtin-types';
+import { CREDENTIALS_FILE_VERSION, type AnthropicCredentials } from '../../core/credentials';
+import type { AccessTokenProvider } from './types';
+import {
+  GRANT_TYPE_REFRESH_TOKEN,
+  MANDATORY_REFRESH_THRESHOLD_IN_SECONDS,
+  OAUTH_API_BETA_HEADER,
+  TOKEN_ENDPOINT,
+  WorkloadIdentityError,
+  checkCredentialsFileSafety,
+  parseTokenResponse,
+  redactSensitive,
+  requireSecureTokenEndpoint,
+  writeCredentialsFileAtomic,
+} from './types';
+import { nowAsSeconds } from '../../internal/utils/time';
+import { VERSION } from '../../version';
+
+export type UserOAuthConfig = {
+  credentialsPath: string;
+  clientId?: string | undefined;
+  baseURL: string;
+  fetch: Fetch;
+  userAgent?: string | undefined;
+  onSafetyWarning?: ((msg: string) => void) | undefined;
+};
+
+/**
+ * Reads a user-oauth credential file. Returns the cached access token while
+ * fresh; on expiry performs a `refresh_token` grant and writes the new
+ * tokens back to the credentials file (atomic replace, fsync'd).
+ *
+ * If `clientId` is empty, the access token is treated as static — the
+ * credentials file is read on every call but no refresh is attempted, and
+ * an expired token without a `refresh_token` raises.
+ */
+export function userOAuthProvider(config: UserOAuthConfig): AccessTokenProvider {
+  return async (opts) => {
+    const fs = await import('node:fs');
+
+    await checkCredentialsFileSafety(config.credentialsPath, config.onSafetyWarning);
+
+    let raw: string;
+    try {
+      raw = await fs.promises.readFile(config.credentialsPath, 'utf-8');
+    } catch (err) {
+      throw new WorkloadIdentityError(`Credentials file not found at ${config.credentialsPath}: ${err}`);
+    }
+    let creds: AnthropicCredentials;
+    try {
+      creds = JSON.parse(raw);
+    } catch (err) {
+      throw new WorkloadIdentityError(
+        `Credentials file at ${config.credentialsPath} is not valid JSON: ${err}`,
+      );
+    }
+
+    const accessToken = creds.access_token;
+    if (!accessToken) {
+      throw new WorkloadIdentityError(
+        `Credentials file at ${config.credentialsPath} must include 'access_token'`,
+      );
+    }
+
+    // Return cached token if still fresh (or no expiry info), unless the
+    // caller is forcing a refresh after a 401 — then go straight to refresh
+    // even if the file's expires_at still looks valid.
+    const expiresAt = creds.expires_at;
+    if (
+      !opts?.forceRefresh &&
+      (expiresAt == null || nowAsSeconds() < expiresAt - MANDATORY_REFRESH_THRESHOLD_IN_SECONDS)
+    ) {
+      return { token: accessToken, expiresAt: expiresAt ?? null };
+    }
+
+    const refreshToken = creds.refresh_token;
+    if (!config.clientId || !refreshToken) {
+      throw new WorkloadIdentityError(
+        `Access token at ${config.credentialsPath} has expired and no refresh is available ` +
+          `(client_id ${config.clientId ? 'set' : 'empty'}, refresh_token ${refreshToken ? 'set' : 'empty'})`,
+      );
+    }
+
+    requireSecureTokenEndpoint(config.baseURL);
+
+    const body: Record<string, string> = {
+      grant_type: GRANT_TYPE_REFRESH_TOKEN,
+      refresh_token: refreshToken,
+      client_id: config.clientId,
+    };
+
+    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,
+          'User-Agent': config.userAgent || `anthropic-sdk-typescript/${VERSION} userOAuthProvider`,
+        },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      throw new WorkloadIdentityError(`User OAuth refresh failed to reach token endpoint: ${err}`);
+    }
+
+    const requestId = resp.headers.get('Request-Id');
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '');
+      throw new WorkloadIdentityError(
+        `User OAuth refresh failed (HTTP ${resp.status}): ${redactSensitive(text)}`,
+        resp.status,
+        redactSensitive(text),
+        requestId,
+      );
+    }
+
+    const data = await parseTokenResponse(resp, requestId);
+    const expiresIn = Number(data.expires_in);
+    if (!Number.isFinite(expiresIn)) {
+      throw new WorkloadIdentityError(
+        `User OAuth refresh response missing or invalid expires_in: ${JSON.stringify(redactSensitive(data))}`,
+        resp.status,
+        redactSensitive(data),
+        requestId,
+      );
+    }
+    const newExpiresAt = nowAsSeconds() + expiresIn;
+    const newRefreshToken = data.refresh_token || refreshToken;
+
+    await writeCredentialsFileAtomic(config.credentialsPath, {
+      ...creds,
+      version: CREDENTIALS_FILE_VERSION,
+      type: 'oauth_token',
+      access_token: data.access_token,
+      expires_at: newExpiresAt,
+      refresh_token: newRefreshToken,
+    });
+
+    return { token: data.access_token, expiresAt: newExpiresAt };
+  };
+}

package/src/lib/credentials.ts

@@ -0,0 +1,3 @@
+export { type AccessToken, type AccessTokenProvider } from './credentials/types';
+export { type AnthropicConfig, type AuthenticationInfo, loadConfig } from '../core/credentials';
+export { resolveCredentialsFromConfig } from './credentials/credential-chain';

package/src/lib/environments/index.ts

@@ -0,0 +1,23 @@
+export {
+  WorkPoller,
+  type WorkPollerOptions,
+  POLL_BLOCK_MS,
+  backoff,
+  jitter,
+  isStatus,
+  is4xx,
+  isFatal4xx,
+} from './poller';
+export {
+  EnvironmentWorker,
+  type EnvironmentWorkerOptions,
+  type EnvironmentWorkerTools,
+  type HandleItemOptions,
+} from './worker';
+export {
+  SessionToolRunner,
+  type SessionToolRunnerOptions,
+  type DispatchedToolCall,
+  MANAGED_AGENTS_BETA,
+  DEFAULT_MAX_IDLE_MS,
+} from '../tools/SessionToolRunner';