@indigoai-us/hq-cli 5.47.6 → 5.47.8

package/src/commands/files-browse.ts

@@ -61,7 +61,7 @@ import {
   ensureCognitoToken,
   buildVaultConfig,
 } from "../utils/cognito-session.js";
-import { getCompanyUid } from "../utils/vault-api.js";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
 
 // ── Types ───────────────────────────────────────────────────────────────────
@@ -128,6 +128,16 @@ export type S3ClientFactory = (input: {
   };
 }) => FilesBrowseS3Client;
 
+/**
+ * Factory for the COMPANY-mode browse client. Injectable for tests; the
+ * production implementation is `createCompanyPresignClient`. Keyed by
+ * `companyUid` (resolved by the orchestrator) — the access token is captured
+ * by the closure at the CLI layer.
+ */
+export type CompanyBrowseClientFactory = (input: {
+  companyUid: string;
+}) => FilesBrowseS3Client;
+
 /**
  * ACL provenance for a single listed key.
  *   - `shared-with-you`: an explicit grant the caller holds covers the key.
@@ -292,13 +302,46 @@ export interface RunBrowseInput {
    */
   personalUid?: string;
   vaultClient: FilesBrowseVaultClient;
-  s3Factory: S3ClientFactory;
+  /** PERSONAL mode: builds a direct-S3 client from vended creds. */
+  s3Factory?: S3ClientFactory;
+  /**
+   * COMPANY mode (HQ-59): builds the presign/list-backed client. Company
+   * browse no longer talks to S3 directly and does not vend STS creds.
+   */
+  companyClient?: CompanyBrowseClientFactory;
   region: string;
 }
 
 export interface RunBrowseResult {
   rows: BrowseRow[];
-  vend: BrowseVendResult;
+  /**
+   * Present ONLY for the PERSONAL (vendSelf + direct S3) path. Company mode
+   * goes through the presign/list API and does not vend, so this is undefined
+   * there.
+   */
+  vend?: BrowseVendResult;
+}
+
+/** Guard: the personal path needs an S3 factory. */
+function requirePersonalS3Factory(f?: S3ClientFactory): S3ClientFactory {
+  if (!f) {
+    throw new Error(
+      "Personal-vault browse requires an s3Factory (direct-S3 client).",
+    );
+  }
+  return f;
+}
+
+/** Guard: the company path needs the presign/list client factory. */
+function requireCompanyClient(
+  f?: CompanyBrowseClientFactory,
+): CompanyBrowseClientFactory {
+  if (!f) {
+    throw new Error(
+      "Company browse requires a companyClient (presign/list client).",
+    );
+  }
+  return f;
 }
 
 /**
@@ -315,7 +358,7 @@ export interface RunBrowseResult {
  * Pure-ish: no console output, no process.exit — caller renders + exits.
  */
 export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult> {
-  const { pathPrefix, vaultClient, s3Factory, region, personalMode } = input;
+  const { pathPrefix, vaultClient, region, personalMode } = input;
 
   // Branch by mode. Company mode parses slug from path and looks up by
   // namespace; personal mode resolves the entity directly by the supplied
@@ -324,7 +367,8 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
   let bucket: string;
   let entityUid: string;
   let slug: string | undefined;
-  let vend: BrowseVendResult;
+  let vend: BrowseVendResult | undefined;
+  let s3: FilesBrowseS3Client;
   if (personalMode) {
     if (!input.personalUid) {
       throw new Error(
@@ -340,7 +384,17 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     }
     entityUid = entity.uid;
     bucket = entity.bucketName;
+    // Personal vault keeps the direct-S3 path: vend self creds, build an S3
+    // client. (HQ-59 scopes the migration to COMPANY mode.)
     vend = await vaultClient.sts.vendSelf({ personUid: entityUid });
+    s3 = requirePersonalS3Factory(input.s3Factory)({
+      region,
+      credentials: {
+        accessKeyId: vend.credentials.accessKeyId,
+        secretAccessKey: vend.credentials.secretAccessKey,
+        sessionToken: vend.credentials.sessionToken,
+      },
+    });
   } else {
     slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
     const entity = await vaultClient.entity.findInMyNamespace("company", slug);
@@ -356,21 +410,11 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     }
     entityUid = entity.uid;
     bucket = entity.bucketName;
-    // Multi-tenant vend: the server resolves this company's bucket + applies
-    // owner/admin role-bypass (full access) or member/guest ACL scoping. The
-    // legacy `POST /vend` is unused here — see FilesBrowseVaultClient docs.
-    vend = await vaultClient.sts.vend({ companyUid: entityUid });
+    // COMPANY mode (HQ-59): list/get go through the presign/list API, which
+    // enforces the same per-file ACLs server-side. No STS vend, no direct S3.
+    s3 = requireCompanyClient(input.companyClient)({ companyUid: entityUid });
   }
 
-  const s3 = s3Factory({
-    region,
-    credentials: {
-      accessKeyId: vend.credentials.accessKeyId,
-      secretAccessKey: vend.credentials.secretAccessKey,
-      sessionToken: vend.credentials.sessionToken,
-    },
-  });
-
   // Company vault keys are company-relative (no `companies/<slug>/` prefix), so
   // translate the CLI's anchored prefix into the bucket-relative form before
   // listing. Personal-mode paths are already bucket-relative.
@@ -447,7 +491,10 @@ export interface RunCatInput {
   /** Canonical person-entity UID; required when `personalMode: true`. */
   personalUid?: string;
   vaultClient: FilesBrowseVaultClient;
-  s3Factory: S3ClientFactory;
+  /** PERSONAL mode: builds a direct-S3 client from vended creds. */
+  s3Factory?: S3ClientFactory;
+  /** COMPANY mode (HQ-59): builds the presign/list-backed client. */
+  companyClient?: CompanyBrowseClientFactory;
   region: string;
   /** Destination stream for the stdout path. Injectable for tests. */
   stdout?: NodeJS.WritableStream;
@@ -456,7 +503,8 @@ export interface RunCatInput {
 export interface RunCatResult {
   bytesWritten: number;
   destination: { kind: "stdout" } | { kind: "file"; absPath: string };
-  vend: BrowseVendResult;
+  /** Present ONLY for the PERSONAL (vendSelf + direct S3) path. */
+  vend?: BrowseVendResult;
 }
 
 /**
@@ -465,7 +513,7 @@ export interface RunCatResult {
  * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
  */
 export async function runCat(input: RunCatInput): Promise<RunCatResult> {
-  const { key, vaultClient, s3Factory, region, hqRoot, personalMode } = input;
+  const { key, vaultClient, region, hqRoot, personalMode } = input;
 
   // Acceptance 5: refuse BEFORE vending — no point pulling credentials
   // for a request we're already going to abort.
@@ -478,7 +526,8 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   // the personal-vs-company rationale.
   let bucket: string;
   let s3Key: string;
-  let vend: BrowseVendResult;
+  let vend: BrowseVendResult | undefined;
+  let s3: FilesBrowseS3Client;
   if (personalMode) {
     if (!input.personalUid) {
       throw new Error(
@@ -495,6 +544,14 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
     bucket = entity.bucketName;
     s3Key = key; // personal-mode keys are already bucket-relative
     vend = await vaultClient.sts.vendSelf({ personUid: entity.uid });
+    s3 = requirePersonalS3Factory(input.s3Factory)({
+      region,
+      credentials: {
+        accessKeyId: vend.credentials.accessKeyId,
+        secretAccessKey: vend.credentials.secretAccessKey,
+        sessionToken: vend.credentials.sessionToken,
+      },
+    });
   } else {
     const slug = input.companySlug ?? parseCompanySlugFromPath(key);
     const entity = await vaultClient.entity.findInMyNamespace("company", slug);
@@ -511,18 +568,10 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
     bucket = entity.bucketName;
     // Translate the anchored CLI key into the company-relative bucket key.
     s3Key = toBucketRelative(key, slug);
-    vend = await vaultClient.sts.vend({ companyUid: entity.uid });
+    // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
+    s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
   }
 
-  const s3 = s3Factory({
-    region,
-    credentials: {
-      accessKeyId: vend.credentials.accessKeyId,
-      secretAccessKey: vend.credentials.secretAccessKey,
-      sessionToken: vend.credentials.sessionToken,
-    },
-  });
-
   const resp = (await s3.send(
     new GetObjectCommand({ Bucket: bucket, Key: s3Key }),
   )) as GetObjectCommandOutput;
@@ -686,7 +735,10 @@ export interface RunSearchInput {
   personalMode?: boolean;
   personalUid?: string;
   vaultClient: FilesBrowseVaultClient;
-  s3Factory: S3ClientFactory;
+  /** PERSONAL mode: direct-S3 client factory. */
+  s3Factory?: S3ClientFactory;
+  /** COMPANY mode (HQ-59): presign/list client factory. */
+  companyClient?: CompanyBrowseClientFactory;
   region: string;
 }
 
@@ -707,6 +759,7 @@ export async function runSearch(input: RunSearchInput): Promise<BrowseRow[]> {
     personalUid: input.personalUid,
     vaultClient: input.vaultClient,
     s3Factory: input.s3Factory,
+    companyClient: input.companyClient,
     region: input.region,
   });
   const q = input.query.toLowerCase();
@@ -768,7 +821,11 @@ export interface RunGetInput {
   hqRoot: string;
   companySlug?: string;
   vaultClient: FilesBrowseVaultClient;
-  s3Factory: S3ClientFactory;
+  /**
+   * COMPANY mode (HQ-59): presign/list client factory. `get` is company-only,
+   * so it always goes through the API — no direct S3, no STS vend.
+   */
+  companyClient?: CompanyBrowseClientFactory;
   region: string;
 }
 
@@ -791,7 +848,7 @@ export interface RunGetResult {
  * HQ root itself, which is too broad to do implicitly.
  */
 export async function runGet(input: RunGetInput): Promise<RunGetResult> {
-  const { path: vaultPath, vaultClient, s3Factory, region, hqRoot } = input;
+  const { path: vaultPath, vaultClient, hqRoot } = input;
   const slug = input.companySlug ?? parseCompanySlugFromPath(vaultPath);
 
   const entity = await vaultClient.entity.findInMyNamespace("company", slug);
@@ -804,15 +861,9 @@ export async function runGet(input: RunGetInput): Promise<RunGetResult> {
     throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
   }
   const bucket = entity.bucketName;
-  const vend = await vaultClient.sts.vend({ companyUid: entity.uid });
-  const s3 = s3Factory({
-    region,
-    credentials: {
-      accessKeyId: vend.credentials.accessKeyId,
-      secretAccessKey: vend.credentials.secretAccessKey,
-      sessionToken: vend.credentials.sessionToken,
-    },
-  });
+  // COMPANY mode (HQ-59): list + get through the presign/list API. No STS vend,
+  // no direct S3 — the server enforces the same per-file read ACLs.
+  const s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
 
   // Company-relative prefix to list/fetch (bucket keys carry no anchor).
   const bucketPrefix = toBucketRelative(vaultPath, slug);
@@ -882,6 +933,134 @@ export async function runGet(input: RunGetInput): Promise<RunGetResult> {
 const defaultS3Factory: S3ClientFactory = ({ region, credentials }) =>
   new S3Client({ region, credentials });
 
+// ── Company-mode presign/list client (HQ-59) ────────────────────────────────
+//
+// The COMPANY browse/cat/get/search path no longer talks to S3 directly. Per
+// the HQ-59 directive ("no client talks to S3 directly"), it goes through the
+// server-side vault API, which enforces the SAME per-file ACLs the STS vend
+// policy used to — so the per-file STS scoping can be dropped later:
+//   - ListObjectsV2  → GET  /v1/files/list  (flat, ACL-filtered, paginated)
+//   - GetObject      → POST /v1/files/presign (op:'get') → fetch the URL
+//
+// It implements the existing `FilesBrowseS3Client` interface so the
+// orchestrators' S3-shaped calls are unchanged; the `Bucket` field on each
+// command is ignored (the server resolves the bucket from the companyUid).
+// The PERSONAL (vendSelf) path keeps using direct S3 via `defaultS3Factory`.
+
+/** Shape of one object in a GET /v1/files/list response. */
+interface FilesListObject {
+  key: string;
+  size: number;
+  lastModified: string | null;
+  etag: string | null;
+  permission: string;
+}
+
+/**
+ * Build a COMPANY-mode browse client backed by the list + presign API. The
+ * access token + companyUid are captured here; the orchestrator just calls
+ * `send(...)` as if it held an S3 client.
+ */
+export function createCompanyPresignClient(input: {
+  token: string;
+  companyUid: string;
+}): FilesBrowseS3Client {
+  const { token, companyUid } = input;
+
+  async function listObjects(
+    cmd: ListObjectsV2Command,
+  ): Promise<ListObjectsV2CommandOutput> {
+    const prefix = cmd.input.Prefix ?? "";
+    const query: Record<string, string> = { company: companyUid };
+    if (prefix.length > 0) query.prefix = prefix;
+    if (cmd.input.ContinuationToken) query.cursor = cmd.input.ContinuationToken;
+
+    const res = await vaultApiFetch({ token, path: "/v1/files/list", query });
+    if (!res.ok) {
+      const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+      throw new Error(
+        body.message ?? body.error ?? `files list failed (${res.status})`,
+      );
+    }
+    const body = (await res.json()) as {
+      objects?: FilesListObject[];
+      cursor?: string | null;
+      truncated?: boolean;
+    };
+    return {
+      // Map the API's company-relative objects onto the ListObjectsV2 shape the
+      // orchestrators read (Key / Size / LastModified / ETag). Re-quote the
+      // etag to match S3's quoted form, in case any caller compares it.
+      Contents: (body.objects ?? []).map((o) => ({
+        Key: o.key,
+        Size: o.size,
+        LastModified: o.lastModified ? new Date(o.lastModified) : undefined,
+        ETag: o.etag != null ? `"${o.etag}"` : undefined,
+      })),
+      NextContinuationToken: body.cursor ?? undefined,
+      IsTruncated: Boolean(body.truncated),
+      // $metadata is required by the SDK output type; the orchestrators never
+      // read it, so a minimal stub is sufficient.
+      $metadata: {},
+    } as ListObjectsV2CommandOutput;
+  }
+
+  async function getObject(
+    cmd: GetObjectCommand,
+  ): Promise<GetObjectCommandOutput> {
+    const key = cmd.input.Key as string;
+    const res = await vaultApiFetch({
+      token,
+      path: "/v1/files/presign",
+      method: "POST",
+      body: { company: companyUid, key, op: "get" },
+    });
+    if (!res.ok) {
+      const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+      throw new Error(
+        body.message ?? body.error ?? `presign failed (${res.status})`,
+      );
+    }
+    const body = (await res.json()) as {
+      results?: Array<{ key: string; url?: string; error?: string; code?: string }>;
+    };
+    const first = body.results?.[0];
+    if (!first || !first.url) {
+      // Per-key denial/validation surfaces here (e.g. FILES_PRESIGN_FORBIDDEN).
+      throw new Error(first?.error ?? `No presigned URL returned for '${key}'`);
+    }
+
+    const dl = await fetch(first.url);
+    if (!dl.ok) {
+      throw new Error(`Failed to download '${key}' (HTTP ${dl.status})`);
+    }
+    // fetch() yields a web ReadableStream; the orchestrators consume Body as a
+    // Node Readable (body.on('data') + stream pipeline), so adapt it. An empty
+    // body (no stream) becomes an empty Readable.
+    const nodeBody = dl.body
+      ? Readable.fromWeb(dl.body as Parameters<typeof Readable.fromWeb>[0])
+      : Readable.from([]);
+    return { Body: nodeBody, $metadata: {} } as unknown as GetObjectCommandOutput;
+  }
+
+  function send(cmd: ListObjectsV2Command): Promise<ListObjectsV2CommandOutput>;
+  function send(cmd: GetObjectCommand): Promise<GetObjectCommandOutput>;
+  function send(
+    cmd: ListObjectsV2Command | GetObjectCommand,
+  ): Promise<ListObjectsV2CommandOutput | GetObjectCommandOutput> {
+    if (cmd instanceof ListObjectsV2Command) return listObjects(cmd);
+    if (cmd instanceof GetObjectCommand) return getObject(cmd);
+    throw new Error("createCompanyPresignClient: unsupported S3 command");
+  }
+
+  return { send };
+}
+
+/** Production company-mode client factory — closes over the caller's token. */
+function makeCompanyPresignFactory(token: string): CompanyBrowseClientFactory {
+  return ({ companyUid }) => createCompanyPresignClient({ token, companyUid });
+}
+
 interface FilesBrowseCliOptions {
   company?: string;
   hqRoot: string;
@@ -1013,7 +1192,7 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
           pathPrefix: pathArg,
           companySlug: slug,
           vaultClient: client,
-          s3Factory: defaultS3Factory,
+          companyClient: makeCompanyPresignFactory(accessToken),
           region: DEFAULT_COGNITO.region,
         });
 
@@ -1127,7 +1306,7 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
           hqRoot: options.hqRoot,
           companySlug: slug,
           vaultClient: client,
-          s3Factory: defaultS3Factory,
+          companyClient: makeCompanyPresignFactory(accessToken),
           region: DEFAULT_COGNITO.region,
         });
 
@@ -1240,7 +1419,7 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
           query,
           companySlug: company,
           vaultClient: client,
-          s3Factory: defaultS3Factory,
+          companyClient: makeCompanyPresignFactory(accessToken),
           region: DEFAULT_COGNITO.region,
         });
         console.log(formatBrowseTable(rows));
@@ -1301,7 +1480,7 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
           hqRoot: options.hqRoot,
           companySlug: slug,
           vaultClient: client,
-          s3Factory: defaultS3Factory,
+          companyClient: makeCompanyPresignFactory(accessToken),
           region: DEFAULT_COGNITO.region,
         });
 

package/src/commands/signals.ts

@@ -31,6 +31,7 @@ import {
   listAvailableEntities,
   listSignals,
   getSignal,
+  VaultClient,
   type SignalType,
   type SignalSummary,
   type SignalDocument,
@@ -164,6 +165,9 @@ async function runList(options: ListOptions): Promise<void> {
     limit,
     continuationToken: options.pageToken,
     includeFrontmatter: options.includeFrontmatter,
+    // HQ-59: route company (cmp_) reads through the ACL-filtered presign
+    // transport (no direct S3). Personal vaults / no-client stay on S3.
+    vault: new VaultClient(vaultConfig),
   });
 
   if (format === "json") {
@@ -212,6 +216,8 @@ async function runGet(options: GetOptions): Promise<void> {
     entity,
     signalType,
     signalId: options.id,
+    // HQ-59: company (cmp_) reads over presign; personal/no-client stay on S3.
+    vault: new VaultClient(vaultConfig),
   });
 
   if (format === "json") {

package/src/commands/sources.ts

@@ -29,6 +29,7 @@ import {
   listAvailableEntities,
   listSources,
   getSource,
+  VaultClient,
   type SourceChannel,
   type SourceSummary,
   type SourceDocument,
@@ -172,6 +173,9 @@ async function runList(options: ListOptions): Promise<void> {
     limit,
     continuationToken: options.pageToken,
     includeFrontmatter: options.includeFrontmatter,
+    // HQ-59: route company (cmp_) reads through the ACL-filtered presign
+    // transport (no direct S3). Personal vaults / no-client stay on S3.
+    vault: new VaultClient(vaultConfig),
   });
 
   if (format === "json") {
@@ -222,6 +226,8 @@ async function runGet(options: GetOptions): Promise<void> {
     channel,
     sourceId: options.id,
     includeRaw: options.includeRaw,
+    // HQ-59: company (cmp_) reads over presign; personal/no-client stay on S3.
+    vault: new VaultClient(vaultConfig),
   });
 
   if (format === "json") {

package/test/commands/signals.test.ts

@@ -24,7 +24,6 @@ import {
   _setSignalsS3Factory,
   _resetSignalsS3Factory,
 } from "@indigoai-us/hq-cloud";
-import { mockS3WithEntries } from "../helpers/s3-list-mock.js";
 import { mockVaultService } from "../helpers/vault-service-mock.js";
 import { runCli } from "../helpers/cli-runner.js";
 
@@ -62,8 +61,21 @@ beforeEach(() => {
 
   tmpHqRoot = mkdtempSync(join(tmpdir(), "hq-signals-test-"));
 
-  const s3 = mockS3WithEntries({
-    entries: [
+  // Transport-switch proof: every read in this suite targets a COMPANY (cmp_)
+  // entity, which routes through presign as of HQ-59. The direct-S3 factory is
+  // wired to THROW so any read accidentally falling back to S3 fails loudly
+  // (mirrors hq-cloud's #88 "S3 stub throws if touched" tests).
+  _setSignalsS3Factory(() => {
+    throw new Error(
+      "S3 transport must not be used for a company (cmp_) read — HQ-59 routes these through presign",
+    );
+  });
+
+  // `files` serves the fixture over the presigned-URL transport (the path
+  // company reads take).
+  restoreFetch = mockVaultService({
+    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
+    files: [
       {
         key: "signals/action_item/xyz.md",
         content: ACTION_ITEM_MD,
@@ -71,11 +83,6 @@ beforeEach(() => {
       },
     ],
   });
-  _setSignalsS3Factory(() => s3);
-
-  restoreFetch = mockVaultService({
-    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
-  });
 });
 
 afterEach(() => {

package/test/commands/sources.test.ts

@@ -26,7 +26,6 @@ import {
   _setSourcesS3Factory,
   _resetSourcesS3Factory,
 } from "@indigoai-us/hq-cloud";
-import { mockS3WithEntries } from "../helpers/s3-list-mock.js";
 import { mockVaultService } from "../helpers/vault-service-mock.js";
 import { runCli } from "../helpers/cli-runner.js";
 
@@ -72,9 +71,21 @@ beforeEach(() => {
   // test writes config.json into it.
   tmpHqRoot = mkdtempSync(join(tmpdir(), "hq-sources-test-"));
 
-  // Default S3 stub returns the one meeting source.
-  const s3 = mockS3WithEntries({
-    entries: [
+  // Transport-switch proof: every read in this suite targets a COMPANY (cmp_)
+  // entity, which routes through presign as of HQ-59. The direct-S3 factory is
+  // wired to THROW so that any read accidentally falling back to S3 fails the
+  // test loudly (mirrors hq-cloud's #88 "S3 stub throws if touched" tests).
+  _setSourcesS3Factory(() => {
+    throw new Error(
+      "S3 transport must not be used for a company (cmp_) read — HQ-59 routes these through presign",
+    );
+  });
+
+  // Default vault-service mock with one entity 'indigo'. `files` serves the
+  // fixture over the presigned-URL transport (the path company reads take).
+  restoreFetch = mockVaultService({
+    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
+    files: [
       {
         key: "sources/meetings/abc.md",
         content: MEETING_MD,
@@ -82,12 +93,6 @@ beforeEach(() => {
       },
     ],
   });
-  _setSourcesS3Factory(() => s3);
-
-  // Default vault-service mock with one entity 'indigo'.
-  restoreFetch = mockVaultService({
-    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
-  });
 });
 
 afterEach(() => {

package/test/helpers/vault-service-mock.ts

@@ -33,12 +33,33 @@ export interface MockStsCredentials {
   sessionToken: string;
 }
 
+/** A file served over the presigned-URL transport (HQ-59 company reads). */
+export interface MockVaultFile {
+  /** Object key (e.g. "sources/meetings/abc.md") */
+  key: string;
+  /** Full file content as UTF-8 string */
+  content: string;
+  /** Optional override; defaults to 2026-01-01T00:00:00Z */
+  lastModified?: Date;
+}
+
 export interface MockVaultOptions {
   entities: MockEntity[];
   /** STS credentials returned for every POST /entities/{uid}/sts; defaults to test creds */
   stsCredentials?: MockStsCredentials;
+  /**
+   * Files served over the presigned-URL transport (`GET /v1/files/list`,
+   * `POST /v1/files/presign`, then a GET against the minted URL). Supplied so
+   * company (cmp_) reads — which route through presign as of HQ-59 — resolve
+   * without touching real S3. Absent → those endpoints return empty/404.
+   */
+  files?: MockVaultFile[];
 }
 
+/** Host for mock presigned URLs minted by POST /v1/files/presign. */
+const PRESIGN_URL_HOST = "https://presigned.test";
+const DEFAULT_FILE_DATE = new Date("2026-01-01T00:00:00Z");
+
 const DEFAULT_STS: MockStsCredentials = {
   accessKeyId: "ASIAMOCK000000000001",
   secretAccessKey: "mockSecretAccessKey",
@@ -51,7 +72,7 @@ const DEFAULT_STS: MockStsCredentials = {
  * @returns A restore function — call it in afterEach to un-install the stub.
  */
 export function mockVaultService(opts: MockVaultOptions): () => void {
-  const { entities, stsCredentials = DEFAULT_STS } = opts;
+  const { entities, stsCredentials = DEFAULT_STS, files = [] } = opts;
   const originalFetch = globalThis.fetch as typeof fetch | undefined;
 
   globalThis.fetch = async (
@@ -67,6 +88,56 @@ export function mockVaultService(opts: MockVaultOptions): () => void {
     const method =
       (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
 
+    // ── Presigned-URL transport (HQ-59 company reads) ──────────────────────
+    // A GET against a URL minted by POST /v1/files/presign below. Serve the
+    // file body (or 404) so PresignObjectIO.getObject resolves like real S3.
+    if (url.startsWith(`${PRESIGN_URL_HOST}/`)) {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const file = files.find((f) => f.key === key);
+      if (!file) return new Response("", { status: 404 });
+      return new Response(file.content, {
+        status: 200,
+        headers: {
+          "Content-Type": "text/markdown",
+          "Content-Length": String(Buffer.byteLength(file.content, "utf-8")),
+          "Last-Modified": (file.lastModified ?? DEFAULT_FILE_DATE).toUTCString(),
+          ETag: '"mock-etag"',
+        },
+      });
+    }
+
+    // GET /v1/files/list?company=<uid>&prefix=<p>&cursor=<c>  (VaultClient.listFiles)
+    if (method === "GET" && /\/v1\/files\/list(\?|$)/.test(url)) {
+      const prefix = new URL(url).searchParams.get("prefix") ?? "";
+      const objects = files
+        .filter((f) => f.key.startsWith(prefix))
+        .map((f) => ({
+          key: f.key,
+          size: Buffer.byteLength(f.content, "utf-8"),
+          lastModified: (f.lastModified ?? DEFAULT_FILE_DATE).toISOString(),
+          etag: "mock-etag",
+          permission: "read",
+        }));
+      return json({ objects, cursor: null, truncated: false });
+    }
+
+    // POST /v1/files/presign  (VaultClient.presign) — mint a per-key URL that
+    // the GET handler above resolves. Unknown keys still get a URL → that GET
+    // 404s, which the reader normalizes to NoSuchKey (the not-found path).
+    if (method === "POST" && /\/v1\/files\/presign$/.test(url)) {
+      const body = init?.body ? JSON.parse(init.body.toString()) : {};
+      const keys = (body.keys ?? []) as Array<{ key: string }>;
+      const results = keys.map((k) => ({
+        key: k.key,
+        url: `${PRESIGN_URL_HOST}/obj?key=${encodeURIComponent(k.key)}`,
+        error: null,
+      }));
+      return json({
+        results,
+        expiresAt: new Date(Date.now() + 3600 * 1000).toISOString(),
+      });
+    }
+
     // GET /membership/me
     if (method === "GET" && /\/membership\/me(\?.*)?$/.test(url)) {
       const memberships: Partial<Membership>[] = entities.map((e) => ({