Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,19 @@ on:
pull_request:
branches: ["master"]


permissions: read-all

jobs:
ci:
permissions:
contents: read
id-token: write
# Reusable CI lives in 1set/meta — the single source of truth for every
# Star* module's pipeline. Pinned to a commit SHA for supply-chain safety;
# bump the pin when meta's workflow changes (Dependabot github-actions can
# automate this).
uses: 1set/meta/.github/workflows/go-ci.yml@5d86667e7264f012655dab2644dfa44e09597445
uses: 1set/meta/.github/workflows/go-ci.yml@496f38088eff1a37bae1b43d158146a8a9d83a37
with:
go-floor: "1.19"
doc-coverage: true
Expand Down
15 changes: 11 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,11 @@ back. Every script-visible thing is a Go struct exposed through a thin
`fs.ValidPath` (the barrier that confines traversal, also satisfies CodeQL's
path-injection query) + dotfile/`@eaDir` rejection (`.well-known` carve-out) +
an `EvalSymlinks` real-path check (`openWithin`) that blocks symlink escape.
Mount registry is copy-on-write so the serve path reads it lock-free. Tests in
Mount roots must exist and be beneath the server's captured working directory
unless the host enables `allow_unsafe_file_paths`. Registration resolves and
copies each root; later cwd changes or symlink retargeting cannot select a
different root. Mount registry is copy-on-write so the serve path reads it
lock-free. Tests in
`static_test.go` (source-shaped).
- **`errors.go`** — `ErrorResponse`, `ErrorHandlerRegistry` (status code →
Starlark handler), invoked from `applyResponse`/`NoRoute`/`NoMethod`.
Expand All @@ -109,7 +113,8 @@ back. Every script-visible thing is a Go struct exposed through a thin

## Invariants / hardening (preserve when editing)

The iron rule is **opt-in / default-off so old scripts run identically**.
Preserve documented defaults; security boundary corrections must explicitly
document their behavior changes.

1. **Default-deny public bind.** `create_server` defaults `host` to `localhost`;
`Start()`/`Run()` call `checkBindAllowed`, which refuses any non-loopback
Expand All @@ -133,8 +138,10 @@ The iron rule is **opt-in / default-off so old scripts run identically**.
into `bodyData` so `body()`/`json()`/`form()`/middleware can all read it;
`form()` re-wraps the cached bytes. Don't re-read `c.Request.Body` directly.
6. **Backward compatibility.** `NewModule()` keeps every historical default
(localhost bind allowed, public bind denied, 32 MiB body cap). Any new safety
lever must default to the historical behavior.
(localhost bind allowed, public bind denied, 32 MiB body cap). File responses
and static mounts share a fixed host root captured at server
creation. Outside static roots now require the existing host-only
`allow_unsafe_file_paths` opt-out; missing roots must be created before mounting.

## Test organization

Expand Down
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,10 +87,10 @@ Module builtins (`load("web", …)`):
- `json_response(data, status?, headers?)` — JSON response.
- `html_response(content, status?, headers?)` — HTML response.
- `text_response(text, status?)` — plain-text response.
- `file_response(filepath, content_type?, filename?)` — serve a file (optionally as a download). Confined to the working directory by default; set `allow_unsafe_file_paths` to serve outside it.
- `file_response(filepath, content_type?, filename?)` — serve a file (optionally as a download). Confined to the working directory captured when the server is created; set `allow_unsafe_file_paths` to serve outside it.
- `send_file(filepath, content_type?)` — serve a file (same working-directory confinement as `file_response`).
- `send_data(data, filename, content_type?)` — send in-memory data as a download.
- `static_dir(root, index?, spa?, cache_control?)` — read-only static-file root for `srv.static` (safe by default: no traversal/dotfiles/listing).
- `static_dir(root, index?, spa?, cache_control?)` — read-only static-file root for `srv.static`; mounts require an existing directory under the server's captured working directory by default (no traversal/dotfiles/listing).
- `redirect(location, status?)` — redirect response.
- `error_response(status, message?)` — error response.
- `api_key_auth(keys?, header?, query_param?)` — API-key authenticator.
Expand Down Expand Up @@ -130,7 +130,10 @@ The module's options (`host`, `port`, `read_timeout`, `write_timeout`,
per-option `get_<key>` / `set_<key>` accessor builtins, and serve as defaults for
the servers the module creates. Two opt-in levers default to off: `allow_public_bind`
lets the host expose a server beyond loopback, and `allow_unsafe_file_paths` lets
`file_response`/`send_file` serve files outside the working directory. Both
file responses and static mounts use paths outside the server's captured working
directory. Relative file responses remain anchored there even if the process
changes directory later. Static mounts bind to a resolved directory at mount
time; changing its original symlink alias cannot redirect the mount. Both
`allow_unsafe_file_paths` and `max_body_size` are **host-only** (no `set_<key>`
builtin) — an untrusted script cannot weaken these safety guards; set them via
Go config or `WEB_*`. See the
Expand Down
14 changes: 14 additions & 0 deletions codecov.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
coverage:
status:
project:
default:
target: auto
threshold: 0%
patch:
default:
target: 100%
threshold: 0%
comment:
layout: "diff, flags, files"
require_changes: false
hide_project_coverage: false
20 changes: 16 additions & 4 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,10 @@ and `Content-Type` by extension all work without the script handling them; an

**Parameters:**

- `root` (string): The directory to serve. Must not be empty.
- `root` (string): The directory to serve. Must not be empty. At mount time it
must exist and resolve to a directory under the working directory captured
when the server was created. The host-only `allow_unsafe_file_paths` option
permits an outside root; it does not disable confinement within that mount.
- `index` (string or list of strings, optional): Directory default pages, tried
in order (default: `["index.html", "index.htm"]`). An empty list disables
index pages (directories then 404).
Expand All @@ -252,7 +255,10 @@ and `Content-Type` by extension all work without the script handling them; an

**Returns:** A `web.StaticDir` handle (pass it to `srv.static`).

**Safety (always on, no opt-out):**
The mount is bound to the resolved physical root at registration. Later cwd
changes or retargeting of the supplied symlink alias do not select a new root.

**Safety within an accepted mount (always on, no opt-out):**

- **No path traversal.** The request path is cleaned and anchored under `root`;
`..` can never escape, and the resolved path is re-checked against the
Expand Down Expand Up @@ -644,7 +650,8 @@ explicit route registered on the server takes precedence. A request under

- `prefix` (string): URL prefix to mount under (`/` serves the whole site).
- `dir` (`web.StaticDir`): the handle returned by `static_dir(...)`.
- **Returns:** `None`.
- **Returns:** `None`. A missing, non-directory or unauthorized root raises an
error without registering the mount. Create the directory before mounting.

```python
srv.static("/assets", static_dir("./public/assets", cache_control="max-age=3600"))
Expand Down Expand Up @@ -898,6 +905,11 @@ lives in the sandbox runtime layer; this is the module-local guardrail.

## Configuration

The server captures the physical working directory at creation. Confined
`file_response`, `send_file`, direct `file_path` assignments and custom error
responses resolve relative paths against that fixed root. Changing cwd later
does not widen this boundary.

Each module configuration option is exposed to scripts as a pair of generated
accessor builtins (loaded from the `web` module alongside the functions above):

Expand Down Expand Up @@ -932,7 +944,7 @@ them from Go configuration or the corresponding `WEB_*` environment variable.
| `debug_mode` | `get_debug_mode` | `set_debug_mode` | bool | `WEB_DEBUG_MODE` | `false` | Enable Gin debug logging |
| `server_header` | `get_server_header` | `set_server_header` | string | `WEB_SERVER_HEADER` | `Starlark-Web/1.0` | Custom `Server` header value |
| `allow_public_bind` | `get_allow_public_bind` | `set_allow_public_bind` | bool | `WEB_ALLOW_PUBLIC_BIND` | `false` | Allow binding to a non-loopback (public) address |
| `allow_unsafe_file_paths` | `get_allow_unsafe_file_paths` | _(host-only)_ | bool | `WEB_ALLOW_UNSAFE_FILE_PATHS` | `false` | Allow `file_response`/`send_file` to serve paths outside the working directory |
| `allow_unsafe_file_paths` | `get_allow_unsafe_file_paths` | _(host-only)_ | bool | `WEB_ALLOW_UNSAFE_FILE_PATHS` | `false` | Allow file responses and static mounts outside the server's captured working directory |

**Example:**

Expand Down
43 changes: 19 additions & 24 deletions server.go
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ type Server struct {
maxBodySize int64
serverHeader string
allowPublicBind bool // When false, refuse to bind to a non-loopback address
allowUnsafeFilePaths bool // When false, confine file_response/send_file to the working directory
allowUnsafeFilePaths bool // Host opt-out from the fileRoot boundary
fileRoot string // Physical working directory captured at server creation; empty denies file access
middleware []*Middleware // All middleware with path patterns
errorHandlers *ErrorHandlerRegistry
ginMiddlewareAdded bool // Flag to prevent multiple Gin middleware additions
Expand All @@ -78,6 +79,7 @@ func newServer(module *Module, host string, port int) *Server {
serverHeader := module.ext.GetString(configKeyServerHeader)
allowPublicBind := module.ext.GetBool(configKeyAllowPublicBind)
allowUnsafeFilePaths := module.ext.GetBool(configKeyAllowUnsafeFilePaths)
fileRoot, _ := workingDirReal()

// Set gin mode - ensure release mode by default to avoid debug output
if debugMode {
Expand Down Expand Up @@ -114,6 +116,7 @@ func newServer(module *Module, host string, port int) *Server {
serverHeader: serverHeader,
allowPublicBind: allowPublicBind,
allowUnsafeFilePaths: allowUnsafeFilePaths,
fileRoot: fileRoot,
middleware: make([]*Middleware, 0),
errorHandlers: NewErrorHandlerRegistry(),
ginMiddlewareAdded: false,
Expand Down Expand Up @@ -498,14 +501,11 @@ func (s *Server) applyResponse(c *gin.Context, response *Response) {

// serveConfinedFile serves a path a script asked to return (via file_response /
// send_file / a directly-set Response.file_path). Unless allow_unsafe_file_paths
// is set, it opens the file first and then validates the open descriptor: it
// must be a regular file — never a directory, which http.ServeFile would turn
// into an index page or listing, nor a FIFO/device that could block — whose real
// path stays under the process working directory. It is then served from that
// same descriptor, which narrows the check-to-serve TOCTOU window and stops an
// untrusted script from reading arbitrary host files or echoing a request
// parameter straight into a file read. (Static mounts have their own confinement
// in static.go.) Returns true when it wrote a response.
// is set, it resolves and checks the path before opening: only regular files
// under the physical working directory captured at server creation are allowed.
// Directories and special files are rejected, and the opened descriptor is used
// for serving. Static mounts use the same host root in static.go. Returns true
// when it wrote a response.
func (s *Server) serveConfinedFile(c *gin.Context, p string) bool {
if s.allowUnsafeFilePaths {
c.File(p) // opt-out: unrestricted serving (historical behavior)
Expand All @@ -531,24 +531,22 @@ func (s *Server) serveConfinedFile(c *gin.Context, p string) bool {
}

// resolveConfinedFile resolves p to a symlink-free physical path, confirms it is
// a regular file under the working directory, and returns it. Resolving and
// checking BEFORE any open means an outside target is never opened — so a
// a regular file under the server's captured working directory, and returns it.
// Resolving and checking BEFORE any open means an outside target is never opened — so a
// FIFO/device outside the root cannot block os.Open — and a directory (which
// http.ServeFile would list) is rejected.
func (s *Server) resolveConfinedFile(p string) (string, bool) {
if strings.TrimSpace(p) == "" {
if strings.TrimSpace(p) == "" || s.fileRoot == "" {
return "", false
}
abs, err := filepath.Abs(p)
if err != nil {
return "", false
if !filepath.IsAbs(p) {
p = filepath.Join(s.fileRoot, p)
}
real, err := filepath.EvalSymlinks(abs)
real, err := filepath.EvalSymlinks(p)
if err != nil {
return "", false
}
realRoot, ok := workingDirReal()
if !ok || !withinRoot(realRoot, real) {
if !withinRoot(s.fileRoot, real) {
return "", false
}
// real is symlink-free, so Lstat == Stat: reject a directory or FIFO/device.
Expand All @@ -559,15 +557,12 @@ func (s *Server) resolveConfinedFile(p string) (string, bool) {
}

// workingDirReal returns the symlink-resolved process working directory.
func workingDirReal() (string, bool) {
func workingDirReal() (string, error) {
root, err := os.Getwd()
if err != nil {
return "", false
}
if rr, err := filepath.EvalSymlinks(root); err == nil {
return rr, true
return "", err
}
return root, true
return filepath.EvalSymlinks(root)
}

// Server lifecycle methods
Expand Down
98 changes: 98 additions & 0 deletions server_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ package web
// - server builtin arg validation: route / error_handler / use_for / group errors
// - lifecycle errors: stop()/double-start guards
// - wrapHandler + applyResponse: request->handler->response bridge via httptest
// - file responses: complete entrypoint contract and fixed host root

import (
"net"
Expand Down Expand Up @@ -658,3 +659,100 @@ def handler(req):
t.Errorf("body = %q, want the custom error handler body", rec.Body.String())
}
}

// TestServerFileRootSnapshot exercises the complete response path after cwd
// changes, including a file returned by a custom error handler.
func TestServerFileRootSnapshot(t *testing.T) {
root, outside := t.TempDir(), t.TempDir()
for dir, content := range map[string]string{root: "inside", outside: "outside"} {
if err := os.WriteFile(filepath.Join(dir, "probe.txt"), []byte(content), 0o600); err != nil {
t.Fatal(err)
}
}
useWorkingDir(t, root)
t.Setenv("WEB_ALLOW_UNSAFE_FILE_PATHS", "false")
m := NewModule()
srv := newServer(m, "localhost", 0)
if err := os.Chdir(outside); err != nil {
t.Fatal(err)
}
if err := srv.RegisterStatic("/", staticDirFor(outside, false)); err == nil {
t.Error("cwd change widened static root authorization")
}
paths := []string{"probe.txt", filepath.Join(root, "probe.txt"), filepath.Join(outside, "probe.txt")}
if volume := filepath.VolumeName(root); volume != "" {
paths = append(paths, volume+"probe.txt")
}
for _, entry := range []string{"file_response", "send_file", "file_path", "error_handler"} {
for _, path := range paths {
t.Run(entry+"/"+path, func(t *testing.T) {
response := &Response{StatusCode: 200, FilePath: path}
if entry == "file_response" || entry == "send_file" {
fn := m.fileResponse
if entry == "send_file" {
fn = m.sendFile
}
v, err := starlark.Call(&starlark.Thread{}, starlark.NewBuiltin(entry, fn), starlark.Tuple{starlark.String(path)}, nil)
if err != nil {
t.Fatal(err)
}
response = v.(*ResponseWrapper).response
}
if entry == "error_handler" {
globals, err := starlark.ExecFile(&starlark.Thread{}, "error.star", "def handler(req):\n return response\n", starlark.StringDict{"response": NewResponseWrapper(response)})
if err != nil {
t.Fatal(err)
}
srv.errorHandlers.RegisterHandler([]int{404}, globals["handler"].(starlark.Callable))
response = &Response{StatusCode: 404}
}
c, rec := newGinContextForTest(http.MethodGet, "/probe")
srv.applyResponse(c, response)
if path == filepath.Join(outside, "probe.txt") || (filepath.VolumeName(path) != "" && !filepath.IsAbs(path)) {
if rec.Code != http.StatusNotFound || strings.Contains(rec.Body.String(), "outside") {
t.Errorf("outside file served: %d %q", rec.Code, rec.Body.String())
}
} else if rec.Code != 200 || rec.Body.String() != "inside" {
t.Errorf("fixed root response: %d %q", rec.Code, rec.Body.String())
}
})
}
}
}

func TestServerMissingFileRootDeniesAccess(t *testing.T) {
srv := newServer(NewModule(), "localhost", 0)
srv.fileRoot = "" // cwd resolution failed at construction
if _, ok := srv.resolveConfinedFile("go.mod"); ok {
t.Error("missing host root must deny file responses")
}
if err := srv.RegisterStatic("/", staticDirFor(".", false)); err == nil {
t.Error("missing host root must deny static mounts")
}
}

func TestServerUnavailableWorkingDirectory(t *testing.T) {
root := t.TempDir()
useWorkingDir(t, root)
if err := os.Remove(root); err != nil {
t.Skipf("platform cannot remove current directory: %v", err)
}
srv := newServer(NewModule(), "localhost", 0)
if srv.fileRoot != "" {
t.Errorf("unavailable cwd yielded a file grant: %q", srv.fileRoot)
}
}

func BenchmarkConfinedFileResponse(b *testing.B) {
srv := newServer(NewModule(), "localhost", 0)
response := &Response{StatusCode: 200, FilePath: "go.mod"}
b.ReportAllocs()
b.ResetTimer()
for i := 0; i < b.N; i++ {
c, rec := newGinContextForTest(http.MethodGet, "/f")
srv.applyResponse(c, response)
if rec.Code != 200 {
b.Fatalf("status = %d", rec.Code)
}
}
}
27 changes: 25 additions & 2 deletions static.go
Original file line number Diff line number Diff line change
Expand Up @@ -148,12 +148,35 @@ func (mt *staticMount) matchPrefix(urlPath string) (string, bool) {
}

// RegisterStatic mounts a StaticDir at prefix. Most-specific (longest) prefix
// wins when several mounts overlap.
// wins when several mounts overlap. The root must be an existing directory
// beneath the physical working directory captured at server creation, unless
// the host enabled allow_unsafe_file_paths. Its resolved path is fixed at mount
// time, so a later cwd change or retargeting of the original alias cannot grant
// access to a different directory.
func (s *Server) RegisterStatic(prefix string, sd *StaticDir) error {
if sd == nil {
return fmt.Errorf("static: dir must not be nil")
}
mt := &staticMount{prefix: normalizeStaticPrefix(prefix), sd: sd}
if sd.rootAbs == "" {
return fmt.Errorf("static: root must not be empty")
}
real, err := filepath.EvalSymlinks(sd.rootAbs)
if err != nil {
return fmt.Errorf("static: cannot resolve root: %w", err)
}
if !s.allowUnsafeFilePaths && (s.fileRoot == "" || !withinRoot(s.fileRoot, real)) {
return fmt.Errorf("static: root is outside the server's working directory")
}
if info, err := os.Stat(real); err != nil || !info.IsDir() {
return fmt.Errorf("static: root must be an existing directory")
}
// Bind an immutable mount copy to the checked physical directory, not to
// the caller's handle or its possibly mutable symlink alias.
bound := *sd
bound.rootAbs, bound.realRoot = real, real
bound.fsys = os.DirFS(real)
bound.index = append([]string(nil), sd.index...)
mt := &staticMount{prefix: normalizeStaticPrefix(prefix), sd: &bound}
s.mu.Lock()
// Copy-on-write: build a fresh slice rather than appending/sorting in place,
// so the lock-free iteration in tryServeStatic (which copies only the slice
Expand Down
Loading
Loading