Spec gap: key bootstrap mechanism for air-gapped environments

[asiridalugoda]

Summary

HDP verification is fully offline — verifyToken() makes zero network calls. However, the specification does not define how implementations should obtain the issuer's public key in environments where /.well-known/hdp-keys.json is also unreachable (air-gapped industrial, classified, or edge deployments).

The gap

The only specified key distribution mechanism is the well-known endpoint format (KeyRegistry.exportWellKnown() / registry.loadWellKnown()). This requires HTTP access. In truly air-gapped environments, there is no specified fallback.

Proposed resolution (targeting §-01 of the IETF draft)

Define a Key Bundle format — a signed JSON object for out-of-band distribution:

{
  "version": "1",
  "issued_at": "<ISO 8601>",
  "keys": [{ "kid": "...", "alg": "Ed25519", "pub": "<base64url>" }],
  "bundle_signature": "<Ed25519 sig over canonical bundle body>"
}

• The bundle is signed by an offline root key whose fingerprint is embedded in the verifying system at manufacture or deployment time
• Distribution channels (USB, QR, secure file transfer) are explicitly out of scope for the spec
• KeyRegistry would gain a loadBundle() method alongside loadWellKnown()

Target

• IETF draft §-01 (new §4.4)
• v0.2 of @helixar_ai/hdp (KeyRegistry.loadBundle())

Related

• README: "HDP verification requires zero network calls" — this is true for verification; key bootstrap is the unspecified part
• See also: #[agent-anonymity issue]