@indigoai-us/hq-cloud 6.14.6 → 6.14.7

package/src/cli/sync.ts

@@ -19,6 +19,7 @@ import {
 } from "../telemetry-events.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { createSyncProgressRecorder } from "../sync-progress.js";
+import { localPathForVaultKey, vaultKeyForLocalPath } from "../local-path-codec.js";
 import {
   downloadFile,
   listRemoteFiles,
@@ -26,7 +27,7 @@ import {
   primeObjectTransport,
   toPosixKey,
 } from "../s3.js";
-import type { RemoteFile } from "../s3.js";
+import type { DownloadModeWarning, RemoteFile } from "../s3.js";
 import {
   readJournal,
   writeJournal,
@@ -971,6 +972,30 @@ function reportInvalidScopedKeys(run: PullRunContext, plan: PullPlan): void {
   }, { claims: run.options.telemetryClaims });
 }
 
+/**
+ * A legacy object without hq-mode can otherwise downgrade a hook to the
+ * receiver umask with no durable signal. downloadFile already prints a local
+ * warning for every caller; the sync path also records a path-free telemetry
+ * event so operators can find vaults that still need the one-time backfill.
+ */
+function reportModeWarnings(
+  run: PullRunContext,
+  warnings: DownloadModeWarning[] | undefined,
+): void {
+  for (const warning of warnings ?? []) {
+    void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+      eventName: "sync_mode_guardrail_warning",
+      source: "hq-sync",
+      companyUid: run.ctx.uid,
+      properties: {
+        leg: "pull",
+        reason: warning.reason,
+        fallback: warning.fallback ?? null,
+      },
+    }, { claims: run.options.telemetryClaims });
+  }
+}
+
 function createPullCounters(): PullCounters {
   return {
     filesDownloaded: 0,
@@ -1220,7 +1245,7 @@ async function executeConflictItem(
   // the REMOTE hash/etag) and skip the conflict path entirely. This removes both
   // the `.conflict-` mirror loop AND the journal false-stamp (remote etag over
   // divergent local content) that the keep path produced for these files.
-  if (isCloudAuthoritative(path.relative(run.hqRoot, localPath))) {
+  if (isCloudAuthoritative(vaultKeyForLocalPath(run.hqRoot, localPath))) {
     downloadItems.push({ action: "download", remoteFile, localPath, isNew: false });
     run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
     return null;
@@ -1230,14 +1255,14 @@ async function executeConflictItem(
 
   const detectedAt = new Date().toISOString();
   const machineId = readShortMachineId(run.hqRoot);
-  const originalRelative = path.relative(run.hqRoot, localPath);
+  const originalRelative = vaultKeyForLocalPath(run.hqRoot, localPath);
   const conflictRelative = buildConflictPath(
     originalRelative,
     detectedAt,
     machineId,
   );
-  const conflictAbs = path.join(run.hqRoot, conflictRelative);
-  const conflictKey = toPosixKey(path.relative(run.companyRoot, conflictAbs));
+  const conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
+  const conflictKey = vaultKeyForLocalPath(run.companyRoot, conflictAbs);
 
   if (!isDownloadWritePathStillContained(run.companyRoot, conflictKey, conflictAbs)) {
     counters.filesSkipped++;
@@ -1459,11 +1484,12 @@ async function downloadOne(
   }
 
   try {
-    const { metadata, contentHash, contentSize } = await downloadFile(
+    const { metadata, contentHash, contentSize, modeWarnings } = await downloadFile(
       run.ctx,
       remoteFile.key,
       localPath,
     );
+    reportModeWarnings(run, modeWarnings);
     const author = metadata?.["created-by"] ?? null;
     const createdBySub = metadata?.["created-by-sub"];
 
@@ -1803,7 +1829,7 @@ 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);
+  const resolvedLocal = localPathForVaultKey(resolvedRoot, key);
   if (!isPathWithin(resolvedRoot, resolvedLocal)) return null;
 
   let realRoot: string;

package/src/local-path-codec.ts

@@ -0,0 +1,95 @@
+/**
+ * Reversible local filename adapter for canonical vault keys on Win32.
+ *
+ * Vault keys are POSIX identifiers and may contain ':' (for example
+ * `factory:slack`).  Win32 cannot materialize those strings as filename
+ * segments, so keep the key canonical in S3 and journals while encoding only
+ * the local segment that reaches the filesystem.
+ */
+import * as path from "path";
+
+const WIN32_RESERVED_CHARS = /[<>:"/\\|?*]/;
+const WIN32_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+
+function isWin32ReservedCharacter(char: string): boolean {
+  return char.charCodeAt(0) <= 0x1f || WIN32_RESERVED_CHARS.test(char);
+}
+
+function percentEscape(char: string): string {
+  return `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+}
+
+/**
+ * Encode one canonical vault-key segment for a Win32 filename. Percent is
+ * escaped before every other character so decoding cannot collide with a
+ * literal `%3A` name. The optional flag makes platform-specific behavior
+ * directly testable without mutating `process.platform`.
+ */
+export function encodeLocalVaultSegment(
+  segment: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  if (!win32) return segment;
+
+  let encoded = "";
+  for (let index = 0; index < segment.length; index++) {
+    const char = segment[index]!;
+    const isTrailingDotOrSpace =
+      index === segment.length - 1 && (char === "." || char === " ");
+    const isDotSegment = (segment === "." || segment === "..") && index === 0;
+    const isReservedDeviceFirstChar = WIN32_DEVICE_NAME.test(segment) && index === 0;
+    if (
+      char === "%" ||
+      isWin32ReservedCharacter(char) ||
+      isTrailingDotOrSpace ||
+      isDotSegment ||
+      isReservedDeviceFirstChar
+    ) {
+      encoded += percentEscape(char);
+    } else {
+      encoded += char;
+    }
+  }
+  return encoded;
+}
+
+/** Decode one local filename segment back to its canonical vault-key form. */
+export function decodeLocalVaultSegment(
+  segment: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  if (!win32) return segment;
+  return segment.replace(/%([0-9a-f]{2})/gi, (_whole, hex: string) =>
+    String.fromCharCode(Number.parseInt(hex, 16)),
+  );
+}
+
+/** Materialize a canonical slash-delimited vault key beneath a local root. */
+export function localPathForVaultKey(
+  root: string,
+  key: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  return path.join(
+    root,
+    ...key.split("/").map((segment) => encodeLocalVaultSegment(segment, win32)),
+  );
+}
+
+/**
+ * Turn a local, root-relative path back into its canonical vault key. This
+ * recognizes legacy percent-encoded Windows materializations as well as the
+ * current codec, so they converge on one remote/journal key instead of
+ * creating duplicates.
+ */
+export function vaultKeyForLocalPath(
+  root: string,
+  localPath: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  return path
+    .relative(root, localPath)
+    .split(path.sep)
+    .map((segment) => decodeLocalVaultSegment(segment, win32))
+    .join("/");
+}

package/src/s3.ts

@@ -764,6 +764,13 @@ export async function uploadSymlink(
  * return it to callers — e.g. the pull loop reads `created-by` to
  * attribute downloaded files to their author with zero extra network.
  */
+export interface DownloadModeWarning {
+  /** The mode guardrail that could not be applied exactly. */
+  reason: "missing-hq-mode" | "invalid-hq-mode" | "chmod-failed";
+  /** Legacy objects can retain a local file's known-good permission bits. */
+  fallback?: "preserved-local-mode" | "receiver-default";
+}
+
 export async function downloadFile(
   ctx: EntityContext,
   key: string,
@@ -772,6 +779,8 @@ export async function downloadFile(
   metadata?: Record<string, string>;
   contentHash?: string;
   contentSize?: number;
+  /** Non-fatal mode guardrail warnings for caller telemetry. */
+  modeWarnings?: DownloadModeWarning[];
 }> {
   const io = resolveObjectIO(ctx);
 
@@ -867,15 +876,25 @@ export async function downloadFile(
     return { metadata };
   }
   const tempPath = downloadTempPath(localPath);
+  // A legacy object has no hq-mode. If it is replacing a regular local file,
+  // that local mode is the only trustworthy signal we have — retaining it is
+  // strictly safer than replacing (for example) a 0755 hook with the receiver
+  // umask's usual 0644. Never inspect a symlink or infer intent from content.
+  let existingLocalMode: number | undefined;
+  try {
+    const existing = fs.lstatSync(localPath);
+    if (existing.isFile()) existingLocalMode = existing.mode & 0o777;
+  } catch {
+    // Fresh destination / inaccessible prior path: no local fallback.
+  }
   let tempReady = true;
   let streamed: { hash: string; size: number };
+  const modeWarnings: DownloadModeWarning[] = [];
   try {
     streamed = await streamRegularFileToTemp(tempPath, initialChunks, iterator);
 
     // Bug #5 — apply source-side mode after the byte write. See
-    // FILE_MODE_META_KEY for the metadata contract. Parses defensively:
-    // a malformed value falls through with no chmod so the umask default
-    // applies, matching the legacy back-compat path. The staged path is a
+    // FILE_MODE_META_KEY for the metadata contract. The staged path is a
     // regular file, then it is atomically renamed over the destination.
     //
     // Codex P2 (PR #24 round 3): strict octal-only regex BEFORE parseInt.
@@ -886,17 +905,33 @@ export async function downloadFile(
     // the upload side stamps (`(mode & 0o777).toString(8)` → at most
     // three digits, all 0–7) and rejects everything else.
     const modeOctal = metadata?.[FILE_MODE_META_KEY];
+    let modeToApply: number | undefined;
     if (typeof modeOctal === "string" && /^[0-7]{1,4}$/.test(modeOctal)) {
       const parsed = parseInt(modeOctal, 8);
       if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 0o777) {
-        try {
-          fs.chmodSync(tempPath, parsed);
-        } catch {
-          // chmod failure (read-only FS, EPERM) is non-fatal — the file
-          // is materialized, just with the umask default. Surface via
-          // S3-side metadata being present but the file not matching;
-          // a future operator-side audit can reconcile.
-        }
+        modeToApply = parsed;
+      }
+    } else if (modeOctal === undefined) {
+      modeToApply = existingLocalMode;
+      modeWarnings.push({
+        reason: "missing-hq-mode",
+        fallback:
+          existingLocalMode === undefined
+            ? "receiver-default"
+            : "preserved-local-mode",
+      });
+    } else {
+      modeWarnings.push({ reason: "invalid-hq-mode", fallback: "receiver-default" });
+    }
+
+    if (modeToApply !== undefined) {
+      try {
+        fs.chmodSync(tempPath, modeToApply);
+      } catch {
+        // chmod failure (read-only FS, EPERM) is non-fatal — the file is
+        // materialized, but callers must receive a telemetry signal instead
+        // of silently believing the guardrail held.
+        modeWarnings.push({ reason: "chmod-failed" });
       }
     }
 
@@ -953,7 +988,21 @@ export async function downloadFile(
   // distinct creation time, so a future receiver upgrade picks it up
   // automatically without a server-side data migration.
 
-  return { metadata, contentHash: streamed.hash, contentSize: streamed.size };
+  if (modeWarnings.length > 0) {
+    for (const warning of modeWarnings) {
+      console.warn(
+        `[hq-sync] mode warning for ${key}: ${warning.reason}` +
+          (warning.fallback ? ` (${warning.fallback})` : ""),
+      );
+    }
+  }
+
+  return {
+    metadata,
+    contentHash: streamed.hash,
+    contentSize: streamed.size,
+    ...(modeWarnings.length > 0 ? { modeWarnings } : {}),
+  };
 }
 
 export interface RemoteFile {

package/src/scope-shrink.ts

@@ -40,6 +40,7 @@ import type {
   SyncJournal,
 } from "./types.js";
 import { hashFile, tombstoneEntry } from "./journal.js";
+import { localPathForVaultKey } from "./local-path-codec.js";
 import {
   isCoveredByAny,
   type ScopePrefixInput,
@@ -168,7 +169,7 @@ function classifyOrphan(
   entry: JournalEntry,
   hqRoot: string,
 ): OrphanClassification {
-  const absPath = path.join(hqRoot, relPath);
+  const absPath = localPathForVaultKey(hqRoot, relPath);
   let stat: fs.Stats;
   try {
     stat = fs.lstatSync(absPath);
@@ -436,9 +437,9 @@ export function applyScopeShrink(
   const dirtyKeptPaths: string[] = [];
 
   for (const orphan of plan.clean) {
-    const absPath = path.join(hqRoot, orphan.path);
+    const absPath = localPathForVaultKey(hqRoot, orphan.path);
     if (quarantining) {
-      const destAbs = path.join(input.quarantineRoot!, orphan.path);
+      const destAbs = localPathForVaultKey(input.quarantineRoot!, orphan.path);
       quarantineOrphan(absPath, destAbs);
       tombstoneEntry(journal, orphan.path, reason);
       cleanQuarantined++;