@indigoai-us/hq-cloud 6.18.44-alpha.9 → 6.18.44

package/dist/machine-auth.test.js

@@ -1,1492 +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;
-let originalUserProfile;
-let originalCredsEnv;
-let tmpHome;
-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;
-    // Keep this suite's token-cache fixture coupled to its sandboxed HOME
-    // instead of inheriting Vitest's suite-wide hermetic state directory.
-    process.env.HQ_STATE_DIR = path.join(tmpHome, ".hq");
-    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 = { username: "machine-agt_01TEST", secret: "s3cret" }) {
-    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) {
-    const enc = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
-    return `${enc({ alg: "RS256", kid: "k" })}.${enc(claims)}.sig`;
-}
-function stubMintFetch(overrides = {}) {
-    const calls = [];
-    const fetchMock = vi.fn(async (url, init) => {
-        calls.push({ url: String(url), init: init ?? {} });
-        const body = JSON.parse(String(init?.body));
-        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"));
-        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, loadCachedMachineTokens } = 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(loadCachedMachineTokens()).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 }],
-    ])("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 = {
-            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, loadCachedMachineTokens, CognitoAuthError } = await importModule();
-        await expect(mintMachineTokens(CONFIG)).rejects.toBeInstanceOf(CognitoAuthError);
-        expect(loadCachedMachineTokens()).toBeNull();
-    });
-});
-// ---------------------------------------------------------------------------
-// getValidMachineTokens — cache vs re-mint
-// ---------------------------------------------------------------------------
-describe("getValidMachineTokens", () => {
-    const cacheWithIdentity = (expiresAt) => ({
-        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,
-        tokenType: "Bearer",
-    });
-    const getMachineTokensWithMinValidity = (get, minValiditySeconds) => get(CONFIG, { minValiditySeconds });
-    it("re-mints a hot cached token with 200 seconds left when 360 are required", async () => {
-        writeCreds();
-        vi.useFakeTimers();
-        vi.setSystemTime(new Date("2026-10-02T07:00:00.000Z"));
-        const { fetchMock } = stubMintFetch();
-        const { saveCachedTokens, getValidMachineTokens } = await importModule();
-        saveCachedTokens(cacheWithIdentity(Date.now() + 400_000));
-        await getMachineTokensWithMinValidity(getValidMachineTokens, 360);
-        await vi.advanceTimersByTimeAsync(200_000);
-        await getMachineTokensWithMinValidity(getValidMachineTokens, 360);
-        expect(fetchMock).toHaveBeenCalledTimes(1);
-    });
-    it("re-mints a disk-cached token with 200 seconds left under the lock", async () => {
-        writeCreds();
-        vi.useFakeTimers();
-        vi.setSystemTime(new Date("2026-10-02T07:00:00.000Z"));
-        const { fetchMock } = stubMintFetch();
-        const { saveCachedTokens, getValidMachineTokens } = await importModule();
-        saveCachedTokens(cacheWithIdentity(Date.now() + 200_000));
-        await getValidMachineTokens(CONFIG);
-        expect(fetchMock).toHaveBeenCalledTimes(1);
-    });
-    it("does not reuse a 200-second cache after a machine lock timeout", async () => {
-        writeCreds();
-        vi.useFakeTimers();
-        vi.setSystemTime(new Date("2026-10-02T07:00:00.000Z"));
-        const { fetchMock } = stubMintFetch();
-        const { saveCachedTokens, getValidMachineTokens, machineTokenCacheFile, CognitoRefreshError } = await importModule();
-        saveCachedTokens(cacheWithIdentity(Date.now() + 200_000));
-        fs.writeFileSync(`${machineTokenCacheFile()}.lock`, String(process.pid));
-        const resolution = getMachineTokensWithMinValidity(getValidMachineTokens, 360);
-        const rejected = resolution.then(() => false, (error) => error instanceof CognitoRefreshError);
-        await vi.advanceTimersByTimeAsync(20_050);
-        expect(await rejected).toBe(true);
-        expect(fetchMock).not.toHaveBeenCalled();
-    });
-    it("reuses a machine token with 400 seconds left when 360 are required", async () => {
-        writeCreds();
-        vi.useFakeTimers();
-        vi.setSystemTime(new Date("2026-10-02T07:00:00.000Z"));
-        const { fetchMock } = stubMintFetch();
-        const { saveCachedTokens, getValidMachineTokens } = await importModule();
-        const cached = cacheWithIdentity(Date.now() + 400_000);
-        saveCachedTokens(cached);
-        const reused = await getValidMachineTokens(CONFIG);
-        expect(reused.expiresAt).toBe(cached.expiresAt);
-        expect(fetchMock).not.toHaveBeenCalled();
-    });
-    it("rejects a required validity above 1800 seconds before any network call", async () => {
-        writeCreds();
-        const { fetchMock } = stubMintFetch();
-        const { getValidMachineTokens } = await importModule();
-        await expect(getMachineTokensWithMinValidity(getValidMachineTokens, 1801)).rejects.toThrow(RangeError);
-        expect(fetchMock).not.toHaveBeenCalled();
-    });
-    it("accepts a required validity of exactly 1800 seconds", async () => {
-        writeCreds();
-        vi.useFakeTimers();
-        vi.setSystemTime(new Date("2026-10-02T07:00:00.000Z"));
-        const { fetchMock } = stubMintFetch();
-        const { saveCachedTokens, getValidMachineTokens } = await importModule();
-        const cached = cacheWithIdentity(Date.now() + 1_900_000);
-        saveCachedTokens(cached);
-        const reused = await getMachineTokensWithMinValidity(getValidMachineTokens, 1800);
-        expect(reused.expiresAt).toBe(cached.expiresAt);
-        expect(fetchMock).not.toHaveBeenCalled();
-    });
-    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",
-        };
-        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, loadCachedMachineTokens, 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(loadCachedMachineTokens()?.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, loadCachedMachineTokens } = 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(loadCachedMachineTokens()?.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.loadCachedMachineTokens()?.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.loadCachedMachineTokens()?.refreshToken).toBe("");
-    });
-    it.each([
-        [
-            "entity type",
-            { entityType: "outpost", entityUid: "out_01TEST" },
-            "agent",
-            "agt_01TEST",
-        ],
-        [
-            "entity uid",
-            { entityType: "outpost", entityUid: "out_01TEST" },
-            "outpost",
-            "out_OTHER",
-        ],
-    ])("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 = {
-            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",
-        };
-        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;
-        const firstMintGate = new Promise((resolve) => {
-            releaseFirstMint = resolve;
-        });
-        let signalFirstMint;
-        const firstMintStarted = new Promise((resolve) => {
-            signalFirstMint = resolve;
-        });
-        let callCount = 0;
-        const fetchMock = vi.fn(async (_url, init) => {
-            callCount += 1;
-            const body = JSON.parse(String(init?.body));
-            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, machineTokenCacheFile } = 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",
-        };
-        saveCachedTokens(cached);
-        // The lock guards the MACHINE cache, which lives beside the creds file,
-        // not in the person's ~/.hq (machine-token-cache-isolation.test.ts).
-        fs.writeFileSync(`${machineTokenCacheFile()}.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, machineTokenCacheFile, 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(`${machineTokenCacheFile()}.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;
-        const mintGate = new Promise((resolve) => {
-            releaseMint = resolve;
-        });
-        let signalMintStarted;
-        const mintStarted = new Promise((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.loadCachedMachineTokens()?.refreshToken).toBe("");
-    });
-    it("serializes the exported direct mint API", async () => {
-        writeCreds();
-        let releaseFirstMint;
-        const firstMintGate = new Promise((resolve) => {
-            releaseFirstMint = resolve;
-        });
-        let signalFirstMint;
-        const firstMintStarted = new Promise((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) => {
-            // Drop FORCE_COLOR/NO_COLOR so child Node processes do not emit the
-            // "NO_COLOR is ignored due to FORCE_COLOR" warning on stderr — that
-            // warning is ambient harness noise and is not a mint failure signal.
-            const childEnv = { ...process.env };
-            delete childEnv.FORCE_COLOR;
-            delete childEnv.NO_COLOR;
-            // Node 22 before type stripping was unflagged (the HQ toolchain ships
-            // 22.17.0) prints an ExperimentalWarning for --experimental-strip-types
-            // on stderr. Silence only that warning class so the empty-stderr check
-            // below still catches every real failure.
-            const child = spawn(process.execPath, [
-                "--experimental-strip-types",
-                "--disable-warning=ExperimentalWarning",
-                "--input-type=module",
-                "-e",
-                childScript,
-            ], {
-                cwd: process.cwd(),
-                env: {
-                    ...childEnv,
-                    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((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) {
-        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");
-    });
-});
-// ---------------------------------------------------------------------------
-// External agents: host-key signed mint (api-contract v1)
-// ---------------------------------------------------------------------------
-import { generateKeyPairSync, createPublicKey, verify as cryptoVerify } from "crypto";
-const EXTERNAL_UID = "agt_01EXTERNAL0000000000000000";
-const EXTERNAL_API = "https://hqapi.example.test";
-function writeHostKey() {
-    const dir = path.join(tmpHome, ".hq-agent");
-    fs.mkdirSync(dir, { recursive: true });
-    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
-    const privatePath = path.join(dir, "host-key");
-    fs.writeFileSync(privatePath, privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
-    return {
-        privatePath,
-        publicPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
-    };
-}
-function writeExternalCreds(hostKeyPath, overrides = {}) {
-    return writeCreds({
-        username: "agt-01external@agents.getindigo.ai",
-        secret: "s3cret",
-        clientId: "agent-client",
-        region: "us-east-1",
-        entityType: "agent",
-        entityUid: EXTERNAL_UID,
-        runtime: "external",
-        hostKeyPath,
-        apiBaseUrl: EXTERNAL_API,
-        ...overrides,
-    });
-}
-/**
- * Fake hq-pro: hands out a nonce, then verifies the Ed25519 signature over
- * `${uid}.${nonce}` against the enrolled public key before minting.
- */
-function stubExternalMintFetch(opts) {
-    const calls = [];
-    const nonces = new Set();
-    let n = 0;
-    const challengeStatuses = [...(opts.challengeStatus ?? [])];
-    const mintStatuses = [...(opts.mintStatus ?? [])];
-    const fetchMock = vi.fn(async (url, init) => {
-        const u = String(url);
-        calls.push({ url: u, init: init ?? {} });
-        if (u.endsWith("/mint-challenge")) {
-            const forced = challengeStatuses.shift();
-            if (forced && forced !== 200) {
-                return new Response(JSON.stringify({ error: "throttled" }), { status: forced });
-            }
-            const nonce = `nonce-${++n}`;
-            nonces.add(nonce);
-            return new Response(JSON.stringify({ nonce, expiresAt: new Date(Date.now() + 60_000).toISOString() }), { status: 200 });
-        }
-        if (u.endsWith("/mint")) {
-            const forced = mintStatuses.shift();
-            if (forced && forced !== 200) {
-                return new Response(JSON.stringify({ error: "throttled" }), { status: forced });
-            }
-            const body = JSON.parse(String(init?.body));
-            if (opts.rejectCode) {
-                return new Response(JSON.stringify({ code: opts.rejectCode, error: "refused" }), { status: opts.rejectStatus ?? 401 });
-            }
-            if (body.secret !== "s3cret") {
-                return new Response(JSON.stringify({ code: "not_authorized", error: "wrong secret" }), { status: 401 });
-            }
-            if (!nonces.delete(body.nonce)) {
-                return new Response(JSON.stringify({ code: "bad_nonce", error: "unknown nonce" }), { status: 401 });
-            }
-            const ok = cryptoVerify(null, Buffer.from(`${EXTERNAL_UID}.${body.nonce}`), createPublicKey(opts.publicPem), Buffer.from(body.signature, "base64"));
-            if (!ok) {
-                return new Response(JSON.stringify({ code: "bad_signature", error: "signature mismatch" }), { status: 401 });
-            }
-            const clientId = opts.clientId ?? "agent-client";
-            return new Response(JSON.stringify(opts.mintBody ?? {
-                accessToken: fakeJwt({
-                    token_use: "access",
-                    client_id: clientId,
-                    username: "uuid-external",
-                    sub: "sub-external",
-                }),
-                idToken: fakeJwt({
-                    token_use: "id",
-                    aud: clientId,
-                    "custom:entityType": "agent",
-                    "custom:entityUid": EXTERNAL_UID,
-                    "cognito:username": "uuid-external",
-                    sub: "sub-external",
-                }),
-                refreshToken: "should-not-be-kept",
-                expiresIn: 3600,
-            }), { status: 200 });
-        }
-        throw new Error(`unexpected fetch ${u}`);
-    });
-    vi.stubGlobal("fetch", fetchMock);
-    return { fetchMock, calls };
-}
-describe("external machine creds parsing", () => {
-    it("parses runtime, hostKeyPath and apiBaseUrl", async () => {
-        const { privatePath } = writeHostKey();
-        writeExternalCreds(privatePath);
-        const { loadMachineCreds, isExternalMachineCreds } = await importModule();
-        const creds = loadMachineCreds();
-        expect(creds).toMatchObject({
-            runtime: "external",
-            hostKeyPath: privatePath,
-            apiBaseUrl: EXTERNAL_API,
-            entityType: "agent",
-            entityUid: EXTERNAL_UID,
-        });
-        expect(isExternalMachineCreds(creds)).toBe(true);
-    });
-    it("keeps hosted creds hosted (no runtime field → not external)", async () => {
-        writeCreds({ username: "machine-agt_01TEST", secret: "s3cret" });
-        const { loadMachineCreds, isExternalMachineCreds } = await importModule();
-        const creds = loadMachineCreds();
-        expect(creds?.runtime).toBeUndefined();
-        expect(isExternalMachineCreds(creds)).toBe(false);
-    });
-    it("rejects an external file without hostKeyPath (no silent hosted downgrade)", async () => {
-        writeCreds({
-            username: "u",
-            secret: "s",
-            entityType: "agent",
-            entityUid: EXTERNAL_UID,
-            runtime: "external",
-        });
-        const { loadMachineCreds } = await importModule();
-        expect(loadMachineCreds()).toBeNull();
-    });
-    it("rejects an unknown runtime value", async () => {
-        writeCreds({ username: "u", secret: "s", runtime: "cloud" });
-        const { loadMachineCreds } = await importModule();
-        expect(loadMachineCreds()).toBeNull();
-    });
-    it("honors HQ_MACHINE_CREDS_FILE for external creds too", async () => {
-        const { privatePath } = writeHostKey();
-        const alt = path.join(tmpHome, "elsewhere.json");
-        fs.writeFileSync(alt, JSON.stringify({
-            username: "u",
-            secret: "s",
-            entityType: "agent",
-            entityUid: EXTERNAL_UID,
-            runtime: "external",
-            hostKeyPath: privatePath,
-        }));
-        process.env.HQ_MACHINE_CREDS_FILE = alt;
-        const { loadMachineCreds, externalMintApiBaseUrl } = await importModule();
-        const creds = loadMachineCreds();
-        expect(creds?.runtime).toBe("external");
-        // No apiBaseUrl in the file → env → default, trailing slash trimmed.
-        process.env.HQ_VAULT_API_URL = "https://alt.example.test/";
-        expect(externalMintApiBaseUrl(creds)).toBe("https://alt.example.test");
-        delete process.env.HQ_VAULT_API_URL;
-        expect(externalMintApiBaseUrl(creds)).toBe("https://hqapi.hq.computer");
-    });
-});
-describe("signExternalMintChallenge", () => {
-    it("produces a base64 Ed25519 signature over `${uid}.${nonce}`", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        const { signExternalMintChallenge, externalMintChallengeMessage } = await importModule();
-        const sig = signExternalMintChallenge(fs.readFileSync(privatePath), EXTERNAL_UID, "abc");
-        expect(externalMintChallengeMessage(EXTERNAL_UID, "abc")).toBe(`${EXTERNAL_UID}.abc`);
-        expect(cryptoVerify(null, Buffer.from(`${EXTERNAL_UID}.abc`), createPublicKey(publicPem), Buffer.from(sig, "base64"))).toBe(true);
-        // A different nonce must not verify with the same signature.
-        expect(cryptoVerify(null, Buffer.from(`${EXTERNAL_UID}.abd`), createPublicKey(publicPem), Buffer.from(sig, "base64"))).toBe(false);
-    });
-    it("refuses a non-Ed25519 key", async () => {
-        const { signExternalMintChallenge, CognitoAuthError } = await importModule();
-        const { privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
-        expect(() => signExternalMintChallenge(privateKey.export({ type: "pkcs8", format: "pem" }), EXTERNAL_UID, "n")).toThrow(CognitoAuthError);
-    });
-});
-describe("mintMachineTokens for external agents", () => {
-    it("challenges, signs, mints through hq-pro and never calls Cognito", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        writeExternalCreds(privatePath);
-        const { calls } = stubExternalMintFetch({ publicPem });
-        const { mintMachineTokens, loadCachedMachineTokens } = await importModule();
-        const tokens = await mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0 });
-        expect(calls.map((c) => c.url)).toEqual([
-            `${EXTERNAL_API}/v1/agents/${EXTERNAL_UID}/mint-challenge`,
-            `${EXTERNAL_API}/v1/agents/${EXTERNAL_UID}/mint`,
-        ]);
-        expect(calls.every((c) => !c.url.includes("cognito-idp"))).toBe(true);
-        // The challenge carries nothing; the mint carries nonce + signature +
-        // the machine secret (hq-pro runs USER_PASSWORD_AUTH with it).
-        expect(String(calls[0].init.body)).toBe("{}");
-        const mintBody = JSON.parse(String(calls[1].init.body));
-        expect(mintBody).toEqual({ nonce: "nonce-1", signature: expect.any(String), secret: "s3cret" });
-        expect(tokens.refreshToken).toBe("");
-        const claims = JSON.parse(Buffer.from(tokens.idToken.split(".")[1], "base64url").toString());
-        expect(claims["custom:entityUid"]).toBe(EXTERNAL_UID);
-        expect(loadCachedMachineTokens()?.idToken).toBe(tokens.idToken);
-    });
-    it("getValidMachineTokens routes external creds through the signed mint", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        writeExternalCreds(privatePath);
-        const { calls } = stubExternalMintFetch({ publicPem });
-        const { getValidMachineTokens } = await importModule();
-        await getValidMachineTokens(CONFIG);
-        await getValidMachineTokens(CONFIG);
-        // One challenge + one mint; the second call is served from the memo.
-        expect(calls).toHaveLength(2);
-    });
-    it("surfaces hq-pro's 401 code (bad_signature) as a hard CognitoAuthError", async () => {
-        const { privatePath } = writeHostKey();
-        const other = generateKeyPairSync("ed25519").publicKey
-            .export({ type: "spki", format: "pem" })
-            .toString();
-        writeExternalCreds(privatePath);
-        const { calls } = stubExternalMintFetch({ publicPem: other });
-        const { mintMachineTokens, CognitoAuthError } = await importModule();
-        await expect(mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0 })).rejects.toThrow(/External machine token mint failed \(401\) bad_signature/);
-        await expect(mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0 })).rejects.toBeInstanceOf(CognitoAuthError);
-        // No retry on a hard refusal: each attempt is exactly challenge + mint.
-        expect(calls.filter((c) => c.url.endsWith("/mint"))).toHaveLength(2);
-    });
-    it("surfaces revoked / not_authorized / agent_not_found without retrying", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        for (const [code, status] of [["revoked", 401], ["not_authorized", 401], ["agent_not_found", 404]]) {
-            writeExternalCreds(privatePath);
-            const { calls } = stubExternalMintFetch({ publicPem, rejectCode: code, rejectStatus: status });
-            const { mintMachineTokens } = await importModule();
-            await expect(mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0 })).rejects.toThrow(new RegExp(`\\(${status}\\) ${code}`));
-            expect(calls).toHaveLength(2);
-            vi.resetModules();
-        }
-    });
-    it("a wrong machine secret is refused as not_authorized", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        writeExternalCreds(privatePath, { secret: "stale" });
-        stubExternalMintFetch({ publicPem });
-        const { mintMachineTokens } = await importModule();
-        await expect(mintMachineTokens(CONFIG)).rejects.toThrow(/\(401\) not_authorized/);
-    });
-    it("retries a throttled challenge and a throttled mint, then succeeds", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        writeExternalCreds(privatePath);
-        const { calls } = stubExternalMintFetch({
-            publicPem,
-            challengeStatus: [429, 200, 200],
-            mintStatus: [429, 200],
-        });
-        const { mintMachineTokens } = await importModule();
-        await mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0, maxRetries: 3 });
-        expect(calls.filter((c) => c.url.endsWith("/mint-challenge"))).toHaveLength(3);
-        expect(calls.filter((c) => c.url.endsWith("/mint"))).toHaveLength(2);
-    });
-    it("fails with an actionable error when the host key is missing", async () => {
-        const missing = path.join(tmpHome, ".hq-agent", "host-key");
-        writeExternalCreds(missing);
-        const { fetchMock } = stubExternalMintFetch({ publicPem: "" });
-        const { mintMachineTokens } = await importModule();
-        await expect(mintMachineTokens(CONFIG)).rejects.toThrow(/Cannot read host key .*--replace/);
-        expect(fetchMock).not.toHaveBeenCalled();
-    });
-    it("rejects tokens that do not match the enrolled identity", async () => {
-        const { privatePath, publicPem } = writeHostKey();
-        writeExternalCreds(privatePath);
-        stubExternalMintFetch({
-            publicPem,
-            mintBody: {
-                accessToken: fakeJwt({ token_use: "access", client_id: "agent-client", username: "x", sub: "x" }),
-                idToken: fakeJwt({
-                    token_use: "id",
-                    aud: "agent-client",
-                    "custom:entityType": "agent",
-                    "custom:entityUid": "agt_01SOMEONEELSE000000000000",
-                    "cognito:username": "x",
-                    sub: "x",
-                }),
-                expiresIn: 3600,
-            },
-        });
-        const { mintMachineTokens } = await importModule();
-        await expect(mintMachineTokens(CONFIG)).rejects.toThrow(/do not match the requested machine identity/);
-    });
-    it("hosted creds still mint straight against Cognito (path untouched)", async () => {
-        writeCreds({
-            username: "agt-01hosted@agents.getindigo.ai",
-            secret: "s3cret",
-            clientId: "agent-client",
-            region: "us-east-1",
-            entityType: "agent",
-            entityUid: "agt_01TEST",
-            runtime: "hosted",
-        });
-        const { calls } = stubMintFetch();
-        const { mintMachineTokens } = await importModule();
-        await mintMachineTokens(CONFIG);
-        expect(calls).toHaveLength(1);
-        expect(calls[0].url).toBe("https://cognito-idp.us-east-1.amazonaws.com/");
-    });
-});
-//# sourceMappingURL=machine-auth.test.js.map