Key Management
Relevant source files
The following files were used as context for generating this wiki page:
Key Management in the Numan Registry project encompasses the generation, storage, and verification of Ed25519 signing keys used to ensure the integrity of the official package index. The system follows a "WSL-first" maintainer approach designed to prevent the exposure of private keys while allowing Numan clients to verify the registry's contents against a built-in trust root.
The primary purpose of this system is to secure the index.json file. While the registry source tree contains a placeholder signature, the production publication workflow utilizes protected environments to apply real signatures that clients verify. Security policies strictly prohibit committing private key material to the repository, utilizing CI scanners and gitignore rules to enforce this invariant.
Sources: README.md:12-14, README.md:73-77, SECURITY.md:65-67, REVIEW.md:52-53
Key Architecture and Trust Model
The registry relies on a decentralized trust model where Numan clients possess a pre-baked "official" trust root. All production artifacts are verified using this root to prevent trust bypass or malicious artifact injection.
Cryptographic Standards
- Algorithm: Ed25519 for all signing operations.
- Digest: SHA-256 for artifact and canonical JSON byte verification.
- Encoding: Base64 for signatures and public keys stored in JSON envelopes.
Sources: README.md:63-65, SECURITY.md:65-70, scripts/provision-production-key.sh:160-165
Key Provisioning Flow
The provisioning process is a manual, maintainer-led workflow that happens locally to ensure the private key is never handled by automated agents or exposed to CI logs.
The diagram shows the local generation process where private material is isolated from the repository.
Sources: scripts/provision-production-key.sh:11-20, scripts/provision-production-key.sh:220-240
Key Implementation Details
Signature Envelope
The detached signature file (registry/index.json.sig) follows a specific JSON schema to facilitate client-side verification.
| Field | Type | Description |
|---|---|---|
key_id | String | Identifier for the trust root (e.g., official-YYYY-MM). |
algorithm | String | The signing algorithm used (default: ed25519). |
signature | String | Base64 encoded Ed25519 signature of canonical index bytes. |
Sources: README.md:58-62, schemas/index-v1.json:20-30
Index Trust Schema
The index.json file can include successor key declarations to facilitate key rotation without breaking client installations.
{
"trust": {
"keys": [
{
"key_id": "string",
"public_key_b64": "base64"
}
]
}
}
Sources: schemas/index-v1.json:21-41
Key Lifecycle and Operations
Provisioning Process
The provision-production-key.sh script handles the lifecycle of a new keypair. It enforces safety by using umask 077 during file creation to ensure the private key is never world-readable.
- Generation: Uses
cryptography.hazmatto generate a raw 32-byte Ed25519 private key. - Fingerprinting: Generates a 16-character SHA-256 fingerprint for public key verification.
- Deployment: The public key is committed to
keys/official.pub, while the private key is manually added to theproductionGitHub Environment secret asNUMAN_REGISTRY_PRIVATE_KEY.
Sources: scripts/provision-production-key.sh:119-122, scripts/provision-production-key.sh:170-185, scripts/provision-production-key.sh:226-235
Verification
Verification is performed using scripts/validate.py. The project supports both full signature verification and "unsigned validation" for local development (which skips the signature check if the source-tree contains a placeholder).
# Verify public key, index, and signature
python3 scripts/validate.py \
--index registry/index.json \
--sig registry/index.json.sig \
--pub keys/official.pub \
--schema schemas/index-v1.json
Sources: scripts/provision-production-key.sh:78-85, REVIEW.md:9-15
Security Invariants
Maintainers and reviewers must flag P0 severity violations during PR reviews:
- No Private Keys: Secret scans (
scripts/scan_for_secrets.py) must pass; committing*.keyor*.pemis strictly prohibited. - Placeholder Signatures: The source tree signature is intentionally a
PLACEHOLDERto prevent the accidental use of development keys as production trust roots. - Protected Signing: Only the manual dispatch of the
production.ymlworkflow in a protected environment has access to the signing secret.
Sources: REVIEW.md:31-35, REVIEW.md:52-56, README.md:85-90
Summary
Key Management in Numan Registry is a security-critical system that relies on Ed25519 signatures to establish trust. By isolating private keys in protected environments and providing local scripts for key generation and validation, the project ensures that registry integrity can be verified by Numan clients while maintaining a simple, auditable maintainer workflow. Significant events such as key exposure or rotation follow specific runbooks located in the docs/ directory.
Sources: README.md:12-20, SECURITY.md:85-87