@indigoai-us/hq-cli 5.47.6 → 5.47.7

package/dist/commands/files-browse.d.ts

@@ -98,6 +98,15 @@ export type S3ClientFactory = (input: {
         sessionToken: string;
     };
 }) => 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.
@@ -190,12 +199,23 @@ 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;
 }
 /**
  * `hq files browse <path>` orchestrator.
@@ -230,7 +250,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;
@@ -243,7 +266,8 @@ export interface RunCatResult {
         kind: "file";
         absPath: string;
     };
-    vend: BrowseVendResult;
+    /** Present ONLY for the PERSONAL (vendSelf + direct S3) path. */
+    vend?: BrowseVendResult;
 }
 /**
  * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then
@@ -308,7 +332,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;
 }
 /**
@@ -348,7 +375,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;
 }
 export interface RunGetResult {
@@ -372,6 +403,15 @@ export interface RunGetResult {
  * HQ root itself, which is too broad to do implicitly.
  */
 export declare function runGet(input: RunGetInput): Promise<RunGetResult>;
+/**
+ * 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 declare function createCompanyPresignClient(input: {
+    token: string;
+    companyUid: string;
+}): FilesBrowseS3Client;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group

package/dist/commands/files-browse.js

@@ -34,15 +34,16 @@
  * methods and `grantPathToPrefix` from hq-cloud.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cad165f9-6445-5434-969b-e0705274aa56")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="76062756-52c6-58a0-a647-9fcc95550911")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
 import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, 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";
 // ── Pure helpers ────────────────────────────────────────────────────────────
 /**
@@ -142,6 +143,20 @@ export function formatBrowseTable(rows) {
     ];
     return lines.join("\n");
 }
+/** Guard: the personal path needs an S3 factory. */
+function requirePersonalS3Factory(f) {
+    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) {
+    if (!f) {
+        throw new Error("Company browse requires a companyClient (presign/list client).");
+    }
+    return f;
+}
 /**
  * `hq files browse <path>` orchestrator.
  *
@@ -156,7 +171,7 @@ export function formatBrowseTable(rows) {
  * Pure-ish: no console output, no process.exit — caller renders + exits.
  */
 export async function runBrowse(input) {
-    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
     // person UID and skips the slug + grants machinery (a person bucket has
@@ -165,6 +180,7 @@ export async function runBrowse(input) {
     let entityUid;
     let slug;
     let vend;
+    let s3;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runBrowse: personalMode requires personalUid. Resolve via " +
@@ -176,7 +192,17 @@ export async function runBrowse(input) {
         }
         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);
@@ -189,19 +215,10 @@ export async function runBrowse(input) {
         }
         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.
@@ -253,7 +270,7 @@ export async function runBrowse(input) {
  * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
  */
 export async function runCat(input) {
-    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.
     let absOut;
@@ -265,6 +282,7 @@ export async function runCat(input) {
     let bucket;
     let s3Key;
     let vend;
+    let s3;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runCat: personalMode requires personalUid. Resolve via " +
@@ -277,6 +295,14 @@ export async function runCat(input) {
         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);
@@ -290,16 +316,9 @@ export async function runCat(input) {
         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 })));
     if (!resp.Body) {
         throw new Error(`GetObject for '${key}' returned no body.`);
@@ -417,6 +436,7 @@ export async function runSearch(input) {
         personalUid: input.personalUid,
         vaultClient: input.vaultClient,
         s3Factory: input.s3Factory,
+        companyClient: input.companyClient,
         region: input.region,
     });
     const q = input.query.toLowerCase();
@@ -467,7 +487,7 @@ export function addPin(hqRoot, companySlug, prefix) {
  * HQ root itself, which is too broad to do implicitly.
  */
 export async function runGet(input) {
-    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);
     if (!entity) {
@@ -477,15 +497,9 @@ export async function runGet(input) {
         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);
     const keys = [];
@@ -544,6 +558,86 @@ export async function runGet(input) {
 }
 // ── CLI registration ────────────────────────────────────────────────────────
 const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, credentials });
+/**
+ * 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) {
+    const { token, companyUid } = input;
+    async function listObjects(cmd) {
+        const prefix = cmd.input.Prefix ?? "";
+        const query = { 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(() => ({})));
+            throw new Error(body.message ?? body.error ?? `files list failed (${res.status})`);
+        }
+        const body = (await res.json());
+        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: {},
+        };
+    }
+    async function getObject(cmd) {
+        const key = cmd.input.Key;
+        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(() => ({})));
+            throw new Error(body.message ?? body.error ?? `presign failed (${res.status})`);
+        }
+        const body = (await res.json());
+        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)
+            : Readable.from([]);
+        return { Body: nodeBody, $metadata: {} };
+    }
+    function send(cmd) {
+        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) {
+    return ({ companyUid }) => createCompanyPresignClient({ token, companyUid });
+}
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group
@@ -622,7 +716,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 pathPrefix: pathArg,
                 companySlug: slug,
                 vaultClient: client,
-                s3Factory: defaultS3Factory,
+                companyClient: makeCompanyPresignFactory(accessToken),
                 region: DEFAULT_COGNITO.region,
             });
             console.log(formatBrowseTable(result.rows));
@@ -699,7 +793,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 hqRoot: options.hqRoot,
                 companySlug: slug,
                 vaultClient: client,
-                s3Factory: defaultS3Factory,
+                companyClient: makeCompanyPresignFactory(accessToken),
                 region: DEFAULT_COGNITO.region,
             });
             if (result.destination.kind === "file") {
@@ -781,7 +875,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 query,
                 companySlug: company,
                 vaultClient: client,
-                s3Factory: defaultS3Factory,
+                companyClient: makeCompanyPresignFactory(accessToken),
                 region: DEFAULT_COGNITO.region,
             });
             console.log(formatBrowseTable(rows));
@@ -824,7 +918,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 hqRoot: options.hqRoot,
                 companySlug: slug,
                 vaultClient: client,
-                s3Factory: defaultS3Factory,
+                companyClient: makeCompanyPresignFactory(accessToken),
                 region: DEFAULT_COGNITO.region,
             });
             console.error(chalk.green("✓"), `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`);
@@ -839,4 +933,4 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=cad165f9-6445-5434-969b-e0705274aa56
+//# debugId=76062756-52c6-58a0-a647-9fcc95550911

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.47.6",
+  "version": "5.47.7",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.11.4",
+    "@indigoai-us/hq-cloud": "^6.11.5",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

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

@@ -42,11 +42,13 @@ import {
   pinFilePath,
   runSharedWithMe,
   formatSharedWithMeTable,
+  createCompanyPresignClient,
   type BrowseVendResult,
   type FilesBrowseS3Client,
   type FilesBrowseVaultClient,
   type FilesSharedWithMeVaultClient,
   type S3ClientFactory,
+  type CompanyBrowseClientFactory,
 } from "./files-browse.js";
 import type { ExplicitGrant } from "@indigoai-us/hq-cloud";
 import {
@@ -143,6 +145,14 @@ interface StubS3Opts {
 
 function makeStubS3Factory(opts: StubS3Opts): {
   factory: S3ClientFactory;
+  /**
+   * The SAME stub typed as a company-mode client factory. Company browse/cat/
+   * get/search now inject `companyClient` (the presign/list seam) instead of
+   * `s3Factory`; the stub ignores its factory arg either way, so one stub
+   * serves both. Personal-mode tests use `factory`; company-mode tests use
+   * `companyFactory`.
+   */
+  companyFactory: CompanyBrowseClientFactory;
   sendSpy: ReturnType<typeof vi.fn>;
   factorySpy: ReturnType<typeof vi.fn>;
 } {
@@ -163,7 +173,12 @@ function makeStubS3Factory(opts: StubS3Opts): {
         send: sendSpy,
       }) as unknown as FilesBrowseS3Client,
   );
-  return { factory: factorySpy as unknown as S3ClientFactory, sendSpy, factorySpy };
+  return {
+    factory: factorySpy as unknown as S3ClientFactory,
+    companyFactory: factorySpy as unknown as CompanyBrowseClientFactory,
+    sendSpy,
+    factorySpy,
+  };
 }
 
 // ── parseCompanySlugFromPath ────────────────────────────────────────────────
@@ -359,22 +374,22 @@ describe("formatBrowseTable", () => {
 // ── runBrowse ───────────────────────────────────────────────────────────────
 
 describe("runBrowse", () => {
-  it("vends via /sts/vend (company) and lists the company-relative prefix", async () => {
+  it("company mode lists via the presign/list client (no STS vend) on the company-relative prefix", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory, sendSpy } = makeStubS3Factory({
+    const { companyFactory, sendSpy } = makeStubS3Factory({
       listResponses: [{ Contents: [] }],
     });
     await runBrowse({
       pathPrefix: "companies/indigo/scratch/",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
     });
-    // Vend through the multi-tenant STS route — NOT the legacy POST /vend.
-    expect(spies.stsVend).toHaveBeenCalledTimes(1);
-    expect(spies.stsVend.mock.calls[0][0]).toEqual({ companyUid: "cmp_indigo" });
+    // HQ-59: company browse no longer vends STS creds — it goes through the
+    // server-side list API, so NEITHER vend route is touched.
+    expect(spies.stsVend).not.toHaveBeenCalled();
     expect(spies.vendSelf).not.toHaveBeenCalled();
-    // S3 list prefix is company-relative (the bug: was anchored → 0 results).
+    // List prefix is company-relative (the bug: was anchored → 0 results).
     const listCmd = sendSpy.mock.calls[0][0] as ListObjectsV2Command;
     expect(listCmd.input.Prefix).toBe("scratch/");
   });
@@ -384,8 +399,8 @@ describe("runBrowse", () => {
       // Real grants are glob/anchored; normalization folds this to "scratch/".
       grants: [fakeGrant("companies/indigo/scratch/*")],
     });
-    const { factory, sendSpy } = makeStubS3Factory({
-      // S3 keys are company-relative (no companies/<slug>/ prefix).
+    const { companyFactory, sendSpy } = makeStubS3Factory({
+      // List objects are company-relative (no companies/<slug>/ prefix).
       listResponses: [
         {
           Contents: [
@@ -422,7 +437,7 @@ describe("runBrowse", () => {
     const result = await runBrowse({
       pathPrefix: "companies/indigo/scratch/",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
     });
     expect(sendSpy).toHaveBeenCalledTimes(2); // pagination
@@ -600,9 +615,9 @@ describe("runBrowse", () => {
 // ── runCat ──────────────────────────────────────────────────────────────────
 
 describe("runCat", () => {
-  it("vends via /sts/vend and GetObjects the company-relative key", async () => {
+  it("company mode fetches the company-relative key via presign (no STS vend)", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory, sendSpy } = makeStubS3Factory({
+    const { companyFactory, sendSpy } = makeStubS3Factory({
       getResponse: {
         Body: Readable.from(Buffer.from("hello world")),
       } as GetObjectCommandOutput,
@@ -612,25 +627,25 @@ describe("runCat", () => {
     await runCat({
       key: "companies/indigo/scratch/a.txt",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
       hqRoot: tmpRoot,
       stdout: sink,
     });
-    expect(spies.stsVend).toHaveBeenCalledTimes(1);
-    expect(spies.stsVend.mock.calls[0][0]).toEqual({ companyUid: "cmp_indigo" });
+    // HQ-59: company cat goes through the presign API — no STS vend.
+    expect(spies.stsVend).not.toHaveBeenCalled();
+    expect(spies.vendSelf).not.toHaveBeenCalled();
     // GetObject key is company-relative (anchor stripped).
     const getCmd = sendSpy.mock.calls.find(
       (c) => c[0] instanceof GetObjectCommand,
     )?.[0] as GetObjectCommand;
-    expect(getCmd.input.Bucket).toBe("hq-vault-cmp-indigo");
     expect(getCmd.input.Key).toBe("scratch/a.txt");
   });
 
   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({
+    const { companyFactory } = makeStubS3Factory({
       getResponse: {
         Body: Readable.from(payload),
       } as GetObjectCommandOutput,
@@ -640,7 +655,7 @@ describe("runCat", () => {
       key: "companies/indigo/scratch/a.txt",
       out: outFile,
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
       hqRoot: tmpRoot,
     });
@@ -651,7 +666,7 @@ describe("runCat", () => {
 
   it("refuses --out under <hqRoot>/companies/ BEFORE vending (no leak)", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory, sendSpy } = makeStubS3Factory({
+    const { companyFactory, sendSpy } = makeStubS3Factory({
       getResponse: { Body: Readable.from(Buffer.from("nope")) } as GetObjectCommandOutput,
     });
     const badOut = path.join(tmpRoot, "companies", "indigo", "leaked.txt");
@@ -660,13 +675,13 @@ describe("runCat", () => {
         key: "companies/indigo/scratch/a.txt",
         out: badOut,
         vaultClient: client,
-        s3Factory: factory,
+        companyClient: companyFactory,
         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.
+    // Critically: the guard runs FIRST — no vend, and no list/presign/S3 call
+    // was made. Failing closed is the whole point of the guard.
     expect(spies.stsVend).not.toHaveBeenCalled();
     expect(spies.vendSelf).not.toHaveBeenCalled();
     expect(sendSpy).not.toHaveBeenCalled();
@@ -843,7 +858,7 @@ describe("runSharedWithMe", () => {
 describe("runSearch", () => {
   it("filters the company listing by case-insensitive substring on the key", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({
+    const { companyFactory } = makeStubS3Factory({
       listResponses: [
         {
           Contents: [
@@ -858,20 +873,21 @@ describe("runSearch", () => {
       query: "roadmap", // lower-case query matches mixed-case key
       companySlug: "indigo",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
     });
     // Keys are re-anchored for display; only the matching one survives.
     expect(rows.map((r) => r.key)).toEqual([
       "companies/indigo/knowledge/Roadmap.md",
     ]);
-    // Vends via the multi-tenant route (inherited from runBrowse).
-    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+    // HQ-59: search lists via the presign/list API (inherited from runBrowse) —
+    // no STS vend.
+    expect(spies.stsVend).not.toHaveBeenCalled();
   });
 
   it("returns an empty array when nothing matches", async () => {
     const { client } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({
+    const { companyFactory } = makeStubS3Factory({
       listResponses: [
         { Contents: [{ Key: "knowledge/a.md", Size: 1, LastModified: new Date() }] },
       ],
@@ -880,7 +896,7 @@ describe("runSearch", () => {
       query: "zzz-no-match",
       companySlug: "indigo",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
     });
     expect(rows).toEqual([]);
@@ -922,7 +938,7 @@ describe("pin set", () => {
 function makeGetStubS3(opts: {
   listKeys: Array<{ Key: string; Size: number }>;
   bodyFor: (key: string) => Buffer;
-}): { factory: S3ClientFactory; sendSpy: ReturnType<typeof vi.fn> } {
+}): { companyFactory: CompanyBrowseClientFactory; sendSpy: ReturnType<typeof vi.fn> } {
   const sendSpy = vi.fn(async (cmd: unknown) => {
     if (cmd instanceof ListObjectsV2Command) {
       return {
@@ -937,16 +953,17 @@ function makeGetStubS3(opts: {
     }
     throw new Error(`unexpected command: ${cmd}`);
   });
-  const factory = vi.fn(
+  // `get` is company-only now, so the stub is the presign/list seam.
+  const companyFactory = vi.fn(
     () => ({ send: sendSpy }) as unknown as FilesBrowseS3Client,
-  ) as unknown as S3ClientFactory;
-  return { factory, sendSpy };
+  ) as unknown as CompanyBrowseClientFactory;
+  return { companyFactory, sendSpy };
 }
 
 describe("runGet", () => {
   it("materializes a prefix in-place under companies/<slug>/ and registers a pin", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory, sendSpy } = makeGetStubS3({
+    const { companyFactory, sendSpy } = makeGetStubS3({
       listKeys: [
         { Key: "knowledge/a.md", Size: 3 },
         { Key: "knowledge/sub/b.md", Size: 3 },
@@ -959,12 +976,12 @@ describe("runGet", () => {
       hqRoot: tmpRoot,
       companySlug: "indigo",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
     });
 
-    // Vends via the multi-tenant company route.
-    expect(spies.stsVend).toHaveBeenCalledWith({ companyUid: "cmp_indigo" });
+    // HQ-59: get materializes through the presign/list API — no STS vend.
+    expect(spies.stsVend).not.toHaveBeenCalled();
     expect(result.filesWritten).toBe(2);
 
     // Files landed in place under companies/<slug>/.
@@ -995,7 +1012,7 @@ describe("runGet", () => {
   it("--into writes outside companies/ and registers NO pin", async () => {
     const into = path.join(tmpRoot, "extract");
     const { client } = makeStubVaultClient({});
-    const { factory } = makeGetStubS3({
+    const { companyFactory } = makeGetStubS3({
       listKeys: [{ Key: "knowledge/a.md", Size: 3 }],
       bodyFor: () => Buffer.from("AAA"),
     });
@@ -1006,7 +1023,7 @@ describe("runGet", () => {
       hqRoot: tmpRoot,
       companySlug: "indigo",
       vaultClient: client,
-      s3Factory: factory,
+      companyClient: companyFactory,
       region: "us-east-1",
     });
 
@@ -1019,7 +1036,7 @@ describe("runGet", () => {
 
   it("throws when no objects exist under the path", async () => {
     const { client } = makeStubVaultClient({});
-    const { factory } = makeGetStubS3({
+    const { companyFactory } = makeGetStubS3({
       listKeys: [],
       bodyFor: () => Buffer.from(""),
     });
@@ -1029,7 +1046,7 @@ describe("runGet", () => {
         hqRoot: tmpRoot,
         companySlug: "indigo",
         vaultClient: client,
-        s3Factory: factory,
+        companyClient: companyFactory,
         region: "us-east-1",
       }),
     ).rejects.toThrow(/No objects under/);
@@ -1083,3 +1100,150 @@ describe("--company parent binding (optsWithGlobals)", () => {
     expect(local).toBeUndefined();
   });
 });
+
+// ── createCompanyPresignClient (HQ-59 list/presign translation) ─────────────
+//
+// The company-mode browse client. Verifies it translates the S3-shaped
+// commands the orchestrators issue into the server-side list/presign API:
+//   - ListObjectsV2Command → GET  /v1/files/list  (company-relative objects)
+//   - GetObjectCommand     → POST /v1/files/presign → fetch(url) → Body
+// fetch is the single network seam (vaultApiFetch uses it; the presigned
+// download uses it), so we spy on globalThis.fetch and route by URL.
+
+describe("createCompanyPresignClient", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  function json(status: number, body: unknown): Response {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  it("ListObjectsV2 → GET /v1/files/list, mapping objects + cursor onto the S3 shape", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      json(200, {
+        prefix: "scratch/",
+        objects: [
+          {
+            key: "scratch/a.txt",
+            size: 12,
+            lastModified: "2026-01-01T00:00:00.000Z",
+            etag: "abc123",
+            permission: "read",
+          },
+        ],
+        cursor: "next-page",
+        truncated: true,
+      }),
+    );
+
+    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
+    const out = await client.send(
+      new ListObjectsV2Command({
+        Bucket: "ignored",
+        Prefix: "scratch/",
+        ContinuationToken: undefined,
+      }),
+    );
+
+    // Request: GET to /v1/files/list with company + prefix query, bearer token.
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/files/list");
+    expect(String(url)).toContain("company=cmp_indigo");
+    expect(String(url)).toContain("prefix=scratch%2F");
+    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer tok");
+
+    // Response mapped onto the ListObjectsV2 shape the orchestrators read.
+    expect(out.Contents).toHaveLength(1);
+    expect(out.Contents?.[0].Key).toBe("scratch/a.txt");
+    expect(out.Contents?.[0].Size).toBe(12);
+    expect(out.Contents?.[0].ETag).toBe('"abc123"');
+    expect(out.Contents?.[0].LastModified?.toISOString()).toBe("2026-01-01T00:00:00.000Z");
+    expect(out.NextContinuationToken).toBe("next-page");
+    expect(out.IsTruncated).toBe(true);
+  });
+
+  it("ListObjectsV2 forwards the ContinuationToken as the cursor query param", async () => {
+    fetchSpy.mockResolvedValueOnce(json(200, { objects: [], cursor: null, truncated: false }));
+    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
+    await client.send(new ListObjectsV2Command({ Bucket: "b", Prefix: "k/", ContinuationToken: "page2" }));
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("cursor=page2");
+  });
+
+  it("ListObjectsV2 throws on a non-2xx list response", async () => {
+    fetchSpy.mockResolvedValueOnce(json(403, { error: "Forbidden", code: "X" }));
+    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
+    await expect(
+      client.send(new ListObjectsV2Command({ Bucket: "b", Prefix: "k/" })),
+    ).rejects.toThrow(/Forbidden/);
+  });
+
+  it("GetObject → POST /v1/files/presign then fetches the URL and returns a Body", async () => {
+    // 1) presign POST → returns a URL; 2) the URL fetch → returns the bytes.
+    fetchSpy
+      .mockResolvedValueOnce(
+        json(200, { results: [{ key: "scratch/a.txt", op: "get", url: "https://s3.example/presigned" }] }),
+      )
+      .mockResolvedValueOnce(new Response("file-bytes-here", { status: 200 }));
+
+    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
+    const out = await client.send(
+      new GetObjectCommand({ Bucket: "ignored", Key: "scratch/a.txt" }),
+    );
+
+    // First call: POST presign with the right body.
+    const [presignUrl, presignInit] = fetchSpy.mock.calls[0];
+    expect(String(presignUrl)).toContain("/v1/files/presign");
+    expect(presignInit?.method).toBe("POST");
+    expect(JSON.parse(presignInit?.body as string)).toEqual({
+      company: "cmp_indigo",
+      key: "scratch/a.txt",
+      op: "get",
+    });
+    // Second call: fetch the presigned URL.
+    expect(String(fetchSpy.mock.calls[1][0])).toBe("https://s3.example/presigned");
+
+    // Body is a readable stream of the downloaded bytes.
+    const chunks: Buffer[] = [];
+    for await (const c of out.Body as unknown as AsyncIterable<Buffer>) {
+      chunks.push(Buffer.from(c));
+    }
+    expect(Buffer.concat(chunks).toString("utf-8")).toBe("file-bytes-here");
+  });
+
+  it("GetObject throws the per-key error when presign denies the key (no URL)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      json(200, {
+        results: [
+          { key: "secret/x", op: "get", error: "Caller lacks read permission on 'secret/x'", code: "FILES_PRESIGN_FORBIDDEN" },
+        ],
+      }),
+    );
+    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
+    await expect(
+      client.send(new GetObjectCommand({ Bucket: "b", Key: "secret/x" })),
+    ).rejects.toThrow(/lacks read permission/);
+    // The denial short-circuits BEFORE any download fetch.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("GetObject throws when the presigned download itself fails", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        json(200, { results: [{ key: "k", op: "get", url: "https://s3.example/x" }] }),
+      )
+      .mockResolvedValueOnce(new Response("nope", { status: 500 }));
+    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
+    await expect(
+      client.send(new GetObjectCommand({ Bucket: "b", Key: "k" })),
+    ).rejects.toThrow(/Failed to download 'k'/);
+  });
+});

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,
         });