sv-files

sv-files serves one directory over HTTP as ordinary file resources. Files can be read, written, edited, and deleted; directories can be listed and removed. It is useful anywhere a browser page, script, or service needs a directory-shaped HTTP surface without translating the files into another data model.

Install and run

Node.js 24 or later.

npm install -g @telepath-computer/file-server
sv-files                         # serve the current directory
sv-files /path/to/directory      # or an explicit root

--host (default 127.0.0.1) and --port (default 8765) adjust binding.

The server binds localhost only by default and has no authentication. CORS is wide open (Access-Control-Allow-Origin: *), so browser pages from any origin can call it directly.

Quick start

The URL space mirrors the served directory:

curl http://127.0.0.1:8765/photos/cat.jpg
curl http://127.0.0.1:8765/photos/
curl -X PUT --data-binary @cat.jpg http://127.0.0.1:8765/photos/copy.jpg
curl -X DELETE http://127.0.0.1:8765/photos/copy.jpg

GET and HEAD read files with media types, validators, and byte ranges. Directory GETs return a one-level JSON listing. PUT atomically creates or replaces any file and creates missing parents; PATCH performs an anchored literal edit of a UTF-8 text file; DELETE removes a file or directory tree. OPTIONS provides the CORS preflight response. See spec/files/ for the complete wire contract, CLI, and API.

Confinement

Every request is confined by canonical path beneath the resolved root, and symbolic links are never served. Confinement uses a canonical-path check-then-act: after a path is checked, a concurrent local process could swap an intermediate directory for a symbolic link before the operation. This accepted race is not reachable through sv-files's own operations. If the threat model includes a hostile local process, use kernel-enforced confinement.

Hard links and bind mounts cannot be detected by path resolution and are outside this boundary. Within the root, sv-files reads, writes, and deletes whatever it is asked to; use a narrower served root when a caller should reach less.