@indigoai-us/hq-cloud 6.11.5 → 6.11.6

package/src/signals/internals.ts

@@ -1,15 +1,34 @@
 /**
  * Internal helpers shared between signals/list.ts and signals/get.ts.
  *
- * Independent S3 client factory hook (separate from sources/internals.ts)
- * so signals tests can swap their stub without disturbing sources tests.
- * Production code never calls the setter.
+ * Two transports back the read surface (see sources/internals.ts for the full
+ * rationale): the presigned-URL path (a vault client + a company vault, cmp_*)
+ * and the direct-S3 path (no vault client, or a personal vault prs_*). The
+ * direct-S3 path goes through `getS3Client`, whose factory hook is independent
+ * from sources/internals.ts so signals tests can swap their stub without
+ * disturbing sources tests.
  */
 
-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(
+      `Signals 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 +63,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/signals/list.test.ts

@@ -6,7 +6,7 @@
  * @aws-sdk/client-s3.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import {
   GetObjectCommand,
   ListObjectsV2Command,
@@ -17,6 +17,8 @@ import {
   _setSignalsS3Factory,
   _resetSignalsS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
+import type { VaultListedObject } from "../vault-client.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSignalTypeError, SIGNAL_TYPES } from "../schemas/signal-types.js";
 
@@ -281,3 +283,114 @@ describe("listSignals", () => {
     expect(observed.commands).toHaveLength(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+interface PresignVaultStub {
+  vault: PresignTransportClient;
+  listCalls: Array<{ prefix?: string; cursor?: string }>;
+}
+
+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-03-15T15:00:00.000Z",
+    etag: "etag",
+    permission: "read",
+  };
+}
+
+describe("listSignals — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("lists via the ACL-filtered vault endpoint and never touches S3", async () => {
+    _setSignalsS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const { vault, listCalls } = makePresignVault({
+      objects: [listed("signals/action_item/foo.md")],
+      cursor: null,
+    });
+
+    const res = await listSignals({
+      entity: ENTITY,
+      signalType: "action_item",
+      vault,
+    });
+
+    expect(res.entries.map((e) => e.signalId)).toEqual(["foo"]);
+    expect(res.entries[0].key).toBe("signals/action_item/foo.md");
+    expect(res.nextToken).toBeUndefined();
+    expect(listCalls[0].prefix).toBe("signals/action_item/");
+  });
+
+  it("surfaces the opaque vault cursor as nextToken", async () => {
+    const { vault } = makePresignVault({
+      objects: [listed("signals/action_item/foo.md")],
+      cursor: "OPAQUE_CURSOR",
+    });
+    const res = await listSignals({
+      entity: ENTITY,
+      signalType: "action_item",
+      vault,
+    });
+    expect(res.nextToken).toBe("OPAQUE_CURSOR");
+  });
+
+  it("includeFrontmatter surfaces sourceRef via a presigned GET", async () => {
+    const { vault } = makePresignVault(
+      { objects: [listed("signals/action_item/foo.md")], cursor: null },
+      { "signals/action_item/foo.md": ACTION_ITEM_MD },
+    );
+    const res = await listSignals({
+      entity: ENTITY,
+      signalType: "action_item",
+      includeFrontmatter: true,
+      vault,
+    });
+    expect(res.entries[0].sourceRef).toBe("abc-meeting-001");
+  });
+});

package/src/signals/list.ts

@@ -6,12 +6,8 @@
  * `includeFrontmatter: true` (otherwise the field is undefined).
  */
 
-import {
-  GetObjectCommand,
-  ListObjectsV2Command,
-} from "@aws-sdk/client-s3";
 import { assertSignalType } from "../schemas/signal-types.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { listObjects, readObjectText } from "./internals.js";
 import { parseFrontmatter } from "./parse.js";
 import type {
   ListSignalsOptions,
@@ -31,44 +27,35 @@ function deriveSignalId(key: string, prefix: string): string | null {
 }
 
 export async function listSignals(opts: ListSignalsOptions): Promise<ListSignalsResult> {
-  // Validate signalType BEFORE any S3 call (acceptance criterion + agent-mitigation).
+  // Validate signalType BEFORE any read (acceptance criterion + agent-mitigation).
   assertSignalType(opts.signalType);
 
-  const client = getS3Client(opts.entity);
   const prefix = `signals/${opts.signalType}/`;
 
-  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: SignalSummary[] = [];
-  for (const obj of response.Contents ?? []) {
-    if (!obj.Key) continue;
-    const signalId = deriveSignalId(obj.Key, prefix);
+  for (const obj of page.contents) {
+    const signalId = deriveSignalId(obj.key, prefix);
     if (!signalId) continue;
 
     const summary: SignalSummary = {
       signalId,
       signalType: opts.signalType,
-      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;
@@ -87,6 +74,6 @@ export async function listSignals(opts: ListSignalsOptions): Promise<ListSignals
 
   return {
     entries,
-    nextToken: response.IsTruncated ? response.NextContinuationToken : undefined,
+    nextToken: page.nextToken,
   };
 }

package/src/signals/types.ts

@@ -9,6 +9,7 @@
 
 import type { SignalType } from "../schemas/signal-types.js";
 import type { EntityContext } from "../types.js";
+import type { PresignTransportClient } from "../object-io.js";
 
 /**
  * Lightweight summary returned by listSignals(). `frontmatter` and
@@ -53,12 +54,23 @@ export interface SignalDocument {
 export interface ListSignalsOptions {
   entity: EntityContext;
   signalType: SignalType;
-  /** 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 ListSignalsResult {
@@ -71,4 +83,9 @@ export interface GetSignalOptions {
   entity: EntityContext;
   signalType: SignalType;
   signalId: string;
+  /**
+   * 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/sources/get.test.ts

@@ -2,13 +2,14 @@
  * Unit tests for sources/get.ts.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { GetObjectCommand, type S3Client } from "@aws-sdk/client-s3";
 import { getSource, SourceNotFoundError } from "./get.js";
 import {
   _setSourcesS3Factory,
   _resetSourcesS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSourceChannelError } from "../schemas/source-channels.js";
 
@@ -164,3 +165,105 @@ describe("getSource", () => {
     expect(doc.body).toBe("Just a body, no frontmatter.");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+/**
+ * A presign-capable vault stub + a `fetch` mock keyed by the presigned URL.
+ * presign() mints a URL that encodes the key; fetch() returns the object's
+ * bytes (404 when absent, so a missing key surfaces as SourceNotFoundError —
+ * matching the S3 NoSuchKey path).
+ */
+function makePresignVault(objects: Record<string, string>): PresignTransportClient {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const content = objects[key];
+      if (content === undefined) return new Response(null, { status: 404 });
+      return new Response(Buffer.from(content, "utf-8"), { status: 200 });
+    }),
+  );
+  return {
+    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 () => ({ objects: [], cursor: null, truncated: false }),
+  };
+}
+
+describe("getSource — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("reads via presign and never touches S3", async () => {
+    // S3 factory throws if used — proves the read went through presign.
+    _setSourcesS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const vault = makePresignVault({ "sources/meetings/abc.md": MEETING_MD });
+
+    const doc = await getSource({
+      entity: ENTITY,
+      channel: "meeting",
+      sourceId: "abc",
+      vault,
+    });
+
+    expect(doc.frontmatter).toEqual({
+      source_id: "abc",
+      source_type: "meeting",
+      title: "Q1 Planning",
+    });
+    expect(doc.body).toContain("Body text line 1.");
+  });
+
+  it("maps a presign 404 to SourceNotFoundError", async () => {
+    const vault = makePresignVault({});
+    await expect(
+      getSource({ entity: ENTITY, channel: "meeting", sourceId: "missing", vault }),
+    ).rejects.toBeInstanceOf(SourceNotFoundError);
+  });
+
+  it("includeRaw via presign reads the .raw.json sibling", async () => {
+    const vault = makePresignVault({
+      "sources/meetings/abc.md": MEETING_MD,
+      "sources/meetings/abc.raw.json": JSON.stringify(RAW_PAYLOAD),
+    });
+    const doc = await getSource({
+      entity: ENTITY,
+      channel: "meeting",
+      sourceId: "abc",
+      includeRaw: true,
+      vault,
+    });
+    expect(doc.raw).toEqual(RAW_PAYLOAD);
+  });
+
+  it("personal vault (prs_) ignores the vault client and stays on direct S3", async () => {
+    // S3 stub serves the doc; the presign fetch would 404 if (wrongly) used.
+    installStub({ "sources/meetings/abc.md": MEETING_MD });
+    const vault = makePresignVault({});
+    const personal: EntityContext = { ...ENTITY, uid: "prs_me" };
+
+    const doc = await getSource({
+      entity: personal,
+      channel: "meeting",
+      sourceId: "abc",
+      vault,
+    });
+
+    expect(doc.body).toContain("Body text line 1.");
+  });
+});

package/src/sources/get.ts

@@ -3,9 +3,8 @@
  * sibling) from an entity bucket and return parsed frontmatter + body.
  */
 
-import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { assertSourceChannel, sourcePathSegment } from "../schemas/source-channels.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { readObjectText, tryReadObjectText } from "./internals.js";
 import { parseMarkdown } from "./parse.js";
 import type { GetSourceOptions, SourceDocument } from "./types.js";
 
@@ -19,15 +18,18 @@ export class SourceNotFoundError extends Error {
 function isNoSuchKey(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const name = (err as { name?: unknown }).name;
-  // AWS SDK v3 throws either a `NoSuchKey` exception or a `NotFound` head error.
-  return name === "NoSuchKey" || name === "NoSuchKeyException";
+  // The transport normalizes a missing object to a `NoSuchKey`-named error on
+  // both the S3 and presigned paths (a presign 404 → NoSuchKey). `NotFound` is
+  // kept for defense in depth (S3 HEAD-style errors).
+  return (
+    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
+  );
 }
 
 export async function getSource(opts: GetSourceOptions): Promise<SourceDocument> {
-  // Validate channel BEFORE any S3 call (acceptance criterion).
+  // Validate channel BEFORE any read (acceptance criterion).
   assertSourceChannel(opts.channel);
 
-  const client = getS3Client(opts.entity);
   // sources-pipeline writes "meeting" channel to sources/meetings/...; other
   // channels pass through. See schemas/source-channels.ts:sourcePathSegment.
   const segment = sourcePathSegment(opts.channel);
@@ -35,13 +37,7 @@ export async function getSource(opts: GetSourceOptions): Promise<SourceDocument>
 
   let body: string;
   try {
-    const response = await client.send(
-      new GetObjectCommand({
-        Bucket: opts.entity.bucketName,
-        Key: key,
-      }),
-    );
-    body = await streamToString(response.Body);
+    body = await readObjectText(opts, key);
   } catch (err) {
     if (isNoSuchKey(err)) {
       throw new SourceNotFoundError(key);
@@ -58,19 +54,11 @@ export async function getSource(opts: GetSourceOptions): Promise<SourceDocument>
   };
 
   if (opts.includeRaw) {
+    // Raw sibling is optional; tryReadObjectText returns null when absent.
     const rawKey = `sources/${segment}/${opts.sourceId}.raw.json`;
-    try {
-      const rawResponse = await client.send(
-        new GetObjectCommand({
-          Bucket: opts.entity.bucketName,
-          Key: rawKey,
-        }),
-      );
-      const rawText = await streamToString(rawResponse.Body);
+    const rawText = await tryReadObjectText(opts, rawKey);
+    if (rawText !== null) {
       document.raw = JSON.parse(rawText);
-    } catch (err) {
-      if (!isNoSuchKey(err)) throw err;
-      // Raw sibling is optional; leave undefined when absent.
     }
   }