@indigoai-us/hq-cloud 6.11.5 → 6.11.6

package/src/sources/internals.ts

@@ -1,15 +1,37 @@
 /**
  * Internal helpers shared between sources/list.ts and sources/get.ts.
  *
- * The S3 client factory hook exists so tests can inject an in-memory stub
- * without standing up vi.mock for @aws-sdk/client-s3. Production code never
- * calls the setter.
+ * Two transports back the read surface:
+ *   - presigned-URL (HQ-59): when a vault client is supplied AND the entity is a
+ *     company vault (cmp_*), reads go through the vault `list`/`presign`
+ *     endpoints — the client never talks to S3 directly. This is the path every
+ *     company read should take going forward.
+ *   - direct S3 (legacy / personal): no vault client, or a personal vault
+ *     (prs_*, whose membership-less creds 403 the membership-gated presign
+ *     endpoints). Goes through `getS3Client`, whose factory hook lets tests
+ *     inject an in-memory stub without vi.mock.
  */
 
-import { S3Client } from "@aws-sdk/client-s3";
+import {
+  S3Client,
+  GetObjectCommand,
+  ListObjectsV2Command,
+} from "@aws-sdk/client-s3";
 import type { EntityContext } from "../types.js";
+import { PresignObjectIO, type PresignTransportClient } from "../object-io.js";
 
 function defaultFactory(ctx: EntityContext): S3Client {
+  if (!ctx.credentials) {
+    // The direct-S3 read path needs STS creds. A credential-less context only
+    // exists on the presign path (HQ-59 company vend-skip), which reads via the
+    // vault list/presign endpoints, not this S3 client — so arriving here with
+    // no creds is a routing bug. Fail loudly rather than 403 opaquely later.
+    throw new Error(
+      `Sources S3 read for ${ctx.uid} requires STS credentials but got a ` +
+        `presign-only context; company presign reads must go through the ` +
+        `vault transport, not getS3Client.`,
+    );
+  }
   return new S3Client({
     region: ctx.region,
     credentials: {
@@ -44,3 +66,133 @@ export async function streamToString(body: unknown): Promise<string> {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
+
+// ---------------------------------------------------------------------------
+// Transport seam (presign for cmp_, direct-S3 otherwise)
+// ---------------------------------------------------------------------------
+
+/** Common shape of every reader's options: an entity + an optional vault client. */
+export interface ReaderTransportOpts {
+  entity: EntityContext;
+  /**
+   * Presign-capable vault client. When supplied and the entity is a company
+   * vault (cmp_*), reads use the presigned-URL transport instead of direct S3.
+   */
+  vault?: PresignTransportClient;
+}
+
+/** Lightweight listed object (transport-agnostic). */
+export interface ListedKey {
+  key: string;
+  size: number;
+  lastModified: Date;
+}
+
+/** True when this read should use the presigned-URL transport. */
+export function usePresign(opts: ReaderTransportOpts): boolean {
+  return opts.vault != null && opts.entity.uid.startsWith("cmp_");
+}
+
+/** A not-found error normalized to the S3 `NoSuchKey` shape callers test for. */
+function noSuchKeyError(key: string): Error {
+  return Object.assign(new Error(`No such key: ${key}`), { name: "NoSuchKey" });
+}
+
+function isNotFound(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return (
+    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
+  );
+}
+
+/**
+ * Read an object's UTF-8 text. Throws a `NoSuchKey`-named error when the object
+ * is absent (both transports), so callers' existing not-found checks work
+ * unchanged.
+ */
+export async function readObjectText(
+  opts: ReaderTransportOpts,
+  key: string,
+): Promise<string> {
+  if (usePresign(opts)) {
+    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
+    try {
+      const { body } = await io.getObject(key);
+      return body.toString("utf-8");
+    } catch (err) {
+      if (isNotFound(err)) throw noSuchKeyError(key);
+      throw err;
+    }
+  }
+  const client = getS3Client(opts.entity);
+  const res = await client.send(
+    new GetObjectCommand({ Bucket: opts.entity.bucketName, Key: key }),
+  );
+  return streamToString(res.Body);
+}
+
+/** Like {@link readObjectText} but returns null when the object is absent. */
+export async function tryReadObjectText(
+  opts: ReaderTransportOpts,
+  key: string,
+): Promise<string | null> {
+  try {
+    return await readObjectText(opts, key);
+  } catch (err) {
+    if (isNotFound(err)) return null;
+    throw err;
+  }
+}
+
+/**
+ * List one page of objects under `prefix`.
+ *
+ * Under the presigned transport the vault `list` endpoint is ACL-filtered and
+ * controls page size server-side, so `limit` is advisory — paginate via the
+ * returned `nextToken` (the opaque vault cursor) until it is undefined. Under
+ * direct S3, `limit` maps to `MaxKeys`.
+ */
+export async function listObjects(
+  opts: ReaderTransportOpts,
+  prefix: string,
+  page: { limit?: number; continuationToken?: string },
+): Promise<{ contents: ListedKey[]; nextToken?: string }> {
+  if (usePresign(opts)) {
+    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
+    const res = await io.listObjects({
+      prefix,
+      continuationToken: page.continuationToken,
+    });
+    return {
+      contents: res.objects.map((o) => ({
+        key: o.key,
+        size: o.size,
+        lastModified: o.lastModified,
+      })),
+      nextToken: res.nextContinuationToken,
+    };
+  }
+  const client = getS3Client(opts.entity);
+  const res = await client.send(
+    new ListObjectsV2Command({
+      Bucket: opts.entity.bucketName,
+      Prefix: prefix,
+      MaxKeys: page.limit,
+      ContinuationToken: page.continuationToken,
+    }),
+  );
+  const contents: ListedKey[] = [];
+  for (const obj of res.Contents ?? []) {
+    if (!obj.Key) continue;
+    contents.push({
+      key: obj.Key,
+      size: obj.Size ?? 0,
+      lastModified: obj.LastModified ?? new Date(0),
+    });
+  }
+  return {
+    contents,
+    nextToken: res.IsTruncated ? res.NextContinuationToken : undefined,
+  };
+}

package/src/sources/list.test.ts

@@ -5,7 +5,7 @@
  * hook so we don't have to stand up vi.mock for @aws-sdk/client-s3.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import {
   GetObjectCommand,
   ListObjectsV2Command,
@@ -16,6 +16,8 @@ import {
   _setSourcesS3Factory,
   _resetSourcesS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
+import type { VaultListedObject } from "../vault-client.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSourceChannelError } from "../schemas/source-channels.js";
 
@@ -245,3 +247,132 @@ describe("listSources", () => {
     expect(observed.commands).toHaveLength(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+interface PresignVaultStub {
+  vault: PresignTransportClient;
+  listCalls: Array<{ prefix?: string; cursor?: string }>;
+}
+
+/**
+ * Vault stub for the list path: `listFiles` returns the configured ACL-filtered
+ * page (the server is the ACL boundary — only readable keys come back) + an
+ * opaque cursor; `presign`+fetch serve per-entry frontmatter GETs.
+ */
+function makePresignVault(
+  page: { objects: VaultListedObject[]; cursor: string | null },
+  contents: Record<string, string> = {},
+): PresignVaultStub {
+  const listCalls: Array<{ prefix?: string; cursor?: string }> = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const c = contents[key];
+      if (c === undefined) return new Response(null, { status: 404 });
+      return new Response(Buffer.from(c, "utf-8"), { status: 200 });
+    }),
+  );
+  const vault: PresignTransportClient = {
+    presign: async (input) => ({
+      results: input.keys.map((k) => ({
+        key: k.key,
+        op: k.op ?? input.op ?? "get",
+        url: `https://signed.example/?key=${encodeURIComponent(k.key)}`,
+      })),
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    }),
+    listFiles: async (_company, prefix, cursor) => {
+      listCalls.push({ prefix, cursor });
+      return {
+        objects: page.objects,
+        cursor: page.cursor,
+        truncated: page.cursor != null,
+      };
+    },
+  };
+  return { vault, listCalls };
+}
+
+function listed(key: string): VaultListedObject {
+  return {
+    key,
+    size: 10,
+    lastModified: "2026-02-01T00:00:00.000Z",
+    etag: "etag",
+    permission: "read",
+  };
+}
+
+describe("listSources — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("lists via the ACL-filtered vault endpoint and never touches S3", async () => {
+    _setSourcesS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const { vault, listCalls } = makePresignVault({
+      objects: [listed("sources/meetings/a.md"), listed("sources/meetings/a.raw.json")],
+      cursor: null,
+    });
+
+    const res = await listSources({ entity: ENTITY, channel: "meeting", vault });
+
+    // .raw.json sibling is skipped; only the .md entry surfaces.
+    expect(res.entries.map((e) => e.sourceId)).toEqual(["a"]);
+    expect(res.entries[0].key).toBe("sources/meetings/a.md");
+    expect(res.nextToken).toBeUndefined();
+    // listFiles was called with the channel prefix (ACL filtering is server-side).
+    expect(listCalls[0].prefix).toBe("sources/meetings/");
+  });
+
+  it("surfaces the opaque vault cursor as nextToken (advisory limit)", async () => {
+    const { vault } = makePresignVault({
+      objects: [listed("sources/meetings/a.md")],
+      cursor: "OPAQUE_CURSOR",
+    });
+    const res = await listSources({
+      entity: ENTITY,
+      channel: "meeting",
+      limit: 1,
+      vault,
+    });
+    expect(res.nextToken).toBe("OPAQUE_CURSOR");
+  });
+
+  it("includeFrontmatter parses each entry via a presigned GET", async () => {
+    const { vault } = makePresignVault(
+      { objects: [listed("sources/meetings/a.md")], cursor: null },
+      { "sources/meetings/a.md": MEETING_MD },
+    );
+    const res = await listSources({
+      entity: ENTITY,
+      channel: "meeting",
+      includeFrontmatter: true,
+      vault,
+    });
+    expect(res.entries[0].frontmatter).toMatchObject({ title: "Hello" });
+  });
+
+  it("forwards the continuationToken as the vault cursor", async () => {
+    const { vault, listCalls } = makePresignVault({
+      objects: [],
+      cursor: null,
+    });
+    await listSources({
+      entity: ENTITY,
+      channel: "meeting",
+      continuationToken: "RESUME_HERE",
+      vault,
+    });
+    expect(listCalls[0].cursor).toBe("RESUME_HERE");
+  });
+});

package/src/sources/list.ts

@@ -6,12 +6,8 @@
  * the summary (callers fetch them via getSource({ includeRaw: true })).
  */
 
-import {
-  GetObjectCommand,
-  ListObjectsV2Command,
-} from "@aws-sdk/client-s3";
 import { assertSourceChannel, sourcePathSegment } from "../schemas/source-channels.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { listObjects, readObjectText } from "./internals.js";
 import { parseFrontmatter } from "./parse.js";
 import type {
   ListSourcesOptions,
@@ -40,46 +36,37 @@ function deriveSourceId(
 }
 
 export async function listSources(opts: ListSourcesOptions): Promise<ListSourcesResult> {
-  // Validate channel BEFORE any S3 call (acceptance criterion).
+  // Validate channel BEFORE any read (acceptance criterion).
   assertSourceChannel(opts.channel);
 
-  const client = getS3Client(opts.entity);
   // Use the canonical path segment from the schema; channel "meeting" maps
   // to the plural "meetings/" prefix the sources-pipeline writes to.
   const prefix = `sources/${sourcePathSegment(opts.channel)}/`;
 
-  const response = await client.send(
-    new ListObjectsV2Command({
-      Bucket: opts.entity.bucketName,
-      Prefix: prefix,
-      MaxKeys: opts.limit,
-      ContinuationToken: opts.continuationToken,
-    }),
-  );
+  // Presign transport ACL-filters server-side and controls page size, so
+  // `limit` is advisory there; under direct S3 it maps to MaxKeys. Paginate via
+  // the returned nextToken regardless of transport.
+  const page = await listObjects(opts, prefix, {
+    limit: opts.limit,
+    continuationToken: opts.continuationToken,
+  });
 
   const entries: SourceSummary[] = [];
-  for (const obj of response.Contents ?? []) {
-    if (!obj.Key) continue;
-    const derived = deriveSourceId(obj.Key, prefix);
+  for (const obj of page.contents) {
+    const derived = deriveSourceId(obj.key, prefix);
     if (!derived || derived.isRawSibling) continue;
 
     const summary: SourceSummary = {
       sourceId: derived.sourceId,
       channel: opts.channel,
-      key: obj.Key,
-      lastModified: obj.LastModified ?? new Date(0),
-      size: obj.Size ?? 0,
+      key: obj.key,
+      lastModified: obj.lastModified,
+      size: obj.size,
     };
 
     if (opts.includeFrontmatter) {
       try {
-        const get = await client.send(
-          new GetObjectCommand({
-            Bucket: opts.entity.bucketName,
-            Key: obj.Key,
-          }),
-        );
-        const text = await streamToString(get.Body);
+        const text = await readObjectText(opts, obj.key);
         const fm = parseFrontmatter(text);
         if (fm) summary.frontmatter = fm;
       } catch {
@@ -92,6 +79,6 @@ export async function listSources(opts: ListSourcesOptions): Promise<ListSources
 
   return {
     entries,
-    nextToken: response.IsTruncated ? response.NextContinuationToken : undefined,
+    nextToken: page.nextToken,
   };
 }

package/src/sources/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { SourceChannel } from "../schemas/source-channels.js";
+import type { PresignTransportClient } from "../object-io.js";
 
 /**
  * Lightweight summary returned by listSources(). `frontmatter` is only
@@ -44,12 +45,23 @@ export interface SourceDocument {
 export interface ListSourcesOptions {
   entity: import("../types.js").EntityContext;
   channel: SourceChannel;
-  /** Max keys per page; defaults to S3 default (1000). */
+  /**
+   * Max keys per page. Under direct S3 this maps to `MaxKeys`; under the
+   * presigned transport ({@link vault} + a company vault) it is advisory — the
+   * vault `list` endpoint controls page size server-side. Defaults to the S3
+   * default (1000) on the direct path.
+   */
   limit?: number;
   /** Opaque continuation token returned by a prior page. */
   continuationToken?: string;
   /** When true, fetches+parses each entry's frontmatter (extra GETs). */
   includeFrontmatter?: boolean;
+  /**
+   * Presign-capable vault client. When supplied and {@link entity} is a company
+   * vault (cmp_*), reads use the presigned-URL transport (ACL-filtered, no
+   * direct S3). Personal vaults and the absent-client path stay on direct S3.
+   */
+  vault?: PresignTransportClient;
 }
 
 export interface ListSourcesResult {
@@ -64,4 +76,9 @@ export interface GetSourceOptions {
   sourceId: string;
   /** When true, also fetches the `.raw.json` sibling. */
   includeRaw?: boolean;
+  /**
+   * Presign-capable vault client. When supplied and {@link entity} is a company
+   * vault (cmp_*), reads use the presigned-URL transport (no direct S3).
+   */
+  vault?: PresignTransportClient;
 }

package/src/sync/event-sync.ts

@@ -7,9 +7,8 @@
  * runner's receiver seam defaults to {@link NoopPushReceiver}. This module is
  * the connective tissue that turns both on for enrolled accounts:
  *
- *  - {@link resolveEventSync} — the rollout gate. EXACT-email allowlist
- *    (mirrors `resolvePresignTransport`'s shape in sync-runner.ts, but full
- *    address, not domain suffix) + `HQ_SYNC_EVENT_SYNC` env override in both
+ *  - {@link resolveEventSync} — the rollout gate. EXACT-email allowlist (full
+ *    address, not a domain suffix) + `HQ_SYNC_EVENT_SYNC` env override in both
  *    directions. ONE gate governs publish AND receive so a device is never
  *    publish-only or receive-only in a half-rolled state.
  *  - {@link subscribeSyncReceive} — `POST /v1/sync/subscribe` (US-015/US-016):
@@ -58,8 +57,8 @@ import type { TreeChangeBatch } from "../watcher.js";
  * single-account Phase 3 rollout (2026-06-10) targets the operator's own
  * devices; `xhassaan@getindigo.ai` and `hassaan@getindigo.ai.evil.com` must
  * never match. Broadening later is an entry here, then a domain set, then a
- * GA default-on switch (the path the presigned-URL transport already took in
- * `resolvePresignTransport`).
+ * GA default-on switch (the same rollout path the presigned-URL sync transport
+ * already took to GA).
  */
 export const EVENT_SYNC_ROLLOUT_EMAILS: ReadonlySet<string> = new Set([
   "hassaan@getindigo.ai",
@@ -68,8 +67,8 @@ export const EVENT_SYNC_ROLLOUT_EMAILS: ReadonlySet<string> = new Set([
 /**
  * Decide whether this session runs event-driven sync (publish + receive).
  *
- * Mirrors `resolvePresignTransport` precedence: `HQ_SYNC_EVENT_SYNC`
- * overrides in both directions (`1`/`true`/`yes`/`on` → force on,
+ * Env-override-in-both-directions precedence: `HQ_SYNC_EVENT_SYNC`
+ * overrides (`1`/`true`/`yes`/`on` → force on,
  * `0`/`false`/`no`/`off` → force off) so unenrolled testers can exercise it
  * and enrolled accounts can be rolled back without a release. An unset/blank
  * override falls through to the exact-email check; an unrecognized override

package/src/types.ts

@@ -155,9 +155,26 @@ export interface EntityContext {
   bucketName: string;
   /** AWS region */
   region: string;
-  /** STS-scoped credentials */
-  credentials: VaultCredentials;
-  /** When the credentials expire (ISO 8601) */
+  /**
+   * STS-scoped credentials.
+   *
+   * Absent for presign-only COMPANY contexts (HQ-59): when a run uses the
+   * presigned-URL transport for company vaults (`companyVaultUsesPresign`),
+   * `resolveEntityContext` skips the `POST /sts/vend` call entirely — the
+   * presign transport authorizes each object server-side and never reads these
+   * creds, and a compliant sync-runner must NOT hit the company vend route
+   * (the route-presence signal the hq-pro min-version gate keys on). The only
+   * reader of these creds is the direct-S3 (`S3SdkObjectIO`) path, which is
+   * used for personal vaults (`prs_*`, still vended) and pre-presign clients —
+   * never for a `cmp_*` context built on the presign path. That path throws
+   * loudly if it ever receives a credential-less context.
+   */
+  credentials?: VaultCredentials;
+  /**
+   * When the credentials expire (ISO 8601). For a presign-only company context
+   * (no STS vend) this is a far-future sentinel so `isExpiringSoon` is always
+   * false and no auto-refresh ever re-vends the skipped company route.
+   */
   expiresAt: string;
 }
 
@@ -209,6 +226,19 @@ export interface VaultServiceConfig {
    * Optional for back-compat, but all first-party clients should pass it.
    */
   clientInfo?: ClientInfo;
+  /**
+   * When true, COMPANY vaults (`cmp_*`) use the presigned-URL transport, so
+   * `resolveEntityContext` SKIPS `POST /sts/vend` for them and returns a
+   * credential-less context with a far-future `expiresAt` (HQ-59). Set by the
+   * sync-runner exactly when it installs the presign transport factory, so the
+   * vend-skip and the transport choice can never diverge. Personal vaults
+   * (`prs_*`) are unaffected — they always vend self via `/sts/vend-self`.
+   *
+   * Leaving this unset (the default) preserves the historical behavior: every
+   * context vends STS creds. Non-runner callers (standalone `hq sync`, hq-cli)
+   * that keep the direct-S3 path for company vaults must NOT set this.
+   */
+  companyVaultUsesPresign?: boolean;
 }
 
 // ── Conflict index (consumed by /resolve-conflicts) ─────────────────────────

package/src/version.ts

@@ -0,0 +1,24 @@
+/**
+ * The hq-cloud package version, read once at module load.
+ *
+ * Mirrors hq-cli's `cli-version.ts` pattern: resolve the version from the
+ * package.json at runtime via `import.meta.url` (rootDir-safe — no JSON import
+ * that would trip `tsc`'s rootDir, and resolves correctly from both `src/`
+ * during tests and `dist/` at runtime). Used to stamp `clientInfo.version` on
+ * the sync-runner's vault requests so the company-vend min-version gate (HQ-59,
+ * hq-pro) can tell a compliant (>= 6.11.6) sync-runner from a pre-6.11.6
+ * straggler. This is the hq-cloud package version — the version the gate
+ * compares against its floor — NOT the hq-sync desktop app version.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+// src/version.ts → dist/version.js; one level up from either is the package root.
+const pkg = JSON.parse(
+  readFileSync(path.resolve(here, "..", "package.json"), "utf-8"),
+) as { name: string; version: string };
+
+export const HQ_CLOUD_VERSION: string = pkg.version;