dsh-plugin-trust-center

Evidence-first inspection, compatibility verification, and quarantine tooling for DeepSeek Harness plugins.

Important: a pass Passport means that the declared package structure passed this version's bounded checks. It is not a certification that third-party code is safe.

Stage 1: Plugin Passport CLI

Stage 1 performs deterministic, static-by-default inspection of:

• a local directory, such as ./my-plugin;
• an npm package, such as npm:@scope/plugin@1.2.3;
• a GitHub repository, such as github:owner/repo#v1.2.3.

Network sources are resolved before inspection: npm metadata records an exact published version and GitHub refs resolve to a 40-character commit SHA. Archive extraction rejects traversal, links, oversized downloads, oversized files, excessive entries, and excessive expanded size.

Run from npm

Install and run the exact public version:

npm exec --package dsh-plugin-trust-center@0.3.2 -- dsh-trust inspect ./my-plugin

Run from a GitHub Release

Download the .tgz and SHA256SUMS.txt assets from the matching GitHub Release, verify the checksum, then run:

npm exec --package ./dsh-plugin-trust-center-0.3.2.tgz -- dsh-trust inspect ./my-plugin

Run from source

Node.js 24.17.x and pnpm 11.21.0 are required.

corepack enable
pnpm install --frozen-lockfile
pnpm build
node dist/cli.js inspect ./test/fixtures/safe-bundle

Commands

dsh-trust inspect <source> [--format human|json|sarif] [--output path]
dsh-trust schema
dsh-trust rules
dsh-trust verify-import <source> [--output path]
dsh-trust quarantine install <source> --target <profile> [--allow-execute]
dsh-trust quarantine promote <quarantine-id> --target <profile> [--dry-run]
dsh-trust profile list
dsh-trust profile snapshot <profile>
dsh-trust profile disable <profile> <bundle> [--dry-run]
dsh-trust profile restore <profile> <snapshot-id> [--dry-run]

inspect never imports target modules or runs package-manager lifecycle scripts. It emits:

• human: a bounded terminal summary;
• json: a canonical Plugin Passport;
• sarif: SARIF 2.1.0 suitable for code-scanning tools.

Exit codes are 0 for pass, 2 for review, 3 for fail, and 1 for an operational error.

verify-import is deliberately separate: it executes the target entry module and must only be used after explicit approval in a disposable, secret-free environment. It copies the package to a temporary directory and installs production dependencies with lifecycle scripts disabled before import. The repository includes a manual-only restricted GitHub Actions workflow that pins execution to the exact source revision inspected.

Library API

import { inspectSource, renderJson } from 'dsh-plugin-trust-center'

const passport = await inspectSource('github:owner/repo#v1.2.3')
process.stdout.write(renderJson(passport))

The Passport includes normalized DSH declarations, install scripts, direct dependency evidence, stable findings, a deterministic package digest, and a CycloneDX 1.6 direct-dependency SBOM. Published evidence omits temporary absolute paths and timestamps.

Stage 2: Community Registry

The public evidence site is generated from immutable declarations in registry/sources.json. It provides searchable no-JavaScript-compatible plugin pages, canonical JSON reports, SVG badges, Shields endpoint JSON, immutable source links, tested DSH versions, and finding evidence.

Each generated record includes deterministic maintenance coordinates (provider, namespace, project, and immutable revision) derived from its reviewed GitHub/npm source. Mutable popularity scores and subjective rankings are intentionally excluded so repeated builds remain reproducible.

Registry labels deliberately avoid the word “safe”:

• verified-package: static inspection produced a pass Passport;
• candidate: static inspection produced a review Passport;
• incompatible: static inspection produced a fail Passport;
• unavailable: acquisition or inspection could not produce a Passport.

Build and verify a byte-stable snapshot locally:

pnpm registry:build
pnpm site:check

Scheduled/manual GitHub Actions publish generated content to the registry-data branch and deploy that branch through GitHub Pages. Collection never imports target modules or runs their lifecycle scripts. Submission and rule-governance requirements are documented in CONTRIBUTING.md and docs/rules.md.

Stage 3: DSH bundle, quarantine, and profile recovery

The npm package and matching v0.3.2 Release tarball are also external DSH bundles. Add either immutable spec through the official CLI and validate the composed configuration:

export DSH_PATH="$(command -v dsh)" # must resolve to an absolute official DSH executable
dsh plugin --profile work add dsh-plugin-trust-center@0.3.2
# Or, after verifying SHA256SUMS.txt:
# dsh plugin --profile work add "$(pwd)/dsh-plugin-trust-center-0.3.2.tgz"
dsh --profile work --dump-config

The bundle patch registers only two bounded, read-only model tools: trust_inspect and trust_profile_status. Local model-driven inspection is denied unless the plugin configuration explicitly lists an allowed local root. Profile mutation is never exposed as a model tool.

Quarantine is an evidence workflow, not a host sandbox:

dsh-trust quarantine install npm:example-plugin@1.2.3 --target work
dsh-trust quarantine promote <quarantine-id> --target work --dry-run
dsh-trust quarantine promote <quarantine-id> --target work

Installation first creates a static Passport and refuses fail verdicts or mutable/local resolved sources. It then uses a dedicated trust-quarantine-<id> profile in an isolated temporary DSH_HOME, disables npm/pnpm lifecycle scripts, runs --dump-config, writes an atomic digest-bound receipt below $DSH_HOME/quarantine, and removes the disposable install tree. --allow-execute is the only path that imports target code and should be used only in a disposable, credential-free environment. Promotion re-inspects the immutable source, verifies the receipt and Passport digest, snapshots the target, calls official dsh plugin add, validates with --dump-config, and records the immutable install spec in the target profile ledger. A target named in the receipt cannot be changed during promotion.

Profile operations are explicit and snapshot-backed:

dsh-trust profile list
dsh-trust profile snapshot work
dsh-trust profile disable work example-plugin --dry-run
dsh-trust profile disable work example-plugin
dsh-trust profile restore work <snapshot-id> --dry-run
dsh-trust profile restore work <snapshot-id>

Snapshots live below $DSH_HOME/snapshots/<profile>, contain only bounded profile control files plus the Trust Center ledger, and carry per-file SHA-256 digests. Disable works only when an immutable ledger record exists, invokes official dsh plugin remove, and restores/reinstalls on failure. Restore verifies snapshot identity and digests, reinstalls ledger-pinned bundles through official commands, and rolls back partial restoration. Trust Center never disables a bundle by editing only dsh.profile.bundles.

The v0.3.1 hardening release serializes ledger writers, terminates timed-out POSIX command process groups, preserves original and rollback errors, protects restore targets at the snapshot-ring limit, checks promotion cleanup failures, and isolates corrupt profile manifests in the read-only status tool.

Reproducible constrained dogfood

Run the bounded release-confidence path from a clean checkout:

pnpm install --frozen-lockfile
pnpm dogfood

The command reads the immutable Sentinel commit from registry/sources.json, verifies the packed bundle with pinned official @deepseek-ai/dsh@0.1.0-rc.6, emits a static Passport, performs a lifecycle-script-disabled quarantine install in a temporary DSH_HOME, requires a receipt with executed: false, runs promotion only with --dry-run, and executes the focused process, ledger, rollback, snapshot, quarantine, plugin, and CLI regression suites. Bounded evidence is written to dogfood-artifacts/; temporary profile state is removed even on failure.

The Constrained Dogfood GitHub workflow exposes the same command through manual workflow_dispatch only. It has read-only repository permission, no secrets, no dynamic import, a 20-minute timeout, and seven-day artifact retention. Network-dependent dogfood is intentionally excluded from ordinary push and pull-request CI.

npm publication integrity

npm publication is a separate protected manual workflow. It downloads every asset from an existing stable GitHub Release, verifies SHA256SUMS.txt, requires the tarball package name and version to match the selected tag, and refuses an already-published version. The workflow publishes that exact tarball with --provenance; it does not rebuild or repack. Bootstrap credentials are scoped to the npm Environment and exposed only to the publish step. Because publication uses workflow_dispatch, provenance identifies the manual workflow run on main; the verified checksum and package-version checks provide the binding to the selected Release tag.

Verdict model

• fail: at least one critical structural finding, including an invalid manifest, escaping/missing/invalid Cordis patch, invalid client/profile declaration, no DSH declaration, or an incomplete scan caused by limits or links;
• review: no critical findings and at least one high-severity observable capability, such as lifecycle scripts, process execution, environment access, network access, native artifacts, suspicious source shape, or mutable dependency specs;
• pass: no findings in the current rule set.

Use dsh-trust rules for machine-readable rule metadata. Rule findings report observable evidence, not author intent.

Delivery stages

1. Plugin Passport CLI — implemented in v0.1.0.
2. Community Registry — implemented in v0.2.0 with GitHub Actions, Pages reports, badges, and contribution rules.
3. DSH integration — implemented in v0.3.0 and hardened in v0.3.1 with the external bundle, quarantine receipts/promotion, transactional snapshots, official disable/restore commands, and rollback.

Specifications live in docs/specs. The security boundary and explicit non-goals are documented in docs/threat-model.md.

Security

Default inspection never executes target code. Static analysis cannot fully detect obfuscation, delayed behavior, dependency compromise, native-code behavior, or remote payloads. Report vulnerabilities privately as described in SECURITY.md.

License

Apache-2.0. See LICENSE and NOTICE.