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 enforces mandatory signature verification for all registry operations. If a network fetch fails or a signature is invalid, Numan attempts to fall back to a "Last Known Good" (LKG) cached index to ensure availability.

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 Ed25519 Sig
    alt Valid Signature
        MGR->>MGR: Update Cache (LKG)
        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 has a production trust root built into the binary. This allows numan init to auto-configure the official registry without manual key onboarding. The system uses a specific key ID (e.g., official-2026-07-01) to identify the built-in trust root.

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://tonythethompson.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. Atomic Writes: Registry indexes and trust store updates use atomic file operations to prevent corruption during crashes.
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.