@indigoai-us/hq-cloud 6.11.10 → 6.11.12

package/dist/cli/sync.d.ts

@@ -6,6 +6,7 @@
  */
 import type { VaultServiceConfig } from "../types.js";
 import type { SyncMode } from "../vault-client.js";
+import { type ScopePrefixInput } from "../prefix-coalesce.js";
 import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
 /**
  * Per-file events emitted by `sync()` as it progresses.
@@ -312,7 +313,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
@@ -357,6 +358,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 {
     filesDownloaded: number;
@@ -431,6 +437,27 @@ export interface SyncResult {
  * `HQ_SYNC_MAX_AUTO_PRUNE`.
  */
 export declare function resolveAutoPruneCap(): number;
+/**
+ * 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.
+ *
+ * POSTs to `${apiUrl}/v1/notify/file-added`, which writes per-recipient
+ * 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 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.
+ */
+export declare function reportNewFilesToNotify(vaultConfig: VaultServiceConfig, companyUid: string, companySlug: string, files: Array<{
+    path: string;
+    bytes: number;
+    addedBy: string | null;
+}>): Promise<void>;
 /**
  * Sync (pull) all allowed files from the entity vault.
  */

package/dist/cli/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"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"}

package/dist/cli/sync.js

@@ -9,14 +9,16 @@ import * as path from "path";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { downloadFile, listRemoteFiles, headRemoteFile, primeObjectTransport, toPosixKey, } from "../s3.js";
 import { readJournal, writeJournal, hashFile, hashSymlinkTarget, updateEntry, removeEntry, getEntry, normalizeEtag, migrateToV2, gcTombstones, lastPullRecord, appendPullRecord, generatePullId, PERSONAL_VAULT_JOURNAL_SLUG, migratePersonalVaultJournal, } from "../journal.js";
+import { PERSONAL_VAULT_MANIFEST_KEY } from "../personal-vault.js";
 import { buildScopeShrinkPlan, applyScopeShrink, ScopeShrinkBlockedError, ScopeShrinkLargePruneError, } from "../scope-shrink.js";
-import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
+import { coalescePrefixes, isCoveredByAny, } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { isEphemeralPath, isMalformedVaultKey } from "./share.js";
 import { resolveConflict } from "./conflict.js";
 import { buildConflictId, buildConflictPath, readShortMachineId, } 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, } from "./tombstones.js";
 /**
  * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
@@ -35,6 +37,15 @@ export function resolveAutoPruneCap() {
 }
 /** 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.
@@ -43,17 +54,31 @@ 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(vaultConfig, companyUid, companySlug, files) {
+export async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, files) {
     if (files.length === 0)
         return;
+    let token;
     try {
-        const token = typeof vaultConfig.authToken === "function"
-            ? await vaultConfig.authToken()
-            : vaultConfig.authToken;
-        const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+        token =
+            typeof vaultConfig.authToken === "function"
+                ? await vaultConfig.authToken()
+                : vaultConfig.authToken;
+    }
+    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(), NOTIFY_FILE_ADDED_TIMEOUT_MS);
         try {
@@ -66,7 +91,7 @@ async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, file
                 body: JSON.stringify({
                     companyUid,
                     companySlug,
-                    files: files.map((f) => ({
+                    files: batch.map((f) => ({
                         path: f.path,
                         bytes: f.bytes,
                         ...(f.addedBy ? { addedBy: f.addedBy } : {}),
@@ -75,24 +100,35 @@ async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, file
                 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) {
+    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
     }
 }
 /**
  * Sync (pull) all allowed files from the entity vault.
  */
 export async function sync(options) {
+    if (options.operationLockAlreadyHeld) {
+        return syncWithOperationLockHeld(options);
+    }
+    return withOperationLock(options.hqRoot, "sync", () => syncWithOperationLockHeld(options));
+}
+async function syncWithOperationLockHeld(options) {
     const { company, onConflict, vaultConfig, hqRoot } = options;
     const emit = options.onEvent ?? defaultConsoleLogger;
     // Resolve company
@@ -376,16 +412,18 @@ export async function sync(options) {
             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);
+            // 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).
@@ -453,10 +491,20 @@ export async function sync(options) {
             const originalRelative = path.relative(hqRoot, localPath);
             const conflictRelative = buildConflictPath(originalRelative, detectedAt, 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
@@ -464,7 +512,7 @@ export async function sync(options) {
                 // 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) {
@@ -643,8 +691,17 @@ export async function sync(options) {
             if (isExpiringSoon(ctx.expiresAt)) {
                 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.
@@ -662,8 +719,8 @@ export async function sync(options) {
                 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
@@ -839,21 +896,17 @@ export async function sync(options) {
     // 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);
+        // 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;
-        }
-        const localPath = path.join(companyRoot, key);
         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;
@@ -1011,6 +1064,85 @@ function isRemoteRecreateAfterTombstone(remote, tombstone) {
         return true; // no remote timestamp → don't suppress
     return remoteMs > deletedAtMs;
 }
+function hasTraversalSegment(key) {
+    return key.split("/").some((segment) => segment === "..");
+}
+function isPathWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+function deepestExistingAncestor(start) {
+    let current = start;
+    for (;;) {
+        try {
+            fs.lstatSync(current);
+            return current;
+        }
+        catch (err) {
+            const code = err && typeof err === "object" && "code" in err
+                ? err.code
+                : undefined;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return null;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function resolveContainedVaultPath(root, key) {
+    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;
+    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, key, localPath) {
+    const resolved = resolveContainedVaultPath(root, key);
+    return resolved !== null && path.resolve(resolved) === path.resolve(localPath);
+}
+function tombstoneTargetDiverged(journal, key, localPath, lstat) {
+    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 planning pass: classify every remote file into download / skip /
  * conflict buckets without performing any S3 transfers. Local hashes are
@@ -1036,7 +1168,11 @@ prefixSet,
 fileTombstones = new Map()) {
     const items = [];
     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
         // mirrors since 5.33.0, but the pull side downloaded them freely from
@@ -1047,17 +1183,15 @@ fileTombstones = new Map()) {
             items.push({ action: "skip-excluded-policy", remoteFile, localPath });
             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.
             //
@@ -1394,12 +1528,8 @@ fileTombstones = new Map()) {
         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))
+        const localPath = resolveContainedVaultPath(companyRoot, key);
+        if (localPath === null)
             continue;
         // PersonalMode key gating — mirror the download branch.
         if (personalMode && key.startsWith("companies/")) {
@@ -1415,7 +1545,6 @@ fileTombstones = new Map()) {
         // 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.