Skip to Content
KERI Deep DiveDuplicity Detection

Duplicity Detection

Duplicity occurs when the same AID signs conflicting events, creating a fork in the Key Event Log. This is the primary attack KERI is designed to detect and handle. This article explains how Foundry’s architecture detects, reports, and resolves duplicity.

What is Duplicity?

In normal operation, a KEL is a linear chain of events. Duplicity creates two branches:

Legitimate:  Inception → Event 1 → Event 2 → Rotation A → Event 3
Attacker:    Inception → Event 1 → Event 2 → Rotation B → Event 3'
                                                ↑
                                          Fork point

This happens when an attacker compromises private keys and rotates them to their own key pair while the legitimate controller also rotates. Two valid but conflicting branches now exist.

Three-Layer Detection

Foundry uses a defense-in-depth approach with three watcher layers, each monitoring at different trust levels.

Layer 1: Local Watcher

Runs inside the KERI agent service. Validates your own KEL for internal consistency:

  • Sequence continuity — Events must be sequential (0, 1, 2…)
  • Signature validity — All signatures must cryptographically verify
  • Digest chain — Each event must chain to the previous event’s digest
  • Key state validity — Signing keys must match the current key state

Scope: Single controller’s local data.

Layer 2: Witness-Level Watcher

Co-located with witnesses. Monitors witness KELs and validates receipts:

  • Cross-witness consistency — Same AID must have identical KELs at all witnesses
  • Receipt threshold — Enough witness signatures must exist
  • Receipt validity — Witness signatures must verify
  • Propagation timing — Events received in correct order

Detection process:

  1. Query all witnesses for the same AID’s KEL
  2. Compare responses
  3. If all match: no duplicity
  4. If any differ: duplicity detected

Layer 3: External Watcher

Independent service providing network-wide monitoring:

  • Network-wide fork detection — Any AID with conflicting KELs anywhere
  • Historical consistency — KEL history matches across all sources
  • Multi-source verification — Cross-verify with multiple independent sources

Reporting

When duplicity is detected, the system preserves cryptographic evidence and alerts through multiple channels.

Evidence Preservation

  • Both branches of the fork (complete event data with signatures)
  • Sequence numbers where the fork occurred
  • Timestamps: when each branch was first observed, when events were created
  • Which witnesses reported which version
  • All stored in an immutable, publicly verifiable log

Alert Channels

  • Webhook callbacks — HTTP POST to registered endpoints with structured payloads (admins can register webhooks from the Witness, Watcher & Duplicity Management tab).
  • REST API — Query duplicity events and monitored AID status on demand via the watcher routes (/api/watcher/*).

Resolution

When duplicity is detected, the system takes immediate protective action:

  1. Alert the controller — Notify with evidence of conflicting events
  2. Mark identifier as compromised — Flag the AID as potentially untrustworthy
  3. Block operations — Prevent new events, credential issuances, and key rotations
  4. Publish evidence — Make duplicity publicly verifiable

Recovery Path

If the legitimate controller can prove ownership (via pre-committed recovery keys):

  1. Controller publishes a recovery event with proof
  2. Witnesses validate the recovery proof
  3. If witness threshold is met (e.g., 2-of-3 accept), recovery succeeds
  4. Forked branch is invalidated, legitimate branch is restored

Permanent Invalidation

If recovery is impossible (no recovery keys, controller unresponsive):

  1. AID is permanently marked as compromised
  2. All credentials issued by this AID become untrustworthy
  3. Verifiers reject any credentials from this AID
  4. Status is propagated network-wide

For high-stakes credentials (e.g., regulated identity attestations), the resolution process can include due process considerations like minimum response windows, legal review, and appeal — these are configured per credential type rather than baked into KERI itself.

Security Properties

  • Byzantine fault tolerance — Threshold signatures prevent single-witness compromise from causing duplicity
  • Non-repudiation — Duplicity is cryptographically provable and publicly verifiable
  • Defense in depth — Multiple independent watcher types catch different attack vectors
  • Availability — Distributed witnesses ensure KELs remain accessible during partial failures

Current Status

The Witness & Watcher infrastructure described above is deployed and surfaced in the Witness, Watcher & Duplicity Management admin tab — including a tenant-summary view, monitored-AID tracking, duplicity-event records, webhook registration, and a duplicity-simulation tool for testing.

Operational today:

  • KEL/TEL generation and ACDC credential issuance
  • Tenant-scoped watcher with monitored AIDs and duplicity-event records
  • Super-watcher (network-wide) endpoints for cross-source verification
  • Webhook subscriptions for duplicity alerts

Areas still maturing include the breadth of the external witness pool, watcher SLO coverage, and detection performance under high load.

KERI FundamentalsSoft Gate Applications
Duplicity Detection