Skip to main content

EXTENSION TRUST AND THE SUPPLY CHAIN

Extensions run arbitrary TypeScript on the user's machine, and anyone can publish to the registry. A registry is a distribution mechanism, not a quality guarantee — it tells you an extension exists, not whether it is safe to run. The trust model exists to close that gap by making trust an explicit, scoped decision rather than something implied by availability.

Trusted collectives

When an operative runs swamp extension pull @someone/something, they explicitly choose to download and execute code from that collective. But during swamp extension install, Swamp resolves dependencies automatically, and automatic resolution needs a boundary. That boundary is the trusted collectives list maintained per repository with swamp extension trust add.

Trust is per-repository because different repositories have different risk profiles. A production infrastructure repository that manages cloud resources should trust fewer collectives than a playground repository used for experimentation. A single global trust list would force the most permissive policy onto every context. The repository-scoped model lets each repo declare its own tolerance, and extensions from untrusted collectives still work — they just require explicit swamp extension pull rather than silent auto-resolution.

The reserved collective @swamp is trusted by default and cannot be removed from the trust list.

Auto-trust for membership collectives

swamp extension trust auto-trust true automatically trusts every collective the authenticated operative belongs to. This is convenient for teams that publish and consume their own extensions — there is no manual trust ceremony each time a colleague pushes a new version under the team's namespace.

The tradeoff is visibility. When auto-trust is on, the trust list is no longer a static declaration; it expands with the authenticated identity's memberships. In repositories managed by CI, where the authenticated identity may belong to many collectives, auto-trust can silently widen the resolution surface beyond what the repository owner intended. The default is off, and the recommendation for CI-managed repositories is to leave it off and maintain an explicit trust list.

Dependency trust scoring

The extension quality scorecard includes a dependency trust factor that audits every npm: import against OSV.dev for known vulnerabilities and the npm registry for deprecation status, license, maintainer count, and publish recency, and every jsr: import for existence. Most of these signals affect only the quality score — a package with few downloads costs points but does not block anything.

Authors write dependencies in many ways: inline or through an import map, exact or as a range, in a deno.json or a package.json, with or without a lock. Push accepts the forms Deno resolves and bundles, and ships every one of them in a single form: each npm: and jsr: import pinned to the exact version the bundle holds. Before that, each step after push — the shipped source, the audit, the registry's scorecard and a consumer's rebuild — read ranges, import maps and locks again, each slightly differently, and the gaps between them were where the audited version and the running version came apart. With one exact form, every step reads the same answer. A bare import is audited like an inline one, and its findings name the import it came from. The supported inputs are listed in Extension Dependencies.

What counts as a dependency is what the shipped code imports. A test file is not audited: it ships in the archive but does not run when the extension does, so its imports say nothing about what a user installs. An import inside a comment, or a string that merely looks like a specifier, is not audited either, since no runtime ever loads it. Reading only real imports keeps an author from losing points for a dependency their extension does not have.

A dependency's license is read as an SPDX expression rather than compared as text, so MIT OR Apache-2.0 passes: every license it names is on the allowlist. A package that declares no license is warned about, because the absence of a license is not permission to use the code.

The audit asks about the version that ships, not about whatever the package calls latest. An exact pin names that version outright. A range or a dist-tag does not, so swamp extension push takes the version its bundler used: the one installed in node_modules for a package.json dependency, each installed copy separately, the one the project's deno.lock records, otherwise the one Deno resolved from its cache or the registry. Push then writes that version into the shipped source. OSV.dev is asked about that version, and the npm license, maintainers and deprecation are read from it; only the publish-recency check keeps looking at the package's latest release, because it measures whether anyone still maintains the package. Facts read from latest would describe code the extension does not run.

Push reads the lockfile and node_modules but never changes them. push, quality and fmt all treat the lock as read-only: a lock out of date with its project file is something the author decides to update with deno install, not something a publish quietly rewrites. The lock is the author's statement of what they tested; a tool that rewrote it on the way to the registry would publish versions nobody chose.

Neither the lockfile nor package.json ships in the archive. Push writes the versions into the shipped source and lists them, with how each was decided, in dependency-audit.json. The registry's scorecard audits the versions the source names, exactly as written: it reads no lockfile and resolves no range, so a newer release after the push does not change what the scorecard says about the version that shipped. A specifier that is not exact, or that the record does not list, is not audited. Archives published before the exact form keep the older rules, under which the registry resolves a range itself.

The rule for authors is to pin exact versions or commit a lock. A range that no lock fixed still ships pinned, but the version is whatever the registry served on the day of the push, which nobody chose, so push warns and the factor gives up one of its two points. A lock fixes the same version and scores the same as an exact pin. It is the stronger choice of the two, because it also fixes the transitive versions the bundle holds, which an exact pin at the top level does not.

An audit that could not run is not a clean one. When the OSV.dev, npm registry or JSR lookup for a package fails, or no published version matches the specifier, so OSV.dev was never asked, the package is reported as not audited, naming the reason, rather than as passed. Silence from an unreachable service says nothing about the package, so neither swamp extension quality nor the registry's scorecard awards the factor for it. A push asks for confirmation before publishing it and records the acceptance, but does not block.

Code from outside npm and JSR — a URL import, or a git or local package.json dependency — is not audited for a different reason: no registry describes it. The npm and JSR audit is a lookup by name and version in registry metadata, and a URL or a git commit has no such entry. Push still bundles and ships it, so nothing that worked stops working, but it lists the code under unaudited with a digest of each module, and it costs both points. Publishing the code to npm or JSR, or moving it into the repository, earns them back.

The exception is the publishing gate. A package whose shipped version is deprecated and whose latest release is deprecated too, or one with a HIGH, CRITICAL, or unknown-severity vulnerability, is a hard error that blocks swamp extension push. The reasoning is asymmetric risk: a single compromised or abandoned dependency in a published extension affects every repository that installs it. Catching the problem at publish time is cheaper than catching it across every consumer. The full factor list and thresholds are on the scorecard rubric.

A deprecated version of a package that is still maintained is a softer case: the author has moved on from that release but not from the package, and a newer version is one bump away. Push warns about it, names that version, and asks for confirmation. It costs both points of the dependency trust factor rather than blocking the push.

Dependencies imported from jsr: are checked only for existence: a missing package or version blocks, and a yanked version warns, naming the newest version that is not yanked, and asks for confirmation the same way. The author withdrew it, so it costs both points too. Neither becomes an error: a version pinned exactly, or held in a lockfile, still installs, and a range already skips a yanked version, so blocking would refuse extensions that run. The score is where the cost shows. The jsr registry already enforces SPDX licensing, provenance, and a prohibition on install scripts, so the npm-style gates would be redundant, and OSV.dev has no jsr data to check. A JSR outage leaves the dependency not audited, as an npm one does.

What consumers run

When an operative pulls, updates or auto-resolves an extension, Swamp keeps the bundle the publisher built, as swamp extension install always has. Before this, pull rebuilt each bundle from the shipped source on the consumer's machine, so a consumer could run a different version from the one the scorecard showed, and pull and install of one version could leave different bundles. Keeping the publisher's bundle makes the code a consumer runs the code the registry audited, and lets that bundle carry the transitive versions the publisher's lock fixed.

Because consumers run the bundle rather than the source, the bundle gets the same scrutiny: pull checks each bundle against the digest in dependency-audit.json and refuses an archive whose bundles do not match, and the safety analysis scans the bundles as well as the source. A consumer rebuilds from the source only when it has to — no bundle for a source, a bundle format the running Swamp does not run, or a bundle that fails to load — and the rebuild ignores any Deno config in the consumer's repository. Because the source names every dependency exactly, a rebuild fetches the versions the registry audited.

The "Verified by Swamp" badge

The badge indicates that the Swamp team has reviewed an extension for safety and correctness. It is separate from the automated quality score because the two answer different questions. The score measures surface-level quality that a publisher controls — documentation, type coverage, dependency health. Verification requires human judgment — does the extension do what it claims, is the author who they say they are, is the code worth running.

Most extensions do not carry this badge, and that is expected. An extension can score 100% on the automated rubric without verification, and a verified extension with poor documentation will still score low. The two signals are independent by design. More detail on how the badge and the score relate is in the scorecard explanation.

Yanking and deprecation

A published extension version can be deprecated or yanked. The distinction reflects intent.

Deprecation is a lifecycle signal — the extension is superseded by something better, or the author no longer maintains it. A deprecated version is still pullable but flagged with a warning and an optional successor pointer.

Yanking is a safety signal — the version was compromised, accidentally published, or contains a defect serious enough to warrant immediate removal. Because the intent is safety, yanking is a hard cut: a yanked version cannot be downloaded at all, regardless of how it is requested. Automatic resolution, explicit pull by exact version, and lockfile restoration are all blocked — the registry returns an error for any download attempt. This is stricter than deprecation precisely because the scenarios that warrant yanking (compromised code, accidental publish of secrets, critical defects) justify breaking existing lockfiles rather than silently serving known-bad code. Existing local copies already on disk are unaffected, but no new copies can be fetched.

Both actions are reversible. Neither deletes the version from the registry, because the registry's promise is that a version, once published, keeps meaning what it meant. See the publishing reference for the commands, and the trust management reference for managing the trusted collectives list.