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).
187 lines
5.4 KiB
TypeScript
187 lines
5.4 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
Identity,
|
|
NostrSecret,
|
|
newClaimPayload,
|
|
nostrPubkeyHex,
|
|
signClaim,
|
|
toCompact,
|
|
} from "@kez/core";
|
|
import {
|
|
KEZ_NOSTR_KIND,
|
|
NostrChannel,
|
|
type NostrEvent,
|
|
type NostrFetcher,
|
|
type NostrFilter,
|
|
buildReqMessage,
|
|
buildSignedEvent,
|
|
eventMatchesAuthor,
|
|
parseRelayMessage,
|
|
} from "../src/nostr.js";
|
|
import { sha256 } from "@noble/hashes/sha2";
|
|
import { bytesToHex } from "@noble/hashes/utils";
|
|
|
|
class CapturingFetcher implements NostrFetcher {
|
|
constructor(
|
|
private events: NostrEvent[],
|
|
private expectedAuthors: string[],
|
|
private expectedKinds: number[],
|
|
) {}
|
|
async fetchEvents(filter: NostrFilter): Promise<NostrEvent[]> {
|
|
expect(filter.authors).toEqual(this.expectedAuthors);
|
|
expect(filter.kinds).toEqual(this.expectedKinds);
|
|
return this.events;
|
|
}
|
|
}
|
|
|
|
function makeEvent(pubkeyHex: string, content: string): NostrEvent {
|
|
return {
|
|
id: "0".repeat(64),
|
|
pubkey: pubkeyHex,
|
|
created_at: Math.floor(Date.now() / 1000),
|
|
kind: KEZ_NOSTR_KIND,
|
|
tags: [["d", "kez"]],
|
|
content,
|
|
sig: "f".repeat(128),
|
|
};
|
|
}
|
|
|
|
function signForSelf() {
|
|
const secret = NostrSecret.generate();
|
|
const identity = secret.identity();
|
|
const signed = signClaim(newClaimPayload(identity, identity, new Date()), secret);
|
|
return { secret, identity, signed };
|
|
}
|
|
|
|
describe("NostrChannel", () => {
|
|
it("verifies a self-published proof", async () => {
|
|
const { identity, signed } = signForSelf();
|
|
const pubkey = nostrPubkeyHex(identity);
|
|
const fetcher = new CapturingFetcher(
|
|
[makeEvent(pubkey, toCompact(signed))],
|
|
[pubkey],
|
|
[KEZ_NOSTR_KIND],
|
|
);
|
|
const channel = new NostrChannel(fetcher);
|
|
const hit = await channel.fetchAndVerify(identity);
|
|
expect(hit.proof).toEqual(signed);
|
|
});
|
|
|
|
it("skips events whose pubkey field mismatches", async () => {
|
|
const a = signForSelf();
|
|
const b = signForSelf();
|
|
const pubkeyB = nostrPubkeyHex(b.identity);
|
|
const compactA = toCompact(a.signed);
|
|
|
|
const fetcher = new CapturingFetcher(
|
|
[makeEvent(pubkeyB, compactA)],
|
|
[nostrPubkeyHex(a.identity)],
|
|
[KEZ_NOSTR_KIND],
|
|
);
|
|
const channel = new NostrChannel(fetcher);
|
|
await expect(channel.fetchAndVerify(a.identity)).rejects.toMatchObject({
|
|
kind: "NotFound",
|
|
});
|
|
});
|
|
|
|
it("rejects proof signed for a different subject", async () => {
|
|
const a = signForSelf();
|
|
const b = signForSelf();
|
|
// a signs a claim with subject = b
|
|
const claimForB = signClaim(
|
|
newClaimPayload(b.identity, a.identity, new Date()),
|
|
a.secret,
|
|
);
|
|
const fetcher = new CapturingFetcher(
|
|
[makeEvent(nostrPubkeyHex(a.identity), toCompact(claimForB))],
|
|
[nostrPubkeyHex(a.identity)],
|
|
[KEZ_NOSTR_KIND],
|
|
);
|
|
const channel = new NostrChannel(fetcher);
|
|
await expect(channel.fetchAndVerify(a.identity)).rejects.toMatchObject({
|
|
kind: "SubjectMismatch",
|
|
});
|
|
});
|
|
|
|
it("no events yields NotFound", async () => {
|
|
const { identity } = signForSelf();
|
|
const fetcher = new CapturingFetcher(
|
|
[],
|
|
[nostrPubkeyHex(identity)],
|
|
[KEZ_NOSTR_KIND],
|
|
);
|
|
const channel = new NostrChannel(fetcher);
|
|
await expect(channel.fetchAndVerify(identity)).rejects.toMatchObject({
|
|
kind: "NotFound",
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("nostr wire helpers", () => {
|
|
it("buildReqMessage includes filter fields", () => {
|
|
const req = buildReqMessage("sub-1", { authors: ["aa"], kinds: [30078], limit: 20 });
|
|
expect(JSON.parse(req)).toEqual([
|
|
"REQ",
|
|
"sub-1",
|
|
{ authors: ["aa"], kinds: [30078], limit: 20 },
|
|
]);
|
|
});
|
|
|
|
it("buildReqMessage omits limit when undefined", () => {
|
|
const req = buildReqMessage("s", { authors: ["aa"], kinds: [1] });
|
|
expect(JSON.parse(req)[2]).toEqual({ authors: ["aa"], kinds: [1] });
|
|
});
|
|
|
|
it("parseRelayMessage handles EVENT / EOSE / other", () => {
|
|
const ev = JSON.stringify([
|
|
"EVENT",
|
|
"s",
|
|
{
|
|
id: "0".repeat(64),
|
|
pubkey: "a".repeat(64),
|
|
created_at: 0,
|
|
kind: 30078,
|
|
tags: [],
|
|
content: "x",
|
|
sig: "f".repeat(128),
|
|
},
|
|
]);
|
|
expect(parseRelayMessage(ev).kind).toBe("event");
|
|
expect(parseRelayMessage(JSON.stringify(["EOSE", "s"])).kind).toBe("eose");
|
|
expect(parseRelayMessage(JSON.stringify(["NOTICE", "hi"])).kind).toBe("other");
|
|
expect(parseRelayMessage("not json").kind).toBe("other");
|
|
});
|
|
|
|
it("buildSignedEvent produces valid NIP-01 event", () => {
|
|
const signer = NostrSecret.generate();
|
|
const event = buildSignedEvent(
|
|
signer,
|
|
1_700_000_000,
|
|
KEZ_NOSTR_KIND,
|
|
[["d", "kez-sigchain"]],
|
|
"hello",
|
|
);
|
|
expect(event.id).toHaveLength(64);
|
|
expect(event.pubkey).toHaveLength(64);
|
|
expect(event.sig).toHaveLength(128);
|
|
expect(event.pubkey).toBe(signer.pubkeyHex());
|
|
// id must equal sha256(canonical [0, pubkey, created_at, kind, tags, content])
|
|
const canonical = JSON.stringify([
|
|
0,
|
|
event.pubkey,
|
|
event.created_at,
|
|
event.kind,
|
|
event.tags,
|
|
event.content,
|
|
]);
|
|
const expected = bytesToHex(sha256(new TextEncoder().encode(canonical)));
|
|
expect(event.id).toBe(expected);
|
|
});
|
|
|
|
it("eventMatchesAuthor is case-insensitive", () => {
|
|
const ev = makeEvent("ABCDEF", "");
|
|
expect(eventMatchesAuthor(ev, "abcdef")).toBe(true);
|
|
expect(eventMatchesAuthor(ev, "ababab")).toBe(false);
|
|
});
|
|
});
|