feat(files-api): SSH-backed write for SaaS workspaces (fixes 500 docker not available)

[HongmingWang-Rabbit]

Summary

Fix 500 failed to write file: docker not available on PUT /workspaces/:id/files/*path for SaaS workspaces (EC2 VMs, not Docker containers).

• New writeFileViaEIC(ctx, instanceID, runtime, relPath, content) in template_files_eic.go
• Uses the same EIC-endpoint + ephemeral-keypair flow as the Terminal tab (terminal.go)
• Remote command: install -D -m 0644 /dev/stdin <abs path> — atomic write + creates missing parent dirs
• Runtime → base-path map: hermes → ~ubuntu/.hermes, langgraph → /opt/configs, default /opt/configs
• WriteFile + ReplaceFiles both detect workspaces.instance_id != '' and route to EIC
• Local/self-hosted Docker path unchanged

Why this fixes the visible bug

Prod screenshot this morning:

API PUT /workspaces/a8af9d79-.../files/config.yaml: 500
{"error":"failed to write file: docker not available"}

SaaS tenants have no Docker to cp into — tenant platform + workspace both run as native processes on EC2. Code previously had no SaaS path at all.

Security

• Absolute path is built from workspaceFilePathPrefix[runtime] (closed map) + filepath.Clean(relPath) — no user-controlled shell escape surface
• validateRelPath rejects absolute paths and surviving .. segments
• Remote command uses install, not shell redirect — no eval
• shellQuote wraps the path as defence-in-depth
• Ephemeral keypair lives in tmpdir for ≤ 30s, wiped on defer
• EIC 60s key validity bounds the blast radius of any leak

Test plan

• go test ./internal/handlers/ -run 'TestResolveWorkspaceFilePath|TestShellQuote' — 10 subtests pass
• go build ./... clean
• Manual: on hongmingwang, PUT /workspaces/:id/files/config.yaml → 200; verify ~ubuntu/.hermes/config.yaml on workspace EC2 shows new content
• Manual: on local self-hosted (docker up), PUT should still route through docker and succeed

Follow-ups (not in this PR)

• Reload hook after save (auto-restart hermes gateway via SSH)
• Tunnel reuse in ReplaceFiles for bulk writes (currently one SSH session per file — ~3s per file)
• Move the runtime → base-path map into the runtime manifest so new runtimes don't require handler changes

🤖 Generated with Claude Code

[molecule-ai]

Review: PR #1702 — feat(files-api): SSH-backed write for SaaS workspaces

APPROVE — Security + correctness verified

Security Analysis

1. Path Traversal (CWE-22 / F1085) — PROTECTED

• resolveWorkspaceFilePath calls validateRelPath(relPath) BEFORE using relPath
• validateRelPath (templates.go:65): checks filepath.IsAbs(clean) + strings.HasPrefix(clean, "..") — blocks both absolute and .. escape attempts
• filepath.Join(base, filepath.Clean(relPath)) — Clean normalizes a/../b to b before Join, preventing mid-path .. bypass
• workspaceFilePathPrefix bases are hardcoded constants — not user-controllable
• Test coverage: TestResolveWorkspaceFilePath_RejectsTraversal confirms ../etc/shadow, /etc/shadow, ./../../etc, a/../../etc all rejected
• shellQuote adds defence-in-depth: single-quote wrapping + backslash-escape, with TestShellQuote confirming correctness

2. SSH Command Injection (CWE-78) — PROTECTED

• sshArgs is a []string array — passed to exec.CommandContext, NOT via shell eval
• absPath is built from a map + Clean() — already traversal-blocked before it reaches the ssh args
• install -D -m 0644 /dev/stdin — stdin redirect prevents any shell interpretation of content
• StrictHostKeyChecking=no + UserKnownHostsFile=/dev/null — acceptable for EIC tunnel to localhost

3. Authorization Scope — CORRECT

• WriteFile and ReplaceFiles routes are gated by WorkspaceAuth middleware (router.go:439-442)
• WorkspaceAuth enforces: per-workspace token OR org-scoped API key OR ADMIN_TOKEN
• instance_id is read from the workspaces DB row, controlled by the provisioner — not caller-supplied
• SaaS branch only activates when instanceID != "" — Docker path unchanged for local containers

4. SaaS Mode vs Local/Dev — CORRECT

• instanceID != "" -> EIC SSH path (SaaS/EC2 workspaces)
• instanceID == "" -> Docker CopyToContainer path (local Docker containers)
• Error on missing instance_id: "workspace has no instance_id — not a SaaS EC2 workspace" — clear and actionable

Architectural Quality

• EIC helpers (sendSSHPublicKey, openTunnelCmd, sshCommandCmd, pickFreePort, waitForPort) are package-level vars, testable by stubbing — same pattern as terminal.go
• Ephemeral keypair: ssh-keygen -t ed25519, stored in temp dir, defer os.RemoveAll(keyDir) on both success and failure paths
• EIC key is only valid for 60s on the instance (AWS enforced) — no persistent key material
• eicFileWriteTimeout = 30s bounds the whole dance; context.WithTimeout cascades to all subprocesses
• region and osUser via env vars — consistent with terminal.go provisioning model

Minor Observations (not blockers)

• ReplaceFiles partial failure: if EIC write fails for file N of M, earlier files are already written with no rollback. Follow-up to track. Not a blocker — HTTP 500 prevents the caller from assuming success.
• No EIC integration test: only unit tests exist (resolveWorkspaceFilePath, RejectsTraversal, shellQuote). Integration test would require AWS credentials + EIC Endpoint. Pre-existing pattern in terminal_test.go — can follow as follow-up.
• Runtime->base-path map: changing base paths without a migration orphans saved files. Acknowledged in code comments and TestResolveWorkspaceFilePath_KnownRuntimes. Not a regression.

Test Coverage

• TestResolveWorkspaceFilePath_KnownRuntimes: 7 cases covering hermes/langgraph/external/default paths, case-insensitive lookup, empty/unknown runtimes
• TestResolveWorkspaceFilePath_RejectsTraversal: 4 cases (absolute, leading .., multi-.., mid-path ..)
• TestShellQuote: 3 cases including embedded single-quote edge case
• All tests on a new template_files_eic_test.go file

Verdict

The SSH-backed write path is well-designed and security-conscious. Path traversal is blocked before the ssh command runs, injection is prevented by array-arg exec (not shell), authorization is correctly scoped to the workspace token, and the EIC ephemeral-key flow mirrors the already-reviewed terminal implementation. No changes requested.