@stigmer/cli 3.0.8

package/resources/version.js

@@ -0,0 +1,75 @@
+// Workflow version history (`get <workflow> --version-history`) and single
+// version retrieval (`get <workflow> --version <hashOrTag>`). Versioning is a
+// workflow-only feature: applies create immutable, hash-addressed versions that
+// can be tagged and diffed. Mirrors Go's workflow.RunVersionsList /
+// RunVersionsGet, including the table layout and the empty-history guidance.
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { GetWorkflowVersionInputSchema, ListWorkflowVersionsInputSchema, } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import { CliExitError, ExitCode } from "../errors/index.js";
+// Go caps the history view at 50 entries (workflow.getWorkflow → RunVersionsList).
+const VERSION_HISTORY_PAGE_SIZE = 50;
+/** Render the workflow's version history table, or empty-history guidance. */
+export async function renderWorkflowVersionHistory(client, org, slug) {
+    const response = await client.workflow.listVersions(create(ListWorkflowVersionsInputSchema, { org, slug, pageSize: VERSION_HISTORY_PAGE_SIZE }));
+    if (response.versions.length === 0) {
+        return [
+            "",
+            `No version history found for ${org}/${slug}`,
+            "Tip: Apply a workflow to create the first version:",
+            "  stigmer apply -f workflow.yaml",
+            "",
+        ].join("\n");
+    }
+    return renderVersionsTable(response.versions, response.totalCount);
+}
+/** Fetch the validated YAML for a specific version (by hash or tag). */
+export async function getWorkflowVersionYaml(client, org, slug, hashOrTag) {
+    const workflow = await client.workflow.getByReference({ org, slug });
+    const workflowId = workflow.metadata?.id ?? "";
+    const entry = await client.workflow.getVersion(create(GetWorkflowVersionInputSchema, { workflowId, versionHash: hashOrTag }));
+    if (entry.validatedYaml === "") {
+        throw new CliExitError(`version ${truncateHash(hashOrTag)} has no validated YAML`, ExitCode.General);
+    }
+    // Go uses fmt.Print (no added newline) — the YAML carries its own.
+    return entry.validatedYaml;
+}
+// --- Rendering (mirrors Go's displayVersionsTable) ---
+function renderVersionsTable(entries, totalCount) {
+    const lines = [
+        "",
+        `Version History (${totalCount} total)`,
+        "",
+        `  ${pad("HASH", 14)} ${pad("TAG", 10)} ${pad("APPLIED AT", 20)} ${pad("CURRENT", 8)} MESSAGE`,
+        `  ${"─".repeat(14)} ${"─".repeat(10)} ${"─".repeat(20)} ${"─".repeat(8)} ───────`,
+    ];
+    for (const entry of entries) {
+        const hash = truncateHash(entry.versionHash);
+        const tag = entry.tag === "" ? "-" : entry.tag;
+        const appliedAt = entry.appliedAt === undefined ? "-" : formatAppliedAt(entry.appliedAt);
+        const current = entry.isCurrent ? "*" : "";
+        const message = truncateMessage(entry.message);
+        lines.push(`  ${pad(hash, 14)} ${pad(tag, 10)} ${pad(appliedAt, 20)} ${pad(current, 8)} ${message}`);
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+function truncateHash(hash) {
+    return hash.length > 12 ? hash.slice(0, 12) : hash;
+}
+function truncateMessage(message) {
+    if (message === "")
+        return "-";
+    return message.length > 40 ? `${message.slice(0, 37)}...` : message;
+}
+// Matches Go's "2006-01-02 15:04" local-time layout.
+function formatAppliedAt(timestamp) {
+    const date = timestampDate(timestamp);
+    const pad2 = (n) => String(n).padStart(2, "0");
+    return (`${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ` +
+        `${pad2(date.getHours())}:${pad2(date.getMinutes())}`);
+}
+function pad(value, width) {
+    return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+//# sourceMappingURL=version.js.map

package/resources/version.js.map

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

package/runtime.d.ts

@@ -0,0 +1,5 @@
+export declare function setDebug(value: boolean): void;
+export declare function isDebug(): boolean;
+export declare function setStandalone(value: boolean): void;
+export declare function isStandalone(): boolean;
+//# sourceMappingURL=runtime.d.ts.map

package/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAQA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE7C;AAED,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/runtime.js

@@ -0,0 +1,19 @@
+// Process-global CLI flags that cross-cutting modules (config, errors, logger)
+// read without threading them through every call. Set once by the root
+// preAction hook from the parsed global options. Mirrors the Go CLI's atomic
+// `standalone`/`debug` globals in internal/cli/config and clierr.
+let debug = false;
+let standalone = false;
+export function setDebug(value) {
+    debug = value;
+}
+export function isDebug() {
+    return debug;
+}
+export function setStandalone(value) {
+    standalone = value;
+}
+export function isStandalone() {
+    return standalone;
+}
+//# sourceMappingURL=runtime.js.map

package/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uEAAuE;AACvE,6EAA6E;AAC7E,kEAAkE;AAElE,IAAI,KAAK,GAAG,KAAK,CAAC;AAClB,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,KAAK,GAAG,KAAK,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,UAAU,GAAG,KAAK,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/src/auth/auth0.ts

@@ -0,0 +1,43 @@
+// Auth0 PKCE configuration for Stigmer Cloud.
+//
+// These values are public metadata for a Native/PKCE application — they are NOT
+// secrets. An Auth0 client ID is a public identifier (like a username, not a
+// password), and PKCE removes the need for a client secret entirely. The
+// authorize/token endpoints are hardcoded because Auth0's URL structure is
+// stable ({domain}/authorize, {domain}/oauth/token), saving an OIDC-discovery
+// round-trip at login time. Kept byte-for-byte identical to the Go CLI.
+
+export const AUTH0_DOMAIN = "https://stigmer-prod.us.auth0.com";
+export const CLIENT_ID = "kIT6URf4HKn6YzrQVVFTFN63BrSJdTPM";
+export const AUDIENCE = "https://api.stigmer.com/";
+export const CALLBACK_PORT = 8088;
+export const CALLBACK_PATH = "/auth/callback";
+
+const SCOPES = ["openid", "profile", "email", "offline_access"] as const;
+
+export const AUTHORIZE_URL = `${AUTH0_DOMAIN}/authorize`;
+export const TOKEN_URL = `${AUTH0_DOMAIN}/oauth/token`;
+
+/** The loopback redirect URI Auth0 calls back with the authorization code. */
+export function callbackUrl(): string {
+  return `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
+}
+
+/**
+ * Build the Auth0 /authorize URL for the PKCE authorization-code flow.
+ * `prompt=login` forces the login page even with an active session, enabling
+ * account switching.
+ */
+export function buildAuthorizeUrl(params: { state: string; codeChallenge: string }): string {
+  const url = new URL(AUTHORIZE_URL);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("redirect_uri", callbackUrl());
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("audience", AUDIENCE);
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("code_challenge", params.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("prompt", "login");
+  return url.toString();
+}

package/src/auth/callback-server.ts

@@ -0,0 +1,104 @@
+// A short-lived loopback HTTP server that receives Auth0's redirect carrying
+// the authorization code. Lifecycle: new -> start -> waitForCallback -> shutdown.
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { CliExitError, ExitCode } from "../errors/index.js";
+import { HOLDING_PAGE, renderErrorPage, SUCCESS_PAGE } from "./pages.js";
+
+export interface CallbackResult {
+  readonly code: string;
+  readonly state: string;
+}
+
+type Settler = {
+  resolve(result: CallbackResult): void;
+  reject(error: Error): void;
+};
+
+export class CallbackServer {
+  private server?: Server;
+  private settler?: Settler;
+
+  constructor(
+    private readonly port: number,
+    private readonly path: string,
+  ) {}
+
+  /** Bind and listen on 127.0.0.1, reporting a clear error if the port is taken. */
+  start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => this.handle(req, res));
+      server.once("error", (err) => {
+        reject(
+          new CliExitError(
+            `failed to start the login callback server on port ${this.port} (is it already in use?): ${err.message}`,
+            ExitCode.General,
+          ),
+        );
+      });
+      server.listen(this.port, "127.0.0.1", () => {
+        this.server = server;
+        resolve();
+      });
+    });
+  }
+
+  /** Resolve when the OAuth callback arrives; reject on error or timeout. */
+  waitForCallback(timeoutMs: number): Promise<CallbackResult> {
+    return new Promise<CallbackResult>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new CliExitError("timed out waiting for authentication — please try again", ExitCode.General));
+      }, timeoutMs);
+      this.settler = {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolve(result);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      };
+    });
+  }
+
+  async shutdown(): Promise<void> {
+    const server = this.server;
+    if (server === undefined) return;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+
+  private handle(req: IncomingMessage, res: ServerResponse): void {
+    const url = new URL(req.url ?? "/", `http://localhost:${this.port}`);
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+
+    if (url.pathname !== this.path) {
+      res.end(HOLDING_PAGE);
+      return;
+    }
+
+    const errorCode = url.searchParams.get("error");
+    if (errorCode !== null) {
+      const description = url.searchParams.get("error_description") ?? "";
+      const message =
+        errorCode === "access_denied" ? "You cancelled the login process." : "Authentication was cancelled or denied.";
+      res.end(renderErrorPage(message, errorCode, description));
+      this.settler?.reject(
+        new CliExitError(`authentication failed: ${errorCode}${description ? ` — ${description}` : ""}`, ExitCode.Auth),
+      );
+      return;
+    }
+
+    const code = url.searchParams.get("code");
+    if (code === null || code === "") {
+      res.end(
+        renderErrorPage("No authorization code received.", "missing_code", "The callback did not contain a code."),
+      );
+      this.settler?.reject(new CliExitError("callback did not contain an authorization code", ExitCode.Auth));
+      return;
+    }
+
+    res.end(SUCCESS_PAGE);
+    this.settler?.resolve({ code, state: url.searchParams.get("state") ?? "" });
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,6 @@
+// Public surface of the auth module.
+
+export { AUDIENCE, AUTH0_DOMAIN, buildAuthorizeUrl, callbackUrl, CLIENT_ID } from "./auth0.js";
+export { login } from "./login.js";
+export { challengeS256, generateState, generateVerifier } from "./pkce.js";
+export { createRefreshingTokenProvider, exchangeCode, refreshAccessToken, type TokenSet } from "./token.js";

package/src/auth/login.ts

@@ -0,0 +1,61 @@
+// Browser-based PKCE OAuth login orchestration.
+//
+// Flow:
+//   1. Start a loopback server to receive the Auth0 callback.
+//   2. Open the browser to /authorize with a PKCE code_challenge.
+//   3. Wait for the redirect carrying the authorization code (5-min timeout).
+//   4. Validate the state parameter (CSRF), then exchange code -> tokens.
+//   5. Persist tokens and switch the backend to cloud mode.
+//
+// Progress goes to stderr; the command layer renders the final result.
+
+import open from "open";
+import { load, save } from "../config/index.js";
+import { CliExitError, ExitCode } from "../errors/index.js";
+import { log } from "../logger.js";
+import { buildAuthorizeUrl, CALLBACK_PATH, CALLBACK_PORT } from "./auth0.js";
+import { CallbackServer } from "./callback-server.js";
+import { challengeS256, generateState, generateVerifier } from "./pkce.js";
+import { exchangeCode } from "./token.js";
+
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+export async function login(): Promise<void> {
+  const verifier = generateVerifier();
+  const codeChallenge = challengeS256(verifier);
+  const state = generateState();
+
+  const server = new CallbackServer(CALLBACK_PORT, CALLBACK_PATH);
+  await server.start();
+  try {
+    const authUrl = buildAuthorizeUrl({ state, codeChallenge });
+    process.stderr.write("Opening browser for authentication...\n");
+    process.stderr.write(`If the browser doesn't open automatically, visit:\n${authUrl}\n\n`);
+
+    try {
+      await open(authUrl);
+    } catch (err) {
+      log.debug(`failed to open browser automatically: ${(err as Error).message}`);
+      process.stderr.write("Could not open the browser automatically. Please open the URL above.\n");
+    }
+
+    const callback = await server.waitForCallback(LOGIN_TIMEOUT_MS);
+    if (callback.state !== state) {
+      throw new CliExitError("OAuth state mismatch — possible CSRF attack, aborting login", ExitCode.Auth);
+    }
+
+    const tokens = await exchangeCode({ code: callback.code, codeVerifier: verifier });
+
+    const config = load();
+    config.backend.type = "cloud";
+    config.backend.cloud = {
+      ...config.backend.cloud,
+      token: tokens.accessToken,
+      refresh_token: tokens.refreshToken,
+      token_expiry: tokens.expiresAt,
+    };
+    save(config);
+  } finally {
+    await server.shutdown();
+  }
+}

package/src/auth/pages.ts

@@ -0,0 +1,31 @@
+// Minimal HTML pages served by the loopback callback server. Self-contained
+// (no external assets) so they render instantly and offline.
+
+function page(title: string, body: string): string {
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${title}</title></head><body style="font-family:system-ui,sans-serif;text-align:center;padding:60px;color:#1a1a2e">${body}</body></html>`;
+}
+
+/** Shown briefly while the user authenticates (only seen on direct navigation). */
+export const HOLDING_PAGE = page("Stigmer CLI", "<h2>Stigmer CLI</h2><p>Waiting for authentication…</p>");
+
+/** Shown after a successful login; the user can close the tab and return to the CLI. */
+export const SUCCESS_PAGE = page(
+  "Stigmer CLI — Success",
+  "<h2>✓ Authentication successful</h2><p>You can close this tab and return to your terminal.</p>",
+);
+
+/** Shown when Auth0 redirects with an error or no code. */
+export function renderErrorPage(message: string, code: string, description: string): string {
+  return page(
+    "Stigmer CLI — Error",
+    `<h2>✗ Authentication failed</h2><p>${escapeHtml(message)}</p><p style="color:#888;font-size:0.9em">${escapeHtml(code)}${description ? `: ${escapeHtml(description)}` : ""}</p>`,
+  );
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/auth/pkce.test.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { buildAuthorizeUrl } from "./auth0.js";
+import { challengeS256, generateState, generateVerifier } from "./pkce.js";
+
+describe("PKCE helpers", () => {
+  it("generates a base64url verifier with no padding", () => {
+    const verifier = generateVerifier();
+    expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(verifier).not.toContain("=");
+    expect(verifier.length).toBeGreaterThanOrEqual(43);
+  });
+
+  it("derives the S256 challenge as base64url(sha256(verifier))", () => {
+    const verifier = "fixed-verifier-value";
+    const expected = createHash("sha256").update(verifier).digest("base64url");
+    expect(challengeS256(verifier)).toBe(expected);
+    expect(challengeS256(verifier)).not.toContain("=");
+  });
+
+  it("produces distinct random verifiers and states", () => {
+    expect(generateVerifier()).not.toBe(generateVerifier());
+    expect(generateState()).not.toBe(generateState());
+  });
+});
+
+describe("authorize URL", () => {
+  it("includes the PKCE challenge, S256 method, state, and prompt=login", () => {
+    const url = new URL(buildAuthorizeUrl({ state: "st", codeChallenge: "ch" }));
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("code_challenge")).toBe("ch");
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(url.searchParams.get("state")).toBe("st");
+    expect(url.searchParams.get("prompt")).toBe("login");
+    expect(url.searchParams.get("redirect_uri")).toBe("http://localhost:8088/auth/callback");
+  });
+});

package/src/auth/pkce.ts

@@ -0,0 +1,26 @@
+// PKCE (RFC 7636) helpers for the authorization-code flow.
+//
+// The verifier is a high-entropy random string; its SHA-256 hash (the
+// "challenge", S256 method) is sent on /authorize, and the raw verifier is sent
+// on /token. Auth0 checks they correspond, proving the same client that started
+// the flow is completing it — without ever transmitting a client secret.
+
+import { createHash, randomBytes } from "node:crypto";
+
+// 32 random bytes -> 43-char base64url string, within RFC 7636's 43–128 range.
+const VERIFIER_BYTES = 32;
+
+/** Generate a cryptographically random PKCE code_verifier (base64url). */
+export function generateVerifier(): string {
+  return randomBytes(VERIFIER_BYTES).toString("base64url");
+}
+
+/** Derive the S256 code_challenge for a verifier: base64url(sha256(verifier)). */
+export function challengeS256(verifier: string): string {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+
+/** Generate a random OAuth `state` value for CSRF protection. */
+export function generateState(): string {
+  return randomBytes(VERIFIER_BYTES).toString("base64url");
+}

package/src/auth/token.test.ts

@@ -0,0 +1,95 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Config } from "../config/index.js";
+import { createRefreshingTokenProvider } from "./token.js";
+
+// The provider persists refreshed tokens via config.save(), which writes to
+// ~/.stigmer/config.yaml. Redirect HOME to a throwaway dir so tests never touch
+// the developer's real config.
+let originalHome: string | undefined;
+
+function cloudConfig(overrides: Partial<NonNullable<Config["backend"]["cloud"]>>): Config {
+  return { backend: { type: "cloud", cloud: { endpoint: "api.stigmer.ai:443", ...overrides } } };
+}
+
+function mockFetch(response: { ok: boolean; status?: number; body: unknown }): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => ({
+      ok: response.ok,
+      status: response.status ?? (response.ok ? 200 : 400),
+      json: async () => response.body,
+    })),
+  );
+}
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  process.env.HOME = mkdtempSync(join(tmpdir(), "stigmer-token-"));
+  delete process.env.STIGMER_API_KEY;
+});
+
+afterEach(() => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  vi.unstubAllGlobals();
+});
+
+describe("createRefreshingTokenProvider", () => {
+  it("returns STIGMER_API_KEY without refreshing", async () => {
+    process.env.STIGMER_API_KEY = "env-key";
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    const provider = createRefreshingTokenProvider(cloudConfig({ token: "stale", token_expiry: past() }));
+    expect(await provider()).toBe("env-key");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns a non-expired token without refreshing", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    const provider = createRefreshingTokenProvider(cloudConfig({ token: "good", token_expiry: future() }));
+    expect(await provider()).toBe("good");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("refreshes an expired token and persists the new one", async () => {
+    mockFetch({ ok: true, body: { access_token: "fresh", refresh_token: "r2", expires_in: 3600 } });
+    const config = cloudConfig({ token: "expired", token_expiry: past(), refresh_token: "r1" });
+    const provider = createRefreshingTokenProvider(config);
+    expect(await provider()).toBe("fresh");
+    expect(config.backend.cloud?.token).toBe("fresh");
+    expect(config.backend.cloud?.refresh_token).toBe("r2");
+  });
+
+  it("falls back to the existing token when refresh fails", async () => {
+    mockFetch({ ok: false, status: 401, body: { error: "invalid_grant" } });
+    const provider = createRefreshingTokenProvider(
+      cloudConfig({ token: "expired", token_expiry: past(), refresh_token: "r1" }),
+    );
+    expect(await provider()).toBe("expired");
+  });
+
+  it("returns null in cloud mode with no credentials", async () => {
+    const provider = createRefreshingTokenProvider(cloudConfig({}));
+    expect(await provider()).toBeNull();
+  });
+
+  it("treats a token without an expiry as valid (legacy)", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    const provider = createRefreshingTokenProvider(cloudConfig({ token: "legacy" }));
+    expect(await provider()).toBe("legacy");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+function past(): string {
+  return new Date(Date.now() - 10 * 60 * 1000).toISOString();
+}
+
+function future(): string {
+  return new Date(Date.now() + 60 * 60 * 1000).toISOString();
+}

package/src/auth/token.ts

@@ -0,0 +1,135 @@
+// Auth0 token operations: exchange an authorization code for tokens, refresh an
+// expired access token, and expose a token provider that refreshes silently.
+
+import type { TokenProvider } from "@stigmer/sdk";
+import { type Config, save } from "../config/index.js";
+import { CliExitError, ExitCode } from "../errors/index.js";
+import { CLIENT_ID, callbackUrl, TOKEN_URL } from "./auth0.js";
+
+/** Normalized result of an Auth0 token endpoint call. */
+export interface TokenSet {
+  readonly accessToken: string;
+  /** Present when `offline_access` was granted; may rotate on refresh. */
+  readonly refreshToken?: string;
+  /** Absolute expiry as an RFC 3339 string, derived from `expires_in`. */
+  readonly expiresAt?: string;
+}
+
+// Refresh this many ms before the real expiry so an in-flight request never
+// races the token going stale.
+const EXPIRY_SKEW_MS = 60_000;
+
+interface Auth0TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  error?: string;
+  error_description?: string;
+}
+
+/** Exchange a PKCE authorization code for an access (+refresh) token. */
+export async function exchangeCode(params: { code: string; codeVerifier: string }): Promise<TokenSet> {
+  return postToken({
+    grant_type: "authorization_code",
+    client_id: CLIENT_ID,
+    code: params.code,
+    redirect_uri: callbackUrl(),
+    code_verifier: params.codeVerifier,
+  });
+}
+
+/** Exchange a refresh token for a fresh access token. */
+export async function refreshAccessToken(refreshToken: string): Promise<TokenSet> {
+  return postToken({
+    grant_type: "refresh_token",
+    client_id: CLIENT_ID,
+    refresh_token: refreshToken,
+  });
+}
+
+/**
+ * A token provider for the backend client that keeps the access token fresh.
+ *
+ * Precedence and behavior, evaluated per request:
+ *   1. STIGMER_API_KEY (env / bridged --api-key) wins and is never refreshed.
+ *   2. A non-expired access token is returned as-is.
+ *   3. An expired token with a refresh token is refreshed; the new token,
+ *      rotated refresh token, and expiry are persisted, then returned.
+ *   4. Otherwise the (possibly stale) token or null is returned, letting the
+ *      server reject it so the error maps to a clear "please log in" exit.
+ *
+ * Closes over `config` so a refresh updates the same object the rest of the
+ * command sees, and writes it through to disk.
+ */
+export function createRefreshingTokenProvider(config: Config): TokenProvider {
+  return async (): Promise<string | null> => {
+    const envKey = process.env.STIGMER_API_KEY;
+    if (envKey !== undefined && envKey !== "") return envKey;
+
+    const cloud = config.backend.cloud;
+    if (cloud?.token === undefined || cloud.token === "") {
+      return cloud?.refresh_token ? refreshAndPersist(config, cloud.refresh_token) : null;
+    }
+    if (!isExpired(cloud.token_expiry)) return cloud.token;
+    if (cloud.refresh_token === undefined || cloud.refresh_token === "") return cloud.token;
+    return refreshAndPersist(config, cloud.refresh_token);
+  };
+}
+
+async function refreshAndPersist(config: Config, refreshToken: string): Promise<string | null> {
+  let next: TokenSet;
+  try {
+    next = await refreshAccessToken(refreshToken);
+  } catch {
+    // Refresh failed (revoked/expired refresh token). Fall back to the current
+    // token if any; the server will reject it and the user is prompted to log in.
+    return config.backend.cloud?.token ?? null;
+  }
+  const cloud = config.backend.cloud ?? {};
+  cloud.token = next.accessToken;
+  if (next.refreshToken !== undefined) cloud.refresh_token = next.refreshToken;
+  cloud.token_expiry = next.expiresAt;
+  config.backend.cloud = cloud;
+  save(config);
+  return next.accessToken;
+}
+
+function isExpired(expiresAt: string | undefined): boolean {
+  // Legacy tokens persisted without an expiry are assumed valid; the server is
+  // the ultimate authority and a 401 triggers re-login.
+  if (expiresAt === undefined || expiresAt === "") return false;
+  const expiryMs = Date.parse(expiresAt);
+  if (Number.isNaN(expiryMs)) return false;
+  return Date.now() >= expiryMs - EXPIRY_SKEW_MS;
+}
+
+async function postToken(form: Record<string, string>): Promise<TokenSet> {
+  let response: Response;
+  try {
+    response = await fetch(TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(form).toString(),
+    });
+  } catch (err) {
+    throw new CliExitError(
+      `failed to reach the authentication server: ${(err as Error).message}`,
+      ExitCode.Connection,
+    );
+  }
+
+  const body = (await response.json().catch(() => ({}))) as Auth0TokenResponse;
+  if (!response.ok || body.access_token === undefined) {
+    const detail = body.error_description ?? body.error ?? `HTTP ${response.status}`;
+    throw new CliExitError(`authentication failed: ${detail}`, ExitCode.Auth);
+  }
+
+  return {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt:
+      body.expires_in !== undefined
+        ? new Date(Date.now() + body.expires_in * 1000).toISOString()
+        : undefined,
+  };
+}