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:

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

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:

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

  1. 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).
  2. Marked-frame consumers use untrustedForMarkedFrames().
  3. Spawns are argv arrays; shell strings escapeshellarg everything.
  4. Anything config-named that executes is documented as a trust decision, and credentials are not inherited by it by default.
  5. New proc_open sites land in the child-lifetimes roster in the same commit.