Kez/nodejs/README.md

# KEZ — Node.js Implementation

TypeScript port of [KEZ](../SPEC.md), structurally mirroring the
[Rust implementation](../rust/README.md) — 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`**](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

```sh
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:

```sh
# 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`](packages/kez-channels/src/dns.ts) | `dns:` | Node `dns/promises` resolver, abstracted behind `TxtResolver` for testing |
| [`github.ts`](packages/kez-channels/src/github.ts) | `github:` | `fetch` against the public REST API, no auth |
| [`nostr.ts`](packages/kez-channels/src/nostr.ts) | `nostr:` | Built-in `WebSocket` to default relays, abstracted behind `NostrFetcher` |
| [`bluesky.ts`](packages/kez-channels/src/bluesky.ts) | `bluesky:` | `fetch` against the public Bluesky AppView, no auth |
| [`activitypub.ts`](packages/kez-channels/src/activitypub.ts) | `ap:`, `mastodon:` | WebFinger + actor JSON, no auth |

Each channel implements:

```ts
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`](packages/kez-channels/src/index.ts).

## Library use

```ts
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`](../README.md#cross-testing) for the runner.

## Tests

```sh
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.