Validate a KEL

KERI's security model requires verifiers to independently validate every event in a KEL before trusting any key state derived from it. There is no trusted third party: validity is a property of the event log itself, derivable from cryptographic rules alone.

@kerits/core exposes granular validation helpers, pure predicates for attachment verification, and a high-level validateKelChain function that runs all checks in sequence.

Validation model assumptions

Witness receipt signature verification assumes the non-transferable basic identifier model: the witness identifier prefix directly encodes the current verification key. This is the KERI default for witnesses.

If transferable witnesses or non-basic identifier types are used, receipt verification must be replaced with witness key state resolution. This assumption applies to both the verifyWitnessReceipt predicate and the fully-witnessed validation mode.

Validation modes

validateKelChain supports two active validation modes via the options.mode parameter:

A strict mode is reserved in the type system for future use but is not currently implemented.

What validateKelChain checks

In structural mode (default):

1. SAID integrity — recomputes each event's SAID and compares to d field
2. AID derivation — for icp/dip events, verifies i === d (only after SAID passes)
3. Required fields — all mandatory fields present for the event type
4. Prior-event linkage — p field matches previous event's d
5. Controller signature verification — Ed25519 signatures over canonical event bytes
6. Signing threshold — valid signatures satisfy kt (simple numeric or weighted multi-clause)
7. Key-chain continuity — rotation keys hash to previous establishment event's n commitments
8. Delegation VRC verification — parent signatures verified against parent's kt threshold (supports multi-sig delegators)

In fully-witnessed mode, additionally:

9. Witness receipt signature verification — each receipt's Ed25519 signature verified using the witness AID prefix as verification key (non-transferable basic model)
10. Witness receipt threshold — verified receipt count satisfies bt

What validateKelChain does NOT check

Delegation anchoring — validateKelChain verifies VRC signatures from the delegator, but does NOT verify that the delegator's KEL contains an event with a seal anchoring the delegated event's SAID. This requires traversing the parent KEL, which is an SDK-level orchestration concern.

Use the exported predicates eventContainsAnchorForSaid and isDelegationAnchor as building blocks for SDK-level anchor verification. See the Predicates reference below.

Check SAID integrity

validateEventSaid recomputes an event's SAID from its body and compares it to the d field.

import { validateEventSaid } from '@kerits/core';
import type { KELEvent } from '@kerits/core';

const result = validateEventSaid(event);
if (!result.valid) {
  console.error('SAID mismatch', { expected: result.expected, actual: result.actual });
}

Check required fields

validateRequiredFields verifies that every field mandated by the event type is present.

import { validateRequiredFields, isValidKeriEvent } from '@kerits/core';

if (!isValidKeriEvent(rawData)) {
  throw new Error('Not a valid KERI event');
}

const result = validateRequiredFields(rawData);
if (!result.valid) {
  console.error('Missing fields:', result.missing);
}

Required fields by event type:

Validate key-chain continuity

validateKeyChain checks that a rotation event's current keys satisfy the previous establishment event's next-key commitments.

import { validateKeyChain } from '@kerits/core';

const result = validateKeyChain(rotEvent, previousEstablishment);
if (!result.valid) {
  console.error('Key chain broken', {
    expected: result.expectedDigests,
    actual: result.actualDigests,
  });
}

Full chain validation

import { validateKelChain } from '@kerits/core';
import type { CESREvent } from '@kerits/core';

const events: CESREvent[] = [
  { event: icpEvent, attachments: [{ kind: 'sig', form: 'indexed', keyIndex: 0, sig: 'AAsig...' }], enc: 'JSON' },
  { event: rotEvent, attachments: [{ kind: 'sig', form: 'indexed', keyIndex: 0, sig: 'ABsig...' }], enc: 'JSON' },
];

const result = validateKelChain(events);
if (!result.valid) {
  const err = result.firstError;
  console.error(`Validation failed at event ${err?.eventIndex}: [${err?.code}] ${err?.message}`);
}

Fully-witnessed mode

const result = validateKelChain(events, { mode: 'fully-witnessed' });

Delegated KELs

const result = validateKelChain(delegatedEvents, { parentKel: parentEvents });

Incremental validation

const result = validateKelChain(events, { startIndex: events.length - 3 });

Predicates reference

Pure predicates for attachment and anchor verification. These are independently importable from @kerits/core.

verifyWitnessReceipt

Verify a witness receipt signature against an event's canonical bytes. Assumes the non-transferable basic witness model.

import { verifyWitnessReceipt } from '@kerits/core';

const valid = verifyWitnessReceipt(
  { by: witnessAid, sig: receiptSignature },
  event,
);

verifyVrcAgainstThreshold

Aggregate VRC verifier: validates attachment structure, verifies each signature, and evaluates the delegator's signing threshold. Returns a discriminated union with typed failure reasons.

import { verifyVrcAgainstThreshold } from '@kerits/core';
import type { VrcVerificationResult } from '@kerits/core';

const result: VrcVerificationResult = verifyVrcAgainstThreshold(
  vrcAttachments,
  childEvent,
  { k: parentKeys, kt: parentThreshold },
);

if (!result.passed) {
  // result.reason: 'cid-mismatch' | 'signature-invalid' | 'key-index-out-of-range' | 'threshold-not-met'
  console.error(result.reason, result.validKeyIndices);
}

eventContainsAnchorForSaid

SAID-only convenience check: does any entry in the event's a[] array have a d field matching the given SAID? Not a full seal matcher — matches SAID only.

import { eventContainsAnchorForSaid } from '@kerits/core';

const hasAnchor = eventContainsAnchorForSaid(parentIxnEvent, delegatedEventSaid);

isDelegationAnchor

Checks that a parent event can carry delegation seals (ixn, rot, drt) and contains a matching SAID anchor. This is a convenience pre-check — complete delegation anchor verification also requires finding the sealing event in the parent KEL and verifying it in its own KEL context.

import { isDelegationAnchor } from '@kerits/core';

for (const parentEvent of parentKel) {
  if (isDelegationAnchor(parentEvent.event, delegatedEventSaid)) {
    console.log('Found delegation anchor at', parentEvent.event.s);
  }
}

Validation error codes