@stigmer/cli 3.13.0 → 3.14.0-dev.20260910084630

package/src/auth/login.ts

@@ -10,7 +10,12 @@
 // Progress goes to stderr; the command layer renders the final result.
 
 import open from "open";
-import { load, save } from "../config/index.js";
+import {
+  CLOUD_BACKEND_NAME,
+  activeBackend,
+  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";
@@ -21,6 +26,27 @@ import { exchangeCode } from "./token.js";
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 
 export async function login(): Promise<void> {
+  // Browser PKCE targets Stigmer Cloud only: the Auth0 coordinates are
+  // compiled in. From the local backend, login lands on (creating if
+  // needed) the reserved "cloud" entry — today's behavior in the named
+  // model. On a selfhost backend the flow refuses with the self-host
+  // credential story (API tokens) instead of silently writing cloud
+  // credentials the active backend would never send.
+  const preflight = load();
+  const { name, entry } = activeBackend(preflight);
+  if (entry?.type === "selfhost") {
+    throw new CliExitError(
+      `backend "${name}" is self-hosted — browser login targets Stigmer Cloud only`,
+      ExitCode.Usage,
+      [
+        "Authenticate a self-hosted backend with an API token:",
+        "  stigmer apikey create --name cli",
+        `  stigmer config backend add ${name} --endpoint <host:port> --api-key <key>`,
+        "or switch first:  stigmer config backend use cloud",
+      ],
+    );
+  }
+
   const verifier = generateVerifier();
   const codeChallenge = challengeS256(verifier);
   const state = generateState();
@@ -30,30 +56,49 @@ export async function login(): Promise<void> {
   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`);
+    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");
+      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);
+      throw new CliExitError(
+        "OAuth state mismatch — possible CSRF attack, aborting login",
+        ExitCode.Auth,
+      );
     }
 
-    const tokens = await exchangeCode({ code: callback.code, codeVerifier: verifier });
+    const tokens = await exchangeCode({
+      code: callback.code,
+      codeVerifier: verifier,
+    });
 
     const config = load();
-    config.backend.type = "cloud";
-    config.backend.cloud = {
-      ...config.backend.cloud,
+    const active = activeBackend(config);
+    // A cloud-type backend keeps its own login; anything else (the local
+    // daemon) lands on the reserved "cloud" entry and switches to it.
+    const targetName =
+      active.entry?.type === "cloud" ? active.name : CLOUD_BACKEND_NAME;
+    const backends = (config.backends ??= {});
+    backends[targetName] = {
+      ...(backends[targetName] ?? { type: "cloud" }),
+      type: "cloud",
       token: tokens.accessToken,
       refresh_token: tokens.refreshToken,
       token_expiry: tokens.expiresAt,
     };
+    config.current_backend = targetName;
     save(config);
   } finally {
     await server.shutdown();

package/src/auth/token.test.ts

@@ -2,7 +2,7 @@ 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 type { Config, NamedBackendConfig } from "../config/index.js";
 import { createRefreshingTokenProvider } from "./token.js";
 
 // The provider persists refreshed tokens via config.save(), which writes to
@@ -10,11 +10,35 @@ import { createRefreshingTokenProvider } from "./token.js";
 // 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 cloudConfig(overrides: Partial<NamedBackendConfig>): Config {
+  return {
+    backend: { type: "cloud" },
+    backends: {
+      cloud: { type: "cloud", endpoint: "api.stigmer.ai:443", ...overrides },
+    },
+    current_backend: "cloud",
+  };
 }
 
-function mockFetch(response: { ok: boolean; status?: number; body: unknown }): void {
+function selfhostConfig(overrides: Partial<NamedBackendConfig> = {}): Config {
+  return {
+    backend: { type: "cloud" },
+    backends: {
+      staging: {
+        type: "selfhost",
+        endpoint: "stigmer.example.com:7234",
+        ...overrides,
+      },
+    },
+    current_backend: "staging",
+  };
+}
+
+function mockFetch(response: {
+  ok: boolean;
+  status?: number;
+  body: unknown;
+}): void {
   vi.stubGlobal(
     "fetch",
     vi.fn(async () => ({
@@ -42,7 +66,9 @@ describe("createRefreshingTokenProvider", () => {
     process.env.STIGMER_API_KEY = "env-key";
     const fetchSpy = vi.fn();
     vi.stubGlobal("fetch", fetchSpy);
-    const provider = createRefreshingTokenProvider(cloudConfig({ token: "stale", token_expiry: past() }));
+    const provider = createRefreshingTokenProvider(
+      cloudConfig({ token: "stale", token_expiry: past() }),
+    );
     expect(await provider()).toBe("env-key");
     expect(fetchSpy).not.toHaveBeenCalled();
   });
@@ -50,24 +76,52 @@ describe("createRefreshingTokenProvider", () => {
   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() }));
+    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" });
+  it("refreshes an expired token and persists the new one into the entry", 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");
+    expect(config.backends?.["cloud"]?.token).toBe("fresh");
+    expect(config.backends?.["cloud"]?.refresh_token).toBe("r2");
+  });
+
+  it("returns the selfhost entry's api_key without any refresh machinery", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    const provider = createRefreshingTokenProvider(
+      selfhostConfig({ api_key: "stk_stored" }),
+    );
+    expect(await provider()).toBe("stk_stored");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns null on a selfhost backend with no stored key", async () => {
+    const provider = createRefreshingTokenProvider(selfhostConfig());
+    expect(await provider()).toBeNull();
   });
 
   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" }),
+      cloudConfig({
+        token: "expired",
+        token_expiry: past(),
+        refresh_token: "r1",
+      }),
     );
     expect(await provider()).toBe("expired");
   });
@@ -80,7 +134,9 @@ describe("createRefreshingTokenProvider", () => {
   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" }));
+    const provider = createRefreshingTokenProvider(
+      cloudConfig({ token: "legacy" }),
+    );
     expect(await provider()).toBe("legacy");
     expect(fetchSpy).not.toHaveBeenCalled();
   });

package/src/auth/token.ts

@@ -2,7 +2,12 @@
 // 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 {
+  type Config,
+  type NamedBackendConfig,
+  activeBackend,
+  save,
+} from "../config/index.js";
 import { CliExitError, ExitCode } from "../errors/index.js";
 import { CLIENT_ID, callbackUrl, TOKEN_URL } from "./auth0.js";
 
@@ -28,7 +33,10 @@ interface Auth0TokenResponse {
 }
 
 /** Exchange a PKCE authorization code for an access (+refresh) token. */
-export async function exchangeCode(params: { code: string; codeVerifier: string }): Promise<TokenSet> {
+export async function exchangeCode(params: {
+  code: string;
+  codeVerifier: string;
+}): Promise<TokenSet> {
   return postToken({
     grant_type: "authorization_code",
     client_id: CLIENT_ID,
@@ -39,7 +47,9 @@ export async function exchangeCode(params: { code: string; codeVerifier: string
 }
 
 /** Exchange a refresh token for a fresh access token. */
-export async function refreshAccessToken(refreshToken: string): Promise<TokenSet> {
+export async function refreshAccessToken(
+  refreshToken: string,
+): Promise<TokenSet> {
   return postToken({
     grant_type: "refresh_token",
     client_id: CLIENT_ID,
@@ -50,12 +60,17 @@ export async function refreshAccessToken(refreshToken: string): Promise<TokenSet
 /**
  * A token provider for the backend client that keeps the access token fresh.
  *
- * Precedence and behavior, evaluated per request:
+ * Precedence and behavior, evaluated per request against the ACTIVE named
+ * backend:
  *   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
+ *   2. selfhost backends return their stored api_key (no refresh machinery —
+ *      server-minted `stk_` tokens are opaque and live until deleted or
+ *      expired server-side); local returns null (no auth).
+ *   3. A cloud backend's non-expired access token is returned as-is.
+ *   4. An expired token with a refresh token is refreshed; the new token,
+ *      rotated refresh token, and expiry are persisted INTO THE ENTRY, then
+ *      returned.
+ *   5. 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
@@ -66,30 +81,38 @@ export function createRefreshingTokenProvider(config: Config): TokenProvider {
     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;
+    const { entry } = activeBackend(config);
+    if (entry === undefined) return null;
+    if (entry.type === "selfhost") return entry.api_key ?? null;
+
+    if (entry.token === undefined || entry.token === "") {
+      return entry.refresh_token
+        ? refreshAndPersist(config, entry, entry.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);
+    if (!isExpired(entry.token_expiry)) return entry.token;
+    if (entry.refresh_token === undefined || entry.refresh_token === "")
+      return entry.token;
+    return refreshAndPersist(config, entry, entry.refresh_token);
   };
 }
 
-async function refreshAndPersist(config: Config, refreshToken: string): Promise<string | null> {
+async function refreshAndPersist(
+  config: Config,
+  entry: NamedBackendConfig,
+  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;
+    return entry.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;
+  entry.token = next.accessToken;
+  if (next.refreshToken !== undefined) entry.refresh_token = next.refreshToken;
+  entry.token_expiry = next.expiresAt;
   save(config);
   return next.accessToken;
 }
@@ -120,7 +143,8 @@ async function postToken(form: Record<string, string>): Promise<TokenSet> {
 
   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}`;
+    const detail =
+      body.error_description ?? body.error ?? `HTTP ${response.status}`;
     throw new CliExitError(`authentication failed: ${detail}`, ExitCode.Auth);
   }
 

package/src/client/client.test.ts

@@ -4,7 +4,13 @@ import type { Config } from "../config/index.js";
 import { createBackendClient } from "./client.js";
 
 function cloud(token?: string): Config {
-  return { backend: { type: "cloud", cloud: { endpoint: "api.stigmer.ai:443", token } } };
+  return {
+    backend: { type: "cloud" },
+    backends: {
+      cloud: { type: "cloud", endpoint: "api.stigmer.ai:443", token },
+    },
+    current_backend: "cloud",
+  };
 }
 
 afterEach(() => {
@@ -19,7 +25,9 @@ describe("createBackendClient — endpoint normalization", () => {
   });
 
   it("normalizes the local endpoint to a plaintext base URL", () => {
-    const client = createBackendClient({ config: { backend: { type: "local" } } });
+    const client = createBackendClient({
+      config: { backend: { type: "local" } },
+    });
     expect(client.stigmer.baseUrl).toBe("http://localhost:7234");
   });
 });

package/src/commands/apikey/index.ts

@@ -6,11 +6,22 @@
 import { createHash } from "node:crypto";
 import { create } from "@bufbuild/protobuf";
 import { timestampDate } from "@bufbuild/protobuf/wkt";
-import { type ApiKey, ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import {
+  type ApiKey,
+  ApiKeySchema,
+} from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
 import { ApiKeyHashSchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/io_pb";
 import type { Command } from "commander";
-import { ensureAuthenticated, resolveContextOrganization } from "../../config/index.js";
-import { type OutputFlags, type OutputFormat, renderProtoJson, renderProtoYaml } from "../../output/index.js";
+import {
+  ensureAuthenticated,
+  resolveContextOrganization,
+} from "../../config/index.js";
+import {
+  type OutputFlags,
+  type OutputFormat,
+  renderProtoJson,
+  renderProtoYaml,
+} from "../../output/index.js";
 import { addReadFlags, readFormat } from "../shared.js";
 import { parseExpiration } from "./duration.js";
 
@@ -23,7 +34,9 @@ interface ApiKeyCreateFlags extends OutputFlags {
 }
 
 export function registerApiKey(program: Command): void {
-  const apikey = program.command("apikey").description("manage API keys for Stigmer Cloud authentication");
+  const apikey = program
+    .command("apikey")
+    .description("manage API keys for Stigmer Cloud authentication");
 
   const create = apikey
     .command("create")
@@ -71,14 +84,23 @@ async function runCreate(options: ApiKeyCreateFlags): Promise<void> {
   process.stdout.write(renderCreatedBanner(created));
 }
 
-async function runFingerprint(rawKey: string, options: OutputFlags): Promise<void> {
-  const hash = createHash("sha256").update(rawKey).digest("hex");
+async function runFingerprint(
+  rawKey: string,
+  options: OutputFlags,
+): Promise<void> {
+  // Base64URL without padding — the server's storage encoding (the Java
+  // ApiKeyHasher and the TS keymaterial module agree). This was hex until
+  // O3, which meant the computed hash could never match a stored key_hash
+  // and the lookup below always answered NotFound (gate ruling Q7).
+  const hash = createHash("sha256").update(rawKey).digest("base64url");
 
   const { connectBackend } = await import("../../backend.js");
   const client = connectBackend();
   ensureAuthenticated(client.config);
 
-  const key = await client.stigmer.apiKey.getByKeyHash(create(ApiKeyHashSchema, { value: hash }));
+  const key = await client.stigmer.apiKey.getByKeyHash(
+    create(ApiKeyHashSchema, { value: hash }),
+  );
   renderApiKey(key, readFormat(options));
 }
 
@@ -101,7 +123,8 @@ function renderApiKey(key: ApiKey, format: OutputFormat): void {
   }
   const lines = [`API Key: ${key.metadata?.id ?? ""}`, ""];
   if (key.metadata?.name) lines.push(`  Name:        ${key.metadata.name}`);
-  if (key.spec?.fingerprint) lines.push(`  Fingerprint: ***${key.spec.fingerprint}`);
+  if (key.spec?.fingerprint)
+    lines.push(`  Fingerprint: ***${key.spec.fingerprint}`);
   lines.push(`  Expires:     ${formatExpiry(key)}`);
   process.stdout.write(`${lines.join("\n")}\n`);
 }
@@ -121,13 +144,21 @@ function renderCreatedBanner(key: ApiKey): string {
     `  ID:          ${key.metadata?.id ?? ""}`,
   ];
   if (key.metadata?.name) lines.push(`  Name:        ${key.metadata.name}`);
-  if (key.spec?.fingerprint) lines.push(`  Fingerprint: ***${key.spec.fingerprint}`);
-  lines.push(`  Expires:     ${formatExpiry(key)}`, "", "Usage:", `  export STIGMER_API_KEY='${key.spec?.keyHash ?? ""}'`, "");
+  if (key.spec?.fingerprint)
+    lines.push(`  Fingerprint: ***${key.spec.fingerprint}`);
+  lines.push(
+    `  Expires:     ${formatExpiry(key)}`,
+    "",
+    "Usage:",
+    `  export STIGMER_API_KEY='${key.spec?.keyHash ?? ""}'`,
+    "",
+  );
   return `${lines.join("\n")}\n`;
 }
 
 function formatExpiry(key: ApiKey): string {
   if (key.spec?.neverExpires) return "Never";
-  if (key.spec?.expiresAt !== undefined) return timestampDate(key.spec.expiresAt).toISOString();
+  if (key.spec?.expiresAt !== undefined)
+    return timestampDate(key.spec.expiresAt).toISOString();
   return "Never";
 }

package/src/commands/auth/index.ts

@@ -4,12 +4,24 @@
 // the standard mutating-output flags.
 
 import type { Command } from "commander";
-import { ensureAuthenticated, load, resolveContextOrganization, save } from "../../config/index.js";
-import { CommandResult, type OutputFlags, renderResult } from "../../output/index.js";
+import {
+  activeBackend,
+  ensureAuthenticated,
+  load,
+  resolveContextOrganization,
+  save,
+} from "../../config/index.js";
+import {
+  CommandResult,
+  type OutputFlags,
+  renderResult,
+} from "../../output/index.js";
 import { addResultFlags, resultFormat } from "../shared.js";
 
 export function registerAuth(program: Command): void {
-  const auth = program.command("auth").description("manage authentication with Stigmer Cloud");
+  const auth = program
+    .command("auth")
+    .description("manage authentication with Stigmer Cloud");
 
   auth
     .command("login")
@@ -44,15 +56,32 @@ export function registerAuth(program: Command): void {
 
 function runLogout(): CommandResult {
   const config = load();
-  const cloud = config.backend.cloud;
-  if (cloud === undefined || (cloud.token === undefined && cloud.refresh_token === undefined)) {
-    return CommandResult.warning("Not currently logged in").hint("Run 'stigmer auth login' to authenticate.");
+  const { name, entry } = activeBackend(config);
+  if (entry?.type === "selfhost") {
+    if (entry.api_key === undefined) {
+      return CommandResult.warning("No API key stored for this backend");
+    }
+    entry.api_key = undefined;
+    save(config);
+    return CommandResult.success(
+      `Cleared the stored API key for backend "${name}"`,
+    );
+  }
+  if (
+    entry === undefined ||
+    (entry.token === undefined && entry.refresh_token === undefined)
+  ) {
+    return CommandResult.warning("Not currently logged in").hint(
+      "Run 'stigmer auth login' to authenticate.",
+    );
   }
-  cloud.token = undefined;
-  cloud.refresh_token = undefined;
-  cloud.token_expiry = undefined;
+  entry.token = undefined;
+  entry.refresh_token = undefined;
+  entry.token_expiry = undefined;
   save(config);
-  return CommandResult.success("Logged out from Stigmer Cloud").hint("Run 'stigmer auth login' to authenticate again.");
+  return CommandResult.success("Logged out from Stigmer Cloud").hint(
+    "Run 'stigmer auth login' to authenticate again.",
+  );
 }
 
 async function runWhoami(): Promise<CommandResult> {
@@ -66,21 +95,30 @@ async function runWhoami(): Promise<CommandResult> {
 
   if (account.metadata !== undefined) {
     section.field("Account ID", account.metadata.id);
-    if (account.metadata.name !== "") section.field("Name", account.metadata.name);
+    if (account.metadata.name !== "")
+      section.field("Name", account.metadata.name);
   }
   if (account.spec !== undefined) {
     if (account.spec.email !== "") section.field("Email", account.spec.email);
     if (account.spec.firstName !== "" || account.spec.lastName !== "") {
-      section.field("Full Name", `${account.spec.firstName} ${account.spec.lastName}`.trim());
+      section.field(
+        "Full Name",
+        `${account.spec.firstName} ${account.spec.lastName}`.trim(),
+      );
     }
-    section.field("Account Type", account.spec.isMachineAccount ? "Machine Account" : "User Account");
+    section.field(
+      "Account Type",
+      account.spec.isMachineAccount ? "Machine Account" : "User Account",
+    );
   }
 
   const org = resolveContextOrganization(client.config);
   if (org !== "") {
     section.field("Organization", org);
   } else {
-    result.hint("No organization set. Use: stigmer config context set --org <slug>");
+    result.hint(
+      "No organization set. Use: stigmer config context set --org <slug>",
+    );
   }
 
   return result;