@indigoai-us/hq-cloud 6.14.11 → 6.14.13

package/dist/machine-auth.test.js

@@ -13,6 +13,8 @@
 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 originalCredsEnv;
@@ -26,6 +28,7 @@ beforeEach(() => {
     vi.resetModules();
 });
 afterEach(() => {
+    vi.useRealTimers();
     if (originalHome === undefined)
         delete process.env.HOME;
     else
@@ -62,11 +65,38 @@ 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: CONFIG.clientId }),
-                IdToken: overrides.IdToken ?? fakeJwt({ token_use: "id" }),
+                    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,
             },
@@ -112,6 +142,25 @@ describe("machine identity detection", () => {
         });
         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" }));
@@ -129,6 +178,31 @@ describe("machine identity detection", () => {
         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
@@ -167,7 +241,7 @@ describe("mintMachineTokens", () => {
         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("rt");
+        expect(tokens.refreshToken).toBe("");
         expect(typeof tokens.expiresAt).toBe("number");
         // Persisted to the shared cache file.
         expect(loadCachedTokens()).toEqual(tokens);
@@ -177,11 +251,59 @@ describe("mintMachineTokens", () => {
         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, loadCachedTokens, CognitoAuthError } = await importModule();
+        await expect(mintMachineTokens(CONFIG)).rejects.toBeInstanceOf(CognitoAuthError);
+        expect(loadCachedTokens()).toBeNull();
+    });
 });
 // ---------------------------------------------------------------------------
 // getValidMachineTokens — cache vs re-mint
@@ -216,6 +338,34 @@ describe("getValidMachineTokens", () => {
         expect(tokens).toEqual(cached);
         expect(fetchMock).not.toHaveBeenCalled();
     });
+    it("strips and persists an empty refresh token when reusing a machine cache", async () => {
+        writeCreds();
+        const { fetchMock } = stubMintFetch();
+        const { saveCachedTokens, loadCachedTokens, getValidMachineTokens } = await importModule();
+        saveCachedTokens({
+            accessToken: fakeJwt({
+                token_use: "access",
+                client_id: CONFIG.clientId,
+                username: "machine-agt_01TEST",
+                sub: "machine-sub",
+            }),
+            idToken: fakeJwt({
+                token_use: "id",
+                aud: CONFIG.clientId,
+                "custom:entityType": "agent",
+                "custom:entityUid": "agt_01TEST",
+                "cognito:username": "machine-agt_01TEST",
+                sub: "machine-sub",
+            }),
+            refreshToken: "legacy-machine-refresh-token",
+            expiresAt: Date.now() + 30 * 60 * 1000,
+            tokenType: "Bearer",
+        });
+        const tokens = await getValidMachineTokens(CONFIG);
+        expect(tokens.refreshToken).toBe("");
+        expect(loadCachedTokens()?.refreshToken).toBe("");
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
     it("re-mints when the cache is expiring", async () => {
         writeCreds();
         const { fetchMock } = stubMintFetch();
@@ -289,6 +439,333 @@ describe("getValidMachineTokens", () => {
         expect(token).toBe(freshId);
         expect(loadCachedTokens()?.idToken).toBe(freshId);
     });
+    it("accepts an Outpost machine cache with delegated claims, then re-mints after expiry without OAuth refresh", async () => {
+        const username = "out-01test@outposts.getindigo.ai";
+        const entityUid = "out_01TEST";
+        writeCreds({
+            username,
+            secret: "outpost-secret",
+            clientId: CONFIG.clientId,
+            region: CONFIG.region,
+            entityType: "outpost",
+            entityUid,
+        });
+        const accessToken = fakeJwt({
+            token_use: "access",
+            client_id: CONFIG.clientId,
+            username,
+            sub: "machine-sub",
+        });
+        const idToken = fakeJwt({
+            token_use: "id",
+            aud: CONFIG.clientId,
+            "custom:entityType": "outpost",
+            "custom:entityUid": entityUid,
+            "custom:delegatedSub": "human-sub",
+            "custom:delegatedEmail": "owner@example.com",
+            "cognito:username": username,
+            sub: "machine-sub",
+        });
+        const { fetchMock, calls } = stubMintFetch({
+            AccessToken: accessToken,
+            IdToken: idToken,
+            RefreshToken: "must-not-be-stored",
+        });
+        const firstModule = await importModule();
+        const first = await firstModule.getValidMachineTokens(CONFIG);
+        expect(first.idToken).toBe(idToken);
+        expect(firstModule.loadCachedTokens()?.refreshToken).toBe("");
+        // A new process accepts the shared Outpost cache without another mint.
+        vi.resetModules();
+        const cacheHitModule = await importModule();
+        await expect(cacheHitModule.getValidMachineTokens(CONFIG)).resolves.toEqual(first);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        // Once expired, a new process re-mints with the permanent secret. It never
+        // attempts the browser client's /oauth2/token refresh-token flow.
+        cacheHitModule.saveCachedTokens({
+            ...first,
+            expiresAt: Date.now() - 1,
+        });
+        vi.resetModules();
+        const expiredModule = await importModule();
+        await expiredModule.getValidMachineTokens(CONFIG);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(calls.every(({ url }) => !url.includes("/oauth2/token"))).toBe(true);
+        for (const { init } of calls) {
+            const body = JSON.parse(String(init.body));
+            expect(body).toMatchObject({
+                AuthFlow: "USER_PASSWORD_AUTH",
+                ClientId: CONFIG.clientId,
+                AuthParameters: { USERNAME: username, PASSWORD: "outpost-secret" },
+            });
+        }
+        expect(expiredModule.loadCachedTokens()?.refreshToken).toBe("");
+    });
+    it.each([
+        [
+            "entity type",
+            { entityType: "outpost", entityUid: "out_01TEST" },
+            "agent",
+            "agt_01TEST",
+        ],
+        [
+            "entity uid",
+            { entityType: "outpost", entityUid: "out_01TEST" },
+            "outpost",
+            "out_OTHER",
+        ],
+    ])("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 } = 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);
+        fs.writeFileSync(path.join(tmpHome, ".hq", "cognito-tokens.json.lock"), String(process.pid));
+        vi.useFakeTimers();
+        const resolution = getValidMachineTokens(CONFIG);
+        await vi.advanceTimersByTimeAsync(20_050);
+        await expect(resolution).resolves.toEqual(cached);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it("rejects a legacy non-empty-refresh cache after a lock timeout without minting unlocked", async () => {
+        writeCreds();
+        const { fetchMock } = stubMintFetch();
+        const { saveCachedTokens, getValidMachineTokens, CognitoAuthError, } = await importModule();
+        saveCachedTokens({
+            accessToken: fakeJwt({
+                token_use: "access",
+                client_id: CONFIG.clientId,
+                username: "machine-agt_01TEST",
+                sub: "machine-sub",
+            }),
+            idToken: fakeJwt({
+                token_use: "id",
+                aud: CONFIG.clientId,
+                "custom:entityType": "agent",
+                "custom:entityUid": "agt_01TEST",
+                "cognito:username": "machine-agt_01TEST",
+                sub: "machine-sub",
+            }),
+            refreshToken: "legacy-refresh",
+            expiresAt: Date.now() + 30 * 60 * 1000,
+            tokenType: "Bearer",
+        });
+        fs.writeFileSync(path.join(tmpHome, ".hq", "cognito-tokens.json.lock"), String(process.pid));
+        vi.useFakeTimers();
+        const resolution = getValidMachineTokens(CONFIG);
+        const rejection = expect(resolution).rejects.toBeInstanceOf(CognitoAuthError);
+        await vi.advanceTimersByTimeAsync(20_050);
+        await rejection;
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
 });
 // ---------------------------------------------------------------------------
 // Regression: constant token mints over N files (sync-runner mint storm)
@@ -327,6 +804,195 @@ describe("regression: constant mints regardless of file count", () => {
         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.loadCachedTokens()?.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) => {
+            const child = spawn(process.execPath, ["--experimental-strip-types", "--input-type=module", "-e", childScript], {
+                cwd: process.cwd(),
+                env: {
+                    ...process.env,
+                    HOME: tmpHome,
+                    HQ_LOCK_TEST_MODULE_URL: moduleUrl,
+                    HQ_LOCK_TEST_READY: path.join(tmpHome, `ready-${name}`),
+                    HQ_LOCK_TEST_START: start,
+                    HQ_LOCK_TEST_MARKER: marker,
+                    HQ_LOCK_TEST_OVERLAP: overlap,
+                },
+            });
+            let stderr = "";
+            child.stderr.on("data", (chunk) => {
+                stderr += String(chunk);
+            });
+            return { child, stderr: () => stderr };
+        });
+        const readyPaths = ["a", "b"].map((name) => path.join(tmpHome, `ready-${name}`));
+        const readyDeadline = Date.now() + 5_000;
+        while (!readyPaths.every((readyPath) => fs.existsSync(readyPath)) &&
+            Date.now() < readyDeadline) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        expect(readyPaths.every((readyPath) => fs.existsSync(readyPath))).toBe(true);
+        fs.writeFileSync(start, "start");
+        const exits = await Promise.all(children.map(({ child, stderr }) => new Promise((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
@@ -346,8 +1012,20 @@ describe("mintMachineTokens throttle retry", () => {
             }
             return new Response(JSON.stringify({
                 AuthenticationResult: {
-                    AccessToken: fakeJwt({ token_use: "access", client_id: CONFIG.clientId }),
-                    IdToken: fakeJwt({ token_use: "id" }),
+                    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 });