@2kw/ai 5.2.0-dev.6 → 5.2.0

package/dist/lib/auth-session.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The stateful half of browser login: the RFC 8628 polling loop that waits for
+ * the user to approve a device code, and the cache that keeps the short-lived
+ * organization JWT out of the auth service between rapid commands.
+ *
+ * auth-service.ts owns single requests; this module owns what happens across
+ * several of them, so it is where the retry policy lives. It keeps the three
+ * exits that module documents apart: an {@link AuthServiceError} means the
+ * service answered and said no (replaying it would only repeat the answer),
+ * while a raw fetch `TypeError` means the request never landed (worth retrying).
+ */
+import { fetchJwt, type DeviceTokenResult, type OrgSummary } from "./auth-service.js";
+import { type ResolvedConfig } from "./config.js";
+/**
+ * The user's own answer to a device login: they refused it, or they left it
+ * long enough to lapse.
+ *
+ * Typed rather than a bare Error because the login command has to tell these
+ * two outcomes apart from everything else the polling loop can raise (a refused
+ * client id, a dead network). Those are faults and belong in the shared error
+ * rendering; these are answers, and get a plain line and a non-zero exit.
+ */
+export declare class DeviceApprovalError extends Error {
+    readonly reason: "denied" | "expired";
+    constructor(message: string, reason: "denied" | "expired");
+}
+/**
+ * The stored session is gone — revoked, or expired server-side. Distinct from
+ * AuthServiceError so callers can offer the one fix that works (sign in again)
+ * instead of reporting a bare 401.
+ */
+export declare class SessionExpiredError extends Error {
+    constructor();
+}
+/**
+ * Read a JWT's `exp` claim as epoch millis.
+ *
+ * Only the payload is decoded and nothing is verified — the CLI is not the
+ * audience for this token, it merely needs to know when to stop reusing it.
+ * Anything that is not a three-segment JWT with a numeric `exp` throws, because
+ * a silently-assumed expiry would either hand a dead token to the API or
+ * re-exchange on every single command.
+ */
+export declare function decodeJwtExpMs(jwt: string): number;
+/**
+ * Whether a cached JWT has enough life left to be worth reusing — an unknown
+ * expiry counts as stale, so a cache entry written by an older CLI is simply
+ * re-exchanged rather than trusted.
+ */
+export declare function isJwtFresh(expMs: number | undefined, nowMs: number): boolean;
+/** Inputs to {@link runDevicePolling}; `poll` and `sleep` are injectable for tests. */
+export interface DevicePollingOptions {
+    /** One device-token poll — normally a bound `pollDeviceToken`. */
+    poll: () => Promise<DeviceTokenResult>;
+    /** Seconds between polls, per the device-code response. Defaults to 5. */
+    intervalSec?: number;
+    /** Total seconds the device code stays valid. Defaults to 1800. */
+    expiresInSec?: number;
+    /** Delay implementation; defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll until the user approves the login in their browser, and return the
+ * session token.
+ *
+ * Failure handling follows the auth-service taxonomy. A transport error is
+ * retried (up to {@link MAX_CONSECUTIVE_POLL_ERRORS} in a row, the count reset
+ * by any poll that completes) because a laptop that drops its Wi-Fi mid-login
+ * should not have to start over. An {@link AuthServiceError} is not retried —
+ * the service answered, and asking again gets the same answer.
+ *
+ * The deadline is spent from the poll budget rather than read off the wall
+ * clock, so an injected sleep makes the whole loop deterministic.
+ *
+ * @throws {DeviceApprovalError} when the user denies the login, or the code
+ *   expires — either because the service said so or because the budget ran out.
+ * @throws {AuthServiceError} when the service refused the exchange outright.
+ * @throws {TypeError} the last transport error, once retrying is pointless.
+ */
+export declare function runDevicePolling(opts: DevicePollingOptions): Promise<string>;
+/** Asks one question and resolves with what the user typed. */
+export type Asker = (question: string) => Promise<string>;
+/** Injection points for {@link selectOrganization}; both default to the real thing. */
+export interface SelectOrgDeps {
+    /** Question function — tests (and any non-readline caller) supply their own;
+     *  the default reads a line from stdin. */
+    ask?: Asker;
+    /** Whether stdin can be prompted; defaults to `process.stdin.isTTY`. */
+    isTTY?: boolean;
+}
+/**
+ * Decide which organization the new session should act as.
+ *
+ * A single membership needs no ceremony, so it is chosen silently; several
+ * memberships get a numbered prompt that repeats until the answer names one of
+ * them. Lives here rather than in the login command because org switching
+ * reuses the identical choice.
+ *
+ * Two guards keep the prompt from becoming a hang. Without a terminal there is
+ * nobody to answer, and readline on a closed or piped stdin resolves nothing
+ * and never ends — so that case is refused up front, with the fix in the
+ * message. The attempt cap covers what the first guard cannot see: an input
+ * that does answer, always invalidly (a pipe that yields "" forever).
+ *
+ * @throws {Error} when the account has no organizations at all, when there is
+ *   no terminal to prompt, or when the attempts run out.
+ */
+export declare function selectOrganization(orgs: OrgSummary[], deps?: SelectOrgDeps): Promise<OrgSummary>;
+/** Injection points for {@link ensureJwt}; all default to the real thing. */
+export interface EnsureJwtDeps {
+    /** Session-to-JWT exchange; defaults to {@link fetchJwt}. */
+    fetchJwtFn?: typeof fetchJwt;
+    /** Cache writer; defaults to {@link updateContext}. */
+    persist?: (contextName: string, patch: {
+        cachedJwt: string;
+        cachedJwtExp: number;
+    }) => void;
+    /** Clock; defaults to `Date.now`. */
+    now?: () => number;
+    /** Skip the cache and always exchange — e.g. right after switching org. */
+    force?: boolean;
+}
+type SessionConfig = Extract<ResolvedConfig, {
+    kind: "session";
+}>;
+/**
+ * Return an organization JWT for a session context, exchanging the session for
+ * a new one whenever the cached token is missing, stale, or explicitly bypassed.
+ *
+ * A fresh token is written both to the config store and back onto `cfg`: a
+ * single command may reach here more than once (a retry after a 401, say), and
+ * the in-memory copy is what those later reads see. Caching is best-effort — a
+ * token that cannot be cached is still a token that works.
+ *
+ * @throws {SessionExpiredError} when the stored session is no longer valid.
+ */
+export declare function ensureJwt(cfg: SessionConfig, deps?: EnsureJwtDeps): Promise<string>;
+export {};
+//# sourceMappingURL=auth-session.d.ts.map

package/dist/lib/auth-session.js

@@ -0,0 +1,275 @@
+/**
+ * The stateful half of browser login: the RFC 8628 polling loop that waits for
+ * the user to approve a device code, and the cache that keeps the short-lived
+ * organization JWT out of the auth service between rapid commands.
+ *
+ * auth-service.ts owns single requests; this module owns what happens across
+ * several of them, so it is where the retry policy lives. It keeps the three
+ * exits that module documents apart: an {@link AuthServiceError} means the
+ * service answered and said no (replaying it would only repeat the answer),
+ * while a raw fetch `TypeError` means the request never landed (worth retrying).
+ */
+import { Buffer } from "node:buffer";
+import { createInterface } from "node:readline/promises";
+import chalk from "chalk";
+import { AuthServiceError, fetchJwt, } from "./auth-service.js";
+import { updateContext } from "./config.js";
+/**
+ * How much life a cached JWT must have left to be reused. Also absorbs modest
+ * client-clock skew: a token minted against a server clock a few seconds ahead
+ * of ours must not be handed to the API a moment before it becomes valid.
+ */
+const JWT_FRESHNESS_MARGIN_MS = 30_000;
+/** Consecutive-transport-failure count at which the loop gives up: two are
+ *  ridden out, the third is rethrown. */
+const MAX_CONSECUTIVE_POLL_ERRORS = 3;
+/** RFC 8628 §3.2 recommends 5 s when the service states no interval. */
+const DEFAULT_POLL_INTERVAL_SEC = 5;
+/** Ceiling on the whole login wait when the service states no expiry. */
+const DEFAULT_POLL_EXPIRES_SEC = 1800;
+/** RFC 8628 §3.5: each slow_down widens the polling interval by 5 s. */
+const SLOW_DOWN_BACKOFF_MS = 5_000;
+const DENIED_MESSAGE = "Login was denied in the browser.";
+const EXPIRED_MESSAGE = 'Login attempt expired — run "2kw auth login" again.';
+/** Nothing to select from, and nothing the CLI can do about it — orgs are
+ *  created in the web app. */
+const NO_ORG_MESSAGE = "Your account belongs to no organization yet — create one in the web app first.";
+/**
+ * The user's own answer to a device login: they refused it, or they left it
+ * long enough to lapse.
+ *
+ * Typed rather than a bare Error because the login command has to tell these
+ * two outcomes apart from everything else the polling loop can raise (a refused
+ * client id, a dead network). Those are faults and belong in the shared error
+ * rendering; these are answers, and get a plain line and a non-zero exit.
+ */
+export class DeviceApprovalError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "DeviceApprovalError";
+    }
+}
+/**
+ * The stored session is gone — revoked, or expired server-side. Distinct from
+ * AuthServiceError so callers can offer the one fix that works (sign in again)
+ * instead of reporting a bare 401.
+ */
+export class SessionExpiredError extends Error {
+    constructor() {
+        super('Session expired or revoked — run "2kw auth login" to sign in again.');
+        this.name = "SessionExpiredError";
+    }
+}
+/** Wait `ms`, used when the caller injects no sleep of its own. */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Read a JWT's `exp` claim as epoch millis.
+ *
+ * Only the payload is decoded and nothing is verified — the CLI is not the
+ * audience for this token, it merely needs to know when to stop reusing it.
+ * Anything that is not a three-segment JWT with a numeric `exp` throws, because
+ * a silently-assumed expiry would either hand a dead token to the API or
+ * re-exchange on every single command.
+ */
+export function decodeJwtExpMs(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) {
+        throw new Error("Malformed token: expected three dot-separated JWT segments.");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+    }
+    catch {
+        throw new Error("Malformed token: the JWT payload is not valid JSON.");
+    }
+    const exp = payload !== null && typeof payload === "object"
+        ? payload.exp
+        : undefined;
+    if (typeof exp !== "number" || !Number.isFinite(exp)) {
+        throw new Error("Malformed token: the JWT payload carries no numeric exp claim.");
+    }
+    return exp * 1000;
+}
+/**
+ * Whether a cached JWT has enough life left to be worth reusing — an unknown
+ * expiry counts as stale, so a cache entry written by an older CLI is simply
+ * re-exchanged rather than trusted.
+ */
+export function isJwtFresh(expMs, nowMs) {
+    return expMs !== undefined && expMs - nowMs > JWT_FRESHNESS_MARGIN_MS;
+}
+/**
+ * Poll until the user approves the login in their browser, and return the
+ * session token.
+ *
+ * Failure handling follows the auth-service taxonomy. A transport error is
+ * retried (up to {@link MAX_CONSECUTIVE_POLL_ERRORS} in a row, the count reset
+ * by any poll that completes) because a laptop that drops its Wi-Fi mid-login
+ * should not have to start over. An {@link AuthServiceError} is not retried —
+ * the service answered, and asking again gets the same answer.
+ *
+ * The deadline is spent from the poll budget rather than read off the wall
+ * clock, so an injected sleep makes the whole loop deterministic.
+ *
+ * @throws {DeviceApprovalError} when the user denies the login, or the code
+ *   expires — either because the service said so or because the budget ran out.
+ * @throws {AuthServiceError} when the service refused the exchange outright.
+ * @throws {TypeError} the last transport error, once retrying is pointless.
+ */
+export async function runDevicePolling(opts) {
+    const { poll, sleep = defaultSleep } = opts;
+    // A zero or negative interval would spin the loop without ever spending the
+    // budget, so treat anything non-positive as "not stated".
+    const intervalSec = opts.intervalSec !== undefined && opts.intervalSec > 0
+        ? opts.intervalSec
+        : DEFAULT_POLL_INTERVAL_SEC;
+    let intervalMs = intervalSec * 1000;
+    let remainingMs = (opts.expiresInSec ?? DEFAULT_POLL_EXPIRES_SEC) * 1000;
+    let consecutiveErrors = 0;
+    for (;;) {
+        let result;
+        try {
+            result = await poll();
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            // Exit #2: the service answered. Retrying just replays the refusal.
+            if (err instanceof AuthServiceError)
+                throw err;
+            // Exit #3: the request never completed. Retry-worthy, within reason.
+            consecutiveErrors += 1;
+            if (consecutiveErrors >= MAX_CONSECUTIVE_POLL_ERRORS)
+                throw err;
+        }
+        switch (result?.status) {
+            case "ok":
+                return result.accessToken;
+            case "denied":
+                throw new DeviceApprovalError(DENIED_MESSAGE, "denied");
+            case "expired":
+                throw new DeviceApprovalError(EXPIRED_MESSAGE, "expired");
+            case "slow_down":
+                intervalMs += SLOW_DOWN_BACKOFF_MS;
+                break;
+            default:
+                // "pending", or a tolerated transport error: wait and ask again.
+                break;
+        }
+        remainingMs -= intervalMs;
+        if (remainingMs <= 0)
+            throw new DeviceApprovalError(EXPIRED_MESSAGE, "expired");
+        await sleep(intervalMs);
+    }
+}
+/** Attempts allowed at the prompt before the loop is called a lost cause. */
+const MAX_ORG_PROMPT_ATTEMPTS = 5;
+const NO_TTY_MESSAGE = "Cannot prompt for an organization: no interactive terminal. " +
+    "Pass an org explicitly or run in a terminal.";
+const TOO_MANY_ATTEMPTS_MESSAGE = `No organization chosen after ${MAX_ORG_PROMPT_ATTEMPTS} attempts.`;
+/**
+ * Decide which organization the new session should act as.
+ *
+ * A single membership needs no ceremony, so it is chosen silently; several
+ * memberships get a numbered prompt that repeats until the answer names one of
+ * them. Lives here rather than in the login command because org switching
+ * reuses the identical choice.
+ *
+ * Two guards keep the prompt from becoming a hang. Without a terminal there is
+ * nobody to answer, and readline on a closed or piped stdin resolves nothing
+ * and never ends — so that case is refused up front, with the fix in the
+ * message. The attempt cap covers what the first guard cannot see: an input
+ * that does answer, always invalidly (a pipe that yields "" forever).
+ *
+ * @throws {Error} when the account has no organizations at all, when there is
+ *   no terminal to prompt, or when the attempts run out.
+ */
+export async function selectOrganization(orgs, deps = {}) {
+    const { ask, isTTY = Boolean(process.stdin.isTTY) } = deps;
+    if (orgs.length === 0)
+        throw new Error(NO_ORG_MESSAGE);
+    if (orgs.length === 1)
+        return orgs[0];
+    // Checked before anything is printed: an injected asker owns its own input,
+    // but the default one is about to open readline on a stdin nobody will type
+    // into.
+    if (!ask && !isTTY)
+        throw new Error(NO_TTY_MESSAGE);
+    console.log("");
+    console.log("Select an organization:");
+    orgs.forEach((org, i) => {
+        console.log(`  ${i + 1}) ${org.name}`);
+    });
+    // Only open a real readline when we have to: an injected asker means the
+    // caller owns the input, and an unused interface would hold stdin open.
+    const rl = ask ? undefined : createInterface({ input: process.stdin, output: process.stdout });
+    const askFn = ask ?? ((question) => rl.question(question));
+    try {
+        for (let attempt = 0; attempt < MAX_ORG_PROMPT_ATTEMPTS; attempt++) {
+            const answer = (await askFn(`Organization [1-${orgs.length}]: `)).trim();
+            // Digits only — parseInt would happily read "2 or so" as 2.
+            if (/^\d+$/.test(answer)) {
+                const choice = Number(answer);
+                if (choice >= 1 && choice <= orgs.length)
+                    return orgs[choice - 1];
+            }
+            console.log(chalk.yellow(`Enter a number between 1 and ${orgs.length}.`));
+        }
+        throw new Error(TOO_MANY_ATTEMPTS_MESSAGE);
+    }
+    finally {
+        rl?.close();
+    }
+}
+/**
+ * Return an organization JWT for a session context, exchanging the session for
+ * a new one whenever the cached token is missing, stale, or explicitly bypassed.
+ *
+ * A fresh token is written both to the config store and back onto `cfg`: a
+ * single command may reach here more than once (a retry after a 401, say), and
+ * the in-memory copy is what those later reads see. Caching is best-effort — a
+ * token that cannot be cached is still a token that works.
+ *
+ * @throws {SessionExpiredError} when the stored session is no longer valid.
+ */
+export async function ensureJwt(cfg, deps = {}) {
+    const { fetchJwtFn = fetchJwt, persist = updateContext, now = Date.now, force = false } = deps;
+    if (!force && cfg.cachedJwt && isJwtFresh(cfg.cachedJwtExp, now())) {
+        return cfg.cachedJwt;
+    }
+    let jwt;
+    try {
+        jwt = await fetchJwtFn(cfg.authUrl, cfg.sessionToken);
+    }
+    catch (err) {
+        // Only a 401 means "this session is done". Every other failure — a 502, a
+        // dead network — says nothing about the session, so it must not tell the
+        // user to sign in again.
+        if (err instanceof AuthServiceError && err.status === 401) {
+            // The stale cache is dropped where this lands rather than here:
+            // handleError in errors.ts clears cachedJwt/cachedJwtExp for the active
+            // context, so every command path gets it, including the raw-fetch ones.
+            throw new SessionExpiredError();
+        }
+        throw err;
+    }
+    try {
+        const expMs = decodeJwtExpMs(jwt);
+        cfg.cachedJwtExp = expMs;
+        cfg.cachedJwt = jwt;
+        persist(cfg.contextName, { cachedJwt: jwt, cachedJwtExp: expMs });
+    }
+    catch {
+        // An unparseable token or a read-only config store must not fail a command
+        // that holds a working credential — skip the cache and use it this once.
+        // Cleared as a pair so a half-written entry can never be read back as fresh.
+        cfg.cachedJwt = undefined;
+        cfg.cachedJwtExp = undefined;
+    }
+    return jwt;
+}
+//# sourceMappingURL=auth-session.js.map

package/dist/lib/client.d.ts

@@ -1,12 +1,69 @@
+import { type Middleware } from "openapi-fetch";
 import type { paths } from "../generated/openapi.js";
+import { type ResolvedConfig } from "./config.js";
+import { ensureJwt } from "./auth-session.js";
 import type { Command } from "commander";
+/**
+ * Marks a request that has already been replayed once after a 401, so a
+ * server that keeps rejecting a freshly minted JWT cannot spin the retry.
+ */
+export declare const RETRY_MARKER = "x-2kw-auth-retried";
+type SessionConfig = Extract<ResolvedConfig, {
+    kind: "session";
+}>;
+type ApiKeyConfig = Extract<ResolvedConfig, {
+    kind: "apiKey";
+}>;
+/** Test seams for the session middleware; both default to the real thing. */
+export interface SessionAuthDeps {
+    /** Session-to-JWT resolution; defaults to {@link ensureJwt}. */
+    ensureJwtFn?: typeof ensureJwt;
+    /** Used only for the 401 replay; defaults to global `fetch`. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ */
+export declare const errorMiddleware: Middleware;
+/**
+ * API-key contexts carry a long-lived credential, so the header is static and
+ * a 401 is final — there is nothing to refresh.
+ */
+export declare function apiKeyAuthMiddleware(config: ApiKeyConfig): Middleware;
+/**
+ * Session contexts authenticate with a short-lived org JWT minted from the
+ * stored session token. On a 401 we force one re-mint and retry — but only
+ * for GET requests: mutation bodies are consumed by the time onResponse
+ * fires and cannot be replayed safely.
+ */
+export declare function sessionAuthMiddleware(config: SessionConfig, deps?: SessionAuthDeps): Middleware;
+/**
+ * The middleware stack for a resolved config, in registration order.
+ *
+ * Order is load-bearing: openapi-fetch runs `onRequest` forwards but
+ * `onResponse` in reverse, so the error middleware is registered FIRST to make
+ * its throw happen LAST. Registered last it would raise on a 401 before the
+ * auth middleware ever saw the response, and the retry would be dead code.
+ */
+export declare function buildMiddleware(config: ResolvedConfig, deps?: SessionAuthDeps): Middleware[];
+/**
+ * Resolve the Authorization header value for code that performs raw fetch
+ * calls outside the openapi-fetch client (multipart uploads, downloads).
+ * API-key contexts are synchronous passthrough; session contexts mint/reuse
+ * a JWT. No 401 retry here — raw-fetch callers surface errors directly.
+ */
+export declare function resolveAuthHeader(config: ResolvedConfig, deps?: Pick<SessionAuthDeps, "ensureJwtFn">): Promise<string>;
 /**
  * Create a typed openapi-fetch client from the resolved config.
  * Attaches Bearer auth and error middleware automatically.
+ *
+ * Stays synchronous — a JWT is minted lazily inside the request middleware, so
+ * none of the ~90 call sites has to await client construction.
  */
 export declare function getClient(command: Command): import("openapi-fetch").Client<paths, `${string}/${string}`>;
 /**
  * Convenience: run an async action with consistent error handling.
  */
 export declare function runAction(command: Command, action: () => Promise<void>): Promise<void>;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.js

@@ -1,10 +1,16 @@
 import createClient from "openapi-fetch";
 import { resolveConfig, isJsonOutput } from "./config.js";
+import { ensureJwt } from "./auth-session.js";
 import { BackboneApiError, handleError } from "./errors.js";
+/**
+ * Marks a request that has already been replayed once after a 401, so a
+ * server that keeps rejecting a freshly minted JWT cannot spin the retry.
+ */
+export const RETRY_MARKER = "x-2kw-auth-retried";
 /**
  * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
  */
-const errorMiddleware = {
+export const errorMiddleware = {
     async onResponse({ response }) {
         if (response.ok)
             return undefined;
@@ -23,19 +29,89 @@ const errorMiddleware = {
         });
     },
 };
+/**
+ * API-key contexts carry a long-lived credential, so the header is static and
+ * a 401 is final — there is nothing to refresh.
+ */
+export function apiKeyAuthMiddleware(config) {
+    return {
+        onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${config.apiKey}`);
+            return request;
+        },
+    };
+}
+/**
+ * Session contexts authenticate with a short-lived org JWT minted from the
+ * stored session token. On a 401 we force one re-mint and retry — but only
+ * for GET requests: mutation bodies are consumed by the time onResponse
+ * fires and cannot be replayed safely.
+ */
+export function sessionAuthMiddleware(config, deps = {}) {
+    const doEnsure = deps.ensureJwtFn ?? ensureJwt;
+    const doFetch = deps.fetchFn ?? fetch;
+    return {
+        async onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${await doEnsure(config)}`);
+            return request;
+        },
+        async onResponse({ request, response }) {
+            if (response.status !== 401 ||
+                request.method !== "GET" ||
+                request.headers.has(RETRY_MARKER)) {
+                return undefined;
+            }
+            const jwt = await doEnsure(config, { force: true });
+            const retry = new Request(request.url, {
+                method: "GET",
+                headers: new Headers(request.headers),
+            });
+            retry.headers.set("Authorization", `Bearer ${jwt}`);
+            retry.headers.set(RETRY_MARKER, "1");
+            return doFetch(retry);
+        },
+    };
+}
+/**
+ * The middleware stack for a resolved config, in registration order.
+ *
+ * Order is load-bearing: openapi-fetch runs `onRequest` forwards but
+ * `onResponse` in reverse, so the error middleware is registered FIRST to make
+ * its throw happen LAST. Registered last it would raise on a 401 before the
+ * auth middleware ever saw the response, and the retry would be dead code.
+ */
+export function buildMiddleware(config, deps = {}) {
+    return [
+        errorMiddleware, // MUST stay first — see docblock
+        config.kind === "apiKey"
+            ? apiKeyAuthMiddleware(config)
+            : sessionAuthMiddleware(config, deps),
+    ];
+}
+/**
+ * Resolve the Authorization header value for code that performs raw fetch
+ * calls outside the openapi-fetch client (multipart uploads, downloads).
+ * API-key contexts are synchronous passthrough; session contexts mint/reuse
+ * a JWT. No 401 retry here — raw-fetch callers surface errors directly.
+ */
+export async function resolveAuthHeader(config, deps = {}) {
+    if (config.kind === "apiKey")
+        return `Bearer ${config.apiKey}`;
+    return `Bearer ${await (deps.ensureJwtFn ?? ensureJwt)(config)}`;
+}
 /**
  * Create a typed openapi-fetch client from the resolved config.
  * Attaches Bearer auth and error middleware automatically.
+ *
+ * Stays synchronous — a JWT is minted lazily inside the request middleware, so
+ * none of the ~90 call sites has to await client construction.
  */
 export function getClient(command) {
     const config = resolveConfig(command);
     const client = createClient({
         baseUrl: config.baseUrl.replace(/\/+$/, ""),
-        headers: {
-            Authorization: `Bearer ${config.apiKey}`,
-        },
     });
-    client.use(errorMiddleware);
+    client.use(...buildMiddleware(config));
     return client;
 }
 /**