Documentation
¶
Overview ¶
Package security provides path safety checks and HTTP security middleware for the static web server.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNullByte indicates the URL path contained a null byte. ErrNullByte = errors.New("path contains null byte") // ErrPathTraversal indicates the resolved path escapes the root directory. ErrPathTraversal = errors.New("path traversal detected") // ErrDotfile indicates a path component starts with '.' and dotfiles are blocked. ErrDotfile = errors.New("dotfile access denied") )
Sentinel errors returned by PathSafe.
Functions ¶
func Middleware ¶
func Middleware(cfg *config.SecurityConfig, root string, next fasthttp.RequestHandler, pc ...*PathCache) fasthttp.RequestHandler
Middleware returns a fasthttp.RequestHandler that validates the request path and sets security response headers before delegating to next. It returns 400 for null bytes, 403 for path traversal and dotfile attempts, and 405 for disallowed HTTP methods.
absRoot is computed once at construction time (via filepath.Abs + filepath.EvalSymlinks) and reused for every request, eliminating the per-request syscall overhead. The resolved safe path is stored in the request context via SetUserValue so downstream handlers can retrieve it with SafePathFromCtx instead of calling PathSafe a second time.
An optional *PathCache may be provided to cache PathSafe results so that repeated requests for the same URL path skip the filesystem syscalls entirely. Pass nil (or omit) to disable path caching.
func PathSafe ¶
PathSafe validates and resolves urlPath relative to absRoot. absRoot must already be an absolute, cleaned path (use filepath.Abs once at startup). The function performs the following checks in order:
- Rejects paths containing null bytes.
- Cleans the URL path with path.Clean.
- Verifies the resolved path is inside absRoot.
- Resolves symlinks via filepath.EvalSymlinks and re-verifies the target is still inside absRoot (prevents symlink escape attacks). For paths that do not exist yet (e.g. not-found pages), the unresolved candidate is returned — it has already passed the prefix check.
- Blocks any path component starting with "." when blockDotfiles is true.
On success it returns the absolute filesystem path. On failure it returns one of the sentinel errors (ErrNullByte, ErrPathTraversal, ErrDotfile).
func SafePathFromCtx ¶ added in v1.3.0
func SafePathFromCtx(ctx *fasthttp.RequestCtx) (string, bool)
SafePathFromCtx retrieves the pre-validated absolute filesystem path that security.Middleware stored in the request context via SetUserValue. Returns ("", false) when the value is absent (e.g. in unit tests that bypass the security middleware).
Types ¶
type PathCache ¶ added in v1.3.0
type PathCache struct {
// contains filtered or unexported fields
}
PathCache caches the results of PathSafe so that repeated requests for the same URL path skip the filesystem syscalls (filepath.EvalSymlinks). It is safe for concurrent use.
func NewPathCache ¶ added in v1.3.0
func NewPathCache() *PathCache
NewPathCache creates a new empty PathCache.
func (*PathCache) Flush ¶ added in v1.3.0
func (pc *PathCache) Flush()
Flush removes all entries from the cache. Call this on SIGHUP alongside the file cache flush to ensure stale path mappings don't persist.
func (*PathCache) Lookup ¶ added in v1.3.0
Lookup returns the cached safe path for urlPath, or ("", false) on miss.
Source Files