Harden mdcode operations for untrusted Markdown and agent execution

[adrianbrowning]

What to build

Harden mdcode for agent processing of untrusted Markdown. File metadata and execution features must not grant unintended filesystem or shell access.

Acceptance criteria

• File paths from block metadata cannot escape an explicit allowed base directory.
• Absolute paths and traversal attempts fail with actionable errors.
• Shell execution is clearly opt-in and returns structured per-block outcomes.
• Failed source reads or transformations fail the command by default, with an explicit continue-on-error option where appropriate.
• Security boundaries and the trusted-input model are documented and tested.

Blocked by

• Add a versioned machine-readable CLI contract for agents #5

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Enforce filesystem and shell-execution safety boundaries for untrusted Markdown.

Current behavior:
Extract and update join metadata file paths to their working paths without containment validation. Traversal can therefore escape the intended directory. Update logs failed source reads and transformer failures, then continues with stale content. Run executes a caller-provided shell command and prints global console output without a separate acknowledgement or structured CLI outcome.

Desired behavior:
Every metadata-derived file access stays below an explicit allowed base directory. Unsafe paths fail with an actionable error tied to the selected block. Source-read and transform failures stop the command by default. Shell execution remains available only through a clearly acknowledged privileged operation and produces structured per-block outcomes.

Key interfaces:

• Guarded path resolution module — resolve metadata paths against an allowed base and reject absolute paths, traversal escapes, and symlink escapes. Reuse this module for all metadata-derived reads and writes.
• Allowed base — update defaults to the Markdown document directory; --base explicitly selects another base for repository layouts where sources live elsewhere.
• Error policy — source-read and transform failures fail the command; --continue-on-error is the only supported opt-in to collecting failures and continuing.
• Privileged run operation — require --allow-shell in addition to the caller-supplied command. Markdown metadata must never supply a command to execute.
• Per-block results — return structured outcomes for success and failure using the JSON contract from issue Add a versioned machine-readable CLI contract for agents #5.

Acceptance criteria:

• Metadata-derived file paths cannot escape the selected base directory.
• Absolute paths, traversal attempts, and symlink escapes fail before an unsafe read or write.
• Errors identify the affected block name or location and rejected path.
• Update defaults its base to the Markdown document directory and supports --base for an explicit alternate base.
• Source-read and transform failures fail by default; --continue-on-error is explicit and reports every affected block.
• Run requires --allow-shell and never executes a command supplied by Markdown metadata.
• Run returns structured per-block outcomes without terminal formatting under JSON output.
• Documentation states the trusted-input model and tests cover the containment and error-policy cases.

Out of scope:

• Sandboxing or otherwise trusting arbitrary commands explicitly supplied by the caller.
• Type-checking or validating the code inside a Markdown block.
• The shared JSON envelope itself, which is issue Add a versioned machine-readable CLI contract for agents #5.

Verification status:
Confirmed by code inspection: extract and update use unchecked path joining, while update and transforms log errors and continue. This issue is blocked by #5 for the structured result contract.