Registry Management & Trust

Relevant source files

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

• src/cmd/registry.rs
• src/core/registry.rs
• src/core/official_registry.rs
• src/core/trust.rs
• src/core/package.rs
• AGENTS.md
• scripts/update-official-trust-root.sh

Introduction

Registry Management & Trust forms the security foundation of Numan, ensuring that all Nushell packages (plugins, modules, scripts, and completions) are sourced from verified and authenticated upstream providers. The system implements a secure supply chain using Ed25519 digital signatures to verify the integrity and provenance of registry indexes before any package installation or update occurs.

At its core, the system manages local registry configurations, synchronization of remote indices, and a trust store containing public keys. The "official" registry is uniquely handled with a built-in production trust root, allowing for seamless, secure onboarding while supporting custom third-party registries via manual key distribution.

Sources: README.md, AGENTS.md, src/core/official_registry.rs

Architecture and Components

The registry system is divided into high-level command interfaces and core logic for integrity verification and data modeling.

Core Data Structures

Structure	Description	Source
RegistryIndex	The top-level JSON structure of a registry, containing metadata and a list of Package objects.	src/core/package.rs:214-223
RegistrySignature	A detached signature envelope containing the key_id and the Base64-encoded signature.	src/core/official_registry.rs:16-21
VerifiedRegistry	Represents an index that has successfully passed cryptographic verification, including its SHA256 hash.	src/core/registry.rs:20-27
TrustStore	A local storage mechanism for mapping registry names to their authoritative Ed25519 public keys.	src/core/trust.rs:10-13

Component Relationship

The following diagram illustrates how the various registry components interact during management operations.

Trust Verification Workflow

The trust model relies on Ed25519 signatures over the exact bytes of the index.json file. When a registry is synced, Numan fetches both the index and a detached .sig file.

Verification Logic

1. Fetch: The index.json and index.json.sig are retrieved via HTTP.
2. Canonicalization: The JSON index is converted to a canonical byte format to ensure signature stability.
3. Key Retrieval: For the "official" registry, the built-in public key is used. For others, the key is pulled from the local TrustStore.
4. Signature Check: The ed25519-dalek library validates the signature against the canonical bytes.
5. Persistence: Only verified indices are promoted to the active index.json path; unverified data is rejected.

Official Registry Trust Root

The official registry is hard-coded into the Numan binary to prevent "bootstrap" trust issues. This configuration includes the production URL and the authoritative public key.

// src/core/official_registry.rs:32-37
pub const OFFICIAL_REGISTRY: OfficialRegistry = OfficialRegistry {
    production_url: "https://tonythethompson.github.io/numan-registry/index.json",
    key_id: "official-2026-07-01",
    public_key_b64: "PLACEHOLDER", // Actual key provided in production builds
};

Sources: src/core/official_registry.rs:32-37, scripts/update-official-trust-root.sh

Trust Rotation

Trust roots are updated via a specialized script update-official-trust-root.sh, which performs safe replacement of public material and enforces naming conventions (e.g., official-YYYY-MM-01).
Sources: scripts/update-official-trust-root.sh:103-155

Registry Management Commands

Registry operations are performed through the numan registry subcommand suite.

Available Subcommands

Command	Action	Implementation Details
list	Displays configured registries and status.	Reads config.toml.
sync	Refreshes local indices with signature verification.	Requires mutation_lock; handles LKG fallbacks.
add	Registers a new custom registry and trust key.	Updates TrustStore and config.toml.
remove	Deletes a registry and its cached index.	Removes directory registry/{name}.
packages	Lists available packages in the default registry.	Displays owner, name, version, and type.

Sources: src/cmd/registry.rs:10-27, src/cmd/registry.rs:114-142

Data Layout and Storage

Registry data is stored under the Numan root directory in a structured hierarchy to support multi-registry environments.

• Config: config.toml contains registry URLs and enabled status.
• Indices: registry/{name}/index.json stores the verified package list.
• Signatures: registry/{name}/index.json.sig stores the signature for the current index.
• Trust: trust/keys.json (managed via TrustStore) contains public keys for custom registries.

Sources: README.md, src/cmd/registry.rs:159-165, src/core/trust.rs:25-35

Conclusion

The Registry Management & Trust system ensures that Numan remains a production-grade tool by enforcing strict cryptographic verification on all package metadata. By combining a built-in trust root for official packages with a flexible TrustStore for community registries, the architecture balances ease-of-use with high-security standards. Failure to verify a registry results in a "fail-closed" state where no new packages can be installed from that source until a valid, signed index is provided.