6dfd5a6938
versioning policy, changelog Full sweep across the three buckets discussed: Bucket A (quick wins — staleness/bugs): - Fix §3 (was §2): drop wrong mastodon row with double-@; ActivityPub channel formalized as `ap:` with mastodon as alias; consolidated with current channel set. - §7 channels table now matches the actually-shipped channel adapters in rust-channels and node-channels. - Drop §12 Test Vectors (the directory never existed). Replaced with one paragraph in §15 pointing at the crosstest.sh harness, which is what we actually use for inter-implementation conformance. - Replace §10 historical "MVP Scope (v0.2)" with §14 Changelog. - §15 Implementation Layout now points at actual repos (rust/, nodejs/, rust-sig-server/) rather than the never-existed kez-web. Bucket B (simplifications): - Folded §9 Starting Points into §10.1 (one paragraph). - Consolidated §1 Core Concepts and §13 One-Sentence Summary into the new opener (§1 Summary + §2 Glossary). - §3.1 Canonicalization inlined into §4.2 (where it actually applies). - §8 Verification trimmed from 9 conflated steps to 5 clean phases. - §8.5 "MUST" softened to "expected" for libraries; complete verifiers do network, helpers don't. Bucket C (real improvements + restructure): - §2 Glossary added (primary key, claim, subject, proof, channel, sigchain, signature envelope, identity graph — all in one place). - §11 Cryptographic Primitives table — every algo we use, its role. - §12 Worked Example with REAL reproducible bytes: fixed Ed25519 seed (4242... — clearly labeled TEST ONLY), specific subject and timestamp, the exact JCS bytes, the exact deterministic Ed25519 signature, the exact compact form. Generated against the reference Rust implementation; any conforming implementation should produce identical bytes. - §13 Versioning & Wire Compatibility policy — what bumps major, what bumps minor, how implementations handle unknown ops. - §14 Changelog — v0.1 / v0.2 / v0.3 with notable changes. - §8.4 Sigchain in pictures — ASCII diagram showing 5 events with hash chaining and rotation. Structural reorganization: - §1 summary → §2 glossary → §3 identifiers → §4 signature envelope → §5 payload shapes → §6 wire encodings → §7 channels → §8 sigchain → §9 storage → §10 verification → §11 crypto → §12 worked example → §13 versioning → §14 changelog → §15 implementation layout. - The envelope (the unit of transport) is now described before the payloads it wraps, matching what's actually on the wire. Also: added §6.5 documenting `kez:zc1:` (compact sigchain bundle) that exists in the implementations but was missing from the spec.
KEZ
KEZ is a portable, decentralized identity graph. It lets a person say:
"These accounts, keys, domains, and identities are all me."
…without depending on any central authority. Every connection is proven by a cryptographic signature against a key the user already controls (a nostr key, an Ed25519 key, etc.), and the proofs are published in places only the claimed account itself can publish to (their gist, their DNS, their nostr relay event). Anyone can verify the graph without trusting a server.
Repository layout
.
├── SPEC.md ← The protocol. Language-agnostic, normative.
├── rust/ ← Rust implementation (kez-core, kez-channels, kez-cli)
├── nodejs/ ← TypeScript/Node implementation (same shape, same CLI)
├── rust-sig-server/ ← Optional HTTP store for sigchains (axum + SQLite)
├── crosstest.sh ← Interop test: artifacts move between implementations
└── README.md ← (this file)
Two parallel implementations. Wire-compatible: a claim signed in Rust verifies in Node and vice versa. The cross-test harness proves it.
A separate rust-sig-server/ crate provides an optional
HTTP storage tier for sigchains — useful when a user doesn't want to set up
DNS/hosting/nostr, but never required; the protocol stays decentralized.
Documentation
Start here:
SPEC.md— the language-agnostic protocol spec (v0.2). Normative for every implementation.rust/README.md— Rust implementation guide: crate layout (kez-core/kez-channels/kez-cli), full CLI reference, channel plugin model, library examples, and the gap list.nodejs/README.md— Node/TypeScript port: same shape as Rust, npm workspaces layout, crypto stack rationale, CLI reference.rust-sig-server/README.md— the optional storage server: API reference, no-auth design + threat model, deployment recipes (bare-metal, Docker, PaaS), and how channel-based publishing remains the fallback if the server is down.
Quick start
Rust
cd rust
cargo build
cargo test # 99 tests
cargo install --path crates/kez-cli # → `kez` on PATH
kez verify id github:jason
Full guide: rust/README.md.
Node.js
cd nodejs
npm install
npm test # 91 tests
npm run cli -- verify id github:jason
Full guide: nodejs/README.md.
Sigchain storage server (optional)
cd rust-sig-server
cargo build --release
./target/release/kez-sig-server # listens on :7878
Full guide: rust-sig-server/README.md.
Cross-testing
./crosstest.sh
Runs 19 scenarios that swap implementations at the artifact boundary:
| # | Scenario |
|---|---|
| 1–2 | nostr-signed JSON claim, both directions |
| 3–4 | nostr-signed compact claim, both directions |
| 5–6 | nostr-signed markdown claim, both directions |
| 7–8 | nostr-signed DNS zone form, both directions |
| 9–10 | ed25519-signed JSON claim, both directions |
| 11–12 | ed25519-signed compact claim, both directions |
| 13–14 | ed25519-signed markdown claim, both directions |
| 15 | rust builds 3-event nostr sigchain → node parses + shows |
| 16 | rust-exported sigchain JSONL == node-exported JSONL (byte-identical) |
| 17 | node builds 3-event nostr sigchain → rust parses + shows |
| 18 | rust builds ed25519 sigchain → node parses + shows |
| 19 | node builds ed25519 sigchain → rust parses + shows |
If all 19 pass: JCS canonicalization, both signature suites (BIP-340 Schnorr
and Ed25519), the compact kez:z1: zstd+base64url encoding, the Markdown
fence, the DNS TXT shape, and the sigchain JSONL bundle format are all
byte-compatible across implementations.
Pass -v for verbose output (echoes intermediate commands and proofs).
What ships in v0.2
- Five channel plugins in each implementation:
dns:,github:,nostr:,bluesky:,ap:(aliasmastodon:). - Four wire encodings: JSON, compact, Markdown fence, DNS TXT.
- Two primary-key algorithms: nostr/secp256k1 Schnorr (BIP-340) and Ed25519 (RFC 8032).
- JCS (RFC 8785) canonicalization for everything signed.
- No API keys required for any channel.
What's not done yet
Tracked in rust/README.md and the
spec:
verify idconsulting the sigchain. Sigchain types, CLI commands (kez sigchain add/revoke/show/export/publish), and the storage server all exist. But proof verification doesn't yet fetch the chain to check for revocations — everyverifyis still a single one-shot proof check.rotateandadd_devicesigchain ops.expires_atenforcement during claim verify.- Typed
VerificationStatus.statusreflecting the five failure modes (valid/revoked/expired/unreachable/fork). - Auth-required publishers (GitHub gist, Bluesky, ActivityPub).
License
Dual-licensed under MIT or Apache-2.0.