AGENTS.md

1# Package Security & Test Guidelines
2 
3**Last Updated:** April 9, 2026
4 
5## Archive Extraction Security
6 
7- Always validate ZIP entry names with a safe join. Reject absolute paths, Windows drive or volume paths, and any entry that escapes the target directory after cleaning.
8- ZIP entry names use slash semantics, not host OS semantics: validate with `path.Clean` and `path.IsAbs`, reject backslashes, and use `path.Base` for hidden-name checks.
9- Convert ZIP names to OS paths only at write time with `filepath.FromSlash(...)`.
10- Enforce destination containment with `filepath.Rel(...)` rather than string-prefix checks.
11- Enforce per-file and total-size budgets to prevent resource exhaustion.
12- Skip OS metadata directories such as `__MACOSX` and reject suspicious names.
13- Keep tests for absolute and volume path rejection, traversal skipping, `__MACOSX` skipping, size limits, directory creation, and safe nested extraction.
14- The current implementation lives in `pkg/fs/zip.go` via `Unzip` and `UnzipFile`; containment is enforced by the shared `SafeJoin` helper in `pkg/fs/join.go` (also used by the WebDAV sync client and server upload handler).
15 
16## HTTP Download Security
17 
18- Use `pkg/http/safe` and `safe.Download(destPath, url, *safe.Options)` instead of ad-hoc `net/http` download code.
19- Default policy allows only `http` and `https`, enforces timeouts and max size, writes to a `0600` temp file, then renames into place.
20- For SSRF protection, set `AllowPrivate=false` unless a test explicitly needs private or loopback addresses.
21- Validate redirect targets and the final connected peer IP.
22- Prefer an image-focused `Accept` header for image downloads: `"image/jpeg, image/png, */*;q=0.1"`.
23- Use `internal/thumb/avatar.SafeDownload` for avatars and other small images; it applies a 15-second timeout, a 10 MiB cap, and `AllowPrivate=false`.
24- Tests using `httptest.Server` on `127.0.0.1` must set `AllowPrivate=true`.
25- Keep size budgets small and rely on `io.LimitReader` plus `Content-Length` prechecks.
26 
27## Focused Package Test Runs
28 
29- Filesystem copy, move, and unzip helpers: `go test ./pkg/fs -run 'Copy|Move|Unzip' -count=1`
30- Media helpers: `go test ./pkg/media/... -count=1`
31 
32