docs: tighten agent guidance toward durable principles#124
Merged
Conversation
benvinegar
force-pushed
the
docs/security-model-guidance
branch
2 times, most recently
from
c3ef33b to
7125c93
Compare
Reframe the security model in AGENTS.md (the agent dev guide, symlinked from CLAUDE.md) and trim a neighbouring bullet, favoring durable principles over code-discoverable detail: - the core isolation rule now states the general invariant — anything agent- or user-produced is untrusted, and content served from a board-origin URL must be sandboxed by the response itself (a sandbox CSP header), since a top-level load bypasses the iframe attribute; - one bullet on the principle that every channel from untrusted content back to the host is gated (can't impersonate the user, exfiltrate, or exhaust the server) — without enumerating the specific mechanisms, which live in code; - the theme bullet drops its per-component implementation trace, keeping the "re-theme every layer; presets go in the registry" principle. No runtime change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
benvinegar
force-pushed
the
docs/security-model-guidance
branch
from
7125c93 to
37591b7
Compare
benvinegar
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
After this security pass, the Architecture invariants in
AGENTS.md(the agent dev guide, symlinked fromCLAUDE.md) needed two things: the new protections documented, and a general pass to favor durable principles over code-discoverable detail — so guidance stays true as the implementation moves and an agent can generalize it to new surfaces/routes rather than pattern-match today's specifics.What changed (docs only, no runtime change)
Core isolation rule — stated generically. Anything agent- or user-produced is untrusted, whatever its kind or route. Content served from a board-origin URL must be sandboxed by the response itself (a
sandboxCSP header), not just the embedding iframe — a top-level load bypasses the attribute. (/s/:idkept only as the current anchor; the rule extends to any future same-origin surface route.)One principle bullet for host-facing channels. Untrusted content reaches the host only through narrow channels (the postMessage bridge, the write API); each is gated so contained content can't impersonate the user, exfiltrate, or exhaust the server — stated by intent, not by naming
bodyLimit/openLink/reply_to_user, which are discoverable in code. A new channel inherits the rule.Trimmed the theme bullet. Dropped the per-component implementation trace (which files read
activeTheme(),viewerThemeCssinjection, thesrcdocrebuild) and kept the durable insight: re-theme every layer (the sandboxed parts bake colors into their string, so they re-render rather than restyle), the terminal is theme-independent, and presets go in the registry, not per-component.What was deliberately left alone
The Map (a navigation index — specifics are the point), the hard constraints (runtime-agnostic / erasable syntax), and the non-obvious gotchas (WebKit ResizeObserver,
JsonFileStorelive objects,SqlStorein-place migration, the exactly-once feedback cursor) — all either navigation, hard rules, or hard-won lessons that aren't discoverable by reading code.Net: the touched sections are leaner and more durable; empty changeset (maintenance), format clean.
🤖 Generated with Claude Code