Cryptographic Trust

Cryptographic Trust & Integrity

Numan employs a multi-layered cryptographic security model to ensure that Nushell packages are authentic, untampered, and derived from trusted sources. This system integrates registry-level signature verification with artifact-level integrity checks to maintain a secure supply chain.

The scope of this system covers Ed25519-based trust roots for registry indexes and SHA256 hashing for binary artifacts. By default, Numan mandates signatures for all registries, requiring an explicit environment variable (NUMAN_ALLOW_UNSIGNED=1) to bypass these checks during development.

Trust Architecture

The trust model centers on a chain of verification starting from a built-in "Official Trust Root" and extending to custom registries via a local trust store.

Official Trust Root

Numan contains a hardcoded production trust root for the official registry. This root consists of a unique key_id, a Base64-encoded Ed25519 public key, and a production URL. This allows Numan to verify the official registry index without manual user intervention or key onboarding during the numan init process.

Registry Verification Flow

When a registry index is synced, Numan verifies an Ed25519 signature (index.json.sig) over the exact bytes of the index.json file.

flowchart TD
    A[Registry Sync] --> B{Official Registry?}
    B -- Yes --> C[Load Built-in Trust Root]
    B -- No --> D[Load Key from Trust Store]
    C --> E[Fetch index.json & index.json.sig]
    D --> E
    E --> F[Verify Ed25519 Signature]
    F -- Valid --> G[Update Local Index Cache]
    F -- Invalid --> H[Fallback to Last Known Good/Fail]

Loading

The diagram illustrates the decision logic between using the built-in official trust root versus custom keys during a registry synchronization event.

Core Components

Integrity Verification (SHA256)

Integrity checks are mandatory for all binary artifacts, specifically plugins. The installation transaction will terminate if the SHA256 hash is missing from the artifact metadata or if the calculated hash of the downloaded file does not match the expected value.

Component	Logic Location	Responsibility
integrity.rs	src/core/integrity.rs	SHA256 computation and verification of downloaded artifacts.
Artifact type	src/core/package.rs	Stores mandatory sha256 metadata for plugins.
Transaction	src/install/transaction.rs	Executes verification before extraction and lockfile updates.

Trust Store (Ed25519)

The trust store manages public keys for non-official registries. Custom registries must be added with a specific public key using the --key flag.

// Example of how the Official Registry is defined in the codebase
pub const OFFICIAL_REGISTRY: OfficialRegistry = OfficialRegistry {
    key_id: "official-2026-07-01",
    public_key_b64: "...", 
    production_url: "https://tonythethompson.github.io/numan-registry/",
};

Maintenance and Rotation

Numan provides tooling to manage the evolution of trust roots, ensuring that key rotation can be handled safely by developers.

Trust Root Updates

The update-official-trust-root.sh script is used to rotate the production trust root. It performs several safety checks before modifying src/core/official_registry.rs:

1. Format Validation: Ensures the public key decodes to exactly 32 bytes.
2. Safety Enforcement: Refuses to set placeholder values unless the --force flag is used.
3. Automated Testing: Runs cargo test official_registry immediately after modification to ensure the new root is functional.

Security Constraints

Numan enforces several architecture rules to maintain integrity:

• Registry Signatures: Mandatory; bypass requires NUMAN_ALLOW_UNSIGNED=1 (intended for development only).
• Immutability: Packages are installed in content-addressed paths (<version>-<sha8prefix>) to prevent in-place tampering.
• Lockfile Ground Truth: The lockfile pins the payload_sha256 to ensure subsequent activations use the exact verified payload.

Summary

Cryptographic trust and integrity in Numan are achieved through mandatory SHA256 artifact verification and Ed25519 signature checks on registry indexes. The system prioritizes "secure by default" behavior by hardcoding the official trust root and requiring explicit overrides for unsigned content, ensuring that users can safely install and activate Nushell packages from both official and third-party registries.