#Trust boundary — the fleet security contract
Every SugarCraft library that renders, spawns, or consumes data lives by the same handful of trust rules. This page is the single discoverable home for them: per-lib docblocks implement them, tests pin them, and a finding that violates one of them is a security finding, not a style nit. Report violations via SECURITY.md.
#1. The terminal is a sink — sanitize before you paint
Anything a program writes to a terminal is executed as control
semantics: a raw ESC in a filename, a tool output line, an image
byte stream or a markdown payload is an escape-sequence injection
primitive (rename windows, forge hyperlinks, spoof frames, smuggle
OSC 8 targets).
The contract lives in SugarCraft\Core\Util\Sanitize
(sugar-core/src/Util/Sanitize.php). Pick by destination:
| Sink | Method | What it does |
|---|---|---|
| Plain text into cells, titles, labels | Sanitize::untrusted() |
Strips ANSI (Ansi::strip) and removes C0 controls except TAB/LF/CR, DEL, and the UTF-8-encoded C1 range — byte-wise, so malformed UTF-8 cannot smuggle a survivor past a /u pattern (fail-closed). |
| Text into a user-facing display where bidi/zero-width tricks matter | Sanitize::untrustedForDisplay() |
The above, plus CR/CRLF→LF mapping, plus markInvisibleFormatting() — invisible directional/zero-width codepoints are replaced by visible <U+202E>-style notations instead of being silently eaten. |
| Text into a frame that already carries zone markers or image markers | Sanitize::untrustedForMarkedFrames() |
untrusted() plus a surgical sweep of the two zone sentinels only (§2), preserving legitimate marker traffic. |
| Raw paste / keyboard input from a terminal | Sanitize::untrustedForMarkedFrames() |
InputReader's paste path uses it: a pasted blob is attacker-authored and frame-marked by the time it lands. |
untrusted() deliberately passes the Private Use Area through — the
PUA is our marker arena (§2), not foreign traffic. Cell-level shaping
(cellValue(), controlChars(), visibleControls())
are separate documented tools; do not confuse them with the untrusted
gate.
Dated accepted residual (2026-11, sugar-markdown-068): OSC-8 link
clickability in sugar-markdown is a DENY-list — Renderer::REFUSED_URL_SCHEMES
refuses javascript: / data: / vbscript:; private or
application-owned schemes (event-handler://…) still receive live
targets, inert until some terminal or desktop opener turns them into
click vectors. The allow-list form behind a hypothetical
withAllowedUrlSchemes() was weighed and deferred by owner gate — it
would silently discard links hosts are built on. Per-lib posture: the
sugar-markdown README, "Link safety".
#2. The U+E000–U+F8FF arena
SugarCraft reserves the entire BMP Private Use Area
(constants PUA_BMP_FIRST U+E000 … PUA_BMP_LAST U+F8FF in Sanitize.php)
as its internal marker space:
- Zone sentinels U+E000 / U+E001 (
Sanitize::ZONE_SENTINEL_OPEN/CLOSE):sugar-mouseMark::zone()/Scanwrap clickable overlay zones in these zero-width cells. Because they are PUA codepoints, they pass throughuntrusted()— which is exactly whySanitize::stripZoneSentinels()(a surgicalstr_replaceof the two sentinels only) exists and why untrusted text must be swept withuntrustedForMarkedFrames()before it can enter a marked frame: forged sentinels could otherwise hijack a zone. - Image markers from U+E002 upward (
ImageOverlay::MARKER_BASE = 0xE002,MAX_IMAGES = 6398, topping the arena at exactly U+F8FF — the class lives atsugar-core/src/ImageOverlay.phpand consumers such assugar-gallery'sPosterCardemit its markers): the marker range and the sentinel range are disjoint by construction. Nerd Font / icon glyphs live outside the reserved band. Sanitize::stripPrivateUse()removes the whole BMP PUA via its byte-wise pattern — the safe direction is over-match, and a/upattern would silently match nothing on malformed input, so it is not used.
If your code emits or parses marked frames, you own both sides: sweep untrusted payloads before composition, and never let user data pick its own marker id.
#3. Spawning: argv arrays, never shell strings
proc_open/exectake an argv array whenever the command is machine-composed — canonicalsugar-mcp-client/src/StdioMcpServer.php(:28). A shell string turns/bin/shinto the parent and leaves the real child orphaned and unkillable on teardown; it is also the injection door.- Where a shell string is unavoidable (feature-detection of
user-supplied options, external CLI flags), every interpolation
goes through
escapeshellarg((string) ($field ?? ''))— the repo law in AGENTS.md ("Pass ALL external-CLI flags every invocation via escapeshellarg"). - Child lifetime accounting is guarded repo-wide by
tools/check-child-lifetimes.phpwith a fail-closed roster.
#4. Configuration is trusted input
This is the doctrine with the most surface: config files name
programs to run, so whoever can write the config can execute code
with the application's privileges. The fleet treats config as the
operator's credential surface — analogous to ~/.ssh/config or
authorized_keys — and the security-relevant duty is loud
documentation and isolation, not pretending config is data:
-
MCP stdio servers (
.mcp.json): acommandentry is arbitrary code execution at startup.candy-codemitigates by not handing the stdio child its inherited credentials —candy-code/src/MCP/McpClient.phpstrips credential-shaped environment variables inresolveEnv(), collects them inrecordStrippedSecretEnv(), and answers them through thestrippedSecretEnv()accessor and its one-sentencestrippedSecretEnvNotice(); a server that needs a secret declares${VAR}in itsenvblock (or is named insecretEnvAllowlist). -
Git repository configuration: cloning a hostile repo is not executing it, but its config can be —
diff.externalandtextconvdrivers name programs that run when Git renders a diff.candy-codekeeps read-only Git paths away from repo-supplied drivers (src/Permissions/ReadOnlyCommands.php:88/:1215/:1233,EnvironmentBlockisolation pinned byEnvironmentBlockGitConfigIsolationTest). -
SSH hub options (
sugar-ssh-server): presented key fingerprints are forgeable metadata — see the admin guide, docs/admin/sugar-ssh-server.md. -
SSH endpoint files (
candy-ssh-launcher): the YAML/JSON endpoint config is trusted input — exactly like~/.ssh/configitself.options:entries reach ssh verbatim, and OpenSSH options such asProxyCommand/LocalCommandexecute arbitrary commands at connect time; keep configs0600/0644-owned and do not accept endpoint files from strangers. Untrusted bytes are fenced on the display path: endpoint fields pass throughSanitize::untrustedForDisplay(with a CR/LF/TAB fold) before printing, the filter echo strips control sequences, and no leading-dash value can smuggle an ssh option. The parser refuses malformed input loudly (quote-aware comment stripping, block-map conflicts, empty hosts/options) rather than guessing.
A change that lets an untrusted repo, server, or config drop reach these execution paths without the user's visible consent is a vulnerability.
#5. stderr echoes are terminal writes too
Writing a caught exception message, a subprocess stderr tail, or an HTTP response fragment to STDERR is writing to the same escape-semantics sink as a pane title — the same escape-semantics door. Sanitize (or route through the launch-notice clip) anything that embeds attacker-influenced bytes before it reaches the error stream.
#6. Image and media bytes are untrusted
Poster bytes, sixel/kitty/iterm2 payloads, GIF/WebP dimensions —
parsed by decoders, then rendered as markers, dimensions, or names —
enter the same sinks. They flow through Sanitize gates before
titles/labels are composed from them, and dimension/name caps are
fail-closed, not advisory.
#7. Style renderers pass bytes through untouched
sugar-style is a renderer, not a sanitizer: ESC and OSC sequences in
styled content flow to the terminal unchanged, because its width
arithmetic must see them to keep alignment honest. The caller owns
ingress sanitization (Sanitize::untrusted*). Two narrow doors exist
inside the lib: Style::hyperlink() refuses ids containing ; or :,
and tabs are expanded per tabWidth (default 4) while \r is never
stripped. Wrapping pre-styled content composes at the byte level — an
inner ESC[0m resets the outer style from that point onward, so keep
composition to one pass.
#Quick checklist for a new library
- Every string that can carry foreign bytes and reach a terminal
sink passes a
Sanitize::untrusted*variant at the boundary (parse-don't-validate: once, at ingress). - Marked-frame consumers use
untrustedForMarkedFrames(). - Spawns are argv arrays; shell strings escapeshellarg everything.
- Anything config-named that executes is documented as a trust decision, and credentials are not inherited by it by default.
- New
proc_opensites land in the child-lifetimes roster in the same commit.