rotate-key

Add a new signing key to an existing issuer. The previous keys are retained in the JWKS so that older event signatures remain verifiable.

Usage

ak rotate-key --domain <DOMAIN> --issuer-dir <PATH> --kid <KID> [OPTIONS]

Flags

Flag	Required	Default	Description
--domain <DOMAIN>	Yes	—	Issuer domain.
--issuer-dir <PATH>	Yes	—	Path to the issuer directory containing .well-known.
--kid <KID>	Yes	—	Key ID for the new signing key.
--seed-hex <HEX>	No	Random	32-byte hex seed for deterministic key generation.

Behavior

• Generates a new Ed25519 signing key and adds it to the issuer’s JWKS.
• Updates the DID document with a new verification method for the key.
• Retains all existing keys so that previously signed events can still be verified.
• Rejects the operation if the provided --kid value already exists in the JWKS, preventing accidental key ID collisions.

Example

ak rotate-key \
  --domain example.com \
  --issuer-dir ./issuer-root \
  --kid orgsign-2 \
  --seed-hex aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899

Output:

Added key "orgsign-2" to issuer did:web:example.com
  Updated JWKS:     ./issuer-root/.well-known/jwks.json
  Updated DID doc:  ./issuer-root/.well-known/did.json

Notes

• Use descriptive, sequential key IDs (e.g., orgsign-1, orgsign-2) to keep track of key generations.
• Old keys should not be removed from the JWKS unless you are certain no events reference them.
• After rotation, new events should be signed with the latest key by specifying its --kid in append-upsert or append-revoke.