Preflight Checks
Relevant source files
The following files were used as context for generating this wiki page:
Preflight checks serve as the primary safety gate for the Numan official registry's key and workflow consistency. These checks run entirely on repository state without requiring network access or secrets, ensuring that configuration drift or security vulnerabilities are caught in CI before reaching manual production procedures.
The preflight system is integrated into the repo-safety.yml workflow and is mandatory for all pushes and Pull Requests to ensure that trust invariants, such as the absence of private keys in the tree and the correct targeting of production environments, are maintained.
Sources: scripts/preflight.py:4-10, README.md:91-95, REVIEW.md:7-14
System Architecture
The preflight check system is implemented as a Python-based validation suite that inspects three critical areas: public key integrity, signature/key consistency, and GitHub Actions workflow safety.
The preflight script acts as a localized gatekeeper, ensuring the repository is in a valid state for signing and publication.
Sources: scripts/preflight.py:126-140, AGENTS.md:23-24
Key and Signature Validation
Preflight checks ensure that the registry's cryptographic materials are structurally sound and consistent.
Public Key Integrity
The system validates keys/official.pub. It ensures the file is valid JSON containing a key_id and public_key_b64. For non-placeholder keys, it verifies that the Base64-encoded public key decodes to exactly 32 bytes, consistent with Ed25519 requirements.
Sources: scripts/preflight.py:53-84
Consistency Monitoring
A critical check ensures that keys/official.pub and registry/index.json.sig agree on the key_id once they move past placeholder values. This prevents scenarios where a new public key is committed but the index signature still refers to an old trust root.
Sources: scripts/preflight.py:87-123, README.md:74-78
| Check Type | Logic | Target File |
|---|---|---|
| JSON Parsing | Validates structure of key/signature files | keys/official.pub, registry/index.json.sig |
| Byte Length | Verifies decoded key is 32 bytes | keys/official.pub |
| ID Match | Compares key_id across files | keys/official.pub vs registry/index.json.sig |
| Placeholder Sync | Ensures both signature fields are real or both are placeholders | registry/index.json.sig |
Sources: scripts/preflight.py:68-83, scripts/preflight.py:106-114
Workflow Safety Checks
The preflight system inspects .github/workflows/production.yml to prevent accidental exposure of the NUMAN_REGISTRY_PRIVATE_KEY secret.
The workflow checks protect the integrity of the signing process by ensuring that debug tracing is disabled in production environments.
Sources: scripts/preflight.py:143-176, scripts/test_workflow_safety.py:48-60
Security Constraints
- Environment Enforcement: The production workflow must explicitly declare
environment: productionto ensure it runs within protected GitHub environment boundaries. - Trace Prevention: The script flags shell debug commands (
set -x,set -o xtrace) and GitHub Actions debug variables (ACTIONS_STEP_DEBUG,RUNNER_DEBUG) that could inadvertently leak secrets to logs. - Echo Prevention: The script uses regex to identify any shell command that attempts to
echotheNUMAN_REGISTRY_PRIVATE_KEYvariable.
Sources: scripts/preflight.py:27-41, scripts/preflight.py:151-171
Related CI Gates
Preflight checks are part of a broader "Repo Safety" suite that includes additional automated validations.
- Secret Scanning:
scripts/scan_for_secrets.pymonitors for committed.keyor.pemfiles. - Parser Parity:
tools/numan-parser-checkensures the index can be parsed by the production Rust parser. - Workflow Pinning: Unit tests verify that all workflow actions are pinned to 40-character commit SHAs.
- Read-Only Defaults: CI ensures workflows default to
contents: readpermissions.
Sources: REVIEW.md:7-14, scripts/test_workflow_safety.py:28-46, AGENTS.md:22-30
Implementation Details
Key Functions
| Function | Description |
|---|---|
check_official_pub() | Validates JSON structure and Ed25519 key length in keys/official.pub. |
check_key_id_consistency() | Ensures the public key file and signature envelope share the same key_id. |
check_production_workflow() | Scans the production YAML for environment declarations and debug leaks. |
Sources: scripts/preflight.py:53, scripts/preflight.py:87, scripts/preflight.py:143
Regex Security Patterns
DEBUG_TRACE_PATTERNS = [
re.compile(r"\bset\s+-\w*x\w*\b"),
re.compile(r"\bset\s+-o\s+xtrace\b"),
re.compile(r"ACTIONS_STEP_DEBUG\s*:\s*true", re.IGNORECASE),
]
Sources: scripts/preflight.py:32-35
Preflight checks provide an essential automated layer for maintaining the Numan registry's trust model, specifically by preventing common configuration errors that could lead to secret exposure or signature verification failure. By running as a no-network, no-secret script, they ensure high-velocity feedback for maintainers and automated agents alike.