@indigoai-us/hq-cloud 6.14.12 → 6.14.14

package/src/machine-auth.test.ts

@@ -14,6 +14,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: string | undefined;
@@ -30,6 +32,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  vi.useRealTimers();
   if (originalHome === undefined) delete process.env.HOME;
   else process.env.HOME = originalHome;
   if (originalCredsEnv === undefined) delete process.env.HQ_MACHINE_CREDS_FILE;
@@ -77,13 +80,48 @@ function stubMintFetch(
   const calls: Array<{ url: string; init: RequestInit }> = [];
   const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {
     calls.push({ url: String(url), init: init ?? {} });
+    const body = JSON.parse(String(init?.body)) as {
+      ClientId: string;
+      AuthParameters: { USERNAME: string };
+    };
+    const credsFile =
+      process.env.HQ_MACHINE_CREDS_FILE ??
+      path.join(tmpHome, ".hq-agent", "machine-creds.json");
+    const creds = JSON.parse(fs.readFileSync(credsFile, "utf-8")) as {
+      entityType?: "agent" | "outpost";
+      entityUid?: string;
+    };
+    const username = body.AuthParameters.USERNAME;
+    const subject = `sub:${username}`;
+    const entityType = creds.entityType ?? "agent";
+    const entityUid = creds.entityUid ?? "agt_01TEST";
     return new Response(
       JSON.stringify({
         AuthenticationResult: {
           AccessToken:
             overrides.AccessToken ??
-            fakeJwt({ token_use: "access", client_id: 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,
         },
@@ -136,6 +174,27 @@ 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(
@@ -157,6 +216,35 @@ 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();
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -205,7 +293,7 @@ describe("mintMachineTokens", () => {
     );
     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.
@@ -227,6 +315,12 @@ describe("mintMachineTokens", () => {
     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 () => {
@@ -235,6 +329,58 @@ describe("mintMachineTokens", () => {
       CognitoAuthError,
     );
   });
+
+  it.each([
+    ["wrong entity type", { "custom:entityType": "agent", "custom:entityUid": "agt_OTHER" }],
+    ["wrong entity uid", { "custom:entityUid": "out_OTHER" }],
+    ["absent delegatedSub", { "custom:delegatedSub": undefined }],
+    ["empty delegatedSub", { "custom:delegatedSub": "" }],
+    ["non-string delegatedSub", { "custom:delegatedSub": 42 }],
+    ["absent delegatedEmail", { "custom:delegatedEmail": undefined }],
+    ["empty delegatedEmail", { "custom:delegatedEmail": "" }],
+    ["non-string delegatedEmail", { "custom:delegatedEmail": 42 }],
+  ] as const)(
+    "rejects and does not cache a first mint with %s",
+    async (_label, claimOverride) => {
+      const username = "out-01test@outposts.getindigo.ai";
+      writeCreds({
+        username,
+        secret: "outpost-secret",
+        entityType: "outpost",
+        entityUid: "out_01TEST",
+      });
+      const claims: Record<string, unknown> = {
+        token_use: "id",
+        aud: CONFIG.clientId,
+        "custom:entityType": "outpost",
+        "custom:entityUid": "out_01TEST",
+        "custom:delegatedSub": "human-sub",
+        "custom:delegatedEmail": "owner@example.com",
+        "cognito:username": username,
+        sub: "machine-sub",
+        ...claimOverride,
+      };
+      for (const [key, value] of Object.entries(claims)) {
+        if (value === undefined) delete claims[key];
+      }
+      stubMintFetch({
+        AccessToken: fakeJwt({
+          token_use: "access",
+          client_id: CONFIG.clientId,
+          username,
+          sub: "machine-sub",
+        }),
+        IdToken: fakeJwt(claims),
+      });
+      const { mintMachineTokens, loadCachedTokens, CognitoAuthError } =
+        await importModule();
+
+      await expect(mintMachineTokens(CONFIG)).rejects.toBeInstanceOf(
+        CognitoAuthError,
+      );
+      expect(loadCachedTokens()).toBeNull();
+    },
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -273,6 +419,38 @@ describe("getValidMachineTokens", () => {
     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();
@@ -353,6 +531,399 @@ 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",
+    ],
+  ] as const)(
+    "re-mints when the cached machine %s does not match the creds",
+    async (_label, expectedIdentity, cachedEntityType, cachedEntityUid) => {
+      const username = "out-01test@outposts.getindigo.ai";
+      writeCreds({
+        username,
+        secret: "outpost-secret",
+        ...expectedIdentity,
+      });
+      const { fetchMock } = stubMintFetch();
+      const { saveCachedTokens, getValidMachineTokens } = await importModule();
+      saveCachedTokens({
+        accessToken: fakeJwt({
+          token_use: "access",
+          client_id: CONFIG.clientId,
+          username,
+          sub: "machine-sub",
+        }),
+        idToken: fakeJwt({
+          token_use: "id",
+          aud: CONFIG.clientId,
+          "custom:entityType": cachedEntityType,
+          "custom:entityUid": cachedEntityUid,
+          "custom:delegatedSub": "human-sub",
+          "custom:delegatedEmail": "owner@example.com",
+          "cognito:username": username,
+          sub: "machine-sub",
+        }),
+        refreshToken: "",
+        expiresAt: Date.now() + 30 * 60 * 1000,
+        tokenType: "Bearer",
+      });
+
+      await getValidMachineTokens(CONFIG);
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it.each(["custom:delegatedSub", "custom:delegatedEmail"])(
+    "re-mints when an Outpost cache is missing %s",
+    async (missingClaim) => {
+      const username = "out-01test@outposts.getindigo.ai";
+      const outpostClaims: Record<string, unknown> = {
+        token_use: "id",
+        aud: CONFIG.clientId,
+        "custom:entityType": "outpost",
+        "custom:entityUid": "out_01TEST",
+        "custom:delegatedSub": "human-sub",
+        "custom:delegatedEmail": "owner@example.com",
+        "cognito:username": username,
+        sub: "machine-sub",
+      };
+      delete outpostClaims[missingClaim];
+      writeCreds({
+        username,
+        secret: "outpost-secret",
+        entityType: "outpost",
+        entityUid: "out_01TEST",
+      });
+      const { fetchMock } = stubMintFetch();
+      const { saveCachedTokens, getValidMachineTokens } = await importModule();
+      saveCachedTokens({
+        accessToken: fakeJwt({
+          token_use: "access",
+          client_id: CONFIG.clientId,
+          username,
+          sub: "machine-sub",
+        }),
+        idToken: fakeJwt(outpostClaims),
+        refreshToken: "",
+        expiresAt: Date.now() + 30 * 60 * 1000,
+        tokenType: "Bearer",
+      });
+
+      await getValidMachineTokens(CONFIG);
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it("keeps accepting legacy agent creds without entity fields", async () => {
+    writeCreds({ username: "machine-agt_01TEST", secret: "s3cret" });
+    const { fetchMock } = stubMintFetch();
+    const { saveCachedTokens, getValidMachineTokens } = await importModule();
+    const cached = {
+      accessToken: fakeJwt({
+        token_use: "access",
+        client_id: CONFIG.clientId,
+        username: "machine-agt_01TEST",
+        sub: "machine-sub",
+      }),
+      idToken: fakeJwt({
+        token_use: "id",
+        aud: CONFIG.clientId,
+        "custom:entityType": "agent",
+        "custom:entityUid": "agt_01TEST",
+        "cognito:username": "machine-agt_01TEST",
+        sub: "machine-sub",
+      }),
+      refreshToken: "",
+      expiresAt: Date.now() + 30 * 60 * 1000,
+      tokenType: "Bearer" as const,
+    };
+    saveCachedTokens(cached);
+
+    await expect(getValidMachineTokens(CONFIG)).resolves.toEqual(cached);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("invalidates the memo after the creds file is reprovisioned", async () => {
+    writeCreds({
+      username: "machine-a",
+      secret: "secret-a",
+      entityType: "agent",
+      entityUid: "agt_A",
+    });
+    const { fetchMock } = stubMintFetch();
+    const { getValidMachineTokens } = await importModule();
+
+    const first = await getValidMachineTokens(CONFIG);
+    writeCreds({
+      username: "machine-b",
+      secret: "secret-b",
+      entityType: "outpost",
+      entityUid: "out_B",
+    });
+    const second = await getValidMachineTokens(CONFIG);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(first.idToken).not.toBe(second.idToken);
+    expect(
+      JSON.parse(
+        Buffer.from(second.idToken.split(".")[1], "base64url").toString(),
+      )["custom:entityUid"],
+    ).toBe("out_B");
+  });
+
+  it("invalidates the memo when legacy creds use a different config client", async () => {
+    writeCreds();
+    const { fetchMock } = stubMintFetch();
+    const { getValidMachineTokens } = await importModule();
+    const otherConfig = { ...CONFIG, clientId: "other-client-id" };
+
+    const first = await getValidMachineTokens(CONFIG);
+    const second = await getValidMachineTokens(otherConfig);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(first.idToken).not.toBe(second.idToken);
+    expect(
+      JSON.parse(
+        Buffer.from(second.idToken.split(".")[1], "base64url").toString(),
+      ).aud,
+    ).toBe(otherConfig.clientId);
+  });
+
+  it("does not attach a reprovisioned identity to the previous identity's in-flight mint", async () => {
+    writeCreds({
+      username: "machine-a",
+      secret: "secret-a",
+      entityType: "agent",
+      entityUid: "agt_A",
+    });
+    let releaseFirstMint: (() => void) | undefined;
+    const firstMintGate = new Promise<void>((resolve) => {
+      releaseFirstMint = resolve;
+    });
+    let signalFirstMint: (() => void) | undefined;
+    const firstMintStarted = new Promise<void>((resolve) => {
+      signalFirstMint = resolve;
+    });
+    let callCount = 0;
+    const fetchMock = vi.fn(async (_url: string | URL, init?: RequestInit) => {
+      callCount += 1;
+      const body = JSON.parse(String(init?.body)) as {
+        ClientId: string;
+        AuthParameters: { USERNAME: string };
+      };
+      if (callCount === 1) {
+        signalFirstMint?.();
+        await firstMintGate;
+      }
+      const username = body.AuthParameters.USERNAME;
+      const uid = username === "machine-a" ? "agt_A" : "agt_B";
+      return new Response(
+        JSON.stringify({
+          AuthenticationResult: {
+            AccessToken: fakeJwt({
+              token_use: "access",
+              client_id: body.ClientId,
+              username,
+              sub: `sub:${username}`,
+            }),
+            IdToken: fakeJwt({
+              token_use: "id",
+              aud: body.ClientId,
+              "custom:entityType": "agent",
+              "custom:entityUid": uid,
+              "cognito:username": username,
+              sub: `sub:${username}`,
+            }),
+            ExpiresIn: 3600,
+          },
+        }),
+        { status: 200 },
+      );
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { getValidMachineTokens } = await importModule();
+
+    const first = getValidMachineTokens(CONFIG);
+    await firstMintStarted;
+    writeCreds({
+      username: "machine-b",
+      secret: "secret-b",
+      entityType: "agent",
+      entityUid: "agt_B",
+    });
+    const second = getValidMachineTokens(CONFIG);
+    releaseFirstMint?.();
+
+    const [firstTokens, secondTokens] = await Promise.all([first, second]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(firstTokens.idToken).not.toBe(secondTokens.idToken);
+    expect(
+      JSON.parse(
+        Buffer.from(secondTokens.idToken.split(".")[1], "base64url").toString(),
+      )["custom:entityUid"],
+    ).toBe("agt_B");
+  });
+
+  it("reuses only an empty-refresh matching cache after a lock timeout", async () => {
+    writeCreds();
+    const { fetchMock } = stubMintFetch();
+    const { saveCachedTokens, getValidMachineTokens } = await importModule();
+    const cached = {
+      accessToken: fakeJwt({
+        token_use: "access",
+        client_id: CONFIG.clientId,
+        username: "machine-agt_01TEST",
+        sub: "machine-sub",
+      }),
+      idToken: fakeJwt({
+        token_use: "id",
+        aud: CONFIG.clientId,
+        "custom:entityType": "agent",
+        "custom:entityUid": "agt_01TEST",
+        "cognito:username": "machine-agt_01TEST",
+        sub: "machine-sub",
+      }),
+      refreshToken: "",
+      expiresAt: Date.now() + 30 * 60 * 1000,
+      tokenType: "Bearer" as const,
+    };
+    saveCachedTokens(cached);
+    fs.writeFileSync(
+      path.join(tmpHome, ".hq", "cognito-tokens.json.lock"),
+      String(process.pid),
+    );
+    vi.useFakeTimers();
+
+    const resolution = getValidMachineTokens(CONFIG);
+    await vi.advanceTimersByTimeAsync(20_050);
+
+    await expect(resolution).resolves.toEqual(cached);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects a legacy non-empty-refresh cache after a lock timeout without minting unlocked", async () => {
+    writeCreds();
+    const { fetchMock } = stubMintFetch();
+    const {
+      saveCachedTokens,
+      getValidMachineTokens,
+      CognitoAuthError,
+    } = await importModule();
+    saveCachedTokens({
+      accessToken: fakeJwt({
+        token_use: "access",
+        client_id: CONFIG.clientId,
+        username: "machine-agt_01TEST",
+        sub: "machine-sub",
+      }),
+      idToken: fakeJwt({
+        token_use: "id",
+        aud: CONFIG.clientId,
+        "custom:entityType": "agent",
+        "custom:entityUid": "agt_01TEST",
+        "cognito:username": "machine-agt_01TEST",
+        sub: "machine-sub",
+      }),
+      refreshToken: "legacy-refresh",
+      expiresAt: Date.now() + 30 * 60 * 1000,
+      tokenType: "Bearer",
+    });
+    fs.writeFileSync(
+      path.join(tmpHome, ".hq", "cognito-tokens.json.lock"),
+      String(process.pid),
+    );
+    vi.useFakeTimers();
+
+    const resolution = getValidMachineTokens(CONFIG);
+    const rejection = expect(resolution).rejects.toBeInstanceOf(
+      CognitoAuthError,
+    );
+    await vi.advanceTimersByTimeAsync(20_050);
+
+    await rejection;
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -406,6 +977,226 @@ describe("regression: constant mints regardless of file count", () => {
       expect(fetchMock).toHaveBeenCalledTimes(1);
     },
   );
+
+  it("serializes independent module instances through the shared cache lock", async () => {
+    const username = "machine-agt_01TEST";
+    writeCreds({
+      username,
+      secret: "s3cret",
+      entityType: "agent",
+      entityUid: "agt_01TEST",
+    });
+    let releaseMint: (() => void) | undefined;
+    const mintGate = new Promise<void>((resolve) => {
+      releaseMint = resolve;
+    });
+    let signalMintStarted: (() => void) | undefined;
+    const mintStarted = new Promise<void>((resolve) => {
+      signalMintStarted = resolve;
+    });
+    const accessToken = fakeJwt({
+      token_use: "access",
+      client_id: CONFIG.clientId,
+      username,
+      sub: "machine-sub",
+    });
+    const idToken = fakeJwt({
+      token_use: "id",
+      aud: CONFIG.clientId,
+      "custom:entityType": "agent",
+      "custom:entityUid": "agt_01TEST",
+      "cognito:username": username,
+      sub: "machine-sub",
+    });
+    const fetchMock = vi.fn(async () => {
+      signalMintStarted?.();
+      await mintGate;
+      return new Response(
+        JSON.stringify({
+          AuthenticationResult: {
+            AccessToken: accessToken,
+            IdToken: idToken,
+            RefreshToken: "must-not-be-stored",
+            ExpiresIn: 3600,
+          },
+        }),
+        { status: 200 },
+      );
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const firstProcessModule = await importModule();
+    vi.resetModules();
+    const secondProcessModule = await importModule();
+
+    const first = firstProcessModule.getValidMachineTokens(CONFIG);
+    await mintStarted;
+    const second = secondProcessModule.getValidMachineTokens(CONFIG);
+    releaseMint?.();
+
+    const [firstTokens, secondTokens] = await Promise.all([first, second]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(secondTokens).toEqual(firstTokens);
+    expect(secondProcessModule.loadCachedTokens()?.refreshToken).toBe("");
+  });
+
+  it("serializes the exported direct mint API", async () => {
+    writeCreds();
+    let releaseFirstMint: (() => void) | undefined;
+    const firstMintGate = new Promise<void>((resolve) => {
+      releaseFirstMint = resolve;
+    });
+    let signalFirstMint: (() => void) | undefined;
+    const firstMintStarted = new Promise<void>((resolve) => {
+      signalFirstMint = resolve;
+    });
+    let activeMints = 0;
+    let maxActiveMints = 0;
+    let callCount = 0;
+    const accessToken = fakeJwt({
+      token_use: "access",
+      client_id: CONFIG.clientId,
+      username: "machine-agt_01TEST",
+      sub: "machine-sub",
+    });
+    const idToken = fakeJwt({
+      token_use: "id",
+      aud: CONFIG.clientId,
+      "custom:entityType": "agent",
+      "custom:entityUid": "agt_01TEST",
+      "cognito:username": "machine-agt_01TEST",
+      sub: "machine-sub",
+    });
+    const fetchMock = vi.fn(async () => {
+      callCount += 1;
+      activeMints += 1;
+      maxActiveMints = Math.max(maxActiveMints, activeMints);
+      if (callCount === 1) {
+        signalFirstMint?.();
+        await firstMintGate;
+      }
+      activeMints -= 1;
+      return new Response(
+        JSON.stringify({
+          AuthenticationResult: {
+            AccessToken: accessToken,
+            IdToken: idToken,
+            ExpiresIn: 3600,
+          },
+        }),
+        { status: 200 },
+      );
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const firstModule = await importModule();
+    vi.resetModules();
+    const secondModule = await importModule();
+
+    const first = firstModule.mintMachineTokens(CONFIG);
+    await firstMintStarted;
+    const second = secondModule.mintMachineTokens(CONFIG);
+    releaseFirstMint?.();
+    await Promise.all([first, second]);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(maxActiveMints).toBe(1);
+  });
+
+  it("serializes direct mints in actual separate processes", async () => {
+    const moduleUrl = pathToFileURL(
+      path.join(process.cwd(), "src", "cognito-auth.ts"),
+    ).href;
+    const marker = path.join(tmpHome, "mint-active");
+    const overlap = path.join(tmpHome, "mint-overlap");
+    const start = path.join(tmpHome, "mint-start");
+    const childScript = String.raw`
+      import fs from "fs";
+      const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+      const fakeJwt = (claims) => {
+        const enc = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+        return enc({ alg: "none" }) + "." + enc(claims) + ".sig";
+      };
+      const auth = await import(process.env.HQ_LOCK_TEST_MODULE_URL);
+      fs.writeFileSync(process.env.HQ_LOCK_TEST_READY, "ready");
+      while (!fs.existsSync(process.env.HQ_LOCK_TEST_START)) await pause(5);
+      globalThis.fetch = async () => {
+        let ownsMarker = false;
+        try {
+          const fd = fs.openSync(process.env.HQ_LOCK_TEST_MARKER, "wx");
+          fs.closeSync(fd);
+          ownsMarker = true;
+        } catch (error) {
+          if (error.code === "EEXIST") {
+            fs.writeFileSync(process.env.HQ_LOCK_TEST_OVERLAP, "overlap");
+          } else {
+            throw error;
+          }
+        }
+        await pause(125);
+        if (ownsMarker) fs.unlinkSync(process.env.HQ_LOCK_TEST_MARKER);
+        return new Response(JSON.stringify({ AuthenticationResult: {
+          AccessToken: fakeJwt({ token_use: "access", client_id: "test-client-id", username: "machine", sub: "sub" }),
+          IdToken: fakeJwt({ token_use: "id", aud: "test-client-id", "custom:entityType": "agent", "custom:entityUid": "agt_TEST", "cognito:username": "machine", sub: "sub" }),
+          ExpiresIn: 3600
+        }}), { status: 200 });
+      };
+      await auth.mintMachineTokens(
+        { region: "us-east-1", userPoolDomain: "unused", clientId: "test-client-id" },
+        { username: "machine", secret: "secret", entityType: "agent", entityUid: "agt_TEST" },
+        { baseDelayMs: 0 }
+      );
+    `;
+    const children = ["a", "b"].map((name) => {
+      const child = spawn(
+        process.execPath,
+        ["--experimental-strip-types", "--input-type=module", "-e", childScript],
+        {
+          cwd: process.cwd(),
+          env: {
+            ...process.env,
+            HOME: tmpHome,
+            HQ_LOCK_TEST_MODULE_URL: moduleUrl,
+            HQ_LOCK_TEST_READY: path.join(tmpHome, `ready-${name}`),
+            HQ_LOCK_TEST_START: start,
+            HQ_LOCK_TEST_MARKER: marker,
+            HQ_LOCK_TEST_OVERLAP: overlap,
+          },
+        },
+      );
+      let stderr = "";
+      child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+      });
+      return { child, stderr: () => stderr };
+    });
+    const readyPaths = ["a", "b"].map((name) =>
+      path.join(tmpHome, `ready-${name}`),
+    );
+    const readyDeadline = Date.now() + 5_000;
+    while (
+      !readyPaths.every((readyPath) => fs.existsSync(readyPath)) &&
+      Date.now() < readyDeadline
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    expect(readyPaths.every((readyPath) => fs.existsSync(readyPath))).toBe(true);
+    fs.writeFileSync(start, "start");
+
+    const exits = await Promise.all(
+      children.map(
+        ({ child, stderr }) =>
+          new Promise<{ code: number | null; stderr: string }>((resolve) => {
+            child.on("exit", (code) => resolve({ code, stderr: stderr() }));
+          }),
+      ),
+    );
+
+    expect(exits).toEqual([
+      { code: 0, stderr: "" },
+      { code: 0, stderr: "" },
+    ]);
+    expect(fs.existsSync(overlap)).toBe(false);
+  }, 10_000);
 });
 
 // ---------------------------------------------------------------------------
@@ -431,8 +1222,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,
           },
         }),