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).
97 lines
2.8 KiB
TypeScript
97 lines
2.8 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
COMPACT_PROOF_PREFIX,
|
|
Identity,
|
|
NostrSecret,
|
|
newClaimPayload,
|
|
signClaim,
|
|
toCompact,
|
|
toMarkdown,
|
|
toPrettyJson,
|
|
} from "@kez/core";
|
|
import {
|
|
ChannelError,
|
|
Registry,
|
|
defaultRegistry,
|
|
extractCompactToken,
|
|
parseAndVerifyFor,
|
|
parseProof,
|
|
} from "../src/index.js";
|
|
|
|
function sign(subjectStr: string) {
|
|
const secret = NostrSecret.generate();
|
|
const primary = secret.identity();
|
|
const subject = Identity.parse(subjectStr);
|
|
return signClaim(newClaimPayload(subject, primary, new Date()), secret);
|
|
}
|
|
|
|
describe("parseProof", () => {
|
|
it("handles all four encodings", () => {
|
|
const signed = sign("github:jason");
|
|
expect(parseProof(toPrettyJson(signed))).toEqual(signed);
|
|
expect(parseProof(toCompact(signed))).toEqual(signed);
|
|
expect(parseProof(toMarkdown(signed))).toEqual(signed);
|
|
});
|
|
|
|
it("rejects unknown format", () => {
|
|
expect(() => parseProof("just some text")).toThrow(/unknown/);
|
|
});
|
|
|
|
it("extracts compact token from surrounding prose", () => {
|
|
const signed = sign("ap:@jason@mastodon.social");
|
|
const compact = toCompact(signed);
|
|
const bio = `hello world! my proof: ${compact} — verify it`;
|
|
expect(parseProof(bio)).toEqual(signed);
|
|
});
|
|
});
|
|
|
|
describe("extractCompactToken", () => {
|
|
it("stops at non-base64url chars", () => {
|
|
expect(extractCompactToken("before kez:z1:KLUv_QBYabc. after")).toBe(
|
|
"kez:z1:KLUv_QBYabc",
|
|
);
|
|
});
|
|
|
|
it("returns undefined when missing or empty body", () => {
|
|
expect(extractCompactToken("nothing")).toBeUndefined();
|
|
expect(extractCompactToken("kez:z1:")).toBeUndefined();
|
|
});
|
|
|
|
it("uses the canonical prefix constant", () => {
|
|
expect(COMPACT_PROOF_PREFIX).toBe("kez:z1:");
|
|
});
|
|
});
|
|
|
|
describe("parseAndVerifyFor", () => {
|
|
it("passes on matching subject", () => {
|
|
const signed = sign("github:jason");
|
|
const hit = parseAndVerifyFor(toPrettyJson(signed), Identity.parse("github:jason"));
|
|
expect(hit.proof).toEqual(signed);
|
|
});
|
|
|
|
it("flags subject mismatch", () => {
|
|
const signed = sign("github:jason");
|
|
expect(() =>
|
|
parseAndVerifyFor(toPrettyJson(signed), Identity.parse("github:mallory")),
|
|
).toThrow(ChannelError);
|
|
});
|
|
});
|
|
|
|
describe("Registry", () => {
|
|
it("dispatches by scheme", async () => {
|
|
const r = await defaultRegistry();
|
|
expect(r.get("github")).toBeDefined();
|
|
expect(r.get("dns")).toBeDefined();
|
|
expect(r.get("nostr")).toBeDefined();
|
|
expect(r.get("bluesky")).toBeDefined();
|
|
expect(r.get("ap")).toBeDefined();
|
|
expect(r.get("mastodon")).toBeDefined();
|
|
expect(r.get("did")).toBeUndefined();
|
|
});
|
|
|
|
it("reports unknown system", async () => {
|
|
const r = new Registry();
|
|
await expect(r.verify(Identity.parse("github:jason"))).rejects.toBeInstanceOf(ChannelError);
|
|
});
|
|
});
|