@puku-ai/sdk 4.0.3 → 4.0.4

package/dist/vendor/lib/credentials/credential-chain.cjs

@@ -0,0 +1,244 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCredentialsFromConfig = resolveCredentialsFromConfig;
+exports.defaultCredentials = defaultCredentials;
+const env_1 = require("../../internal/utils/env");
+const credentials_1 = require("../../core/credentials");
+const types_1 = require("./types");
+const time_1 = require("../../internal/utils/time");
+const identity_token_1 = require("./identity-token");
+const oidc_federation_1 = require("./oidc-federation");
+const user_oauth_1 = require("./user-oauth");
+function resolveCredentialsFromConfig(config, options) {
+    const credentialsPath = config.authentication.credentials_path ?? null;
+    const effectiveBaseURL = (config.base_url || options.baseURL).replace(/\/+$/, '');
+    const provider = buildProvider(config, credentialsPath, effectiveBaseURL, options);
+    const extraHeaders = {};
+    // For federation profiles workspace_id is sent in the jwt-bearer exchange
+    // body, not as a request header (the minted token is already
+    // workspace-scoped, so the header would be ignored).
+    if (config.workspace_id && config.authentication.type === 'user_oauth') {
+        extraHeaders['puku-workspace-id'] = config.workspace_id;
+    }
+    // Surface the profile's own base_url (not the options.baseURL fallback) so
+    // the client can adopt it for outbound API requests when the caller didn't
+    // pin one explicitly. Echoing options.baseURL back would defeat precedence.
+    return { provider, extraHeaders, baseURL: config.base_url || undefined };
+}
+/**
+ * Resolves a {@link CredentialResult} from the environment. Returns `null`
+ * when no credentials can be resolved.
+ *
+ * Resolution order:
+ *
+ *   1. Config file for the active profile (or the explicit `profile` argument)
+ *      → dispatch on `authentication.type` (`oidc_federation`, `user_oauth`)
+ *   2. Environment variables `PUKU_FEDERATION_RULE_ID` +
+ *      `PUKU_ORGANIZATION_ID` (+ identity token) → OIDC federation
+ *   3. Nothing matches → `null`
+ *
+ * Passing `profile` selects `<config_dir>/configs/<profile>.json` directly,
+ * skipping `PUKU_PROFILE` / `active_config` resolution.
+ */
+async function defaultCredentials(options, profile) {
+    const loaded = await (0, credentials_1.loadConfigWithSource)(profile);
+    if (!loaded) {
+        return null;
+    }
+    const { config, fromFile } = loaded;
+    // For file-loaded configs, default credentials_path to the per-profile
+    // location so user_oauth and federation caching work. Shallow-clone first
+    // so callers that retain a reference to the loaded config don't observe the
+    // patched-in default.
+    //
+    // Env-only credentials (no profile file on disk) skip the disk cache —
+    // matching the other SDKs. A disk cache keyed by profile path would
+    // re-serve a stale token after a change to PUKU_WORKSPACE_ID (or
+    // PUKU_ORGANIZATION_ID / PUKU_FEDERATION_RULE_ID) until the
+    // cached token expired, so the env-only chain stays in-memory only.
+    const withPath = config.authentication.credentials_path || !fromFile ?
+        config
+        : {
+            ...config,
+            authentication: {
+                ...config.authentication,
+                credentials_path: (await (0, credentials_1.getCredentialsPath)(config, profile)) ?? undefined,
+            },
+        };
+    return resolveCredentialsFromConfig(withPath, options);
+}
+function buildProvider(config, credentialsPath, baseURL, options) {
+    switch (config.authentication.type) {
+        case 'oidc_federation': {
+            const auth = config.authentication;
+            const identityProvider = resolveIdentityTokenProvider(auth);
+            if (!identityProvider) {
+                throw new types_1.WorkloadIdentityError('oidc_federation config requires an identity token (set authentication.identity_token, ' +
+                    'PUKU_IDENTITY_TOKEN_FILE, or PUKU_IDENTITY_TOKEN)');
+            }
+            if (!auth.federation_rule_id) {
+                throw new types_1.WorkloadIdentityError("oidc_federation config requires 'federation_rule_id'. Set it in authentication.federation_rule_id in your profile, or via PUKU_FEDERATION_RULE_ID (profile takes precedence).");
+            }
+            if (!config.organization_id) {
+                throw new types_1.WorkloadIdentityError('oidc_federation config requires organization_id (set PUKU_ORGANIZATION_ID or config.organization_id)');
+            }
+            const exchange = (0, oidc_federation_1.oidcFederationProvider)({
+                identityTokenProvider: identityProvider,
+                federationRuleId: auth.federation_rule_id,
+                organizationId: config.organization_id,
+                serviceAccountId: auth.service_account_id,
+                workspaceId: config.workspace_id,
+                baseURL,
+                fetch: options.fetch,
+                userAgent: options.userAgent,
+            });
+            // If there's a credentials file path, wrap the exchange with file caching
+            // (check file for fresh token before exchanging, write back after).
+            if (credentialsPath) {
+                return cachedExchangeProvider(exchange, credentialsPath, options.onCacheWriteError, options.onSafetyWarning);
+            }
+            return exchange;
+        }
+        case 'user_oauth': {
+            if (!credentialsPath) {
+                throw new types_1.WorkloadIdentityError('user_oauth config requires authentication.credentials_path ' +
+                    '(or load via a profile so it defaults to <config_dir>/credentials/<profile>.json)');
+            }
+            return (0, user_oauth_1.userOAuthProvider)({
+                credentialsPath,
+                clientId: config.authentication.client_id,
+                baseURL,
+                fetch: options.fetch,
+                userAgent: options.userAgent,
+                onSafetyWarning: options.onSafetyWarning,
+            });
+        }
+        default: {
+            const t = config.authentication.type;
+            throw new types_1.WorkloadIdentityError(`authentication.type "${t}" is not a known authentication type`);
+        }
+    }
+}
+/**
+ * Resolves the identity token provider from config fields or environment variables.
+ *
+ * Resolution order:
+ *   1. `identity_token.path` from the config (source: "file")
+ *   2. `PUKU_IDENTITY_TOKEN_FILE` env var
+ *   3. `PUKU_IDENTITY_TOKEN` env var (static value)
+ */
+function resolveIdentityTokenProvider(auth) {
+    if (auth.identity_token) {
+        // Cast needed to stringify an unknown source value for the error message:
+        // the on-disk JSON may contain a source this SDK version doesn't know about.
+        const source = auth.identity_token.source;
+        if (source !== 'file') {
+            throw new types_1.WorkloadIdentityError(`identity_token.source "${source}" is not supported by this SDK version (only "file")`);
+        }
+        if (!auth.identity_token.path) {
+            throw new types_1.WorkloadIdentityError(`identity_token.source "file" requires a non-empty path`);
+        }
+        return (0, identity_token_1.identityTokenFromFile)(auth.identity_token.path);
+    }
+    const tokenFile = (0, env_1.readEnv)('PUKU_IDENTITY_TOKEN_FILE');
+    if (tokenFile) {
+        return (0, identity_token_1.identityTokenFromFile)(tokenFile);
+    }
+    const tokenValue = (0, env_1.readEnv)('PUKU_IDENTITY_TOKEN');
+    if (tokenValue) {
+        return (0, identity_token_1.identityTokenFromValue)(tokenValue);
+    }
+    return null;
+}
+/**
+ * Wraps a federation exchange provider with credential file caching.
+ * Checks the file for a fresh token before exchanging, and writes the
+ * result back after a successful exchange (best-effort, atomic replace).
+ *
+ * Note: this is not cross-process serialized — two SDK instances that
+ * miss the cache simultaneously will both perform a full exchange and
+ * the last writer wins. That is acceptable: federation exchanges are
+ * idempotent and the cache is an optimization, not a correctness gate.
+ */
+function cachedExchangeProvider(exchange, credentialsPath, onCacheWriteError, onSafetyWarning) {
+    return async (opts) => {
+        const { fs } = await Promise.resolve().then(() => __importStar(require('../../internal/node')));
+        await (0, types_1.checkCredentialsFileSafety)(credentialsPath, onSafetyWarning);
+        // Try cached credentials file
+        let existing;
+        try {
+            const raw = await fs.promises.readFile(credentialsPath, 'utf-8');
+            existing = JSON.parse(raw);
+            const token = existing?.['access_token'];
+            if (token && !opts?.forceRefresh) {
+                const expiresAt = existing?.['expires_at'];
+                if (expiresAt == null || (0, time_1.nowAsSeconds)() < expiresAt - types_1.MANDATORY_REFRESH_THRESHOLD_IN_SECONDS) {
+                    return { token, expiresAt: expiresAt ?? null };
+                }
+            }
+        }
+        catch (err) {
+            // ENOENT or invalid-JSON → no usable cache, exchange fresh. Other
+            // errors (EACCES, EISDIR, …) indicate a broken cache path; surface to
+            // the optional hook so they're at least debuggable, then proceed.
+            const code = err?.code;
+            if (code !== 'ENOENT' && !(err instanceof SyntaxError)) {
+                onCacheWriteError?.(err);
+            }
+        }
+        // Exchange for a new token
+        const result = await exchange(opts);
+        // Write cache back (best-effort). Preserve any unknown keys from the
+        // existing file (notably refresh_token, in the unlikely case this path
+        // is shared with a user_oauth profile) so the federation cache writer
+        // doesn't clobber material it didn't own.
+        try {
+            await (0, types_1.writeCredentialsFileAtomic)(credentialsPath, {
+                ...(existing ?? {}),
+                version: credentials_1.CREDENTIALS_FILE_VERSION,
+                type: 'oauth_token',
+                access_token: result.token,
+                expires_at: result.expiresAt,
+            });
+        }
+        catch (err) {
+            // Best-effort caching: surface to the optional hook but never fail
+            // the exchange itself.
+            onCacheWriteError?.(err);
+        }
+        return result;
+    };
+}

package/dist/vendor/lib/credentials/identity-token.cjs

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityTokenFromFile = identityTokenFromFile;
+exports.identityTokenFromValue = identityTokenFromValue;
+const error_1 = require("../../core/error");
+/**
+ * Reads a JWT from a file on every call. Supports automatic rotation
+ * (e.g. Kubernetes projected service-account tokens).
+ */
+function identityTokenFromFile(path) {
+    if (!path) {
+        throw new error_1.PukuError('Identity token file path is empty');
+    }
+    return async () => {
+        const { fs } = await Promise.resolve().then(() => __importStar(require('../../internal/node')));
+        let content;
+        try {
+            content = await fs.promises.readFile(path, 'utf-8');
+        }
+        catch (err) {
+            throw new error_1.PukuError(`Failed to read identity token file at ${path}: ${err}`);
+        }
+        const token = content.trim();
+        if (!token) {
+            throw new error_1.PukuError(`Identity token file at ${path} is empty`);
+        }
+        return token;
+    };
+}
+/**
+ * Wraps a static JWT string as an {@link IdentityTokenProvider}.
+ */
+function identityTokenFromValue(token) {
+    if (!token) {
+        throw new error_1.PukuError('Identity token value is empty');
+    }
+    return () => token;
+}

package/dist/vendor/lib/credentials/oidc-federation.cjs

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oidcFederationProvider = oidcFederationProvider;
+const types_1 = require("./types");
+const time_1 = require("../../internal/utils/time");
+const version_1 = require("../../version");
+/**
+ * Exchanges an external OIDC JWT for an PukuAI 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.
+ */
+function oidcFederationProvider(config) {
+    return async () => {
+        (0, types_1.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 types_1.WorkloadIdentityError(`Identity token is ${Math.ceil(jwt.length / 1024)} KiB, exceeds the 16 KiB assertion limit`);
+        }
+        const body = {
+            grant_type: types_1.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}${types_1.TOKEN_ENDPOINT}`;
+        let resp;
+        try {
+            resp = await config.fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'puku-beta': `${types_1.OAUTH_API_BETA_HEADER},${types_1.FEDERATION_BETA_HEADER}`,
+                    'User-Agent': config.userAgent || `puku-ai-sdk-typescript/${version_1.VERSION} oidcFederationProvider`,
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new types_1.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 = (0, types_1.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 Puku 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 PUKU_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 Puku Console for more details.`;
+            }
+            throw new types_1.WorkloadIdentityError(`Token exchange failed with status ${resp.status}${requestId ? ` (request-id ${requestId})` : ''}: ${redacted}${hint}`, resp.status, redacted, requestId);
+        }
+        const data = await (0, types_1.parseTokenResponse)(resp, requestId);
+        const expiresIn = Number(data.expires_in);
+        if (!Number.isFinite(expiresIn)) {
+            throw new types_1.WorkloadIdentityError(`Token endpoint response missing required fields: ${JSON.stringify((0, types_1.redactSensitive)(data))}`, resp.status, (0, types_1.redactSensitive)(data), requestId);
+        }
+        return {
+            token: data.access_token,
+            expiresAt: (0, time_1.nowAsSeconds)() + expiresIn,
+        };
+    };
+}

package/dist/vendor/lib/credentials/token-cache.cjs

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenCache = void 0;
+const types_1 = require("./types");
+const time_1 = require("../../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.
+ */
+class TokenCache {
+    provider;
+    cached = null;
+    pendingRefresh = null;
+    nextForce = false;
+    lastAdvisoryError = 0;
+    onAdvisoryRefreshError;
+    constructor(provider, onAdvisoryRefreshError) {
+        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;