@ai21/gateway 0.5.3

package/dist/login/loopback.js

@@ -0,0 +1,192 @@
+/**
+ * The loopback listener that receives the login callback.
+ *
+ * This is the security surface of the whole handshake, so the invariants are
+ * asserted by tests rather than trusted: bound to `127.0.0.1` only, one valid
+ * callback accepted and no more, `state` compared before the payload is handed
+ * over, a hard timeout so the CLI cannot sit open indefinitely, and a body size
+ * cap so a stray client cannot make us buffer without bound.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { CALLBACK_PATH, START_PATH, parseCallback } from "./contract.js";
+/** Two minutes: long enough to sign in, short enough not to look wedged. */
+export const LOGIN_TIMEOUT_MS = 120_000;
+const MAX_BODY_BYTES = 8_192;
+const LOOPBACK_HOST = "127.0.0.1";
+/** 256 bits from the CSPRNG. Guessing it is not a threat model we need to model. */
+export function newState() {
+    return randomBytes(32).toString("base64url");
+}
+/** Constant-time where it can be; length mismatch is not secret. */
+function statesMatch(expected, received) {
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(received, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let body = "";
+        let tooBig = false;
+        req.on("data", (chunk) => {
+            if (tooBig)
+                return;
+            body += chunk.toString("utf8");
+            if (body.length > MAX_BODY_BYTES) {
+                tooBig = true;
+                // Destroy rather than keep reading: the only client we expect sends a few
+                // hundred bytes, so anything larger is not the flow we are in.
+                req.destroy();
+            }
+        });
+        req.on("end", () => resolve(tooBig ? undefined : body));
+        req.on("error", () => resolve(undefined));
+    });
+}
+/**
+ * Starts the listener. Resolves once it is bound, so the caller can put the real
+ * port into the URL it opens.
+ */
+export function startLoopback(options) {
+    const state = newState();
+    const timeoutMs = options.timeoutMs ?? LOGIN_TIMEOUT_MS;
+    let settle;
+    const result = new Promise((resolve) => {
+        settle = resolve;
+    });
+    let done = false;
+    /**
+     * The single-use latch. A second callback — a replayed POST, a double-submitting
+     * page — must not overwrite credentials we have already accepted.
+     */
+    const finish = (outcome) => {
+        if (done)
+            return;
+        done = true;
+        settle(outcome);
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res);
+    });
+    const cors = (res) => {
+        // The page POSTing here is on the webapp's origin, so without CORS the browser
+        // refuses the request outright. Named explicitly rather than `*`: any origin
+        // being able to talk to this port is the thing we are trying to avoid.
+        res.setHeader("Access-Control-Allow-Origin", options.allowedOrigin);
+        res.setHeader("Access-Control-Allow-Headers", "content-type");
+        res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+        // Chrome's Private Network Access: a public HTTPS page reaching a loopback address
+        // must be granted it explicitly, or the preflight fails and the POST never happens.
+        res.setHeader("Access-Control-Allow-Private-Network", "true");
+        res.setHeader("Vary", "Origin");
+    };
+    // Single-use: an attacker who guesses the port and beats the browser to /start
+    // gets the state, but the browser then fails visibly instead of the run being
+    // hijacked in silence.
+    let redirected = false;
+    let signInUrl = "";
+    async function handle(req, res) {
+        cors(res);
+        const path = (req.url ?? "").split("?")[0];
+        if (path === START_PATH) {
+            if (req.method !== "GET") {
+                res.writeHead(405).end();
+            }
+            else if (redirected) {
+                res.writeHead(410, { "content-type": "text/plain" }).end("This sign-in link has already been used.");
+            }
+            else {
+                redirected = true;
+                res.writeHead(302, { location: signInUrl }).end();
+            }
+            return;
+        }
+        if (path !== CALLBACK_PATH) {
+            res.writeHead(404).end();
+            return;
+        }
+        if (req.method === "OPTIONS") {
+            res.writeHead(204).end();
+            return;
+        }
+        if (req.method !== "POST") {
+            // Notably this rejects GET, which is what a credential-in-the-URL flow would
+            // use. The secret must arrive in a body.
+            res.writeHead(405).end();
+            return;
+        }
+        const raw = await readBody(req);
+        if (raw === undefined) {
+            res.writeHead(413).end();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            res.writeHead(400).end();
+            return;
+        }
+        const payload = parseCallback(parsed);
+        if (payload === undefined) {
+            res.writeHead(400).end();
+            return;
+        }
+        if (!statesMatch(state, payload.state)) {
+            // Rejected, and the run is *not* abandoned: a spoofed or stale POST must not
+            // be able to cancel a legitimate login that is still in progress.
+            res.writeHead(403).end();
+            return;
+        }
+        if (done) {
+            res.writeHead(409).end();
+            return;
+        }
+        res.writeHead(200, { "content-type": "application/json" }).end('{"ok":true}');
+        finish({ kind: "callback", payload });
+    }
+    const timer = setTimeout(() => finish({ kind: "timeout" }), timeoutMs);
+    // Never hold the process open on our own account.
+    timer.unref();
+    const close = () => {
+        clearTimeout(timer);
+        server.close();
+    };
+    // Closing on settle rather than making the caller remember to: a listener left
+    // open after the flow ends is an open port nobody is watching.
+    void result.then(close);
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            // Nothing bound, so nothing to close — and the timer would otherwise
+            // outlive a run that never started.
+            clearTimeout(timer);
+            reject(err);
+        };
+        server.once("error", onError);
+        // Port 0 asks the OS for an ephemeral one. The CLI tells the browser where it
+        // landed, so nothing has to guess — and there is no fixed port to collide over.
+        server.listen({ port: 0, host: LOOPBACK_HOST }, () => {
+            server.removeListener("error", onError);
+            /* Swapped only now that the socket is bound: until then an error is a bind
+             * failure, which rejects the promise rather than settling a run that never
+             * started. */
+            server.on("error", (err) => finish({ kind: "failed", reason: err.message }));
+            const address = server.address();
+            const origin = `http://${LOOPBACK_HOST}:${address.port}`;
+            const callbackUrl = `${origin}${CALLBACK_PATH}`;
+            signInUrl = options.signInUrl(callbackUrl, state);
+            resolve({
+                startUrl: `${origin}${START_PATH}`,
+                signInUrl,
+                callbackUrl,
+                state,
+                host: address.address,
+                port: address.port,
+                result,
+                close,
+            });
+        });
+    });
+}
+//# sourceMappingURL=loopback.js.map

package/dist/login/loopback.js.map

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

package/dist/login/session.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `login` orchestration: open the browser, wait on the loopback listener, hand
+ * whatever comes back to the ordinary config writer.
+ *
+ * The credentials live in a local variable for the length of one run and are
+ * written only into `settings.json`. Nothing else is persisted — no token cache, no
+ * `~/.ai21/credentials` — so there is nothing for an attacker to find later.
+ */
+import { type ResolvedUrls } from "../args.js";
+import { type Listener, type LoopbackOptions } from "./loopback.js";
+export interface LoginDeps {
+    readonly startListener: (options: LoopbackOptions) => Promise<Listener>;
+    readonly openBrowser: (url: string) => boolean;
+}
+export type LoginOutcome = {
+    readonly kind: "credentials";
+    readonly agentId: string;
+    readonly ai21Key: string;
+    /** Present only when the callback supplied a well-formed one. */
+    readonly workspaceId?: string | undefined;
+} | {
+    readonly kind: "timeout";
+} | {
+    readonly kind: "rejected";
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+};
+/** The `/welcome` URL, carrying where to call back and the nonce to echo. */
+export declare function loginUrl(urls: ResolvedUrls, callbackUrl: string, state: string): string;
+export interface LoginProgress {
+    /** Told what to say while waiting; the caller decides which stream it lands on. */
+    readonly notify: (message: string) => void;
+}
+export declare function runLogin(urls: ResolvedUrls, deps: LoginDeps, io: LoginProgress): Promise<LoginOutcome>;

package/dist/login/session.js

@@ -0,0 +1,75 @@
+/**
+ * `login` orchestration: open the browser, wait on the loopback listener, hand
+ * whatever comes back to the ordinary config writer.
+ *
+ * The credentials live in a local variable for the length of one run and are
+ * written only into `settings.json`. Nothing else is persisted — no token cache, no
+ * `~/.ai21/credentials` — so there is nothing for an attacker to find later.
+ */
+import { containsControlCharacters } from "../args.js";
+import { CALLBACK_PARAM, STATE_PARAM } from "./contract.js";
+/** The `/welcome` URL, carrying where to call back and the nonce to echo. */
+export function loginUrl(urls, callbackUrl, state) {
+    const url = new URL("/welcome", urls.app);
+    url.searchParams.set(CALLBACK_PARAM, callbackUrl);
+    url.searchParams.set(STATE_PARAM, state);
+    return url.toString();
+}
+/**
+ * Callback values are remote input, so they are validated by exactly the rule the
+ * flags use. They land in the same `\n`-joined header string, where a newline
+ * forges a header that Claude Code would then send on every request — and unlike a
+ * flag, nobody typed this.
+ */
+function rejectBadValues(payload) {
+    for (const [name, value] of [
+        ["agentId", payload.agentId],
+        ["ai21Key", payload.ai21Key],
+    ]) {
+        if (containsControlCharacters(value)) {
+            return `the ${name} in the login response contains control characters`;
+        }
+    }
+    return undefined;
+}
+export async function runLogin(urls, deps, io) {
+    let listener;
+    try {
+        listener = await deps.startListener({
+            allowedOrigin: urls.app,
+            signInUrl: (callbackUrl, state) => loginUrl(urls, callbackUrl, state),
+        });
+    }
+    catch (err) {
+        return { kind: "failed", reason: err instanceof Error ? err.message : "the local listener could not be started" };
+    }
+    // The browser is pointed at the loopback redirect, so the nonce never reaches its
+    // command line. The printed URL is the real one, since a manual path needs it.
+    //
+    // Claims nothing about whether a browser appeared: `spawn` reports a missing binary
+    // asynchronously, so a failed launch still looks like a success from here.
+    deps.openBrowser(listener.startUrl);
+    io.notify(`Sign in to continue — your browser should open. If it does not, visit:\n\n  ${listener.signInUrl}\n\nWaiting…`);
+    return settle(await listener.result);
+}
+/** Shared tail: turn a listener outcome into the credentials, or say why not. */
+function settle(outcome) {
+    switch (outcome.kind) {
+        case "timeout":
+            return { kind: "timeout" };
+        case "failed":
+            return { kind: "failed", reason: outcome.reason };
+        case "callback": {
+            const problem = rejectBadValues(outcome.payload);
+            if (problem !== undefined)
+                return { kind: "rejected", reason: problem };
+            return {
+                kind: "credentials",
+                agentId: outcome.payload.agentId,
+                ai21Key: outcome.payload.ai21Key,
+                ...(outcome.payload.workspaceId === undefined ? {} : { workspaceId: outcome.payload.workspaceId }),
+            };
+        }
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/login/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/login/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,yBAAyB,EAAqB,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAoB,WAAW,EAAE,MAAM,eAAe,CAAC;AAoB9E,6EAA6E;AAC7E,MAAM,UAAU,QAAQ,CAAC,IAAkB,EAAE,WAAmB,EAAE,KAAa;IAC7E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAClD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAEzC,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,OAAoB;IAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;QAC1B,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC;QAC5B,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC;KACpB,EAAE,CAAC;QACX,IAAI,yBAAyB,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,OAAO,OAAO,IAAI,oDAAoD,CAAC;QACzE,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAkB,EAAE,IAAe,EAAE,EAAiB;IACnF,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC;YAClC,aAAa,EAAE,IAAI,CAAC,GAAG;YACvB,SAAS,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC;SACtE,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,yCAAyC,EAAE,CAAC;IACpH,CAAC;IAED,kFAAkF;IAClF,+EAA+E;IAC/E,EAAE;IACF,oFAAoF;IACpF,2EAA2E;IAC3E,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACpC,EAAE,CAAC,MAAM,CACP,+EAA+E,QAAQ,CAAC,SAAS,cAAc,CAChH,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,iFAAiF;AACjF,SAAS,MAAM,CAAC,OAAwB;IACtC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,SAAS;YACZ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7B,KAAK,QAAQ;YACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACpD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACjD,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAExE,OAAO;gBACL,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO;gBAChC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO;gBAChC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;aACnG,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/prompt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reading the AI21 key from the terminal when `--key` was not given.
+ *
+ * Two properties matter: the key is never echoed — the whole reason for prompting
+ * rather than taking a flag — and a non-interactive run fails immediately instead
+ * of blocking on a stdin that will never deliver a line.
+ */
+import type { Readable, Writable } from "node:stream";
+/** How the prompt ended. `cancelled` covers Ctrl-C and a closed stdin. */
+export type PromptOutcome = {
+    readonly kind: "key";
+    readonly value: string;
+} | {
+    readonly kind: "no-tty";
+} | {
+    readonly kind: "cancelled";
+};
+export interface PromptIo {
+    readonly input: Readable & {
+        isTTY?: boolean;
+        setRawMode?: (raw: boolean) => void;
+    };
+    readonly output: Writable;
+    /** Overrides the stream's own flag; tests drive a pipe as though it were a tty. */
+    readonly isTTY?: boolean;
+}
+/**
+ * Reads one line without echoing it. Raw mode is what makes that possible, and is
+ * restored on every exit path — a terminal left in raw mode makes the user's next
+ * command invisible.
+ */
+export declare function promptForKey(io: PromptIo, label?: string): Promise<PromptOutcome>;

package/dist/prompt.js

@@ -0,0 +1,72 @@
+const ETX = "\u0003"; // Ctrl-C
+const EOT = "\u0004"; // Ctrl-D
+// eslint-disable-next-line no-control-regex
+const BACKSPACE = /[\u0008\u007F]/;
+// C0 controls minus the ones handled above, plus DEL.
+// eslint-disable-next-line no-control-regex
+const OTHER_CONTROL = /[\u0000-\u001F\u007F]/;
+/**
+ * Reads one line without echoing it. Raw mode is what makes that possible, and is
+ * restored on every exit path — a terminal left in raw mode makes the user's next
+ * command invisible.
+ */
+export function promptForKey(io, label = "AI21 key: ") {
+    const interactive = io.isTTY ?? io.input.isTTY ?? false;
+    if (!interactive) {
+        return Promise.resolve({ kind: "no-tty" });
+    }
+    return new Promise((resolve) => {
+        let buffer = "";
+        let settled = false;
+        const restore = () => {
+            io.input.setRawMode?.(false);
+            io.input.pause();
+            io.input.off("data", onData);
+            io.input.off("end", onEnd);
+            io.input.off("close", onEnd);
+        };
+        // Ctrl-D arrives as a byte, but a stream that simply ends delivers none. Without
+        // this the promise never settles and the CLI wedges.
+        function onEnd() {
+            finish({ kind: "cancelled" });
+        }
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            restore();
+            // The newline the user's Enter did not produce, because it was swallowed.
+            io.output.write("\n");
+            resolve(outcome);
+        };
+        function onData(chunk) {
+            for (const char of chunk.toString("utf8")) {
+                if (char === "\r" || char === "\n") {
+                    finish({ kind: "key", value: buffer });
+                    return;
+                }
+                if (char === ETX || char === EOT) {
+                    finish({ kind: "cancelled" });
+                    return;
+                }
+                if (BACKSPACE.test(char)) {
+                    buffer = buffer.slice(0, -1);
+                    continue;
+                }
+                // Arrow keys arrive as escape sequences and would corrupt the key. The flag
+                // path rejects the same characters, so accepting them here is a second way in.
+                if (OTHER_CONTROL.test(char))
+                    continue;
+                // Unechoed, and no mask characters either: a visible length is information.
+                buffer += char;
+            }
+        }
+        io.output.write(label);
+        io.input.setRawMode?.(true);
+        io.input.resume();
+        io.input.on("data", onData);
+        io.input.once("end", onEnd);
+        io.input.once("close", onEnd);
+    });
+}
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

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

package/dist/report.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Turning an outcome into output: human text on the right stream, or exactly one
+ * JSON object, plus the warnings that apply either way.
+ *
+ * Two rules hold everywhere here. The key never appears, in any line. And `--json`
+ * emits a single object, since a consumer parses the whole of stdout.
+ */
+import type { ResolvedUrls } from "./args.js";
+import type { ConfigOutcome } from "./config.js";
+import type { RevertOutcome } from "./revert.js";
+import type { VerifyOutcome } from "./verify.js";
+import { type RunResult } from "./result.js";
+/**
+ * Outcome name → exit code. This is the map `--json` consumers branch on, so the
+ * numbers are a contract: they may gain entries but never change meaning.
+ */
+export declare const EXIT_FOR: Record<ConfigOutcome["kind"], number>;
+/**
+ * `uninstall` outcome → exit code. Same contract as EXIT_FOR: entries may be added,
+ * meanings never change. Actionable refusals share CONFLICT; the two
+ * "not-there" cases get their own codes so a script can tell them apart.
+ */
+export declare const EXIT_FOR_REVERT: Record<RevertOutcome["kind"], number>;
+export declare function reportRevert(outcome: RevertOutcome, json: boolean): RunResult;
+export interface Warning {
+    /** Stable identifier, so `--json` consumers match on this and not on prose. */
+    readonly code: "anthropic-api-key-set" | "non-production-gateway" | "insecure-gateway" | "verification-skipped" | "verification-failed";
+    readonly message: string;
+}
+export interface WarningContext {
+    readonly urls: ResolvedUrls;
+    /** The process environment, injected so tests need not mutate the real one. */
+    readonly processEnv: Record<string, string | undefined>;
+}
+/**
+ * Not failures, but things that make a correct config look broken later — which is
+ * when a warning earns its noise.
+ */
+export declare function collectWarnings(ctx: WarningContext): Warning[];
+export interface ReportInput {
+    readonly outcome: ConfigOutcome;
+    readonly warnings: readonly Warning[];
+    readonly json: boolean;
+    /** Extra human-only detail, such as the per-key conflict breakdown. */
+    readonly detail?: string | undefined;
+    readonly urls: ResolvedUrls;
+    /** Absent when the write never succeeded, so verification was not attempted. */
+    readonly verification?: VerifyOutcome | undefined;
+}
+export declare function report(input: ReportInput): RunResult;