Key Rotation & Emergency Revocation

WAB key material is rotatable by design. This page documents the routine rotation procedure, the emergency revocation procedure, and how downstream agents reconcile a rotation event.

1. Key kinds

Key	Owner	Used for	Routine cadence
Site Ed25519	Site operator	Signing `wab.json`, ATP receipts, intents	Recommended every 365 d
Site key-signing key (optional)	Site operator	Co-signing rotations of the Ed25519 key (anti-lockout)	3–5 years
Ring 4 anchor key	webagentbridge.com	Trust-graph attestations	Annual, scheduled
Webhook secret (HMAC)	Site operator	Stripe-style webhook auth	Per integration; rotate on suspicion

2. Routine site-key rotation

T-7 days — Announce next-key. The site publishes next_public_key inside the current wab.json, co-signed by the existing key.

T-0 — Cutover. The site replaces public_key with the previously announced next_public_key, signs the new manifest with the new key, and lists the old key under previous_keys with a valid_until timestamp.

T+30 days — Grace expires. Receipts signed by the old key after valid_until are rejected by compliant agents.

T+90 days — Old key drops out of the manifest. Historical receipts remain verifiable from archived manifest snapshots.

Example manifest during a routine rotation

{
  "schema_version": "wab/1",
  "site": "https://yourdomain.com",
  "public_key": "ed25519:NEW_KEY_BASE64",
  "previous_keys": [
    { "key": "ed25519:OLD_KEY_BASE64", "valid_until": "2026-06-25T00:00:00Z", "reason": "scheduled" }
  ],
  "next_public_key": null,
  "signature": "ed25519:SIG_BY_NEW_KEY"
}

3. Emergency revocation

Use this path when you believe the private key is — or may be — compromised. Speed matters more than ceremony.

Generate a new Ed25519 keypair on a clean host. Keep the private key offline until publishing.

Publish a revocation record at https://yourdomain.com/.well-known/wab-revocations.json:

{
  "site": "https://yourdomain.com",
  "revoked": [
    { "key": "ed25519:COMPROMISED_BASE64", "revoked_at": "2026-05-25T12:00:00Z", "reason": "key_compromise" }
  ],
  "new_public_key": "ed25519:NEW_BASE64",
  "signature_by_new_key": "ed25519:SIG",
  "signature_by_dns_proof": "see wab.json TXT"
}

Update DNS TXT at _wab.<domain> with the new public key. DNS propagation determines how quickly off-graph agents pick up the change; we recommend a TTL of 300 s on this record.
Replace /.well-known/wab.json with a manifest signed by the new key, listing the compromised key in previous_keys with reason="key_compromise" and valid_until set to the revocation timestamp.
Notify Ring 4 via POST /api/trust/revoke (signed by the new key). The trust graph propagates the revocation to attested agents within minutes.
Audit receipts signed by the old key between the suspected compromise window and the revocation timestamp. Anything outside scope or above ambient compensation rate should be reviewed.

4. Agent behavior during/after rotation

On every discovery refresh (default TTL ≤ 1 h), agents re-fetch wab.json and check previous_keys + /.well-known/wab-revocations.json.
Receipts signed by a key listed in previous_keys with reason="key_compromise" are flagged distrusted from revoked_at forward.
Receipts signed during the grace window (routine rotation) remain valid.
Agents must reject manifests whose signature does not validate against public_key, even if cached. No silent downgrade.

5. Ring 4 anchor rotation

The Ring 4 anchor key (held by webagentbridge.com) follows a stricter procedure:

New anchor key is generated and committed in a public transparency log 30 days before activation.
Cross-signed by the previous anchor for a 90-day overlap.
Listed in DNS at _anchor.webagentbridge.com with both the old and new keys during overlap.
Old anchor key is retired and listed under previous_anchors with valid_until.

Emergency anchor rotation (compromise of the Ring 4 root) requires a published, signed statement from the foundation, an out-of-band public announcement, and an attested transparency-log entry. Trust scores from before the compromise event are recomputed.

6. Webhook secret rotation

Webhook HMAC secrets are rotated by your provider (e.g. Stripe). On the WAB side, support two secrets in parallel for at least 30 days: the operator pastes the new one into the dashboard, requests roll the old one out, and the system tries both during the overlap. Reject anything that matches neither.

7. Operator checklist

☐ Offline backup of the site Ed25519 private key (encrypted, two locations).
☐ Key-signing key (optional but recommended) on a separate device.
☐ DNS TXT TTL ≤ 300 s for _wab records.
☐ Routine rotation calendar entry annually.
☐ Runbook for emergency revocation tested at least once per year (table-top is fine).
☐ security@ contact wired to a human, not a forwarding void.

8. Document history

2026-05-25 — Initial publication.