Tudisco d0db6f00f1 Initial implementation of KEZ — protocol, two impls, and storage server
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).
2026-05-24 14:41:00 -06:00

93 lines
3.0 KiB
TypeScript

// Nostr/secp256k1 primary keys. Schnorr (BIP-340), bech32 nsec/npub.
// Mirrors Rust's NostrSecret. Signatures are deterministic (auxRand = zeros)
// to match the Rust `sign_schnorr_no_aux_rand` path.
import { schnorr } from "@noble/curves/secp256k1";
import { bech32 } from "@scure/base";
import { bytesToHex } from "@noble/hashes/utils";
import { Identity, validateNpub } from "./identity.js";
const ZERO_AUX = new Uint8Array(32);
export class NostrSecret {
private readonly secretKey: Uint8Array; // 32 bytes
private constructor(secretKey: Uint8Array) {
if (secretKey.length !== 32) {
throw new Error(`secret key must be 32 bytes, got ${secretKey.length}`);
}
this.secretKey = secretKey;
}
static generate(): NostrSecret {
return new NostrSecret(schnorr.utils.randomPrivateKey());
}
static fromNsec(nsec: string): NostrSecret {
const decoded = bech32.decode(nsec as `${string}1${string}`, 1023);
if (decoded.prefix !== "nsec") {
throw new Error(`expected nsec bech32, got hrp=${decoded.prefix}`);
}
const bytes = bech32.fromWords(decoded.words);
return new NostrSecret(Uint8Array.from(bytes));
}
/** Lowercase 32-byte x-only public key, hex-encoded. */
pubkeyHex(): string {
return bytesToHex(schnorr.getPublicKey(this.secretKey));
}
nsec(): string {
return bech32.encode("nsec", bech32.toWords(this.secretKey), 1023);
}
npub(): string {
const pubkey = schnorr.getPublicKey(this.secretKey);
return bech32.encode("npub", bech32.toWords(pubkey), 1023);
}
identity(): Identity {
return Identity.parse(`nostr:${this.npub()}`);
}
/**
* Sign a digest with deterministic Schnorr (zero auxRand) to match Rust's
* `sign_schnorr_no_aux_rand`. Returns a 64-byte BIP-340 signature.
*/
signDigest(digest: Uint8Array): Uint8Array {
if (digest.length !== 32) {
throw new Error(`digest must be 32 bytes, got ${digest.length}`);
}
return schnorr.sign(digest, this.secretKey, ZERO_AUX);
}
}
/** Lowercase 32-byte x-only public key (hex) for a `nostr:npub1...` identity. */
export function nostrPubkeyHex(identity: Identity): string {
if (identity.scheme !== "nostr") {
throw new Error(`expected nostr: identity, got: ${identity}`);
}
const decoded = bech32.decode(identity.id as `${string}1${string}`, 1023);
if (decoded.prefix !== "npub") {
throw new Error(`expected npub bech32, got hrp=${decoded.prefix}`);
}
return bytesToHex(Uint8Array.from(bech32.fromWords(decoded.words)));
}
/** Verify a Schnorr signature over a 32-byte digest. */
export function verifySchnorr(
signature: Uint8Array,
digest: Uint8Array,
pubkeyHex: string,
): boolean {
// Normalize hex → bytes via noble's utility (accepts hex strings or bytes).
return schnorr.verify(signature, digest, pubkeyHex);
}
/** Decode an npub to its raw x-only pubkey bytes. */
export function npubToPubkeyBytes(npub: string): Uint8Array {
validateNpub(npub);
const decoded = bech32.decode(npub as `${string}1${string}`, 1023);
return Uint8Array.from(bech32.fromWords(decoded.words));
}