@indigoai-us/hq-cloud 6.14.48 → 6.14.49

package/src/read-only-state-dir.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Child-job authentication against a read-only HQ state directory.
+ *
+ * WHY (client report + live reproduction 2026-08-10)
+ * --------------------------------------------------
+ * "The parent runner can authenticate and reach every provider, but the skill
+ * subprocesses cannot use that machine authentication. They fall back to
+ * refreshing a human HQ session, which then fails because the job's HQ state
+ * directory is read-only."
+ *
+ * Two independent defects produced that:
+ *
+ *  1. The state dir was hardcoded to `os.homedir()/.hq` with no override, while
+ *     the CREDS path already had one (HQ_MACHINE_CREDS_FILE). So auth required
+ *     a writable HOME even for a machine identity: with valid machine creds and
+ *     a read-only `~/.hq`, `getValidMachineTokens` died on the lock candidate
+ *     write with EACCES *before any network call*.
+ *
+ *  2. A machine context that cannot find its creds does not error —
+ *     `isMachineIdentity()` returns false and the caller proceeds to the human
+ *     path, which on a headless box tries to open a browser and hangs.
+ *
+ * These tests pin the fixes: HQ_STATE_DIR redirects state, writes degrade
+ * instead of throwing, and HQ_REQUIRE_MACHINE_IDENTITY makes the downgrade loud.
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CognitoTokens } from "./cognito-auth.js";
+
+let originalHome: string | undefined;
+let originalStateDir: string | undefined;
+let originalCredsEnv: string | undefined;
+let originalRequireEnv: string | undefined;
+let tmpHome: string;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  originalStateDir = process.env.HQ_STATE_DIR;
+  originalCredsEnv = process.env.HQ_MACHINE_CREDS_FILE;
+  originalRequireEnv = process.env.HQ_REQUIRE_MACHINE_IDENTITY;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-ro-state-test-"));
+  process.env.HOME = tmpHome;
+  delete process.env.HQ_STATE_DIR;
+  delete process.env.HQ_MACHINE_CREDS_FILE;
+  delete process.env.HQ_REQUIRE_MACHINE_IDENTITY;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  const restore = (key: string, value: string | undefined): void => {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  };
+  restore("HOME", originalHome);
+  restore("HQ_STATE_DIR", originalStateDir);
+  restore("HQ_MACHINE_CREDS_FILE", originalCredsEnv);
+  restore("HQ_REQUIRE_MACHINE_IDENTITY", originalRequireEnv);
+  try {
+    fs.chmodSync(path.join(tmpHome, ".hq"), 0o700);
+  } catch {
+    /* dir may not exist */
+  }
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+const TOKENS = {
+  accessToken: "access-token-value",
+  idToken: "id-token-value",
+  refreshToken: "",
+  expiresAt: Date.now() + 3_600_000,
+  tokenType: "Bearer",
+} as const satisfies CognitoTokens;
+
+describe("HQ_STATE_DIR override", () => {
+  it("defaults to ~/.hq when unset", async () => {
+    const mod = await import("./cognito-auth.js");
+    expect(mod.hqStateDir()).toBe(path.join(tmpHome, ".hq"));
+    expect(mod.tokenCacheFile()).toBe(
+      path.join(tmpHome, ".hq", "cognito-tokens.json"),
+    );
+  });
+
+  it("redirects state to a writable dir, so a read-only HOME can still cache", async () => {
+    const writable = fs.mkdtempSync(path.join(os.tmpdir(), "hq-writable-"));
+    process.env.HQ_STATE_DIR = writable;
+    const mod = await import("./cognito-auth.js");
+
+    expect(mod.hqStateDir()).toBe(writable);
+    mod.saveCachedTokens({ ...TOKENS });
+    // Landed in the override, NOT under HOME.
+    expect(fs.existsSync(path.join(writable, "cognito-tokens.json"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpHome, ".hq", "cognito-tokens.json"))).toBe(
+      false,
+    );
+    expect(mod.loadCachedTokens()?.accessToken).toBe(TOKENS.accessToken);
+    fs.rmSync(writable, { recursive: true, force: true });
+  });
+
+  it("is read per call, so it can be set after the module loads", async () => {
+    const mod = await import("./cognito-auth.js");
+    const before = mod.hqStateDir();
+    process.env.HQ_STATE_DIR = "/tmp/hq-state-late-binding";
+    expect(mod.hqStateDir()).not.toBe(before);
+    expect(mod.hqStateDir()).toBe("/tmp/hq-state-late-binding");
+  });
+});
+
+describe("read-only state directory degrades instead of failing auth", () => {
+  it("saveCachedTokens does not throw when the state dir is not writable", async () => {
+    const stateDir = path.join(tmpHome, ".hq");
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(stateDir, 0o500); // read-only
+    const mod = await import("./cognito-auth.js");
+
+    // Previously: EACCES on the tmp write, killing the caller's auth.
+    expect(() => mod.saveCachedTokens({ ...TOKENS })).not.toThrow();
+    // Nothing persisted...
+    expect(fs.existsSync(path.join(stateDir, "cognito-tokens.json"))).toBe(false);
+    // ...but the session this process just minted is not lost.
+    expect(mod.loadCachedTokens()?.accessToken).toBe(TOKENS.accessToken);
+  });
+
+  it("still propagates a genuine write fault (not a permission problem)", async () => {
+    // A FILE where the state dir should be is a real misconfiguration (ENOTDIR),
+    // not a read-only mount — it must not be silently swallowed.
+    const asFile = path.join(tmpHome, "state-as-file");
+    fs.writeFileSync(asFile, "not a directory");
+    process.env.HQ_STATE_DIR = path.join(asFile, "nested");
+    const mod = await import("./cognito-auth.js");
+    expect(() => mod.saveCachedTokens({ ...TOKENS })).toThrow();
+  });
+});
+
+describe("HQ_REQUIRE_MACHINE_IDENTITY makes the silent downgrade loud", () => {
+  it("is off by default — human fallback stays available", async () => {
+    const mod = await import("./cognito-auth.js");
+    expect(mod.machineIdentityRequired()).toBe(false);
+    expect(() => mod.assertMachineIdentityWhenRequired()).not.toThrow();
+  });
+
+  it("throws a diagnosable error naming the path checked when creds are missing", async () => {
+    process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+    const mod = await import("./cognito-auth.js");
+    expect(mod.isMachineIdentity()).toBe(false);
+    try {
+      mod.assertMachineIdentityWhenRequired();
+      throw new Error("expected assertMachineIdentityWhenRequired to throw");
+    } catch (err) {
+      const message = (err as Error).message;
+      // Names the exact path AND how it was derived — the missing diagnosis in
+      // the original "falling back to a human session" report.
+      expect(message).toContain(".hq-agent/machine-creds.json");
+      expect(message).toContain("os.homedir()");
+      expect(message).toContain("HQ_MACHINE_CREDS_FILE");
+      expect(message).not.toContain("browser");
+    }
+  });
+
+  it("names HQ_MACHINE_CREDS_FILE as the source when it is set but unusable", async () => {
+    process.env.HQ_REQUIRE_MACHINE_IDENTITY = "true";
+    process.env.HQ_MACHINE_CREDS_FILE = path.join(tmpHome, "nope.json");
+    const mod = await import("./cognito-auth.js");
+    expect(() => mod.assertMachineIdentityWhenRequired()).toThrow(
+      /path from HQ_MACHINE_CREDS_FILE/,
+    );
+  });
+
+  it("is a no-op once machine creds ARE resolvable", async () => {
+    const credsPath = path.join(tmpHome, "machine-creds.json");
+    fs.writeFileSync(
+      credsPath,
+      JSON.stringify({
+        username: "agt-test@agents.getindigo.ai",
+        secret: "secret-value",
+        entityType: "agent",
+        entityUid: "agt_01TESTTESTTESTTESTTESTTEST",
+      }),
+    );
+    process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+    process.env.HQ_MACHINE_CREDS_FILE = credsPath;
+    const mod = await import("./cognito-auth.js");
+    expect(mod.isMachineIdentity()).toBe(true);
+    expect(() => mod.assertMachineIdentityWhenRequired()).not.toThrow();
+  });
+});