Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(mcp): add original-byte file transfer
Rahman9180df3e6372
diff --git a/.env.example b/.env.exampleindex d6b9b0a9..3ccf33de 100644--- a/.env.example+++ b/.env.example@@ -331,6 +331,11 @@ OS_MCP_MAX_SCOPE=exec# Origin and need no entry. Exact origins only; this never weakens loopback/DNS-# rebinding protection. Example: https://claude.example,https://cursor.example# OS_MCP_BROWSER_ORIGINS=+# Optional exact Azure Blob hostnames accepted for ChatGPT fileParams downloads.+# `*.oaiusercontent.com` remains trusted without configuration; Azure account-name+# prefixes are NOT ownership proof, so list exact hosts only when your ChatGPT+# attachment URL uses Azure Blob. Comma-separated; wildcards are rejected.+# OS_MCP_OPENAI_FILE_HOSTS=oaisdmntprseasia.blob.core.windows.net# Persistent semantic skill/recipe memory. The default is ~/.mso/skill-memory.json# (0600). Embeddings are deterministic and local — no API key, model download or# network call is required.diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 59d24e8e..fd347bf2 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -6,6 +6,10 @@ this is the *what*, and it is what Settings → About shows as “What's new”.## 2026-09-14+**Added**++- `mcp` add original-byte file transfer+**Fixed**- `integrations` preserve strict SC bundle validationdiff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.mdindex 86ce5f6f..c19acd50 100644--- a/docs/CHATGPT-PLUGIN.md+++ b/docs/CHATGPT-PLUGIN.md@@ -118,6 +118,32 @@ The ChatGPT model profile includes:A completely idle ChatGPT conversation still cannot be awakened by a remote MCP server. Its durable mail is delivered on its next MCP call. `local_agent_request` and `agent_subagent_run` are part of the ChatGPT model profile; their existing scope, isolation, and server-side authorization rules remain authoritative.+## Original-byte file transfer++MSO exposes two bounded file bridges instead of treating screenshots/previews as general transfer:++```text+ChatGPT file parameter VPS file+ │ │+ ▼ ▼+ fs_upload_file fs_export_file+ │ │+ ├─ PNG/WebP/JPEG/JSON/ZIP only ├─ OS_FS_READ_ROOTS + credential denylist+ ├─ 20 MiB streamed cap ├─ original bytes, max 10 MiB+ ├─ trusted OpenAI host / exact Azure host ├─ SHA-256+ └─ OS_FS_WRITE_ROOTS └─ private 15-minute temp-share+ │+ ▼+ approved-device authenticated download+```++Upload trusts `*.oaiusercontent.com` directly. If ChatGPT supplies an Azure Blob URL, the exact+host must be configured in `OS_MCP_OPENAI_FILE_HOSTS`; wildcard or prefix-based Azure trust is+intentionally rejected. Export returns a `resource_link` plus structured checksum/size metadata.+The link is not public, consumes the existing MSO approved-device session gate, allows at most five+downloads, and preserves the source bytes exactly. `session_artifacts` remains a preview/artifact+workflow and may recompress large images, so it is not the original-file export path.+## OAuth contractFor origin `https://mso.example.com`:diff --git a/docs/MCP.md b/docs/MCP.mdindex 7f290f04..8e51bca7 100644--- a/docs/MCP.md+++ b/docs/MCP.md@@ -553,18 +553,26 @@ image generation**, and offering a second tool for the same job made the model cbetween them — usually wrong, and the MSO one billed a separate API key. Nothingreplaces it: ask the client to generate the image with its own capability.-Importing the result is unchanged and deliberately preserved: **`fs_upload_file`** takes-one ChatGPT conversation/generated file through `openai/fileParams`, downloads its-temporary OpenAI HTTPS URL immediately, re-validates up to three redirects, and consumes the+File transfer is now explicit in both directions. **`fs_upload_file`** takes one ChatGPT+conversation/generated PNG, WebP, JPEG, JSON or ZIP file through `openai/fileParams`, downloads+its temporary OpenAI HTTPS URL immediately, re-validates up to three redirects, and consumes thebody incrementally with a hard **20 MiB** ceiling even when `Content-Length` is absent or false.-It accepts PNG/WebP/JPEG or generic octet-stream, rejects a conflicting response MIME, validates-PNG/JPEG/WebP magic bytes, and writes only inside `OS_FS_WRITE_ROOTS`. Allowed download hosts are-OpenAI `*.oaiusercontent.com` content hosts or the explicitly matched-`oaisdmntpr<region>.blob.core.windows.net` storage-account family—not arbitrary Azure Blob hosts.-The final write uses the normal credential/path jail, an exclusive random temporary file and an-atomic rename; MSO never executes the transferred bytes automatically. The result returns path,-bytes and SHA-256. An existing same-name file may be replaced, so the tool is classified as a-write/destructive action. See `CHATGPT-PLUGIN.md` for the end-to-end diagram.+The declared/inferred MIME must be in that five-format matrix; generic octet-stream may be used on+the wire but cannot bypass the declared matrix. PNG/JPEG/WebP magic bytes, JSON UTF-8 + syntax,+and ZIP signatures are validated before the normal credential/path jail writes into+`OS_FS_WRITE_ROOTS`. `*.oaiusercontent.com` is trusted directly. Azure Blob hosts are accepted only+when their exact hostname is listed in `OS_MCP_OPENAI_FILE_HOSTS`; account-name prefixes are not+treated as ownership proof. The final write uses an exclusive random temporary file and atomic+rename, never executes transferred bytes, and returns path, bytes and SHA-256. Existing same-name+files may still be replaced, so import remains a write/destructive action.++**`fs_export_file`** is the read-side counterpart for one original file up to **10 MiB**. It uses+the same `OS_FS_READ_ROOTS`, realpath and credential denylist as other reads, reads with+`O_NOFOLLOW`, computes SHA-256 over the original bytes, then copies those bytes into the existing+private temporary-share store. The returned resource/download link requires an approved-device MSO+session, is `no-store`, expires after 15 minutes and is limited to five downloads. It never creates+a public URL and never routes through `session_artifacts`, so images and archives are not+recompressed or text-decoded. See `CHATGPT-PLUGIN.md` for the end-to-end contract.`OS_CODEX_BUILTIN_TOOLS` still exists and still takes an allowlisted list, but itsdefault is now EMPTY and `image_generation` is no longer an accepted value — naming itdiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 8071ca58..30b13f9b 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,3 +1,15 @@+## 2026-09-14 — Original-byte MCP file export + explicit ChatGPT import matrix++The upstream MSO file-transfer audit is now implemented instead of remaining a read-only finding.+`fs_export_file` exports one original file through the existing authenticated temporary-share store:+READ-root/credential guards and `O_NOFOLLOW` remain authoritative, bytes are not decoded or+recompressed, SHA-256 is returned, and the approved-device download expires after 15 minutes / five+downloads. ChatGPT import is now an explicit PNG/WebP/JPEG/JSON/ZIP matrix with format validation;+generic octet-stream is accepted only as a transport response for a known declared/inferred format,+not as a bypass. Azure Blob trust moved from an account-name prefix heuristic to exact optional+`OS_MCP_OPENAI_FILE_HOSTS` entries; `*.oaiusercontent.com` remains trusted directly. Derivative MSO+projects remain unchanged until this upstream contract passes release verification.+## 2026-09-14 — Integrations is a first-class shell app and SI-Coder worktrees are detected safely## 2026-09-14 — Preserve dedicated embed endpoint from concurrent releasediff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.mdindex 0e024269..5bdbb38f 100644--- a/docs/generated/MCP-CATALOG.md+++ b/docs/generated/MCP-CATALOG.md@@ -4,21 +4,21 @@## Full MSO catalog-<!-- mcp-toolset: server=1.14.1 version=2026.09.14.1 tools=104 read=49 write=34 exec=21 -->+<!-- mcp-toolset: server=1.14.1 version=2026.09.14.1 tools=105 read=50 write=34 exec=21 -->| Fact | Current source value ||---|---:|| MCP server | `1.14.1` || Toolset | `2026.09.14.1` || Toolset changed at | `2026-09-14T15:44:00Z` |-| Transport tools | **106** |-| Model/operator tools | **104** |-| Read | **49** |+| Transport tools | **107** |+| Model/operator tools | **105** |+| Read | **50** || Write | **34** || Exec | **21** || App-only bridges | **2** |-### Read (49)+### Read (50)- `a2a_agent_discover`- `a2a_agents_list`@@ -38,6 +38,7 @@- `exec_job_status`- `flow_catalog`- `flow_status`+- `fs_export_file`- `fs_list`- `fs_read`- `fs_search`@@ -138,20 +139,20 @@## ChatGPT model profile-<!-- mcp-chatgpt-profile: server=1.14.1 version=2026.09.14.1 tools=104 read=49 write=34 exec=21 app-only=2 total=106 -->+<!-- mcp-chatgpt-profile: server=1.14.1 version=2026.09.14.1 tools=105 read=50 write=34 exec=21 app-only=2 total=107 -->The ChatGPT profile automatically projects the complete MSO-owned generic model/operator catalog. OAuth scope is still enforced independently; app-only compatibility bridges stay app-only, and project-owned MCP tool names remain dynamic data behind the generic project bridge.| Fact | Current source value ||---|---:|-| ChatGPT transport tools | **106** |-| ChatGPT model/operator tools | **104** |-| Read | **49** |+| ChatGPT transport tools | **107** |+| ChatGPT model/operator tools | **105** |+| Read | **50** || Write | **34** || Exec | **21** || App-only bridges | **2** |-### ChatGPT read (49)+### ChatGPT read (50)- `a2a_agent_discover`- `a2a_agents_list`@@ -171,6 +172,7 @@ The ChatGPT profile automatically projects the complete MSO-owned generic model/- `exec_job_status`- `flow_catalog`- `flow_status`+- `fs_export_file`- `fs_list`- `fs_read`- `fs_search`diff --git a/lib/host/fs-api.ts b/lib/host/fs-api.tsindex 34314ecd..6ea62848 100644--- a/lib/host/fs-api.ts+++ b/lib/host/fs-api.ts@@ -1,7 +1,9 @@-export { listDir, readFile, writeFile, makeDir, remove, move, copy, searchFs, usage, statReadable, fileStream } from "./fs";+export { listDir, readFile, writeFile, makeDir, remove, move, copy, searchFs, usage, statReadable, mimeFor, fileStream } from "./fs";export { uploadInto, resolveUploadDest, streamFileInto } from "./fs-upload";export { zipStream } from "./fs-zip";export { parseMultipart, boundaryFromContentType, UploadTooLargeError } from "./multipart";export type { MultipartPart } from "./multipart";export { sha256Text, utf8Bytes } from "./hash";export { writeFileGuarded } from "./guarded-write";++export { readFileBytes } from "./fs-read-bytes";diff --git a/lib/host/fs-read-bytes.ts b/lib/host/fs-read-bytes.tsnew file mode 100644index 00000000..1111f745--- /dev/null+++ b/lib/host/fs-read-bytes.ts@@ -0,0 +1,23 @@+import { promises as fs, constants as fsConstants } from "fs";+import { HostError } from "./host-error";+import { resolveReadable } from "./paths";++/** Binary-safe bounded read using the same READ roots and sensitive-path jail as fs_read. */+export async function readFileBytes(requested: string, maxBytes = 10 * 1024 * 1024): Promise<Buffer> {+ const p = await resolveReadable(requested);+ let handle;+ try {+ handle = await fs.open(p, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);+ const stat = await handle.stat();+ if (!stat.isFile()) throw new HostError(stat.isDirectory() ? "Is a directory" : "Not a regular file");+ if (!Number.isFinite(maxBytes) || maxBytes < 1 || stat.size > maxBytes) {+ throw new HostError(`File too large to export (max ${Math.floor(maxBytes / (1024 * 1024))} MiB)`);+ }+ return await handle.readFile();+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code === "ELOOP") throw new HostError("Refusing symlink file");+ throw error;+ } finally {+ await handle?.close().catch(() => undefined);+ }+}diff --git a/lib/host/fs.ts b/lib/host/fs.tsindex b0b2961a..90e69d5f 100644--- a/lib/host/fs.ts+++ b/lib/host/fs.ts@@ -193,7 +193,7 @@ const MIME: Record<string, string> = {mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", flac: "audio/flac",aiff: "audio/aiff", aif: "audio/aiff", ogg: "audio/ogg", oga: "audio/ogg",opus: "audio/opus", aac: "audio/aac", wma: "audio/x-ms-wma",- pdf: "application/pdf",+ pdf: "application/pdf", json: "application/json", zip: "application/zip",};export function mimeFor(p: string): string {diff --git a/lib/mcp/openai-file-upload.test.ts b/lib/mcp/openai-file-upload.test.tsindex 8299bc50..83c99808 100644--- a/lib/mcp/openai-file-upload.test.ts+++ b/lib/mcp/openai-file-upload.test.ts@@ -1,5 +1,5 @@type FsApiModule = typeof import("@/lib/host/fs-api");-import { beforeEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";vi.mock("server-only", () => ({}));const uploadInto = vi.fn(async () => ({ written: 1, failed: [] as string[] }));@@ -10,93 +10,151 @@ vi.mock("@/lib/host/fs-api", async (orig) => {const { importOpenAiProvidedFile } = await import("./openai-file-upload");+const PNG = Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]);+const JPEG = Uint8Array.from([0xff, 0xd8, 0xff, 0x00]);+const WEBP = new TextEncoder().encode("RIFF0000WEBP");+const JSON_BYTES = new TextEncoder().encode('{"ok":true}');+const ZIP = Uint8Array.from([0x50, 0x4b, 0x03, 0x04, 0x00]);+beforeEach(() => {uploadInto.mockClear();- vi.stubGlobal("fetch", vi.fn(async () => new Response(Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]), {+ delete process.env.OS_MCP_OPENAI_FILE_HOSTS;+ vi.stubGlobal("fetch", vi.fn(async () => new Response(PNG, {status: 200,- headers: { "content-type": "image/png", "content-length": "8" },+ headers: { "content-type": "image/png", "content-length": String(PNG.byteLength) },})));});+afterEach(() => vi.unstubAllGlobals());-describe("ChatGPT file host allowlist", () => {- const importUrl = async (download_url: string, file_id = "file_test") => importOpenAiProvidedFile({+function importFile(input: {+ download_url?: string;+ file_id?: string;+ mime_type?: string;+ file_name?: string;+ size?: number;+}) {+ return importOpenAiProvidedFile({file: {- download_url,- file_id,- mime_type: "image/png",- file_name: "file.png",- size: 8,+ download_url: input.download_url || "https://files.oaiusercontent.com/file",+ file_id: input.file_id || "file_test",+ mime_type: input.mime_type,+ file_name: input.file_name || "file.png",+ size: input.size,},- dest: "/home/example/generated-images",- filename: "file.png",+ dest: "/home/example/generated-files",});+}- it.each([- "oaisdmntprseasia.blob.core.windows.net",- "oaisdmntpraustraliaeast.blob.core.windows.net",- "oaisdmntprnznorth.blob.core.windows.net",- "oaisdmntprindiasocentral.blob.core.windows.net",- "oaisdmntprfuture123.blob.core.windows.net",- ])("accepts OpenAI regional Azure storage account %s", async (host) => {- const result = await importUrl(`https://${host}/container/file.png?sig=redacted`);- expect(result.bytes).toBe(8);- expect(uploadInto).toHaveBeenCalledTimes(1);+describe("ChatGPT file host allowlist", () => {+ it("accepts OpenAI oaiusercontent content hosts by default", async () => {+ await expect(importFile({ download_url: "https://files.oaiusercontent.com/file.png", mime_type: "image/png" })).resolves.toMatchObject({ bytes: 8 });});- it.each([- "attacker.blob.core.windows.net",- "oaisdmntpr.blob.core.windows.net",- "oaisdmntpr-seasia.blob.core.windows.net",- "evil.oaisdmntprseasia.blob.core.windows.net",- "oaisdmntprseasia.blob.core.windows.net.evil.example",- ])("rejects non-OpenAI/lookalike Azure host %s", async (host) => {- await expect(importUrl(`https://${host}/container/file.png`)).rejects.toThrow("host is not allowed");- expect(uploadInto).not.toHaveBeenCalled();+ it("rejects Azure account-name prefixes unless the exact host is configured", async () => {+ await expect(importFile({ download_url: "https://oaisdmntprseasia.blob.core.windows.net/container/file.png", mime_type: "image/png" }))+ .rejects.toThrow("host is not allowed");+ });++ it("accepts only an exact configured Azure Blob hostname", async () => {+ process.env.OS_MCP_OPENAI_FILE_HOSTS = "oaisdmntprseasia.blob.core.windows.net";+ await expect(importFile({ download_url: "https://oaisdmntprseasia.blob.core.windows.net/container/file.png?sig=redacted", mime_type: "image/png" }))+ .resolves.toMatchObject({ bytes: 8 });+ await expect(importFile({ download_url: "https://oaisdmntprfuture123.blob.core.windows.net/container/file.png", mime_type: "image/png" }))+ .rejects.toThrow("host is not allowed");+ });++ it("rejects malformed configured Azure host entries fail-closed", async () => {+ process.env.OS_MCP_OPENAI_FILE_HOSTS = "*.blob.core.windows.net";+ await expect(importFile({ download_url: "https://files.oaiusercontent.com/file.png", mime_type: "image/png" }))+ .resolves.toMatchObject({ bytes: 8 });+ await expect(importFile({ download_url: "https://oaisdmntprseasia.blob.core.windows.net/file.png", mime_type: "image/png" }))+ .rejects.toThrow("invalid Azure Blob hostname");});- it("rejects a redirect from an allowed OpenAI host to an unrelated host", async () => {+ it("rejects a redirect from an allowed OpenAI host to an unconfigured Azure host", async () => {vi.stubGlobal("fetch", vi.fn(async () => new Response(null, {status: 302,headers: { location: "https://attacker.blob.core.windows.net/container/file.png" },})));- await expect(importUrl("https://oaisdmntprseasia.blob.core.windows.net/container/file.png"))+ await expect(importFile({ download_url: "https://files.oaiusercontent.com/start/file.png", mime_type: "image/png" })).rejects.toThrow("host is not allowed: attacker.blob.core.windows.net");- expect(uploadInto).not.toHaveBeenCalled();});- it("allows redirects only when every hop remains on a trusted OpenAI host", async () => {+ it("allows a redirect to an exact configured Azure host", async () => {+ process.env.OS_MCP_OPENAI_FILE_HOSTS = "oaisdmntprseasia.blob.core.windows.net";const fetchMock = vi.fn().mockResolvedValueOnce(new Response(null, {status: 302,- headers: { location: "https://oaisdmntprfuture123.blob.core.windows.net/container/file.png?sig=next" },+ headers: { location: "https://oaisdmntprseasia.blob.core.windows.net/container/file.png?sig=next" },}))- .mockResolvedValueOnce(new Response(Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]), {+ .mockResolvedValueOnce(new Response(PNG, {status: 200,headers: { "content-type": "image/png", "content-length": "8" },}));vi.stubGlobal("fetch", fetchMock);- const result = await importUrl("https://files.oaiusercontent.com/start/file.png");- expect(result.bytes).toBe(8);+ await expect(importFile({ download_url: "https://files.oaiusercontent.com/start/file.png", mime_type: "image/png" })).resolves.toMatchObject({ bytes: 8 });expect(fetchMock).toHaveBeenCalledTimes(2);- expect(uploadInto).toHaveBeenCalledTimes(1);});+});- it("rejects an image whose bytes do not match its declared MIME", async () => {- vi.stubGlobal("fetch", vi.fn(async () => new Response(new TextEncoder().encode("not a png"), {+describe("explicit ChatGPT file MIME matrix", () => {+ it.each([+ ["image/png", "file.png", PNG],+ ["image/jpeg", "file.jpg", JPEG],+ ["image/webp", "file.webp", WEBP],+ ["application/json", "file.json", JSON_BYTES],+ ["application/zip", "file.zip", ZIP],+ ])("accepts %s with matching content", async (mimeType, fileName, data) => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(data, {status: 200,- headers: { "content-type": "image/png" },+ headers: { "content-type": mimeType, "content-length": String(data.byteLength) },})));- await expect(importUrl("https://files.oaiusercontent.com/file.png")).rejects.toThrow("signature does not match image/png");+ await expect(importFile({ mime_type: mimeType, file_name: fileName, size: data.byteLength })).resolves.toMatchObject({ mimeType, bytes: data.byteLength });+ });++ it("normalizes the common ZIP MIME alias", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(ZIP, {+ status: 200,+ headers: { "content-type": "application/x-zip-compressed" },+ })));+ await expect(importFile({ mime_type: "application/x-zip-compressed", file_name: "file.zip" })).resolves.toMatchObject({ mimeType: "application/zip" });+ });++ it("infers a supported type from the filename when ChatGPT omits mime_type", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON_BYTES, {+ status: 200,+ headers: { "content-type": "application/octet-stream" },+ })));+ await expect(importFile({ file_name: "data.json" })).resolves.toMatchObject({ mimeType: "application/json" });+ });++ it("rejects generic declared octet-stream instead of bypassing the matrix", async () => {+ await expect(importFile({ mime_type: "application/octet-stream", file_name: "file.bin" })).rejects.toThrow("unsupported file type");expect(uploadInto).not.toHaveBeenCalled();});+ it("rejects invalid JSON content", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(new TextEncoder().encode("{broken"), {+ status: 200,+ headers: { "content-type": "application/json" },+ })));+ await expect(importFile({ mime_type: "application/json", file_name: "file.json" })).rejects.toThrow("content does not match application/json");+ });++ it("rejects invalid ZIP content", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(new TextEncoder().encode("not zip"), {+ status: 200,+ headers: { "content-type": "application/zip" },+ })));+ await expect(importFile({ mime_type: "application/zip", file_name: "file.zip" })).rejects.toThrow("content does not match application/zip");+ });+it("rejects a conflicting trusted response MIME", async () => {- vi.stubGlobal("fetch", vi.fn(async () => new Response(Uint8Array.from([0xff, 0xd8, 0xff]), {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JPEG, {status: 200,headers: { "content-type": "image/jpeg" },})));- await expect(importUrl("https://files.oaiusercontent.com/file.png")).rejects.toThrow("does not match image/png");- expect(uploadInto).not.toHaveBeenCalled();+ await expect(importFile({ mime_type: "image/png", file_name: "file.png" })).rejects.toThrow("does not match image/png");});it("stops a chunked response at 20 MiB even without Content-Length", async () => {@@ -109,17 +167,9 @@ describe("ChatGPT file host allowlist", () => {});vi.stubGlobal("fetch", vi.fn(async () => new Response(body, {status: 200,- headers: { "content-type": "application/octet-stream" },+ headers: { "content-type": "image/png" },})));- await expect(importOpenAiProvidedFile({- file: {- download_url: "https://files.oaiusercontent.com/file.bin",- file_id: "file_large",- mime_type: "application/octet-stream",- file_name: "file.bin",- },- dest: "/home/example/generated-images",- })).rejects.toThrow("exceeds the 20 MiB MCP import limit");+ await expect(importFile({ mime_type: "image/png", file_name: "large.png" })).rejects.toThrow("exceeds the 20 MiB MCP import limit");expect(uploadInto).not.toHaveBeenCalled();});});diff --git a/lib/mcp/openai-file-upload.ts b/lib/mcp/openai-file-upload.tsindex 24b18b16..22a7805a 100644--- a/lib/mcp/openai-file-upload.ts+++ b/lib/mcp/openai-file-upload.ts@@ -13,7 +13,17 @@ export interface OpenAiProvidedFile {}const MAX_FILE_BYTES = 20 * 1024 * 1024;-const ALLOWED_MIME = new Set(["image/png", "image/webp", "image/jpeg", "application/octet-stream"]);+const SUPPORTED_MIME = new Set(["image/png", "image/webp", "image/jpeg", "application/json", "application/zip"]);+const WIRE_MIME = new Set([...SUPPORTED_MIME, "application/octet-stream"]);+const MIME_ALIASES = new Map([["application/x-zip-compressed", "application/zip"]]);+const EXTENSION_MIME = new Map([+ [".png", "image/png"],+ [".webp", "image/webp"],+ [".jpg", "image/jpeg"],+ [".jpeg", "image/jpeg"],+ [".json", "application/json"],+ [".zip", "application/zip"],+]);function providedFile(value: unknown): OpenAiProvidedFile {if (!value || typeof value !== "object") throw new HostError("file must be a ChatGPT-provided file object");@@ -23,21 +33,35 @@ function providedFile(value: unknown): OpenAiProvidedFile {return row as OpenAiProvidedFile;}+function normalizeMime(value: string): string {+ const mime = value.split(";", 1)[0]?.trim().toLowerCase() || "";+ return MIME_ALIASES.get(mime) || mime;+}++function configuredAzureHosts(): Set<string> {+ const hosts = new Set<string>();+ for (const raw of (process.env.OS_MCP_OPENAI_FILE_HOSTS || "").split(",")) {+ const host = raw.trim().toLowerCase();+ if (!host) continue;+ if (!/^[a-z0-9-]+\.blob\.core\.windows\.net$/.test(host)) {+ throw new HostError("OS_MCP_OPENAI_FILE_HOSTS contains an invalid Azure Blob hostname");+ }+ hosts.add(host);+ }+ return hosts;+}+function trustedDownloadUrl(raw: string): URL {let url: URL;try { url = new URL(raw); } catch { throw new HostError("file.download_url is invalid"); }if (url.protocol !== "https:") throw new HostError("file.download_url must use HTTPS");const host = url.hostname.toLowerCase();- // ChatGPT temporary files are served either from oaiusercontent.com or from- // OpenAI-owned Azure Storage accounts whose globally unique account name uses- // the stable `oaisdmntpr<region>` prefix. Match that account family rather than- // enumerating regions, but never accept arbitrary *.blob.core.windows.net hosts.- // Azure storage account names are globally unique, so an unrelated tenant cannot- // create another account with the same full account name.- const openAiAzureBlobHost = /^oaisdmntpr[a-z0-9]{2,40}\.blob\.core\.windows\.net$/;+ // OpenAI-owned oaiusercontent hosts are trusted directly. Azure Blob accounts+ // are accepted only by exact operator allowlist: a shared account-name prefix+ // is not proof that an arbitrary Azure storage account belongs to OpenAI.const openAiContentHost = host === "files.oaiusercontent.com" || host.endsWith(".oaiusercontent.com");- if (!openAiContentHost && !openAiAzureBlobHost.test(host)) {+ if (!openAiContentHost && !configuredAzureHosts().has(host)) {throw new HostError(`file.download_url host is not allowed: ${host}`);}return url;@@ -49,7 +73,7 @@ async function fetchTrustedFile(initialUrl: URL): Promise<Response> {const response = await fetch(url, {redirect: "manual",signal: AbortSignal.timeout(60_000),- headers: { accept: "image/png,image/webp,image/jpeg,application/octet-stream" },+ headers: { accept: "image/png,image/webp,image/jpeg,application/json,application/zip,application/octet-stream" },});if (![301, 302, 303, 307, 308].includes(response.status)) return response;const location = response.headers.get("location");@@ -91,19 +115,44 @@ async function readBoundedBody(response: Response): Promise<Buffer> {}function responseMime(response: Response): string | null {- const value = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();+ const value = response.headers.get("content-type");if (!value) return null;- if (!ALLOWED_MIME.has(value)) throw new HostError(`unsupported response file type: ${value}`);- return value;+ const mime = normalizeMime(value);+ if (!WIRE_MIME.has(mime)) throw new HostError(`unsupported response file type: ${mime}`);+ return mime;}-function hasExpectedSignature(data: Buffer, mimeType: string): boolean {+function declaredMime(file: OpenAiProvidedFile): string {+ const explicit = file.mime_type ? normalizeMime(file.mime_type) : "";+ if (explicit) {+ if (!SUPPORTED_MIME.has(explicit)) throw new HostError(`unsupported file type: ${explicit}`);+ return explicit;+ }+ const candidate = file.file_name || file.name || "";+ const inferred = EXTENSION_MIME.get(path.extname(candidate).toLowerCase());+ if (!inferred) throw new HostError("file type is missing or unsupported");+ return inferred;+}++function validateBody(data: Buffer, mimeType: string): boolean {if (mimeType === "image/png") {return data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));}if (mimeType === "image/jpeg") return data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;if (mimeType === "image/webp") return data.length >= 12 && data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP";- return true; // application/octet-stream is intentionally a generic file bridge.+ if (mimeType === "application/zip") {+ return data.length >= 4 && data[0] === 0x50 && data[1] === 0x4b && [0x03, 0x05, 0x07].includes(data[2]) && [0x04, 0x06, 0x08].includes(data[3]);+ }+ if (mimeType === "application/json") {+ try {+ const text = new TextDecoder("utf-8", { fatal: true }).decode(data);+ JSON.parse(text);+ return true;+ } catch {+ return false;+ }+ }+ return false;}function safeFilename(input: string | undefined, fallback: string): string {@@ -128,8 +177,7 @@ export async function importOpenAiProvidedFile(opts: {}> {const file = providedFile(opts.file);const url = trustedDownloadUrl(file.download_url);- const mimeType = (file.mime_type || "application/octet-stream").toLowerCase();- if (!ALLOWED_MIME.has(mimeType)) throw new HostError(`unsupported file type: ${mimeType}`);+ const mimeType = declaredMime(file);if (typeof file.size === "number" && (!Number.isFinite(file.size) || file.size < 0 || file.size > MAX_FILE_BYTES)) {throw new HostError("file exceeds the 20 MiB MCP import limit");}@@ -137,19 +185,13 @@ export async function importOpenAiProvidedFile(opts: {const response = await fetchTrustedFile(url);if (!response.ok) throw new HostError(`OpenAI file download failed (${response.status})`);const wireMime = responseMime(response);- if (- mimeType !== "application/octet-stream" &&- wireMime &&- wireMime !== "application/octet-stream" &&- wireMime !== mimeType- ) {+ if (wireMime && wireMime !== "application/octet-stream" && wireMime !== mimeType) {throw new HostError(`response file type ${wireMime} does not match ${mimeType}`);}const data = await readBoundedBody(response);- const effectiveMime = mimeType === "application/octet-stream" ? (wireMime || mimeType) : mimeType;- if (!hasExpectedSignature(data, effectiveMime)) throw new HostError(`file signature does not match ${effectiveMime}`);+ if (!validateBody(data, mimeType)) throw new HostError(`file content does not match ${mimeType}`);- const fallback = file.file_name || file.name || `${file.file_id}.bin`;+ const fallback = file.file_name || file.name || `${file.file_id}${[...EXTENSION_MIME.entries()].find(([, mime]) => mime === mimeType)?.[0] || ".bin"}`;const filename = safeFilename(opts.filename, fallback);const result = await uploadInto(opts.dest, [{ relPath: filename, data }]);if (result.written !== 1 || result.failed.length) throw new HostError(`file import failed: ${result.failed.join(", ") || "not written"}`);diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.tsindex 9a23179d..fa98f2e4 100644--- a/lib/mcp/parity.test.ts+++ b/lib/mcp/parity.test.ts@@ -43,6 +43,7 @@ const MCP_ONLY: Record<string, string> = {"project.mcp.tools": "external MCP clients discover one selected project MCP lazily; dynamic project tool names never enter either global catalog","project.mcp.call": "external MCP clients execute one exact dynamically-discovered project MCP tool under exec scope; Alfa can use its approved exec path and must not import project MCP catalogs","fs.upload.file": "external ChatGPT connectors need openai/fileParams to move conversation-generated files onto the VPS; in-shell Alfa already has direct host filesystem access",+ "fs.export.file": "external MCP clients need an authenticated original-byte download bridge; in-shell Alfa already has direct host filesystem access","workflow.start": "the external connector needs an actor-scoped task boundary; Alfa already owns an in-app conversation/run boundary","workflow.status": "app-only MCP Apps bridge used by the ChatGPT progress component; Alfa already owns its in-shell run state and must not poll the external workflow store","workflow.cancel": "same actor-scoped boundary; external runs need explicit recovery from an interrupted task",@@ -167,6 +168,7 @@ describe("MCP rate limits mirror the routes", () => {"flow.run": 20, "flow.manage": 20, "agent.session.open": 20, "project.mcp.manage": 20, "project.asset.attach": 20,// Native capabilities have independent bounded buckets (no matching HTTP route)."screen.capture": 10,+ "fs.export": 20,"session.artifacts": 60,"session.artifact.register": 30,"session.artifact.cleanup": 6,diff --git a/lib/mcp/tool-contract.ts b/lib/mcp/tool-contract.tsindex b666743c..537b5181 100644--- a/lib/mcp/tool-contract.ts+++ b/lib/mcp/tool-contract.ts@@ -123,7 +123,7 @@ export function toolDescriptor(tool: McpTool, profile: McpToolProfile = "full")return {name: tool.name,title: tool.title ?? toolTitle(tool.name),- description: compact ? compactText(tool.chatgptDescription ?? tool.description) : tool.description,+ description: compact ? compactText(tool.chatgptDescription ?? tool.description, 72) : tool.description,inputSchema: compact ? compactSchema(tool.inputSchema) : tool.inputSchema,...(outputSchema ? { outputSchema: compact ? compactSchema(outputSchema) : outputSchema } : {}),securitySchemes,diff --git a/lib/mcp/tools-file-transfer.ts b/lib/mcp/tools-file-transfer.tsnew file mode 100644index 00000000..93a72212--- /dev/null+++ b/lib/mcp/tools-file-transfer.ts@@ -0,0 +1,48 @@+import { createHash } from "node:crypto";+import path from "node:path";+import { mimeFor, readFileBytes } from "@/lib/host/fs-api";+import { createTempShare, tempShareUrl } from "@/lib/host/temp-share-api";+import { mcpDirect, PATH_P, READ_ONLY, S, str, type McpTool } from "./tool-kit";++export const FILE_TRANSFER_READ_TOOLS: McpTool[] = [+ {+ name: "fs_export_file",+ description:+ "Export one original VPS file (max 10 MiB) from OS_FS_READ_ROOTS to a private 15-minute approved-device temp-share. Returns SHA-256 and a download/resource link; no decoding, recompression or public URL.",+ scope: "read",+ annotations: READ_ONLY,+ limit: { key: "fs.export", max: 20, windowMs: 60_000 },+ inputSchema: S(PATH_P, ["path"]),+ run: async (a) => {+ const requested = str(a, "path");+ const bytes = await readFileBytes(requested, 10 * 1024 * 1024);+ const filename = path.basename(requested);+ const mimeType = mimeFor(requested);+ const share = await createTempShare({ data: bytes, filename, mimeType, ttlMs: 15 * 60_000, maxDownloads: 5 });+ const previewUrl = tempShareUrl(share.id);+ const downloadUrl = tempShareUrl(share.id, true);+ const sha256 = createHash("sha256").update(bytes).digest("hex");+ const result = {+ path: requested,+ filename,+ mimeType,+ bytes: bytes.byteLength,+ sha256,+ previewUrl,+ downloadUrl,+ expiresAt: share.expiresAt,+ downloadsLeft: share.downloadsLeft,+ };+ return mcpDirect([+ {+ type: "resource_link",+ uri: downloadUrl,+ name: filename,+ description: "Authenticated original-byte download; requires an approved MSO browser session and expires automatically.",+ mimeType,+ },+ { type: "text", text: JSON.stringify(result) },+ ], false, { result });+ },+ },+];diff --git a/lib/mcp/tools-mutate.ts b/lib/mcp/tools-mutate.tsindex 88a7bec8..dd7662a3 100644--- a/lib/mcp/tools-mutate.ts+++ b/lib/mcp/tools-mutate.ts@@ -35,15 +35,15 @@ export const MUTATE_TOOLS: McpTool[] = [limit: { key: "fs.upload", max: 20, windowMs: 60_000 },audit: { action: "fs.upload" as const, targetArg: "dest" },description:- "Import one ChatGPT conversation/generated file into an existing VPS directory. " +- "ChatGPT binds the top-level file parameter through openai/fileParams, MSO downloads the temporary OpenAI URL immediately, validates the host/type/size, writes within OS_FS_WRITE_ROOTS, and returns byte count plus SHA-256. Existing same-name files may be replaced.",+ "Import one ChatGPT conversation/generated PNG, WebP, JPEG, JSON or ZIP file into an existing VPS directory. " ++ "ChatGPT binds the top-level file parameter through openai/fileParams; MSO downloads the temporary OpenAI URL immediately, validates exact host/type/size/content, writes within OS_FS_WRITE_ROOTS, and returns byte count plus SHA-256. Azure Blob download hosts require explicit OS_MCP_OPENAI_FILE_HOSTS allowlisting. Existing same-name files may be replaced.",scope: "write",annotations: { destructiveHint: true, openWorldHint: true },meta: { "openai/fileParams": ["file"] },inputSchema: S({file: {type: "object",- description: "ChatGPT-provided file reference. Select or attach exactly one generated/uploaded image.",+ description: "ChatGPT-provided file reference. Select or attach exactly one PNG, WebP, JPEG, JSON or ZIP file.",properties: {download_url: { type: "string" },file_id: { type: "string" },diff --git a/lib/mcp/tools-read-export.test.ts b/lib/mcp/tools-read-export.test.tsnew file mode 100644index 00000000..9d0512f1--- /dev/null+++ b/lib/mcp/tools-read-export.test.ts@@ -0,0 +1,60 @@+import { describe, expect, it, vi } from "vitest";+vi.mock("server-only", () => ({}));++const mocks = vi.hoisted(() => ({+ readFileBytes: vi.fn(async () => Buffer.from([0x50, 0x4b, 0x03, 0x04, 0x01, 0x02])),+ mimeFor: vi.fn(() => "application/zip"),+ createTempShare: vi.fn(async () => ({+ id: "abcdefghijklmnopqrstuvwxyzABCDEF",+ name: "archive.zip",+ mimeType: "application/zip",+ createdAt: 1,+ expiresAt: 901_000,+ downloadsLeft: 5,+ bytes: 6,+ })),+ tempShareUrl: vi.fn((id: string, download = false) => `https://mso.example.test/api/v1/temp-share/${id}${download ? "?download=1" : ""}`),+}));++vi.mock("@/lib/host/fs-api", async (orig) => {+ const real = await orig<typeof import("@/lib/host/fs-api")>();+ return { ...real, readFileBytes: mocks.readFileBytes, mimeFor: mocks.mimeFor };+});+vi.mock("@/lib/host/temp-share-api", () => ({ createTempShare: mocks.createTempShare, tempShareUrl: mocks.tempShareUrl }));++const { FILE_TRANSFER_READ_TOOLS } = await import("./tools-file-transfer");++describe("fs_export_file", () => {+ it("returns an authenticated original-byte resource link plus checksum metadata", async () => {+ const tool = FILE_TRANSFER_READ_TOOLS.find((row) => row.name === "fs_export_file");+ expect(tool).toBeDefined();+ expect(tool?.scope).toBe("read");+ expect(tool?.annotations).toMatchObject({ readOnlyHint: true });++ const result = await tool!.run({ path: "/home/example/archive.zip" }, { scope: "read" }) as {+ __mcpDirect: true;+ content: Array<Record<string, unknown>>;+ structuredContent?: { result?: Record<string, unknown> };+ };+ expect(mocks.readFileBytes).toHaveBeenCalledWith("/home/example/archive.zip", 10 * 1024 * 1024);+ expect(mocks.createTempShare).toHaveBeenCalledWith(expect.objectContaining({+ filename: "archive.zip",+ mimeType: "application/zip",+ ttlMs: 15 * 60_000,+ maxDownloads: 5,+ }));+ expect(result.content[0]).toMatchObject({+ type: "resource_link",+ uri: "https://mso.example.test/api/v1/temp-share/abcdefghijklmnopqrstuvwxyzABCDEF?download=1",+ name: "archive.zip",+ mimeType: "application/zip",+ });+ expect(result.structuredContent?.result).toMatchObject({+ filename: "archive.zip",+ mimeType: "application/zip",+ bytes: 6,+ sha256: "72ddd979de80b61ca55ce309f4c2a029c78a7ef9b6259e0a3d5e17a191a4cfdf",+ downloadsLeft: 5,+ });+ });+});diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.tsindex 6ab673cb..8a0cbc5a 100644--- a/lib/mcp/tools.ts+++ b/lib/mcp/tools.ts@@ -2,6 +2,7 @@ import { AGENT_OPEN_TOOLS } from "./tools-agent-open";import { PROJECT_ASSET_TOOLS } from "./tools-project-assets";import { PROJECT_MCP_MANAGE_TOOLS } from "./tools-project-mcp-manage";import { FLOW_TOOLS } from "./tools-flows";+import { FILE_TRANSFER_READ_TOOLS } from "./tools-file-transfer";import { withWorkflowContext } from "./tool-context";import { A2A_TOOLS } from "./tools-a2a";import { AGENT_TOOLS } from "./tools-agent";@@ -24,4 +25,4 @@ import { BLOCK_TOOLS, SURFACE_TOOLS } from "./tools-ui";import type { McpTool } from "./tool-kit";import { MUTATE_TOOLS } from "./tools-mutate";-export const TOOLS: McpTool[] = [...FLOW_TOOLS, ...AGENT_OPEN_TOOLS, ...PROJECT_ASSET_TOOLS, ...PROJECT_MCP_MANAGE_TOOLS, ...SESSION_ARTIFACT_TOOLS, ...READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...AGENT_TOOLS, ...LOCAL_AGENT_TOOLS, ...SUBAGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...READ_PIPELINE_TOOLS, ...PROJECT_MCP_TOOLS, ...PROJECT_EXPERIENCE_TOOLS, ...OPERATOR_DASHBOARD_TOOLS, ...BLOCK_TOOLS, ...SURFACE_TOOLS, ...INFRA_TOOLS, ...INTEGRATION_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));+export const TOOLS: McpTool[] = [...FLOW_TOOLS, ...AGENT_OPEN_TOOLS, ...PROJECT_ASSET_TOOLS, ...PROJECT_MCP_MANAGE_TOOLS, ...SESSION_ARTIFACT_TOOLS, ...READ_TOOLS, ...FILE_TRANSFER_READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...AGENT_TOOLS, ...LOCAL_AGENT_TOOLS, ...SUBAGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...READ_PIPELINE_TOOLS, ...PROJECT_MCP_TOOLS, ...PROJECT_EXPERIENCE_TOOLS, ...OPERATOR_DASHBOARD_TOOLS, ...BLOCK_TOOLS, ...SURFACE_TOOLS, ...INFRA_TOOLS, ...INTEGRATION_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));