@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/machine-auth.test.ts

@@ -1,1323 +0,0 @@
-/**
- * Unit tests for the machine-identity auth mode in cognito-auth.ts.
- *
- * Machine identities (company agents) carry long-lived Cognito creds at
- * ~/.hq-agent/machine-creds.json (HQ_MACHINE_CREDS_FILE override) and mint
- * sessions via USER_PASSWORD_AUTH on demand — no browser, no refresh token.
- * The contract under test:
- *   - detection: creds file present + well-formed → machine mode
- *   - minting: BOTH tokens cached with correct field semantics
- *   - re-mint on expiry; cache hit when valid
- *   - getValidAccessToken short-circuits into machine mode (never browser)
- */
-
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { spawn } from "child_process";
-import { pathToFileURL } from "url";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-let originalHome: string | undefined;
-let originalUserProfile: string | undefined;
-let originalCredsEnv: string | undefined;
-let tmpHome: string;
-
-beforeEach(() => {
-  originalHome = process.env.HOME;
-  originalUserProfile = process.env.USERPROFILE;
-  originalCredsEnv = process.env.HQ_MACHINE_CREDS_FILE;
-  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-machine-auth-test-"));
-  process.env.HOME = tmpHome;
-  process.env.USERPROFILE = tmpHome;
-  delete process.env.HQ_MACHINE_CREDS_FILE;
-  vi.resetModules();
-});
-
-afterEach(() => {
-  vi.useRealTimers();
-  if (originalHome === undefined) delete process.env.HOME;
-  else process.env.HOME = originalHome;
-  if (originalUserProfile === undefined) delete process.env.USERPROFILE;
-  else process.env.USERPROFILE = originalUserProfile;
-  if (originalCredsEnv === undefined) delete process.env.HQ_MACHINE_CREDS_FILE;
-  else process.env.HQ_MACHINE_CREDS_FILE = originalCredsEnv;
-  fs.rmSync(tmpHome, { recursive: true, force: true });
-  vi.unstubAllGlobals();
-  vi.restoreAllMocks();
-});
-
-async function importModule() {
-  return await import("./cognito-auth.js");
-}
-
-const CONFIG = {
-  region: "us-east-1",
-  userPoolDomain: "vault-indigo-hq-prod",
-  clientId: "test-client-id",
-};
-
-function writeCreds(
-  creds: unknown = { username: "machine-agt_01TEST", secret: "s3cret" },
-): string {
-  const dir = path.join(tmpHome, ".hq-agent");
-  fs.mkdirSync(dir, { recursive: true });
-  const file = path.join(dir, "machine-creds.json");
-  fs.writeFileSync(file, JSON.stringify(creds));
-  return file;
-}
-
-/** Build a fake JWT whose payload decodes to the given claims. */
-function fakeJwt(claims: Record<string, unknown>): string {
-  const enc = (o: unknown) =>
-    Buffer.from(JSON.stringify(o)).toString("base64url");
-  return `${enc({ alg: "RS256", kid: "k" })}.${enc(claims)}.sig`;
-}
-
-function stubMintFetch(
-  overrides: Partial<{
-    AccessToken: string;
-    IdToken: string;
-    RefreshToken: string;
-    ExpiresIn: number;
-  }> = {},
-) {
-  const calls: Array<{ url: string; init: RequestInit }> = [];
-  const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {
-    calls.push({ url: String(url), init: init ?? {} });
-    const body = JSON.parse(String(init?.body)) as {
-      ClientId: string;
-      AuthParameters: { USERNAME: string };
-    };
-    const credsFile =
-      process.env.HQ_MACHINE_CREDS_FILE ??
-      path.join(tmpHome, ".hq-agent", "machine-creds.json");
-    const creds = JSON.parse(fs.readFileSync(credsFile, "utf-8")) as {
-      entityType?: "agent" | "outpost";
-      entityUid?: string;
-    };
-    const username = body.AuthParameters.USERNAME;
-    const subject = `sub:${username}`;
-    const entityType = creds.entityType ?? "agent";
-    const entityUid = creds.entityUid ?? "agt_01TEST";
-    return new Response(
-      JSON.stringify({
-        AuthenticationResult: {
-          AccessToken:
-            overrides.AccessToken ??
-            fakeJwt({
-              token_use: "access",
-              client_id: body.ClientId,
-              username,
-              sub: subject,
-            }),
-          IdToken:
-            overrides.IdToken ??
-            fakeJwt({
-              token_use: "id",
-              aud: body.ClientId,
-              "custom:entityType": entityType,
-              "custom:entityUid": entityUid,
-              ...(entityType === "outpost"
-                ? {
-                    "custom:delegatedSub": "human-sub",
-                    "custom:delegatedEmail": "owner@example.com",
-                  }
-                : {}),
-              "cognito:username": username,
-              sub: subject,
-            }),
-          RefreshToken: overrides.RefreshToken,
-          ExpiresIn: overrides.ExpiresIn ?? 3600,
-        },
-      }),
-      { status: 200 },
-    );
-  });
-  vi.stubGlobal("fetch", fetchMock);
-  return { fetchMock, calls };
-}
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-describe("machine identity detection", () => {
-  it("is off when no creds file exists", async () => {
-    const { isMachineIdentity, loadMachineCreds } = await importModule();
-    expect(loadMachineCreds()).toBeNull();
-    expect(isMachineIdentity()).toBe(false);
-  });
-
-  it("detects creds at the default ~/.hq-agent path", async () => {
-    writeCreds();
-    const { isMachineIdentity, loadMachineCreds } = await importModule();
-    expect(loadMachineCreds()).toEqual({
-      username: "machine-agt_01TEST",
-      secret: "s3cret",
-      clientId: undefined,
-      region: undefined,
-    });
-    expect(isMachineIdentity()).toBe(true);
-  });
-
-  it("detects provisioned-shape creds (agt-<ulid>@agents domain + clientId/region)", async () => {
-    writeCreds({
-      username: "agt-01ktt1rjj6kqrhnhhst0k4vrgt@agents.getindigo.ai",
-      secret: "s3cret",
-      clientId: "agent-client-1",
-      region: "us-east-1",
-      userPoolId: "us-east-1_pool",
-    });
-    const { isMachineIdentity, loadMachineCreds } = await importModule();
-    expect(loadMachineCreds()).toEqual({
-      username: "agt-01ktt1rjj6kqrhnhhst0k4vrgt@agents.getindigo.ai",
-      secret: "s3cret",
-      clientId: "agent-client-1",
-      region: "us-east-1",
-    });
-    expect(isMachineIdentity()).toBe(true);
-  });
-
-  it("parses the expected machine entity type and uid from provisioned creds", async () => {
-    writeCreds({
-      username: "out-01test@outposts.getindigo.ai",
-      secret: "s3cret",
-      clientId: "outpost-client-1",
-      region: "us-east-1",
-      entityType: "outpost",
-      entityUid: "out_01TEST",
-    });
-    const { loadMachineCreds } = await importModule();
-
-    expect(loadMachineCreds()).toEqual({
-      username: "out-01test@outposts.getindigo.ai",
-      secret: "s3cret",
-      clientId: "outpost-client-1",
-      region: "us-east-1",
-      entityType: "outpost",
-      entityUid: "out_01TEST",
-    });
-  });
-
-  it("honors HQ_MACHINE_CREDS_FILE override", async () => {
-    const custom = path.join(tmpHome, "elsewhere.json");
-    fs.writeFileSync(
-      custom,
-      JSON.stringify({ username: "machine-agt_X", secret: "y" }),
-    );
-    process.env.HQ_MACHINE_CREDS_FILE = custom;
-    const { loadMachineCreds, machineCredsFilePath } = await importModule();
-    expect(machineCredsFilePath()).toBe(custom);
-    expect(loadMachineCreds()?.username).toBe("machine-agt_X");
-  });
-
-  it("rejects malformed creds (missing secret, empty username, bad JSON)", async () => {
-    const { loadMachineCreds } = await importModule();
-    writeCreds({ username: "", secret: "x" });
-    expect(loadMachineCreds()).toBeNull();
-    writeCreds({ username: "machine-agt_01TEST" });
-    expect(loadMachineCreds()).toBeNull();
-    fs.writeFileSync(path.join(tmpHome, ".hq-agent", "machine-creds.json"), "{nope");
-    expect(loadMachineCreds()).toBeNull();
-  });
-
-  it.each([
-    { entityType: "agent", entityUid: "out_WRONG" },
-    { entityType: "outpost", entityUid: "agt_WRONG" },
-    { entityType: "agent", entityUid: "garbage" },
-    { entityType: "agent" },
-    { entityType: "outpost" },
-    { entityUid: "out_NO_TYPE" },
-    { entityUid: "garbage" },
-    { entityType: "agent", entityUid: "agt_" },
-    { entityType: "outpost", entityUid: "out_" },
-  ])("rejects malformed or cross-prefix entity metadata: %j", async (identity) => {
-    writeCreds({ username: "machine", secret: "secret", ...identity });
-    const { loadMachineCreds } = await importModule();
-
-    expect(loadMachineCreds()).toBeNull();
-  });
-
-  it("accepts an agt_* uid without a type as the legacy agent inference", async () => {
-    writeCreds({
-      username: "machine-agt_01TEST",
-      secret: "secret",
-      entityUid: "agt_01TEST",
-    });
-    const { loadMachineCreds } = await importModule();
-
-    expect(loadMachineCreds()).toMatchObject({ entityUid: "agt_01TEST" });
-    expect(loadMachineCreds()?.entityType).toBeUndefined();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Minting
-// ---------------------------------------------------------------------------
-
-describe("mintMachineTokens", () => {
-  it("prefers the creds file's clientId/region over config (agent app client has USER_PASSWORD_AUTH)", async () => {
-    writeCreds({
-      username: "agt-01ktt1rjj6kqrhnhhst0k4vrgt@agents.getindigo.ai",
-      secret: "s3cret",
-      clientId: "agent-client-1",
-      region: "eu-west-1",
-    });
-    const { calls } = stubMintFetch();
-    const { mintMachineTokens } = await importModule();
-    await mintMachineTokens(CONFIG);
-    expect(calls[0].url).toBe("https://cognito-idp.eu-west-1.amazonaws.com/");
-    const body = JSON.parse(String(calls[0].init.body));
-    expect(body.ClientId).toBe("agent-client-1");
-  });
-
-  it("mints via USER_PASSWORD_AUTH and caches both tokens with correct fields", async () => {
-    writeCreds();
-    const { calls } = stubMintFetch({ RefreshToken: "rt" });
-    const { mintMachineTokens, loadCachedTokens } = await importModule();
-
-    const tokens = await mintMachineTokens(CONFIG);
-
-    // Request shape: Cognito IDP InitiateAuth with the machine creds.
-    expect(calls).toHaveLength(1);
-    expect(calls[0].url).toBe("https://cognito-idp.us-east-1.amazonaws.com/");
-    const body = JSON.parse(String(calls[0].init.body));
-    expect(body).toMatchObject({
-      AuthFlow: "USER_PASSWORD_AUTH",
-      ClientId: CONFIG.clientId,
-      AuthParameters: { USERNAME: "machine-agt_01TEST", PASSWORD: "s3cret" },
-    });
-
-    // Field semantics: access token in accessToken, id token in idToken.
-    const accessClaims = JSON.parse(
-      Buffer.from(tokens.accessToken.split(".")[1], "base64url").toString(),
-    );
-    const idClaims = JSON.parse(
-      Buffer.from(tokens.idToken.split(".")[1], "base64url").toString(),
-    );
-    expect(accessClaims.token_use).toBe("access");
-    expect(idClaims.token_use).toBe("id");
-    expect(tokens.refreshToken).toBe("");
-    expect(typeof tokens.expiresAt).toBe("number");
-
-    // Persisted to the shared cache file.
-    expect(loadCachedTokens()).toEqual(tokens);
-  });
-
-  it("throws CognitoAuthError on auth failure", async () => {
-    writeCreds();
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () =>
-        new Response(
-          JSON.stringify({ __type: "NotAuthorizedException", message: "nope" }),
-          { status: 400 },
-        ),
-      ),
-    );
-    const { mintMachineTokens, CognitoAuthError } = await importModule();
-    await expect(mintMachineTokens(CONFIG)).rejects.toBeInstanceOf(
-      CognitoAuthError,
-    );
-    expect(
-      fs.existsSync(path.join(tmpHome, ".hq", "cognito-tokens.json.lock")),
-    ).toBe(false);
-
-    stubMintFetch();
-    await expect(mintMachineTokens(CONFIG)).resolves.toBeDefined();
-  });
-
-  it("throws when no creds are present", async () => {
-    const { mintMachineTokens, CognitoAuthError } = await importModule();
-    await expect(mintMachineTokens(CONFIG)).rejects.toBeInstanceOf(
-      CognitoAuthError,
-    );
-  });
-
-  it.each([
-    ["wrong entity type", { "custom:entityType": "agent", "custom:entityUid": "agt_OTHER" }],
-    ["wrong entity uid", { "custom:entityUid": "out_OTHER" }],
-    ["absent delegatedSub", { "custom:delegatedSub": undefined }],
-    ["empty delegatedSub", { "custom:delegatedSub": "" }],
-    ["non-string delegatedSub", { "custom:delegatedSub": 42 }],
-    ["absent delegatedEmail", { "custom:delegatedEmail": undefined }],
-    ["empty delegatedEmail", { "custom:delegatedEmail": "" }],
-    ["non-string delegatedEmail", { "custom:delegatedEmail": 42 }],
-  ] as const)(
-    "rejects and does not cache a first mint with %s",
-    async (_label, claimOverride) => {
-      const username = "out-01test@outposts.getindigo.ai";
-      writeCreds({
-        username,
-        secret: "outpost-secret",
-        entityType: "outpost",
-        entityUid: "out_01TEST",
-      });
-      const claims: Record<string, unknown> = {
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "outpost",
-        "custom:entityUid": "out_01TEST",
-        "custom:delegatedSub": "human-sub",
-        "custom:delegatedEmail": "owner@example.com",
-        "cognito:username": username,
-        sub: "machine-sub",
-        ...claimOverride,
-      };
-      for (const [key, value] of Object.entries(claims)) {
-        if (value === undefined) delete claims[key];
-      }
-      stubMintFetch({
-        AccessToken: fakeJwt({
-          token_use: "access",
-          client_id: CONFIG.clientId,
-          username,
-          sub: "machine-sub",
-        }),
-        IdToken: fakeJwt(claims),
-      });
-      const { mintMachineTokens, loadCachedTokens, CognitoAuthError } =
-        await importModule();
-
-      await expect(mintMachineTokens(CONFIG)).rejects.toBeInstanceOf(
-        CognitoAuthError,
-      );
-      expect(loadCachedTokens()).toBeNull();
-    },
-  );
-});
-
-// ---------------------------------------------------------------------------
-// getValidMachineTokens — cache vs re-mint
-// ---------------------------------------------------------------------------
-
-describe("getValidMachineTokens", () => {
-  it("returns the cache when valid without touching the network", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const { saveCachedTokens, getValidMachineTokens } = await importModule();
-    // A valid machine cache must prove this exact agent identity (F06): the
-    // cached tokens carry the agent claims that distinguish a machine token
-    // from a same-client human token, so cache reuse is safe and skips the wire.
-    const cached = {
-      accessToken: fakeJwt({
-        token_use: "access",
-        client_id: CONFIG.clientId,
-        username: "machine-agt_01TEST",
-      }),
-      idToken: fakeJwt({
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "agent",
-        "custom:entityUid": "agt_01TEST",
-        "cognito:username": "machine-agt_01TEST",
-      }),
-      refreshToken: "",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer" as const,
-    };
-    saveCachedTokens(cached);
-
-    const tokens = await getValidMachineTokens(CONFIG);
-    expect(tokens).toEqual(cached);
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("strips and persists an empty refresh token when reusing a machine cache", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const { saveCachedTokens, loadCachedTokens, getValidMachineTokens } =
-      await importModule();
-    saveCachedTokens({
-      accessToken: fakeJwt({
-        token_use: "access",
-        client_id: CONFIG.clientId,
-        username: "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      idToken: fakeJwt({
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "agent",
-        "custom:entityUid": "agt_01TEST",
-        "cognito:username": "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      refreshToken: "legacy-machine-refresh-token",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer",
-    });
-
-    const tokens = await getValidMachineTokens(CONFIG);
-
-    expect(tokens.refreshToken).toBe("");
-    expect(loadCachedTokens()?.refreshToken).toBe("");
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("re-mints when the cache is expiring", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const { saveCachedTokens, getValidMachineTokens } = await importModule();
-    saveCachedTokens({
-      accessToken: fakeJwt({ token_use: "access", client_id: CONFIG.clientId }),
-      idToken: fakeJwt({ token_use: "id" }),
-      refreshToken: "",
-      expiresAt: Date.now() + 10 * 1000,
-      tokenType: "Bearer",
-    });
-
-    await getValidMachineTokens(CONFIG);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-  });
-
-  it("re-mints when the cached token targets a different app client", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const { saveCachedTokens, getValidMachineTokens } = await importModule();
-    saveCachedTokens({
-      accessToken: fakeJwt({ token_use: "access", client_id: "other-client" }),
-      idToken: fakeJwt({ token_use: "id" }),
-      refreshToken: "",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer",
-    });
-
-    await getValidMachineTokens(CONFIG);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-  });
-
-  it("R-F06: re-mints when cached access and ID tokens belong to different agents", async () => {
-    writeCreds();
-    const freshAccess = fakeJwt({
-      token_use: "access",
-      client_id: CONFIG.clientId,
-      username: "machine-agt_01TEST",
-      sub: "sub-agent-1",
-    });
-    const freshId = fakeJwt({
-      token_use: "id",
-      aud: CONFIG.clientId,
-      "custom:entityType": "agent",
-      "custom:entityUid": "agt_01TEST",
-      "cognito:username": "machine-agt_01TEST",
-      sub: "sub-agent-1",
-    });
-    const { fetchMock } = stubMintFetch({
-      AccessToken: freshAccess,
-      IdToken: freshId,
-    });
-    const { saveCachedTokens, getValidAccessToken, loadCachedTokens } =
-      await importModule();
-    saveCachedTokens({
-      accessToken: fakeJwt({
-        token_use: "access",
-        client_id: CONFIG.clientId,
-        username: "machine-agt_01TEST",
-        sub: "sub-agent-1",
-      }),
-      idToken: fakeJwt({
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "agent",
-        "custom:entityUid": "agt_OTHER",
-        "cognito:username": "machine-agt_OTHER",
-        sub: "sub-agent-2",
-      }),
-      refreshToken: "",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer",
-    });
-
-    const token = await getValidAccessToken(CONFIG, { interactive: false });
-
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    expect(token).toBe(freshId);
-    expect(loadCachedTokens()?.idToken).toBe(freshId);
-  });
-
-  it("accepts an Outpost machine cache with delegated claims, then re-mints after expiry without OAuth refresh", async () => {
-    const username = "out-01test@outposts.getindigo.ai";
-    const entityUid = "out_01TEST";
-    writeCreds({
-      username,
-      secret: "outpost-secret",
-      clientId: CONFIG.clientId,
-      region: CONFIG.region,
-      entityType: "outpost",
-      entityUid,
-    });
-    const accessToken = fakeJwt({
-      token_use: "access",
-      client_id: CONFIG.clientId,
-      username,
-      sub: "machine-sub",
-    });
-    const idToken = fakeJwt({
-      token_use: "id",
-      aud: CONFIG.clientId,
-      "custom:entityType": "outpost",
-      "custom:entityUid": entityUid,
-      "custom:delegatedSub": "human-sub",
-      "custom:delegatedEmail": "owner@example.com",
-      "cognito:username": username,
-      sub: "machine-sub",
-    });
-    const { fetchMock, calls } = stubMintFetch({
-      AccessToken: accessToken,
-      IdToken: idToken,
-      RefreshToken: "must-not-be-stored",
-    });
-
-    const firstModule = await importModule();
-    const first = await firstModule.getValidMachineTokens(CONFIG);
-    expect(first.idToken).toBe(idToken);
-    expect(firstModule.loadCachedTokens()?.refreshToken).toBe("");
-
-    // A new process accepts the shared Outpost cache without another mint.
-    vi.resetModules();
-    const cacheHitModule = await importModule();
-    await expect(cacheHitModule.getValidMachineTokens(CONFIG)).resolves.toEqual(
-      first,
-    );
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-
-    // Once expired, a new process re-mints with the permanent secret. It never
-    // attempts the browser client's /oauth2/token refresh-token flow.
-    cacheHitModule.saveCachedTokens({
-      ...first,
-      expiresAt: Date.now() - 1,
-    });
-    vi.resetModules();
-    const expiredModule = await importModule();
-    await expiredModule.getValidMachineTokens(CONFIG);
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(calls.every(({ url }) => !url.includes("/oauth2/token"))).toBe(true);
-    for (const { init } of calls) {
-      const body = JSON.parse(String(init.body));
-      expect(body).toMatchObject({
-        AuthFlow: "USER_PASSWORD_AUTH",
-        ClientId: CONFIG.clientId,
-        AuthParameters: { USERNAME: username, PASSWORD: "outpost-secret" },
-      });
-    }
-    expect(expiredModule.loadCachedTokens()?.refreshToken).toBe("");
-  });
-
-  it.each([
-    [
-      "entity type",
-      { entityType: "outpost", entityUid: "out_01TEST" },
-      "agent",
-      "agt_01TEST",
-    ],
-    [
-      "entity uid",
-      { entityType: "outpost", entityUid: "out_01TEST" },
-      "outpost",
-      "out_OTHER",
-    ],
-  ] as const)(
-    "re-mints when the cached machine %s does not match the creds",
-    async (_label, expectedIdentity, cachedEntityType, cachedEntityUid) => {
-      const username = "out-01test@outposts.getindigo.ai";
-      writeCreds({
-        username,
-        secret: "outpost-secret",
-        ...expectedIdentity,
-      });
-      const { fetchMock } = stubMintFetch();
-      const { saveCachedTokens, getValidMachineTokens } = await importModule();
-      saveCachedTokens({
-        accessToken: fakeJwt({
-          token_use: "access",
-          client_id: CONFIG.clientId,
-          username,
-          sub: "machine-sub",
-        }),
-        idToken: fakeJwt({
-          token_use: "id",
-          aud: CONFIG.clientId,
-          "custom:entityType": cachedEntityType,
-          "custom:entityUid": cachedEntityUid,
-          "custom:delegatedSub": "human-sub",
-          "custom:delegatedEmail": "owner@example.com",
-          "cognito:username": username,
-          sub: "machine-sub",
-        }),
-        refreshToken: "",
-        expiresAt: Date.now() + 30 * 60 * 1000,
-        tokenType: "Bearer",
-      });
-
-      await getValidMachineTokens(CONFIG);
-
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-    },
-  );
-
-  it.each(["custom:delegatedSub", "custom:delegatedEmail"])(
-    "re-mints when an Outpost cache is missing %s",
-    async (missingClaim) => {
-      const username = "out-01test@outposts.getindigo.ai";
-      const outpostClaims: Record<string, unknown> = {
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "outpost",
-        "custom:entityUid": "out_01TEST",
-        "custom:delegatedSub": "human-sub",
-        "custom:delegatedEmail": "owner@example.com",
-        "cognito:username": username,
-        sub: "machine-sub",
-      };
-      delete outpostClaims[missingClaim];
-      writeCreds({
-        username,
-        secret: "outpost-secret",
-        entityType: "outpost",
-        entityUid: "out_01TEST",
-      });
-      const { fetchMock } = stubMintFetch();
-      const { saveCachedTokens, getValidMachineTokens } = await importModule();
-      saveCachedTokens({
-        accessToken: fakeJwt({
-          token_use: "access",
-          client_id: CONFIG.clientId,
-          username,
-          sub: "machine-sub",
-        }),
-        idToken: fakeJwt(outpostClaims),
-        refreshToken: "",
-        expiresAt: Date.now() + 30 * 60 * 1000,
-        tokenType: "Bearer",
-      });
-
-      await getValidMachineTokens(CONFIG);
-
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-    },
-  );
-
-  it("keeps accepting legacy agent creds without entity fields", async () => {
-    writeCreds({ username: "machine-agt_01TEST", secret: "s3cret" });
-    const { fetchMock } = stubMintFetch();
-    const { saveCachedTokens, getValidMachineTokens } = await importModule();
-    const cached = {
-      accessToken: fakeJwt({
-        token_use: "access",
-        client_id: CONFIG.clientId,
-        username: "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      idToken: fakeJwt({
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "agent",
-        "custom:entityUid": "agt_01TEST",
-        "cognito:username": "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      refreshToken: "",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer" as const,
-    };
-    saveCachedTokens(cached);
-
-    await expect(getValidMachineTokens(CONFIG)).resolves.toEqual(cached);
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("invalidates the memo after the creds file is reprovisioned", async () => {
-    writeCreds({
-      username: "machine-a",
-      secret: "secret-a",
-      entityType: "agent",
-      entityUid: "agt_A",
-    });
-    const { fetchMock } = stubMintFetch();
-    const { getValidMachineTokens } = await importModule();
-
-    const first = await getValidMachineTokens(CONFIG);
-    writeCreds({
-      username: "machine-b",
-      secret: "secret-b",
-      entityType: "outpost",
-      entityUid: "out_B",
-    });
-    const second = await getValidMachineTokens(CONFIG);
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(first.idToken).not.toBe(second.idToken);
-    expect(
-      JSON.parse(
-        Buffer.from(second.idToken.split(".")[1], "base64url").toString(),
-      )["custom:entityUid"],
-    ).toBe("out_B");
-  });
-
-  it("invalidates the memo when legacy creds use a different config client", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const { getValidMachineTokens } = await importModule();
-    const otherConfig = { ...CONFIG, clientId: "other-client-id" };
-
-    const first = await getValidMachineTokens(CONFIG);
-    const second = await getValidMachineTokens(otherConfig);
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(first.idToken).not.toBe(second.idToken);
-    expect(
-      JSON.parse(
-        Buffer.from(second.idToken.split(".")[1], "base64url").toString(),
-      ).aud,
-    ).toBe(otherConfig.clientId);
-  });
-
-  it("does not attach a reprovisioned identity to the previous identity's in-flight mint", async () => {
-    writeCreds({
-      username: "machine-a",
-      secret: "secret-a",
-      entityType: "agent",
-      entityUid: "agt_A",
-    });
-    let releaseFirstMint: (() => void) | undefined;
-    const firstMintGate = new Promise<void>((resolve) => {
-      releaseFirstMint = resolve;
-    });
-    let signalFirstMint: (() => void) | undefined;
-    const firstMintStarted = new Promise<void>((resolve) => {
-      signalFirstMint = resolve;
-    });
-    let callCount = 0;
-    const fetchMock = vi.fn(async (_url: string | URL, init?: RequestInit) => {
-      callCount += 1;
-      const body = JSON.parse(String(init?.body)) as {
-        ClientId: string;
-        AuthParameters: { USERNAME: string };
-      };
-      if (callCount === 1) {
-        signalFirstMint?.();
-        await firstMintGate;
-      }
-      const username = body.AuthParameters.USERNAME;
-      const uid = username === "machine-a" ? "agt_A" : "agt_B";
-      return new Response(
-        JSON.stringify({
-          AuthenticationResult: {
-            AccessToken: fakeJwt({
-              token_use: "access",
-              client_id: body.ClientId,
-              username,
-              sub: `sub:${username}`,
-            }),
-            IdToken: fakeJwt({
-              token_use: "id",
-              aud: body.ClientId,
-              "custom:entityType": "agent",
-              "custom:entityUid": uid,
-              "cognito:username": username,
-              sub: `sub:${username}`,
-            }),
-            ExpiresIn: 3600,
-          },
-        }),
-        { status: 200 },
-      );
-    });
-    vi.stubGlobal("fetch", fetchMock);
-    const { getValidMachineTokens } = await importModule();
-
-    const first = getValidMachineTokens(CONFIG);
-    await firstMintStarted;
-    writeCreds({
-      username: "machine-b",
-      secret: "secret-b",
-      entityType: "agent",
-      entityUid: "agt_B",
-    });
-    const second = getValidMachineTokens(CONFIG);
-    releaseFirstMint?.();
-
-    const [firstTokens, secondTokens] = await Promise.all([first, second]);
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(firstTokens.idToken).not.toBe(secondTokens.idToken);
-    expect(
-      JSON.parse(
-        Buffer.from(secondTokens.idToken.split(".")[1], "base64url").toString(),
-      )["custom:entityUid"],
-    ).toBe("agt_B");
-  });
-
-  it("reuses only an empty-refresh matching cache after a lock timeout", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const { saveCachedTokens, getValidMachineTokens } = await importModule();
-    const cached = {
-      accessToken: fakeJwt({
-        token_use: "access",
-        client_id: CONFIG.clientId,
-        username: "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      idToken: fakeJwt({
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "agent",
-        "custom:entityUid": "agt_01TEST",
-        "cognito:username": "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      refreshToken: "",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer" as const,
-    };
-    saveCachedTokens(cached);
-    fs.writeFileSync(
-      path.join(tmpHome, ".hq", "cognito-tokens.json.lock"),
-      String(process.pid),
-    );
-    vi.useFakeTimers();
-
-    const resolution = getValidMachineTokens(CONFIG);
-    await vi.advanceTimersByTimeAsync(20_050);
-
-    await expect(resolution).resolves.toEqual(cached);
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("rejects a legacy non-empty-refresh cache after a lock timeout without minting unlocked", async () => {
-    writeCreds();
-    const { fetchMock } = stubMintFetch();
-    const {
-      saveCachedTokens,
-      getValidMachineTokens,
-      CognitoAuthError,
-    } = await importModule();
-    saveCachedTokens({
-      accessToken: fakeJwt({
-        token_use: "access",
-        client_id: CONFIG.clientId,
-        username: "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      idToken: fakeJwt({
-        token_use: "id",
-        aud: CONFIG.clientId,
-        "custom:entityType": "agent",
-        "custom:entityUid": "agt_01TEST",
-        "cognito:username": "machine-agt_01TEST",
-        sub: "machine-sub",
-      }),
-      refreshToken: "legacy-refresh",
-      expiresAt: Date.now() + 30 * 60 * 1000,
-      tokenType: "Bearer",
-    });
-    fs.writeFileSync(
-      path.join(tmpHome, ".hq", "cognito-tokens.json.lock"),
-      String(process.pid),
-    );
-    vi.useFakeTimers();
-
-    const resolution = getValidMachineTokens(CONFIG);
-    const rejection = expect(resolution).rejects.toBeInstanceOf(
-      CognitoAuthError,
-    );
-    await vi.advanceTimersByTimeAsync(20_050);
-
-    await rejection;
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Regression: constant token mints over N files (sync-runner mint storm)
-// ---------------------------------------------------------------------------
-//
-// `getValidAccessToken` (→ getValidMachineTokens) is invoked on EVERY vault
-// request a sync makes, including the per-file tombstone HEAD verifies. The
-// 2026-06-26 prod incident was 56 throttled USER_PASSWORD_AUTH mints over 314
-// files on one box: with no in-process memo + single-flight, mints scaled with
-// request count and tripped Cognito's per-user limit. These lock the invariant
-// that mints are O(1) per process, independent of N.
-
-describe("regression: constant mints regardless of file count", () => {
-  it.each([10, 300])(
-    "performs exactly ONE token mint across %i sequential file-verify requests",
-    async (n) => {
-      writeCreds();
-      const { fetchMock } = stubMintFetch();
-      const { getValidMachineTokens } = await importModule();
-
-      for (let i = 0; i < n; i++) {
-        await getValidMachineTokens(CONFIG);
-      }
-
-      // One mint for N requests — NOT proportional to N. The first call mints;
-      // every later call is served by the in-process memo (no network).
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-    },
-  );
-
-  it.each([10, 300])(
-    "collapses a concurrent burst of %i requests onto a SINGLE mint (single-flight)",
-    async (n) => {
-      writeCreds();
-      const { fetchMock } = stubMintFetch();
-      const { getValidMachineTokens } = await importModule();
-
-      // Fire all N at once, as the run-start fan-out does. Without single-flight
-      // every concurrent miss would mint and burst the per-user limit.
-      const results = await Promise.all(
-        Array.from({ length: n }, () => getValidMachineTokens(CONFIG)),
-      );
-
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-      // All callers observe the same token.
-      for (const r of results) expect(r).toEqual(results[0]);
-
-      // Follow-up sequential requests stay on the memo — still one mint total.
-      await getValidMachineTokens(CONFIG);
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-    },
-  );
-
-  it("serializes independent module instances through the shared cache lock", async () => {
-    const username = "machine-agt_01TEST";
-    writeCreds({
-      username,
-      secret: "s3cret",
-      entityType: "agent",
-      entityUid: "agt_01TEST",
-    });
-    let releaseMint: (() => void) | undefined;
-    const mintGate = new Promise<void>((resolve) => {
-      releaseMint = resolve;
-    });
-    let signalMintStarted: (() => void) | undefined;
-    const mintStarted = new Promise<void>((resolve) => {
-      signalMintStarted = resolve;
-    });
-    const accessToken = fakeJwt({
-      token_use: "access",
-      client_id: CONFIG.clientId,
-      username,
-      sub: "machine-sub",
-    });
-    const idToken = fakeJwt({
-      token_use: "id",
-      aud: CONFIG.clientId,
-      "custom:entityType": "agent",
-      "custom:entityUid": "agt_01TEST",
-      "cognito:username": username,
-      sub: "machine-sub",
-    });
-    const fetchMock = vi.fn(async () => {
-      signalMintStarted?.();
-      await mintGate;
-      return new Response(
-        JSON.stringify({
-          AuthenticationResult: {
-            AccessToken: accessToken,
-            IdToken: idToken,
-            RefreshToken: "must-not-be-stored",
-            ExpiresIn: 3600,
-          },
-        }),
-        { status: 200 },
-      );
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const firstProcessModule = await importModule();
-    vi.resetModules();
-    const secondProcessModule = await importModule();
-
-    const first = firstProcessModule.getValidMachineTokens(CONFIG);
-    await mintStarted;
-    const second = secondProcessModule.getValidMachineTokens(CONFIG);
-    releaseMint?.();
-
-    const [firstTokens, secondTokens] = await Promise.all([first, second]);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    expect(secondTokens).toEqual(firstTokens);
-    expect(secondProcessModule.loadCachedTokens()?.refreshToken).toBe("");
-  });
-
-  it("serializes the exported direct mint API", async () => {
-    writeCreds();
-    let releaseFirstMint: (() => void) | undefined;
-    const firstMintGate = new Promise<void>((resolve) => {
-      releaseFirstMint = resolve;
-    });
-    let signalFirstMint: (() => void) | undefined;
-    const firstMintStarted = new Promise<void>((resolve) => {
-      signalFirstMint = resolve;
-    });
-    let activeMints = 0;
-    let maxActiveMints = 0;
-    let callCount = 0;
-    const accessToken = fakeJwt({
-      token_use: "access",
-      client_id: CONFIG.clientId,
-      username: "machine-agt_01TEST",
-      sub: "machine-sub",
-    });
-    const idToken = fakeJwt({
-      token_use: "id",
-      aud: CONFIG.clientId,
-      "custom:entityType": "agent",
-      "custom:entityUid": "agt_01TEST",
-      "cognito:username": "machine-agt_01TEST",
-      sub: "machine-sub",
-    });
-    const fetchMock = vi.fn(async () => {
-      callCount += 1;
-      activeMints += 1;
-      maxActiveMints = Math.max(maxActiveMints, activeMints);
-      if (callCount === 1) {
-        signalFirstMint?.();
-        await firstMintGate;
-      }
-      activeMints -= 1;
-      return new Response(
-        JSON.stringify({
-          AuthenticationResult: {
-            AccessToken: accessToken,
-            IdToken: idToken,
-            ExpiresIn: 3600,
-          },
-        }),
-        { status: 200 },
-      );
-    });
-    vi.stubGlobal("fetch", fetchMock);
-    const firstModule = await importModule();
-    vi.resetModules();
-    const secondModule = await importModule();
-
-    const first = firstModule.mintMachineTokens(CONFIG);
-    await firstMintStarted;
-    const second = secondModule.mintMachineTokens(CONFIG);
-    releaseFirstMint?.();
-    await Promise.all([first, second]);
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(maxActiveMints).toBe(1);
-  });
-
-  it("serializes direct mints in actual separate processes", async () => {
-    const moduleUrl = pathToFileURL(
-      path.join(process.cwd(), "src", "cognito-auth.ts"),
-    ).href;
-    const marker = path.join(tmpHome, "mint-active");
-    const overlap = path.join(tmpHome, "mint-overlap");
-    const start = path.join(tmpHome, "mint-start");
-    const childScript = String.raw`
-      import fs from "fs";
-      const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-      const fakeJwt = (claims) => {
-        const enc = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
-        return enc({ alg: "none" }) + "." + enc(claims) + ".sig";
-      };
-      const auth = await import(process.env.HQ_LOCK_TEST_MODULE_URL);
-      fs.writeFileSync(process.env.HQ_LOCK_TEST_READY, "ready");
-      while (!fs.existsSync(process.env.HQ_LOCK_TEST_START)) await pause(5);
-      globalThis.fetch = async () => {
-        let ownsMarker = false;
-        try {
-          const fd = fs.openSync(process.env.HQ_LOCK_TEST_MARKER, "wx");
-          fs.closeSync(fd);
-          ownsMarker = true;
-        } catch (error) {
-          if (error.code === "EEXIST") {
-            fs.writeFileSync(process.env.HQ_LOCK_TEST_OVERLAP, "overlap");
-          } else {
-            throw error;
-          }
-        }
-        await pause(125);
-        if (ownsMarker) fs.unlinkSync(process.env.HQ_LOCK_TEST_MARKER);
-        return new Response(JSON.stringify({ AuthenticationResult: {
-          AccessToken: fakeJwt({ token_use: "access", client_id: "test-client-id", username: "machine", sub: "sub" }),
-          IdToken: fakeJwt({ token_use: "id", aud: "test-client-id", "custom:entityType": "agent", "custom:entityUid": "agt_TEST", "cognito:username": "machine", sub: "sub" }),
-          ExpiresIn: 3600
-        }}), { status: 200 });
-      };
-      await auth.mintMachineTokens(
-        { region: "us-east-1", userPoolDomain: "unused", clientId: "test-client-id" },
-        { username: "machine", secret: "secret", entityType: "agent", entityUid: "agt_TEST" },
-        { baseDelayMs: 0 }
-      );
-    `;
-    const children = ["a", "b"].map((name) => {
-      const child = spawn(
-        process.execPath,
-        ["--experimental-strip-types", "--input-type=module", "-e", childScript],
-        {
-          cwd: process.cwd(),
-          env: {
-            ...process.env,
-            HOME: tmpHome,
-            HQ_LOCK_TEST_MODULE_URL: moduleUrl,
-            HQ_LOCK_TEST_READY: path.join(tmpHome, `ready-${name}`),
-            HQ_LOCK_TEST_START: start,
-            HQ_LOCK_TEST_MARKER: marker,
-            HQ_LOCK_TEST_OVERLAP: overlap,
-          },
-        },
-      );
-      let stderr = "";
-      child.stderr.on("data", (chunk) => {
-        stderr += String(chunk);
-      });
-      return { child, stderr: () => stderr };
-    });
-    const readyPaths = ["a", "b"].map((name) =>
-      path.join(tmpHome, `ready-${name}`),
-    );
-    const readyDeadline = Date.now() + 5_000;
-    while (
-      !readyPaths.every((readyPath) => fs.existsSync(readyPath)) &&
-      Date.now() < readyDeadline
-    ) {
-      await new Promise((resolve) => setTimeout(resolve, 10));
-    }
-    expect(readyPaths.every((readyPath) => fs.existsSync(readyPath))).toBe(true);
-    fs.writeFileSync(start, "start");
-
-    const exits = await Promise.all(
-      children.map(
-        ({ child, stderr }) =>
-          new Promise<{ code: number | null; stderr: string }>((resolve) => {
-            child.on("exit", (code) => resolve({ code, stderr: stderr() }));
-          }),
-      ),
-    );
-
-    expect(exits).toEqual([
-      { code: 0, stderr: "" },
-      { code: 0, stderr: "" },
-    ]);
-    expect(fs.existsSync(overlap)).toBe(false);
-  }, 10_000);
-});
-
-// ---------------------------------------------------------------------------
-// Throttle handling: retry TooManyRequestsException with backoff
-// ---------------------------------------------------------------------------
-
-describe("mintMachineTokens throttle retry", () => {
-  /** Fetch mock that throttles (HTTP 400 + TooManyRequestsException, the shape
-   *  Cognito actually returns) for the first `throttleCount` calls, then 200s. */
-  function stubThrottleThenSuccess(throttleCount: number) {
-    let call = 0;
-    const fetchMock = vi.fn(async () => {
-      call++;
-      if (call <= throttleCount) {
-        return new Response(
-          JSON.stringify({
-            __type: "TooManyRequestsException",
-            message: "Too many requests",
-          }),
-          { status: 400 },
-        );
-      }
-      return new Response(
-        JSON.stringify({
-          AuthenticationResult: {
-            AccessToken: fakeJwt({
-              token_use: "access",
-              client_id: CONFIG.clientId,
-              username: "machine-agt_01TEST",
-              sub: "machine-sub",
-            }),
-            IdToken: fakeJwt({
-              token_use: "id",
-              aud: CONFIG.clientId,
-              "custom:entityType": "agent",
-              "custom:entityUid": "agt_01TEST",
-              "cognito:username": "machine-agt_01TEST",
-              sub: "machine-sub",
-            }),
-            ExpiresIn: 3600,
-          },
-        }),
-        { status: 200 },
-      );
-    });
-    vi.stubGlobal("fetch", fetchMock);
-    return fetchMock;
-  }
-
-  it("retries a throttled mint with backoff and eventually succeeds", async () => {
-    writeCreds();
-    const fetchMock = stubThrottleThenSuccess(2);
-    const { mintMachineTokens } = await importModule();
-
-    // baseDelayMs: 0 keeps the test instant — jitter * 0 == 0.
-    const tokens = await mintMachineTokens(CONFIG, undefined, {
-      baseDelayMs: 0,
-      maxRetries: 5,
-    });
-
-    expect(fetchMock).toHaveBeenCalledTimes(3); // 2 throttles + 1 success
-    const idClaims = JSON.parse(
-      Buffer.from(tokens.idToken.split(".")[1], "base64url").toString(),
-    );
-    expect(idClaims.token_use).toBe("id");
-  });
-
-  it("gives up after maxRetries and throws when throttling never clears", async () => {
-    writeCreds();
-    const fetchMock = stubThrottleThenSuccess(Number.POSITIVE_INFINITY);
-    const { mintMachineTokens, CognitoAuthError } = await importModule();
-
-    await expect(
-      mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0, maxRetries: 2 }),
-    ).rejects.toBeInstanceOf(CognitoAuthError);
-
-    // maxRetries: 2 → 3 total attempts (initial + 2 retries).
-    expect(fetchMock).toHaveBeenCalledTimes(3);
-  });
-
-  it("does NOT retry a non-throttle auth failure (bad creds fail fast)", async () => {
-    writeCreds();
-    const fetchMock = vi.fn(async () =>
-      new Response(
-        JSON.stringify({ __type: "NotAuthorizedException", message: "nope" }),
-        { status: 400 },
-      ),
-    );
-    vi.stubGlobal("fetch", fetchMock);
-    const { mintMachineTokens, CognitoAuthError } = await importModule();
-
-    await expect(
-      mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0, maxRetries: 5 }),
-    ).rejects.toBeInstanceOf(CognitoAuthError);
-    expect(fetchMock).toHaveBeenCalledTimes(1); // no retries
-  });
-});
-
-// ---------------------------------------------------------------------------
-// getValidAccessToken — machine-mode short circuit
-// ---------------------------------------------------------------------------
-
-describe("getValidAccessToken in machine mode", () => {
-  it("mints via machine creds and returns the ID token (vault-API identity)", async () => {
-    writeCreds();
-    const { calls } = stubMintFetch();
-    const { getValidAccessToken } = await importModule();
-
-    const token = await getValidAccessToken(CONFIG, { interactive: false });
-
-    expect(calls).toHaveLength(1);
-    const claims = JSON.parse(
-      Buffer.from(token.split(".")[1], "base64url").toString(),
-    );
-    // ID, NOT access: agent identity rides the ID token; the access-token
-    // return lobotomized first-sync on the first post-cutover box.
-    expect(claims.token_use).toBe("id");
-  });
-});