Key Management and Rotation (NexArt Node)

How NexArt Node manages Ed25519 signing keys, rotates them safely, and maintains backward-compatible verification.

Overview

Each NexArt attestation node signs Certified Execution Records (CERs) using Ed25519 keys. The signature is embedded in the attestation receipt, which becomes part of the CER bundle.

The signing key is what makes a node receipt trustable. It binds the node identity to the record at a specific point in time. Without it, receipts cannot be independently verified.

Key management matters because:

It defines whether receipts can be verified later.
It determines if old CERs survive a security incident.
It is a target for audit and compliance review.

Key Model

The node maintains a key ring with two categories of keys:

Active key. The single key currently used to sign new CER receipts. Identified by activeKid.
Deprecated keys. Previously active keys kept for verification only. They are not used for new signatures.

Every key has a kid (key identifier). The kid is included in every signed receipt so verifiers know which public key to use.

The node publishes its public keys at:

GET /.well-known/nexart-node.json

Example well-known response

{
  "nodeId": "nexart-node-primary",
  "activeKid": "k1",
  "keys": [
    {
      "kid": "k1",
      "algorithm": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA...",
      "status": "active"
    },
    {
      "kid": "k0",
      "algorithm": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA...",
      "status": "deprecated"
    }
  ]
}

Field definitions:

nodeId — unique identifier for the attestation node.
activeKid — the kid of the key currently used for signing.
keys[] — array of all known keys. Each entry contains:
- kid — key identifier. Must be unique within the node.
- algorithm — signing algorithm. Always Ed25519.
- publicKey — the public key material in base64.
- status — active or deprecated.

Verification Guarantees

The key system is designed so that rotation never breaks verification:

Old CERs remain verifiable after key rotation. Deprecated keys are retained until explicitly removed.
Verification accepts all known keys. The verifier matches the receipt kid against the published key set.
Certificate hashes are NOT affected by key rotation. The certificateHash is computed from the CER bundle content, not the signature.
Only signatures depend on keys. If a key is lost, previously signed receipts may become unverifiable. This is why deprecated keys are retained.

The NexArt Node acts as the independent trust authority. Verification does not rely on trusting platform storage or databases. It is performed using the signed receipt and the node's published public keys.

Key Rotation Process

Follow this procedure exactly. Do not skip steps.

Generate a new Ed25519 key pair.
Use a cryptographically secure source. The private key will be used for signing; the public key will be published.
Set the new key as NODE_ATTESTATION_PRIVATE_KEY.
This becomes the active signing key. The node will use it for all new receipts.
Move the previous key to NODE_ATTESTATION_DEPRECATED_KEYS.
Only the PUBLIC KEY is required for deprecated keys. Deprecated private keys must NOT be retained.
Deprecated keys are used for verification only. They do not require private key material. Retaining private keys beyond their active use increases security risk and is not permitted.
Deploy the node.
On startup, the node loads the active key and all deprecated keys. It publishes the public material at /.well-known/nexart-node.json.
Verify new CERs are signed with the new key.
Create a test CER and inspect the receipt. Confirm the kid matches the new activeKid.
Verify old CERs still verify.
Pick a CER signed before rotation and run it through the verifier. The receipt kid should match a deprecated key in the well-known document.
Monitor system behavior.
Watch for verification failures, key mismatch errors, or well-known endpoint latency.
Optionally remove deprecated keys after a safe period.
There is no fixed retention period. Remove a deprecated key only when you are confident no valid receipts depend on it. In practice, this means waiting until all CERs signed with that key have exceeded your retention policy.

When to Rotate Keys

Rotate keys in the following situations:

Suspected compromise. If a private key may have been exposed, rotate immediately. Treat this as an incident.
Periodic rotation. Recommended but optional. A reasonable interval is 12 months. More frequent rotation adds operational burden without proportional security benefit if the key is well-protected.
Security upgrades. If the host infrastructure changes (new platform, new secret store, new access controls), rotation reduces blast radius from any misconfiguration.

Deprecated public keys should be retained for at least the duration of the CER retention policy. Removing a key too early may prevent verification of historical records.

Security Considerations

Private keys must never be exposed. They are loaded from environment variables at runtime. They must not appear in logs, source control, or chat messages.
Keys are stored in Railway environment variables. Railway is the current host. Access to the Railway project must be restricted to authorized operators only.
Enforce two-factor authentication. Every account with Railway access must have 2FA enabled.
Limit access. Only operators who need to rotate keys should have project access. Review access quarterly.
Rotation must be controlled. Key rotation is not automated. It is performed by an operator following the procedure above. Document each rotation with date, reason, and operator identity.

Backward Compatibility

Key rotation is designed to be non-breaking:

Rotation does NOT break existing CER verification. Deprecated keys are kept in the well-known document.
Multi-key support ensures continuity. Verifiers check all published keys, not just the active one.
Verification remains deterministic. A CER verifies the same way today as it did the day it was signed, provided the key is still published.

Note: If a deprecated key is removed before all dependent CERs have expired, those CERs will fail signature verification. The certificateHash will still prove integrity, but the attestation witness will be unverifiable. Plan key removal against your retention policy.