Jason Tudisco b1f8b3a5fb docs(nodejs): add TUTORIAL.md — Node.js mirror of the Rust tutorial

Parallel of rust/TUTORIAL.md (d10dfb9), adapted for the Node.js
implementation. Same end-state for the reader: from "I have a nostr
nsec" to "I have a verified, published sigchain" in ~15 minutes.

Node-specific adaptations:
  • Install (Node 22+ note for the built-in WebSocket the nostr
    channel needs, npm 9+ workspaces, optional `npm link` for global
    `kez` instead of `npm run cli --`).
  • Every command uses `npm run cli --` to match the README's
    existing convention; explicit "-- swallowed flags" callout.
  • New section 8 "Programmatic use" — short snippet showing how to
    sign + verify via @kez/core + @kez/channels for embedding in a
    Node app. Cross-checked against the real exports
    (newClaimPayload(subject, primary, date), signClaim(payload,
    signer), await defaultRegistry(), registry.verify(...)).
  • Cross-implementation interop callout: sign in Node, verify in
    Rust (wire-compatible by design).
  • Common-confusions FAQ gets one extra entry — "Is the Node version
    slower than Rust?" (answer: I/O-bound on channels, both fine for
    interactive use; Rust faster only for batch sigchain work).
  • Troubleshooting adds "WebSocket is not defined → upgrade Node" for
    the nostr channel.

README now points to TUTORIAL.md as the on-ramp, matching the Rust
README's structure.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-30 00:19:18 -06:00

5.1 KiB

Raw Blame History

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.

5.1 KiB Raw Blame History