Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
fix(client): never send IX_TOKEN to a non-local endpoint
KageBinaryde57b89be3b2
diff --git a/docs-site/src/content/docs/reference/configuration.md b/docs-site/src/content/docs/reference/configuration.mdindex 629218f5..e4982e06 100644--- a/docs-site/src/content/docs/reference/configuration.md+++ b/docs-site/src/content/docs/reference/configuration.md@@ -19,7 +19,7 @@ ix config set format llm # set a value|---|---|| `IX_HOME` | Relocates everything under `~/.ix`, configuration included. Useful for giving a CI job or a second install its own state. It's read at use, not at install, so move `~/.ix` there rather than expecting the old configuration to be found || `IX_FORMAT` | Default output format: `text`, `json` or `llm`. Overrides the config file. `--format` overrides it |-| `IX_TOKEN=<token>` | Bearer token sent to the backend on every request, to any endpoint. Overrides the stored local token (see [Local token](#local-token)) |+| `IX_TOKEN=<token>` | Bearer token sent to a local backend (localhost or another loopback address) on every request. Overrides the stored local token (see [Local token](#local-token)). Never sent to any other endpoint || `IX_DEBUG=1` | Prints full stack traces on errors || `IX_READ_DEADLINE_MS=<ms>` | How long one command's reads may take in all before it fails (default 60000), so a hung backend fails a query in a minute rather than after each request's 2-minute timeout. The clock restarts after each write the command makes. `ix map`, `ix ingest` and `ix stats` have no read deadline. `0` turns it off. A read that meets a refused or dropped connection, or a 502/503/504, is retried once; writes never are || `IX_MCP_SUBPROCESS=1` | Runs each MCP tool call in its own `ix` process |@@ -77,4 +77,4 @@ ix docker start --no-local-token # stop requiring it and forget itix doctor # "Backend token" says whether it is required and accepted```-The token is stored as `auth.local_token` in `~/.ix/config.yaml` and written to `~/.ix/backend/.env` for Compose. The CLI and `ix view` send it only to a local endpoint; set `IX_TOKEN` to send a token to any other backend.+The token is stored as `auth.local_token` in `~/.ix/config.yaml` and written to `~/.ix/backend/.env` for Compose. The CLI and `ix view` send it only to a local endpoint. `IX_TOKEN` overrides it, under the same rule: no token, stored or from `IX_TOKEN`, is sent to a backend on another host. To use a token-protected backend elsewhere, forward its port to this machine (for example `ssh -L 8090:localhost:8090 <host>`) and point `IX_ENDPOINT` at `http://localhost:8090`.diff --git a/ix-cli/src/cli/__tests__/local-token.test.ts b/ix-cli/src/cli/__tests__/local-token.test.tsindex 01071010..10b61e77 100644--- a/ix-cli/src/cli/__tests__/local-token.test.ts+++ b/ix-cli/src/cli/__tests__/local-token.test.ts@@ -131,12 +131,55 @@ describe("the client sends the token on every request", () => {});describe("which token goes where", () => {- it("IX_TOKEN wins, and goes to any endpoint", async () => {+ it("IX_TOKEN wins on a loopback endpoint and is never sent anywhere else", async () => {storeToken("b".repeat(64));process.env.IX_TOKEN = TOKEN;const { getLocalToken } = await import("../config.js");expect(getLocalToken("http://localhost:8090")).toBe(TOKEN);- expect(getLocalToken("https://ix.example.com")).toBe(TOKEN);+ expect(getLocalToken("http://127.0.0.1:8090")).toBe(TOKEN);+ expect(getLocalToken("https://ix.example.com")).toBeUndefined();+ expect(getLocalToken("https://tunnel.ix-infra.com/t/acme")).toBeUndefined();+ expect(getLocalToken("http://127.0.0.1.evil.com:8090")).toBeUndefined();+ });++ it("a client for a remote endpoint sends no Authorization header, even with IX_TOKEN set", async () => {+ storeToken(TOKEN);+ process.env.IX_TOKEN = TOKEN;+ const sent: Array<string | null> = [];+ vi.spyOn(globalThis, "fetch").mockImplementation(async (_input, init) => {+ sent.push(new Headers(init?.headers).get("authorization"));+ return new Response(JSON.stringify({ results: [] }), { status: 200, headers: { "content-type": "application/json" } });+ });+ const { createClient } = await import("../../client/factory.js");+ const client = createClient({ endpoint: "https://ix.example.com" });+ expect(client.sendsToken).toBe(false);+ await client.search("x");+ expect(sent).toEqual([null]);+ });++ it("Ix Pro's cloud JWT is no longer replaced by IX_TOKEN (createClient via config.ts)", async () => {+ // Pro's cloud-auth.ts wraps fetch and adds `Bearer <org JWT>` to requests+ // at the trusted cloud origin only when no Authorization header is set.+ // Before, IX_TOKEN went to every endpoint and took the JWT's place.+ const cloud = "https://tunnel.example.com/t/acme";+ writeFileSync(join(home, "config.yaml"), `endpoint: ${cloud}\nformat: text\n`);+ process.env.IX_TOKEN = TOKEN;+ const sent: Array<string | null> = [];+ const inner = async (_input: unknown, init?: RequestInit) => {+ sent.push(new Headers(init?.headers).get("authorization"));+ return new Response(JSON.stringify({ results: [] }), { status: 200, headers: { "content-type": "application/json" } });+ };+ vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {+ const headers = new Headers(init?.headers);+ if (String(input instanceof Request ? input.url : input).startsWith(cloud) && !headers.get("authorization")) {+ headers.set("authorization", "Bearer org-jwt");+ }+ return inner(input, { ...init, headers });+ });+ const { createClient } = await import("../config.js");+ const client = await createClient();+ await client.search("x");+ expect(sent).toEqual(["Bearer org-jwt"]);});it("the stored token goes only to a loopback endpoint", async () => {@@ -178,7 +221,9 @@ describe("errors and doctor", () => {error: "local_token_required",next: expect.stringContaining("ix docker start --local-token"),});- expect(localTokenRequiredError("https://ix.example.com").next).toMatch(/IX_TOKEN/);+ // A remote backend is not told to set IX_TOKEN: it would never be sent there.+ expect(localTokenRequiredError("https://ix.example.com").next).toMatch(/only to a backend on this machine/);+ expect(localTokenRequiredError("https://ix.example.com").next).toMatch(/IX_ENDPOINT/);expect(localTokenRequiredError("https://ix.example.com").next).not.toMatch(/ix docker/);});@@ -210,6 +255,11 @@ describe("errors and doctor", () => {expect(assessLocalAuth({ local_auth: "bearer-v1", local_auth_enforcing: false }, false, true)).toMatchObject({ok: true, detail: expect.stringMatching(/not required/),});+ // A remote backend asking for a token is not told to set IX_TOKEN.+ expect(assessLocalAuth(refused, false, false)).toMatchObject({+ ok: false, detail: expect.stringMatching(/only to a backend on this machine/),+ });+ expect(assessLocalAuth(refused, false, false).detail).not.toMatch(/set IX_TOKEN/);});});diff --git a/ix-cli/src/cli/commands/doctor.ts b/ix-cli/src/cli/commands/doctor.tsindex 011fdc80..c178b3ff 100644--- a/ix-cli/src/cli/commands/doctor.ts+++ b/ix-cli/src/cli/commands/doctor.ts@@ -208,6 +208,11 @@ export function checkNestedWorkspaces(};}+/** A remote backend that asks for the local token: this CLI never sends one off the machine. */+const REMOTE_TOKEN_HINT =+ "this CLI sends its token (IX_TOKEN or the stored one) only to a backend on this machine; " ++ "reach that backend through a local port forward and point IX_ENDPOINT at it";+/*** Does the backend require the local bearer token, and does this CLI have the* one it accepts? `caps` is the `/v1/capabilities` answer, or the error asking@@ -224,9 +229,9 @@ export function assessLocalAuth(ok: false,detail: sendsToken? "the backend refused this CLI's token — " +- (local ? "run 'ix docker start --local-token' to give the backend the stored one" : "check IX_TOKEN")+ (local ? "run 'ix docker start --local-token' to give the backend the stored one" : REMOTE_TOKEN_HINT): "the backend requires a token and this CLI has none — " +- (local ? "run 'ix docker start --local-token', or set IX_TOKEN" : "set IX_TOKEN"),+ (local ? "run 'ix docker start --local-token', or set IX_TOKEN" : REMOTE_TOKEN_HINT),};}if (caps instanceof Error) return { ok: true, detail: "backend unreachable (skipped)" };@@ -338,7 +343,8 @@ function doctorClient(): { endpoint: string; client: IxClient } {} catch (e) {if (!isConfigParseError(e)) throw e;// createClient read the stored token from the file that does not parse.- const token = process.env.IX_TOKEN?.trim();+ // Loopback only, as getLocalToken would have decided.+ const token = isLocalEndpoint(endpoint) ? process.env.IX_TOKEN?.trim() : undefined;// eslint-disable-next-line no-restricted-syntax -- the factory cannot build a client without config.yamlreturn { endpoint, client: new IxClient(endpoint, undefined, token ? { token } : {}) };}diff --git a/ix-cli/src/cli/commands/view.ts b/ix-cli/src/cli/commands/view.tsindex 845314f7..81f50ea5 100644--- a/ix-cli/src/cli/commands/view.ts+++ b/ix-cli/src/cli/commands/view.ts@@ -668,7 +668,7 @@ function openBrowser(url: string): void {/*** The token the visualizer's /v1 proxy sends to the backend: IX_TOKEN, else- * the stored local token (the proxy only ever talks to the local backend).+ * the stored local token, and only when that backend is on this machine.* Handed to the server through its environment, never argv.*/function viewBackendToken(): string {diff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.tsindex cf788040..49f16fff 100644--- a/ix-cli/src/cli/config.ts+++ b/ix-cli/src/cli/config.ts@@ -397,17 +397,19 @@ export function getEndpoint(): string {}/**- * The bearer token the client sends to `endpoint`, if any.+ * The bearer token the client sends to `endpoint`, if any: IX_TOKEN, else the+ * stored `auth.local_token`.*- * IX_TOKEN is the user's explicit choice and goes to whatever endpoint is- * configured. The stored `auth.local_token` belongs to the backend `ix docker`- * runs on this machine, so it is sent only to a loopback endpoint: pointing- * IX_ENDPOINT at another host must not hand that host the local credential.+ * Either goes only to a loopback endpoint. The token is the local backend's+ * (`ix docker` runs it on this machine), so pointing IX_ENDPOINT at another+ * host must not hand that host the credential. And a remote backend has its+ * own auth: Ix Pro's cloud wrapper adds the org's JWT only to a request that+ * carries no Authorization header, so a bearer set here would replace it.*/export function getLocalToken(endpoint: string = getEndpoint()): string | undefined {+ if (!isLocalEndpoint(endpoint)) return undefined;const explicit = process.env.IX_TOKEN?.trim();if (explicit) return explicit;- if (!isLocalEndpoint(endpoint)) return undefined;return storedLocalToken();}diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.tsindex d170fd5a..45402855 100644--- a/ix-cli/src/cli/errors.ts+++ b/ix-cli/src/cli/errors.ts@@ -360,7 +360,9 @@ export function localTokenRequiredError(endpoint?: string): StructuredError {message: `The Ix backend${endpoint ? ` at ${endpoint}` : ""} requires a token this CLI did not send or that it refused.`,next: isLocalEndpoint(endpoint)? "Run `ix docker start --local-token` to give the backend this CLI's stored token, or set IX_TOKEN to the backend's token."- : "Set IX_TOKEN to the token that backend was started with.",+ : "This CLI sends its token (IX_TOKEN or the stored one) only to a backend on this machine. " ++ "Reach that backend through a local port forward (for example `ssh -L 8090:localhost:8090 <host>`) " ++ "and point IX_ENDPOINT at http://localhost:8090.",};}diff --git a/skills/ix/references/troubleshooting.md b/skills/ix/references/troubleshooting.mdindex 198990f7..3abeef52 100644--- a/skills/ix/references/troubleshooting.md+++ b/skills/ix/references/troubleshooting.md@@ -31,7 +31,7 @@ again.| Symptom | Fix ||---|---|| `Ix backend not reachable` | `ix docker start`, wait, then `ix doctor` |-| `error code=local_token_required` | The backend requires a token this CLI did not send. On the local backend run `ix docker start --local-token` (gives it the CLI's stored token); for another backend set `IX_TOKEN`. `ix doctor` reports it under "Backend token" |+| `error code=local_token_required` | The backend requires a token this CLI did not send. On the local backend run `ix docker start --local-token` (gives it the CLI's stored token) or set `IX_TOKEN`. No token is ever sent to a backend on another host: forward its port to this machine and point `IX_ENDPOINT` at the loopback address. `ix doctor` reports it under "Backend token" || Docker daemon not running | Start Docker Desktop / the Docker service, then re-run bootstrap || `ix: command not found` | Re-run bootstrap (installs the CLI), or restart the shell so PATH picks up the wrapper || `The '<name>' command requires Ix Pro.` | Not installed — skip the step, do not retry or mention it again this session |