Kez/nodejs

KEZ — Node.js Implementation

TypeScript port of KEZ, structurally mirroring the Rust implementation — three packages (core, channels, cli) with the same CLI surface, the same proof formats, and the same five channel plugins. Wire-compatible with the Rust version: a claim signed in Rust verifies in Node and vice versa.

nodejs/
├── package.json                 npm workspaces root
├── tsconfig.base.json
├── packages/
│   ├── kez-core/                Types, signing, verification, JCS, all four encodings
│   ├── kez-channels/            One file per channel (github, dns, nostr, bluesky, activitypub)
│   └── kez-cli/                 Thin CLI dispatching through the channel registry
└── README.md                    (this file)

New to KEZ? Read TUTORIAL.md — a friendly step-by-step walkthrough that takes you from "I have a nostr nsec" to "I have a verified, published sigchain." It assumes nothing.

This README is the reference; the tutorial is the on-ramp.

Requirements

• Node.js 22+ (for the built-in WebSocket the nostr channel uses)
• npm 9+ (for workspaces)

Install & test

npm install                  # one-time
npm test                     # runs all packages' vitest suites
npm run typecheck            # strict tsc --build across all packages

CLI

The CLI mirrors the Rust CLI exactly. Run it via the workspace script:

# Create a key
npm run cli -- identity new

# Sign a claim — pick either key type
npm run cli -- claim create github:jason --nsec nsec1... --format markdown --out github.kez.md
npm run cli -- claim create github:jason --ed25519-seed <64-char-hex> --format markdown --out github.kez.md

# Generate an ed25519 identity instead of nostr
npm run cli -- identity new --key-type ed25519

# Local sigchain (state at ~/.kez/sigchains/<safe-primary>.jsonl)
npm run cli -- sigchain add    github:jason --nsec nsec1...
npm run cli -- sigchain revoke github:jason --nsec nsec1...
npm run cli -- sigchain show   --nsec nsec1...
npm run cli -- sigchain export --nsec nsec1... --format jsonl

# Publish the sigchain to one or more destinations
npm run cli -- sigchain publish --nsec nsec1... \
  --server http://localhost:7878 \
  --web --out chain.jsonl \
  --dns example.com \
  --nostr wss://relay.damus.io

# Verify a local file
npm run cli -- verify file github.kez.md

# Verify any KEZ identifier over the network
npm run cli -- verify id github:jason
npm run cli -- verify id dns:jason.example.com
npm run cli -- verify id nostr:npub1...
npm run cli -- verify id bluesky:jason.bsky.social
npm run cli -- verify id ap:@jason@mastodon.social
npm run cli -- verify id mastodon:@jason@mastodon.social

Channels

File	System	Implementation
dns.ts	dns:	Node dns/promises resolver, abstracted behind TxtResolver for testing
github.ts	github:	fetch against the public REST API, no auth
nostr.ts	nostr:	Built-in WebSocket to default relays, abstracted behind NostrFetcher
bluesky.ts	bluesky:	fetch against the public Bluesky AppView, no auth
activitypub.ts	ap:, mastodon:	WebFinger + actor JSON, no auth

Each channel implements:

interface Channel {
  readonly system: string;
  fetchAndVerify(identity: Identity): Promise<ChannelHit>;
}

…and is registered in Registry. Adding a new channel is one file + one r.register(new MyChannel()) line in defaultRegistry.

Library use

import { Identity } from "@kez/core";
import { defaultRegistry } from "@kez/channels";

const registry = await defaultRegistry();
const hit = await registry.verify(Identity.parse("github:jason"));
console.log(hit.status); // VerificationStatus

Crypto stack

• Schnorr signatures — @noble/curves/secp256k1 (BIP-340)
• SHA-256 — @noble/hashes/sha2
• bech32 (npub/nsec) — @scure/base
• JCS (RFC 8785) — canonicalize
• zstd — fzstd (pure JS, no native deps)
• base64url — @scure/base
• HTTP — Node 18+ built-in fetch
• WebSocket — Node 22+ built-in WebSocket
• DNS TXT — Node dns/promises

No native dependencies. Runs on Node, Bun, and (mostly) Deno.

Cross-implementation interop

The whole point of having two implementations is to demonstrate that the proof format is portable. The repo root has a crosstest.sh script that generates artifacts in Rust and verifies them in Node, and vice versa. See ../README.md for the runner.

Tests

npm test                          # full suite
npx vitest run --project core     # one workspace package

The test suite hits no network — HTTP channels use an injected fetch, DNS uses a TxtResolver interface, nostr uses a NostrFetcher interface.

License

Dual-licensed under MIT or Apache-2.0.