Kez/SPEC.md

KEZ Specification

Status: Draft v0.3 Date: 2026-05-25 Conformance: Implementations MUST conform to the formats and behaviors defined here. Two implementations conform iff a claim signed by one verifies in the other and vice versa (see §15).

---

1. Summary

KEZ is a portable identity graph. Users sign claims connecting their many accounts, publish those claims in places they control, and anyone can verify the connections without trusting a central server.

"These accounts, keys, domains, and identities are all me."

No central authority blesses the claim. Verification is done by cryptographic signatures against keys the user already controls.

---

2. Glossary

Term	Meaning
Primary key	The key the user owns; the root of their identity. One per user. Supported algorithms in §11.
Identity	A canonical system:identifier string (e.g. github:jason, nostr:npub1abc...). §3.
Subject	The identity being claimed about, in a claim payload.
Claim payload	The unsigned JSON object asserting that the primary key controls a subject. §5.1.
Signature envelope	The wrapper that wraps any payload with {kez, payload, signature}. The unit of transport. §4.
Proof	A signature envelope (containing a claim) that has been published in a location only the claimed subject controls.
Channel	A protocol/system where a proof can be published and fetched. §7.
Sigchain event	An entry in a user's sigchain — add, revoke, rotate, etc. §5.2.
Sigchain	The append-only signed log of sigchain events for one primary key. §8.
Identity graph	The set of currently-active subjects reachable from a primary key, walked through its sigchain.

---

3. Identifiers

A KEZ identifier is always system:identifier — the system prefix is required, never optional. A human glancing at the string can tell what namespace it lives in.

Canonical examples:

System	Example
nostr	nostr:npub1abc...
ed25519	ed25519:2152f8d19b791d24... (64 lowercase hex chars)
github	github:jason
dns	dns:jason.example.com
web	web:https://jason.example.com
bluesky	bluesky:jason.bsky.social
did	did:plc:abc...
ens	ens:jason.eth
ap	ap:@jason@mastodon.social (alias: mastodon:@...)
farcaster	farcaster:fid:12345

Bare npub1... (no nostr: prefix) is not a valid stored or signed identifier. CLI tools MAY accept it as input ergonomics, but MUST normalize to nostr:npub1... before signing, publishing, or storing.

Identifier strings are case-sensitive except where the underlying system normalizes case (e.g. DNS — lowercased before comparison).

KEZ is not a phone book. It cannot resolve "Jason" from a human name. A verifier always needs a concrete starting identifier (see §10).

---

4. The Signature Envelope

Every signed thing in KEZ — claims, sigchain events, future payload types — is wrapped in the same three-field envelope:

{
  "kez": "<envelope-tag>",
  "payload": { ... },
  "signature": {
    "alg": "<signature-suite>",
    "key": "<primary-identity>",
    "sig": "<hex-encoded-signature>"
  }
}

The envelope is the unit of transport. Everything on the wire is an envelope; payloads never appear bare.

4.1 Envelope fields

Field	Type	Meaning
kez	string	Envelope tag — identifies the payload kind without parsing the payload. Examples: "claim", "sigchain_event".
payload	object	The payload — the actual data being signed. Shape depends on the envelope tag (see §5).
signature.alg	string	Full signature suite, identifying key family + hash + canonicalization. §11.
signature.key	string	The signing key as a KEZ identity. MUST equal payload.primary for claim and sigchain-event envelopes.
signature.sig	string	The signature, lowercase hex, no 0x prefix. The signature covers JCS(payload), not the envelope.

The on-disk file extension for a signed claim envelope is .kez. The MIME type is application/vnd.kez+json.

4.2 Canonicalization for signing

Signatures are computed over the JCS-canonicalized bytes of the payload (RFC 8785, JSON Canonicalization Scheme). Implementations MUST NOT rely on incidental key ordering — JCS sorts keys lexicographically, normalizes numbers, escapes strings deterministically.

This is what enables interop: byte-identical canonical bytes across implementations means byte-identical signatures (for deterministic algorithms) or universally-verifiable signatures (for randomized ones).

---

5. Payload Shapes

Two payload shapes are defined in v0.3.

5.1 Claim payload

A claim asserts that a primary key controls a subject identity.

{
  "type": "kez.claim",
  "version": 1,
  "primary": "ed25519:2152f8d19b791d24...",
  "subject": "github:jason",
  "created_at": "2026-05-19T18:00:00Z"
}

Required fields: type, version, primary, subject, created_at.

Optional fields:

Field	Type	Meaning
expires_at	RFC 3339 timestamp	After this time the claim is treated as expired.
nonce	opaque string	Prevents replay across publishing channels.
note	string ≤256 chars	Human-readable note.

Type strings are dotted and namespaced (kez.claim, kez.sigchain.event, future kez.device, etc.).

5.2 Sigchain event payload

{
  "type": "kez.sigchain.event",
  "version": 1,
  "primary": "ed25519:2152f8d19b791d24...",
  "seq": 7,
  "prev": "sha256:<hex of prior envelope's JCS bytes>",
  "created_at": "2026-05-20T12:00:00Z",
  "op": "add",
  "payload": { ... op-specific ... }
}

seq is strictly monotonic starting from 0. prev is sha256: plus hex SHA-256 of the JCS bytes of the prior signed envelope (whole envelope, not just its payload). The first event (seq: 0) has no prev field.

Per-op payload shapes are defined in §8.

---

6. Wire Encodings

A signed envelope can be transported in four interchangeable forms. All carry the same logical content; choose the one that fits the channel.

6.1 JSON

Standard JSON serialization of the envelope (pretty or compact). Native form. Used for HTTP fetches, /.well-known/kez.json, developer tooling.

Different implementations MAY produce different whitespace and field order in raw JSON, but the JCS-canonicalized payload must match. Signatures verify regardless of envelope whitespace.

6.2 Compact (kez:z1:)

URL-safe, copy-pasteable form designed for QR codes, DNS TXT records, chat messages, and other tight channels:

kez:z1:<base64url-no-pad(zstd(envelope-as-compact-json))>

• z1 is the compact format version. Future versions (z2, …) may change compression or framing.
• Compression: zstd, default level 3.
• Encoding: base64url (RFC 4648 §5), no padding.
• The decoded payload MUST parse as a valid signature envelope per §4.

Why zstd over gzip: ~30% smaller for our JSON shapes, low CPU cost, modern decoder available everywhere (built into Node 22.15+ via node:zlib, the zstd crate in Rust, etc.).

Implementations MUST support encoding and decoding kez:z1:.

6.3 Markdown

Human-readable proof file suitable for a GitHub gist, profile README, or any Markdown-rendering surface. The machine-readable proof lives inside a fenced code block tagged ```kez:

# KEZ Proof

This account publishes a signed KEZ identity claim.

- Primary: `ed25519:2152f8d19b...`
- Subject: `github:jason`
- Created: `2026-05-19T18:00:00Z`

```kez
{
  "kez": "claim",
  "payload": { ... },
  "signature": { ... }
}
```

Parsers MUST locate the first ```kez fence, take the contents up to the next ```, trim whitespace, parse as JSON. Surrounding prose is informational.

6.4 DNS TXT

For dns: subjects, the proof is published as a TXT record at:

_kez.<domain>

The TXT record value is the compact encoding (§6.2):

kez:z1:KLUv_QBY...

Raw JSON is NOT a valid DNS TXT proof — JSON exceeds the 255-byte TXT segment limit too easily and complicates quoting. The compact form fits common claims in a single segment (chunked across segments if needed, per standard DNS TXT semantics).

If a claim is too large even compressed, implementations SHOULD publish a web: proof instead and add a dns: claim pointing at the domain — chain, don't split.

6.5 Sigchain compact bundle (kez:zc1:)

For transporting an entire sigchain as one string (nostr event content, DNS TXT pointer, ActivityPub profile field):

kez:zc1:<base64url-no-pad(zstd(jsonl))>

Where the inner content is JSONL — one signed sigchain envelope per line. Parsers MUST decompress, split on newlines, and parse each line as a sigchain event envelope.

---

7. Channels

A channel is a system + the conventions for publishing a proof there so a verifier can fetch it.

System	Where to publish	Wire encoding
github	Public gist (filename should include kez), or README on the user's <user>/<user> profile repo	Markdown (§6.3)
dns	TXT record at _kez.<domain>	Compact (§6.2)
web	https://<domain>/.well-known/kez.json	JSON (§6.1)
nostr	Nostr event of kind 30078 (parameterized replaceable), d tag kez	JSON in event content
bluesky	Public post on the user's PDS	JSON or Markdown
ap (alias mastodon)	Profile field (preferred) or bio of the user's actor object; resolved via WebFinger → actor JSON	Compact (§6.2) inline, or Markdown

Verifying a proof always means: fetch from the channel the identity itself controls, then verify the signature against the primary key. A claim that signs correctly but is not found at the identity's own channel is not a valid proof.

Channel implementations are pluggable. Adding a new channel does not change the wire format or signatures — only adds a new resolver for a new system: prefix.

---

8. Sigchain Semantics

The sigchain is the append-only, signed log of identity events belonging to one primary key. It's how a verifier knows:

• What subjects the user has currently claimed
• What subjects have been revoked
• What devices / secondary keys the user controls
• When (if ever) the primary key was rotated

8.1 Operations

Each sigchain event has an op string and a payload tailored to it.

op	Payload	Effect
add	{ "subject": "github:jason", "proof_url": "..." } (proof_url optional)	Asserts the user controls subject.
revoke	{ "subject": "github:jason" }	Withdraws a previously added subject.
rotate	{ "new_primary": "ed25519:...", "new_key_sig": "<hex>" }	Rotates the primary key. The old key signs this event; new_key_sig is the new key's signature over the JCS of the same event with new_key_sig omitted, proving both keys consent.
add_device	{ "device_key": "ed25519:...", "label": "macbook" }	Adds a secondary key authorized to sign on behalf of this primary. (Semantics for device-signed events TBD in a future minor version.)

8.2 Integrity rules

• seq MUST be strictly monotonic, starting at 0.
• prev MUST equal sha256: + hex SHA-256 of the JCS-canonicalized envelope (not just payload) of the prior entry. The first event (seq: 0) has no prev field.
• A verifier MUST reject any sigchain with a broken hash chain, missing prev, or non-monotonic seq.
• Multiple sigchain copies MAY exist across stores; the longest valid chain wins. If two valid chains diverge at the same seq with different envelope hashes, a verifier SHOULD report a fork rather than silently picking one.

8.3 Key rotation

After a rotate:

• All subsequent entries MUST be signed by the new primary.
• Each entry's primary field MUST reflect the new key.
• Verifiers walk rotations by following the chain: the old key signed the rotation event, and the new_key_sig field within that event is the new key's signature over the same event (with new_key_sig omitted from the JCS input), closing the loop.

8.4 Sigchain in pictures

seq 0          seq 1                       seq 2                       seq 3
add github   add dns:example.com         revoke github               rotate to new_pk
                                                                      ↓
┌────────┐    ┌────────────────┐          ┌────────────────┐          ┌────────────────┐
│type:   │    │type: ...event  │          │type: ...event  │          │type: ...event  │
│ ...    │    │seq: 1          │          │seq: 2          │          │seq: 3          │
│seq: 0  │    │prev: sha256:H0 │ ────────►│prev: sha256:H1 │ ────────►│prev: sha256:H2 │
│prev: - │    │op: add         │          │op: revoke      │          │op: rotate      │
│op: add │    │payload: ...    │          │payload: ...    │          │new_key_sig:... │
│sub:gh:.│    └────────────────┘          └────────────────┘          └────────────────┘
└────────┘    │ signed by old │          │ signed by old │          │ signed by old │
│signed by │    │ primary       │          │ primary       │          │  + new_key_sig│
│primary    │  └────────────────┘          └────────────────┘          └────────────────┘
└──────────┘
   H0 =                                                                  After this event,
   sha256(                                                               subsequent events
   JCS(seq 0                                                             are signed by
   envelope))                                                            new_pk and have
                                                                          primary: new_pk

H₀, H₁, H₂ are the SHA-256s of the full JCS envelopes. Each event's prev points back to the prior envelope's hash, forming the chain.

---

9. Storage

KEZ is store-agnostic. Verifiers MUST be able to fetch sigchains and proofs from any of:

• nostr relays
• GitHub (gists, repos)
• HTTP(S) URLs (websites, /.well-known/kez.json)
• DNS (TXT records)
• IPFS
• Bluesky PDS
• ActivityPub (WebFinger + actor JSON)
• Local filesystem (for development and testing)

There is no required central KEZ server. Storage servers (e.g. a sigchain HTTP store) MAY exist as convenience tiers, but the signatures are the source of truth — a verifier MUST validate signatures locally, not trust a server's claim about validity.

Implementations SHOULD support multiple stores in parallel and treat them as mirrors.

---

10. Verification

10.1 Starting point

A verifier always starts from one identifier supplied externally — e.g. someone shared @chris@kez.lat, a QR code embedded nostr:npub1abc..., a profile page passed dns:chris.com. KEZ cannot resolve "Chris" from a human name; it always needs a concrete starting identifier.

Same mental model as the web: you don't know every URL; you start at one and follow links.

10.2 Input and output

Input: one identifier.

Output: a graph of identities reachable from the input, each with a status. Example:

Primary: ed25519:2152f8d19b791d24...

Verified identities:
  github:jason               valid
  dns:jason.example          valid
  bluesky:jason.bsky.social  valid
  ens:jason.eth              unreachable
Status:     valid
Confidence: strong

Confidence is implementation-defined but is typically a function of: number of independently-verified subjects, channel diversity, sigchain length and age.

10.3 Algorithm (5 phases)

1. Fetch. Resolve the input identifier on its native channel; fetch the proof. (Real network fetch — see §10.5.)
2. Verify signature. Parse the envelope; verify the signature against payload.primary over JCS bytes of the payload.
3. Confirm channel ownership. The proof was found at a location only the input identity could publish to.
4. Walk sigchain. Locate and load the sigchain for the primary key. Validate it end-to-end (signatures, hash chain, monotonic seq, rotation closure). Reject the proof if the input subject's most recent op is revoke, or any required event fails validation.
5. Walk graph. For each other subject in the sigchain, attempt to re-verify its proof against its own channel (best-effort).

10.4 Failure modes

A verifier MUST distinguish:

Status	Cause
invalid	A signature failed, or the chain is broken.
revoked	The identity was explicitly removed via a sigchain revoke.
expired	The claim's expires_at has passed.
unreachable	The channel could not be fetched (network/transient).
fork	The sigchain has diverging valid branches at the same seq.

These MUST NOT be conflated. A verifier MUST surface the distinction.

10.5 Network fetching is expected

A complete verifier performs real network fetches for each channel:

• dns: — real DNS resolution; reads the TXT record at _kez.<domain>.
• github: — HTTPS fetch against api.github.com / raw.githubusercontent.com.
• web: — HTTPS fetch of /.well-known/kez.json.
• nostr: — connect to one or more relays; fetch the relevant event.
• bluesky: — HTTPS fetch against the user's PDS.
• ap: — HTTPS fetch of WebFinger followed by actor JSON.

A library that only checks signatures over local data is a useful helper but not a complete verifier. Complete verifiers MAY expose a local-file mode for testing; it MUST be clearly labeled as such.

---

11. Cryptographic Primitives

Primitive	Role
BIP-340 Schnorr (over secp256k1)	nostr-key signatures. Suite: nostr-secp256k1-schnorr-sha256-jcs. Signatures are deterministic (zero aux randomness).
Ed25519 (RFC 8032)	ed25519-key signatures. Suite: ed25519-sha512-jcs. PureEdDSA — the signature is over the raw JCS bytes; SHA-512 is performed internally.
SHA-256	Sigchain prev chaining; pre-hash for Schnorr signing (sig = schnorr(SHA-256(JCS(payload)), key)).
SHA-512	Internal to Ed25519.
JCS (RFC 8785)	Canonicalize the bytes to be signed.
zstd (default level 3)	Compress the JSON envelope for the compact wire form.
base64url (RFC 4648 §5, no padding)	Encode compressed bytes for URL-safe transport.
hex (lowercase, no 0x)	Encode signatures and hashes wherever they appear in JSON.

The suite string names every choice (<key-family>-<hash>-<canonicalization>) so a verifier can dispatch without guessing. Future suites follow the same pattern.

---

12. Worked Example (reproducible)

Anyone implementing this spec should produce byte-identical results for these inputs, modulo signature aux randomness (Ed25519 is deterministic so the signature is byte-identical too).

Inputs (TEST ONLY — do not use this key for anything real):

Ed25519 seed (32 bytes, hex):
4242424242424242424242424242424242424242424242424242424242424242

Subject:    github:jason
created_at: 2026-01-01T00:00:00Z

Derived public key:

ed25519 pubkey (hex):
2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12

KEZ identity:
ed25519:2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12

The claim payload:

{
  "type": "kez.claim",
  "version": 1,
  "subject": "github:jason",
  "primary": "ed25519:2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12",
  "created_at": "2026-01-01T00:00:00Z"
}

JCS-canonicalized form (UTF-8 bytes, no whitespace, keys sorted):

{"created_at":"2026-01-01T00:00:00Z","primary":"ed25519:2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12","subject":"github:jason","type":"kez.claim","version":1}

JCS bytes (hex, for byte-level comparison):

7b22637265617465645f6174223a22323032362d30312d30315430303a30303a30
305a222c227072696d617279223a2265643235353139...

Ed25519 signature (over the JCS bytes above, using the seed above — PureEdDSA, no pre-hash):

bc338ba33c28aab2962041e115753865c37f0edca7bdc821ed4f5e8f45bf92e72fbce5623d6d977fa0f8d41b7fff9a47de9ac8123b4ab63429e08223f856540b

The full signed envelope (pretty JSON for display):

{
  "kez": "claim",
  "payload": {
    "type": "kez.claim",
    "version": 1,
    "subject": "github:jason",
    "primary": "ed25519:2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12",
    "created_at": "2026-01-01T00:00:00Z"
  },
  "signature": {
    "alg": "ed25519-sha512-jcs",
    "key": "ed25519:2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12",
    "sig": "bc338ba33c28aab2962041e115753865c37f0edca7bdc821ed4f5e8f45bf92e72fbce5623d6d977fa0f8d41b7fff9a47de9ac8123b4ab63429e08223f856540b"
  }
}

Compact form (kez:z1:) of the same envelope:

kez:z1:KLUv_QBY5QgAlpZCIFCH1gEAeFb7A6gC1YAb2oLOI6pa3SWmN_aYp6OqqqoBPwA2ADoAyrzw02VjaYSyLBLJhILpgnMGoVEG6bJ5X3AGk4i6TCgUZnkCgII3pMtfNJp0uIStODR6kUgilD68dFnwhnQEJ9GTqD2bLpsegN_0Ly-RXHWojDV1_qi22jkIPrfy1TG-5U95_0bW37SIU1qobXlTyOKyrmsBvvrBP3Ghx4ohXqz6ms6qtt7N9iHUzhB6ni4HCvOGRJJ5hWSVm8Akg0Onw-UvjKYTA4VJ5JEC7pwADY9H-kmsmEW0y863TUh5J0er7HV7uFK3GONyTZDF03GtBhVEq_ifx12_LTqnyJ5jgq_LHgwEADhkaDUYyCo6IR0I9QQ

(The compact bytes encode the compact JSON of the full envelope — no pretty-printing — compressed with zstd and base64url-encoded. Implementations that emit raw JSON in different field order or with different whitespace will produce different compact strings even though the signature still verifies; the test above produced exactly these bytes against the reference Rust implementation.)

To reproduce: use the seed and inputs above with any conforming implementation; you should get the same JCS bytes and the same signature.

---

13. Versioning & Wire Compatibility

Spec versions are major.minor. The current spec is v0.3.

What's non-breaking (minor bump)

• Adding optional payload fields
• Adding new envelope tags (kez: "...")
• Adding new wire encodings (kez:z2:, future)
• Adding new sigchain ops (existing verifiers MUST ignore unknown ops, preserving chain validity)
• Adding new signature suites
• Adding new channels (new system: prefixes)

What's breaking (major bump)

• Adding required fields
• Renaming or removing fields
• Changing the meaning of an existing field
• Changing the canonicalization scheme
• Changing the hashing or signature dispatch

Implementation policy

• An implementation declaring v0.3 MUST accept all v0.3 features.
• Implementations MAY accept newer minor versions if they ignore unknown additive content safely.
• Verifiers that encounter an event with an unknown op MUST chain past it (validate seq and prev) but MUST NOT use it for graph-resolution decisions.

---

14. Changelog

Version	Notable
v0.3 (current)	Restructured around the signature envelope; added glossary, cryptographic primitives table, reproducible worked example, versioning policy. Added kez:zc1: sigchain bundle encoding. ActivityPub channel formalized; mastodon: is an alias.
v0.2	Spec-aligned types across implementations. Added Ed25519 (ed25519-sha512-jcs). JCS canonicalization required. Five channels formalized (dns, github, nostr, bluesky, ap).
v0.1	Initial draft. Single signature suite (Schnorr/nostr).

---

15. Implementation Layout

Each language implementation lives in its own top-level directory. Current implementations:

Directory	Language	What it ships
rust/	Rust	kez-core (lib), kez-channels (lib), kez-cli (binary kez)
nodejs/	TypeScript	@kez/core, @kez/channels, @kez/cli — npm workspaces
rust-sig-server/	Rust	Optional HTTP server for sigchain storage

Conformance between implementations is verified by crosstest.sh at the repo root — a harness that generates artifacts with one implementation and verifies them with the other, in every direction and every wire encoding. A passing cross-test is the operational definition of "two implementations interoperate."

A future vectors/ directory may hold canonical test fixtures for third-party implementations to validate against. Not required while two interop-tested implementations exist.