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.
Related
- How Swamp Works — foundational concepts and architecture.
- About the Extension Scorecard — what the quality score measures and why verification is separate.
- Scorecard Rubric — exact factors, weights, and grade thresholds.
- Publishing Reference — yank and deprecate commands.
- Extension Management — trust commands.