@indigoai-us/hq-cloud 6.18.44-alpha.48 → 6.18.44-alpha.49

package/dist/machine-auth.test.js

@@ -0,0 +1,1492 @@
+/**
+ * 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