feat(#1435): capability matrix (generated + drift-guarded) + trust-model doc consolidation (#1458)

* feat(#1435): capability matrix (generated + drift-guarded) + trust-model doc consolidation

ADR-1244 Phase 6. Adds the capability matrix reference, generated FROM the committed registry so it
can never drift from the actual capability set:
- scripts/gen-capability-matrix.cjs (--write / --check); --check is a CI drift guard.
- tests/capability-matrix-sync.test.cjs (4 tests): drift guard, buildMatrix==committed, every cap
  present, no placeholders.
- docs/reference/capability-matrix.md regenerated from the registry (release-stable: shows engines.gsd,
  omits the lockstep per-cap version that would churn the file every release).
- Consolidated the duplicate trust-model doc: deleted docs/explanation/the-capability-trust-model.md,
  merged its content into capability-trust-model.md, redirected ~10 references; no stale links remain.
- Diataxis verification (now that gsd capability is a real command): corrected the matrix's third-party
  section — the matrix is the first-party catalogue; the overlay-aware view of installed third-party
  capabilities is 'gsd capability list', not this generated file.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(#1435): Added changeset for the capability matrix reference

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#1435): address code-review — non-vacuous matrix test + generator polish

- capability-matrix-sync.test.cjs: assert the 'security registers a ship:pre gate' precondition
  unconditionally so the extension-point check can never degrade to a vacuous pass on registry drift.
- gen-capability-matrix.cjs: warn (stderr) on an unknown loop point at generation time; rename
  enginesOf -> fmtEngines for consistency with the other fmt* helpers (output unchanged).
- capability-trust-model.md: point the two how-to links at the real files
  (import-a-capability-from-a-url.md, version-a-capability.md) instead of the bare directory.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(#1435): backfill changeset PR number → #1458

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-19 12:45:26 -04:00
committed by GitHub
parent 34bc096ec2
commit 0d56f544d2
16 changed files with 507 additions and 231 deletions

View File

@@ -3,8 +3,8 @@
> **Explanation** — This document describes *why* GSD draws its trust
> boundaries where it does, and *what the trade-offs are*. It is not a
> step-by-step guide to installing capabilities; for that, see the how-to
> guides for [importing a capability](../how-to/) and
> [version management](../how-to/). For the decision record, see
> guides for [importing a capability](../how-to/import-a-capability-from-a-url.md) and
> [version management](../how-to/version-a-capability.md). For the decision record, see
> [ADR-1244 D5](../adr/1244-capability-ecosystem.md#d5--trust-model-artifact-parity-is-full-trust-posture-is-tiered).
> For the capability field reference, see the
> [capability matrix](../reference/capability-matrix.md).
@@ -172,6 +172,15 @@ What it does not defend against: a malicious capability where the author
themselves publishes a bad bundle. The SHA is honest about what you are
installing; it says nothing about whether what you are installing is safe.
It also pins **only the top-level bundle**, not an `npm`-sourced capability's
resolved dependency graph. `--ignore-scripts` and copy-only staging stop
install-time execution, but when a command module is later `require()`'d, Node
resolves and runs its transitive dependencies — which the bundle SHA does not
cover (the Wiz / VS Code lesson). For the `npm` source kind, 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 or ship a lockfile.
### Auto-update off by default, re-consent on executable-set change
When auto-update is enabled for a third-party capability, each update is
@@ -200,13 +209,54 @@ rejected at the conformance gate. This prevents impersonation: a malicious
actor cannot publish a capability called `gsd-security` and exploit a user's
implicit trust in the GSD namespace.
### `strictKnownRegistries` for managed environments
### `capabilities.strict_known_registries` for managed environments
Teams or enterprises that want to constrain which capability sources are
permissible can set `strictKnownRegistries` in managed or project config to an
explicit allowlist of URLs or registry names. Setting it to `[]` blocks all
external installs. This gives an administrator a policy lever that operates
before the user even sees a consent prompt.
permissible set `capabilities.strict_known_registries` in config. Its semantics:
- **unset / `null`** *(default)* — permissive: external installs (git / npm /
tarball) are allowed, each still passing the consent + integrity gate. Local
filesystem installs are always allowed.
- **`[]`** *(explicit empty array)* — lockdown: **all external installs are
blocked**; local-only.
- **non-empty list** — a **host-based** allowlist: only sources whose host
matches an entry (exact host or a subdomain of it — `github.com` matches
`api.github.com` but never `evilgithub.com`; the literal token `npm` permits
the npm source kind). A malformed (non-array) value **fails closed**.
This gives an administrator a policy lever that operates before the user even
sees a consent prompt. The default is permissive-with-consent (not Obsidian-style
restricted-by-default), because the epic deliberately chose decentralised import
with the consent prompt as the default barrier and lockdown one config key away.
### Command dispatch: where third-party code runs (1.6.0)
A capability may declare a **command family** (`commands: [{ family, module,
router }]`); `gsd-tools <family>` dispatches it by `require()`-ing the router.
This is the one place a third-party capability's own code executes, so it is
gated twice. **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 consented. A bundle merely present on disk with no install record
still contributes its declarative surfaces but is **not** command-dispatchable.
**Confinement:** the router module loads only from the capability's own install
root (bare-`.cjs` basename, `realpath`-confined, rejecting `..` traversal and
symlink escape); a first-party command can never be shadowed by a third-party one.
#### The project-scope trust boundary
Capabilities install **globally** (`$GSD_HOME/.gsd/capabilities/`) or
**project-scoped** (`<projectRoot>/.gsd/capabilities/`). The consent record is
the ledger — and a project-scope ledger lives **inside the repository**. A repo
you check out can therefore ship a capability bundle *and* a ledger that marks
it committed; running `gsd-tools <its-family>` in that repo executes its code.
This is the same boundary that already applies to a repo's build scripts or a
project-scoped capability's hooks, and it is **narrower** — a command never fires
on its own; you have to type it. GSD cannot cryptographically distinguish a
genuine project-local install from a forged project ledger, so: 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. Review repos before running `gsd` commands in them, and prefer global
installs for capabilities you want to trust across projects.
---