@tetral-ai/sdk 0.110.0-alpha.1

package/lib/credentials/token-cache.d.mts

@@ -0,0 +1,54 @@
+import type { AccessTokenProvider } from "./types.mjs";
+/**
+ * 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 declare class TokenCache {
+    private provider;
+    private cached;
+    private pendingRefresh;
+    private nextForce;
+    private lastAdvisoryError;
+    private onAdvisoryRefreshError;
+    constructor(provider: AccessTokenProvider, onAdvisoryRefreshError?: (err: unknown) => void);
+    getToken(): Promise<string>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Core refresh. Sets {@link pendingRefresh} so concurrent callers
+     * (both advisory and mandatory) coalesce into a single provider call.
+     */
+    private doRefresh;
+}
+//# sourceMappingURL=token-cache.d.mts.map

package/lib/credentials/token-cache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.d.mts","sourceRoot":"","sources":["../../src/lib/credentials/token-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,mBAAmB,EAAE,oBAAgB;AAQhE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,sBAAsB,CAAuC;gBAEzD,QAAQ,EAAE,mBAAmB,EAAE,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI;IAKpF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IA6BjC;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;OAGG;IACH,OAAO,CAAC,SAAS;CAclB"}

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

@@ -0,0 +1,54 @@
+import type { AccessTokenProvider } from "./types.js";
+/**
+ * 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 declare class TokenCache {
+    private provider;
+    private cached;
+    private pendingRefresh;
+    private nextForce;
+    private lastAdvisoryError;
+    private onAdvisoryRefreshError;
+    constructor(provider: AccessTokenProvider, onAdvisoryRefreshError?: (err: unknown) => void);
+    getToken(): Promise<string>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Core refresh. Sets {@link pendingRefresh} so concurrent callers
+     * (both advisory and mandatory) coalesce into a single provider call.
+     */
+    private doRefresh;
+}
+//# sourceMappingURL=token-cache.d.ts.map

package/lib/credentials/token-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.d.ts","sourceRoot":"","sources":["../../src/lib/credentials/token-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,mBAAmB,EAAE,mBAAgB;AAQhE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,sBAAsB,CAAuC;gBAEzD,QAAQ,EAAE,mBAAmB,EAAE,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI;IAKpF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IA6BjC;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;OAGG;IACH,OAAO,CAAC,SAAS;CAclB"}

package/lib/credentials/token-cache.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenCache = void 0;
+const types_1 = require("./types.js");
+const time_1 = require("../../internal/utils/time.js");
+/**
+ * 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.
+ */
+class TokenCache {
+    constructor(provider, onAdvisoryRefreshError) {
+        this.cached = null;
+        this.pendingRefresh = null;
+        this.nextForce = false;
+        this.lastAdvisoryError = 0;
+        this.provider = provider;
+        this.onAdvisoryRefreshError = onAdvisoryRefreshError;
+    }
+    async getToken() {
+        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 - (0, time_1.nowAsSeconds)();
+        if (remaining > types_1.ADVISORY_REFRESH_THRESHOLD_IN_SECONDS) {
+            return cached.token;
+        }
+        if (remaining > types_1.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() {
+        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.
+     */
+    refresh(force = false) {
+        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.
+     */
+    backgroundRefresh() {
+        if (this.pendingRefresh) {
+            return;
+        }
+        if ((0, time_1.nowAsSeconds)() - this.lastAdvisoryError < types_1.ADVISORY_REFRESH_BACKOFF_IN_SECONDS) {
+            return;
+        }
+        this.doRefresh().catch((err) => {
+            this.lastAdvisoryError = (0, time_1.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.
+     */
+    doRefresh(force = false) {
+        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;
+    }
+}
+exports.TokenCache = TokenCache;
+//# sourceMappingURL=token-cache.js.map

package/lib/credentials/token-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.js","sourceRoot":"","sources":["../../src/lib/credentials/token-cache.ts"],"names":[],"mappings":"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"}

package/lib/credentials/token-cache.mjs

@@ -0,0 +1,108 @@
+import { ADVISORY_REFRESH_BACKOFF_IN_SECONDS, ADVISORY_REFRESH_THRESHOLD_IN_SECONDS, MANDATORY_REFRESH_THRESHOLD_IN_SECONDS, } from "./types.mjs";
+import { nowAsSeconds } from "../../internal/utils/time.mjs";
+/**
+ * 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 {
+    constructor(provider, onAdvisoryRefreshError) {
+        this.cached = null;
+        this.pendingRefresh = null;
+        this.nextForce = false;
+        this.lastAdvisoryError = 0;
+        this.provider = provider;
+        this.onAdvisoryRefreshError = onAdvisoryRefreshError;
+    }
+    async getToken() {
+        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() {
+        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.
+     */
+    refresh(force = false) {
+        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.
+     */
+    backgroundRefresh() {
+        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.
+     */
+    doRefresh(force = false) {
+        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;
+    }
+}
+//# sourceMappingURL=token-cache.mjs.map

package/lib/credentials/token-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.mjs","sourceRoot":"","sources":["../../src/lib/credentials/token-cache.ts"],"names":[],"mappings":"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"}

package/lib/credentials/types.d.mts

@@ -0,0 +1,96 @@
+import { AnthropicError } from "../../core/error.mjs";
+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 declare const GRANT_TYPE_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export declare const GRANT_TYPE_REFRESH_TOKEN = "refresh_token";
+export declare 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 declare 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 declare const FEDERATION_BETA_HEADER = "oidc-federation-2026-04-01";
+export declare const ADVISORY_REFRESH_THRESHOLD_IN_SECONDS = 120;
+export declare const MANDATORY_REFRESH_THRESHOLD_IN_SECONDS = 30;
+export declare const ADVISORY_REFRESH_BACKOFF_IN_SECONDS = 5;
+/**
+ * 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 declare function requireSecureTokenEndpoint(baseURL: string): void;
+/**
+ * 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 declare function parseTokenResponse(resp: Response, requestId: string | null): Promise<TokenEndpointResponse & {
+    access_token: string;
+}>;
+/**
+ * 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 declare function redactSensitive(body: unknown): unknown;
+/**
+ * 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 declare function checkCredentialsFileSafety(path: string, onWarn?: (msg: string) => void): Promise<void>;
+/**
+ * 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 declare function writeCredentialsFileAtomic(targetPath: string, data: unknown): Promise<void>;
+export declare class WorkloadIdentityError extends AnthropicError {
+    readonly statusCode: number | null;
+    readonly body: unknown;
+    readonly requestId: string | null;
+    constructor(message: string, statusCode?: number | null, body?: unknown, requestId?: string | null);
+}
+//# sourceMappingURL=types.d.mts.map

package/lib/credentials/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../src/lib/credentials/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAElD,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAE9F,MAAM,MAAM,qBAAqB,GAAG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,qBAAqB,gDAAgD,CAAC;AACnF,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AACxD,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE,eAAO,MAAM,qCAAqC,MAAM,CAAC;AACzD,eAAO,MAAM,sCAAsC,KAAK,CAAC;AACzD,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAIrD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAehE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,qBAAqB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B3D;AAQD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAoBtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAiD,GACzE,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCjG;AAmCD,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAM,GAAG,IAAW,EAChC,IAAI,GAAE,OAAc,EACpB,SAAS,GAAE,MAAM,GAAG,IAAW;CAOlC"}

package/lib/credentials/types.d.ts

@@ -0,0 +1,96 @@
+import { AnthropicError } from "../../core/error.js";
+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 declare const GRANT_TYPE_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export declare const GRANT_TYPE_REFRESH_TOKEN = "refresh_token";
+export declare 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 declare 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 declare const FEDERATION_BETA_HEADER = "oidc-federation-2026-04-01";
+export declare const ADVISORY_REFRESH_THRESHOLD_IN_SECONDS = 120;
+export declare const MANDATORY_REFRESH_THRESHOLD_IN_SECONDS = 30;
+export declare const ADVISORY_REFRESH_BACKOFF_IN_SECONDS = 5;
+/**
+ * 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 declare function requireSecureTokenEndpoint(baseURL: string): void;
+/**
+ * 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 declare function parseTokenResponse(resp: Response, requestId: string | null): Promise<TokenEndpointResponse & {
+    access_token: string;
+}>;
+/**
+ * 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 declare function redactSensitive(body: unknown): unknown;
+/**
+ * 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 declare function checkCredentialsFileSafety(path: string, onWarn?: (msg: string) => void): Promise<void>;
+/**
+ * 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 declare function writeCredentialsFileAtomic(targetPath: string, data: unknown): Promise<void>;
+export declare class WorkloadIdentityError extends AnthropicError {
+    readonly statusCode: number | null;
+    readonly body: unknown;
+    readonly requestId: string | null;
+    constructor(message: string, statusCode?: number | null, body?: unknown, requestId?: string | null);
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/credentials/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/credentials/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,4BAAyB;AAElD,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAE9F,MAAM,MAAM,qBAAqB,GAAG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,qBAAqB,gDAAgD,CAAC;AACnF,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AACxD,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE,eAAO,MAAM,qCAAqC,MAAM,CAAC;AACzD,eAAO,MAAM,sCAAsC,KAAK,CAAC;AACzD,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAIrD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAehE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,qBAAqB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B3D;AAQD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAoBtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAiD,GACzE,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCjG;AAmCD,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAM,GAAG,IAAW,EAChC,IAAI,GAAE,OAAc,EACpB,SAAS,GAAE,MAAM,GAAG,IAAW;CAOlC"}