@indigoai-us/hq-cli 5.17.0 → 5.18.1

package/src/commands/files-browse.test.ts

@@ -0,0 +1,475 @@
+/**
+ * Unit tests for `hq files browse` + `hq files cat` (files-browse.ts).
+ *
+ * Stubs VaultClient.vend / listMyExplicitGrants / entity.findInMyNamespace
+ * and the S3 client so we cover the three acceptance criteria the unit
+ * suite is responsible for (acceptance 6):
+ *
+ *   1. vend uses `purpose: 'browse'` (NOT `'sync'`) for both subcommands.
+ *   2. `--out` refuses any destination under `<hqRoot>/companies/`.
+ *   3. ACL-source classification: keys with a covering explicit grant →
+ *      `shared-with-you`; keys with no covering grant → `role-bypass`.
+ *
+ * Plus the pure helpers (parseCompanySlugFromPath, classifyAclSource,
+ * assertOutPathOutsideCompanies, formatBrowseTable).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Readable, Writable } from "node:stream";
+
+import {
+  assertOutPathOutsideCompanies,
+  classifyAclSource,
+  formatBrowseTable,
+  parseCompanySlugFromPath,
+  runBrowse,
+  runCat,
+  type FilesBrowseS3Client,
+  type FilesBrowseVaultClient,
+  type S3ClientFactory,
+} from "./files-browse.js";
+import type { ExplicitGrant, VendResult } from "@indigoai-us/hq-cloud";
+import {
+  ListObjectsV2Command,
+  GetObjectCommand,
+  type ListObjectsV2CommandOutput,
+  type GetObjectCommandOutput,
+} from "@aws-sdk/client-s3";
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-files-browse-"));
+  // Create the companies/ subtree so the guard has a real path to compare
+  // against (the guard's check is string-level so this isn't strictly
+  // required, but it mirrors the real layout).
+  fs.mkdirSync(path.join(tmpRoot, "companies", "indigo"), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+function fakeGrant(p: string): ExplicitGrant {
+  return {
+    companyUid: "cmp_indigo",
+    path: p,
+    permission: "read",
+    source: "person",
+  };
+}
+
+function fakeVendResult(overrides: Partial<VendResult> = {}): VendResult {
+  return {
+    credentials: {
+      accessKeyId: "ASIA-test",
+      secretAccessKey: "secret-test",
+      sessionToken: "session-test",
+      expiration: new Date(Date.now() + 900_000).toISOString(),
+    },
+    paths: ["companies/indigo/"],
+    operations: "read-only",
+    purpose: "browse",
+    policySize: 512,
+    ...overrides,
+  };
+}
+
+interface StubVaultOpts {
+  vend?: VendResult;
+  grants?: ExplicitGrant[];
+  entity?:
+    | { uid: string; slug: string; name?: string; bucketName?: string }
+    | null;
+}
+
+function makeStubVaultClient(opts: StubVaultOpts = {}): {
+  client: FilesBrowseVaultClient;
+  spies: {
+    vend: ReturnType<typeof vi.fn>;
+    listMyExplicitGrants: ReturnType<typeof vi.fn>;
+    findInMyNamespace: ReturnType<typeof vi.fn>;
+  };
+} {
+  const entity =
+    opts.entity === null
+      ? null
+      : (opts.entity ?? {
+          uid: "cmp_indigo",
+          slug: "indigo",
+          name: "Indigo",
+          bucketName: "hq-vault-cmp-indigo",
+        });
+  const vend = vi.fn(async () => opts.vend ?? fakeVendResult());
+  const listMyExplicitGrants = vi.fn(async () => opts.grants ?? []);
+  const findInMyNamespace = vi.fn(async () => entity);
+  const get = vi.fn(async (uid: string) => {
+    if (!entity) throw new Error(`entity ${uid} not found`);
+    return entity;
+  });
+  const client: FilesBrowseVaultClient = {
+    vend,
+    listMyExplicitGrants,
+    entity: { get, findInMyNamespace },
+  };
+  return { client, spies: { vend, listMyExplicitGrants, findInMyNamespace } };
+}
+
+interface StubS3Opts {
+  listResponses?: ListObjectsV2CommandOutput[];
+  getResponse?: GetObjectCommandOutput;
+}
+
+function makeStubS3Factory(opts: StubS3Opts): {
+  factory: S3ClientFactory;
+  sendSpy: ReturnType<typeof vi.fn>;
+  factorySpy: ReturnType<typeof vi.fn>;
+} {
+  const responses = [...(opts.listResponses ?? [])];
+  const sendSpy = vi.fn(async (cmd: unknown) => {
+    if (cmd instanceof ListObjectsV2Command) {
+      const next = responses.shift() ?? { Contents: [] };
+      return next;
+    }
+    if (cmd instanceof GetObjectCommand) {
+      return opts.getResponse ?? { Body: undefined };
+    }
+    throw new Error(`unexpected command: ${cmd}`);
+  });
+  const factorySpy = vi.fn(
+    () =>
+      ({
+        send: sendSpy,
+      }) as unknown as FilesBrowseS3Client,
+  );
+  return { factory: factorySpy as unknown as S3ClientFactory, sendSpy, factorySpy };
+}
+
+// ── parseCompanySlugFromPath ────────────────────────────────────────────────
+
+describe("parseCompanySlugFromPath", () => {
+  it("extracts slug from a canonical prefix", () => {
+    expect(parseCompanySlugFromPath("companies/indigo/scratch/")).toBe("indigo");
+  });
+
+  it("tolerates leading slashes", () => {
+    expect(parseCompanySlugFromPath("/companies/acme/foo")).toBe("acme");
+  });
+
+  it("rejects paths not anchored at companies/", () => {
+    expect(() => parseCompanySlugFromPath("personal/notes/")).toThrow(
+      /Expected a path starting with 'companies\//,
+    );
+    expect(() => parseCompanySlugFromPath("")).toThrow();
+    expect(() => parseCompanySlugFromPath("companies/")).toThrow();
+  });
+});
+
+// ── classifyAclSource ───────────────────────────────────────────────────────
+
+describe("classifyAclSource", () => {
+  it("returns shared-with-you when any grant prefixes the key", () => {
+    const grants = [fakeGrant("companies/indigo/scratch/")];
+    expect(
+      classifyAclSource("companies/indigo/scratch/foo.txt", grants),
+    ).toBe("shared-with-you");
+  });
+
+  it("returns role-bypass when no grant covers the key", () => {
+    const grants = [fakeGrant("companies/indigo/scratch/")];
+    expect(
+      classifyAclSource("companies/indigo/secrets/db.txt", grants),
+    ).toBe("role-bypass");
+  });
+
+  it("returns role-bypass on an empty grant list", () => {
+    expect(classifyAclSource("companies/indigo/anything/x", [])).toBe(
+      "role-bypass",
+    );
+  });
+
+  it("matches against the first covering grant — multiple grants are fine", () => {
+    const grants = [
+      fakeGrant("companies/other/"),
+      fakeGrant("companies/indigo/scratch/"),
+    ];
+    expect(
+      classifyAclSource("companies/indigo/scratch/sub/y.bin", grants),
+    ).toBe("shared-with-you");
+  });
+});
+
+// ── assertOutPathOutsideCompanies (writes-guard) ───────────────────────────
+
+describe("assertOutPathOutsideCompanies", () => {
+  it("refuses a destination directly under <hqRoot>/companies/", () => {
+    const dest = path.join(tmpRoot, "companies", "indigo", "leaked.txt");
+    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).toThrow(
+      /Refusing to write/,
+    );
+  });
+
+  it("refuses a destination deep under <hqRoot>/companies/", () => {
+    const dest = path.join(
+      tmpRoot,
+      "companies",
+      "indigo",
+      "scratch",
+      "deep",
+      "leaked.txt",
+    );
+    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).toThrow();
+  });
+
+  it("refuses the bare companies/ root", () => {
+    const dest = path.join(tmpRoot, "companies");
+    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).toThrow();
+  });
+
+  it("permits a destination outside <hqRoot>/companies/ (e.g. /tmp)", () => {
+    const dest = path.join(tmpRoot, "scratch.txt");
+    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).not.toThrow();
+    expect(assertOutPathOutsideCompanies(dest, tmpRoot)).toBe(
+      path.resolve(dest),
+    );
+  });
+
+  it("permits an absolute path under /tmp that is unrelated to hqRoot", () => {
+    // Use a sibling tmp dir as the "outside" location so the test is
+    // platform-portable (no hard-coded /tmp/foo paths).
+    const otherRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-out-"));
+    try {
+      const dest = path.join(otherRoot, "leaked.txt");
+      expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).not.toThrow();
+    } finally {
+      fs.rmSync(otherRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("refuses a relative path that resolves under companies/", () => {
+    // On macOS the OS tmp dir is a symlink (`/tmp` → `/private/tmp`,
+    // `/var/folders/...` is the canonical form). Resolving the realpath
+    // on both sides keeps `path.resolve`'s output and the guard's
+    // protected-root match on the same physical tree, so a cwd-relative
+    // "companies/indigo/…" lookup is correctly classified as protected.
+    const realRoot = fs.realpathSync(tmpRoot);
+    const cwd = process.cwd();
+    process.chdir(realRoot);
+    try {
+      expect(() =>
+        assertOutPathOutsideCompanies("companies/indigo/foo.txt", realRoot),
+      ).toThrow();
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+});
+
+// ── formatBrowseTable ───────────────────────────────────────────────────────
+
+describe("formatBrowseTable", () => {
+  it("renders an empty marker when no rows", () => {
+    expect(formatBrowseTable([])).toMatch(/No objects/);
+  });
+
+  it("includes key, size, modified, and ACL source in the row", () => {
+    const out = formatBrowseTable([
+      {
+        key: "companies/indigo/scratch/a.txt",
+        size: 42,
+        lastModified: new Date("2026-01-15T10:00:00Z"),
+        aclSource: "shared-with-you",
+      },
+    ]);
+    expect(out).toContain("companies/indigo/scratch/a.txt");
+    expect(out).toContain("42");
+    expect(out).toContain("2026-01-15");
+    expect(out).toContain("shared-with-you");
+  });
+});
+
+// ── runBrowse ───────────────────────────────────────────────────────────────
+
+describe("runBrowse", () => {
+  it("vends with purpose='browse' (NOT 'sync') for the requested prefix", async () => {
+    const { client, spies } = makeStubVaultClient({});
+    const { factory } = makeStubS3Factory({
+      listResponses: [{ Contents: [] }],
+    });
+    await runBrowse({
+      pathPrefix: "companies/indigo/scratch/",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+    expect(spies.vend).toHaveBeenCalledTimes(1);
+    const arg = spies.vend.mock.calls[0][0];
+    expect(arg.purpose).toBe("browse");
+    expect(arg.purpose).not.toBe("sync");
+    expect(arg.operations).toBe("read-only");
+    expect(arg.paths).toEqual(["companies/indigo/scratch/"]);
+  });
+
+  it("paginates ListObjectsV2 fully and classifies each key's ACL source", async () => {
+    const { client } = makeStubVaultClient({
+      grants: [fakeGrant("companies/indigo/scratch/")],
+    });
+    const { factory, sendSpy } = makeStubS3Factory({
+      listResponses: [
+        {
+          Contents: [
+            {
+              Key: "companies/indigo/scratch/a.txt",
+              Size: 10,
+              LastModified: new Date("2026-01-01T00:00:00Z"),
+            },
+            {
+              Key: "companies/indigo/secrets/db.txt",
+              Size: 20,
+              LastModified: new Date("2026-01-02T00:00:00Z"),
+            },
+          ],
+          NextContinuationToken: "page2",
+        },
+        {
+          Contents: [
+            {
+              Key: "companies/indigo/scratch/sub/b.bin",
+              Size: 30,
+              LastModified: new Date("2026-01-03T00:00:00Z"),
+            },
+            // S3 directory marker — should be filtered out.
+            {
+              Key: "companies/indigo/scratch/empty/",
+              Size: 0,
+              LastModified: new Date("2026-01-04T00:00:00Z"),
+            },
+          ],
+        },
+      ],
+    });
+    const result = await runBrowse({
+      pathPrefix: "companies/indigo/scratch/",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+    expect(sendSpy).toHaveBeenCalledTimes(2); // pagination
+    expect(result.rows).toHaveLength(3);
+    const byKey = Object.fromEntries(result.rows.map((r) => [r.key, r]));
+    expect(byKey["companies/indigo/scratch/a.txt"].aclSource).toBe(
+      "shared-with-you",
+    );
+    expect(byKey["companies/indigo/scratch/sub/b.bin"].aclSource).toBe(
+      "shared-with-you",
+    );
+    // Visible only via role-bypass — this is the leak-out-of-grant case.
+    expect(byKey["companies/indigo/secrets/db.txt"].aclSource).toBe(
+      "role-bypass",
+    );
+  });
+
+  it("throws when the slug doesn't resolve in the caller's namespace", async () => {
+    const { client } = makeStubVaultClient({ entity: null });
+    const { factory } = makeStubS3Factory({ listResponses: [] });
+    await expect(
+      runBrowse({
+        pathPrefix: "companies/notmine/scratch/",
+        vaultClient: client,
+        s3Factory: factory,
+        region: "us-east-1",
+      }),
+    ).rejects.toThrow(/No company found for slug 'notmine'/);
+  });
+});
+
+// ── runCat ──────────────────────────────────────────────────────────────────
+
+describe("runCat", () => {
+  it("vends with purpose='browse' for a cat call", async () => {
+    const { client, spies } = makeStubVaultClient({});
+    const { factory } = makeStubS3Factory({
+      getResponse: {
+        Body: Readable.from(Buffer.from("hello world")),
+      } as GetObjectCommandOutput,
+    });
+    // Drain to a sink so process.stdout isn't touched.
+    const sink = new Writable({ write(_c, _e, cb) { cb(); } });
+    await runCat({
+      key: "companies/indigo/scratch/a.txt",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+      hqRoot: tmpRoot,
+      stdout: sink,
+    });
+    expect(spies.vend).toHaveBeenCalledTimes(1);
+    expect(spies.vend.mock.calls[0][0].purpose).toBe("browse");
+  });
+
+  it("writes to --out when outside the companies tree and reports byte count", async () => {
+    const { client } = makeStubVaultClient({});
+    const payload = Buffer.from("safe-payload");
+    const { factory } = makeStubS3Factory({
+      getResponse: {
+        Body: Readable.from(payload),
+      } as GetObjectCommandOutput,
+    });
+    const outFile = path.join(tmpRoot, "safe.txt");
+    const result = await runCat({
+      key: "companies/indigo/scratch/a.txt",
+      out: outFile,
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+      hqRoot: tmpRoot,
+    });
+    expect(result.destination).toEqual({ kind: "file", absPath: outFile });
+    expect(fs.readFileSync(outFile, "utf-8")).toBe("safe-payload");
+    expect(result.bytesWritten).toBe(payload.length);
+  });
+
+  it("refuses --out under <hqRoot>/companies/ BEFORE vending (no leak)", async () => {
+    const { client, spies } = makeStubVaultClient({});
+    const { factory, sendSpy } = makeStubS3Factory({
+      getResponse: { Body: Readable.from(Buffer.from("nope")) } as GetObjectCommandOutput,
+    });
+    const badOut = path.join(tmpRoot, "companies", "indigo", "leaked.txt");
+    await expect(
+      runCat({
+        key: "companies/indigo/scratch/a.txt",
+        out: badOut,
+        vaultClient: client,
+        s3Factory: factory,
+        region: "us-east-1",
+        hqRoot: tmpRoot,
+      }),
+    ).rejects.toThrow(/Refusing to write/);
+    // Critically: no vend was issued (guard runs first) and no S3 call
+    // was made — failing closed is the whole point of the guard.
+    expect(spies.vend).not.toHaveBeenCalled();
+    expect(sendSpy).not.toHaveBeenCalled();
+    // And no file was written under the protected tree.
+    expect(fs.existsSync(badOut)).toBe(false);
+  });
+
+  it("rejects a vault key that isn't anchored at companies/", async () => {
+    const { client } = makeStubVaultClient({});
+    const { factory } = makeStubS3Factory({});
+    await expect(
+      runCat({
+        key: "personal/notes/x.txt",
+        vaultClient: client,
+        s3Factory: factory,
+        region: "us-east-1",
+        hqRoot: tmpRoot,
+      }),
+    ).rejects.toThrow(/Expected a path starting with 'companies\//);
+  });
+});