Extension Integrity

Extension Integrity

Optional install-time and load-time integrity controls for extensions — signing, checksums, pinning. v1 ships these as opt-in hardening, not as a runtime sandbox. See Extension Isolation for why runtime isolation is not in v1.

---

Intent

Trust (per Project Trust and Trust Model) is binary: loaded or not. Integrity tells the user what they are trusting. An extension whose bytes silently change between sessions has slipped past the first-run prompt. Integrity controls make that drift visible.

---

What integrity buys

Surface	Question answered
Checksum	Are the bytes the same as last session?
Signature	Who vouches for these bytes?
Version pin	Are we running the version we agreed to?

Integrity does not replace trust. A signed extension from a new publisher is still untrusted until the user accepts it.

---

v1 posture

flowchart LR
    Install[install or discover] --> Opt{integrity<br/>configured?}
    Opt -->|no| Direct[load as-is]
    Opt -->|checksum| Hash[compute + compare]
    Opt -->|signature| Verify[verify signature]
    Opt -->|pin| Check[compare version]
    Hash --> Load[register]
    Verify --> Load
    Check --> Load
    Hash -.->|mismatch| Fail[validation diagnostic<br/>hard-fail on critical tier]
    Verify -.->|invalid| Fail
    Check -.->|drift| Fail

Loading

• Default posture. No integrity check; extensions load once validation passes.
• Opt-in. The user enables checksums, signature verification, or pinning per extension or globally.
• Enforcement. On mismatch, the Validation Pipeline emits a diagnostic. The category's severity rules decide hard-fail vs warn-and-skip.

---

Checksums

A checksum file (managed under ~/.stud/integrity/ at user opt-in) records the expected digest of each extension's declared manifest bundle.

• Computed at install or on explicit "accept current bytes" action.
• Compared at session start.
• A mismatch emits an IntegrityChecksumMismatch diagnostic.

Checksums catch silent edits (especially to ~/.stud/ extensions a user installed months ago and forgot about).

---

Signatures

For publishers that sign releases:

• The extension declares a public-key identity in its manifest.
• A signature over the manifest bundle is shipped alongside.
• At load, core verifies the signature against the declared key.
• First-sight: the first signature observed becomes the accepted key (TOFU — trust on first use), recorded in the integrity store. Rotation requires user confirmation.

Signatures are not a prerequisite for loading an extension in v1. The out-of-box default is "no signature required." Users opting in accept slightly more friction for higher assurance.

---

Version pinning

An extension is declared in user config with a pinned contractVersion. At load, if the discovered version does not match, the Validation Pipeline emits ContractVersionMismatch. Core does not auto-upgrade.

Pinning is the user's tool for preventing an extension from silently upgrading to a breaking contract version.

---

Where integrity lives

Integrity configuration lives under ~/.stud/ (user-global) or <cwd>/.stud/ (project). It is not session-specific state and is not stored in the session manifest.

~/.stud/integrity/
  checksums.json           # one line per extension
  keys/                    # accepted public keys per publisher
  pins.json                # per-extension version pins

The wiki does not fix the on-disk shape; the point is that integrity is durable across sessions and reviewable.

---

Relation to MCP

MCP servers declared in mcp.json are executables. Integrity here means:

• Pinning by path + checksum.
• Optional signature verification if the server ships a signed bundle.
• Warning the user when an mcp.json entry references a path outside the project or global scope.

See MCP Trust.

---

Out-of-box defaults

Control	Default
Checksums	Off.
Signature verification	Off.
Version pinning	Off (extensions load whatever version is discovered).
MCP server integrity	Off.

These defaults favor friction-free onboarding. Hardened deployments flip them on.

---

Audit

Every integrity check emits an audit event on success and failure:

• IntegrityChecked with result = ok | mismatch | missing.
• IntegrityEnforcementFailed when a mismatch caused a load failure.

See Audit Trail.

---

Related pages

• Trust Model
• Project Trust
• Extension Isolation
• MCP Trust
• Validation Pipeline
• Audit Trail