msd-core/docs/explanation/the-capability-trust-model.md

The capability trust model

Status: Implemented in ADR-1244 Phase 4 (gsd-core/bin/lib/capability-trust.cjs, capability-lifecycle.cjs). This document is the honest explanation of why GSD trusts third-party capabilities the way it does — including what it does not protect against.

GSD capabilities can ship the same executable artifacts GSD itself ships — hook scripts, command modules, and (for third parties) MCP server declarations. That is full first-party parity, chosen deliberately (epic #1244, alternative 2). Parity means a third-party capability is, in the limit, arbitrary code you have invited into your agent runtime. This page explains the barrier GSD puts in front of that invitation, and why the barrier is consent + integrity + reversibility rather than a sandbox.

Why there is no sandbox (Ask #1)

ADR-857 D8 originally earned "no sandbox" on a declarative-only premise: capabilities were data, not code. This feature reverses that premise, so the justification must be re-derived on grounds that survive third-party code execution. It is:

GSD has no process boundary to interpose. A capability's executable surfaces all run inside the host agent runtime's own trust context:

• hook scripts run as the runtime's configured hook commands (your shell, your permissions);
• command modules are require()'d directly into the GSD CLI's own Node process;
• MCP servers are spawned by the host runtime, not by GSD.

GSD never forks a sandboxed child to run any of this. It could not meaningfully do so: the runtime loads hooks and MCP servers itself, and a command module is in-process by definition. A sandboxTier enum on capabilities that GSD does not actually enforce would be security theater — worse than nothing, because it implies a boundary that isn't there.

The runtime descriptor's existing sandboxTier axis (none | codex-agent-sandbox, runtime-config-adapter-registry.cts) is the runtime's own sandbox over everything it executes — capability code included. That sandbox keeps applying. But it belongs to the runtime (e.g. Codex's workspace-write), not to GSD, and GSD does not extend or simulate it.

So the barrier GSD owns is the same posture the Obsidian and VS Code marketplaces settled on after their own supply-chain incidents:

1. No execution at install. Staging is copy-only. npm sources use --ignore-scripts; there is no postinstall. Installing a capability never runs its code.
2. Integrity before extraction. Tarball sources verify a sha512 digest over the fetched bytes before anything is written to the install root; a mismatch aborts.
3. Disclosure + explicit consent. Every executable surface a capability declares is disclosed at install, and installing one that ships any executable surface requires explicit consent. Declining aborts cleanly, writing nothing.
4. Namespace reservation. Third parties cannot claim the gsd-, gsd-core-, or anthropic- id prefixes, so a hostile capability cannot impersonate a first-party one.
5. Reversibility. The ledger records exactly what each install wrote; remove deletes exactly those files and surgically strips exactly the shared-config entries the capability added, touching nothing the user owns.

Consent is meaningful precisely because (1)–(2) guarantee nothing has run yet when you are asked, and (4)–(5) guarantee you can fully undo it. That is the trade GSD makes instead of a sandbox it cannot honestly provide.

strictKnownRegistries default (Ask #4a)

capabilities.strict_known_registries gates install itself, not merely auto-update.

Value	Meaning
unset / null (default)	External installs (git / npm / tarball / registry) are allowed, each still passing the consent + integrity gate. Local filesystem installs always allowed.
[] (explicit empty array)	Blocks all external installs — managed/enterprise lockdown. Local installs only.
["github.com", "registry.example.com"]	Allowlist — only sources whose host matches an entry (exact host or a subdomain of it) are permitted.

The default is permissive-with-consent, not Obsidian-style restricted-by-default. The epic deliberately chose decentralized URL/git distribution over a curated-registry gate (alternative 3), so the consent prompt is the default barrier and full lockdown is one config key away. The allowlist match is host-based, not substring: github.com does not match evilgithub.com.

The npm transitive-dependency boundary (Ask #4b)

integrity (sha512) pins only the top-level fetched artifact — the tarball, or the output of npm pack. It does not pin the resolved dependency graph.

--ignore-scripts and copy-only staging stop install-time execution (no postinstall). But when a capability's command module is later require()'d, Node resolves and executes that module's transitive dependency tree, and sha512 says nothing about those packages — they can be mutable or compromised independently of the pinned top artifact. This is exactly the Wiz / VS Code supply-chain lesson.

For the npm source kind, therefore: a green integrity check means "the package tarball is the one you pinned," not "every line of code that will run is the code you reviewed." Authors who want a stronger guarantee should vendor their dependencies into the capability or ship a lockfile; the consent prompt always discloses when a capability ships command modules, which is the surface through which transitive code reaches your process.

Where third-party code runs: command dispatch (Phase 5 / D7)

A capability may declare a command family (commands: [{ family, module, router }]). When you run gsd-tools <family> …, GSD dispatches it by require()-ing the named module's router function. This is the one place a third-party capability's own code executes in the GSD CLI process, so it is gated twice:

1. Consent. A third-party family is dispatchable only if its capability has a committed ledger entry — i.e. you installed it through the lifecycle (and, for executable surfaces, consented). The loader records a dispatchable "command root" only for committed (non-_pending) capabilities; a bundle merely present on disk with no ledger entry still contributes its declarative surfaces (skills/agents/config) but is not command-dispatchable.
2. Confinement. The router module is loaded from the capability's own install root — a bare .cjs basename, realpath-confined to that directory, rejecting .. traversal and symlink escape. A capability can never reach code outside its own bundle, and a first-party command (graphify/intel/audit, which ship in bin/lib/) can never be shadowed by a third-party one.

The project-scope trust boundary (be honest about it)

Capabilities can be installed globally (under your home, $GSD_HOME/.gsd/capabilities/) or project-scoped (under a repository, <projectRoot>/.gsd/capabilities/). The consent signal is the ledger, and the project-scope ledger (<projectRoot>/.gsd-capabilities.json) lives inside the repository. A repository you check out can therefore ship both a capability bundle and a ledger that marks it "committed." Running gsd-tools <that-family> inside such a repo will execute its code.

This is the same trust boundary that already applies to a repository's build scripts, npm postinstall, or a project-scoped capability's hooks (which GSD has loaded since Phase 2) — and it is narrower than those, because a command never fires on its own: you have to type it. GSD does not (and with plain files cannot) cryptographically distinguish a genuine project-local install from a forged project ledger. The honest guidance:

• A global install's consent record lives outside any repo and is trustworthy.
• A project-scoped capability is only as trustworthy as the repository it ships in — treat running its commands like running that repo's other code. Review repos before running gsd commands in them, and prefer global installs for capabilities you want to trust across projects.