feat: download native ChatGPT files into workspaces (#88)

* feat: stage native ChatGPT artifacts privately

* feat: materialize staged artifacts in workspaces

* fix: accept regional ChatGPT artifact hosts

* test: harden artifact workspace materialization

* feat: materialize native artifacts in one call

* refactor: use one-shot native artifact downloads

* test: make artifact security fixtures umask-independent

* feat: download artifacts to requested paths

* docs: describe artifact destination handoff

* refactor: stage artifacts beside destination

* refactor: remove retired artifact migration

* fix: preserve raced artifact destinations

* refactor: remove retired artifact store shims

* fix: gate artifact downloads by platform

* fix: keep downloaded artifacts private

* fix: address final artifact handoff review

---------

Co-authored-by: Waishnav <waishnavdeore@gmail.com>

Author: jplew

.env.example

@@ -27,6 +27,10 @@ DEVSPACE_LOG_SHELL_COMMANDS=0
 # DEVSPACE_TRUST_PROXY=1
 # DEVSPACE_STATE_DIR=/home/waishnav/.local/share/devspace
 # DEVSPACE_WORKTREE_ROOT=/home/waishnav/.devspace/worktrees
+# Native-file download is opt-in. Files stream to a model-selected relative
+# path inside an already-open workspace without overwriting existing files.
+# DEVSPACE_ARTIFACTS=1
+# DEVSPACE_ARTIFACT_MAX_FILE_BYTES=104857600
 # DEVSPACE_AUTO_LOAD_AGENTS_MD=1
 # Skills are enabled by default. Set DEVSPACE_SKILLS=0 to hide them.
 # DEVSPACE_SKILLS=0

README.md

@@ -180,6 +180,7 @@ devspace doctor
 - [Setup Guide](https://github.com/Waishnav/devspace/blob/main/docs/setup.md)
 - [ChatGPT Coding Workflow](https://github.com/Waishnav/devspace/blob/main/docs/chatgpt-coding-workflow.md)
 - [Configuration Reference](https://github.com/Waishnav/devspace/blob/main/docs/configuration.md)
+- [Native File Download](https://github.com/Waishnav/devspace/blob/main/docs/artifact-exchange.md)
 - [Security Model](https://github.com/Waishnav/devspace/blob/main/docs/security.md)
 - [Troubleshooting Gotchas](https://github.com/Waishnav/devspace/blob/main/docs/gotchas.md)
 

docs/artifact-exchange.md

@@ -0,0 +1,42 @@
+# Download a native file
+
+DevSpace can save a file attached or generated by an MCP host, such as ChatGPT,
+directly into an open workspace. Enable the tool with `DEVSPACE_ARTIFACTS=1`.
+
+## Workflow
+
+```text
+open_workspace
+  -> download_artifact({ file, workspaceId, path })
+  -> { path }
+```
+
+1. Open the project with `open_workspace`.
+2. Pass the host-provided native `file`, the returned `workspaceId`, and an
+   unused workspace-relative `path` to `download_artifact`.
+3. Use the returned path with the ordinary DevSpace filesystem tools.
+
+```text
+download_artifact({
+  file: <native file value supplied by the MCP host>,
+  workspaceId: "ws_123",
+  path: "public/images/generated-image.png"
+})
+```
+
+DevSpace creates missing parent directories and refuses to overwrite an existing
+file. After the download, normal tools can inspect, move, rename, replace, or
+delete it.
+
+## Safety and limits
+
+The `file` input must be the native value supplied by the MCP host. DevSpace does
+not accept pasted download URLs or local source paths. It validates the complete
+file-object shape, trusted OpenAI download hosts, and redirects before streaming.
+Malformed references, unknown fields, absolute paths, traversal, and symlinked
+parents are rejected.
+
+Downloads are streamed under `DEVSPACE_ARTIFACT_MAX_FILE_BYTES` and published as
+owner-only files without overwriting an existing destination. The tool is
+available on Linux, macOS, FreeBSD, OpenBSD, and NetBSD; it is not registered on
+Windows.

docs/configuration.md

@@ -39,6 +39,38 @@ npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com
 | `DEVSPACE_WORKTREE_ROOT` | Directory for managed Git worktrees. Defaults to `~/.devspace/worktrees`. |
 | `DEVSPACE_STATE_DIR` | Directory for SQLite state. Defaults to `~/.local/share/devspace`. |
 
+## Native Artifact Download
+
+Native-file download is disabled by default. Enable it when ChatGPT needs to hand
+an attached or generated file into an already-open workspace:
+
+```bash
+DEVSPACE_ARTIFACTS=1 npx @waishnav/devspace serve
+```
+
+This feature currently supports Linux, macOS, FreeBSD, OpenBSD, and NetBSD. It
+is not registered on Windows because the secure publication path depends on
+descriptor-anchored directory operations.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DEVSPACE_ARTIFACTS` | `0` | Expose `download_artifact` for trusted native files. |
+| `DEVSPACE_ARTIFACT_MAX_FILE_BYTES` | `104857600` | Maximum streamed size of one file (100 MiB). |
+
+The same settings may be persisted in `~/.devspace/config.json` as
+`artifactsEnabled` and `artifactMaxFileBytes`.
+
+`download_artifact` accepts the native file object supplied by the MCP connector,
+a `workspaceId` returned by `open_workspace`, and a relative workspace `path`.
+DevSpace safely creates missing parent directories, refuses to overwrite an
+existing destination, and returns only the normalized workspace-relative path.
+It does not accept conflict modes, expected hashes, arbitrary URL strings, local
+paths, embedded credentials, or extra object fields.
+
+There is no artifact root, total quota, TTL, pinning, persistent database record,
+or background artifact cleanup service. See [Native File Download](artifact-exchange.md)
+for the supported connector shape and security boundaries.
+
 ## OAuth
 
 DevSpace uses a single-user OAuth approval flow.
@@ -158,6 +190,7 @@ DEVSPACE_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
 DEVSPACE_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
 DEVSPACE_PUBLIC_BASE_URL="https://devspace.example.com" \
 DEVSPACE_WORKTREE_ROOT="$HOME/.devspace/worktrees" \
+DEVSPACE_ARTIFACTS="1" \
 DEVSPACE_TOOL_MODE="minimal" \
 DEVSPACE_WIDGETS="full" \
 npx @waishnav/devspace serve

docs/security.md

@@ -92,9 +92,33 @@ Managed worktrees reduce accidental edits to your active checkout, but they are
 not a security boundary. They are a workflow boundary for isolated coding
 sessions.
 
+## Native File Download
+
+Native file download is an opt-in, one-shot transfer into an already-open
+workspace. `download_artifact` accepts the MCP host's native file value, the
+`workspaceId` returned by `open_workspace`, and an unused relative destination
+path. It returns only the workspace-relative path and does not create a
+persistent artifact service or reusable artifact ID.
+
+DevSpace accepts only the documented native-file object and trusted OpenAI
+download hosts and redirects. Arbitrary URL strings, local source paths,
+credentials, malformed references, and unknown object fields are rejected.
+
+Absolute paths, traversal, symlinked parents, and existing destinations also
+fail closed. Downloads stream under the configured per-file limit and are
+published without overwrite as owner-only files. DevSpace does not extract or
+execute transferred content.
+
 ## Logs
 
 By default, DevSpace logs requests and tool calls. Shell command previews are
 disabled unless `DEVSPACE_LOG_SHELL_COMMANDS=1`.
 
 Do not enable shell command logging if commands may contain secrets.
+
+Artifact tool logs contain bounded workspace ID, validated hostname,
+workspace-relative output path, byte count, hash, duration, and status metadata.
+`download_artifact` does not log the opaque file value. Raw content, connector
+references, native file IDs, bearer credentials, presigned URLs, host paths,
+temporary paths, and base64 chunks are never included in tool logs or tool
+results.

package.json

@@ -28,7 +28,7 @@
     "dev": "node scripts/dev-server.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],