@tangle-network/agent-app 0.60.191 → 0.60.192

package/dist/chat-routes/resolve-attachments.d.ts

@@ -17,6 +17,7 @@
  */
 import { type ChatAttachmentPart } from '../chat-store/parts';
 import type { ReadAttachmentFn } from './attachment-store';
+import { type AttachmentPathCheck } from './attachment-validation';
 /** Resolve the result of chat attachment processing with success status and corresponding data or error */
 export type ResolveChatAttachmentsResult = {
     succeeded: true;
@@ -25,31 +26,6 @@ export type ResolveChatAttachmentsResult = {
     succeeded: false;
     error: string;
 };
-/** Verdict of a path check: OK, or a rejection naming why. Mirrors
- *  `SandboxMentionPathCheck` in `./wire`. */
-export type AttachmentPathCheck = {
-    succeeded: true;
-} | {
-    succeeded: false;
-    error: string;
-};
-/**
- * Default path validator when a caller supplies none. Rejects the ways a path
- * picked in a client can escape the store root — traversal (`..` segment),
- * absolute (leading `/`), backslashes, null bytes, control characters (see
- * {@link CONTROL_CHARS} — a path also feeds {@link buildAttachmentPromptBlock}'s
- * `(vault: ${path})` pointer, so it is exposed to the same injection surface as
- * `name`) — plus a dotfile/hidden segment (a leading `.` on any segment).
- * Generalized from gtm's `validateVaultFilePath`, in the spirit of
- * `validateSandboxMentionPath` (`/chat-routes`'s wire mention-path validator) —
- * but the dotfile rejection here is INTENTIONALLY stricter than that sibling:
- * an uploaded attachment path is sanitized store-relative storage the product
- * itself assigned, whereas a mention path points at a file that already exists
- * in the sandbox and may legitimately live under a dotfile segment. A caller
- * that needs gtm's exact (looser) rule can supply `validatePath` to override
- * this default entirely.
- */
-export declare function defaultValidateAttachmentPath(path: string): AttachmentPathCheck;
 /** Define options to resolve and validate chat attachments with size, count, and path constraints */
 export interface ResolveChatAttachmentsOptions {
     /** The product's workspace/tenant key, passed to `readAttachment`. */

package/dist/chat-store/index.js

@@ -14,9 +14,9 @@ import {
   mentionInputToPart,
   mentionPartsFromMessageParts,
   toChatMessageParts
-} from "../chunk-TNWDYAFX.js";
-import "../chunk-YHRWZZJN.js";
+} from "../chunk-E6UTFXKQ.js";
 import "../chunk-ZVEEWGDK.js";
+import "../chunk-YHRWZZJN.js";
 import "../chunk-TXD5HXLE.js";
 import {
   attachmentPartKey

package/dist/{chunk-MSAGTFN4.js → chunk-6RFNLZCK.js}

@@ -27,7 +27,7 @@ import {
   checkAttachmentType,
   sanitizeAttachmentFileName,
   sniffBinary
-} from "./chunk-WTC6AOPL.js";
+} from "./chunk-PBQYVAB6.js";
 
 // src/web-react/use-dictation.ts
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -1552,4 +1552,4 @@ export {
   ComposerModeControls,
   EntryComposer
 };
-//# sourceMappingURL=chunk-MSAGTFN4.js.map
+//# sourceMappingURL=chunk-6RFNLZCK.js.map

package/dist/{chunk-TNWDYAFX.js → chunk-E6UTFXKQ.js}

@@ -1,9 +1,9 @@
-import {
-  mentionKindForPath
-} from "./chunk-YHRWZZJN.js";
 import {
   persistedPartToWorkProduct
 } from "./chunk-ZVEEWGDK.js";
+import {
+  mentionKindForPath
+} from "./chunk-YHRWZZJN.js";
 import {
   persistedPartToInteraction
 } from "./chunk-6VQCFJWP.js";
@@ -135,4 +135,4 @@ export {
   buildAttachmentPromptBlock,
   historyContentWithAttachments
 };
-//# sourceMappingURL=chunk-TNWDYAFX.js.map
+//# sourceMappingURL=chunk-E6UTFXKQ.js.map

package/dist/{chunk-Y2SOQOJE.js → chunk-KNTRS7OZ.js}

@@ -37,7 +37,7 @@ import {
 } from "./chunk-AVP5SNIG.js";
 import {
   attachmentPartsFromMessageParts
-} from "./chunk-TNWDYAFX.js";
+} from "./chunk-E6UTFXKQ.js";
 import {
   TURN_INTENT_EVENT,
   TURN_PHASE_EVENT,
@@ -7207,4 +7207,4 @@ export {
   useThinkingSeconds,
   ChatMessages
 };
-//# sourceMappingURL=chunk-Y2SOQOJE.js.map
+//# sourceMappingURL=chunk-KNTRS7OZ.js.map

package/dist/{chunk-WTC6AOPL.js → chunk-PBQYVAB6.js}

@@ -364,6 +364,84 @@ function attachmentSizeErrorMessage(name, actualBytes, limitBytes) {
 function attachmentTotalSizeErrorMessage(totalBytes, limitBytes) {
   return `Attachments total ${formatBytes(totalBytes)}; each message is limited to ${formatBytes(limitBytes)}`;
 }
+var MAX_ATTACHMENT_NAME_LENGTH = 256;
+function isAttachmentKind(value) {
+  return value === "image" || value === "file";
+}
+var CONTROL_CHARS = /[\x00-\x1F\x7F]/;
+function defaultValidateAttachmentPath(path) {
+  if (path.includes("\0")) return { succeeded: false, error: "attachment path must not contain null bytes" };
+  if (path.includes("\\")) return { succeeded: false, error: "attachment path must not contain backslashes" };
+  if (CONTROL_CHARS.test(path)) return { succeeded: false, error: "attachment path must not contain control characters" };
+  if (path.startsWith("/")) return { succeeded: false, error: "attachment path must be store-relative, not absolute" };
+  const segments = path.split("/");
+  if (segments.some((segment) => segment === "..")) {
+    return { succeeded: false, error: 'attachment path must not contain ".." segments' };
+  }
+  if (segments.some((segment) => segment.startsWith("."))) {
+    return { succeeded: false, error: "attachment path must not contain a hidden (dotfile) segment" };
+  }
+  return { succeeded: true };
+}
+function parseAttachmentInput(value, index, validatePath) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { succeeded: false, error: `attachments[${index}] must be an object` };
+  }
+  const record = value;
+  const path = record.path;
+  if (typeof path !== "string" || !path) {
+    return { succeeded: false, error: `attachments[${index}].path must be a non-empty string` };
+  }
+  const name = record.name;
+  if (typeof name !== "string" || !name.trim()) {
+    return { succeeded: false, error: `attachments[${index}].name must be a non-empty string` };
+  }
+  if (name.length > MAX_ATTACHMENT_NAME_LENGTH) {
+    return { succeeded: false, error: `attachments[${index}].name must not exceed ${MAX_ATTACHMENT_NAME_LENGTH} characters` };
+  }
+  if (CONTROL_CHARS.test(name)) {
+    return { succeeded: false, error: `attachments[${index}].name must not contain control characters` };
+  }
+  const size = record.size;
+  if (typeof size !== "number" || !Number.isFinite(size)) {
+    return { succeeded: false, error: `attachments[${index}].size must be a finite number` };
+  }
+  if (size < 0) {
+    return { succeeded: false, error: `attachments[${index}].size must not be negative` };
+  }
+  const mediaType = record.mediaType;
+  if (typeof mediaType !== "string") {
+    return { succeeded: false, error: `attachments[${index}].mediaType must be a string` };
+  }
+  const kind = record.kind;
+  if (!isAttachmentKind(kind)) {
+    return { succeeded: false, error: `attachments[${index}].kind must be "image" or "file"` };
+  }
+  const pathCheck = validatePath(path);
+  if (!pathCheck.succeeded) return { succeeded: false, error: pathCheck.error };
+  return { succeeded: true, value: { path, name, size, mediaType, kind } };
+}
+function parseChatAttachmentInputs(value, options = {}) {
+  const maxCount = options.maxCount ?? ATTACHMENT_MAX_COUNT;
+  const validatePath = options.validatePath ?? defaultValidateAttachmentPath;
+  if (value === void 0 || value === null) return { succeeded: true, value: [] };
+  if (!Array.isArray(value)) return { succeeded: false, error: "attachments must be an array" };
+  if (value.length > maxCount) {
+    return { succeeded: false, error: `attachments must not exceed ${maxCount} entries` };
+  }
+  const inputs = [];
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.length; index += 1) {
+    const parsed = parseAttachmentInput(value[index], index, validatePath);
+    if (!parsed.succeeded) return parsed;
+    if (seenPaths.has(parsed.value.path)) {
+      return { succeeded: false, error: `attachments must not repeat a path: ${parsed.value.path}` };
+    }
+    seenPaths.add(parsed.value.path);
+    inputs.push(parsed.value);
+  }
+  return { succeeded: true, value: inputs };
+}
 
 export {
   OOXML_WORD_MIME,
@@ -384,6 +462,8 @@ export {
   checkAttachmentType,
   sanitizeAttachmentFileName,
   attachmentSizeErrorMessage,
-  attachmentTotalSizeErrorMessage
+  attachmentTotalSizeErrorMessage,
+  defaultValidateAttachmentPath,
+  parseChatAttachmentInputs
 };
-//# sourceMappingURL=chunk-WTC6AOPL.js.map
+//# sourceMappingURL=chunk-PBQYVAB6.js.map

package/dist/chunk-PBQYVAB6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/chat-routes/binary-sniff.ts","../src/chat-routes/attachment-validation.ts"],"sourcesContent":["/**\n * Content-based binary/text classification, shared by the attachment upload\n * route (server) and the composer's client-side pre-validation (browser) —\n * both sides must agree on what counts as binary before a byte ever leaves\n * the client. Extension-based allowlists lie (a renamed `.docx`, a PNG saved\n * as `.txt`), so classification reads the actual bytes: a magic-byte table\n * for common binary formats first, then a UTF-8 decode attempt for\n * everything else. Three families need more than a fixed-offset signature and\n * get a reader of their own — ISO-BMFF brands (`sniffFtyp`), EBML containers\n * (`sniffEbml`), and OOXML Office packages, whose PKZIP container is shared\n * with every other `.zip` (`sniffOoxml`).\n *\n * Lifted near-verbatim from gtm-agent's `src/lib/binary-sniff.ts` (the\n * source PRs hardened this against real corruption/gate bugs: gtm#584,\n * gtm#592). Import-free by design — `/web-react` re-exports `/chat-routes`\n * modules into browser bundles (`tests/browser-safe-subpaths.test.ts` walks\n * the graph), so nothing here may reach a Node builtin or an engine package.\n */\n\nexport interface SniffResult {\n  binary: boolean\n  mime: string | null\n}\n\n/** Sniffed mime for a Word OOXML package (`.docx`). */\nexport const OOXML_WORD_MIME = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'\n\n/** Sniffed mime for an Excel OOXML package (`.xlsx`). */\nexport const OOXML_SPREADSHEET_MIME = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'\n\n/** Sniffed mime for a PowerPoint OOXML package (`.pptx`). */\nexport const OOXML_PRESENTATION_MIME = 'application/vnd.openxmlformats-officedocument.presentationml.presentation'\n\n/** Sniffed mime for a macro-enabled Word package (`.docm`). Reported\n *  separately from {@link OOXML_WORD_MIME} so a package carrying a VBA project\n *  can never be admitted under the plain-document mime: a route that wants\n *  macro-enabled files opts in explicitly through its allowed-mime seam. */\nexport const OOXML_WORD_MACRO_ENABLED_MIME = 'application/vnd.ms-word.document.macroEnabled.12'\n\n/** Sniffed mime for a macro-enabled Excel package (`.xlsm`). */\nexport const OOXML_SPREADSHEET_MACRO_ENABLED_MIME = 'application/vnd.ms-excel.sheet.macroEnabled.12'\n\n/** Sniffed mime for a macro-enabled PowerPoint package (`.pptm`). */\nexport const OOXML_PRESENTATION_MACRO_ENABLED_MIME = 'application/vnd.ms-powerpoint.presentation.macroEnabled.12'\n\nfunction bytesStartWith(bytes: Uint8Array, offset: number, signature: number[]): boolean {\n  if (bytes.length < offset + signature.length) return false\n  for (let i = 0; i < signature.length; i++) {\n    if (bytes[offset + i] !== signature[i]) return false\n  }\n  return true\n}\n\nfunction asciiAt(bytes: Uint8Array, offset: number, text: string): boolean {\n  if (bytes.length < offset + text.length) return false\n  for (let i = 0; i < text.length; i++) {\n    if (bytes[offset + i] !== text.charCodeAt(i)) return false\n  }\n  return true\n}\n\n/** RIFF containers (WebP, WAV) share the `RIFF....<TYPE>` header; the type\n *  tag at byte offset 8 distinguishes them. */\nfunction sniffRiff(bytes: Uint8Array): string | null {\n  if (!asciiAt(bytes, 0, 'RIFF')) return null\n  if (asciiAt(bytes, 8, 'WEBP')) return 'image/webp'\n  if (asciiAt(bytes, 8, 'WAVE')) return 'audio/wav'\n  return null\n}\n\n/** MP4/MOV/AVIF/HEIC containers share an `ftyp` box at byte offset 4; the\n *  major brand at offset 8 tells them apart within the shared ISO-BMFF\n *  family. Brands outside this table (mp4, m4a, m4v, etc) fall back to\n *  `video/mp4`, the family's most common member. */\nfunction sniffFtyp(bytes: Uint8Array): string | null {\n  if (!asciiAt(bytes, 4, 'ftyp')) return null\n  if (asciiAt(bytes, 8, 'qt  ')) return 'video/quicktime'\n  if (asciiAt(bytes, 8, 'avif') || asciiAt(bytes, 8, 'avis')) return 'image/avif'\n  if (asciiAt(bytes, 8, 'heic') || asciiAt(bytes, 8, 'heix') || asciiAt(bytes, 8, 'hevc') || asciiAt(bytes, 8, 'hevx')) return 'image/heic'\n  if (asciiAt(bytes, 8, 'mif1') || asciiAt(bytes, 8, 'msf1')) return 'image/heif'\n  return 'video/mp4'\n}\n\nconst EBML_HEADER_ID = 0x1a45dfa3\nconst EBML_DOC_TYPE_ID = 0x4282\n/** A normal EBML header is only a few dozen bytes. This cap keeps a crafted\n *  header from choosing how much untrusted input the DocType reader scans. */\nconst EBML_HEADER_SCAN_BYTES = 4 * 1024\n\ninterface EbmlVint {\n  length: number\n  value: number\n}\n\n/** Read an EBML variable-width integer. Element IDs retain their marker bit;\n *  element sizes remove it. Values too large for exact JS integer arithmetic,\n *  unknown-size sentinels, and truncated encodings are rejected. */\nfunction readEbmlVint(\n  bytes: Uint8Array,\n  offset: number,\n  maxLength: number,\n  stripMarker: boolean,\n): EbmlVint | null {\n  const first = bytes[offset]\n  if (first === undefined || first === 0) return null\n\n  let marker = 0x80\n  let length = 1\n  while ((first & marker) === 0) {\n    marker >>= 1\n    length++\n  }\n  if (length > maxLength || offset + length > bytes.length) return null\n\n  if (stripMarker) {\n    let unknown = (first & (marker - 1)) === marker - 1\n    for (let index = 1; index < length; index++) unknown &&= bytes[offset + index] === 0xff\n    if (unknown) return null\n  }\n\n  let value = stripMarker ? first & (marker - 1) : first\n  for (let index = 1; index < length; index++) {\n    value = value * 0x100 + bytes[offset + index]!\n    if (!Number.isSafeInteger(value)) return null\n  }\n  return { length, value }\n}\n\n/** WebM and Matroska share the EBML magic. Their header's bounded DocType\n *  element is the distinguishing signal; other or malformed EBML containers\n *  remain recognized only as unknown binary. */\nfunction sniffEbml(bytes: Uint8Array): string | null {\n  const headerId = readEbmlVint(bytes, 0, 4, false)\n  if (headerId?.value !== EBML_HEADER_ID) return null\n\n  const headerSize = readEbmlVint(bytes, headerId.length, 8, true)\n  if (!headerSize) return null\n  const headerStart = headerId.length + headerSize.length\n  const headerEnd = headerStart + headerSize.value\n  if (!Number.isSafeInteger(headerEnd) || headerEnd > bytes.length) return null\n  const scanEnd = Math.min(headerEnd, headerStart + EBML_HEADER_SCAN_BYTES)\n\n  let cursor = headerStart\n  while (cursor < scanEnd) {\n    const id = readEbmlVint(bytes, cursor, 4, false)\n    if (!id) return null\n    const size = readEbmlVint(bytes, cursor + id.length, 8, true)\n    if (!size) return null\n    const valueStart = cursor + id.length + size.length\n    const valueEnd = valueStart + size.value\n    if (!Number.isSafeInteger(valueEnd) || valueEnd > headerEnd || valueEnd > scanEnd) return null\n\n    if (id.value === EBML_DOC_TYPE_ID) {\n      let docType = ''\n      for (let index = valueStart; index < valueEnd; index++) {\n        const byte = bytes[index]!\n        if (byte > 0x7f) return null\n        docType += String.fromCharCode(byte)\n      }\n      if (docType === 'webm') return 'video/webm'\n      if (docType === 'matroska') return 'video/x-matroska'\n      return null\n    }\n    cursor = valueEnd\n  }\n  return null\n}\n\n/** `BM` alone matches ordinary prose (\"BMW…\"), so require the BMP header's\n *  reserved bytes (offsets 6-9), which the format mandates to be zero. */\nfunction sniffBmp(bytes: Uint8Array): boolean {\n  return asciiAt(bytes, 0, 'BM')\n    && bytes.length >= 10\n    && bytes[6] === 0 && bytes[7] === 0 && bytes[8] === 0 && bytes[9] === 0\n}\n\n/** `ID3` alone matches ordinary prose (\"ID3 tags…\"), so require the ID3v2\n *  header shape: a plausible version byte and sync-safe size bytes. */\nfunction sniffId3(bytes: Uint8Array): boolean {\n  return asciiAt(bytes, 0, 'ID3')\n    && bytes.length >= 10\n    && bytes[3]! < 0x10\n    && bytes[6]! < 0x80 && bytes[7]! < 0x80 && bytes[8]! < 0x80 && bytes[9]! < 0x80\n}\n\nconst ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50\nconst ZIP_CENTRAL_FILE_HEADER_SIGNATURE = 0x02014b50\nconst ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50\n/** Fixed part of an end-of-central-directory record, before its comment. */\nconst ZIP_END_OF_CENTRAL_DIRECTORY_BYTES = 22\n/** Fixed part of a central-directory file header, before name/extra/comment. */\nconst ZIP_CENTRAL_FILE_HEADER_BYTES = 46\n/** Fixed part of a local file header, before name/extra. */\nconst ZIP_LOCAL_FILE_HEADER_BYTES = 30\n/** A zip's trailing comment is a u16 length, so the end-of-central-directory\n *  record sits within this distance of the last byte. */\nconst ZIP_MAX_COMMENT_BYTES = 0xffff\n/** ZIP64 stores sentinels in the 16/32-bit fields and the real values in a\n *  separate record. Nothing that large rides an attachment cap, so a sentinel\n *  leaves the archive unclassified instead of half-parsed. */\nconst ZIP64_SENTINEL_U16 = 0xffff\nconst ZIP64_SENTINEL_U32 = 0xffffffff\n/** Deflate is the usual method; only method 0 (stored) can be read without an\n *  inflater, and this module has no decompression (it runs in the browser\n *  bundle and on the upload path, on untrusted bytes). */\nconst ZIP_METHOD_STORED = 0\n\n/** The OPC content-types part every OOXML package carries. */\nconst OPC_CONTENT_TYPES_PART = '[Content_Types].xml'\n\n/** The OPC package-relationships part. ECMA-376 Part 2 requires it in every\n *  conforming package, so an archive that borrowed the Office part NAMES\n *  without also carrying this one is not a package. Structural, like the\n *  content-types part: both are read from the zip's own uncompressed metadata,\n *  which is the only evidence available without an inflater. */\nconst OPC_PACKAGE_RELATIONSHIPS_PART = '_rels/.rels'\n\n/** Namespace a genuine content-types part declares. Only checkable when that\n *  part is STORED uncompressed — Word, Excel and PowerPoint all deflate it —\n *  so this narrows the crafted-archive surface where it applies and is silent\n *  where it does not. */\nconst OPC_CONTENT_TYPES_NAMESPACE = 'http://schemas.openxmlformats.org/package/2006/content-types'\n\n/** Ceiling on how much of the content-types part is read when it happens to\n *  be stored uncompressed — the genuine part is a few hundred bytes, and a\n *  crafted archive must not be able to dictate how much text is scanned. */\nconst OPC_CONTENT_TYPES_SCAN_BYTES = 64 * 1024\n\ninterface OoxmlDeclaredMainPartType {\n  /** The content type as it appears in the content-types part. */\n  readonly declaredType: string\n  /** Reported mime when the package carries no VBA project. */\n  readonly mime: string\n  /** Reported mime for the same family once a VBA project is present. */\n  readonly macroEnabledMime: string\n  /** True when `declaredType` is itself one of the macro-enabled types. */\n  readonly macroEnabled: boolean\n}\n\n/** Content types a package DECLARES for its main part, in the content-types\n *  part itself — the authoritative signal when it is readable, because it\n *  distinguishes a document from a template or a macro-enabled sibling that\n *  share the same part layout. Each row carries its macro-enabled sibling\n *  because a declared type is only half the answer: the VBA-project scan can\n *  override it, and a package that carries one is macro-enabled whatever it\n *  declares. */\nconst OOXML_DECLARED_MAIN_PART_TYPES: ReadonlyArray<OoxmlDeclaredMainPartType> = [\n  {\n    declaredType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml',\n    mime: OOXML_WORD_MIME,\n    macroEnabledMime: OOXML_WORD_MACRO_ENABLED_MIME,\n    macroEnabled: false,\n  },\n  {\n    declaredType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml',\n    mime: OOXML_SPREADSHEET_MIME,\n    macroEnabledMime: OOXML_SPREADSHEET_MACRO_ENABLED_MIME,\n    macroEnabled: false,\n  },\n  {\n    declaredType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml',\n    mime: OOXML_PRESENTATION_MIME,\n    macroEnabledMime: OOXML_PRESENTATION_MACRO_ENABLED_MIME,\n    macroEnabled: false,\n  },\n  {\n    declaredType: 'application/vnd.ms-word.document.macroEnabled.main+xml',\n    mime: OOXML_WORD_MACRO_ENABLED_MIME,\n    macroEnabledMime: OOXML_WORD_MACRO_ENABLED_MIME,\n    macroEnabled: true,\n  },\n  {\n    declaredType: 'application/vnd.ms-excel.sheet.macroEnabled.main+xml',\n    mime: OOXML_SPREADSHEET_MACRO_ENABLED_MIME,\n    macroEnabledMime: OOXML_SPREADSHEET_MACRO_ENABLED_MIME,\n    macroEnabled: true,\n  },\n  {\n    declaredType: 'application/vnd.ms-powerpoint.presentation.macroEnabled.main+xml',\n    mime: OOXML_PRESENTATION_MACRO_ENABLED_MIME,\n    macroEnabledMime: OOXML_PRESENTATION_MACRO_ENABLED_MIME,\n    macroEnabled: true,\n  },\n]\n\n/** Main part of each Office format, as it appears in the package's entry\n *  names — the structural signal used when the declared content types are\n *  compressed (the common case: Word, Excel and PowerPoint all deflate the\n *  content-types part). Entry names live in the zip's own uncompressed\n *  metadata, so reading them needs no inflater.\n *\n *  `directory` is the fallback for the packages that do not use the canonical\n *  main-part name — a repaired or converted Word file declares\n *  `word/document2.xml` — and it is only consulted for a package already\n *  confirmed to carry the OPC content-types part, where a `word/` part means\n *  a Word document and nothing else. The three directories never mix: an\n *  embedded workbook inside a `.docx` lives under `word/embeddings/`. */\nconst OOXML_MAIN_PARTS: ReadonlyArray<{ part: string; directory: string; mime: string; macroEnabledMime: string }> = [\n  { part: 'word/document.xml', directory: 'word/', mime: OOXML_WORD_MIME, macroEnabledMime: OOXML_WORD_MACRO_ENABLED_MIME },\n  { part: 'xl/workbook.xml', directory: 'xl/', mime: OOXML_SPREADSHEET_MIME, macroEnabledMime: OOXML_SPREADSHEET_MACRO_ENABLED_MIME },\n  { part: 'ppt/presentation.xml', directory: 'ppt/', mime: OOXML_PRESENTATION_MIME, macroEnabledMime: OOXML_PRESENTATION_MACRO_ENABLED_MIME },\n]\n\n/** A VBA project part means the package is macro-enabled whatever its\n *  extension claims. Matched by suffix rather than by exact path: naming the\n *  macro-enabled mime is the fail-closed answer (the default allow-list\n *  refuses it), so a part this misses is the expensive direction. */\nconst OOXML_VBA_PROJECT_PART_SUFFIX = 'vbaProject.bin'\n\ninterface ZipEntry {\n  name: string\n  compressionMethod: number\n  compressedBytes: number\n  localHeaderOffset: number\n}\n\nfunction readU16Le(bytes: Uint8Array, offset: number): number {\n  return bytes[offset]! | (bytes[offset + 1]! << 8)\n}\n\n/** Little-endian u32 as an unsigned JS number — the high byte is multiplied\n *  rather than shifted, because `<< 24` would produce a negative value. */\nfunction readU32Le(bytes: Uint8Array, offset: number): number {\n  return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16)) + bytes[offset + 3]! * 0x1000000\n}\n\n/** Entry names are raw bytes; only exact ASCII part names are compared here,\n *  so a non-ASCII byte becomes a character that can never match one. */\nfunction asciiEntryName(bytes: Uint8Array, offset: number, length: number): string {\n  let name = ''\n  for (let i = 0; i < length; i++) {\n    const byte = bytes[offset + i]!\n    name += byte < 0x80 ? String.fromCharCode(byte) : '\\uFFFD'\n  }\n  return name\n}\n\n/** Scan back from the tail for the end-of-central-directory record. The\n *  comment length must account for exactly the bytes that follow, or the\n *  \"signature\" is compressed data that happens to spell `PK\\x05\\x06`. */\nfunction findZipEndOfCentralDirectory(bytes: Uint8Array): number | null {\n  const lowest = Math.max(0, bytes.length - ZIP_END_OF_CENTRAL_DIRECTORY_BYTES - ZIP_MAX_COMMENT_BYTES)\n  for (let offset = bytes.length - ZIP_END_OF_CENTRAL_DIRECTORY_BYTES; offset >= lowest; offset--) {\n    if (readU32Le(bytes, offset) !== ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE) continue\n    if (offset + ZIP_END_OF_CENTRAL_DIRECTORY_BYTES + readU16Le(bytes, offset + 20) === bytes.length) return offset\n  }\n  return null\n}\n\n/** Read the archive's central directory — the authoritative index a zip\n *  reader uses. Returns `null` for anything that is not a complete, in-bounds,\n *  non-ZIP64 directory: a truncated or crafted archive is left unclassified\n *  rather than guessed at from its first local header. */\nfunction readZipCentralDirectory(bytes: Uint8Array): ZipEntry[] | null {\n  const end = findZipEndOfCentralDirectory(bytes)\n  if (end === null) return null\n\n  const entryCount = readU16Le(bytes, end + 10)\n  const directoryBytes = readU32Le(bytes, end + 12)\n  const directoryOffset = readU32Le(bytes, end + 16)\n  if (entryCount === ZIP64_SENTINEL_U16) return null\n  if (directoryBytes === ZIP64_SENTINEL_U32 || directoryOffset === ZIP64_SENTINEL_U32) return null\n  if (directoryOffset + directoryBytes > bytes.length) return null\n\n  const entries: ZipEntry[] = []\n  let cursor = directoryOffset\n  for (let i = 0; i < entryCount; i++) {\n    if (cursor + ZIP_CENTRAL_FILE_HEADER_BYTES > bytes.length) return null\n    if (readU32Le(bytes, cursor) !== ZIP_CENTRAL_FILE_HEADER_SIGNATURE) return null\n    const nameLength = readU16Le(bytes, cursor + 28)\n    const extraLength = readU16Le(bytes, cursor + 30)\n    const commentLength = readU16Le(bytes, cursor + 32)\n    if (cursor + ZIP_CENTRAL_FILE_HEADER_BYTES + nameLength > bytes.length) return null\n    entries.push({\n      name: asciiEntryName(bytes, cursor + ZIP_CENTRAL_FILE_HEADER_BYTES, nameLength),\n      compressionMethod: readU16Le(bytes, cursor + 10),\n      compressedBytes: readU32Le(bytes, cursor + 20),\n      localHeaderOffset: readU32Le(bytes, cursor + 42),\n    })\n    cursor += ZIP_CENTRAL_FILE_HEADER_BYTES + nameLength + extraLength + commentLength\n  }\n  return entries\n}\n\n/** Text of an entry stored WITHOUT compression, or `null` for anything else.\n *  The data offset is computed from the local header (its extra field may be\n *  a different length than the central directory's copy). */\nfunction storedZipEntryText(bytes: Uint8Array, entry: ZipEntry): string | null {\n  if (entry.compressionMethod !== ZIP_METHOD_STORED) return null\n  const header = entry.localHeaderOffset\n  if (header + ZIP_LOCAL_FILE_HEADER_BYTES > bytes.length) return null\n  if (readU32Le(bytes, header) !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) return null\n  const start = header + ZIP_LOCAL_FILE_HEADER_BYTES + readU16Le(bytes, header + 26) + readU16Le(bytes, header + 28)\n  const length = Math.min(entry.compressedBytes, OPC_CONTENT_TYPES_SCAN_BYTES)\n  if (length === 0 || start + length > bytes.length) return null\n  return new TextDecoder('utf-8').decode(bytes.subarray(start, start + length))\n}\n\n/**\n * Identify an OOXML (Office Open XML) package inside a PKZIP container, or\n * `null` for an archive that is not one.\n *\n * Every `.docx`/`.xlsx`/`.pptx` is a zip, so the zip signature alone says\n * nothing — matching on it would admit every `.zip` a user can produce. What\n * this reads is the archive's own uncompressed metadata: the central\n * directory's entry names, plus the content-types part's text in the one case\n * where a producer stored it uncompressed. Everything below follows from that\n * one constraint — the module ships into browser bundles and runs on untrusted\n * bytes, so it has no inflater and cannot read a deflated part.\n *\n * Structural preconditions (both required): the OPC content-types part\n * `[Content_Types].xml` AND the OPC package-relationships part `_rels/.rels`.\n * Which Office format it is comes from the content types the first part\n * DECLARES when it is readable, and otherwise from which main part the package\n * contains (`word/document.xml`, `xl/workbook.xml`, `ppt/presentation.xml`).\n * A package carrying a VBA project reports the macro-enabled mime — computed\n * BEFORE the declared lookup and applied to its answer, so a package that\n * declares the plain type and ships `vbaProject.bin` reports macro-enabled,\n * and a decoy `Override` cannot select the plainer of two declared types.\n *\n * **What this does NOT prove, and no name-only reader can.** A deflated part's\n * CONTENT is unreadable here, so an archive that names its entries like a\n * package and fills them with arbitrary bytes reports the Office mime. That is\n * the same standing as every other magic-byte family this module reports —\n * `%PDF-` followed by arbitrary bytes reports `application/pdf` — because a\n * content sniffer answers \"what format does this claim to be\", not \"is this\n * safe\". The attachment gate is a FORMAT gate; a product that needs the bytes\n * to be a real, parseable document gets that from `/documents`' extractor,\n * which fails loud on a package it cannot read.\n */\nfunction sniffOoxml(bytes: Uint8Array): string | null {\n  const entries = readZipCentralDirectory(bytes)\n  if (!entries) return null\n\n  const contentTypes = entries.find((entry) => entry.name === OPC_CONTENT_TYPES_PART)\n  if (!contentTypes) return null\n  const names = entries.map((entry) => entry.name)\n  if (!names.includes(OPC_PACKAGE_RELATIONSHIPS_PART)) return null\n\n  // Order is load-bearing: a VBA project part makes the package macro-enabled\n  // whatever its content-types part declares, and the declared lookup below\n  // RETURNS, so this has to be known before it runs.\n  const macroEnabled = names.some((name) => name.endsWith(OOXML_VBA_PROJECT_PART_SUFFIX))\n\n  const declared = storedZipEntryText(bytes, contentTypes)\n  if (declared !== null) {\n    if (!declared.includes(OPC_CONTENT_TYPES_NAMESPACE)) return null\n    // Every match, not the first: `includes` over the whole part means a decoy\n    // `Override` declaring a second main-part type is indistinguishable from\n    // the real one, so the macro-enabled reading wins whenever one is present.\n    const matches = OOXML_DECLARED_MAIN_PART_TYPES.filter((row) => declared.includes(row.declaredType))\n    const row = matches.find((candidate) => candidate.macroEnabled) ?? matches[0]\n    if (row) return macroEnabled || row.macroEnabled ? row.macroEnabledMime : row.mime\n  }\n\n  const canonical = OOXML_MAIN_PARTS.find((main) => names.includes(main.part))\n  const format = canonical ?? OOXML_MAIN_PARTS.find((main) => names.some((name) => name.startsWith(main.directory)))\n  if (!format) return null\n  return macroEnabled ? format.macroEnabledMime : format.mime\n}\n\nfunction sniffMagicBytes(bytes: Uint8Array): string | null {\n  if (bytesStartWith(bytes, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png'\n  if (bytesStartWith(bytes, 0, [0xff, 0xd8, 0xff])) return 'image/jpeg'\n  if (asciiAt(bytes, 0, 'GIF87a') || asciiAt(bytes, 0, 'GIF89a')) return 'image/gif'\n  if (sniffBmp(bytes)) return 'image/bmp'\n  if (bytesStartWith(bytes, 0, [0x49, 0x49, 0x2a, 0x00])) return 'image/tiff' // little-endian\n  if (bytesStartWith(bytes, 0, [0x4d, 0x4d, 0x00, 0x2a])) return 'image/tiff' // big-endian\n  if (bytesStartWith(bytes, 0, [0x00, 0x00, 0x01, 0x00])) return 'image/x-icon'\n  if (asciiAt(bytes, 0, '%PDF-')) return 'application/pdf'\n  // OOXML (.docx/.xlsx/.pptx) is a PKZIP container, so the container is\n  // inspected before an archive is reported as a generic one — see\n  // `sniffOoxml`. An archive that is not an Office package stays\n  // `application/zip`, which no default allow-list admits.\n  if (bytesStartWith(bytes, 0, [0x50, 0x4b, 0x03, 0x04])) return sniffOoxml(bytes) ?? 'application/zip'\n  if (bytesStartWith(bytes, 0, [0x1f, 0x8b])) return 'application/gzip'\n  if (sniffId3(bytes) || bytesStartWith(bytes, 0, [0xff, 0xfb])) return 'audio/mpeg'\n  if (asciiAt(bytes, 0, 'OggS')) return 'audio/ogg'\n\n  const ebml = sniffEbml(bytes)\n  if (ebml) return ebml\n\n  const riff = sniffRiff(bytes)\n  if (riff) return riff\n\n  const ftyp = sniffFtyp(bytes)\n  if (ftyp) return ftyp\n\n  return null\n}\n\n/** SVG is valid UTF-8 but must round-trip byte-identical (image tools read\n *  it from the box as a file), so it is classified binary. Conservative\n *  match: the document's first element is `<svg`, or an `<?xml` prolog is\n *  followed by an `<svg` element within the first ~1KB (comments/doctype may\n *  sit between). Plain XML without an svg root, or prose that merely\n *  mentions \"<svg\", stays text. */\nfunction sniffSvgText(decoded: string): boolean {\n  let text = decoded\n  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1)\n  text = text.trimStart()\n  if (/^<svg[\\s>/]/.test(text)) return true\n  if (!text.startsWith('<?xml')) return false\n  return /<svg[\\s>/]/.test(text.slice(0, 1024))\n}\n\n/** Decide whether uploaded bytes are binary or text, and identify the mime\n *  type when it can be determined from content. Magic bytes are checked\n *  first; anything unmatched falls back to a fatal UTF-8 decode. A NUL byte\n *  or a decode failure means binary. Valid UTF-8 that is an SVG document is\n *  binary (byte-identity matters for image tooling). Content that matches\n *  nothing and does not decode as text is binary with an unknown mime —\n *  extension-based guessing happens at the call site, not here. */\nexport function sniffBinary(bytes: Uint8Array): SniffResult {\n  const mime = sniffMagicBytes(bytes)\n  if (mime) return { binary: true, mime }\n\n  if (bytes.includes(0x00)) return { binary: true, mime: null }\n\n  let decoded: string\n  try {\n    decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes)\n  } catch {\n    return { binary: true, mime: null }\n  }\n  if (sniffSvgText(decoded)) return { binary: true, mime: 'image/svg+xml' }\n  return { binary: false, mime: null }\n}\n","/**\n * Shared attachment validation core — constants, type-gate, and filename\n * sanitization used by BOTH the (server) attachment upload route and the\n * (browser) composer's client-side pre-validation, so a rejection never\n * differs depending on which side classified the bytes first. The structural\n * `attachments` parser lives here too, so the chat route and the operator API\n * refuse the same turn bodies without either pulling in the chat store.\n *\n * ≈ gtm-agent's `src/lib/attachment-limits.ts`, minus what agent-app already\n * has (`ATTACHMENT_MAX_COUNT`/`MAX_ATTACHMENT_TOTAL_BYTES`/\n * `attachmentTotalSizeErrorMessage` lived in `./resolve-attachments` and are\n * re-homed here so the whole validation vocabulary — count cap, size caps,\n * and type gate — has one address). Import-free besides `./wire`\n * (`formatBytes`) and `./binary-sniff` (`SniffResult`): `/web-react`\n * re-exports `/chat-routes` modules into browser bundles\n * (`tests/browser-safe-subpaths.test.ts` walks the graph), so nothing here\n * may reach a Node builtin or an engine package.\n */\n\nimport { formatBytes, type ChatAttachmentInput, type ChatAttachmentKind } from './wire'\nimport {\n  OOXML_PRESENTATION_MACRO_ENABLED_MIME,\n  OOXML_PRESENTATION_MIME,\n  OOXML_SPREADSHEET_MACRO_ENABLED_MIME,\n  OOXML_SPREADSHEET_MIME,\n  OOXML_WORD_MACRO_ENABLED_MIME,\n  OOXML_WORD_MIME,\n} from './binary-sniff'\nimport type { SniffResult } from './binary-sniff'\n\n/** Ceiling on a binary attachment's raw (pre-encoding) byte size. */\nexport const MAX_BINARY_ATTACHMENT_BYTES = 10 * 1024 * 1024\n\n/** Ceiling on a text attachment's raw byte size. Text hydrates through\n *  inline prompt parts, a separate path that remains proxy-capped (see\n *  `INLINE_PARTS_MAX_BYTES` in `./wire`). */\nexport const MAX_TEXT_ATTACHMENT_BYTES = 950 * 1024\n\n/** Most files a single request may carry: the composer staging cap, the\n *  upload route's per-request cap, and the chat body's `attachments` cap. */\nexport const ATTACHMENT_MAX_COUNT = 10\n\n/** Aggregate raw-byte ceiling across one message's attachments. */\nexport const MAX_ATTACHMENT_TOTAL_BYTES = 25 * 1024 * 1024\n\n/**\n * Accept list for the composer file picker + type validation, same grammar as\n * the native `<input accept>` attribute. Images plus the text/doc types a\n * product's store actually reads.\n *\n * Every extension here is one the default {@link ALLOWED_ATTACHMENT_SNIFFED_MIMES}\n * actually admits — a picker that offers a format the gate then rejects is a\n * defect, so `tests/chat-routes/attachment-validation.test.ts` walks this\n * string and proves each entry uploads.\n */\nexport const ATTACHMENT_ACCEPT =\n  'image/*,.pdf,.docx,.xlsx,.pptx,.txt,.md,.csv,.json,.yaml,.yml,.html'\n\n/** The Office (OOXML) package mimes the default allow-list admits — the\n *  formats professionals actually send: Word contracts, Excel workpapers,\n *  PowerPoint decks. Admitting the format is a gate decision only; whether a\n *  product can EXTRACT text from one is that product's concern. */\nexport const OOXML_SNIFFED_MIMES: ReadonlySet<string> = new Set([\n  OOXML_WORD_MIME,\n  OOXML_SPREADSHEET_MIME,\n  OOXML_PRESENTATION_MIME,\n])\n\n/** Macro-enabled Office package mimes (`.docm`/`.xlsm`/`.pptm`), reported by\n *  `sniffBinary` but deliberately NOT in the default allow-list: a package\n *  carrying a VBA project is a different risk decision than a plain document,\n *  and it is the product's to make. Opt in by widening the allow-list at the\n *  route's `allowedSniffedMimes` seam:\n *  `new Set([...ALLOWED_ATTACHMENT_SNIFFED_MIMES, ...MACRO_ENABLED_OOXML_SNIFFED_MIMES])`. */\nexport const MACRO_ENABLED_OOXML_SNIFFED_MIMES: ReadonlySet<string> = new Set([\n  OOXML_WORD_MACRO_ENABLED_MIME,\n  OOXML_SPREADSHEET_MACRO_ENABLED_MIME,\n  OOXML_PRESENTATION_MACRO_ENABLED_MIME,\n])\n\n/** Sniffed-mime counterpart of `ATTACHMENT_ACCEPT`: the binary formats\n *  `sniffBinary` can identify from content among the accepted types.\n *  Values must match `sniffBinary`'s output strings verbatim, or every\n *  upload of that format fails the type gate — locked by the round-trip test\n *  that sniffs real bytes of every mime listed here. */\nexport const ALLOWED_ATTACHMENT_SNIFFED_MIMES: ReadonlySet<string> = new Set([\n  'image/png',\n  'image/jpeg',\n  'image/gif',\n  'image/bmp',\n  'image/tiff',\n  'image/x-icon',\n  'image/webp',\n  'image/svg+xml',\n  'image/avif',\n  'image/heic',\n  'image/heif',\n  'application/pdf',\n  ...OOXML_SNIFFED_MIMES,\n])\n\n/** Extensions whose magic-byte family is unambiguous, mapped to the mime\n *  `sniffBinary` emits for genuine content of that format. Keep in sync with\n *  `ATTACHMENT_ACCEPT`: an extension only belongs here if its format has a\n *  detectable magic-byte signature. Text extensions (.txt/.md/.csv/.json/\n *  .yaml/.yml/.html) are deliberately absent — they have no magic bytes to\n *  compare against, so they ride the plain UTF-8 gate instead. AVIF/HEIC/HEIF\n *  extensions are also deliberately absent: the ISO-BMFF brand-to-extension\n *  mapping in that family isn't one-to-one (a legitimate `.heic` can carry a\n *  `mif1` brand), so an extension-implies-mime entry would reject genuine\n *  files. They still ride the allowlist gate below, which is what catches an\n *  mp4 renamed `.avif` (its content sniffs `video/mp4`, not an allowed mime).\n *  The Office extensions ARE here: a `.zip` renamed `.docx` sniffs\n *  `application/zip` (its container carries neither of the two OPC parts an\n *  Office package must have), so the entry turns a generic 415 into a mismatch\n *  that names what the file actually is. Sniffing answers what format the\n *  bytes CLAIM to be, not whether they are a readable document — see\n *  `sniffOoxml`'s note on what a reader with no inflater can and cannot prove.\n *  The macro-enabled and EBML-video extensions are listed for the same reason\n *  even though the default allow-list refuses them — a product that widens\n *  the allow-list gets the renamed-file check with it. */\nconst EXTENSION_IMPLIES_SNIFFED_MIME: Readonly<Record<string, string>> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  gif: 'image/gif',\n  bmp: 'image/bmp',\n  tif: 'image/tiff',\n  tiff: 'image/tiff',\n  ico: 'image/x-icon',\n  webp: 'image/webp',\n  svg: 'image/svg+xml',\n  pdf: 'application/pdf',\n  docx: OOXML_WORD_MIME,\n  xlsx: OOXML_SPREADSHEET_MIME,\n  pptx: OOXML_PRESENTATION_MIME,\n  docm: OOXML_WORD_MACRO_ENABLED_MIME,\n  xlsm: OOXML_SPREADSHEET_MACRO_ENABLED_MIME,\n  pptm: OOXML_PRESENTATION_MACRO_ENABLED_MIME,\n  webm: 'video/webm',\n  mkv: 'video/x-matroska',\n}\n\n/** Represent the result of checking an attachment's type with success or specific failure details */\nexport type AttachmentTypeCheckResult =\n  | { succeeded: true }\n  | { succeeded: false; code: 'attachment_type_mismatch' | 'attachment_type_not_allowed'; message: string }\n\n/**\n * Cross-check a filename's extension against its sniffed content.\n *\n * Text content (`sniff.binary === false`) always passes here — it has no\n * magic bytes to compare, so it rides the existing UTF-8 gate instead. For\n * binary content: an extension with an unambiguous magic-byte family (e.g.\n * `.pdf`) must match the sniffed mime, or the upload is a mismatch (a\n * renamed file). Otherwise the sniffed mime must be one of `allowed`\n * (default {@link ALLOWED_ATTACHMENT_SNIFFED_MIMES}), or the upload is\n * rejected outright. The `allowed` param feeds a route's override seam (a\n * product accepting a narrower or wider set than the default).\n */\nexport function checkAttachmentType(\n  fileName: string,\n  sniff: SniffResult,\n  allowed: ReadonlySet<string> = ALLOWED_ATTACHMENT_SNIFFED_MIMES,\n): AttachmentTypeCheckResult {\n  if (sniff.binary === false) return { succeeded: true }\n\n  const extension = fileName.split('.').pop()?.toLowerCase() ?? ''\n  const impliedMime = EXTENSION_IMPLIES_SNIFFED_MIME[extension]\n  if (impliedMime && sniff.mime && sniff.mime !== impliedMime) {\n    return {\n      succeeded: false,\n      code: 'attachment_type_mismatch',\n      message: `${fileName} has a .${extension} extension, but its content is ${sniff.mime}`,\n    }\n  }\n\n  if (!sniff.mime || !allowed.has(sniff.mime)) {\n    return {\n      succeeded: false,\n      code: 'attachment_type_not_allowed',\n      message: sniff.mime\n        ? `${fileName}'s content (${sniff.mime}) is not an allowed attachment type`\n        : `${fileName}'s content is not a recognized attachment type`,\n    }\n  }\n\n  return { succeeded: true }\n}\n\n/**\n * Rewrite a filename into the store-path charset (`A-Za-z0-9._-` per\n * segment) — attachment paths double as store keys, sandbox file paths, and\n * in-message path references, none of which tolerate spaces or punctuation.\n * Runs of unsupported characters collapse to one `-`; leading dots/dashes are\n * stripped so the name can't read as a hidden segment. The original name is\n * preserved separately (the returned `ChatAttachmentInput.name`), so\n * sanitization loses nothing.\n */\nexport function sanitizeAttachmentFileName(name: string): string {\n  const sanitized = name\n    .trim()\n    .replace(/[^A-Za-z0-9._-]+/g, '-')\n    .replace(/^[.-]+/, '')\n  return sanitized || 'file'\n}\n\n/** Human-readable error naming both the actual size and the limit that was\n *  exceeded. Shared so the server route and the composer pre-check report\n *  the same message shape. */\nexport function attachmentSizeErrorMessage(name: string, actualBytes: number, limitBytes: number): string {\n  return `${name} is ${formatBytes(actualBytes)}; attachments are limited to ${formatBytes(limitBytes)}`\n}\n\n/** Human-readable error for a chat message whose combined attachments exceed\n *  the aggregate raw-byte ceiling. */\nexport function attachmentTotalSizeErrorMessage(totalBytes: number, limitBytes: number): string {\n  return `Attachments total ${formatBytes(totalBytes)}; each message is limited to ${formatBytes(limitBytes)}`\n}\n\n/** Verdict of a path check: OK, or a rejection naming why. Mirrors\n *  `SandboxMentionPathCheck` in `./wire`. */\nexport type AttachmentPathCheck =\n  | { succeeded: true }\n  | { succeeded: false; error: string }\n\n/** Longest attachment display name accepted — bounds what gets echoed into the\n *  prompt block and rendered as a chip label. */\nconst MAX_ATTACHMENT_NAME_LENGTH = 256\n\nfunction isAttachmentKind(value: unknown): value is ChatAttachmentKind {\n  return value === 'image' || value === 'file'\n}\n\n/** C0 control characters (0x00–0x1F) plus DEL (0x7F) — covers `\\n`/`\\r`/`\\t`.\n *  A `name` or `path` carrying one of these has no legitimate use here and\n *  everything to gain from an attacker: {@link buildAttachmentPromptBlock} in\n *  `/chat-store` renders both fields verbatim into the dispatched agent\n *  prompt, so an embedded newline fabricates new prompt lines (a\n *  prompt-injection vector) rather than naming a file. Rejected at this\n *  boundary — not merely neutralized downstream — so the wire never accepts\n *  the input in the first place; a legitimate name/path never contains one. */\nconst CONTROL_CHARS = /[\\x00-\\x1F\\x7F]/\n\n/**\n * Default path validator when a caller supplies none. Rejects the ways a path\n * picked in a client can escape the store root — traversal (`..` segment),\n * absolute (leading `/`), backslashes, null bytes, control characters (see\n * {@link CONTROL_CHARS} — a path also feeds {@link buildAttachmentPromptBlock}'s\n * `(vault: ${path})` pointer, so it is exposed to the same injection surface as\n * `name`) — plus a dotfile/hidden segment (a leading `.` on any segment).\n * Generalized from gtm's `validateVaultFilePath`, in the spirit of\n * `validateSandboxMentionPath` (`/chat-routes`'s wire mention-path validator) —\n * but the dotfile rejection here is INTENTIONALLY stricter than that sibling:\n * an uploaded attachment path is sanitized store-relative storage the product\n * itself assigned, whereas a mention path points at a file that already exists\n * in the sandbox and may legitimately live under a dotfile segment. A caller\n * that needs gtm's exact (looser) rule can supply `validatePath` to override\n * this default entirely.\n */\nexport function defaultValidateAttachmentPath(path: string): AttachmentPathCheck {\n  if (path.includes('\\0')) return { succeeded: false, error: 'attachment path must not contain null bytes' }\n  if (path.includes('\\\\')) return { succeeded: false, error: 'attachment path must not contain backslashes' }\n  if (CONTROL_CHARS.test(path)) return { succeeded: false, error: 'attachment path must not contain control characters' }\n  if (path.startsWith('/')) return { succeeded: false, error: 'attachment path must be store-relative, not absolute' }\n  const segments = path.split('/')\n  if (segments.some((segment) => segment === '..')) {\n    return { succeeded: false, error: 'attachment path must not contain \"..\" segments' }\n  }\n  if (segments.some((segment) => segment.startsWith('.'))) {\n    return { succeeded: false, error: 'attachment path must not contain a hidden (dotfile) segment' }\n  }\n  return { succeeded: true }\n}\n\nfunction parseAttachmentInput(\n  value: unknown,\n  index: number,\n  validatePath: (path: string) => AttachmentPathCheck,\n): { succeeded: true; value: ChatAttachmentInput } | { succeeded: false; error: string } {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return { succeeded: false, error: `attachments[${index}] must be an object` }\n  }\n  const record = value as Record<string, unknown>\n\n  const path = record.path\n  if (typeof path !== 'string' || !path) {\n    return { succeeded: false, error: `attachments[${index}].path must be a non-empty string` }\n  }\n  const name = record.name\n  if (typeof name !== 'string' || !name.trim()) {\n    return { succeeded: false, error: `attachments[${index}].name must be a non-empty string` }\n  }\n  if (name.length > MAX_ATTACHMENT_NAME_LENGTH) {\n    return { succeeded: false, error: `attachments[${index}].name must not exceed ${MAX_ATTACHMENT_NAME_LENGTH} characters` }\n  }\n  if (CONTROL_CHARS.test(name)) {\n    return { succeeded: false, error: `attachments[${index}].name must not contain control characters` }\n  }\n  const size = record.size\n  if (typeof size !== 'number' || !Number.isFinite(size)) {\n    return { succeeded: false, error: `attachments[${index}].size must be a finite number` }\n  }\n  if (size < 0) {\n    return { succeeded: false, error: `attachments[${index}].size must not be negative` }\n  }\n  const mediaType = record.mediaType\n  if (typeof mediaType !== 'string') {\n    return { succeeded: false, error: `attachments[${index}].mediaType must be a string` }\n  }\n  const kind = record.kind\n  if (!isAttachmentKind(kind)) {\n    return { succeeded: false, error: `attachments[${index}].kind must be \"image\" or \"file\"` }\n  }\n\n  const pathCheck = validatePath(path)\n  if (!pathCheck.succeeded) return { succeeded: false, error: pathCheck.error }\n\n  return { succeeded: true, value: { path, name, size, mediaType, kind } }\n}\n\n/** Structural limits for {@link parseChatAttachmentInputs}. */\nexport interface ParseChatAttachmentInputsOptions {\n  /** Most attachments one request may carry. Default {@link ATTACHMENT_MAX_COUNT}. */\n  maxCount?: number\n  /** Path validator override. Default {@link defaultValidateAttachmentPath}. */\n  validatePath?: (path: string) => AttachmentPathCheck\n}\n\n/**\n * Validate an `attachments` value's shape without reading the store: an\n * array of at most `maxCount` {@link ChatAttachmentInput}s with valid,\n * distinct paths. Absent (`undefined`/`null`) is an empty list. Sizes are\n * still client-reported here; {@link resolveChatAttachments} re-derives them\n * from the store.\n */\nexport function parseChatAttachmentInputs(\n  value: unknown,\n  options: ParseChatAttachmentInputsOptions = {},\n): { succeeded: true; value: ChatAttachmentInput[] } | { succeeded: false; error: string } {\n  const maxCount = options.maxCount ?? ATTACHMENT_MAX_COUNT\n  const validatePath = options.validatePath ?? defaultValidateAttachmentPath\n\n  if (value === undefined || value === null) return { succeeded: true, value: [] }\n  if (!Array.isArray(value)) return { succeeded: false, error: 'attachments must be an array' }\n  if (value.length > maxCount) {\n    return { succeeded: false, error: `attachments must not exceed ${maxCount} entries` }\n  }\n\n  const inputs: ChatAttachmentInput[] = []\n  const seenPaths = new Set<string>()\n  for (let index = 0; index < value.length; index += 1) {\n    const parsed = parseAttachmentInput(value[index], index, validatePath)\n    if (!parsed.succeeded) return parsed\n    if (seenPaths.has(parsed.value.path)) {\n      return { succeeded: false, error: `attachments must not repeat a path: ${parsed.value.path}` }\n    }\n    seenPaths.add(parsed.value.path)\n    inputs.push(parsed.value)\n  }\n  return { succeeded: true, value: inputs }\n}\n"],"mappings":"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","names":["row"]}

package/dist/{chunk-J26IXWFK.js → chunk-Q2H5FKVG.js}

@@ -17,7 +17,7 @@ import {
 import {
   mentionInputToPart,
   toChatMessageParts
-} from "./chunk-TNWDYAFX.js";
+} from "./chunk-E6UTFXKQ.js";
 import {
   ChatTurnInputError,
   TURN_INTENT_EVENT,
@@ -1270,4 +1270,4 @@ export {
   createChatTurnRoutes,
   streamChatRouteAsSandboxEvents
 };
-//# sourceMappingURL=chunk-J26IXWFK.js.map
+//# sourceMappingURL=chunk-Q2H5FKVG.js.map

package/dist/operator/chat-adapter.d.ts

@@ -1,3 +1,4 @@
+import type { ChatAttachmentInput } from '../chat-routes/wire.js';
 import type { OperatorApproval, OperatorAssetRef, OperatorFile, OperatorFileEntry, OperatorJournalEntry, OperatorRole, OperatorScorecard } from './contract.js';
 import { type OperatorAdapter, type OperatorContext } from './server.js';
 /** The message fields the adapter reads; agent-app's chat-store rows satisfy it. */
@@ -58,6 +59,12 @@ export interface ChatOperatorAdmissionStore<Identity> {
 export interface ChatOperatorAdapterOptions<Identity> {
     /** Optional durable claims; without one, transcript retry detection is not an atomic admission lock. */
     admissions?: ChatOperatorAdmissionStore<Identity>;
+    /**
+     * Set when `runTurn` forwards `attachments` in the chat request body and the
+     * chat route resolves them from the workspace's store, as with
+     * `resolveChatAttachments`. Without it, turns that carry attachments are refused.
+     */
+    acceptsAttachments?: boolean;
     /** The app's public origin, the base of every browser link. */
     origin: string;
     /** Browser path of a conversation; defaults to `/app/<workspace>/chat/<thread>`. */
@@ -98,6 +105,7 @@ export interface ChatOperatorAdapterOptions<Identity> {
      * Run one turn through the app's own chat route as this caller. The adapter
      * reads the response to its end, so the turn is driven exactly as a browser
      * holding its stream drives it, and the start request returns once it settles.
+     * `attachments` arrives only when `acceptsAttachments` is set.
      */
     runTurn(ctx: OperatorContext<Identity>, input: {
         workspaceId: string;
@@ -105,6 +113,7 @@ export interface ChatOperatorAdapterOptions<Identity> {
         turnId: string;
         content: string;
         model?: string;
+        attachments?: ChatAttachmentInput[];
     }): Promise<Response>;
     /** Optional authoritative status of this user-turn anchor. When supplied,
      *  missing/running status without a live lease never promotes a partial reply to success. */

package/dist/operator/contract.d.ts

@@ -4,6 +4,7 @@
  * another app's agent) holds one scoped key per app and drives workspaces
  * through these routes; the app supplies only storage and execution.
  */
+import type { ChatAttachmentInput } from '../chat-routes/wire.js';
 export declare const OPERATOR_API_VERSION = "v1";
 export declare const OPERATOR_API_BASE_PATH = "/api/operator/v1";
 /** Key permissions, with the labels an app's API access page shows. */
@@ -42,7 +43,7 @@ export interface OperatorAppInfo {
     /** Optional operations this app implements; absent ones answer 501. */
     capabilities: OperatorCapability[];
 }
-export type OperatorCapability = 'workspaces.create' | 'threads.read' | 'files.read' | 'journal.read' | 'assets.read' | 'scorecard.read';
+export type OperatorCapability = 'turns.attachments' | 'workspaces.create' | 'threads.read' | 'files.read' | 'journal.read' | 'assets.read' | 'scorecard.read';
 export interface OperatorPrincipalInfo {
     keyId: string;
     scopes: string[];
@@ -174,6 +175,15 @@ export interface StartTurnInput {
     /** Title for a new conversation. */
     title?: string;
     model?: string;
+    /**
+     * Files uploaded to this workspace ahead of the turn, as the app's
+     * attachment upload route returned them in `{ files }`. They reach the
+     * agent exactly as browser-composer attachments do; the app re-checks each
+     * path against the workspace's own store. At most `ATTACHMENT_MAX_COUNT`
+     * (`/chat-routes`) entries. Apps without the `turns.attachments`
+     * capability refuse them.
+     */
+    attachments?: ChatAttachmentInput[];
 }
 /** Route table: method, path pattern under the base path, and required scopes. */
 export declare const OPERATOR_ROUTES: readonly [{

package/dist/operator/index.js

@@ -3,12 +3,17 @@ import {
   agentOperatorScopes,
   createApiKeyRequestAuth
 } from "../chunk-XB4KZVUV.js";
+import {
+  parseChatAttachmentInputs
+} from "../chunk-PBQYVAB6.js";
 import {
   createApiKeyFetch
 } from "../chunk-RN4WPTBH.js";
 import {
   messageHasTurnId
 } from "../chunk-YG66IHDU.js";
+import "../chunk-YHRWZZJN.js";
+import "../chunk-TXD5HXLE.js";
 
 // src/operator/contract.ts
 var OPERATOR_API_VERSION = "v1";
@@ -121,7 +126,7 @@ var TURN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a
 var THREAD_ID = /^[A-Za-z0-9_-]{1,256}$/;
 var MAX_BODY_BYTES = 128 * 1024;
 var MAX_CONTENT_BYTES = 64 * 1024;
-var START_FIELDS = /* @__PURE__ */ new Set(["turnId", "content", "threadId", "title", "model"]);
+var START_FIELDS = /* @__PURE__ */ new Set(["turnId", "content", "threadId", "title", "model", "attachments"]);
 var NO_STORE = { "cache-control": "private, no-store" };
 function json(body, status = 200) {
   return Response.json(body, { status, headers: NO_STORE });
@@ -192,12 +197,15 @@ function parseStartTurn(body) {
   }
   const title = optionalString(body, "title", 200);
   const model = optionalString(body, "model", 200);
+  const attachments = parseChatAttachmentInputs(body.attachments);
+  if (!attachments.succeeded) throw new OperatorError("operator.invalid_input", 400, attachments.error);
   return {
     turnId: body.turnId.toLowerCase(),
     content: body.content,
     ...threadId === void 0 ? {} : { threadId },
     ...title === void 0 ? {} : { title },
-    ...model === void 0 ? {} : { model }
+    ...model === void 0 ? {} : { model },
+    ...attachments.value.length === 0 ? {} : { attachments: attachments.value }
   };
 }
 function capabilities(adapter) {
@@ -209,7 +217,8 @@ function capabilities(adapter) {
     ["assets.read", adapter.readAsset],
     ["scorecard.read", adapter.getScorecard]
   ];
-  return present.filter(([, implemented]) => typeof implemented === "function").map(([name]) => name);
+  const implemented = present.filter(([, method]) => typeof method === "function").map(([name]) => name);
+  return adapter.acceptsAttachments === true ? ["turns.attachments", ...implemented] : implemented;
 }
 function unsupported() {
   throw new OperatorError("operator.unsupported", 501, "This app does not implement this operation");
@@ -306,6 +315,9 @@ function createOperatorApi(options) {
           return json({ workspace });
         case "turns.start": {
           const input = parseStartTurn(await readJsonBody(request));
+          if (input.attachments && adapter.acceptsAttachments !== true) {
+            throw new OperatorError("operator.unsupported", 501, "This app does not accept attachments on operator turns");
+          }
           return json({ turn: await adapter.startTurn(ctx, workspace, input) }, 202);
         }
         case "threads.list": {
@@ -682,6 +694,7 @@ function createChatOperatorAdapter(options) {
     return id;
   }
   const adapter = {
+    ...options.acceptsAttachments === true ? { acceptsAttachments: true } : {},
     async authorizeWorkspace(ctx, workspaceId, access) {
       const workspace = await options.workspaces.authorize(ctx, workspaceId, access);
       return workspace ? workspaceView(workspace) : null;
@@ -715,7 +728,8 @@ function createChatOperatorAdapter(options) {
         threadId,
         turnId: input.turnId,
         content: input.content,
-        ...input.model === void 0 ? {} : { model: input.model }
+        ...input.model === void 0 ? {} : { model: input.model },
+        ...input.attachments === void 0 ? {} : { attachments: input.attachments }
       });
       if (!response.ok) {
         const body = await response.json().catch(() => ({}));