@introspection-sdk/introspection-node 0.5.5 → 0.5.7

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @introspection-sdk/introspection-node@0.5.5 build /home/runner/work/introspection-js-sdk/introspection-js-sdk/packages/introspection-node
+> @introspection-sdk/introspection-node@0.5.7 build /home/runner/work/introspection-js-sdk/introspection-js-sdk/packages/introspection-node
 > tsc
 

package/dist/auth.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CP `POST /v1/oauth/token` response. No refresh token is issued for the
+ * machine grants — re-mint when it expires.
+ */
+export interface OAuthToken {
+    /** Project-scoped RS256 access token (`Authorization: Bearer …`). */
+    access_token: string;
+    /** Always `"Bearer"`. */
+    token_type: string;
+    /** Token lifetime in seconds. */
+    expires_in: number;
+    /** The granted (scope-capped) scope, when the CP returns one. */
+    scope: string | null;
+    /**
+     * Data Plane API base URL for the token's project, resolved by the CP the
+     * same way it is for the CLI login. `null` when the deployment can't be
+     * resolved; the caller then needs an explicit DP URL. Hand this to the
+     * browser SDK as `dpUrl` so the SPA connects without separate DP config.
+     */
+    dp_url: string | null;
+}
+export interface ServiceAccountTokenParams {
+    /** Confidential Application client id (`intro_app_…`). */
+    clientId: string;
+    /** Confidential Application client secret (`intro_sk_…`). */
+    clientSecret: string;
+    /**
+     * Project the token is scoped to. Required by the CP `client_credentials`
+     * grant — the minted token is project-scoped and the project must belong to
+     * the Application's organization.
+     */
+    projectId: string;
+    /**
+     * Optional space-separated scope. Capped server-side to the Application's
+     * `allowed_scopes`; omit to receive the Application's default scope.
+     */
+    scope?: string;
+    /**
+     * CP API base URL. Defaults to `INTROSPECTION_BASE_API_URL` or
+     * `https://api.introspection.dev`.
+     */
+    baseApiUrl?: string;
+    /** Custom `fetch` (for tests or non-standard runtimes). */
+    fetch?: typeof fetch;
+}
+/**
+ * Back-compat alias: the `client_credentials` response is the same shape as
+ * every other `/v1/oauth/token` response.
+ */
+export type ServiceAccountToken = OAuthToken;
+/**
+ * Mint a project-scoped CP access token from confidential service-account
+ * credentials. See {@link ServiceAccountTokenParams}.
+ *
+ * @example
+ * ```typescript
+ * const { access_token, dp_url } = await serviceAccountToken({
+ *   clientId: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_ID!,
+ *   clientSecret: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_SECRET!,
+ *   projectId: process.env.INTRO_PROJECT_ID!,
+ * });
+ * const client = new IntrospectionClient({ token: access_token });
+ * ```
+ */
+export declare function serviceAccountToken(params: ServiceAccountTokenParams): Promise<OAuthToken>;
+export interface AuthorizationCodeParams {
+    /** The authorization code returned to the redirect URI. */
+    code: string;
+    /** Public SPA Application `client_id` (PKCE — no secret). */
+    clientId: string;
+    /** The redirect URI the code was issued for (must match the authorize call). */
+    redirectUri: string;
+    /** The PKCE `code_verifier` paired with the authorize-step challenge. */
+    codeVerifier: string;
+    /**
+     * CP API base URL. Defaults to `INTROSPECTION_BASE_API_URL` or
+     * `https://api.introspection.dev`.
+     */
+    baseApiUrl?: string;
+    /** Custom `fetch` (for tests or non-standard runtimes). */
+    fetch?: typeof fetch;
+}
+/**
+ * RFC 6749 / PKCE `authorization_code` exchange against CP
+ * `POST /v1/oauth/token`. Run it in your backend so the browser hosted-login
+ * flow does not hand-roll the token POST.
+ */
+export declare function authorizationCodeToken(params: AuthorizationCodeParams): Promise<OAuthToken>;
+export interface TokenExchangeParams {
+    /** The end user's subject token (e.g. a partner-IdP `id_token`). */
+    subjectToken: string;
+    /** The federated Application's `client_id` (public client — no secret). */
+    clientId: string;
+    /** Project the minted DP token is scoped to. */
+    projectId: string;
+    /**
+     * The subject token's type URI. Defaults to
+     * `urn:ietf:params:oauth:token-type:id_token`.
+     */
+    subjectTokenType?: string;
+    /** Optional space-separated scope, capped server-side. */
+    scope?: string;
+    /**
+     * CP API base URL. Defaults to `INTROSPECTION_BASE_API_URL` or
+     * `https://api.introspection.dev`.
+     */
+    baseApiUrl?: string;
+    /** Custom `fetch` (for tests or non-standard runtimes). */
+    fetch?: typeof fetch;
+}
+/**
+ * RFC 8693 token-exchange against CP `POST /v1/oauth/token`: trade an end
+ * user's partner-IdP token for a project-scoped DP access token for a
+ * `member_type=customer` member. Intended to run server-side in a broker (the
+ * subject token shouldn't be re-handled in the browser longer than needed).
+ *
+ * @example
+ * ```typescript
+ * const { access_token, dp_url } = await tokenExchange({
+ *   subjectToken: idTokenFromPartnerIdp,
+ *   clientId: process.env.FEDERATED_CLIENT_ID!,
+ *   projectId: process.env.INTRO_PROJECT_ID!,
+ * });
+ * ```
+ */
+export declare function tokenExchange(params: TokenExchangeParams): Promise<OAuthToken>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAyDA;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,UAAU,CAAC,CAarB;AAED,MAAM,WAAW,uBAAuB;IACtC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAarB;AAED,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAcrB"}

package/dist/auth.js

@@ -0,0 +1,112 @@
+/**
+ * Service-account (machine) authentication for the Control Plane.
+ *
+ * Mints a short-lived, project-scoped Introspection access token via the
+ * OAuth 2.0 `client_credentials` grant against CP `POST /v1/oauth/token`.
+ * This is the headless / CI counterpart to a long-lived API key: the
+ * confidential Application's `client_id` + `client_secret` stay server-side,
+ * and you re-mint when the token expires (no refresh token is issued).
+ *
+ * The minted `access_token` is an ordinary CP bearer token, so it drops
+ * straight into the existing client surface — pass it to
+ * {@link IntrospectionClient}, or use
+ * {@link IntrospectionClient.fromServiceAccount} to mint and construct in one
+ * call, and the usual `client.runtimes("name").run()` flow works unchanged.
+ */
+import { stripTrailingSlash, toApiError } from "@introspection-sdk/http";
+const DEFAULT_BASE_API_URL = "https://api.introspection.dev";
+const GRANT_TYPE_CLIENT_CREDENTIALS = "client_credentials";
+const GRANT_TYPE_TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange";
+const GRANT_TYPE_AUTHORIZATION_CODE = "authorization_code";
+const SUBJECT_TOKEN_TYPE_ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token";
+function resolveBaseApiUrl(baseApiUrl) {
+    return stripTrailingSlash(baseApiUrl ??
+        process.env.INTROSPECTION_BASE_API_URL ??
+        DEFAULT_BASE_API_URL);
+}
+function resolveFetch(custom) {
+    const fetchImpl = custom ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("global fetch is unavailable; pass `fetch` or run on Node 18+");
+    }
+    return fetchImpl;
+}
+async function postTokenForm(baseApiUrl, form, fetchImpl) {
+    const res = await fetchImpl(`${baseApiUrl}/v1/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: form.toString(),
+        cache: "no-store",
+    });
+    if (!res.ok)
+        throw await toApiError(res);
+    return (await res.json());
+}
+/**
+ * Mint a project-scoped CP access token from confidential service-account
+ * credentials. See {@link ServiceAccountTokenParams}.
+ *
+ * @example
+ * ```typescript
+ * const { access_token, dp_url } = await serviceAccountToken({
+ *   clientId: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_ID!,
+ *   clientSecret: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_SECRET!,
+ *   projectId: process.env.INTRO_PROJECT_ID!,
+ * });
+ * const client = new IntrospectionClient({ token: access_token });
+ * ```
+ */
+export async function serviceAccountToken(params) {
+    const form = new URLSearchParams({
+        grant_type: GRANT_TYPE_CLIENT_CREDENTIALS,
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        project_id: params.projectId,
+    });
+    if (params.scope)
+        form.set("scope", params.scope);
+    return postTokenForm(resolveBaseApiUrl(params.baseApiUrl), form, resolveFetch(params.fetch));
+}
+/**
+ * RFC 6749 / PKCE `authorization_code` exchange against CP
+ * `POST /v1/oauth/token`. Run it in your backend so the browser hosted-login
+ * flow does not hand-roll the token POST.
+ */
+export async function authorizationCodeToken(params) {
+    const form = new URLSearchParams({
+        grant_type: GRANT_TYPE_AUTHORIZATION_CODE,
+        code: params.code,
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        code_verifier: params.codeVerifier,
+    });
+    return postTokenForm(resolveBaseApiUrl(params.baseApiUrl), form, resolveFetch(params.fetch));
+}
+/**
+ * RFC 8693 token-exchange against CP `POST /v1/oauth/token`: trade an end
+ * user's partner-IdP token for a project-scoped DP access token for a
+ * `member_type=customer` member. Intended to run server-side in a broker (the
+ * subject token shouldn't be re-handled in the browser longer than needed).
+ *
+ * @example
+ * ```typescript
+ * const { access_token, dp_url } = await tokenExchange({
+ *   subjectToken: idTokenFromPartnerIdp,
+ *   clientId: process.env.FEDERATED_CLIENT_ID!,
+ *   projectId: process.env.INTRO_PROJECT_ID!,
+ * });
+ * ```
+ */
+export async function tokenExchange(params) {
+    const form = new URLSearchParams({
+        grant_type: GRANT_TYPE_TOKEN_EXCHANGE,
+        subject_token: params.subjectToken,
+        subject_token_type: params.subjectTokenType ?? SUBJECT_TOKEN_TYPE_ID_TOKEN,
+        client_id: params.clientId,
+        project_id: params.projectId,
+    });
+    if (params.scope)
+        form.set("scope", params.scope);
+    return postTokenForm(resolveBaseApiUrl(params.baseApiUrl), form, resolveFetch(params.fetch));
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/client.d.ts

@@ -13,6 +13,7 @@
  */
 import type { AdvancedOptions } from "@introspection-sdk/types";
 import type { IntrospectionClientOptions } from "./types.js";
+import { type ServiceAccountTokenParams } from "./auth.js";
 import { HttpClient } from "./http.js";
 import { type RuntimeHandleFactory, type RuntimesApi } from "./resources/runtimes.js";
 import { type ExperimentHandleFactory, type ExperimentsApi } from "./resources/experiments.js";
@@ -60,6 +61,35 @@ export declare class IntrospectionClient {
      */
     readonly recipes: RecipesApi;
     constructor(options?: IntrospectionClientOptions);
+    /**
+     * Authenticate as a confidential service account and return a ready
+     * client.
+     *
+     * Mints a short-lived, project-scoped CP access token via the
+     * `client_credentials` grant (see {@link serviceAccountToken}) and wires
+     * it in as the bearer token, so the runtime flow works exactly as it does
+     * with an API key:
+     *
+     * @example
+     * ```typescript
+     * const client = await IntrospectionClient.fromServiceAccount({
+     *   clientId: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_ID!,
+     *   clientSecret: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_SECRET!,
+     *   projectId: process.env.INTRO_PROJECT_ID!,
+     * });
+     *
+     * // Resolved fresh from the runtime name on every call.
+     * const runner = await client.runtimes("customer-agent").run({
+     *   identity: { user_id: "u_demo" },
+     * });
+     * ```
+     *
+     * The token is not auto-refreshed: it lives for `expires_in` seconds, so
+     * re-mint (call this again) for long-lived processes once it lapses.
+     */
+    static fromServiceAccount(params: ServiceAccountTokenParams & {
+        serviceName?: string;
+    }): Promise<IntrospectionClient>;
     /** Close the underlying HTTP client. */
     shutdown(): Promise<void>;
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,oBAAoB,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,uBAAuB,CAAC;IAE/D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;gBAEjB,OAAO,GAAE,0BAA+B;IAgCpD,wCAAwC;IAClC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAuB,KAAK,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,oBAAoB,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,uBAAuB,CAAC;IAE/D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;gBAEjB,OAAO,GAAE,0BAA+B;IAgCpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACU,kBAAkB,CAC7B,MAAM,EAAE,yBAAyB,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3D,OAAO,CAAC,mBAAmB,CAAC;IAS/B,wCAAwC;IAClC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}

package/dist/client.js

@@ -12,6 +12,7 @@
  * `@introspection-sdk/introspection-node/otel`.
  */
 import { logger as sdkLogger } from "./utils.js";
+import { serviceAccountToken } from "./auth.js";
 import { HttpClient } from "./http.js";
 import { attachRuntimes, } from "./resources/runtimes.js";
 import { attachExperiments, } from "./resources/experiments.js";
@@ -82,6 +83,40 @@ export class IntrospectionClient {
         this.recipes = attachRecipes(this.cpHttp);
         sdkLogger.info(`IntrospectionClient initialized: api=${baseApiUrl}`);
     }
+    /**
+     * Authenticate as a confidential service account and return a ready
+     * client.
+     *
+     * Mints a short-lived, project-scoped CP access token via the
+     * `client_credentials` grant (see {@link serviceAccountToken}) and wires
+     * it in as the bearer token, so the runtime flow works exactly as it does
+     * with an API key:
+     *
+     * @example
+     * ```typescript
+     * const client = await IntrospectionClient.fromServiceAccount({
+     *   clientId: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_ID!,
+     *   clientSecret: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_SECRET!,
+     *   projectId: process.env.INTRO_PROJECT_ID!,
+     * });
+     *
+     * // Resolved fresh from the runtime name on every call.
+     * const runner = await client.runtimes("customer-agent").run({
+     *   identity: { user_id: "u_demo" },
+     * });
+     * ```
+     *
+     * The token is not auto-refreshed: it lives for `expires_in` seconds, so
+     * re-mint (call this again) for long-lived processes once it lapses.
+     */
+    static async fromServiceAccount(params) {
+        const { access_token } = await serviceAccountToken(params);
+        return new IntrospectionClient({
+            token: access_token,
+            serviceName: params.serviceName,
+            advanced: { baseApiUrl: params.baseApiUrl, fetch: params.fetch },
+        });
+    }
     /** Close the underlying HTTP client. */
     async shutdown() {
         // HttpClient has no persistent connections to close, but reserved

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,cAAc,GAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,GAGlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,aAAa,EAAmB,MAAM,wBAAwB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,mBAAmB;IAC9B,2EAA2E;IAClE,MAAM,CAAa;IAC5B,mFAAmF;IAC1E,eAAe,CAAkB;IAE1C;;;;;OAKG;IACM,QAAQ,CAAqC;IAEtD;;OAEG;IACM,WAAW,CAA2C;IAE/D;;;;OAIG;IACM,OAAO,CAAa;IAE7B,YAAY,UAAsC,EAAE;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC;QAChC,MAAM,UAAU,GACd,QAAQ,CAAC,UAAU;YACnB,OAAO,CAAC,GAAG,CAAC,0BAA0B;YACtC,+BAA+B,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,CACZ,+DAA+D,CAChE,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,qEAAqE;QACrE,6DAA6D;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,UAAU,CAAC;YAC3B,MAAM,EAAE,UAAU;YAClB,KAAK;YACL,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;YAC7C,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1C,SAAS,CAAC,IAAI,CAAC,wCAAwC,UAAU,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,QAAQ;QACZ,kEAAkE;QAClE,gDAAgD;QAChD,SAAS,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAkC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,cAAc,GAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,GAGlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,aAAa,EAAmB,MAAM,wBAAwB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,mBAAmB;IAC9B,2EAA2E;IAClE,MAAM,CAAa;IAC5B,mFAAmF;IAC1E,eAAe,CAAkB;IAE1C;;;;;OAKG;IACM,QAAQ,CAAqC;IAEtD;;OAEG;IACM,WAAW,CAA2C;IAE/D;;;;OAIG;IACM,OAAO,CAAa;IAE7B,YAAY,UAAsC,EAAE;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC;QAChC,MAAM,UAAU,GACd,QAAQ,CAAC,UAAU;YACnB,OAAO,CAAC,GAAG,CAAC,0BAA0B;YACtC,+BAA+B,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,CACZ,+DAA+D,CAChE,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,qEAAqE;QACrE,6DAA6D;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,UAAU,CAAC;YAC3B,MAAM,EAAE,UAAU;YAClB,KAAK;YACL,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;YAC7C,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1C,SAAS,CAAC,IAAI,CAAC,wCAAwC,UAAU,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAC7B,MAA4D;QAE5D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC3D,OAAO,IAAI,mBAAmB,CAAC;YAC7B,KAAK,EAAE,YAAY;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;SACjE,CAAC,CAAC;IACL,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,QAAQ;QACZ,kEAAkE;QAClE,gDAAgD;QAChD,SAAS,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/index.d.ts

@@ -9,6 +9,8 @@
  * from `@introspection-sdk/introspection-node/otel`.
  */
 export { IntrospectionClient } from "./client.js";
+export { serviceAccountToken, tokenExchange, authorizationCodeToken, } from "./auth.js";
+export type { ServiceAccountTokenParams, ServiceAccountToken, TokenExchangeParams, AuthorizationCodeParams, OAuthToken, } from "./auth.js";
 export type { AdvancedOptions, IntrospectionClientOptions, FeedbackOptions, UserTraits, } from "./types.js";
 export { ConversationItemsApi, ConversationsApi, FileVersionsApi, FilesApi, RunHandle, SharesApi, TaskRunsApi, TasksApi, } from "@introspection-sdk/http";
 export type { FileUploadBody, StartParams } from "@introspection-sdk/http";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,eAAe,EACf,UAAU,GACX,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,SAAS,EACT,SAAS,EACT,WAAW,EACX,QAAQ,GACT,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGnE,YAAY,EACV,SAAS,EACT,UAAU,EACV,IAAI,EACJ,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,UAAU,EACV,UAAU,EACV,OAAO,EACP,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,QAAQ,EACR,OAAO,EACP,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,GAAG,EACH,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,SAAS,EACT,QAAQ,EACR,UAAU,GACX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,EAChC,8BAA8B,EAC9B,qCAAqC,GACtC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,QAAQ,IAAI,cAAc,GAC3B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,oCAAoC,EACpC,uCAAuC,EACvC,uCAAuC,EACvC,mCAAmC,GACpC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,eAAe,EACf,aAAa,EACb,yBAAyB,EACzB,UAAU,EACV,UAAU,GACX,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -10,6 +10,8 @@
  */
 // REST client.
 export { IntrospectionClient } from "./client.js";
+// Machine / federated / hosted-login OAuth token helpers.
+export { serviceAccountToken, tokenExchange, authorizationCodeToken, } from "./auth.js";
 // Runner-bound REST namespaces (runner.tasks, runner.files,
 // runner.conversations) + HTTP/SSE.
 export { ConversationItemsApi, ConversationsApi, FileVersionsApi, FilesApi, RunHandle, SharesApi, TaskRunsApi, TasksApi, } from "@introspection-sdk/http";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAe;AACf,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAUlD,4DAA4D;AAC5D,oCAAoC;AACpC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,SAAS,EACT,SAAS,EACT,WAAW,EACX,QAAQ,GACT,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,yBAAyB;AACzB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAgEnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAiBlC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,kEAAkE;AAClE,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,EAChC,8BAA8B,EAC9B,qCAAqC,GACtC,MAAM,wBAAwB,CAAC;AAShC,2DAA2D;AAC3D,OAAO,EACL,oCAAoC,EACpC,uCAAuC,EACvC,uCAAuC,EACvC,mCAAmC,GACpC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAe;AACf,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,0DAA0D;AAC1D,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAiBnB,4DAA4D;AAC5D,oCAAoC;AACpC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,SAAS,EACT,SAAS,EACT,WAAW,EACX,QAAQ,GACT,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,yBAAyB;AACzB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAgEnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAiBlC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,kEAAkE;AAClE,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,EAChC,8BAA8B,EAC9B,qCAAqC,GACtC,MAAM,wBAAwB,CAAC;AAShC,2DAA2D;AAC3D,OAAO,EACL,oCAAoC,EACpC,uCAAuC,EACvC,uCAAuC,EACvC,mCAAmC,GACpC,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-node",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for Node.js",
   "engines": {
@@ -139,10 +139,10 @@
     "@opentelemetry/api": "^1.9.1",
     "https-proxy-agent": "^7.0.6",
     "proxy-from-env": "^2.1.0",
-    "@introspection-sdk/types": "0.5.5",
-    "@introspection-sdk/http": "0.5.5",
-    "@introspection-sdk/introspection-pi": "0.5.5",
-    "@introspection-sdk/introspection-proxy": "0.5.5"
+    "@introspection-sdk/types": "0.5.7",
+    "@introspection-sdk/http": "0.5.7",
+    "@introspection-sdk/introspection-proxy": "0.5.7",
+    "@introspection-sdk/introspection-pi": "0.5.7"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/auth.ts

@@ -0,0 +1,236 @@
+/**
+ * Service-account (machine) authentication for the Control Plane.
+ *
+ * Mints a short-lived, project-scoped Introspection access token via the
+ * OAuth 2.0 `client_credentials` grant against CP `POST /v1/oauth/token`.
+ * This is the headless / CI counterpart to a long-lived API key: the
+ * confidential Application's `client_id` + `client_secret` stay server-side,
+ * and you re-mint when the token expires (no refresh token is issued).
+ *
+ * The minted `access_token` is an ordinary CP bearer token, so it drops
+ * straight into the existing client surface — pass it to
+ * {@link IntrospectionClient}, or use
+ * {@link IntrospectionClient.fromServiceAccount} to mint and construct in one
+ * call, and the usual `client.runtimes("name").run()` flow works unchanged.
+ */
+import { stripTrailingSlash, toApiError } from "@introspection-sdk/http";
+
+const DEFAULT_BASE_API_URL = "https://api.introspection.dev";
+const GRANT_TYPE_CLIENT_CREDENTIALS = "client_credentials";
+const GRANT_TYPE_TOKEN_EXCHANGE =
+  "urn:ietf:params:oauth:grant-type:token-exchange";
+const GRANT_TYPE_AUTHORIZATION_CODE = "authorization_code";
+const SUBJECT_TOKEN_TYPE_ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token";
+
+function resolveBaseApiUrl(baseApiUrl?: string): string {
+  return stripTrailingSlash(
+    baseApiUrl ??
+      process.env.INTROSPECTION_BASE_API_URL ??
+      DEFAULT_BASE_API_URL,
+  );
+}
+
+function resolveFetch(custom?: typeof fetch): typeof fetch {
+  const fetchImpl = custom ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error(
+      "global fetch is unavailable; pass `fetch` or run on Node 18+",
+    );
+  }
+  return fetchImpl;
+}
+
+async function postTokenForm(
+  baseApiUrl: string,
+  form: URLSearchParams,
+  fetchImpl: typeof fetch,
+): Promise<OAuthToken> {
+  const res = await fetchImpl(`${baseApiUrl}/v1/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: form.toString(),
+    cache: "no-store",
+  });
+  if (!res.ok) throw await toApiError(res);
+  return (await res.json()) as OAuthToken;
+}
+
+/**
+ * CP `POST /v1/oauth/token` response. No refresh token is issued for the
+ * machine grants — re-mint when it expires.
+ */
+export interface OAuthToken {
+  /** Project-scoped RS256 access token (`Authorization: Bearer …`). */
+  access_token: string;
+  /** Always `"Bearer"`. */
+  token_type: string;
+  /** Token lifetime in seconds. */
+  expires_in: number;
+  /** The granted (scope-capped) scope, when the CP returns one. */
+  scope: string | null;
+  /**
+   * Data Plane API base URL for the token's project, resolved by the CP the
+   * same way it is for the CLI login. `null` when the deployment can't be
+   * resolved; the caller then needs an explicit DP URL. Hand this to the
+   * browser SDK as `dpUrl` so the SPA connects without separate DP config.
+   */
+  dp_url: string | null;
+}
+
+export interface ServiceAccountTokenParams {
+  /** Confidential Application client id (`intro_app_…`). */
+  clientId: string;
+  /** Confidential Application client secret (`intro_sk_…`). */
+  clientSecret: string;
+  /**
+   * Project the token is scoped to. Required by the CP `client_credentials`
+   * grant — the minted token is project-scoped and the project must belong to
+   * the Application's organization.
+   */
+  projectId: string;
+  /**
+   * Optional space-separated scope. Capped server-side to the Application's
+   * `allowed_scopes`; omit to receive the Application's default scope.
+   */
+  scope?: string;
+  /**
+   * CP API base URL. Defaults to `INTROSPECTION_BASE_API_URL` or
+   * `https://api.introspection.dev`.
+   */
+  baseApiUrl?: string;
+  /** Custom `fetch` (for tests or non-standard runtimes). */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Back-compat alias: the `client_credentials` response is the same shape as
+ * every other `/v1/oauth/token` response.
+ */
+export type ServiceAccountToken = OAuthToken;
+
+/**
+ * Mint a project-scoped CP access token from confidential service-account
+ * credentials. See {@link ServiceAccountTokenParams}.
+ *
+ * @example
+ * ```typescript
+ * const { access_token, dp_url } = await serviceAccountToken({
+ *   clientId: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_ID!,
+ *   clientSecret: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_SECRET!,
+ *   projectId: process.env.INTRO_PROJECT_ID!,
+ * });
+ * const client = new IntrospectionClient({ token: access_token });
+ * ```
+ */
+export async function serviceAccountToken(
+  params: ServiceAccountTokenParams,
+): Promise<OAuthToken> {
+  const form = new URLSearchParams({
+    grant_type: GRANT_TYPE_CLIENT_CREDENTIALS,
+    client_id: params.clientId,
+    client_secret: params.clientSecret,
+    project_id: params.projectId,
+  });
+  if (params.scope) form.set("scope", params.scope);
+  return postTokenForm(
+    resolveBaseApiUrl(params.baseApiUrl),
+    form,
+    resolveFetch(params.fetch),
+  );
+}
+
+export interface AuthorizationCodeParams {
+  /** The authorization code returned to the redirect URI. */
+  code: string;
+  /** Public SPA Application `client_id` (PKCE — no secret). */
+  clientId: string;
+  /** The redirect URI the code was issued for (must match the authorize call). */
+  redirectUri: string;
+  /** The PKCE `code_verifier` paired with the authorize-step challenge. */
+  codeVerifier: string;
+  /**
+   * CP API base URL. Defaults to `INTROSPECTION_BASE_API_URL` or
+   * `https://api.introspection.dev`.
+   */
+  baseApiUrl?: string;
+  /** Custom `fetch` (for tests or non-standard runtimes). */
+  fetch?: typeof fetch;
+}
+
+/**
+ * RFC 6749 / PKCE `authorization_code` exchange against CP
+ * `POST /v1/oauth/token`. Run it in your backend so the browser hosted-login
+ * flow does not hand-roll the token POST.
+ */
+export async function authorizationCodeToken(
+  params: AuthorizationCodeParams,
+): Promise<OAuthToken> {
+  const form = new URLSearchParams({
+    grant_type: GRANT_TYPE_AUTHORIZATION_CODE,
+    code: params.code,
+    client_id: params.clientId,
+    redirect_uri: params.redirectUri,
+    code_verifier: params.codeVerifier,
+  });
+  return postTokenForm(
+    resolveBaseApiUrl(params.baseApiUrl),
+    form,
+    resolveFetch(params.fetch),
+  );
+}
+
+export interface TokenExchangeParams {
+  /** The end user's subject token (e.g. a partner-IdP `id_token`). */
+  subjectToken: string;
+  /** The federated Application's `client_id` (public client — no secret). */
+  clientId: string;
+  /** Project the minted DP token is scoped to. */
+  projectId: string;
+  /**
+   * The subject token's type URI. Defaults to
+   * `urn:ietf:params:oauth:token-type:id_token`.
+   */
+  subjectTokenType?: string;
+  /** Optional space-separated scope, capped server-side. */
+  scope?: string;
+  /**
+   * CP API base URL. Defaults to `INTROSPECTION_BASE_API_URL` or
+   * `https://api.introspection.dev`.
+   */
+  baseApiUrl?: string;
+  /** Custom `fetch` (for tests or non-standard runtimes). */
+  fetch?: typeof fetch;
+}
+
+/**
+ * RFC 8693 token-exchange against CP `POST /v1/oauth/token`: trade an end
+ * user's partner-IdP token for a project-scoped DP access token for a
+ * `member_type=customer` member. Intended to run server-side in a broker (the
+ * subject token shouldn't be re-handled in the browser longer than needed).
+ *
+ * @example
+ * ```typescript
+ * const { access_token, dp_url } = await tokenExchange({
+ *   subjectToken: idTokenFromPartnerIdp,
+ *   clientId: process.env.FEDERATED_CLIENT_ID!,
+ *   projectId: process.env.INTRO_PROJECT_ID!,
+ * });
+ * ```
+ */
+export async function tokenExchange(
+  params: TokenExchangeParams,
+): Promise<OAuthToken> {
+  const form = new URLSearchParams({
+    grant_type: GRANT_TYPE_TOKEN_EXCHANGE,
+    subject_token: params.subjectToken,
+    subject_token_type: params.subjectTokenType ?? SUBJECT_TOKEN_TYPE_ID_TOKEN,
+    client_id: params.clientId,
+    project_id: params.projectId,
+  });
+  if (params.scope) form.set("scope", params.scope);
+  return postTokenForm(
+    resolveBaseApiUrl(params.baseApiUrl),
+    form,
+    resolveFetch(params.fetch),
+  );
+}

package/src/client.ts

@@ -15,6 +15,7 @@
 import type { AdvancedOptions } from "@introspection-sdk/types";
 import { logger as sdkLogger } from "./utils.js";
 import type { IntrospectionClientOptions } from "./types.js";
+import { serviceAccountToken, type ServiceAccountTokenParams } from "./auth.js";
 import { HttpClient } from "./http.js";
 import {
   attachRuntimes,
@@ -106,6 +107,43 @@ export class IntrospectionClient {
     sdkLogger.info(`IntrospectionClient initialized: api=${baseApiUrl}`);
   }
 
+  /**
+   * Authenticate as a confidential service account and return a ready
+   * client.
+   *
+   * Mints a short-lived, project-scoped CP access token via the
+   * `client_credentials` grant (see {@link serviceAccountToken}) and wires
+   * it in as the bearer token, so the runtime flow works exactly as it does
+   * with an API key:
+   *
+   * @example
+   * ```typescript
+   * const client = await IntrospectionClient.fromServiceAccount({
+   *   clientId: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_ID!,
+   *   clientSecret: process.env.INTROSPECTION_SERVICE_ACCOUNT_CLIENT_SECRET!,
+   *   projectId: process.env.INTRO_PROJECT_ID!,
+   * });
+   *
+   * // Resolved fresh from the runtime name on every call.
+   * const runner = await client.runtimes("customer-agent").run({
+   *   identity: { user_id: "u_demo" },
+   * });
+   * ```
+   *
+   * The token is not auto-refreshed: it lives for `expires_in` seconds, so
+   * re-mint (call this again) for long-lived processes once it lapses.
+   */
+  static async fromServiceAccount(
+    params: ServiceAccountTokenParams & { serviceName?: string },
+  ): Promise<IntrospectionClient> {
+    const { access_token } = await serviceAccountToken(params);
+    return new IntrospectionClient({
+      token: access_token,
+      serviceName: params.serviceName,
+      advanced: { baseApiUrl: params.baseApiUrl, fetch: params.fetch },
+    });
+  }
+
   /** Close the underlying HTTP client. */
   async shutdown(): Promise<void> {
     // HttpClient has no persistent connections to close, but reserved

package/src/index.ts

@@ -12,6 +12,20 @@
 // REST client.
 export { IntrospectionClient } from "./client.js";
 
+// Machine / federated / hosted-login OAuth token helpers.
+export {
+  serviceAccountToken,
+  tokenExchange,
+  authorizationCodeToken,
+} from "./auth.js";
+export type {
+  ServiceAccountTokenParams,
+  ServiceAccountToken,
+  TokenExchangeParams,
+  AuthorizationCodeParams,
+  OAuthToken,
+} from "./auth.js";
+
 // Configuration / event types shared with the OTel surface.
 export type {
   AdvancedOptions,