Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.md
index 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 it
ix 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.ts
index 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.ts
index 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.yaml
return { 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 |