KEZ is a portable, decentralized identity graph: a person signs claims
linking their many accounts, publishes those claims in places only the
claimed account can publish to, and anyone can verify the connections
without trusting a central server.
Layout
------
- SPEC.md Language-agnostic protocol spec (v0.2)
- rust/ Rust implementation: kez-core, kez-channels, kez-cli
- nodejs/ TypeScript port at full parity
- rust-sig-server/ Optional axum + SQLite storage server for sigchains
- crosstest.sh Cross-implementation interop harness
Capabilities (both implementations, byte-compatible)
----------------------------------------------------
- Two primary-key algorithms: nostr/secp256k1 Schnorr (BIP-340) and
Ed25519 (RFC 8032). Identifiers: nostr:npub1... and ed25519:<hex>.
- JCS (RFC 8785) canonicalization for everything signed.
- Four proof encodings: JSON envelope, compact (kez:z1:<base64url(zstd(json))>),
Markdown fence, DNS TXT.
- Five channel plugins (no API keys, no auth needed for any of them):
dns: system resolver, _kez.<domain> TXT records
github: public gist scan + <user>/<user> profile README fallback
nostr: kind-30078 events from default relays
bluesky: public AppView author feed
ap: WebFinger + actor JSON (alias mastodon:)
- Identical CLI surface:
kez identity new [--key-type nostr|ed25519]
kez claim create <subject> (--nsec | --ed25519-seed) [--format ...] [--out ...]
kez claim dns <domain> (--nsec | --ed25519-seed)
kez verify file <path>
kez verify id <identifier>
kez sigchain add|revoke|show|export|publish
- Sigchains: append-only signed log per primary, hash-chained per spec §6,
stored locally at ~/.kez/sigchains/, exportable as JSONL or kez:zc1: bundle.
- Sigchain publish destinations: chain server, web (file dump), DNS (zone
record print), nostr (kind-30078 wrapping event).
kez-sig-server
--------------
Optional storage tier. Axum + SQLite, single binary, no external deps.
- No auth — the cryptography is the access control. The server validates
every signature, every seq, every prev hash before storing.
- REST API: POST /v1/sigchains/{scheme}/{id}/events (append signed event,
201 with new head hash or 4xx); GET /{scheme}/{id} (full chain as JSONL);
GET /head; GET /healthz.
- Designed for one central instance for now; the design doesn't preclude
running more later (clients gain a configurable list, verifiers
reconcile per spec §6.2).
- Channel-based publishing remains the always-available fallback if the
server is unavailable.
Tests
-----
- rust/ 99 tests
- rust-sig-server/ 10 integration tests (real HTTP, real SQLite)
- nodejs/ 91 tests (vitest)
- crosstest.sh 19 cross-impl scenarios — proves JCS bytes,
Schnorr + Ed25519 sigs, all four claim encodings,
and the sigchain JSONL bundle are byte-compatible
between Rust and Node in both directions.
What's not done yet
-------------------
- verify id consulting the sigchain for revocations (data path exists,
just not wired into the verifier output).
- rotate and add_device sigchain ops (types reserved).
- expires_at enforcement during claim verification.
- Typed VerificationStatus.status reflecting the five failure modes.
- Auth-required publishers (GitHub gist, Bluesky, ActivityPub).
151 lines
5.4 KiB
Rust
151 lines
5.4 KiB
Rust
//! Integration tests for the nostr channel using a fake `NostrFetcher`.
|
|
//! The real fetcher uses websockets to live relays; tests substitute
|
|
//! canned events so they're hermetic.
|
|
|
|
use std::sync::Arc;
|
|
|
|
use async_trait::async_trait;
|
|
use chrono::Utc;
|
|
use kez_channels::nostr::{KEZ_NOSTR_KIND, NostrChannel, NostrEvent, NostrFetcher, NostrFilter};
|
|
use kez_channels::{Channel, ChannelError, ChannelResult};
|
|
use kez_core::{ClaimPayload, Identity, NostrSecret, SignedClaim, nostr_pubkey_hex};
|
|
|
|
struct CapturingFetcher {
|
|
events: Vec<NostrEvent>,
|
|
expected_authors: Vec<String>,
|
|
expected_kinds: Vec<u32>,
|
|
}
|
|
|
|
#[async_trait]
|
|
impl NostrFetcher for CapturingFetcher {
|
|
async fn fetch_events(&self, filter: &NostrFilter) -> ChannelResult<Vec<NostrEvent>> {
|
|
assert_eq!(filter.authors, self.expected_authors, "wrong authors filter");
|
|
assert_eq!(filter.kinds, self.expected_kinds, "wrong kinds filter");
|
|
Ok(self.events.clone())
|
|
}
|
|
}
|
|
|
|
struct FailingFetcher;
|
|
|
|
#[async_trait]
|
|
impl NostrFetcher for FailingFetcher {
|
|
async fn fetch_events(&self, _filter: &NostrFilter) -> ChannelResult<Vec<NostrEvent>> {
|
|
Err(ChannelError::Unreachable("all relays down".into()))
|
|
}
|
|
}
|
|
|
|
fn make_event(pubkey_hex: &str, content: String) -> NostrEvent {
|
|
NostrEvent {
|
|
id: "0".repeat(64),
|
|
pubkey: pubkey_hex.to_owned(),
|
|
created_at: Utc::now().timestamp(),
|
|
kind: KEZ_NOSTR_KIND,
|
|
tags: vec![vec!["d".to_owned(), "kez".to_owned()]],
|
|
content,
|
|
sig: "f".repeat(128),
|
|
}
|
|
}
|
|
|
|
fn sign_for_self() -> (NostrSecret, Identity, SignedClaim) {
|
|
let secret = NostrSecret::generate();
|
|
let identity = Identity::parse(format!("nostr:{}", secret.npub())).unwrap();
|
|
let signed = SignedClaim::sign(
|
|
ClaimPayload::new(identity.clone(), identity.clone(), Utc::now()),
|
|
&secret,
|
|
)
|
|
.unwrap();
|
|
(secret, identity, signed)
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn verifies_self_published_proof_from_relay() {
|
|
let (_secret, identity, signed) = sign_for_self();
|
|
let pubkey_hex = nostr_pubkey_hex(&identity).unwrap();
|
|
let compact = signed.to_compact().unwrap();
|
|
|
|
let fetcher = CapturingFetcher {
|
|
events: vec![make_event(&pubkey_hex, compact)],
|
|
expected_authors: vec![pubkey_hex.clone()],
|
|
expected_kinds: vec![KEZ_NOSTR_KIND],
|
|
};
|
|
|
|
let channel = NostrChannel::with_fetcher(Arc::new(fetcher));
|
|
let hit = channel.fetch_and_verify(&identity).await.unwrap();
|
|
assert_eq!(hit.proof, signed);
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn skips_events_whose_pubkey_field_mismatches() {
|
|
// Relay returns an event with a forged content-pubkey discrepancy:
|
|
// event.pubkey claims to be someone else even though the filter asked
|
|
// for `identity`. We must not trust the content in that case.
|
|
let (_secret_a, identity_a, signed_a) = sign_for_self();
|
|
let (_secret_b, identity_b, _signed_b) = sign_for_self();
|
|
let pubkey_b_hex = nostr_pubkey_hex(&identity_b).unwrap();
|
|
let compact_a = signed_a.to_compact().unwrap();
|
|
|
|
let fetcher = CapturingFetcher {
|
|
events: vec![make_event(&pubkey_b_hex, compact_a)],
|
|
expected_authors: vec![nostr_pubkey_hex(&identity_a).unwrap()],
|
|
expected_kinds: vec![KEZ_NOSTR_KIND],
|
|
};
|
|
|
|
let channel = NostrChannel::with_fetcher(Arc::new(fetcher));
|
|
let err = channel.fetch_and_verify(&identity_a).await.unwrap_err();
|
|
assert!(
|
|
matches!(err, ChannelError::NotFound(_)),
|
|
"expected NotFound (all events rejected by author check), got {err:?}"
|
|
);
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn rejects_proof_signed_for_different_subject() {
|
|
// The event is correctly authored, but the embedded claim is for a
|
|
// different identity. The subject-mismatch check must fire.
|
|
let (secret_a, identity_a, _signed_self_a) = sign_for_self();
|
|
let (_secret_b, identity_b, _signed_self_b) = sign_for_self();
|
|
let pubkey_a_hex = nostr_pubkey_hex(&identity_a).unwrap();
|
|
|
|
// A signs a claim with subject == B (legitimate proof but for B, not A).
|
|
let claim_for_b = SignedClaim::sign(
|
|
ClaimPayload::new(identity_b.clone(), identity_a.clone(), Utc::now()),
|
|
&secret_a,
|
|
)
|
|
.unwrap();
|
|
let compact = claim_for_b.to_compact().unwrap();
|
|
|
|
let fetcher = CapturingFetcher {
|
|
events: vec![make_event(&pubkey_a_hex, compact)],
|
|
expected_authors: vec![pubkey_a_hex.clone()],
|
|
expected_kinds: vec![KEZ_NOSTR_KIND],
|
|
};
|
|
|
|
let channel = NostrChannel::with_fetcher(Arc::new(fetcher));
|
|
let err = channel.fetch_and_verify(&identity_a).await.unwrap_err();
|
|
assert!(
|
|
matches!(err, ChannelError::SubjectMismatch { .. }),
|
|
"expected SubjectMismatch, got {err:?}"
|
|
);
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn no_events_yields_not_found() {
|
|
let (_s, identity, _signed) = sign_for_self();
|
|
let fetcher = CapturingFetcher {
|
|
events: vec![],
|
|
expected_authors: vec![nostr_pubkey_hex(&identity).unwrap()],
|
|
expected_kinds: vec![KEZ_NOSTR_KIND],
|
|
};
|
|
let channel = NostrChannel::with_fetcher(Arc::new(fetcher));
|
|
let err = channel.fetch_and_verify(&identity).await.unwrap_err();
|
|
assert!(matches!(err, ChannelError::NotFound(_)));
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn fetcher_failure_surfaces_as_unreachable() {
|
|
let (_s, identity, _signed) = sign_for_self();
|
|
let channel = NostrChannel::with_fetcher(Arc::new(FailingFetcher));
|
|
let err = channel.fetch_and_verify(&identity).await.unwrap_err();
|
|
assert!(matches!(err, ChannelError::Unreachable(_)));
|
|
}
|