Authority key rotation

When to rotate

• Suspected exposure of the authority signing key.
• Scheduled hygiene rotation (recommended every 12 months).
• Personnel change with access to the publisher key material.

What is preserved

• The authority URI (aarmos://authority/<slug>) — never changes on rotation. Only aarmos authority init mints a new URI.
• The manifest sequence — stays monotonic across rotation. The next publish emits sequence + 1, signed with the new key.
• Historical receipts referencing the previous fingerprint remain verifiable — the old public key stays in the archived trust set.

What changes

• The publisher fingerprint (Ed25519 public-key SHA-256).
• Every subscriber pinned to the previous fingerprint MUST re-pin to the new one — this is a deliberate, ADR-0002-consistent trust-on-change step (no transitive trust, no auto-rotation).

Steps

1. Confirm the current authority and fingerprint:

   aarmos authority show

   Copy
2. Rotate the signing key. The URI and stored authority record are preserved:

   aarmos authority key rotate

   Copy
   The command prints the old and new fingerprints.
3. Publish a fresh manifest signed with the new key. The sequence advances by one automatically:

   aarmos authority publish --out authority-manifest.json

   Copy
4. Distribute the new manifest (Git, CDN, wherever your subscribers fetch from). Announce the new fingerprint on your existing trust-channel (release notes, security page).
5. Every subscriber re-pins the new fingerprint:

   aarmos trust manifest subscribe authority-manifest.json

   Copy
   The verifier refuses the manifest until the new fingerprint is pinned — this is the deliberate ADR-0002 trust-on-change step.

Verification checklist

• aarmos authority verify authority-manifest.json succeeds under the new fingerprint.
• aarmos authority show reports the new key fingerprint but the unchanged URI and monotonic sequence.
• A pre-rotation receipt still verifies (old fingerprint stays in the archived trust set).
• A post-rotation receipt verifies against the new manifest and chains cleanly to the previous sequence.

Related

• Entitlement signing secret rotation — different key, different lifecycle; do not confuse the two.
• AVAR spec — canonical wire format for manifests and receipts.