@indigoai-us/hq-cloud 5.41.0 → 5.43.0

package/src/prefix-coalesce.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { coalescePrefixes, isCoveredByAny } from "./prefix-coalesce.js";
+import {
+  coalescePrefixes,
+  isCoveredByAny,
+  grantPathToPrefix,
+} from "./prefix-coalesce.js";
 
 describe("coalescePrefixes", () => {
   it("returns empty for empty input", () => {
@@ -93,3 +97,74 @@ describe("isCoveredByAny", () => {
     expect(isCoveredByAny("A/b/c.md", ["a/"])).toBe(false);
   });
 });
+
+describe("grantPathToPrefix", () => {
+  const slug = "indigo";
+
+  it("strips a companies/<slug>/ anchor", () => {
+    expect(grantPathToPrefix("companies/indigo/knowledge/README.md", slug)).toBe(
+      "knowledge/README.md",
+    );
+  });
+
+  it("strips a bare <slug>/ anchor", () => {
+    expect(grantPathToPrefix("indigo/data/vyg/old-meetings/*", slug)).toBe(
+      "data/vyg/old-meetings/",
+    );
+  });
+
+  it("folds a trailing /* glob into a directory prefix", () => {
+    expect(grantPathToPrefix("data/vyg/*", slug)).toBe("data/vyg/");
+    expect(grantPathToPrefix("companies/indigo/design-pack/*", slug)).toBe(
+      "design-pack/",
+    );
+  });
+
+  it("folds a trailing bare * into its parent prefix", () => {
+    expect(grantPathToPrefix("reports*", slug)).toBe("reports");
+  });
+
+  it("leaves a company-relative directory prefix unchanged", () => {
+    expect(grantPathToPrefix("knowledge/security/", slug)).toBe(
+      "knowledge/security/",
+    );
+  });
+
+  it("leaves a company-relative exact key unchanged", () => {
+    expect(grantPathToPrefix("company.yaml", slug)).toBe("company.yaml");
+  });
+
+  it("maps a bare '*' (and empty) to '' = everything", () => {
+    expect(grantPathToPrefix("*", slug)).toBe("");
+    expect(grantPathToPrefix("", slug)).toBe("");
+  });
+
+  it("tolerates leading slashes", () => {
+    expect(grantPathToPrefix("/companies/indigo/x/*", slug)).toBe("x/");
+  });
+
+  it("does not strip a different company's anchor (defensive)", () => {
+    // A grant anchored at another slug is left intact (won't match this
+    // company's keys, which is the safe outcome).
+    expect(grantPathToPrefix("companies/other/x/*", slug)).toBe(
+      "companies/other/x/",
+    );
+  });
+
+  it("round-trips through coalescePrefixes + isCoveredByAny against real keys", () => {
+    const grants = [
+      "companies/indigo/design-pack/*",
+      "companies/indigo/knowledge/README.md",
+      "data/vyg/*",
+      "company.yaml",
+    ];
+    const prefixes = coalescePrefixes(grants.map((g) => grantPathToPrefix(g, slug)));
+    expect(isCoveredByAny("design-pack/logo.svg", prefixes)).toBe(true);
+    expect(isCoveredByAny("knowledge/README.md", prefixes)).toBe(true);
+    expect(isCoveredByAny("data/vyg/2026/q1.md", prefixes)).toBe(true);
+    expect(isCoveredByAny("company.yaml", prefixes)).toBe(true);
+    // Out of scope:
+    expect(isCoveredByAny("secrets/db.json", prefixes)).toBe(false);
+    expect(isCoveredByAny("knowledge/OTHER.md", prefixes)).toBe(false);
+  });
+});

package/src/prefix-coalesce.ts

@@ -70,3 +70,48 @@ export function isCoveredByAny(
   }
   return false;
 }
+
+/**
+ * Normalize a raw ACL grant `path` into a COMPANY-RELATIVE prefix suitable
+ * for `coalescePrefixes` + `isCoveredByAny` (which do literal `startsWith`
+ * matching against company-relative `RemoteFile.key`s).
+ *
+ * Real-world grant paths are inconsistent — observed forms in production:
+ *   - `*`                                  → everything (company-wide glob)
+ *   - `companies/<slug>/design-pack/*`     → full-anchored + trailing glob
+ *   - `companies/<slug>/knowledge/README.md` → full-anchored exact file
+ *   - `<slug>/data/vyg/old-meetings/*`     → slug-anchored + trailing glob
+ *   - `data/vyg/*`                         → company-relative + trailing glob
+ *   - `company.yaml`                       → company-relative exact file
+ *
+ * The engine's keys are ALWAYS company-relative (`design-pack/x`,
+ * `company.yaml`). So we:
+ *   1. strip a leading `companies/<slug>/` or `<slug>/` anchor, and
+ *   2. fold the ACL glob suffix into a `startsWith`-friendly prefix:
+ *        - `*`        (bare)      → `""`  (covers everything)
+ *        - `foo/bar/*` or `foo/bar*` → `foo/bar/` / `foo/bar`
+ *        - `foo/bar/`  (dir)      → unchanged
+ *        - `foo/bar.md` (exact)   → unchanged (an exact key is its own prefix)
+ *
+ * Without this, `coalescePrefixes(grants.map(g => g.path))` produced prefixes
+ * with trailing `*` (which never `startsWith`-match a real key) and
+ * full/slug-anchored prefixes (which never match company-relative keys) — so
+ * `syncMode: shared` would download nothing and prune everything the caller
+ * actually has access to. See the live grant dump in the hq-pro vault.
+ */
+export function grantPathToPrefix(grantPath: string, slug: string): string {
+  let p = (grantPath ?? "").replace(/^\/+/, "");
+  // 1. Strip the company anchor, if present.
+  const companyAnchor = `companies/${slug}/`;
+  const slugAnchor = `${slug}/`;
+  if (p.startsWith(companyAnchor)) {
+    p = p.slice(companyAnchor.length);
+  } else if (p.startsWith(slugAnchor)) {
+    p = p.slice(slugAnchor.length);
+  }
+  // 2. Fold the ACL glob suffix into a startsWith prefix.
+  if (p === "*" || p === "") return ""; // company-wide / empty → everything
+  if (p.endsWith("/*")) return p.slice(0, -1); // "a/b/*" → "a/b/"
+  if (p.endsWith("*")) return p.slice(0, -1); // "a/b*"  → "a/b"
+  return p; // dir prefix ("a/b/") or exact key ("a/b.md") — already a prefix
+}

package/src/scope-shrink.ts

@@ -203,6 +203,34 @@ export class ScopeShrinkBlockedError extends Error {
   }
 }
 
+/**
+ * Structured error thrown when an AUTOMATIC scope shrink would prune more
+ * CLEAN local files than the configured safety cap in a single pull. This is
+ * the bulk-delete guard: a routine background sync should never silently
+ * delete a large local tree — whether from a deliberate-but-abrupt first
+ * narrow, a server bug returning an unexpectedly small grant set, or a
+ * mis-resolved scope. The operator runs the explicit `hq sync narrow` ritual
+ * (which has its own confirmation + dirty gate) or passes `--force-scope-shrink`
+ * to proceed. The engine never deletes anything when it throws this.
+ */
+export class ScopeShrinkLargePruneError extends Error {
+  readonly code = "SCOPE_SHRINK_LARGE_PRUNE";
+  constructor(
+    public readonly companyUid: string,
+    public readonly toMode: PullRecord["syncMode"],
+    public readonly cleanCount: number,
+    public readonly cap: number,
+  ) {
+    super(
+      `Refusing to auto-prune ${cleanCount} local file(s) for ${companyUid} ` +
+        `(${toMode} scope) in one sync — exceeds the safety cap of ${cap}. ` +
+        `Run \`hq sync narrow --apply\` to migrate with confirmation, raise ` +
+        `HQ_SYNC_MAX_AUTO_PRUNE, or pass --force-scope-shrink.`,
+    );
+    this.name = "ScopeShrinkLargePruneError";
+  }
+}
+
 export interface ApplyScopeShrinkInput {
   journal: SyncJournal;
   plan: ScopeShrinkPlan;

package/src/vault-client.test.ts

@@ -670,6 +670,30 @@ describe("VaultClient identity bootstrap", () => {
     expect(result?.type).toBe("person");
   });
 
+  it("sts.vend roundtrips POST /sts/vend with companyUid", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        credentials: {
+          accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+          secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+          sessionToken: "FwoGZXIvYXdzEBY...",
+        },
+        expiresAt: "2026-01-01T01:00:00.000Z",
+      }),
+    );
+
+    const result = await client.sts.vend({ companyUid: "cmp_x" });
+
+    expect(result.credentials.accessKeyId).toBe("AKIAIOSFODNN7EXAMPLE");
+    expect(result.credentials.sessionToken).toBe("FwoGZXIvYXdzEBY...");
+    expect(typeof result.expiresAt).toBe("string");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/sts/vend");
+    expect((init.method as string).toUpperCase()).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({ companyUid: "cmp_x" });
+  });
+
   it("vendSelf_roundtrip", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(200, {

package/src/vault-client.ts

@@ -693,6 +693,30 @@ export class VaultClient {
   // -- STS operations (VLT-8) -----------------------------------------------
 
   readonly sts = {
+    /**
+     * Vend membership-scoped credentials for a company the caller belongs to.
+     * Backed by the vault-service `POST /sts/vend` route — the multi-tenant
+     * path that resolves the company's per-entity bucket and builds the
+     * session policy from the caller's role + ACL grants server-side
+     * (owner/admin get full-access, member/guest get per-prefix scoping).
+     *
+     * This is the correct path for interactive reads (`hq files browse`/`cat`):
+     * the legacy `POST /vend` ({@link VaultClient.vend}) assumes a single
+     * static bucket and is non-functional in multi-tenant production.
+     */
+    vend: async (input: {
+      companyUid: string;
+      durationSeconds?: number;
+    }): Promise<{
+      credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken: string;
+      };
+      expiresAt: string;
+    }> => {
+      return this.post("/sts/vend", input);
+    },
     /**
      * Vend task-scoped child credentials strictly narrower than the caller's
      * own membership. Backed by the vault-service `POST /sts/vend-child`