@openchambery/web 1.19.12 → 1.19.13-beta.2

package/server/lib/fs/prompt-attachment-store.test.js

@@ -0,0 +1,263 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  assertImageContentMatchesMime,
+  decodeDataUrlStrict,
+  relativeObjectPath,
+  storePromptAttachmentBytes,
+  readPromptAttachmentBytes,
+  promptAttachmentsRoot,
+} from './prompt-attachment-store.js';
+
+const png = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+  0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+  0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
+  0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53,
+  0xde, 0x00, 0x00, 0x00, 0x0c, 0x49, 0x44, 0x41,
+  0x54, 0x08, 0xd7, 0x63, 0xf8, 0xcf, 0xc0, 0x00,
+  0x00, 0x00, 0x03, 0x00, 0x01, 0x00, 0x05, 0xfe,
+  0xd4, 0xef, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45,
+  0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+]);
+
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex');
+
+const makeDataDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'pas-'));
+
+describe('prompt-attachment-store', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('stores content-addressed bytes and rejects path traversal relative paths', async () => {
+    const dataDir = makeDataDir();
+    const digest = sha256(png);
+    const stored = await storePromptAttachmentBytes({
+      dataDir,
+      buffer: png,
+      expectedSha256: digest,
+      mime: 'image/png',
+      filename: 'x.png',
+    });
+    expect(stored.relativePath).toBe(relativeObjectPath(digest, 'image/png'));
+    expect(stored.sha256).toBe(digest);
+    const again = await storePromptAttachmentBytes({
+      dataDir,
+      buffer: png,
+      expectedSha256: digest,
+      mime: 'image/png',
+      filename: 'x.png',
+    });
+    expect(again.absolutePath).toBe(stored.absolutePath);
+    const read = await readPromptAttachmentBytes(dataDir, stored.relativePath);
+    expect(read.buffer.equals(png)).toBe(true);
+    await expect(readPromptAttachmentBytes(dataDir, '../etc/passwd')).rejects.toMatchObject({
+      code: 'attachment_unsafe_path',
+    });
+    await fsp.rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('rejects image mime/signature mismatch', () => {
+    expect(() => assertImageContentMatchesMime(Buffer.from('not-an-image'), 'image/png')).toThrowError(
+      expect.objectContaining({ code: 'attachment_mime_mismatch' }),
+    );
+    expect(() => assertImageContentMatchesMime(png, 'image/png')).not.toThrow();
+  });
+
+  describe('decodeDataUrlStrict', () => {
+    it('preserves literal plus in non-base64 data URLs (not form-urlencoded spaces)', () => {
+      const decoded = decodeDataUrlStrict('data:text/plain,a+b');
+      expect(decoded.buffer.toString('utf8')).toBe('a+b');
+      expect(decoded.mime).toBe('text/plain');
+    });
+
+    it('percent-decodes %2B to plus and rejects malformed percent sequences', () => {
+      expect(decodeDataUrlStrict('data:text/plain,a%2Bb').buffer.toString('utf8')).toBe('a+b');
+      expect(() => decodeDataUrlStrict('data:text/plain,a%zz')).toThrowError(
+        expect.objectContaining({ code: 'validation_error' }),
+      );
+      expect(() => decodeDataUrlStrict('data:text/plain,a%2')).toThrowError(
+        expect.objectContaining({ code: 'validation_error' }),
+      );
+    });
+
+    it('rejects invalid base64 alphabet and broken padding', () => {
+      expect(() => decodeDataUrlStrict('data:text/plain;base64,!!!')).toThrowError(
+        expect.objectContaining({ code: 'validation_error' }),
+      );
+      expect(() => decodeDataUrlStrict('data:text/plain;base64,YWJ')).toThrowError(
+        expect.objectContaining({ code: 'validation_error' }),
+      );
+      expect(() => decodeDataUrlStrict('data:text/plain;base64,YWJj====')).toThrowError(
+        expect.objectContaining({ code: 'validation_error' }),
+      );
+    });
+
+    it('allows html and svg data URLs for ordinary chat source uploads', () => {
+      const html = decodeDataUrlStrict('data:text/html,<h1>x</h1>');
+      expect(html.buffer.toString('utf8')).toBe('<h1>x</h1>');
+      expect(html.mime).toBe('text/html');
+      const svg = decodeDataUrlStrict('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg"></svg>');
+      expect(svg.mime).toBe('image/svg+xml');
+      expect(svg.buffer.toString('utf8')).toContain('<svg');
+    });
+  });
+
+  it('allows HTML and SVG file storage (display safety is not this module)', async () => {
+    const dataDir = makeDataDir();
+    const html = Buffer.from('<!doctype html><title>t</title>', 'utf8');
+    const svg = Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>', 'utf8');
+    const htmlStored = await storePromptAttachmentBytes({
+      dataDir,
+      buffer: html,
+      mime: 'text/html',
+      validateImage: false,
+    });
+    const svgStored = await storePromptAttachmentBytes({
+      dataDir,
+      buffer: svg,
+      mime: 'image/svg+xml',
+      validateImage: false,
+    });
+    expect(htmlStored.sha256).toBe(sha256(html));
+    expect(svgStored.sha256).toBe(sha256(svg));
+    const htmlRead = await readPromptAttachmentBytes(dataDir, htmlStored.relativePath);
+    const svgRead = await readPromptAttachmentBytes(dataDir, svgStored.relativePath);
+    expect(htmlRead.buffer.equals(html)).toBe(true);
+    expect(svgRead.buffer.equals(svg)).toBe(true);
+    await fsp.rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('completes short writes instead of leaving truncated objects', async () => {
+    const dataDir = makeDataDir();
+    const body = Buffer.from('0123456789abcdefghijklmnopqrstuvwxyz', 'utf8');
+    const digest = sha256(body);
+    const openOrig = fsp.open.bind(fsp);
+    let shortWrote = false;
+    vi.spyOn(fsp, 'open').mockImplementation(async (filePath, flags, mode) => {
+      const handle = await openOrig(filePath, flags, mode);
+      if (typeof filePath === 'string' && filePath.includes('.tmp-')) {
+        const writeOrig = handle.write.bind(handle);
+        handle.write = async (buffer, offset = 0, length = buffer.length - offset, position = null) => {
+          if (!shortWrote && length > 1) {
+            shortWrote = true;
+            return writeOrig(buffer, offset, 1, position);
+          }
+          return writeOrig(buffer, offset, length, position);
+        };
+      }
+      return handle;
+    });
+
+    const stored = await storePromptAttachmentBytes({
+      dataDir,
+      buffer: body,
+      expectedSha256: digest,
+      mime: 'text/plain',
+      validateImage: false,
+    });
+    expect(shortWrote).toBe(true);
+    expect(stored.size).toBe(body.length);
+    const onDisk = await fsp.readFile(stored.absolutePath);
+    expect(onDisk.equals(body)).toBe(true);
+    expect(sha256(onDisk)).toBe(digest);
+    await fsp.rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('rejects store-root and hash-prefix symlink escape (NOFOLLOW alone is not enough)', async () => {
+    const base = makeDataDir();
+    const dataDir = path.join(base, 'data');
+    const outside = path.join(base, 'outside-secret');
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(outside, 'secret-leak');
+
+    const digest = sha256(png);
+    const prefix = digest.slice(0, 2);
+    const storeRoot = promptAttachmentsRoot(dataDir);
+    fs.mkdirSync(storeRoot, { recursive: true });
+    const prefixPath = path.join(storeRoot, prefix);
+    try {
+      fs.symlinkSync(path.dirname(outside), prefixPath);
+    } catch {
+      await fsp.rm(base, { recursive: true, force: true });
+      return;
+    }
+
+    await expect(storePromptAttachmentBytes({
+      dataDir,
+      buffer: png,
+      expectedSha256: digest,
+      mime: 'image/png',
+      validateImage: true,
+    })).rejects.toMatchObject({ code: 'attachment_unsafe_path' });
+
+    // Must not have written the object through the escaped prefix.
+    const escapedCandidate = path.join(path.dirname(outside), `${digest}.png`);
+    expect(fs.existsSync(escapedCandidate)).toBe(false);
+
+    await expect(readPromptAttachmentBytes(
+      dataDir,
+      relativeObjectPath(digest, 'image/png'),
+    )).rejects.toMatchObject({
+      code: expect.stringMatching(/attachment_unsafe_path|attachment_not_found/),
+    });
+
+    await fsp.rm(base, { recursive: true, force: true });
+  });
+
+  it('rejects corrupt existing object whose bytes do not match addressing hash', async () => {
+    const dataDir = makeDataDir();
+    const digest = sha256(png);
+    const relativePath = relativeObjectPath(digest, 'image/png');
+    const storeRoot = promptAttachmentsRoot(dataDir);
+    const absolutePath = path.join(storeRoot, relativePath);
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+    fs.writeFileSync(absolutePath, Buffer.from('not-the-png-bytes'));
+
+    await expect(storePromptAttachmentBytes({
+      dataDir,
+      buffer: png,
+      expectedSha256: digest,
+      mime: 'image/png',
+      validateImage: true,
+    })).rejects.toMatchObject({ code: 'attachment_hash_mismatch' });
+
+    await fsp.rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('rejects read when on-disk bytes diverge from path addressing hash or expected hash/size', async () => {
+    const dataDir = makeDataDir();
+    const digest = sha256(png);
+    const relativePath = relativeObjectPath(digest, 'image/png');
+    const storeRoot = promptAttachmentsRoot(dataDir);
+    const absolutePath = path.join(storeRoot, relativePath);
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+    fs.writeFileSync(absolutePath, Buffer.from('corrupt-payload'));
+
+    await expect(readPromptAttachmentBytes(dataDir, relativePath)).rejects.toMatchObject({
+      code: 'attachment_hash_mismatch',
+    });
+
+    // Plant correct bytes then fail optional caller expectations.
+    fs.writeFileSync(absolutePath, png);
+    await expect(readPromptAttachmentBytes(dataDir, relativePath, {
+      expectedSha256: 'a'.repeat(64),
+    })).rejects.toMatchObject({ code: 'attachment_hash_mismatch' });
+    await expect(readPromptAttachmentBytes(dataDir, relativePath, {
+      expectedSize: png.length + 1,
+    })).rejects.toMatchObject({ code: 'PROMPT_ATTACHMENT_SIZE_MISMATCH' });
+
+    const ok = await readPromptAttachmentBytes(dataDir, relativePath, {
+      expectedSha256: digest,
+      expectedSize: png.length,
+    });
+    expect(ok.buffer.equals(png)).toBe(true);
+
+    await fsp.rm(dataDir, { recursive: true, force: true });
+  });
+});

package/server/lib/fs/routes.js

@@ -2,6 +2,15 @@ import { createHash } from 'node:crypto';
 import { createRealpathCache } from '../path-realpath-cache.js';
 import nodeFsPromises from 'node:fs/promises';
 import nodePath from 'node:path';
+import {
+  MAX_PROMPT_ATTACHMENT_BYTES,
+  PROMPT_ATTACHMENT_ID,
+  PROMPT_ATTACHMENT_MIME,
+  PROMPT_ATTACHMENT_SHA256,
+  collectRequestBytes,
+  promptAttachmentExtension,
+  storePromptAttachmentBytes,
+} from './prompt-attachment-store.js';
 
 const EXEC_JOB_TTL_MS = 30 * 60 * 1000;
 const OUTSIDE_FILE_GRANT_TTL_MS = 10 * 60 * 1000;
@@ -363,58 +372,11 @@ const runCommandInDirectory = ({ shell, shellFlag, command, resolvedCwd, spawn,
   });
 };
 
-const MAX_PROMPT_ATTACHMENT_BYTES = 25 * 1024 * 1024;
-const PROMPT_ATTACHMENT_ID = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
-const PROMPT_ATTACHMENT_SHA256 = /^[a-f0-9]{64}$/;
-const PROMPT_ATTACHMENT_MIME = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
-
 const headerValue = (value) => {
   if (Array.isArray(value)) return value[0];
   return typeof value === 'string' ? value : undefined;
 };
 
-const promptAttachmentExtension = (mime, filename) => {
-  const fromName = typeof filename === 'string' ? nodePath.posix.extname(filename).toLowerCase() : '';
-  if (fromName && fromName.length <= 16 && /^\.[a-z0-9.]+$/i.test(fromName)) return fromName;
-  const lowerMime = typeof mime === 'string' ? mime.toLowerCase() : '';
-  if (lowerMime === 'image/jpeg') return '.jpg';
-  if (lowerMime === 'image/png') return '.png';
-  if (lowerMime === 'image/gif') return '.gif';
-  if (lowerMime === 'image/webp') return '.webp';
-  if (lowerMime === 'image/heic') return '.heic';
-  if (lowerMime === 'image/heif') return '.heif';
-  if (lowerMime === 'image/avif') return '.avif';
-  if (lowerMime === 'image/bmp') return '.bmp';
-  if (lowerMime === 'image/svg+xml') return '.svg';
-  return '.bin';
-};
-
-const collectRequestBytes = async (req, { expectedSize, maxBytes, signal } = {}) => {
-  const chunks = [];
-  let size = 0;
-  for await (const chunk of req) {
-    if (signal?.aborted) {
-      const error = new Error('Upload aborted');
-      error.code = 'PROMPT_ATTACHMENT_ABORTED';
-      throw error;
-    }
-    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += bytes.byteLength;
-    if (size > maxBytes) {
-      const error = new Error('Attachment too large');
-      error.code = 'PROMPT_ATTACHMENT_TOO_LARGE';
-      throw error;
-    }
-    chunks.push(bytes);
-  }
-  if (expectedSize !== undefined && size !== expectedSize) {
-    const error = new Error('Attachment size mismatch');
-    error.code = 'PROMPT_ATTACHMENT_SIZE_MISMATCH';
-    throw error;
-  }
-  return { buffer: Buffer.concat(chunks, size), size };
-};
-
 export const registerFsRoutes = (app, dependencies) => {
   const {
     os,
@@ -1109,38 +1071,29 @@ export const registerFsRoutes = (app, dependencies) => {
     const controller = new AbortController();
     req.once?.('aborted', () => controller.abort());
 
-    let tmpPath;
     try {
       const { buffer, size } = await collectRequestBytes(req, {
         expectedSize,
         maxBytes: MAX_PROMPT_ATTACHMENT_BYTES,
         signal: controller.signal,
       });
-      const digest = createHash('sha256').update(buffer).digest('hex');
-      if (digest !== expectedSha256) {
-        return res.status(400).json({ error: 'Attachment digest mismatch' });
-      }
-
-      const storeRoot = path.resolve(dataDir, 'prompt-attachments');
-      const destinationDir = path.join(storeRoot, digest.slice(0, 2));
-      const destination = path.join(destinationDir, `${digest}${promptAttachmentExtension(mimeType, filename)}`);
-      await fsPromises.mkdir(destinationDir, { recursive: true, mode: 0o700 });
-      tmpPath = `${destination}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-      await fsPromises.writeFile(tmpPath, buffer, { mode: 0o600 });
-      try {
-        await fsPromises.rename(tmpPath, destination);
-      } catch (error) {
-        if (error && typeof error === 'object' && (error.code === 'EEXIST' || error.code === 'ENOTEMPTY')) {
-          await fsPromises.unlink(tmpPath).catch(() => {});
-          tmpPath = undefined;
-        } else {
-          throw error;
-        }
-      }
-      tmpPath = undefined;
-      return res.json({ success: true, path: destination, size, mime: mimeType, sha256: digest });
+      const stored = await storePromptAttachmentBytes({
+        dataDir,
+        buffer,
+        expectedSha256,
+        mime: mimeType,
+        filename,
+        maxBytes: MAX_PROMPT_ATTACHMENT_BYTES,
+        validateImage: false,
+      });
+      return res.json({
+        success: true,
+        path: stored.absolutePath,
+        size: stored.size,
+        mime: stored.mime,
+        sha256: stored.sha256,
+      });
     } catch (error) {
-      if (tmpPath) await fsPromises.unlink(tmpPath).catch(() => {});
       const code = error && typeof error === 'object' ? error.code : undefined;
       if (code === 'PROMPT_ATTACHMENT_TOO_LARGE') {
         return res.status(413).json({ error: 'Attachment too large' });
@@ -1151,6 +1104,9 @@ export const registerFsRoutes = (app, dependencies) => {
       if (code === 'PROMPT_ATTACHMENT_ABORTED') {
         return res.status(499).json({ error: 'Upload aborted' });
       }
+      if (code === 'attachment_hash_mismatch') {
+        return res.status(400).json({ error: 'Attachment digest mismatch' });
+      }
       console.error('Failed to store prompt attachment:', error);
       return res.status(500).json({ error: 'Failed to store prompt attachment' });
     }

package/server/lib/fs/routes.test.js

@@ -1,4 +1,7 @@
 import { EventEmitter } from 'events';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -323,15 +326,10 @@ describe('fs stat', () => {
 
 describe('fs prompt attachments', () => {
   it('stores binary bytes under the data-dir content-addressed path', async () => {
-    const fsPromises = {
-      mkdir: vi.fn(async () => undefined),
-      writeFile: vi.fn(async () => undefined),
-      rename: vi.fn(async () => undefined),
-      unlink: vi.fn(async () => undefined),
-    };
-    const handler = registerPromptAttachment(fsPromises);
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fs-prompt-att-'));
+    const handler = registerPromptAttachment({}, { openchamberDataDir: dataDir });
     const body = Buffer.from('hello-image');
-    const digest = 'a9a8fa077e26f69bcc4a7eeec6e1827a07ae07281952ae755766b9f06c8185e1';
+    const digest = createHash('sha256').update(body).digest('hex');
     const req = {
       params: { attachmentID: 'att-1' },
       headers: {
@@ -347,34 +345,20 @@ describe('fs prompt attachments', () => {
     const res = createMockResponse();
     await handler(req, res);
 
-    expect(res.body).toEqual({
+    expect(res.body).toMatchObject({
       success: true,
-      path: `/data/openchamber/prompt-attachments/${digest.slice(0, 2)}/${digest}.png`,
       size: body.length,
       mime: 'image/png',
       sha256: digest,
     });
-    expect(fsPromises.mkdir).toHaveBeenCalledWith(
-      `/data/openchamber/prompt-attachments/${digest.slice(0, 2)}`,
-      { recursive: true, mode: 0o700 },
-    );
-    const tmp = fsPromises.writeFile.mock.calls[0][0];
-    expect(tmp).toMatch(new RegExp(`^/data/openchamber/prompt-attachments/${digest.slice(0, 2)}/${digest}\\.png\\.tmp-`));
-    expect(fsPromises.writeFile).toHaveBeenCalledWith(tmp, body, { mode: 0o600 });
-    expect(fsPromises.rename).toHaveBeenCalledWith(
-      tmp,
-      `/data/openchamber/prompt-attachments/${digest.slice(0, 2)}/${digest}.png`,
-    );
+    expect(fs.existsSync(res.body.path)).toBe(true);
+    expect(path.basename(res.body.path)).toBe(`${digest}.png`);
+    fs.rmSync(dataDir, { recursive: true, force: true });
   });
 
   it('rejects digest mismatches without writing a durable file', async () => {
-    const fsPromises = {
-      mkdir: vi.fn(async () => undefined),
-      writeFile: vi.fn(async () => undefined),
-      rename: vi.fn(async () => undefined),
-      unlink: vi.fn(async () => undefined),
-    };
-    const handler = registerPromptAttachment(fsPromises);
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fs-prompt-att-bad-'));
+    const handler = registerPromptAttachment({}, { openchamberDataDir: dataDir });
     const body = Buffer.from('hello-image');
     const req = {
       params: { attachmentID: 'att-1' },
@@ -391,8 +375,9 @@ describe('fs prompt attachments', () => {
     await handler(req, res);
     expect(res.statusCode).toBe(400);
     expect(res.body).toEqual({ error: 'Attachment digest mismatch' });
-    expect(fsPromises.writeFile).not.toHaveBeenCalled();
-    expect(fsPromises.rename).not.toHaveBeenCalled();
+    const storeRoot = path.join(dataDir, 'prompt-attachments');
+    expect(fs.existsSync(storeRoot) ? fs.readdirSync(storeRoot).length : 0).toBe(0);
+    fs.rmSync(dataDir, { recursive: true, force: true });
   });
 
   it('reports unavailable storage when the data dir is missing', async () => {

package/server/lib/llm/catalog.js

@@ -5,8 +5,19 @@ const stringID = (value) => (typeof value === 'string' && value.trim() ? value.t
 const listIncludesImage = (value) => Array.isArray(value)
   && value.some((item) => String(item).toLowerCase() === 'image');
 
-function modelAcceptsImages(model) {
+/**
+ * Vision capability projection.
+ * Prefer authoritative OpenCode SDK Model.capabilities (`input.image` / `attachment`),
+ * then fall back to legacy modalities/input/attachment shapes used by older fixtures.
+ */
+export function modelAcceptsImages(model) {
   if (!isRecord(model)) return false;
+  if (isRecord(model.capabilities)) {
+    if (isRecord(model.capabilities.input) && typeof model.capabilities.input.image === 'boolean') {
+      return model.capabilities.input.image === true;
+    }
+    if (model.capabilities.attachment === true) return true;
+  }
   if (isRecord(model.modalities) && listIncludesImage(model.modalities.input)) return true;
   if (listIncludesImage(model.input)) return true;
   return model.attachment === true;
@@ -40,7 +51,12 @@ export function projectConnectedModels(source) {
       if (!isRecord(model)) continue;
       const modelID = stringID(model.id);
       if (!modelID) continue;
-      const entry = { providerID, modelID, name: stringID(model.name) || modelID, acceptsImages: modelAcceptsImages(model) };
+      const entry = {
+        providerID,
+        modelID,
+        name: stringID(model.name) || modelID,
+        acceptsImages: modelAcceptsImages(model),
+      };
       models.push(entry);
       providerModels.push({ id: modelID, name: entry.name });
     }
@@ -76,25 +92,84 @@ export function isConnectedModel(catalog, providerID, modelID) {
   return catalog.models.some((entry) => entry.providerID === providerID && entry.modelID === modelID);
 }
 
+/** Bound provider/config catalog loads so a pending SDK call cannot stall a contact lane. */
+export const CONNECTED_CATALOG_TIMEOUT_MS = 8_000;
+
+const isAbortError = (error) => (
+  error?.name === 'AbortError'
+  || error?.code === 'ABORT_ERR'
+  || (typeof error?.message === 'string' && /aborted|timed out/i.test(error.message))
+);
+
 /**
  * Load the connected catalog from an OpenCode SDK client.
  * Failure is distinct from a successful empty catalog.
+ * Uses a bounded AbortSignal (default 8s) on provider.list + config.providers.
+ *
+ * @param {object} client
+ * @param {{ signal?: AbortSignal, timeoutMs?: number }} [options]
  */
-export async function loadConnectedCatalog(client) {
-  const listed = await client.provider.list({});
-  if (listed?.error || !isRecord(listed?.data)) {
-    const error = new Error('OpenCode provider list is unavailable');
-    error.code = 'upstream_error';
-    throw error;
+export async function loadConnectedCatalog(client, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+    ? Math.trunc(options.timeoutMs)
+    : CONNECTED_CATALOG_TIMEOUT_MS;
+  const parentSignal = options.signal;
+  const controller = new AbortController();
+  const onParentAbort = () => {
+    try {
+      controller.abort(parentSignal?.reason instanceof Error
+        ? parentSignal.reason
+        : new Error('Connected catalog aborted'));
+    } catch {
+      // ignore
+    }
+  };
+  if (parentSignal) {
+    if (parentSignal.aborted) onParentAbort();
+    else parentSignal.addEventListener('abort', onParentAbort, { once: true });
   }
-  const configured = await client.config.providers({});
-  if (configured?.error || !isRecord(configured?.data)) {
-    const error = new Error('OpenCode provider catalog is unavailable');
-    error.code = 'upstream_error';
+  const timer = setTimeout(() => {
+    try {
+      controller.abort(new Error(`Connected catalog timed out after ${timeoutMs}ms`));
+    } catch {
+      // ignore
+    }
+  }, timeoutMs);
+  timer.unref?.();
+
+  const requestOptions = { signal: controller.signal };
+  try {
+    const listed = await client.provider.list({}, requestOptions);
+    if (listed?.error || !isRecord(listed?.data)) {
+      const error = new Error('OpenCode provider list is unavailable');
+      error.code = 'upstream_error';
+      throw error;
+    }
+    const configured = await client.config.providers({}, requestOptions);
+    if (configured?.error || !isRecord(configured?.data)) {
+      const error = new Error('OpenCode provider catalog is unavailable');
+      error.code = 'upstream_error';
+      throw error;
+    }
+    return projectConnectedModels({
+      connected: listed.data.connected,
+      providers: configured.data.providers,
+    });
+  } catch (error) {
+    if (controller.signal.aborted || isAbortError(error)) {
+      const timedOut = typeof error?.message === 'string' && /timed out/i.test(error.message)
+        || (controller.signal.reason instanceof Error && /timed out/i.test(controller.signal.reason.message));
+      const next = new Error(
+        timedOut
+          ? `Connected catalog timed out after ${timeoutMs}ms`
+          : 'Connected catalog request was aborted',
+      );
+      next.code = 'upstream_error';
+      throw next;
+    }
     throw error;
+  } finally {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener?.('abort', onParentAbort);
   }
-  return projectConnectedModels({
-    connected: listed.data.connected,
-    providers: configured.data.providers,
-  });
 }