@ai21/gateway 0.6.0 → 1.0.0

package/dist/login/keychain/runner.d.ts

@@ -0,0 +1,30 @@
+import type { SecretName } from "../secretStore.js";
+/** The service every keychain entry is filed under, on both backends. */
+export declare const KEYCHAIN_SERVICE = "ai21-gateway";
+/** Generous for a local call, short enough that a hung prompt does not hold the CLI. */
+export declare const KEYCHAIN_TIMEOUT_MS = 10000;
+/** One entry per secret per gateway, so staging is never production and each secret has its own lifetime. */
+export declare function accountFor(gateway: string, name: SecretName): string;
+export interface CommandOutcome {
+    /** `null` when the process was killed or never started. */
+    readonly code: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    /** The executable is missing or not runnable — the tier is unavailable, not failing. */
+    readonly spawnFailed: boolean;
+}
+/** Injected so tests drive the backends without a real keychain. */
+export type CommandRunner = (executable: string, args: readonly string[], options: {
+    readonly input?: string | undefined;
+    readonly timeoutMs: number;
+}) => Promise<CommandOutcome>;
+/** Why a credential command failed, for an error message. Never includes stdout, which may hold a secret. */
+export declare function failureReason(outcome: CommandOutcome): string;
+export declare const runCredentialCommand: CommandRunner;
+/** For callers inside the credentials-file lock, which is synchronous. */
+export type SyncCommandRunner = (executable: string, args: readonly string[], options: {
+    readonly timeoutMs: number;
+}) => CommandOutcome;
+/** No stdin: nothing synchronous needs to send a secret. */
+export declare const runCredentialCommandSync: SyncCommandRunner;

package/dist/login/keychain/runner.js

@@ -0,0 +1,88 @@
+/**
+ * Runs a credential tool as a child process with a hard bound. A child process, not a
+ * native binding: a blocked child can be killed, a blocked native call cannot, and on
+ * macOS the keychain grant stays with the Apple-signed `/usr/bin/security` across node
+ * upgrades. Secrets go in on stdin, never in `args`, which `ps` shows to every user.
+ */
+import { spawn, spawnSync } from "node:child_process";
+/** The service every keychain entry is filed under, on both backends. */
+export const KEYCHAIN_SERVICE = "ai21-gateway";
+/** Generous for a local call, short enough that a hung prompt does not hold the CLI. */
+export const KEYCHAIN_TIMEOUT_MS = 10_000;
+/** One entry per secret per gateway, so staging is never production and each secret has its own lifetime. */
+export function accountFor(gateway, name) {
+    return `${gateway}#${name}`;
+}
+/** Enough for a key or a token; a credential tool answering with more is malfunctioning. */
+const MAX_OUTPUT_CHARS = 64 * 1024;
+/** Why a credential command failed, for an error message. Never includes stdout, which may hold a secret. */
+export function failureReason(outcome) {
+    if (outcome.spawnFailed)
+        return "the tool could not be run";
+    if (outcome.timedOut)
+        return "timed out";
+    const text = outcome.stderr.trim();
+    return text === "" ? `exit code ${outcome.code}` : text.split("\n")[0];
+}
+export const runCredentialCommand = (executable, args, options) => new Promise((resolve) => {
+    let child;
+    try {
+        child = spawn(executable, [...args], { stdio: ["pipe", "pipe", "pipe"] });
+    }
+    catch {
+        return resolve({ code: null, stdout: "", stderr: "", timedOut: false, spawnFailed: true });
+    }
+    let stdout = "";
+    let stderr = "";
+    const capture = (append) => (chunk) => {
+        append(chunk.toString("utf8"));
+    };
+    child.stdout.on("data", capture((t) => (stdout += stdout.length < MAX_OUTPUT_CHARS ? t : "")));
+    child.stderr.on("data", capture((t) => (stderr += stderr.length < MAX_OUTPUT_CHARS ? t : "")));
+    let done = false;
+    const settle = (outcome) => {
+        if (done)
+            return;
+        done = true;
+        clearTimeout(timer);
+        resolve(outcome);
+    };
+    // SIGKILL: a process waiting on a keychain dialog may not act on a signal it can catch.
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        settle({ code: null, stdout, stderr, timedOut: true, spawnFailed: false });
+    }, options.timeoutMs);
+    timer.unref();
+    // ENOENT for a tool that is not installed — `secret-tool` on most servers.
+    child.on("error", () => settle({ code: null, stdout: "", stderr: "", timedOut: false, spawnFailed: true }));
+    child.on("close", (code) => settle({ code, stdout, stderr, timedOut: false, spawnFailed: false }));
+    // EPIPE when the child has already gone; the close handler reports that.
+    child.stdin.on("error", () => undefined);
+    if (options.input !== undefined)
+        child.stdin.end(options.input);
+    else
+        child.stdin.end();
+});
+/** No stdin: nothing synchronous needs to send a secret. */
+export const runCredentialCommandSync = (executable, args, options) => {
+    const result = spawnSync(executable, [...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: options.timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: MAX_OUTPUT_CHARS,
+        windowsHide: true,
+    });
+    // pid 0: the process never started, e.g. ENOENT.
+    if (result.pid === 0)
+        return { code: null, stdout: "", stderr: "", timedOut: false, spawnFailed: true };
+    const timedOut = result.error?.code === "ETIMEDOUT";
+    return {
+        code: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        timedOut,
+        spawnFailed: false,
+    };
+};
+//# sourceMappingURL=runner.js.map

package/dist/login/keychain/runner.js.map

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

package/dist/login/keychain/select.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Picking a tier, and falling back to the file when the keychain will not answer. The
+ * fallback is silent: storage is meant to be invisible, and once an agent is configured
+ * the key sits in plaintext in its own config anyway.
+ */
+import { type CredentialPaths } from "../credentials.js";
+import type { SecretStore } from "../secretStore.js";
+import { type LinuxKeychainDeps } from "./linux.js";
+import { type MacosKeychainDeps } from "./macos.js";
+export interface TierDeps extends MacosKeychainDeps, LinuxKeychainDeps {
+    readonly paths: CredentialPaths;
+}
+/** The platform's keychain where one is reachable, otherwise the file. */
+export declare function selectSecretStore(deps: TierDeps): SecretStore;

package/dist/login/keychain/select.js

@@ -0,0 +1,74 @@
+/**
+ * Picking a tier, and falling back to the file when the keychain will not answer. The
+ * fallback is silent: storage is meant to be invisible, and once an agent is configured
+ * the key sits in plaintext in its own config anyway.
+ */
+import { fileSecretStore } from "../credentials.js";
+import { findSecretTool, linuxKeychainStore } from "./linux.js";
+import { macosKeychainAvailable, macosKeychainStore } from "./macos.js";
+/** The platform's keychain where one is reachable, otherwise the file. */
+export function selectSecretStore(deps) {
+    const file = fileSecretStore(deps.paths);
+    const keychain = chooseKeychain(deps);
+    return keychain === undefined ? file : withFileFallback(keychain, file);
+}
+function chooseKeychain(deps) {
+    if (macosKeychainAvailable(deps))
+        return macosKeychainStore(deps);
+    const secretTool = findSecretTool(deps);
+    return secretTool === undefined ? undefined : linuxKeychainStore(deps, secretTool);
+}
+/**
+ * The file holds a secret only when it is the newest copy: written before the keychain
+ * tier existed, or written there because the keychain refused. A successful keychain
+ * write drops the file copy. So reads try the file first, and a keychain entry left
+ * behind by a failed write can never shadow the value that replaced it.
+ *
+ * A keychain that throws is not asked again for the rest of the process, so a locked
+ * keychain costs one timeout, not one per call.
+ */
+function withFileFallback(keychain, file) {
+    let degraded = false;
+    const degrade = () => {
+        degraded = true;
+    };
+    return {
+        get tier() {
+            return degraded ? file.tier : keychain.tier;
+        },
+        async read(gateway, name) {
+            const fromFile = await file.read(gateway, name);
+            if (fromFile !== undefined || degraded)
+                return fromFile;
+            try {
+                return await keychain.read(gateway, name);
+            }
+            catch {
+                degrade();
+                return undefined;
+            }
+        },
+        async write(gateway, name, value) {
+            if (!degraded) {
+                try {
+                    await keychain.write(gateway, name, value);
+                }
+                catch {
+                    degrade();
+                }
+            }
+            if (degraded) {
+                await file.write(gateway, name, value);
+            }
+            else {
+                await file.forget(gateway, name);
+            }
+        },
+        async forget(gateway, name) {
+            const fromKeychain = degraded ? false : await keychain.forget(gateway, name);
+            const fromFile = await file.forget(gateway, name);
+            return fromKeychain || fromFile;
+        },
+    };
+}
+//# sourceMappingURL=select.js.map

package/dist/login/keychain/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/login/keychain/select.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAwB,MAAM,mBAAmB,CAAC;AAE1E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAA0B,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAA0B,MAAM,YAAY,CAAC;AAMhG,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAEtC,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,cAAc,CAAC,IAAc;IACpC,IAAI,sBAAsB,CAAC,IAAI,CAAC;QAAE,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAElE,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAExC,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,QAAqB,EAAE,IAAiB;IAChE,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,IAAI;YACN,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC9C,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI;YACtB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC;YAExD,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,CAAC;gBAEV,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK;YAC9B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,IAAI,CAAC;oBACH,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC7C,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC;YAED,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI;YACxB,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC7E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAElD,OAAO,YAAY,IAAI,QAAQ,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/login/lock.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Removes a lock judged stale without removing a live one. Several waiters can judge the
+ * same lock stale; renaming it to a name only this process uses lets exactly one take it.
+ * If what it took is not the lock it judged, another waiter already replaced that one,
+ * so it goes back. `link` rather than `rename` for that, so it cannot overwrite a third
+ * process's lock; in that case the lock stays lost, which takes three processes racing
+ * within microseconds of a crash.
+ */
+export declare function breakStale(lockPath: string, judgedIno: number): void;
+/**
+ * Runs `change` with the lock held, and releases it however that turns out. The lock's
+ * directory must exist. Throws if the lock is not free within the budget.
+ */
+export declare function withLock<T>(lockPath: string, change: () => T, options?: {
+    waitBudgetMs?: number;
+}): T;

package/dist/login/lock.js

@@ -0,0 +1,139 @@
+/**
+ * A cross-process lock around the credentials file. Every write there is
+ * read-modify-write, so without it two concurrent `ai21-gateway` processes can drop each
+ * other's gateway entries. Synchronous, to match the file writes it guards.
+ *
+ * Known limit: liveness is `kill(pid, 0)`, which only means something on this host. A
+ * home directory shared across hosts or containers can make a live holder look dead.
+ */
+import { closeSync, fstatSync, linkSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+/** Long enough that an ordinary write never hits it, short enough to not feel hung. */
+const WAIT_BUDGET_MS = 10_000;
+/**
+ * Backstop for a lock whose pid is unreadable or was recycled. Normally staleness is
+ * decided by whether the holder is still running, so a slow holder is never robbed.
+ * A write holds the lock for milliseconds, so this only has to outlast the wait budget.
+ */
+const STALE_AFTER_MS = 15_000;
+const RETRY_MS = 20;
+/** Blocks this thread without a busy loop. A CLI has nothing else to do meanwhile. */
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** One consistent look at the lock file, or undefined when it cannot be read (usually: it is gone). */
+function inspect(lockPath) {
+    let fd;
+    try {
+        fd = openSync(lockPath, "r");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const { ino, mtimeMs } = fstatSync(fd);
+        return { ino, ageMs: Date.now() - mtimeMs, running: isRunning(readFileSync(fd, "utf8")) };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * `kill(pid, 0)` only asks whether the pid exists; `EPERM` means it does, under another
+ * user. A missing or malformed pid counts as running — the holder may not have written it
+ * yet — and is left to the age backstop.
+ */
+function isRunning(content) {
+    const pid = Number.parseInt(content.trim(), 10);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Removes a lock judged stale without removing a live one. Several waiters can judge the
+ * same lock stale; renaming it to a name only this process uses lets exactly one take it.
+ * If what it took is not the lock it judged, another waiter already replaced that one,
+ * so it goes back. `link` rather than `rename` for that, so it cannot overwrite a third
+ * process's lock; in that case the lock stays lost, which takes three processes racing
+ * within microseconds of a crash.
+ */
+export function breakStale(lockPath, judgedIno) {
+    const claimed = `${lockPath}.${process.pid}`;
+    try {
+        renameSync(lockPath, claimed);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    try {
+        if (statSync(claimed).ino !== judgedIno)
+            linkSync(claimed, lockPath);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    finally {
+        rmSync(claimed, { force: true });
+    }
+}
+/** Only if it is still ours: if our lock was broken as stale, what sits there now is someone else's. */
+function release(lockPath, ownIno) {
+    try {
+        if (statSync(lockPath).ino === ownIno)
+            rmSync(lockPath, { force: true });
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+/**
+ * Runs `change` with the lock held, and releases it however that turns out. The lock's
+ * directory must exist. Throws if the lock is not free within the budget.
+ */
+export function withLock(lockPath, change, options = {}) {
+    // Overridable so the test for the refusal does not spend the real budget waiting.
+    const deadline = Date.now() + (options.waitBudgetMs ?? WAIT_BUDGET_MS);
+    let fd;
+    for (;;) {
+        try {
+            // "wx" is O_CREAT|O_EXCL: the create either wins or fails, with no window between
+            // the check and the claim.
+            fd = openSync(lockPath, "wx", 0o600);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        const holder = inspect(lockPath);
+        if (holder !== undefined && (!holder.running || holder.ageMs > STALE_AFTER_MS)) {
+            breakStale(lockPath, holder.ino);
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`another ai21-gateway command is writing credentials (${lockPath} held for ${holder?.ageMs ?? "?"}ms). ` +
+                "Wait for it to finish, or delete that file if nothing is running.");
+        }
+        sleep(RETRY_MS);
+    }
+    const ownIno = fstatSync(fd).ino;
+    try {
+        // Waiters test this pid to decide whether the lock is stale.
+        writeSync(fd, `${process.pid}\n`);
+        return change();
+    }
+    finally {
+        closeSync(fd);
+        release(lockPath, ownIno);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/login/lock.js.map

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

package/dist/login/secretStore.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Where secrets live between runs.
+ *
+ * `login` holds two secrets with independent lifetimes: a Firebase refresh token, which
+ * acts as the user, and the AI21 key minted for it. Either can be revoked or expire
+ * without the other, so each is read, replaced and forgotten on its own. Both are keyed
+ * by gateway URL, so a staging secret is never sent to production.
+ *
+ * Async although the file tier is synchronous: the keychain tiers shell out.
+ */
+/** Matches the field names the file tier already uses, so the on-disk shape is unchanged. */
+export type SecretName = "refreshToken" | "ai21Key";
+/** Which backend holds the secrets, so the CLI can tell the user where their key is. */
+export type SecretTier = "file" | "keychain";
+export interface SecretStore {
+    readonly tier: SecretTier;
+    read(gateway: string, name: SecretName): Promise<string | undefined>;
+    write(gateway: string, name: SecretName, value: string): Promise<void>;
+    /** Resolves false when there was nothing to forget. */
+    forget(gateway: string, name: SecretName): Promise<boolean>;
+}

package/dist/login/secretStore.js

@@ -0,0 +1,12 @@
+/**
+ * Where secrets live between runs.
+ *
+ * `login` holds two secrets with independent lifetimes: a Firebase refresh token, which
+ * acts as the user, and the AI21 key minted for it. Either can be revoked or expire
+ * without the other, so each is read, replaced and forgotten on its own. Both are keyed
+ * by gateway URL, so a staging secret is never sent to production.
+ *
+ * Async although the file tier is synchronous: the keychain tiers shell out.
+ */
+export {};
+//# sourceMappingURL=secretStore.js.map

package/dist/login/secretStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretStore.js","sourceRoot":"","sources":["../../src/login/secretStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/login/session.d.ts

@@ -2,11 +2,14 @@ import { type ResolvedUrls } from "../args.js";
 import type { FetchLike } from "./tokens.js";
 import { type CliCredential } from "./contract.js";
 import { type Listener, type LoopbackOptions } from "./loopback.js";
+import type { SecretStore } from "./secretStore.js";
 export interface LoginDeps {
     readonly startListener: (options: LoopbackOptions) => Promise<Listener>;
     readonly openBrowser: (url: string) => boolean;
     /** For the token exchange and workspace listing; injected so tests make no calls. */
     readonly fetchImpl: FetchLike;
+    /** Where the refresh token and the minted key are kept; injected so tests use neither. */
+    readonly secrets: SecretStore;
 }
 export type LoginOutcome = {
     readonly kind: "credential";

package/dist/login/session.js.map

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

package/dist/login/workspaces.d.ts

@@ -1,5 +1,5 @@
 /**
- * The caller's AI21 workspaces, so `login` can say which one it signed in to.
+ * The caller's AI21 workspaces, and which one to act in.
  *
  * Identity shares the gateway's origin (`api.<domain>/identity`), so the URL is derived
  * from it. Authenticated with the Firebase ID token in a `firebase-token` header —
@@ -9,9 +9,26 @@ import type { FetchLike } from "./tokens.js";
 export interface Workspace {
     readonly id: string;
     readonly name: string;
+    /** `"public"`, `"private"`, or `"personal"` — identity sends `workspace_type`. */
+    readonly workspaceType: string;
 }
 /** `https://api.example.com/gateway` → `https://api.example.com`. */
 export declare function identityBase(gatewayUrl: string): string | undefined;
 /** Empty rather than throwing on anything unexpected: a completed login must not be lost
  *  to a failed listing. */
 export declare function fetchWorkspaces(gatewayUrl: string, idToken: string, fetchImpl?: FetchLike): Promise<readonly Workspace[]>;
+/**
+ * Which workspace the key is minted into. `overrideId` is `--workspace`, and returns
+ * undefined when it names nothing in the listing rather than falling back — silently
+ * minting somewhere else is exactly what the flag exists to prevent.
+ *
+ * Identity returns public + personal + private, but neither group is ordered within
+ * itself, so taking its first is not reproducible. Public first, then by id, is.
+ */
+export declare function chooseWorkspace(available: readonly Workspace[], overrideId?: string): Workspace | undefined;
+/**
+ * The workspace holding `agentId`, found by listing each workspace's agents. A key only
+ * sees its own workspace's agents, so minting anywhere else makes `install` refuse the
+ * agent it was asked to configure. Undefined when none holds it or none answered.
+ */
+export declare function workspaceOwningAgent(agentsUrl: string, idToken: string, workspaces: readonly Workspace[], agentId: string, fetchImpl?: FetchLike): Promise<Workspace | undefined>;

package/dist/login/workspaces.js

@@ -53,13 +53,57 @@ function parse(payload) {
         const name = row["name"];
         if (typeof id !== "string" || id === "")
             continue;
-        if (typeof row["type"] === "string" && row["type"].toLowerCase() === LEGACY_PERSONAL_TYPE)
+        // identity sends `workspace_type`; the legacy `type` is tolerated alongside it.
+        const rawType = typeof row["workspace_type"] === "string" ? row["workspace_type"] : row["type"];
+        const workspaceType = typeof rawType === "string" ? rawType.toLowerCase() : "";
+        if (workspaceType === LEGACY_PERSONAL_TYPE)
             continue;
         // Stripped for the same reason as the callback's strings: this gets printed.
         // eslint-disable-next-line no-control-regex
         const label = typeof name === "string" ? name.replace(/[\u0000-\u001F\u007F]/g, "") : "";
-        found.push({ id, name: label === "" ? id : label });
+        found.push({ id, name: label === "" ? id : label, workspaceType });
     }
     return found;
 }
+/** Identity's own notion of primary: an org's public workspace, not a private one. */
+const PUBLIC_TYPE = "public";
+/**
+ * Which workspace the key is minted into. `overrideId` is `--workspace`, and returns
+ * undefined when it names nothing in the listing rather than falling back — silently
+ * minting somewhere else is exactly what the flag exists to prevent.
+ *
+ * Identity returns public + personal + private, but neither group is ordered within
+ * itself, so taking its first is not reproducible. Public first, then by id, is.
+ */
+export function chooseWorkspace(available, overrideId) {
+    if (overrideId !== undefined)
+        return available.find((workspace) => workspace.id === overrideId);
+    const rank = (workspace) => (workspace.workspaceType === PUBLIC_TYPE ? 0 : 1);
+    return [...available].sort((a, b) => rank(a) - rank(b) || a.id.localeCompare(b.id))[0];
+}
+/**
+ * The workspace holding `agentId`, found by listing each workspace's agents. A key only
+ * sees its own workspace's agents, so minting anywhere else makes `install` refuse the
+ * agent it was asked to configure. Undefined when none holds it or none answered.
+ */
+export async function workspaceOwningAgent(agentsUrl, idToken, workspaces, agentId, fetchImpl = fetch) {
+    const holds = async (workspace) => {
+        try {
+            const response = await fetchImpl(agentsUrl, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${idToken}`, "X-Workspace-Id": workspace.id },
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!response.ok)
+                return false;
+            const agents = JSON.parse(await response.text());
+            return Array.isArray(agents) && agents.some((agent) => agent?.agent_id === agentId);
+        }
+        catch {
+            return false;
+        }
+    };
+    const answers = await Promise.all(workspaces.map(holds));
+    return workspaces.find((_, n) => answers[n]);
+}
 //# sourceMappingURL=workspaces.js.map

package/dist/login/workspaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/login/workspaces.ts"],"names":[],"mappings":"AASA,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAC/C,MAAM,UAAU,GAAG,MAAM,CAAC;AAE1B;uCACuC;AACvC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAOxC,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;2BAC2B;AAC3B,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,OAAe,EACf,YAAuB,KAAK;IAE5B,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAElC,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,IAAI,GAAG,eAAe,EAAE,EAAE;YACtD,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,gBAAgB,EAAE,OAAO,EAAE;YACtC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC;SACxC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IAE5B,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;QACxD,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,KAAK,CAAC,OAAgB;IAC7B,uEAAuE;IACvE,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,OAAoC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IAEzG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAE1D,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QAElD,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,oBAAoB;YAAE,SAAS;QAEpG,6EAA6E;QAC7E,4CAA4C;QAC5C,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/login/workspaces.ts"],"names":[],"mappings":"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"}

package/dist/precheck.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Checks a pasted AI21 key before anything is written, with a GET on the agents
+ * endpoint. Only a positively identified rejection stops a write: there is no flag to
+ * bypass this, so anything we cannot read has to fall through and let the write happen.
+ */
+/** Just enough of `fetch` to GET with. `text` is optional; absent reads as unparseable. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text?: () => Promise<string>;
+}>;
+export interface PrecheckDeps {
+    readonly fetchImpl: FetchLike;
+}
+export interface PrecheckContext {
+    /** The resolved agents endpoint — `urls.agents`, never rebuilt here. */
+    readonly agentsUrl: string;
+    /** The agent the config will name; checked for existence under this key. */
+    readonly agentId: string;
+    readonly ai21Key: string;
+}
+export declare const PRECHECK_TIMEOUT_MS = 10000;
+/** `rejected` and `unknown-agent` are separate because their remedies differ. */
+export type PrecheckOutcome = {
+    readonly kind: "accepted";
+} | {
+    readonly kind: "rejected";
+    readonly reason: string;
+} | {
+    readonly kind: "unknown-agent";
+    readonly known: readonly string[];
+} | {
+    readonly kind: "inconclusive";
+    readonly reason: string;
+} | {
+    readonly kind: "skipped";
+    readonly reason: string;
+};
+/** Reasons carry no key and end without a full stop — `report.ts` punctuates. */
+export declare function precheckKey(ctx: PrecheckContext, deps: PrecheckDeps): Promise<PrecheckOutcome>;
+/** The real-world adapter, kept here so `cli.ts` stays a thin edge. */
+export declare function nodePrecheckDeps(): PrecheckDeps;