Skip to content

armgit / mso

Public Imported from GitHub
0

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.

feat(mcp): add original-byte file transfer

Rahman9180df3e6372
diff --git a/.env.example b/.env.example
index 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.md
index 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 validation
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index 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 contract
For origin `https://mso.example.com`:
diff --git a/docs/MCP.md b/docs/MCP.md
index 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 c
between them — usually wrong, and the MSO one billed a separate API key. Nothing
replaces 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 the
body 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 its
default is now EMPTY and `image_generation` is no longer an accepted value — naming it
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 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 release
diff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.md
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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]));