Tech debt: type-driven hardening of the KEL verify path (unsigned-replay unrepresentable, consolidate DelegatorKelLookup, tighten boundary types)

[bordumb]

Tech debt: type-driven hardening of the KEL verify path

Architectural follow-ups surfaced while remediating RT-002 (the systemic "verify path
replays a KEL by structure only, never checks event signatures" finding; see
docs/prompts/red_team_2026_06_10.md and #262). RT-002's functional gap is closed for
every signature-carrying transport. This issue captures the structural weaknesses that
let the class exist and that still make it easy to reintroduce. None of these are
security-blocking today; they are correctness-by-construction improvements.

Pre-launch repo: no backwards-compatibility constraints — wire formats and public
signatures may change freely.

---

Zero-context primer (read first)

• KERI / KEL. An identity is a Key Event Log (KEL): an ordered chain of events —
  icp (inception), rot (rotation), ixn (interaction), plus delegated variants dip
  (delegated inception) and drt (delegated rotation). Each event is content-addressed by
  a SAID (self-addressing identifier, a hash over its own bytes). An identity's prefix
  (its DID, did:keri:<prefix>) is the SAID of its inception event — so the inception is
  self-certifying, but later appended events are not constrained by the prefix.
• Two kinds of "replay". The engine lives in crates/auths-keri/src/validate.rs:
  • Structural replay — validate_kel(&[Event]) (+ _with_lookup, _with_receipts,
    and the alias replay_kel): checks SAID + sequence + chain-linkage + pre-rotation
    commitment. It does not verify that each event is signed by the controlling key.
  • Authenticated replay — validate_signed_kel(&[SignedEvent], Option<&dyn DelegatorKelLookup>) at validate.rs:588: folds per-event signature verification into
    the replay. SignedEvent { event, signatures } pairs an event with its CESR signature
    attachment.
  • RT-002 in one line: untrusted-input verifiers were calling the structural form, so
    a forged/unsigned KEL replayed to attacker-chosen keys and verified.
• Delegation constraint (important for any refactor here). A delegated event (dip/
  drt) cannot be authenticated standalone: validate_delegated_inception
  (validate.rs:1024) requires a DelegatorKelLookup to resolve the delegator's
  anchoring seal. So authentication of a delegated device KEL must happen where the root
  KEL + the device KEL + the lookup all coexist (the commit-verify layer, or the
  org-bundle pattern in offline_verify.rs).
• Trust tiers. The local ~/.auths registry is trusted (self-owned). Bundles
  (--identity-bundle, org air-gapped bundle), WASM/FFI inputs, and --remote/--oobi
  fetches are untrusted and must be authenticated.
• Ports/adapters. RegistryBackend (trait at crates/auths-id/src/storage/registry/ backend.rs:502) is the storage port; adapters are GitRegistryBackend (auths-storage,
  real), PostgresAdapter (stub), FakeRegistryBackend (testing), plus a blanket
  impl RegistryBackend for Arc<T> (backend.rs:1019).
• Build/check (per-crate, avoid --all-features on auths-crypto/-core — a deliberate
  FIPS/CNSA compile_error! guard makes that fail):
  cargo build -p auths-<crate> 2>&1 | grep "^error\[E". The verifier's WASM path compiles
  natively with cargo build -p auths-verifier --features wasm. A standing lint
  cargo run -p xtask -- check-verify-path-completeness guards the verify surfaces (below).

---

Verdict

Trending right, but mixed. The ports/adapters seam is genuine and the leaf domain types
are good. The weaknesses cluster in three places: (1) a trait-default footgun that caused
RT-002, (2) parse-don't-validate is applied at the leaves but not at the load-bearing
boundary (the public replay API still accepts unsigned &[Event]), and (3) genuine
logic duplication in delegator-seal lookups.

---

1. Ports/adapters — the lossy trait-default footgun (ALREADY FIXED; keep as a guardrail)

What happened: RegistryBackend::append_signed_event / get_attachment were default
methods whose defaults silently did the wrong thing — append_signed_event delegated to
append_event and dropped the signature attachment; get_attachment returned
Ok(None). The Arc<T> blanket impl did not override them, so every
Arc<dyn RegistryBackend> (the common handle) inherited the lossy default. Nothing failed
loudly — get_attachment just returned None. This is the literal root cause of RT-002:
producers couldn't ship signatures because storage silently discarded them.

Fix already landed (this session): the two methods are now required (no default) at
backend.rs:537/:549, so the compiler enumerates every adapter that must implement them;
Git/Fake/Postgres/Arc all implement them (Arc forwards at backend.rs:1029/:1038).

Lesson to encode (the actionable part):

• A trait default method is safe only if its default is fail-closed. A default that
  loses data or returns "absent" is a landmine. Audit the rest of RegistryBackend (and
  peer port traits) for other defaults that silently no-op.
• A blanket impl ... for Arc<T> must forward every method, and there is no
  compile-time guarantee it stays complete as methods are added (a required method does
  force it; a defaulted one does not). Consider whether the Arc blanket impl is worth its
  maintenance hazard, or whether a #[forward]-style macro / explicit newtype is clearer.

---

2. Parse-don't-validate — solid at the leaves, weak exactly where it's load-bearing

Good (do not "fix"): Prefix, Said, CesrKey, IndexedSignature are real newtypes
that validate on deserialize. SignedEvent { event, signatures } is the right domain type
and validate_signed_kel consumes it.

Gaps:

2a. The dangerous boundary is not typed — this is the big one. All four structural
replays are still public and take bare &[Event]:

• validate.rs:390 pub fn validate_kel(&[Event])
• validate.rs:398 pub fn validate_kel_with_lookup(...)
• validate.rs:472 pub fn validate_kel_with_receipts(...)
• validate.rs:1131 pub fn replay_kel(&[Event]) (a literal alias of validate_kel)

The type system does nothing to stop an unsigned replay; we rely on the CI lint
xtask check-verify-path-completeness (which bans these on verify surfaces unless a call
site carries an // rt-002-allow: <reason> comment). The lint is a guardrail; the real
fix the audit specified (task "A.0", docs/prompts/red_team_2026_06_10.md) is type-level:
make bare-Event replay pub(crate)/private and have the only public replay take
&[SignedEvent], so "verify an unsigned KEL" becomes a compile error. Then the lint
becomes a backstop instead of the primary defense.

2b. Parallel index-correlated arrays instead of one type. The wire structs carry events
and their attachments as two arrays zipped + length-checked at runtime:

• crates/auths-verifier/src/core.rs:935 pub kel: Vec<serde_json::Value> +
  :943 pub kel_attachments: Vec<String> (in IdentityBundle, core.rs:918).
• crates/auths-sdk/src/domains/org/bundle.rs:49 BundledKel { events: Vec<Event>, attachments: Vec<String> }.

A Vec<SignedEvent> makes the length mismatch unrepresentable. Worse, IdentityBundle.kel
is Vec<serde_json::Value> — unparsed JSON, the weakest possible typing, deferring the
parse past the type boundary entirely. The parallel-array wire shape has a defensible
forward/backward-read reason, but internally we should collapse to Vec<SignedEvent>
immediately at deserialize and never pass the loose arrays around. (Today the verify gate
does reconstruct SignedEvent then call validate_signed_kel, but the struct still leaks
the loose arrays to every other reader.)

2c. Primitive obsession at the resolver boundary. In
crates/auths-cli/src/commands/verify_commit.rs:

• :173/:394/:439 thread bundle_kel: Option<&(String, Vec<Event>)> — an anonymous
  tuple whose String is really a DID — through three signatures. A named
  BundleKel { did: Prefix /* or IdentityDid */, events: Vec<Event> } (or Vec<SignedEvent>)
  is clearer and self-documenting.
• resolve_signer_kel(did: &str) re-runs parse_did_keri(did) on every branch
  (:403, :408, …) instead of parsing once at the boundary into a Prefix and passing
  the typed value down (parse-don't-validate: parse at the edge, pass the proof inward).

---

3. Shared logic vs. duplication — one clear offender (and I added to it)

There are three near-identical DelegatorKelLookup impls (trait at validate.rs:373,
single method find_seal(&self, delegator_aid: &Prefix, seal_said: &Said) -> Option<SourceSeal>), each indexing "a KEL's anchoring seals":

• crates/auths-verifier/src/commit_kel.rs:165 RootKelLookup — linear scan
• crates/auths-verifier/src/presentation.rs:67 DelegatorSeals — linear scan
• crates/auths-sdk/src/domains/org/offline_verify.rs:88 OrgKelLookup — precomputed
  HashMap, O(1) (added during the RT-002 work because the other two weren't reusable)

Three structs for one concept, and inconsistent in quality (HashMap vs linear scan). This
should be one reusable index — e.g. KelSealIndex::from_events(&[Event]) living in
auths-keri next to the trait — that everyone constructs. Note the lookups span crates
(auths-verifier and auths-sdk), so the shared type belongs in auths-keri.

Minor: replay_kel (validate.rs:1131) is a literal alias of validate_kel — two public
names for one function; collapse to one (the alias forced the lint to ban both names).

Working as intended (keep): replay logic is not duplicated — bundle, org bundle, and
WASM validateKelJson all call the single validate_signed_kel engine fn. That reuse is
the pattern done right; preserve it.

---

Proposed work (priority order)

P1 — Type-level A.0: make unsigned replay unrepresentable.
Make validate_kel / validate_kel_with_lookup / validate_kel_with_receipts /
replay_kel pub(crate) (or move behind a private module); expose only signed entrypoints
taking &[SignedEvent]. Signer-side trusted re-derivations that legitimately replay an
already-trusted local KEL stay inside the crate boundary or get a typed "trusted" wrapper.
Acceptance: calling structural replay with bare &[Event] from outside the engine crate
is a compile error; check-verify-path-completeness stays green as a backstop; the
existing rt-002-allow: annotations are revisited (several become unnecessary once the type
enforces it).

P2 — Consolidate the three DelegatorKelLookup impls into one KelSealIndex in
auths-keri; delete RootKelLookup, DelegatorSeals, OrgKelLookup in favor of it.
Acceptance: one impl, O(1) lookup, used by commit-verify + presentation + offline org
verify; behavior unchanged (existing org_delegation + commit_kel + presentation tests
pass).

P3 — Tighten boundary types. IdentityBundle.kel: Vec<serde_json::Value> →
Vec<Event> (ideally fold kel + kel_attachments into Vec<SignedEvent>); same for
BundledKel. Replace (String, Vec<Event>) in verify_commit.rs with a named struct;
have resolve_signer_kel take a parsed Prefix instead of &str + repeated
parse_did_keri.
Acceptance: no serde_json::Value in the bundle wire type; no anonymous DID-bearing
tuples on the resolver path; DID parsed once at the boundary.

Also fold in: audit remaining RegistryBackend (and peer port) trait methods for
lossy/no-op defaults (§1); collapse the replay_kel alias (§3).

---

Constraints & gotchas for whoever picks this up

• Delegated KELs can't self-authenticate — preserve the lookup-at-the-assembly-point
  pattern (§primer). P1 must not break this: the signed public API still needs the
  Option<&dyn DelegatorKelLookup> parameter.
• Don't run full test suites (repo convention — a push pre-hook gates that); use targeted
  per-crate builds + the specific test cases named above.
• No commits — the human handles commits (passphrase-gated signing hooks).
• Related: RT-002 follow-up: signature-carrying wire formats for remaining untrusted KEL transports (--oobi, --remote stranger, WASM verifyDeviceLink/credential/presentation) #262 (RT-002 untrusted-transport residuals), docs/prompts/red_team_2026_06_10.md
  (audit, tasks A.0/A.1), Add custom lint rules to enforce domain types over raw strings #98 (existing "custom lint rules to enforce domain types over raw
  strings" — P1's lint half partially overlaps).

[bordumb]

P1 decision doc — type-level "unsigned replay unrepresentable"

Status update from an overnight pass: P2 and P3 (items 1–2) are done (see commits/diff
on dev-security); P1 is paused pending an API-surface decision captured here, because
every way to do it touches public surface and the naive form breaks legitimate callers. No
P1 code was changed.

What landed (P2 + P3)

• P2 — added auths_keri::KelSealIndex (O(1) precomputed seal index) and deleted the
  three hand-rolled DelegatorKelLookup impls (RootKelLookup, DelegatorSeals,
  OrgKelLookup). One definition, one perf profile. Tests green.
• P3.1 — IdentityBundle.kel: Vec<serde_json::Value> → Vec<auths_keri::Event> (wire
  form unchanged). This forced trusted_root_from_bundle off loose-JSON poking
  (inception.get("i").as_str(), compute_said(&Value)) onto typed accessors
  (inception.prefix(), compute_event_said(&Event)) — a parse-don't-validate win in
  itself.
• P3.2 — the anonymous (String, Vec<Event>) threaded through verify_commit.rs is now
  a named BundleKel { did, events }.
• P3.3 (deferred) — resolve_signer_kel(did: &str) → parsed Prefix: low value, churns
  error-message wording; left for a supervised pass.

Why P1 needs a decision (the caller inventory)

P1 = make the structural replays pub(crate) so the only public replay takes
&[SignedEvent]. Concrete reachability (non-test, cross-crate):

fn	external callers	nature
validate_kel	~20	mostly trusted-local (see below) + 4 lint-gated verify paths
validate_kel_with_lookup	0 outside auths-verifier verify paths	lint-gated
validate_kel_with_receipts	0 outside auths-verifier verify paths	lint-gated
replay_kel (alias of validate_kel)	3 in auths-keri/tests/cases/dual_index.rs + re-exported by auths-id::keri	dead-ish alias

The trusted-local validate_kel callers (these read a KEL out of the local trusted
registry/storage and replay it to get key-state — they have no attacker input and no
signatures in hand):

• auths-id: domain/keri_resolve.rs:29, trust/mod.rs:71, identity/rotate.rs:111,
  keri/rotation.rs (×5), keri/anchor.rs (×2), keri/resolve.rs (×2),
  keri/inception.rs (×3, in-file tests)
• auths-sdk: keri/resolver.rs:187 (resolve_current_public_key)

A blanket pub(crate) breaks all of these, and forcing them through validate_signed_kel
is wrong: they'd have to re-load CESR attachments to re-verify signatures on a KEL the
local store already vouches for — redundant work, and some don't have the attachments at
hand. So P1 is not a mechanical move; it needs a trusted-path API.

Options

1. pub(crate) + route everyone through validate_signed_kel — ❌ rejected: imposes
   signature re-verification on ~16 trusted-local replays that don't need it.
2. TrustedKel(Vec<Event>) newtype (recommended, larger) — a wrapper only
   constructible by trusted sources (the registry/storage read paths). validate_kel
   becomes validate_kel(&TrustedKel) (or pub(crate) with a public
   replay_trusted(&TrustedKel)); untrusted input literally cannot build a TrustedKel
   without going through authentication. This is the real "make illegal states
   unrepresentable" fix the issue asks for, but it touches every trusted read path (each
   must wrap) — a deliberate, reviewable refactor, not an overnight one.
3. Rename to signal trust (smaller) — keep it public but rename
   validate_kel→replay_trusted_kel (+ docs: "trusted/local or already-authenticated
   KELs only; untrusted input must use validate_signed_kel"). No compile-time guarantee
   beyond the name; the check-verify-path-completeness lint stays the enforcement. Cheap,
   but mostly cosmetic over what we have.

Recommendation: Option 2 for the durable guarantee, accepting it as a planned refactor.
If you want a quick partial now, Option 3 + making validate_kel_with_lookup /
validate_kel_with_receipts / replay_kel pub(crate) (they have no trusted-local
external callers) is low-risk and shrinks the dangerous public surface to the single
validate_kel name.

Bundle in: drop the replay_kel alias

replay_kel is a literal alias of validate_kel with only 3 dual_index.rs test callers +
auths-id::keri re-exports. Replace those 3 calls with validate_kel, drop the alias and
its re-exports. Trivial, but it's a public-surface edit — do it as part of whichever option
above you pick, not piecemeal.

What's safe to execute once you choose

• Option 3 or the pub(crate)-the-three-zero-caller-fns step can be done immediately and
  mechanically.
• Option 2 wants a short design note on where TrustedKel is constructed (registry read
  boundary) before touching the ~16 sites.

I left the tree green at each step; the check-verify-path-completeness lint remains the
active backstop regardless of which option lands.

[bordumb]

P1 — DONE (Option 2: TrustedKel newtype). 2026-06-11, branch dev-security, uncommitted.

Implemented the type-level guarantee. Outside auths-keri, structural replay of a bare
&[Event] is now a compile error.

auths-keri

• New pub struct TrustedKel<'a>(&'a [Event]) (Copy, zero-cost) with
  from_trusted_source(&[Event]) + events() + replay() / replay_with_lookup() /
  replay_with_receipts() / replay_with_policy().
• validate_kel, validate_kel_with_lookup, validate_kel_with_receipts,
  validate_kel_with_policy → pub(crate). replay_kel alias removed.
• lib.rs: dropped those 5 from the public API, exported TrustedKel.

Callers (minted at the trusted boundary, per the design note)

• auths-id (the trusted-local boundary — owns the registry): its keri facade now
  provides a thin local validate_kel that mints TrustedKel internally, so all ~12
  production callers + auths-id tests were untouched. (One test, witness_convergence,
  used validate_kel_with_receipts directly → switched to the method.)
• auths-sdk resolver.rs: 1 site → TrustedKel::from_trusted_source(&kel).replay().
• auths-verifier (7 verify-path sites, commit_kel/credential/presentation/verify): each
  now an explicit TrustedKel::from_trusted_source(..).replay*() carrying its existing
  rt-002-allow: rationale (KEL authenticated at the ingestion boundary).
• Tests: dual_index (auths-keri) + kel_verification (auths-verifier) switched to the
  TrustedKel API.

Lint

check-verify-path-completeness now gates from_trusted_source (the explicit trust
assertion) on verify paths — the bare validate_kel* names can no longer be called
cross-crate anyway, so the assertion is the thing to review. Kept the old names for defence
in depth. Green: 0 violations.

Synergy with #262

A --remote/--oobi fetch can no longer be replayed for key-state without first being
authenticated into a TrustedKel (or via validate_signed_kel) — so #262's remote/oobi
fix is now structurally forced, not just lint-suggested.

Verification (all green)

Full cargo build --workspace EXIT=0. Suites: auths-keri (233+65+25), auths-id
(288+75+8, incl. witness_convergence + all facade callers), auths-verifier (120+172+10),
auths-sdk org_delegation (+ rebuilt bundle_rejects_did_not_matching_its_kel_inception
using a real inception), auths-cli verify_identity_bundle (5/5). Lint 0 violations.

Deferred (unchanged)

P3.3 (resolve_signer_kel(&str)→Prefix) — fold into a future typed-DID pass. No commits
(per repo convention).