* Typed error refactor done; verify passes. Co-authored-by: xlionjuan <[email protected]> * All 6 items done; verify passes. Co-authored-by: xlionjuan <[email protected]> * Review: narrow error-model claims, fix Unwrap coverage, docs sync * All findings fixed; verify passes, tests added, docs synced. Co-authored-by: xlionjuan <[email protected]> * Both changes done; verify + diff check pass. Co-authored-by: xlionjuan <[email protected]> * Docs contract fixed; verify passes clean. Co-authored-by: xlionjuan <[email protected]> * All 3 findings fixed; verify passes, fixture shrunk 44→26. Co-authored-by: xlionjuan <[email protected]> * docs contract: cover parseErrorDocRows guardrails and fix fixture scope claim Add TestParseErrorDocRows_Behavior, table-driven tests proving that a same-named row outside the handler-error section is ignored, a duplicate inside the section fails closed with errDocDuplicateRow, and extraction stops at the next heading. Correct the fixture scope description in errorDocCases and TestDocsMCPTools_ErrorRows: some cases deliberately duplicate rows already pinned verbatim by exact-output unit tests to exercise placeholder normalization, rather than claiming those rows are not duplicated. --------- Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com> Co-authored-by: xlionjuan <[email protected]>
17 KiB
ADR 002: Path Validation Architecture
Status: Active
Last updated: 2026-07-30
Supersedes: Earlier draft with single-layer blocklist
Context
The file_path parameter in create_paste accepts a local filesystem path.
Without proper validation, a malicious or buggy agent could read arbitrary files
via path traversal (../) or by requesting sensitive system paths.
The original implementation had a single isPathAllowed function that checked
both a blocklist and an optional allowlist. This design had several issues:
- No path-traversal detection —
../in the raw input was resolved byfilepath.Cleanbefore the blocklist check, meaning traversals that landed outside blocked paths would succeed silently. - No concept of "sensitive path components" (e.g.
.ssh,.gnupg). Only absolute-path prefixes like/etcwere blocked. - The blocklist was a single list with no distinction between built-in defaults and user additions, making it impossible to have separate error messages or disable one without the other.
- No Windows path separator normalisation.
Decision
We separate path validation into six independent, composable stages, each implemented as its own function. The stages are evaluated in strict order:
file_path (raw user input)
│
├── (1a) PATH TRAVERSAL DETECTION (raw input)
│ Rejects `..` / `../` patterns in the raw input.
│ Independent from all path resolution.
│ Error: "path traversal is not allowed and will always be rejected;
│ do not attempt again"
│
├── (1b) SENSITIVE COMPONENT DETECTION (raw input, before resolution)
│ Checks each path component in the normalized raw path against
│ sensitive patterns: .ssh, .gnupg, .aws, .kube, .docker, .git.
│ Runs BEFORE filepath.EvalSymlinks, so a blocked-component
│ symlink (e.g. .ssh → realssh) is caught before the symlink
│ target hides the component name.
│ Error (typed BlockedComponentError): "file path contains a blocked
│ component and will always be rejected; do not attempt again:
│ <component>"
│ Same component check is repeated on the resolved path as
│ Stage 3b for defense in depth.
│
├── (4a) USER BLOCKLIST — LEXICAL (pre-resolution)
│ User-defined absolute path prefixes, compared against the
│ absolute form of the raw request path before EvalSymlinks.
│ Converts relative paths to absolute via filepath.Abs
│ (no symlink resolution) so that CLI-mode relative paths
│ and MCP-mode absolute paths are treated identically.
│ Catches access through a user-blocked directory that was
│ created or retargeted as a symlink after startup.
│ Error: "file path is in a user-blocked directory and will always
│ be rejected; do not attempt again"
│ Bypassed by ALLOWED_PATHS.
│
├── filepath.EvalSymlinks + filepath.Clean
│
├── (2) ALLOWED_PATHS (user whitelist) — highest priority
│ If configured, the resolved path MUST be under one of these.
│ Path is resolved via filepath.EvalSymlinks before the check.
│ Only absolute paths accepted.
│ When a path matches, continues to (3b) component check.
│ Error: "file path is not under any configured allowed path; ask
│ the user to check ALLOWED_PATHS if this path should be accessible"
│
├── (3) BUILT-IN BLOCKLIST (hardcoded defaults)
│ Two independent sub-checks:
│ (3a) Absolute path prefix match
│ Checks resolved absolute path against:
│ /etc, /proc, /sys, /dev
│ Error: "file path is in a blocked system directory and will
│ always be rejected; do not attempt again: <prefix>"
│ Bypassed by ALLOWED_PATHS (prefixes are location, not
│ sensitivity).
│ (3b) Path component match
│ Checks each path component (directory name) in the
│ resolved path against sensitive patterns like:
│ .ssh, .gnupg, .aws, .kube, .docker, .git
│ Error (typed BlockedComponentError): "file path contains a
│ blocked component and will always be rejected; do not
│ attempt again: <component>"
│ Enforced even inside ALLOWED_PATHS (per B2 exception).
│ This is the defense-in-depth companion to Stage 1b.
│ Disabled by setting WASTEBIN_MCP_DISABLE_BUILTIN_BLOCKLIST=true
│ Both sub-checks share the same disable flag.
│
├── (4b) USER BLOCKLIST — RESOLVED (post-resolution)
│ User-defined list of absolute path prefixes, compared
│ against the resolved canonical path after EvalSymlinks.
│ Relative entries are rejected at startup.
│ Resolved via filepath.EvalSymlinks (matching Stage 2
│ resolution) with fallback to Clean for non-existent
│ absolute paths that may exist later.
│ Error: "file path is in a user-blocked directory and will always
│ be rejected; do not attempt again"
│ Bypassed by ALLOWED_PATHS.
│
└── All passed → file is allowed
Path types by mode
| Mode | file_path input | Base directory |
|---|---|---|
| MCP mode | Absolute path (e.g. /home/user/doc.txt) |
N/A — paths are always absolute |
| CLI mode | Absolute or relative path | Relative paths are resolved against $PWD at invocation time; absolute paths are used as-is |
Both modes apply the same six-stage validation pipeline (Stages 1a, 1b, 4a, 2, 3, 4b). The strict execution order is:
1a → 1b → 4a → EvalSymlinks → 2 → 3 → 4b
Stages 1a (traversal detection), 1b (sensitive component detection),
and 4a (user blocklist lexical) run on the raw input before EvalSymlinks
resolves symlinks. Stage 4a converts relative paths to absolute via
filepath.Abs (which does not resolve symlinks) so that both CLI-mode relative
paths and MCP-mode absolute paths are checked identically. After resolution,
Stages 2–4b check allowlists and blocklists against the resolved absolute path.
CLI mode is not exempt from path validation.
Key design principles
-
ALLOWED_PATHS bypasses the prefix blocklist and user blocklist, but not the sensitive component blocklist (B2 exception). If the resolved path is under an allowed path, the sensitive component blocklist is still checked before accepting the path. This prevents explicit ALLOWED_PATHS entries from accidentally exposing credential directories (
.ssh,.gnupg,.aws,.kube,.docker,.git) while still allowing system-directory prefixes like/etc/nginxto be used. See Breaking change B2 for details. -
Path traversal and sensitive component detection happen BEFORE resolution. The raw input is checked for
..components and for blocked path components (.ssh,.gnupg, etc.) before any path resolution or symlink evaluation. This prevents both..and symlinked blocked components (e.g..ssh→realssh) from bypassing detection, sinceEvalSymlinkswould otherwise resolve the symlink and erase the blocked component name from the path. -
Built-in blocklist vs user blocklist are separate concepts with separate error messages, so the user knows exactly which rule rejected their path.
-
Windows support: All file paths are normalised at the earliest stage:
\is replaced with/before any processing. This ensures that path component matching, traversal detection, and path resolution work uniformly regardless of OS.
Rejected alternatives
- Single blocklist with mixed entries: Rejected because it conflates "sensitive system directory" (absolute prefix) with "sensitive file name" (path component), making error messages vague and the disable semantics ambiguous.
- Path traversal only via filepath.Clean/EvalSymlinks: Rejected
because Clean resolves
..before the blocklist sees the path, making traversal detection dependent on path resolution rather than being an independent guard. - No Windows support: Rejected because the MCP server may run on Windows hosts in future.
Windows strategy
The Go path/filepath package is platform-aware. By normalising \ to
/ at the input stage and using filepath.FromSlash() when interacting
with the OS, we get cross-platform behaviour without platform-specific
code paths.
Key points:
\→/normalisation happens once, before any validation.filepath.Clean,filepath.Abs,filepath.EvalSymlinksuse the OS-native separator internally — no need to change their behaviour.- Path component matching splits on
/(after normalisation), so it works transparently on all platforms.
Consequences
Positive:
- Clear separation of concerns — each stage is independently testable.
- ALLOWED_PATHS cannot be accidentally circumvented by blocklist entries (prefix and user), while the component blocklist provides defence in depth against credential exposure even inside allowed directories.
- Path traversal is caught early, before resolution.
- Cross-platform support without platform-specific code.
Negative:
- More validation code than the original single-function approach.
- Path component matching adds a new class of blocklist entries that could surprise users who expect only absolute-path matching.
- EvalSymlinks in the ALLOWED_PATHS stage requires the file to exist; non-existent files under an allowed path will be rejected.
Implementation notes
- There are six stages (1a, 1b, 2, 3, 4a, 4b). Stage 1b checks the raw, un-resolved path for blocked components, while Stage 3b repeats the same check on the resolved path for defense in depth.
- Stage 4a (user blocklist lexical) runs before
EvalSymlinkson the absolute form of the raw request path. It usesblockedPathEntry.Lexical(the operator's original configured path) to match against. Stage 4b (user blocklist resolved) runs afterEvalSymlinksand usesblockedPathEntry.Resolved(the canonical target). - The
blockedPathEntrytype stores both identities —Lexical(as configured,filepath.Clean) andResolved(afterEvalSymlinks, or equal toLexicalif the path did not exist at startup). This dual identity prevents late-created or retargeted symlinks from bypassing the user blocklist. - Builtin blocklist stages are composed via the
BlocklistStagestype, which holds optionalStageclosures.DisableBuiltinBlocklistis consumed exactly at the point of pipeline construction (newBlocklistStages) — the validation code itself never checks the flag. Stage func(path string) (string, error)is a composable validation step. Stages are composed viaBlocklistStagesstruct fields rather than aPipelinerunner (thePipelinetype was dropped as dead code — stages are always dispatched through theirBlocklistStagesaccessor).- Component matching is consolidated into a single helper:
hasComponentBlockedIn(path string, components []string) (string, bool). The pre-resolutionhasComponentBlocked, the resolved-path-onlyisComponentBlocked, and the component check insideisBuiltinBlockedall delegate to this function. - All stages are pure functions operating on strings/paths — no external dependencies.
- The
Configstruct gains:DisableBuiltinBlocklist boolfield. - The
WASTEBIN_MCP_DISABLE_BUILTIN_BLOCKLISTenv var is parsed as bool. - Built-in blocked path prefixes and blocked path components are defined
as package-level slices:
var builtinBlockedPrefixes = []string{ "/etc", "/proc", "/sys", "/dev", } var builtinBlockedComponents = []string{ ".ssh", ".gnupg", ".aws", ".kube", ".docker", ".git", } - Error sentinel values for each stage, enabling tests to assert the
exact rejection reason. Blocked-component rejections are returned as the
typed
BlockedComponentErrorand blocked-prefix rejections asBlockedPrefixError; all messages follow the unified"<problem>; <next-step guidance>"wording from ADR 005.
Breaking change B2: Component blocklist inside ALLOWED_PATHS
Date: 2026-06-16
ID: B2
Change
Previously, ALLOWED_PATHS bypassed all blocklist stages entirely. After B2, the sensitive component blocklist (Stage 3b) is checked even when a path falls under an allowed directory. Only the system directory prefix blocklist (Stage 3a) and the user blocklist (Stage 4b) remain bypassed.
Rationale
The sensitive component blocklist protects credential files (.ssh,
.gnupg, .aws, .kube, .docker, .git) from accidental exposure. A
user who configures ALLOWED_PATHS=/home/user probably does not intend to
make ~/.ssh/id_rsa readable. Enforcing the component blocklist inside
ALLOWED_PATHS provides defense in depth without breaking legitimate use
cases (e.g., ALLOWED_PATHS=/etc/nginx for reading nginx configs).
Migration
Existing configurations that deliberately place sensitive directories under ALLOWED_PATHS must either:
- Move the sensitive data outside the sensitive directory name, or
- Disable the built-in blocklist entirely with
WASTEBIN_MCP_DISABLE_BUILTIN_BLOCKLIST=true.
Affected stages
| Stage | Bypassed by ALLOWED_PATHS? |
|---|---|
| 1a — Path traversal | ❌ No (unchanged — independent guard) |
| 1b — Component (raw input) | ❌ No (unchanged — independent guard) |
| 4a — User blocklist (lexical, pre-resolution) | ✅ Yes (unchanged) |
| 2 — ALLOWED_PATHS | N/A (this is the bypass enabler) |
| 3a — Prefix blocklist | ✅ Yes (unchanged) |
| 3b — Component blocklist | ❌ No (unchanged) |
| 4b — User blocklist (resolved, post-resolution) | ✅ Yes (unchanged) |
Post-validation TOCTOU protection (openat+O_NOFOLLOW)
While ADR 002 describes the validation pipeline (Stages 1-4), the validation only determines whether a path is allowed. The actual file open is a separate step with its own security properties.
Implementation
After validation passes, the file is opened via the openFileResolved function
in internal/wastebin/open.go:
-
Trusted root:
/is opened withos.O_RDONLY|unix.O_NOFOLLOWas a pinned directory fd. (The root directory cannot be a symlink on Linux, butO_NOFOLLOWis applied defensively.) -
Component walk: Each path component is opened relative to the previous one using
unix.Openat(parentFd, component, O_RDONLY|O_NOFOLLOW|O_CLOEXEC, 0). Intermediate components are verified to be directories viaFstat. -
Result: The final component is returned as an
*os.File. If any component is (or becomes) a symlink,openatreturnsELOOPinstead of following it.
Security model
- Pre-resolution checks (raw input): Stages 1a, 1b, and 4a run on the raw
path before
EvalSymlinks: path traversal detection catches..components that would be normalized away; the sensitive component blocklist catches blocked names (.ssh,.gnupg, etc.) before a symlink target could hide them; and the user blocklist lexical check (Stage 4a) catches paths under a user-blocked alias (including late-created or retargeted symlinks). Stage 4a converts relative paths to absolute viafilepath.Absto ensure CLI-mode paths are checked identically to MCP-mode paths. - Resolved-path validation (EvalSymlinks): After pre-resolution checks
(Stages 1a, 1b, 4a),
filepath.EvalSymlinksresolves all symlinks. The resolved path is then validated against the allowlist and blocklists (Stages 2, 3, 4b), preventing symlink-based evasion of directory-level restrictions. - Post-validation (openat+O_NOFOLLOW): Eliminates TOCTOU symlink-swap attacks where an attacker replaces a validated directory component with a symlink between validation and the file open.
Without the post-validation step, a concurrent attacker could:
- Create a legitimate path
/home/user/allowed/file.txt - Wait for validation to pass
- Replace
/home/user/allowedwith a symlink to/etc/passwd - The file open would follow the symlink and read the blocked path
With openat+O_NOFOLLOW, Step 3 causes ELOOP — the open fails rather than
following the swapped symlink.
Related documents
internal/wastebin/open.go— full implementationCONTEXT.md— project domain context with file-read pipeline descriptiondocs/MCP_TOOLS.md— MCP tool documentation with security notesAGENTS.md— agent behaviour constraints