@indigoai-us/hq-cloud 6.11.10 → 6.11.12

package/src/cli/sync.ts

@@ -35,6 +35,7 @@ import {
   PERSONAL_VAULT_JOURNAL_SLUG,
   migratePersonalVaultJournal,
 } from "../journal.js";
+import { PERSONAL_VAULT_MANIFEST_KEY } from "../personal-vault.js";
 import {
   buildScopeShrinkPlan,
   applyScopeShrink,
@@ -42,7 +43,11 @@ import {
   ScopeShrinkLargePruneError,
   type ScopeShrinkAdviceContext,
 } from "../scope-shrink.js";
-import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
+import {
+  coalescePrefixes,
+  isCoveredByAny,
+  type ScopePrefixInput,
+} from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { isEphemeralPath, isMalformedVaultKey } from "./share.js";
 import { resolveConflict } from "./conflict.js";
@@ -54,6 +59,7 @@ import {
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
 import { reindex } from "./reindex.js";
+import { withOperationLock } from "../operation-lock.js";
 import {
   fetchCompanyTombstones,
   type CompanyTombstone,
@@ -368,7 +374,7 @@ export interface SyncOptions {
    * (not empty `"shared"`) on any grant-resolution error, so a transient
    * failure can never silently prune the local tree.
    */
-  prefixSet?: string[];
+  prefixSet?: ScopePrefixInput[];
   /**
    * When the effective scope shrinks relative to the last pull and the shrink
    * would orphan locally-modified ("dirty") files, `sync()` aborts with a
@@ -413,6 +419,11 @@ export interface SyncOptions {
    * this and run `reindex()` once itself instead of per-company.
    */
   skipReindex?: boolean;
+  /**
+   * Internal runner seam: true only when the caller already holds the
+   * per-root operation lock for this sync pass.
+   */
+  operationLockAlreadyHeld?: boolean;
 }
 
 export interface SyncResult {
@@ -496,6 +507,16 @@ export function resolveAutoPruneCap(): number {
 /** Max time to wait on the best-effort new-files notification POST. */
 const NOTIFY_FILE_ADDED_TIMEOUT_MS = 5000;
 
+/**
+ * Server cap on files per `/v1/notify/file-added` report. The endpoint rejects
+ * an oversized batch wholesale, so the client MUST split a large report into
+ * chunks at or under this size — otherwise a first sync with more than this many
+ * new files reports none of them, and the same oversized batch re-triggers every
+ * sync cycle (wasted work + dropped notifications). Keep in lockstep with the
+ * server-side limit.
+ */
+const NOTIFY_FILE_ADDED_MAX_BATCH = 1000;
+
 /**
  * Best-effort report of the files that were new to this drive during the sync,
  * so the HQ Sync app can show a persistent cross-session "new files" history.
@@ -504,22 +525,36 @@ const NOTIFY_FILE_ADDED_TIMEOUT_MS = 5000;
  * FILE_EVENT rows for the calling user (the one the files are new for). Fully
  * non-fatal: any error, non-2xx, or timeout is swallowed — the durable signal
  * is the synced file itself; this is only a notification mirror. Bounded by a
- * 5s timeout so a hung endpoint can't stall sync completion. No-op when there
- * are no new files.
+ * 5s timeout PER request so a hung endpoint can't stall sync completion. No-op
+ * when there are no new files.
+ *
+ * Large reports are split into chunks of at most NOTIFY_FILE_ADDED_MAX_BATCH
+ * files (the server's per-report cap). Each chunk is POSTed independently and
+ * best-effort, so one failing/oversized batch can never block the others or the
+ * sync. Exported only so the chunking can be unit-tested directly.
  */
-async function reportNewFilesToNotify(
+export async function reportNewFilesToNotify(
   vaultConfig: VaultServiceConfig,
   companyUid: string,
   companySlug: string,
   files: Array<{ path: string; bytes: number; addedBy: string | null }>,
 ): Promise<void> {
   if (files.length === 0) return;
+
+  let token: string;
   try {
-    const token =
+    token =
       typeof vaultConfig.authToken === "function"
         ? await vaultConfig.authToken()
         : vaultConfig.authToken;
-    const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+  } catch (err) {
+    logNotifyFailure(err);
+    return;
+  }
+  const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+
+  for (let i = 0; i < files.length; i += NOTIFY_FILE_ADDED_MAX_BATCH) {
+    const batch = files.slice(i, i + NOTIFY_FILE_ADDED_MAX_BATCH);
     const controller = new AbortController();
     const timer = setTimeout(
       () => controller.abort(),
@@ -535,7 +570,7 @@ async function reportNewFilesToNotify(
         body: JSON.stringify({
           companyUid,
           companySlug,
-          files: files.map((f) => ({
+          files: batch.map((f) => ({
             path: f.path,
             bytes: f.bytes,
             ...(f.addedBy ? { addedBy: f.addedBy } : {}),
@@ -543,20 +578,26 @@ async function reportNewFilesToNotify(
         }),
         signal: controller.signal,
       });
+    } catch (err) {
+      // Best-effort per chunk: never let notification reporting affect the sync
+      // result, and a failed chunk must not abort the remaining chunks.
+      logNotifyFailure(err);
     } finally {
       clearTimeout(timer);
     }
-  } catch (err) {
-    // Best-effort: never let notification reporting affect the sync result.
-    try {
-      console.error(
-        `[hq-sync] new-files notify report failed (non-fatal): ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    } catch {
-      // swallow — logging must never break sync
-    }
+  }
+}
+
+/** Log a non-fatal notify failure without ever throwing out of the logger. */
+function logNotifyFailure(err: unknown): void {
+  try {
+    console.error(
+      `[hq-sync] new-files notify report failed (non-fatal): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  } catch {
+    // swallow — logging must never break sync
   }
 }
 
@@ -564,6 +605,17 @@ async function reportNewFilesToNotify(
  * Sync (pull) all allowed files from the entity vault.
  */
 export async function sync(options: SyncOptions): Promise<SyncResult> {
+  if (options.operationLockAlreadyHeld) {
+    return syncWithOperationLockHeld(options);
+  }
+  return withOperationLock(options.hqRoot, "sync", () =>
+    syncWithOperationLockHeld(options),
+  );
+}
+
+async function syncWithOperationLockHeld(
+  options: SyncOptions,
+): Promise<SyncResult> {
   const { company, onConflict, vaultConfig, hqRoot } = options;
   const emit = options.onEvent ?? defaultConsoleLogger;
 
@@ -897,16 +949,17 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       const tombstoneKey = item.remoteFile.key;
       // Same Windows-backslash landmine guard as the journal-tombstone executor:
       // a malformed key must never reach fs.unlinkSync (path.join collapses the
-      // backslashes onto a REAL POSIX file). Drop the poisoned journal entry
-      // without touching disk.
-      if (isMalformedVaultKey(tombstoneKey)) {
-        removeEntry(journal, tombstoneKey);
-        continue;
-      }
+      // backslashes onto a REAL POSIX file). Traversal keys are likewise
+      // refused before any local filesystem or journal mutation.
+      const tombstonePath = resolveContainedVaultPath(companyRoot, tombstoneKey);
+      if (tombstonePath === null) continue;
       try {
-        const lstat = fs.lstatSync(item.localPath);
+        const lstat = fs.lstatSync(tombstonePath);
+        if (tombstoneTargetDiverged(journal, tombstoneKey, tombstonePath, lstat)) {
+          continue;
+        }
         if (lstat.isSymbolicLink() || lstat.isFile()) {
-          fs.unlinkSync(item.localPath);
+          fs.unlinkSync(tombstonePath);
         }
         // A directory at the key: don't recursively rm-rf the operator's dir;
         // just drop the journal entry (safe-by-default, same as the other path).
@@ -984,11 +1037,22 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         machineId,
       );
       const conflictAbs = path.join(hqRoot, conflictRelative);
+      const conflictKey = toPosixKey(path.relative(companyRoot, conflictAbs));
+
+      if (!isDownloadWritePathStillContained(companyRoot, conflictKey, conflictAbs)) {
+        filesSkipped++;
+        emit({
+          type: "error",
+          path: remoteFile.key,
+          message: "conflict mirror skipped: local parent escaped the sync root",
+        });
+        continue;
+      }
 
       let remoteFetched = false;
       let converged = false;
       try {
-        await downloadFile(ctx, remoteFile.key, conflictAbs);
+        const downloaded = await downloadFile(ctx, remoteFile.key, conflictAbs);
         remoteFetched = true;
         // Hash the fetched remote exactly the way the planner hashed local
         // (symlink-aware) so the two hashes are directly comparable. A
@@ -996,7 +1060,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         // target string matches `hashSymlinkTarget(localPath)`.
         const remoteHash = fs.lstatSync(conflictAbs).isSymbolicLink()
           ? hashSymlinkTarget(fs.readlinkSync(conflictAbs))
-          : hashFile(conflictAbs);
+          : (downloaded.contentHash ?? hashFile(conflictAbs));
         converged = remoteHash === item.localHash;
       } catch (probeErr) {
         // Couldn't fetch or hash the remote — fail safe by falling through to
@@ -1211,8 +1275,22 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         ctx = await refreshEntityContext(companyRef, vaultConfig);
       }
 
+      if (!isDownloadWritePathStillContained(companyRoot, remoteFile.key, localPath)) {
+        filesSkipped++;
+        emit({
+          type: "error",
+          path: remoteFile.key,
+          message: "download skipped: local parent escaped the sync root",
+        });
+        return;
+      }
+
       try {
-        const { metadata } = await downloadFile(ctx, remoteFile.key, localPath);
+        const { metadata, contentHash, contentSize } = await downloadFile(
+          ctx,
+          remoteFile.key,
+          localPath,
+        );
         const author = metadata?.["created-by"] ?? null;
         // Author sub for the scope-shrink authorship guard — same field the
         // upload side stamps, read straight off the GET response metadata.
@@ -1231,8 +1309,8 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         const isLocalSymlink = localLstat.isSymbolicLink();
         const hash = isLocalSymlink
           ? hashSymlinkTarget(fs.readlinkSync(localPath))
-          : hashFile(localPath);
-        const size = isLocalSymlink ? 0 : fs.statSync(localPath).size;
+          : (contentHash ?? hashFile(localPath));
+        const size = isLocalSymlink ? 0 : (contentSize ?? fs.statSync(localPath).size);
         // Capture the listing's ETag so subsequent syncs can detect remote
         // drift independently of mtime drift. Stamp mtimeMs from localLstat
         // (5.36.0) so the next push planner's lstat fast-path can skip the
@@ -1429,21 +1507,16 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   // converged. Failures are reported but non-fatal — the entry stays in
   // the journal and the next run retries.
   for (const key of plan.tombstones) {
-    // Last line of defense against the Windows backslash-key landmine: a
-    // malformed key must NEVER reach fs.unlinkSync. path.join(companyRoot, key)
-    // collapses the backslashes and resolves onto the REAL POSIX file, so
-    // unlinking here destroys live data (ridge incident, feedback_b8d09d0f).
-    // The planner already refuses to enqueue malformed keys; if one still
-    // arrives, drop the poisoned journal entry without touching disk —
-    // normalizeJournalKeys rewrites it to its POSIX form on load.
-    if (isMalformedVaultKey(key)) {
-      removeEntry(journal, key);
-      continue;
-    }
-    const localPath = path.join(companyRoot, key);
+    // Last line of defense: a malformed or traversal key must NEVER reach
+    // fs.unlinkSync or journal mutation for a path outside the sync root.
+    const localPath = resolveContainedVaultPath(companyRoot, key);
+    if (localPath === null) continue;
     let removedSomething = false;
     try {
       const lstat = fs.lstatSync(localPath);
+      if (tombstoneTargetDiverged(journal, key, localPath, lstat)) {
+        continue;
+      }
       if (lstat.isSymbolicLink() || lstat.isFile()) {
         fs.unlinkSync(localPath);
         removedSomething = true;
@@ -1614,6 +1687,99 @@ function isRemoteRecreateAfterTombstone(
   return remoteMs > deletedAtMs;
 }
 
+function hasTraversalSegment(key: string): boolean {
+  return key.split("/").some((segment) => segment === "..");
+}
+
+function isPathWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+function deepestExistingAncestor(start: string): string | null {
+  let current = start;
+  for (;;) {
+    try {
+      fs.lstatSync(current);
+      return current;
+    } catch (err: unknown) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function resolveContainedVaultPath(root: string, key: string): string | null {
+  if (isMalformedVaultKey(key) || hasTraversalSegment(key)) return null;
+
+  const resolvedRoot = path.resolve(root);
+  const resolvedLocal = path.resolve(resolvedRoot, key);
+  if (!isPathWithin(resolvedRoot, resolvedLocal)) return null;
+
+  let realRoot: string;
+  try {
+    realRoot = fs.realpathSync.native(resolvedRoot);
+  } catch {
+    // If the vault root does not exist yet, no below-root symlink component can
+    // already exist to redirect this key. Preserve first-pull behavior.
+    return resolvedLocal;
+  }
+
+  const existingAncestor = deepestExistingAncestor(path.dirname(resolvedLocal));
+  if (existingAncestor === null) return null;
+  try {
+    const realAncestor = fs.realpathSync.native(existingAncestor);
+    if (!isPathWithin(realRoot, realAncestor)) return null;
+  } catch {
+    return null;
+  }
+  return resolvedLocal;
+}
+
+function isDownloadWritePathStillContained(
+  root: string,
+  key: string,
+  localPath: string,
+): boolean {
+  const resolved = resolveContainedVaultPath(root, key);
+  return resolved !== null && path.resolve(resolved) === path.resolve(localPath);
+}
+
+function tombstoneTargetDiverged(
+  journal: SyncJournal,
+  key: string,
+  localPath: string,
+  lstat: fs.Stats,
+): boolean {
+  const journalEntry = journal.files[key];
+  if (!journalEntry?.hash) {
+    return lstat.isSymbolicLink() || lstat.isFile();
+  }
+
+  try {
+    if (lstat.isSymbolicLink()) {
+      return hashSymlinkTarget(fs.readlinkSync(localPath)) !== journalEntry.hash;
+    }
+    if (lstat.isFile()) {
+      return hashFile(localPath) !== journalEntry.hash;
+    }
+  } catch {
+    return true;
+  }
+
+  return false;
+}
+
 /**
  * Stage-1 classification for a single remote object. Each remote file falls
  * into exactly one bucket; the executor in `sync()` switches on `action` to
@@ -1715,7 +1881,7 @@ function computePullPlan(
   // Coalesced, company-relative prefixes the pull is scoped to (US-005).
   // `[""]` (the `all`-mode value) covers everything via `isCoveredByAny`, so
   // the scope filter below becomes a no-op and legacy behavior is preserved.
-  prefixSet: string[],
+  prefixSet: readonly ScopePrefixInput[],
   // FILE_TOMBSTONE records (POSIX-keyed) for the company — the durable
   // "this key was intentionally deleted" signal the planner consults before
   // re-downloading a key, so a deleted folder does not resync back in
@@ -1727,7 +1893,11 @@ function computePullPlan(
   const items: PullPlanItem[] = [];
 
   for (const remoteFile of remoteFiles) {
-    const localPath = path.join(companyRoot, remoteFile.key);
+    const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
+    if (localPath === null) {
+      items.push({ action: "skip-excluded-policy", remoteFile, localPath: companyRoot });
+      continue;
+    }
 
     // Ephemeral-mirror filter — symmetric with the push-side walker. Bug #2
     // in the 5.33.0 deep-test: the push side has refused to upload conflict
@@ -1740,18 +1910,17 @@ function computePullPlan(
       continue;
     }
 
-    // Malformed-key filter — keys with backslash separators pushed by
-    // pre-5.47.2 Windows clients. Downloading one materializes a junk local
-    // file whose NAME contains backslashes (it is not a path on POSIX), which
-    // then churns conflict mirrors forever. Refuse at planning time, same
-    // policy bucket as the ephemeral filter above. The bogus keys themselves
-    // are cleaned server-side; this keeps clean trees clean in the meantime.
-    if (isMalformedVaultKey(remoteFile.key)) {
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-      continue;
-    }
-
-    if (personalMode && remoteFile.key.startsWith("companies/")) {
+    if (
+      personalMode &&
+      remoteFile.key.startsWith("companies/") &&
+      // EXEMPTION: companies/manifest.yaml is the routing source-of-truth
+      // carved INTO the personal vault on the push side
+      // (computePersonalVaultPaths). It must round-trip on the pull leg too —
+      // skipping it here leaves it forever unjournaled, which re-fires a
+      // transient push-side conflict every sync (no journal baseline). Let it
+      // fall through to download + journal like any personal file.
+      remoteFile.key !== PERSONAL_VAULT_MANIFEST_KEY
+    ) {
       // Default: drop every `companies/...` key — the legacy contract
       // is that the personal bucket should never contain them.
       //
@@ -2101,12 +2270,8 @@ function computePullPlan(
     // POSIX compare is defense-in-depth (ridge data-loss, feedback_b8d09d0f).
     const posixKey = toPosixKey(key);
     if (remoteKeySet.has(posixKey)) continue;
-    // Never tombstone-delete via a malformed (backslash) key: the executor's
-    // path.join(companyRoot, key) collapses backslashes back onto the REAL
-    // POSIX file and unlinks live data. Leave it for normalizeJournalKeys to
-    // rewrite to POSIX on the next write; the canonical key is re-evaluated
-    // (and correctly tombstoned if genuinely remote-deleted) on a later pull.
-    if (isMalformedVaultKey(key)) continue;
+    const localPath = resolveContainedVaultPath(companyRoot, key);
+    if (localPath === null) continue;
     // PersonalMode key gating — mirror the download branch.
     if (personalMode && key.startsWith("companies/")) {
       const slug = key.split("/")[1] ?? "";
@@ -2120,7 +2285,6 @@ function computePullPlan(
     // Honor the current ignore filter — if a path was previously synced
     // but is now ignored (operator edited .hqignore), do NOT delete
     // the local copy. They're keeping it deliberately.
-    const localPath = path.join(companyRoot, key);
     if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
     // Codex P1 (PR #24 round 3): detect local edits before tombstoning.
     // Delete-vs-local-edit race: peer deleted the file remotely while

package/src/cognito-auth.test.ts

@@ -198,6 +198,83 @@ describe("getValidAccessToken stale-pool detection", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Machine identity cache isolation — machine mode must not reuse human tokens
+// from the shared Cognito cache even when the app client matches.
+// ---------------------------------------------------------------------------
+
+describe("machine identity cache isolation", () => {
+  it("F06: machine mode re-mints instead of reusing a cached human token", async () => {
+    const { saveCachedTokens, getValidAccessToken } = await importModule();
+
+    const cachedHumanAccessToken = makeAccessToken({
+      token_use: "access",
+      client_id: PROD_CLIENT,
+      username: "human@example.com",
+      sub: "human-sub",
+    });
+    const cachedHumanIdToken = makeAccessToken({
+      token_use: "id",
+      aud: PROD_CLIENT,
+      email: "human@example.com",
+      "cognito:username": "human@example.com",
+      sub: "human-sub",
+    });
+    saveCachedTokens({
+      ...baseTokens,
+      accessToken: cachedHumanAccessToken,
+      idToken: cachedHumanIdToken,
+      expiresAt: Date.now() + 60 * 60 * 1000,
+    });
+
+    const machineUid = "agt_01JZ0000000000000000000000";
+    const machineCredsDir = path.join(tmpHome, ".hq-agent");
+    fs.mkdirSync(machineCredsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(machineCredsDir, "machine-creds.json"),
+      JSON.stringify({
+        username: "agt-01jz0000000000000000000000@agents.getindigo.ai",
+        secret: "machine-secret",
+        clientId: PROD_CLIENT,
+        region: "us-east-1",
+      }),
+    );
+
+    const mintedMachineAccessToken = makeAccessToken({
+      token_use: "access",
+      client_id: PROD_CLIENT,
+      username: "agt-01jz0000000000000000000000@agents.getindigo.ai",
+      sub: machineUid,
+    });
+    const mintedMachineIdToken = makeAccessToken({
+      token_use: "id",
+      aud: PROD_CLIENT,
+      "custom:entityType": "agent",
+      "custom:entityUid": machineUid,
+      "cognito:username": "agt-01jz0000000000000000000000@agents.getindigo.ai",
+      sub: machineUid,
+    });
+    const fetchMock = vi.fn(async () =>
+      new Response(
+        JSON.stringify({
+          AuthenticationResult: {
+            AccessToken: mintedMachineAccessToken,
+            IdToken: mintedMachineIdToken,
+            ExpiresIn: 3600,
+          },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(
+      getValidAccessToken(baseConfig, { interactive: false }),
+    ).resolves.toBe(mintedMachineIdToken);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Round-trip: writers emit epoch-ms, readers read epoch-ms
 // ---------------------------------------------------------------------------

package/src/cognito-auth.ts

@@ -134,19 +134,80 @@ export function isExpiring(tokens: CognitoTokens, bufferSeconds = 60): boolean {
  * forcing a re-login is the only safe self-heal.
  */
 export function decodeAccessTokenClientId(accessToken: string): string | null {
+  const claims = decodeJwtClaims(accessToken);
+  return typeof claims?.client_id === "string" ? claims.client_id : null;
+}
+
+function decodeJwtClaims(token: string): Record<string, unknown> | null {
   try {
-    const parts = accessToken.split(".");
+    const parts = token.split(".");
     if (parts.length < 2) return null;
     const payloadB64 = parts[1];
-    const padded = payloadB64 + "=".repeat((4 - (payloadB64.length % 4)) % 4);
+    const normalized = payloadB64.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
     const json = Buffer.from(padded, "base64").toString("utf-8");
-    const claims = JSON.parse(json) as { client_id?: unknown };
-    return typeof claims.client_id === "string" ? claims.client_id : null;
+    const claims = JSON.parse(json);
+    return claims && typeof claims === "object" && !Array.isArray(claims)
+      ? (claims as Record<string, unknown>)
+      : null;
   } catch {
     return null;
   }
 }
 
+function cachedTokensMatchMachineIdentity(
+  tokens: CognitoTokens,
+  creds: MachineCreds,
+  expectedClientId: string,
+): boolean {
+  const accessClaims = decodeJwtClaims(tokens.accessToken);
+  const idClaims = decodeJwtClaims(tokens.idToken);
+  if (!accessClaims || !idClaims) return false;
+
+  const stringClaim = (
+    claims: Record<string, unknown>,
+    key: string,
+  ): string | null => {
+    const value = claims[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+  };
+
+  const accessClientId = accessClaims.client_id;
+  const idAudience = idClaims.aud;
+  const accessUsername =
+    stringClaim(accessClaims, "username") ??
+    stringClaim(accessClaims, "cognito:username");
+  const accessSub = stringClaim(accessClaims, "sub");
+  const idUsername =
+    stringClaim(idClaims, "cognito:username") ?? stringClaim(idClaims, "username");
+  const idSub = stringClaim(idClaims, "sub");
+  const entityType = idClaims["custom:entityType"];
+  const entityUid = idClaims["custom:entityUid"];
+  const idTokenMatchesCreds =
+    idUsername === creds.username || idSub === creds.username;
+  const subjectBindings: boolean[] = [];
+  if (accessUsername !== null && idUsername !== null) {
+    subjectBindings.push(accessUsername === idUsername);
+  }
+  if (accessSub !== null && idSub !== null) {
+    subjectBindings.push(accessSub === idSub);
+  }
+  const tokensShareSubject =
+    subjectBindings.length > 0 && subjectBindings.every(Boolean);
+
+  return (
+    accessClaims.token_use === "access" &&
+    accessClientId === expectedClientId &&
+    idClaims.token_use === "id" &&
+    idAudience === expectedClientId &&
+    entityType === "agent" &&
+    typeof entityUid === "string" &&
+    entityUid.startsWith("agt_") &&
+    idTokenMatchesCreds &&
+    tokensShareSubject
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Machine identity (company agents)
 // ---------------------------------------------------------------------------
@@ -309,17 +370,18 @@ export async function mintMachineTokens(
 export async function getValidMachineTokens(
   config: CognitoAuthConfig,
 ): Promise<CognitoTokens> {
+  const machineCreds = loadMachineCreds();
   const cached = loadCachedTokens();
-  if (cached && !isExpiring(cached, 120)) {
-    const cachedClientId = decodeAccessTokenClientId(cached.accessToken);
-    // Compare against the client we'd actually mint with (creds-file
-    // clientId wins over config).
-    const expectedClientId = loadMachineCreds()?.clientId ?? config.clientId;
-    if (cachedClientId === null || cachedClientId === expectedClientId) {
+  if (machineCreds && cached && !isExpiring(cached, 120)) {
+    // Compare against the client we'd actually mint with (creds-file clientId
+    // wins over config), and require the cached ID token to prove this exact
+    // agent identity. Opaque/missing/human-shaped claims are treated as stale.
+    const expectedClientId = machineCreds.clientId ?? config.clientId;
+    if (cachedTokensMatchMachineIdentity(cached, machineCreds, expectedClientId)) {
       return cached;
     }
   }
-  return mintMachineTokens(config);
+  return mintMachineTokens(config, machineCreds ?? undefined);
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -62,6 +62,14 @@ export {
   coalescePrefixes,
   isCoveredByAny,
   grantPathToPrefix,
+  grantPathToScopePrefix,
+  pathToScopePrefix,
+  toScopePrefixEntries,
+} from "./prefix-coalesce.js";
+export type {
+  ScopePrefixEntry,
+  ScopePrefixInput,
+  ScopePrefixMatch,
 } from "./prefix-coalesce.js";
 
 // Scope-shrink detection + application (US-005)