docs: security model concept page

[marc0olo]

Summary

• Explains the IC security model from a developer perspective (Diataxis: explanation — no CLI commands)
• Covers execution model: update calls (consensus-verified) vs query calls (single-replica, unverified without certificates)
• Explains canister isolation and the async interleaving pitfall (TOCTOU)
• Defines trust boundaries: what the protocol guarantees (replicated execution, state integrity, message authenticity, isolation) vs what it does NOT (query integrity, code correctness, access control, memory confidentiality)
• Covers boundary nodes and canister_inspect_message limitations
• Developer threat model: missing access control, reentrancy, callback traps, cycle drain, unsafe upgrades, controller risk, unverified builds
• Each threat links to the corresponding security guide for actionable patterns
• Informed by canister-security icskill for accurate pitfall descriptions

Sync recommendation

Upstream-informed: dfinity/portal docs/building-apps/best-practices/trust-in-canisters.mdx, general.mdx; icskills: canister-security

[marc0olo]

Review: Security Model

Blocking issues

1. canister_inspect_message paragraph misplaced under "Boundary nodes" (~line 62). This hook is a canister-level mechanism, not a network-layer concept. Placing it under "Boundary nodes" creates a misleading association and hurts scanability — a developer looking for inspect_message won't look under a heading about boundary nodes. Move it to its own ### canister_inspect_message subsection under "Trust boundaries", or relocate it near the cycle drain attacks section in "Threat model" where it's most actionable.

2. "Unverified builds" section missing link to reproducible builds guide (~line 95). The section says developers should ensure reproducible builds but doesn't link to ../guides/canister-management/reproducible-builds.md, which exists and explains how. Add: See [Reproducible builds](../guides/canister-management/reproducible-builds.md).

Non-blocking improvements

3. Certified variables mentioned but not explained. The content brief calls for covering "certified variables and response verification." The page links to them but never explains the mechanism (canister sets data → subnet signs state tree → client verifies signature). A 1–2 sentence inline explanation in the "Query calls" paragraph would help readers understand the mitigation without clicking through. Appropriate depth for a concept page.

4. Learn Hub TEE article from content brief not incorporated. The stub listed Trusted Execution Environments as source material. Some subnets use SEV-SNP for memory confidentiality, which could nuance the "Memory confidentiality on application subnets" bullet. However, portal sources don't cover this either, so it may be too bleeding-edge. Could be a one-line mention or skipped entirely.

Validation notes

Done:

• All 9 internal link targets verified (ls confirmed each .md file exists)
• No external URLs — all links are internal relative paths with .md extension
• No dfx references, no .mdx/JSX, no code examples (appropriate for concept page)
• Frontmatter complete: title, description, sidebar.order, icskills
• No <!-- TODO --> or <!-- Needs human verification --> flags present
• Technical claims verified against canister-security icskill and portal sources (BFT fault tolerance, query trust model, TOCTOU, inspect_message limitations, callback rollback, freezing threshold, controller risks)
• Content brief coverage: canister isolation, trust boundaries, certified variables (mentioned+linked), boundary nodes, threat model, security guide links — all addressed
• Diataxis: explanation type respected (no CLI commands, no step-by-step)
• Funnel: orient → explain → threats → what's next
• Writing quality: directive, technical, scannable headings, no hand-wavy language, no ambiguous pronouns
• Brownfield compatibility: no anchor/link regressions, consistent with existing sidebar structure

Pending:

• Learn Hub TEE article content not cross-checked (external source, not in .sources/)

[marc0olo]

Feedback addressed:

• Moved canister_inspect_message to its own subsection under "Trust boundaries" (was buried under "Boundary nodes")
• Added link to reproducible builds guide in "Unverified builds" section
• Added brief certified variables explanation in the "Query calls" paragraph
• Added SEV-SNP rollout caveat to the "Memory confidentiality" bullet