Registry Management

Registry Management

Registry Management in Numan encompasses the discovery, synchronization, and verification of Nushell packages through signed remote indexes. The system is designed to ensure that all packages—including plugins, modules, scripts, and completions—originate from trusted sources using Ed25519 cryptographic signatures.

The architecture separates registry configuration (stored in config.toml) from the actual index data and trust roots. Numan supports a built-in "official" registry with a hardcoded trust root, while also allowing users to add custom registries by providing a name, URL, and public key.

Registry Architecture and Data Structures

The registry system relies on structured JSON indexes that define package metadata, versions, and verification requirements.

Registry Index Schema

A RegistryIndex contains the global state of a specific registry at a point in time, including its schema version and the list of available packages.

Field	Type	Description
schema_version	u32	Version of the registry format (aliases to version).
updated_at	String	Timestamp of the last index update.
packages	Vec<Package>	Collection of packages hosted by the registry.
trust	Option<Extension>	Optional metadata for registry trust extensions.

Core Components Diagram

The following diagram illustrates the relationship between the command handlers, the registry manager, and the trust store.

flowchart TD
    CMD[Registry Command] --> MGR[Registry Manager]
    MGR --> TRUST[Trust Store]
    MGR --> HTTP[Remote Index & Sig]
    TRUST --> KEYS[Ed25519 Public Keys]
    HTTP --> VERIFY[Signature Verification]
    VERIFY --> CACHE[Verified Index Cache]
    CACHE --> LOCK[Lockfile Selection]

Loading

The Registry Manager coordinates between the local Trust Store (for public keys) and remote resources to produce a Verified Index.

Synchronization and Verification

Synchronization is the process of fetching the latest index.json and its corresponding index.json.sig signature from a remote URL.

Signature Verification Flow

Numan verifies the signature and schema before promoting a fetched index. It preserves the previous verified index and signature as a Last Known Good (LKG) pair, atomically replaces each current cache file only after verification succeeds, and keeps using verified cache data if a network fetch or signature check fails.

sequenceDiagram
    participant CLI as Registry CLI
    participant MGR as Registry Manager
    participant HTTP as Remote Registry
    participant TRUST as Trust Store

    CLI->>MGR: sync_registries()
    MGR->>HTTP: GET index.json
    MGR->>HTTP: GET index.json.sig
    MGR->>TRUST: Get Public Key
    TRUST-->>MGR: Key Data
    MGR->>MGR: Verify signature and schema
    alt Valid Signature
        MGR->>MGR: Preserve prior pair as LKG; atomically replace cache files
        MGR-->>CLI: Success
    else Invalid/Fetch Failure
        MGR->>MGR: Load Cached Index
        MGR-->>CLI: Warning (Using Cache)
    end

Loading

Official Registry Trust Root

The official registry is live at https://numan-cli.github.io/numan-registry/index.json. Numan pins its production trust root, official-2026-07-01, in the binary, so numan init can configure official without manual key onboarding. The protected production workflow publishes the signed index; the public key, deployed signature, and key-rotation procedure are available for independent verification.

Command Reference

The numan registry subcommand group provides the following management capabilities:

Command	Arguments	Description
list	None	Displays all configured registries and their status.
sync	None	Fetches and verifies indexes for all enabled registries.
add	name, url, --key	Adds a custom registry with a base64 public key.
remove	name	Deletes a registry and its cached index data.
packages	None	Lists all packages available in the default registry.

Registry Configuration Snippet

Registries are configured within the Numan root config.toml file.

[registries.official]
url = "https://numan-cli.github.io/numan-registry/index.json"
enabled = true
trust_key = "..." # Base64 public key

Security Invariants

Registry management adheres to several critical security rules:

1. Mandatory Signatures: All registry indexes must be signed. Bypassing this requires setting NUMAN_ALLOW_UNSIGNED=1, which is intended for development only.
2. Verified cache promotion: Only a signature- and schema-validated index is promoted; the prior verified index/signature is retained as LKG and each cache file is atomically replaced.
3. Key Isolation: Public keys are stored in a TrustStore and are used to verify specific registries based on their configured name or key ID.

Conclusion

The Registry Management system provides a secure, decentralized foundation for Nushell package distribution. By combining Ed25519 signature verification with a robust caching and fallback mechanism, Numan ensures that package metadata remains trustworthy even in the event of transient network failures.