Key Rotation For Agent DIDs: Surviving Compromise Without Identity Loss

TL;DR

Keys get compromised. Insider threats, supply chain attacks, deployment misconfigurations, and bugs in cryptographic libraries all create paths to key exposure. The agent's DID must survive these events without identity loss, because losing the DID means losing the accumulated reputation, credentials, and pact history bound to it. The mitigations are well-understood: separation of key concerns at the verification method level, scheduled rotation on a predictable cadence, emergency rotation triggered by detection, and multi-key DID documents that allow incremental rotation without forcing buyers to re-verify. This essay walks through the rotation patterns, the failure modes during rotation, and the operational runbook that turns rotation from a panic event into a planned exercise. The reader artifact is a complete Key Rotation Runbook that operators can adapt for their own agents.

The Failure Mode That Forces The Pattern

A developer-tooling agent had been operating for fourteen months with a single Ed25519 key handling all signing duties: DID document updates, pact commitments, runtime authentication, and credential issuance acknowledgments. The key was stored in an environment variable on the agent's deployment infrastructure. A junior engineer accidentally committed the deployment configuration to a public repository for ninety seconds before deleting and force-pushing. A scraper picked up the key during the exposure window. Two days later the key began appearing in pact signatures the operator had not authorized, on a different infrastructure, signing commitments to obligations that would damage the agent's reputation if executed.

The operator's options were grim. Revoke the key in the DID document and break every existing pact, every issued credential, every authentication session. Migrate to a new DID and lose the accumulated reputation that had made the agent valuable. Try to coordinate a multi-day rotation while the attacker continued to issue unauthorized signatures. Each option carried significant cost. The compromise had not just exposed a key; it had revealed that the agent's identity infrastructure had no graceful path through a compromise event. The single key had created a single point of failure, and the failure had no recovery mechanism that preserved identity continuity.

This is the rotation failure mode that operators discover only when they need rotation and find they cannot do it without breaking everything. The infrastructure was set up for the happy path: register the agent, sign things with the key, never think about the key again. The failure path requires ceremony, planning, and pre-built infrastructure that the operator did not have. Building the infrastructure during the compromise event is too slow and too error-prone.

The correct posture is to design for rotation from the start. Multiple keys with separated concerns, so a compromise of one key does not require rotating all of them. A multi-key DID document that allows old and new keys to coexist temporarily, so verifiers can transition smoothly. A scheduled rotation cadence that exercises the rotation infrastructure regularly, ensuring it works when needed. An emergency rotation procedure documented and tested, so the response to a real compromise is mechanical rather than improvised. Together these elements turn rotation from a feared event into a routine operation.

This essay is about how to build that posture. The patterns apply equally to agents that operate at small scale (a single developer running one agent) and to agents that operate at platform scale (a hosted agent platform managing thousands of identities). The specifics differ; the principles are the same. The reader artifact at the end is a runbook operators adopt as the basis for their own rotation procedures. The intermediate sections walk through the design patterns, the operational mechanics, and the failure modes that the runbook is built to handle.

H2 1: The Three Keys Every Agent Should Have

The first design principle for rotation-friendly agents is to separate concerns across multiple keys. A single key that signs everything creates a single point of failure: any compromise affects everything the key has signed. Separating concerns means a compromise of one key affects only the artifacts that key was authorized to sign. The blast radius is bounded.

The three keys every agent should have are the controller key, the assertion method key, and the session key. Each has a specific role, a specific rotation cadence, and a specific compromise response.

The controller key is the agent's root authority. It signs DID document updates, including the rotation of all other keys. It is the most sensitive key the agent holds. It is the key that, if compromised, allows an attacker to fully impersonate the agent at the identity layer. The controller key should be stored with the highest possible security: in a hardware security module for self-hosted agents, in a managed key service with strict access controls for cloud-hosted agents. The controller key should rotate rarely, on a planned schedule (typically annually), with explicit pre-announcement to verifiers.

The assertion method key signs verifiable credentials issued to the agent and signs commitments the agent makes to pacts. It is sensitive but less critical than the controller key: a compromise allows an attacker to sign credentials and commit to pacts in the agent's name, but does not allow them to update the DID document or rotate other keys. The assertion method key should rotate quarterly to limit the window during which a hidden compromise could have been exploited. The rotation is straightforward: the controller key signs an update to the DID document that adds the new assertion method key and removes the old one.

The session key signs runtime authentication challenges. It is the lowest-sensitivity of the three: a compromise allows an attacker to impersonate the agent in active sessions but not to sign credentials, commit to pacts, or update the DID document. The session key should rotate frequently, typically on a daily or weekly cadence, and ideally on every infrastructure deployment. Frequent rotation limits the window during which a stolen key remains useful.

The separation has multiple benefits. First, it bounds compromise impact: an attacker who steals the session key cannot sign new credentials or pacts in the agent's name. Second, it allows independent rotation cadences: the rarely-changing controller key does not have to be rotated every time the session key is. Third, it enables defense in depth: the controller key can be air-gapped or stored in a hardware module, while the session key can be deployed as a software key with normal infrastructure access. The controller key compromises become extremely rare because the controller key is not present in normal infrastructure.

The DID document expresses this separation through verification relationships. The controller key is referenced from capabilityInvocation, indicating it can sign DID document updates. The assertion method key is referenced from assertionMethod, indicating it can sign credentials and pact commitments. The session key is referenced from authentication, indicating it can sign authentication challenges. Each key's authority is explicit and bounded by its verification relationship. A verifier checking a signature looks up the key in the appropriate relationship and rejects signatures by keys not authorized for the operation.

In practice, agents may have more than three keys: encryption keys for confidential communication, additional assertion keys for different credential issuers or pact contexts, backup keys for recovery scenarios. The principle remains: separate concerns by purpose, with each key authorized for its specific role and rotated on a cadence appropriate to its sensitivity.

H2 2: Scheduled Rotation: The Boring Path That Keeps Things Working

Scheduled rotation is the routine operation that keeps the rotation infrastructure exercised and known-good. The schedule is the cadence at which keys are rotated regardless of whether a compromise has occurred. Without scheduled rotation, the rotation infrastructure rusts: it works in test environments but breaks the first time it is exercised in production under stress. With scheduled rotation, the infrastructure is exercised regularly and the operators are practiced.

The cadence depends on the key type. Controller keys rotate annually. Assertion method keys rotate quarterly. Session keys rotate weekly or per-deployment. The cadences should be calendared, with reminders triggered before each rotation. The rotation itself should be automated to the extent possible, with human oversight for the controller key rotations and full automation for session key rotations.

The scheduled rotation procedure has six steps: generate the new key, validate the new key, update the DID document to add the new key, wait for propagation, deactivate the old key, archive the old key. Each step is mechanical and can be scripted.

Generating the new key uses the same cryptographic library and parameters as the current key. The new key must be generated in a secure environment: for controller keys, in the hardware security module; for assertion method keys, in the managed key service; for session keys, in the deployment pipeline's secret management infrastructure. The generation should be deterministic in its security properties: same algorithm, same parameter sizes, same randomness source.

Validating the new key checks that it can sign and verify correctly, that the public key is well-formed, and that the private key is properly stored. A round-trip test with a sample message catches most key generation problems before they become production incidents. The validation should be part of the rotation script, not a manual step.

Updating the DID document adds the new key as a new verification method entry, references it from the appropriate verification relationship, and signs the updated document with the controller key. The update is published to the DID's resolution endpoint. For did:web DIDs, this is uploading the new document to the well-known location. For did:armalo DIDs, this is calling the platform's update API. The old key remains in the document during this step: both old and new are valid simultaneously.

Waiting for propagation gives verifiers time to refresh their cached DID documents. The wait is bounded by the maximum cache TTL of any verifier likely to interact with the agent. For agent ecosystems with cache TTLs in the minutes range, the wait is also in the minutes range. For ecosystems with longer cache TTLs, the wait is longer. The propagation wait is what makes the rotation graceful: verifiers transition from old to new without a window where neither is recognized.

Deactivating the old key removes it from the DID document, signed by the controller key. From this point, signatures by the old key no longer verify against the document. New signatures must use the new key. Existing signatures from before the rotation continue to be verifiable using historical document snapshots, which the resolver can serve for audit purposes.

Archiving the old key moves it to long-term storage where it remains available for forensics but is not used for active signing. The archive should be access-controlled, encrypted, and audit-logged. The old key may need to be referenced months or years later if a question arises about historical signatures, so destroying it would harm auditability.

The whole procedure, fully automated, takes minutes for session key rotations and hours for controller key rotations (mostly waiting for propagation). The frequency of execution keeps the procedure familiar to operators. When an emergency rotation is needed, the same procedure runs faster but follows the same path. The familiarity is what makes emergency response work.

H2 3: Emergency Rotation: When Detection Triggers Action

Emergency rotation is the response to a detected or suspected compromise. The procedure is similar to scheduled rotation but compresses the timeline and adds explicit escalation. The trigger is detection: an unexpected signature, a key file appearing in an unexpected location, a security tool flagging anomalous access. The response must be fast because every minute of attacker access is a minute of potential damage.

The emergency rotation procedure has eight steps: triage the trigger, isolate the compromised key, generate the replacement, update the DID document, propagate, broadcast emergency notification, revoke pacts and credentials signed by the compromised key during the suspect window, post-incident review.

Triage establishes whether the compromise is real and which key is affected. False positives are common: a security alert may indicate suspicious activity that turns out to be authorized. Real positives must be confirmed quickly. The triage typically involves checking signatures against expected sources, examining access logs, and consulting the security team. A confirmed compromise moves immediately to the next step. An uncertain trigger may proceed conservatively as if confirmed, with later steps adjusted if the trigger turns out to be benign.

Isolating the compromised key prevents further use. For session keys this may mean revoking infrastructure access. For assertion method keys this may mean disabling the signing service that uses the key. For controller keys, isolation is more invasive and may require a planned downtime window. The isolation prevents the attacker from continuing to use the key while the rotation is in progress.

Generating the replacement follows the same procedure as scheduled rotation but is executed faster. The replacement key should be generated in a clean environment that has not been exposed to the compromise. If the compromise was through infrastructure access, the new key may need to be generated in a freshly provisioned environment. The added care is appropriate because reissuing in a compromised environment risks the new key being compromised before it is even used.

Updating the DID document is the same operation as scheduled rotation. The signed update adds the new key and removes the old. For emergency rotation, the document update should also include a revokedKeys annotation listing the compromised key with a revocation timestamp, so verifiers consulting historical signatures can distinguish signatures from before the compromise (which may still be trusted) from signatures during the compromise window (which should be assumed forged).

Propagation in emergency rotation may require active push to known verifiers in addition to passive polling. High-stakes verifiers can subscribe to emergency notification channels: webhooks, alert feeds, pub/sub topics. The push notification accelerates propagation for the verifiers who matter most, even though the underlying DID document update reaches all verifiers eventually through normal polling.

Broadcasting emergency notification informs the broader ecosystem. The notification should specify the compromised key, the suspect window, the affected credentials and pacts, and the new key being authorized. The notification should be publicly archived so verifiers can confirm authenticity and timing. The Armalo platform operates an emergency notification channel for compromise events that affect agents on the platform.

Revoking pacts and credentials signed by the compromised key during the suspect window is the cleanup step. Any pact signed by the compromised key during the window is now of uncertain authenticity: it may be a legitimate commitment by the operator or a forged signature by the attacker. The conservative response is to revoke all pacts in the window and explicitly re-sign legitimate ones with the new key. Credentials issued by an evaluator using a compromised assertion method key fall into the same category and should be revoked through the issuer's status list mechanism.

Post-incident review captures what happened, what worked, what did not, and what should change. The review is essential for improving the response. Every emergency rotation is a learning event. The runbook should be updated with the lessons. The infrastructure should be improved based on the failure modes encountered. The next emergency rotation should be smoother because of the lessons from this one.

H2 4: Multi-Key Documents And The Coexistence Window

The multi-key DID document is what makes graceful rotation possible. By allowing multiple verification methods of the same type to coexist, the document supports a transition window where both old and new keys are valid simultaneously. Verifiers can use either, and the agent's signing infrastructure can switch from old to new without breaking verifier trust.

The pattern is simple. The verification methods array contains entries for both keys. The verification relationships reference both. Verifiers parsing the document accept signatures from either key. The agent uses the new key for new signatures while the old key remains in the document.

The coexistence window has a specific duration: long enough for verifiers to refresh their cached documents and notice the new key, short enough that the old key is removed before any compromise that motivated the rotation can be exploited further. Typical coexistence windows are minutes for session keys (matching the typical cache TTL), hours for assertion method keys, days for controller keys.

Within the window, the agent should preferentially use the new key but tolerate signatures by the old key for legacy operations that started before the rotation. After the window, the old key is removed from the document and signatures by it no longer verify. New operations must use the new key.

This pattern handles a subtle problem: in-flight transactions that began before the rotation but complete after. A pact signature created with the old key just before rotation may need to be verified by a buyer who fetches the DID document just after rotation. If the rotation removed the old key immediately, the signature would fail to verify. The coexistence window keeps the old key valid long enough for in-flight signatures to complete verification successfully.

A related pattern is the signature timestamp annotation. Each signature should include a timestamp indicating when the signature was created. Verifiers can use the timestamp to determine which key was active at signature time and verify against that key even if the key has since been removed from the document. This requires the resolver to maintain historical document snapshots, which is the standard pattern for DID resolution. Combined with the coexistence window, this makes rotation transparent to almost all verifiers and operations.

The edge case is verifying a signature whose timestamp falls within the coexistence window where both keys were valid. The verifier may not know which key was used (some signature schemes do not include the public key in the signature) and may need to try both. This is operationally trivial: try the new key first, fall back to the old. The cost is one extra signature verification, which is microseconds.

Multi-key documents also support intentional dual-key operation outside of rotation. An agent that operates across multiple environments (production, staging, disaster recovery) may have separate keys per environment, with all keys listed in the document and used contextually. This is not the rotation pattern but uses the same document infrastructure. The document supports any number of verification methods, each with its own purpose.

H2 5: The Key Rotation Runbook Template

This is the reader artifact: a complete runbook that operators adopt as the basis for their own rotation procedures. The runbook covers scheduled and emergency rotation for all three key types, with the operational details that make the procedures repeatable.

The top of the runbook declares the agent DID, the runbook version, and the responsible operator. Versioning matters because procedures evolve and the version captures which procedure was in effect at any given time.

The key inventory section lists the keys the agent maintains, with each key's identifier, type, current rotation status, current rotation cadence, and storage location. The inventory is the single source of truth for what keys exist and where they are.

The scheduled rotation section enumerates the rotation procedures for each key type. For each procedure: the trigger (calendar date, deployment event), the steps (in order), the expected duration, the post-rotation validation, and the rollback procedure if anything goes wrong.

The emergency rotation section covers the same ground for emergency triggers: detected compromise, suspected compromise, security tool alert, third-party report. For each trigger: the triage criteria, the escalation procedure, the rotation steps, the notification recipients, and the post-incident review template.

The contact and escalation section lists the operators authorized to execute each procedure, the on-call rotation, the security team contact, and the platform support contact. Emergency procedures can require multiple authorized parties; the contact list ensures the right people can be reached quickly.

The sample runbook:

runbookVersion: "3.0"
agentDid: "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f"
responsibleOperator: "ops@example.com"
lastTested: "2026-08-22"

keyInventory:
  - keyId: "#controller"
    type: "Ed25519VerificationKey2020"
    purpose: "controller"
    rotationCadence: "annual"
    storage: "hsm:cluster-prod-01"
    lastRotated: "2026-02-15"
    nextRotationDue: "2027-02-15"
  - keyId: "#assertion"
    type: "Ed25519VerificationKey2020"
    purpose: "assertionMethod"
    rotationCadence: "quarterly"
    storage: "kms:armalo-prod"
    lastRotated: "2026-07-01"
    nextRotationDue: "2026-10-01"
  - keyId: "#session-2026-09"
    type: "Ed25519VerificationKey2020"
    purpose: "authentication"
    rotationCadence: "weekly"
    storage: "deployment-secrets:current"
    lastRotated: "2026-09-04"
    nextRotationDue: "2026-09-11"

scheduledRotation:
  controller:
    trigger: "calendar-date-or-manual"
    steps:
      - "generate-new-key-in-hsm"
      - "validate-new-key"
      - "add-new-key-to-did-document"
      - "sign-document-update-with-existing-controller-key"
      - "publish-updated-document"
      - "wait-7-days-for-propagation"
      - "verify-new-key-recognized-by-test-verifiers"
      - "remove-old-controller-key-from-document"
      - "sign-with-new-controller-key"
      - "publish-final-document"
      - "archive-old-key"
    expectedDuration: "7-days-elapsed-30-min-active"
    validation: "controller-key-rotation-test-suite"
    rollback: "restore-previous-document-from-snapshot"
  assertion:
    trigger: "calendar-date-or-manual"
    steps:
      - "generate-new-key-in-kms"
      - "validate-new-key"
      - "add-new-key-to-did-document"
      - "sign-document-update-with-controller-key"
      - "publish-updated-document"
      - "wait-2-hours-for-propagation"
      - "switch-credential-issuance-to-new-key"
      - "remove-old-assertion-key-from-document"
      - "publish-final-document"
      - "archive-old-key"
    expectedDuration: "2-hours"
  session:
    trigger: "weekly-cron-or-deployment"
    steps:
      - "generate-new-key-in-deployment-pipeline"
      - "deploy-new-key-to-runtime"
      - "add-new-key-to-did-document"
      - "sign-document-update-with-controller-key"
      - "publish-updated-document"
      - "wait-15-minutes-for-propagation"
      - "switch-runtime-authentication-to-new-key"
      - "remove-old-session-key-from-document"
      - "publish-final-document"
    expectedDuration: "30-minutes"

emergencyRotation:
  triggers:
    - "unexpected-signature-detected"
    - "key-file-found-in-public-location"
    - "security-tool-alert"
    - "third-party-compromise-report"
    - "unauthorized-pact-signature-claimed"
  triagePeriodMaxMinutes: 30
  procedure:
    immediate:
      - "isolate-compromised-key"
      - "freeze-affected-signing-services"
      - "page-on-call-and-security-team"
    within-1-hour:
      - "generate-replacement-key-in-clean-environment"
      - "add-new-key-to-did-document"
      - "sign-update-with-controller-key-or-emergency-recovery-key"
      - "publish-updated-document-with-revoked-keys-annotation"
      - "send-emergency-notification"
    within-24-hours:
      - "revoke-pacts-signed-by-compromised-key-in-suspect-window"
      - "revoke-credentials-signed-by-compromised-key-in-suspect-window"
      - "audit-historical-signatures-for-anomalies"
      - "prepare-post-incident-review"
  notificationRecipients:
    emergencyChannel: "https://armalo.ai/api/v1/emergency-notify"
    knownVerifiers: "webhook-subscribers"
    publicAnnouncement: "https://example.com/security-bulletins"

contactAndEscalation:
  primaryOperator: "ops@example.com"
  onCallRotation: "https://example.com/oncall"
  securityTeam: "security@example.com"
  armaloSupport: "trust-ops@armalo.ai"
  authorizedRotationApprovers:
    - "ops@example.com"
    - "security@example.com"

This runbook is the operational artifact operators maintain. It is reviewed annually, tested quarterly through scheduled rotations, and exercised whenever an emergency occurs. The runbook is the source of truth for what to do; the operators executing it follow the steps without improvisation, which is what makes rotations reliable under stress.

H2 6: Recovery Keys And The Bootstrap Problem

The controller key is the root authority for all other key rotations. If the controller key is itself compromised, what authority signs the rotation that replaces it? This is the bootstrap problem of key rotation: the highest-privilege key has no higher authority that can rotate it on its own.

The traditional solution is the recovery key, a separate key held in deeper storage that has authority to update the DID document but is not used for any other purpose. The recovery key's job is to recover from a controller key compromise. If the controller is compromised, the recovery key signs an update that adds a new controller and removes the old. The recovery key returns to deep storage. Normal operations resume with the new controller.

The recovery key faces the same single-point-of-failure problem at one level removed. If the recovery key is compromised along with the controller key, recovery becomes impossible without abandoning the DID. The mitigation is to store the recovery key with extreme care: in a hardware security module that is physically isolated, with access requiring multiple authorized parties, with automatic alerting on any access attempt. The recovery key is touched only during recovery events, which should be rare.

For operations that cannot tolerate single-key recovery failure, multi-signature recovery is the answer. The DID document declares a recovery quorum: a set of recovery keys, with a threshold number required to authorize a controller rotation. Compromise of fewer than threshold keys does not enable recovery. This is operationally heavier but provides resilience against compromise of individual recovery keys.

The Armalo platform supports a recovery key configuration where operators can designate a single recovery key (the default) or a multi-signature quorum. The platform also offers a recovery service for hosted agents where the platform itself holds the recovery key, with strong commitments about how that key is protected and used. Operators choose the model that matches their risk tolerance.

Cross-organization recovery is the deepest version of the pattern. The recovery key (or quorum) is held by a trusted third party, separate from the agent operator's organization. This guards against the failure mode where a compromise of the operator's own infrastructure compromises both the controller and the recovery key. The third party introduces governance complexity (who can authorize a recovery, under what circumstances) but provides the strongest defense against catastrophic operator compromise.

The recovery key, however configured, must itself be tested. A recovery procedure that has never been exercised in practice will fail when needed. Quarterly recovery drills (rotating to a new controller key using the recovery key, then rolling back) keep the procedure familiar and catch infrastructure rot. The drill is an inconvenience; the alternative is discovering recovery does not work during a real compromise.

The operator who has set up recovery keys, tested them quarterly, documented the recovery procedure, and confirmed all recovery key holders can be reached in an emergency has set up recovery correctly. The operator who has a recovery key in an envelope in a desk drawer that no one has opened in three years has set up recovery wrong. The difference is exercise. Recovery infrastructure that is not exercised is recovery infrastructure that does not work.

H2 7: Verifier Behavior During Rotation

The verifier's experience during a rotation depends on the verifier's caching strategy and freshness requirements. A verifier with a short cache TTL sees the rotation quickly and adapts. A verifier with a long cache TTL may use the old key for some period after the rotation has completed. The protocol must handle both cases gracefully.

During the coexistence window, both keys are valid in the DID document and verifiers should accept signatures from either. After the window, the old key is removed and only the new key is valid for new signatures. Historical signatures created before the rotation should still be verifiable through the resolver's historical document support: the resolver can serve the document state as of any past timestamp, allowing verification of signatures against the keys that were valid at signature time.

The verifier should refresh their cached DID document on a schedule that matches the issuer's expected rotation cadence. For agents with frequent session key rotation, the verifier's cache TTL should be short enough that the verifier sees session key changes within the typical session duration. For agents with rare controller key rotation, longer cache TTLs are acceptable.

The verifier should also handle the rotation transition gracefully when it is in progress. A signature that fails to verify against the cached document key should trigger a document refresh and a retry, in case the failure is due to a key the verifier has not yet seen. After the retry, persistent failures should be treated as actual signature failures. This pattern handles the case where the verifier's cache is stale during a rotation without permanently rejecting valid signatures.

For emergency rotations with revokedKeys annotations, the verifier should treat signatures by revoked keys as invalid even if they were created during the suspect window. This is the conservative response to a confirmed compromise: assume the worst about signatures from the compromised key. Operators who have legitimate signatures in the suspect window must re-sign them with the new key to restore their validity.

The verifier's logging should capture rotation events for audit. A document update that adds or removes verification methods is a meaningful event. Logging it helps the verifier reconstruct the agent's identity history if questions arise later. The log should include the timestamp, the document version (or hash), and the changes observed. Over time, the log becomes a record of how the agent's identity has evolved.

Verifier libraries should make rotation handling automatic. The Armalo verifier library refreshes documents on cache expiration, accepts signatures from any verification method present in the current document, falls back to historical documents for signatures with timestamps in the past, and surfaces rotation events to the application layer through structured callbacks. Applications that want to react to rotations (re-pinning to new keys, alerting on unexpected rotations) can subscribe to the callbacks. Applications that do not care can ignore them.

H2 8: Rotation Hygiene And Long-Term Posture

Rotation is not a one-time setup; it is an ongoing discipline. The infrastructure must be maintained, the procedures must be exercised, and the operators must be trained. Long-term rotation hygiene is what distinguishes operators who stay safe from operators who get caught flat-footed.

Regular rotation drills exercise the infrastructure and the operators. A quarterly drill that walks through a controller key rotation, even when no rotation is actually needed, keeps the procedures familiar. The drill should follow the runbook exactly, including the validation steps and the rollback procedures. Any failure or surprise during the drill is a finding to be addressed before the next real rotation.

Key storage audits verify that keys are stored as the inventory says they are. A key that is supposed to be in an HSM but is actually in a configuration file is a critical finding. Audits should be periodic (annually at minimum) and should sample key locations directly rather than just consulting the inventory documentation.

Access audits verify that only authorized parties can access keys. An access list that has not been reviewed in a year may include former employees, terminated contractors, or service accounts that no longer need access. Quarterly review of access lists, with explicit removal of unneeded access, prevents the slow accumulation of unnecessary access that creates compromise risk.

Deprecation policies ensure that old keys do not linger. A key that has been removed from the DID document but is still active in storage may be inadvertently used or compromised. The archive procedure should include explicit deactivation: the key is moved to an archive that is read-only and cannot be used for signing. Any attempt to use an archived key fails immediately.

Incident retrospectives capture lessons from real and drilled rotations. A retrospective document should be written after every emergency rotation and after every drill that surfaced any issue. The retrospective should identify what worked, what did not, and what should change. The runbook should be updated based on the retrospective findings. Over time, the retrospectives create an institutional memory of how rotations have gone and what improvements have been made.

Cryptographic agility planning considers what happens when the underlying cryptographic primitives need to change. Ed25519 may eventually be deprecated in favor of post-quantum signature schemes. The DID document and the rotation infrastructure should be able to handle the migration. The verification methods array supports multiple key types, so adding a new type alongside existing ones is straightforward. The deeper challenge is the ecosystem coordination: verifiers must support the new type before agents can transition to it. Planning for this transition years in advance keeps the eventual migration smooth.

The operator who has invested in rotation hygiene has a posture that is resilient to compromise. The operator who has not is one bad day away from identity loss. The investment is moderate: a few engineer-days per quarter for drills, audits, and reviews. The return is substantial: the difference between graceful recovery and catastrophic loss when a compromise eventually occurs.

Counter-Argument And Answer

The steelman objection to elaborate key rotation infrastructure is that it adds operational complexity for a low-probability event. A skeptic argues that most agents will never experience a key compromise, that the rotation infrastructure is only relevant in the rare case when it is needed, and that the engineering investment is better spent on features that affect every transaction rather than on infrastructure that affects almost none.

The answer is that key compromise is a low-probability, high-impact event. The expected cost of a compromise (probability times impact) can be substantial even if the probability is low. An agent that loses identity continuity after a compromise loses years of accumulated reputation, all issued credentials, all pact history, and the buyer relationships that depended on them. The rebuild cost, in time and lost trust, can be larger than the agent's entire previous lifetime of investment. The expected cost calculation favors investment in rotation infrastructure even at modest probabilities.

The complexity argument also overstates the actual operational burden. The runbook this essay describes is on the order of a few hundred lines of YAML and a few hundred lines of automation code. The drills take a few engineer-hours per quarter. The audits take a few engineer-days per year. For an agent with significant accumulated reputation, this is rounding error in the operational budget. The complexity is fixed cost; the protection is proportional to the agent's identity value.

The deeper objection is that rotation infrastructure may itself be a source of compromise: misconfigured rotation could destroy keys or break verifier trust without an actual compromise. This is true and is why the infrastructure must be exercised regularly. The drilled, tested rotation infrastructure is far less risky than the never-tested one. Drills surface configuration errors before they cause real damage. Drills give operators experience that prevents panic-driven mistakes during real incidents. The risk is in untested infrastructure, not in the existence of the infrastructure.

The practical advice is to scale the investment to the agent's identity value. A new agent with no accumulated reputation can use a single key with manual rotation procedures. As the agent accumulates reputation, the investment scales: separation of concerns, then scheduled rotation, then emergency rotation, then recovery infrastructure. Each step matches a level of identity value worth protecting. Agents that grow in value should grow in rotation maturity. Agents that never grow in value can stay simple. The pattern is proportional, not absolute.

What Armalo Does

The Armalo platform issues agents with three keys by default: a controller key, an assertion method key, and a session key. The DID document is populated with all three at registration, with appropriate verification relationship grants for each. The platform manages key storage in AWS KMS for hosted agents, with controller keys backed by additional access controls.

Scheduled rotation is automated for hosted agents on the platform's default cadences: annual for controller keys, quarterly for assertion method keys, weekly for session keys. Operators can override the cadences in agent settings if they have specific requirements. The rotation procedure publishes updated DID documents through the did:armalo resolver and refreshes platform-side caches.

Emergency rotation can be triggered through the agent's security dashboard or programmatically through the @armalo/agent-sdk library. The emergency procedure follows the runbook pattern documented in this essay, with platform-managed steps for hosted agents and operator-executed steps for self-hosted agents.

Recovery keys are configurable through the agent settings. Operators can designate a single recovery key, a multi-signature quorum, or use the platform's managed recovery service. Recovery procedures are tested quarterly through automated drills.

The complete key rotation workflow, from initial setup through emergency response, is documented at https://armalo.ai/docs/key-rotation with worked examples and SDK snippets.

FAQ

What happens to historical signatures after a key is rotated?

Historical signatures continue to verify against the keys that were valid at signature time. The resolver maintains historical document snapshots so verifiers can fetch the document state as of a past timestamp. A signature with an associated timestamp can be verified against the historical document at that timestamp.

Can a single key be used for multiple verification relationships?

Technically yes, but it is poor practice. A key authorized for both assertionMethod and capabilityInvocation can sign credentials and update the DID document. A compromise of that key gives the attacker both capabilities. Separating concerns by key bounds the blast radius of any single compromise.

How long should the coexistence window be during rotation?

Long enough for verifiers to refresh their cached DID documents. Typical values are minutes for session keys, hours for assertion method keys, days for controller keys. The window should match the longest expected verifier cache TTL plus a safety margin.

What happens if the controller key is lost rather than compromised?

Loss is recovered through the recovery key (if configured) or through migration to a new DID with explicit cross-references (if no recovery is configured). Migration to a new DID loses identity continuity, which is why recovery keys are recommended for any agent with significant accumulated reputation.

Can rotation be paused mid-procedure?

Yes. The procedure has well-defined intermediate states (new key added but old not yet removed, in particular) where the system is fully functional. Pausing in this state is safe. Resuming and completing the procedure is straightforward. This makes the rotation tolerant to operator interruptions or infrastructure issues during the procedure.

How do verifiers know when a rotation has happened?

They see the updated DID document on their next refresh. The document includes timestamps for each verification method (when added) and any revocation annotations (for emergency rotations). Verifiers comparing successive document versions can detect what changed.

What is the minimum viable rotation infrastructure?

For an agent with limited operational maturity, the minimum viable setup is two keys (a controller and a session key), a manual rotation procedure documented in a checklist, and quarterly drill events to exercise the procedure. As the agent's operational maturity grows, additional keys, automation, and recovery infrastructure can be added incrementally.

Bottom Line

Key rotation is the discipline that lets agent identity survive the inevitable compromise. The patterns are well-understood: separate concerns by key, schedule routine rotation, prepare emergency rotation, configure recovery keys, exercise the infrastructure regularly. Without rotation infrastructure, a single compromise can destroy years of accumulated reputation. With it, compromise becomes a managed event whose impact is bounded by the design choices made before the compromise occurred. The runbook in this essay is the operational starting point. The investment is moderate. The protection is proportional to the agent's identity value. For any agent expected to operate long enough to accumulate meaningful reputation, the investment is mandatory.