docs(cache): document the cache signing trust model

[dmadisetti]

📝 Summary

Docs for the cache signing trust model.

Adds a "Cache signing and trust" section to docs/api/caching.md covering the config surface, the
verification postures, and the sharing-between-machines workflow.

Stack

1. feat(cache): formalize caching config and add signing fields #10523 — config entrypoints + signing fields
2. refactor(cache): introduce SigningPolicy and rename mode to verification #10524 — SigningPolicy, mode → verification
3. feat(cache): sanitize signing config from untrusted layers #10525 — config sanitization (untrusted layers)
4. this PR — docs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
marimo-docs	Ready	Preview	Sep 22, 2026 11:27pm UTC

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

No issues found across 2 files

Architecture diagram

sequenceDiagram
    participant User as User Config
    participant Env as Environment
    participant Proj as Project Config
    participant NB as Notebook Metadata
    participant Marimo as marimo Runtime
    participant Cache as Cache Store
    participant Crypto as Signing/Verification
    
    Note over User,Crypto: Cache Signing Trust Model Architecture
    
    Note over User,Env: Trusted Configuration Sources
    
    User->>Marimo: signing.private_key_path
    User->>Marimo: signing.trusted_signers
    User->>Marimo: cache.verification (off|on|strict)
    Env->>Marimo: cache.verification override
    
    Note over Proj,NB: Untrusted Configuration Sources
    
    Proj->>Marimo: cache.store (allowed)
    Proj--xMarimo: signing (ignored)
    Proj--xMarimo: cache.verification (ignored)
    NB--xMarimo: signing (ignored)
    NB--xMarimo: cache.verification (ignored)
    
    Note over Marimo: Cache Read Flow
    
    Marimo->>Cache: Request cached entry
    Cache-->>Marimo: Return serialized data
    
    alt verification = "on" (default)
        Marimo->>Crypto: Verify signature with trusted key
        Crypto->>Crypto: Check fingerprint whitelist
        alt Trusted & valid signature
            Crypto-->>Marimo: Signature valid
            Marimo->>Marimo: Deserialize with pickle.loads
        else Foreign key or invalid
            Crypto-->>Marimo: Verification failed
            Marimo->>Marimo: Treat as cache miss (recompute)
        end
    else verification = "strict"
        Marimo->>Crypto: Verify signature with trusted key
        Crypto->>Crypto: Check fingerprint whitelist
        alt Trusted & valid signature
            Crypto-->>Marimo: Signature valid
            Marimo->>Marimo: Deserialize with pickle.loads
        else Foreign key or invalid
            Crypto-->>Marimo: Verification failed
            Marimo->>Marimo: Raise exception (fail closed)
        end
    else verification = "off"
        Marimo->>Marimo: Deserialize without verification
        Note over Marimo: Unverified pickle.loads - code execution risk
    end
    
    Note over Marimo: Cache Write Flow
    
    alt verification = "off"
        Marimo->>Cache: Write unsigned entry
    else verification = "on" or "strict"
        Marimo->>Crypto: Sign entry with local Ed25519 key
        Crypto-->>Marimo: Signature attached
        Marimo->>Cache: Write signed entry
    end
    
    Note over Crypto: Missing cryptography package
    alt cryptography not installed
        Note over Marimo,Crypto: verification="on": all reads miss, writes skipped
        Note over Marimo,Crypto: verification="strict": raises
    end

Loading

_{Re-trigger cubic}

[Copilot]

Pull request overview

Adds documentation describing marimo’s cache-signing trust model, including how signing keys are trusted across machines, how cache verification postures behave, and where security-sensitive settings can (and cannot) be configured.

Changes:

• Add a new “Cache signing and trust” section to the caching API docs, covering trust, sharing workflows, and verification postures.
• Update configuration docs to clarify that some security-sensitive settings cannot be overridden by repository-traveling config layers (e.g., pyproject.toml, script metadata, project .marimo.toml).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/guides/configuration/index.md	Clarifies override limits and warns that repository-traveling layers can’t set signing / cache.verification.
docs/api/caching.md	Documents cache signing, key trust, verification modes, and where trust configuration is honored.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/api/caching.md:334

• The verification table implies entries are always signed on write for verification="on"/"strict", but LazyLoader skips writes when no private signing key is available (e.g. a public-key-only verifier). This row should be qualified to avoid suggesting unsigned entries will be written under verifying modes.

| Foreign key, bad signature, or unsigned | served **unchecked** | **miss** — recomputed | **raises** |
| On write | not signed | signed | signed |

docs/api/caching.md:354

• This section says [signing] and [cache].verification are read from user config files only, but earlier in the same doc you describe MARIMO_CACHE_SIGNING_PRIVATE_KEY / MARIMO_CACHE_SIGNING_PUBLIC_KEY as additional (trusted, operator-controlled) ways to configure signing identity/trust. Consider clarifying that the restriction is about repository-controlled config layers, and that environment variables are still honored.

`[signing]` and `[cache].verification` are read from your own user configuration
only — the file at `~/.config/marimo/marimo.toml` or `~/.marimo.toml`. marimo
ignores them in `pyproject.toml`, in notebook script metadata, and in a
`.marimo.toml` that sits inside a project directory.

[akshayka]

Has lazy loader been introduced before in the documentation? You should define it when it is first mentioned. When I read this paragraph, I think "What lazy loader? What is a lazy loader?"

[akshayka]

This is difficult for a user to understand. Instead of saying "Two environment variables set the same thing without …" you should frame this as instructive for a user, based on what they are trying to do.

For example, something like: "You can also using environment variables. Store XXX in the XXX environment variable, and XXX in the XXX environment variable. The environment variables expect keys in XXX form."

[akshayka]

"Restoring a cache entry can involve arbitrary code execution. For this reason, only add a fingerprint if you would run any script that person handed you"