Trust Model & Verification

Relevant source files

The following files were used as context for generating this wiki page:

• SECURITY.md
• REVIEW.md
• AGENTS.md
• README.md
• schemas/index-v1.json
• scripts/validate_candidate.py
• scripts/provision-production-key.sh

The Trust Model & Verification system within the Numan Registry ensures the integrity and authenticity of Nushell packages. It is designed to prevent compromised or malicious artifacts from being installed by clients. The model relies on Ed25519 signatures over canonical data, immutable artifact digests, and a multi-stage validation pipeline that spans from initial package intake to production deployment.

This system is central to the project's security posture, separating automated staging (using ephemeral keys) from protected production signing. Production clients verify the official registry index using a trust root baked into the Numan CLI, ensuring that only reviewed and signed metadata leads to artifact installation.

Core Trust Architecture

The trust model is built on three primary pillars: cryptographic identity, data canonicalization, and artifact immutability.

Cryptographic Identity

Numan uses Ed25519 signatures for high-speed, secure verification. The official trust root is embedded in the Numan CLI, and the registry publishes a detached signature (index.json.sig) for its catalog.
Sources: SECURITY.md:58-60, README.md:10-15

Data Canonicalization

To ensure signatures are stable across different environments, the registry index (index.json) must be transformed into a canonical JSON form—specifically sorted keys, compact encoding, and no whitespace—before it is digested and signed.
Sources: README.md:94-98

Artifact Integrity

Every artifact (binary, archive, or source) listed in the index MUST carry a SHA-256 digest. The Numan client refuses to install any binary that does not match the recorded digest. Once published, artifact URLs and digests are strictly immutable.
Sources: SECURITY.md:61-68, REVIEW.md:27-30

Validation Pipeline

Verification occurs at multiple stages: during local development, human review, CI staging, and finally, production publication.

Automated CI Gates

The following checks are mandatory for any Pull Request to ensure repo safety:

• Secret Scanning: scan_for_secrets.py searches for private-key material (*.key, *.pem) which are strictly forbidden in the source tree.
• Schema Validation: Ensures index.json adheres to schemas/index-v1.json.
• Parser Parity: The catalog is parsed using the production Rust registry parser (numan-parser-check) to prevent syntax regressions.
• Manifest Linting: lint-manifest-index.py verifies that nu_version ranges in the index match those in the numan-plugins manifest.
  Sources: AGENTS.md:18-35, REVIEW.md:7-18

The Intake Cycle

New packages follow a 5-stage validation process orchestrated by validate_candidate.py:

1. Download & Hash: add-package.py downloads the artifact to compute a real SHA-256; hand-typing hashes is a P0 severity violation.
2. Structural Lint: Structural integrity checks via lint_packages.py.
3. Schema Verification: Full JSON schema check.
4. Lifecycle Proof: lifecycle-prove.py runs a simulated install/activation against a real Nushell instance.
   Sources: scripts/validate_candidate.py:15-28, REVIEW.md:27-30, README.md:144-155

Severity Levels

PR reviewers flag issues based on a specific severity scale:

Label	Meaning
P0	Trust bypass, private-key material, unsigned-production fallback, hand-typed hashes.
P1	Incorrect intake logic, missing lifecycle evidence, schema/parser mismatch.
P2	Doc/intake-state drift, misleading checklists.
P3	Style, naming, non-blocking suggestions.
Sources: REVIEW.md:21-26

Key Management and Provisioning

The project maintains a strict boundary between public and private cryptographic material.

Key Provisioning

The scripts/provision-production-key.sh utility is used to generate Ed25519 keypairs locally.

• Private Keys: NEVER committed or printed to logs. They are stored in protected GitHub Environments (production) and encrypted vaults.
• Public Keys: Committed to keys/official.pub.
• Successor Keys: The schema supports trust.keys for successor key declarations to allow for planned rotations.
  Sources: scripts/provision-production-key.sh:10-25, schemas/index-v1.json:20-43, README.md:112-118

Trust Invariants

Maintainers and automated agents must enforce the following invariants to preserve the system's integrity:

1. No Private Keys in Tree: Any occurrence of a private key file is a fatal CI error.
2. Placeholder Signatures: The registry/index.json.sig file in the source tree is a PLACEHOLDER. Real signatures are only generated during protected deployment workflows.
3. Download-only Hashes: SHA256 values must never be hand-edited; they must be derived from actual artifact downloads.
4. Binary-only Catalog: Official promotion is restricted to binary artifacts; kind: source is rejected during intake.
5. Human Review Required: Automated scripts are prohibited from auto-publishing to the trust root.
   Sources: REVIEW.md:27-42, SECURITY.md:69-72

Signature Envelope Format

The detached signature index.json.sig is a JSON envelope containing the algorithm, key identifier, and the base64-encoded signature.

{
  "key_id": "official-YYYY-MM",
  "algorithm": "ed25519",
  "signature": "base64..."
}

Sources: README.md:100-110

Numan registry's trust model effectively combines pre-commit structural validation, CI-enforced schema checks, and protected production signing to ensure a secure distribution channel for Nushell extensions.