signet-protocol 1.11.1 → 1.11.2

package/README.md

@@ -39,6 +39,7 @@ const events = await fetchFromRelay('wss://relay.example.com', filters);
 const badge = await computeBadge('<hex-pubkey>', events, { verifySignatures: true });
 
 // badge.tier => 3, badge.score => 106, badge.displayLabel => "Verified (Tier 3)"
+// (illustrative values; badge.score is a Level 1 approximation, see the notes below)
 if (meetsMinimumTier(badge, 2)) {
   // allow posting in verified-only community
 }
@@ -46,9 +47,15 @@ if (meetsMinimumTier(badge, 2)) {
 
 `fetchFromRelay(relayUrl, filters)` is the package's own minimal relay client and returns `Promise<NostrEvent[]>`. Any other Nostr client works too: pass `buildBadgeFilters` output as the REQ filters and hand the resulting events to `computeBadge`. `computeBadge` is async and returns `Promise<BadgeInfo>`.
 
+Three things to know before you copy this:
+
+- `verifySignatures` defaults to `false`. A call such as `computeBadge(pubkey, events)` checks no signatures and trusts every event it is given, so keep `{ verifySignatures: true }` unless the events were already verified. `fetchFromRelay` drops events with an invalid signature or id by default; events from any other source are not checked for you.
+- `badge.score` is on the 0-200 Signet IQ scale but is a Level 1 approximation of `computeTrustScore(...).score`: it ignores account age and identity bridges and applies none of the per-type caps (1 professional verification, 3 in-person vouches, 5 online vouches). Use `computeTrustScore` when you need the full score.
+- `computeBadge` does not check who issued a Tier 3 or Tier 4 credential, and `buildBadgeFilters` does not fetch verifier or revocation events. Any key can sign an event that carries `tier: 3`, and it will count. To require that the issuer is an activated, unrevoked verifier, fetch the verifier credentials, their vouches and revocations yourself, apply `checkCrossVerification(...).activated` and `isVerifierRevoked(...)`, and drop other issuers' Tier 3 and Tier 4 credentials before calling `computeBadge`. [llms.txt](llms.txt) has the steps.
+
 See [Signet in 5 Minutes](docs/signet-in-5-minutes.md) for a full developer overview, or the [full flow example](examples/full-flow.ts) for all 4 tiers, trust scoring, policies, and verifier lifecycle.
 
-For LLM and agent tooling, [llms.txt](llms.txt) is a concise API overview and [llms-full.txt](llms-full.txt) adds the full protocol and voting specifications and the developer guides in one file. Both ship in the npm package.
+For LLM and agent tooling, [llms.txt](llms.txt) is a concise API overview and [llms-full.txt](llms-full.txt) adds the full protocol and voting specifications and the developer guides in one file. Both ship in the npm package, as do `spec/`, `examples/` and the four `docs/` pages linked from this README and `llms.txt` (`signet-in-5-minutes.md`, `implementation-levels.md`, `private-vault-v1.md` and `bot-ownership-v1.md`), so those relative links resolve inside `node_modules/signet-protocol/`. Other files under `docs/`, `legal/` and `tests/` stay in the repository only.
 
 ## Protocol
 

package/docs/bot-ownership-v1.md

@@ -0,0 +1,43 @@
+# Draft bot ownership profile
+
+Unstable. Import from `signet-protocol/experimental`; nothing here is exported
+from the package root, and any of it may change without a deprecation period.
+
+This unreleased profile uses nostr-attestations kind 31000 with type
+`bot-ownership`. Its replaceable d-tag is `bot-ownership:<bot pubkey>`, p-tag is
+the bot, and the event author is the selected owner persona. It cannot replace
+a credential or vouch. Ownership never grants the bot the owner's trust.
+
+A live claim has `valid_from` equal to `created_at`, matching `valid_to` and
+`expiration`, and content `{ "v": 1, "label": "…" }` (100 characters maximum).
+Labels refuse C0/C1 controls, DEL, zero-width and bidi marks (LRM, RLM, ALM),
+line/paragraph separators and bidi embeddings, overrides and isolates, lone
+surrogates, and every other Unicode format or default-ignorable code point,
+except the narrow in-context forms emoji sequences need: the zero-width
+joiner between emoji elements, the VS15/VS16 variation selectors right after
+an emoji or a keycap base, and the England/Scotland/Wales RGI subdivision
+flag tag sequences (no other tag sequence, and no hidden tag payload).
+The event supplies principal, agent, issue date and expiry without requiring a
+raw-hash signature: ordinary NIP-46 sign_event works on hardware. Revocation is
+the existing same-address attestation with `status=revoked` and empty content.
+
+Builders return unsigned events and never publish. Product integration must ask
+for creation consent every time, sign with the chosen persona, and keep the
+signed claim private until publication is explicitly chosen. Hardware-derived
+bots must be registered on the device; this module does not register them.
+
+Default expiry is 30 days, permitted creation range 1–90 days. Readers apply the
+earliest of signed expiry, 90 days and an optional stricter per-bot ceiling,
+with five minutes of clock tolerance. Lapsed is different from revoked.
+Renewal becomes due with ten days left; retry at most daily. The scheduling
+helper never signs: local policy and hardware approvals remain in force.
+
+Consumers pin the expected owner and bot, verify signatures, and select the
+newest same-address event while retaining their previously seen high-water mark.
+A stale ownership claim must not resurrect a newer revocation. This module
+validates one event; it does not implement relay freshness or fetch ordering.
+`readBotOwnershipSync` applies identical validation for synchronous storage and
+transport codecs; `readBotOwnership` is the asynchronous form of the same check.
+
+Protocol review, app lifecycle/UI, isolated bots contacts, downstream adoption,
+and hardware acceptance are still required before release.

package/docs/implementation-levels.md

@@ -0,0 +1,235 @@
+# Signet Implementation Levels
+
+A guide for Nostr client developers integrating the Signet identity protocol. There are three progressive integration levels. Start at Level 1 and add depth as your use case demands.
+
+## Summary
+
+| Level | Effort | Event Kinds | New Crypto | What Users Get |
+|-------|--------|-------------|------------|----------------|
+| 1 — Read Trust Badges | ~1 weekend | 31000 (credential, vouch) | None | Tier badges and Signet Score on profiles |
+| 2 — Issue Vouches | A few days | 31000, 30078 | None | Peer vouching, Tier 2 networks, policy checks |
+| 3 — Full Protocol | Weeks to months | 31000, 30078, 30482-30484 | Merkle, Pedersen range proofs, ring signatures | Professional verification, ZK proofs, elections |
+
+---
+
+## Level 1 — Read Trust Badges
+
+**Effort:** A weekend
+**Event kinds:** 31000 (attestation — filter by `type` tag: `credential`, `vouch`)
+**New crypto required:** None — Nostr already verifies Schnorr signatures
+
+This is the NIP-05 equivalent of Signet integration. You read one event kind (filtered by type tag), call one function, and display a badge. No cryptographic work on your part beyond what your Nostr client already does.
+
+### What to build
+
+1. Subscribe to kind `31000` events with `type` tags `credential` and `vouch` for the pubkeys you want to display.
+2. Pass the events to `computeBadge()`.
+3. Show the result on the user's profile.
+
+### Installation
+
+```bash
+npm install signet-protocol
+```
+
+### Code example
+
+```typescript
+import { computeBadge, buildBadgeFilters, fetchFromRelay } from 'signet-protocol';
+
+const pubkey = '<hex-pubkey>';
+
+// 1. Fetch events from a relay (fetchFromRelay is the package's own client; any Nostr client works)
+const filters = buildBadgeFilters([pubkey]);
+// The filters request kind 31000 with credential and vouch type tags.
+const events = await fetchFromRelay('wss://relay.example.com', filters);
+
+// 2. Compute badge from the events you receive
+const badge = await computeBadge(pubkey, events, { verifySignatures: true }); // async: returns Promise<BadgeInfo>
+
+// 3. Display
+if (badge.isVerified) {
+  console.log(badge.tierLabel, badge.score); // replace with your own rendering
+}
+```
+
+The `badge` object includes:
+
+- `badge.isVerified` — boolean, true if the pubkey has any Signet verification
+- `badge.tier` — number 1–4, the highest verified tier
+- `badge.tierLabel` — human-readable string (e.g. `"Vouched"`, `"Verified"`, `"Verified (Child Safety)"`)
+- `badge.score`: integer 0–200 on the Signet IQ scale (100 = government standard), derived from credentials and vouches only. It is a Level 1 approximation of `computeTrustScore(...).score`: it ignores account age and identity bridges and applies no per-type caps
+
+### Trust tiers at a glance
+
+| Tier | Meaning |
+|------|---------|
+| 1 | Self-declared — the user has made identity claims |
+| 2 | Web-of-trust — other users have vouched for this identity |
+| 3 | Professional adult — verified by a recognised professional body |
+| 4 | Professional adult + child safeguarding — extended professional verification |
+
+### What you do NOT need to handle at this level
+
+- Generating or validating zero-knowledge proofs
+- Nullifier computation
+- Merkle trees
+- Any cryptographic primitives beyond standard Nostr signature verification
+
+Two things Level 1 does not do for you:
+
+- Signature checking is opt-in. `verifySignatures` defaults to `false`, so `computeBadge(pubkey, events)` with no options trusts every event it is given. Keep `{ verifySignatures: true }` unless the events were already verified (`fetchFromRelay` drops events with an invalid signature or id by default; events from other sources are not checked for you).
+- Issuer standing is not checked. `computeBadge` does not look at who signed a Tier 3 or Tier 4 credential, and `buildBadgeFilters` fetches no verifier or revocation events, so any key can sign an event that carries `tier: 3` and it will count. To require an activated, unrevoked verifier, fetch the verifier credentials, their vouches and revocations yourself, apply `checkCrossVerification(...).activated` and `isVerifierRevoked(...)`, and drop other issuers' Tier 3 and Tier 4 credentials before calling `computeBadge` (see `llms.txt`).
+
+---
+
+## Level 2 — Issue Vouches
+
+**Effort:** A few days
+**Event kinds:** 31000 (attestation — credential, vouch types), 30078 (policy)
+**New crypto required:** None
+
+Level 2 adds the ability for your users to vouch for each other and for your client to respect community policies. This is the viral layer of the protocol — peer vouching is what builds Tier 2 trust networks and creates network effects across clients.
+
+### What to build
+
+Everything from Level 1, plus:
+
+1. UI for a user to select a contact and publish a kind `31000` vouch attestation (with `['type', 'vouch']` tag).
+2. Read kind `30078` (NIP-78 app-specific data) policies from community relays and check whether a pubkey meets the policy threshold before allowing sensitive actions.
+
+### Creating a vouch
+
+```typescript
+import { createVouch } from 'signet-protocol';
+
+// createVouch takes the voucher's private key and a VouchParams object.
+// It returns a signed Nostr event ready to publish.
+const vouchEvent = await createVouch(myPrivkey, {
+  subjectPubkey: theirPubkey,
+  method: 'in-person',
+  context: 'I have met this person in person and verified their identity.',
+  voucherTier: 2,
+  voucherScore: 106,
+});
+
+// Publish to your relay as a standard Nostr event.
+await publishEvent(vouchEvent);
+```
+
+### Parsing incoming vouches
+
+```typescript
+import { parseVouch, countQualifyingVouches, hasEnoughVouches } from 'signet-protocol';
+
+// Parse a raw Nostr event into a structured vouch object
+const vouch = parseVouch(rawEvent);
+
+// Count how many qualifying vouches a pubkey has received
+const count = countQualifyingVouches(allVouchEvents, pubkey);
+
+// Check whether a pubkey clears the threshold required for Tier 2
+const qualifies = hasEnoughVouches(allVouchEvents, pubkey, 3);
+```
+
+Reference: `src/vouches.ts`
+
+### Checking policy compliance
+
+Policies (kind `30078`, NIP-78) let community operators define trust thresholds for specific actions — for example, requiring a minimum score of 40 before a user can post to a paid relay, or requiring Tier 2 before joining a group.
+
+```typescript
+import { parsePolicy, checkPolicyCompliance, PolicyChecker } from 'signet-protocol';
+
+// Parse a policy event
+const policy = parsePolicy(policyEvent);
+
+// One-shot check: does this user meet the policy?
+const result = checkPolicyCompliance(policy, userTier, userScore);
+if (!result.allowed) {
+  showError(`This action requires Tier ${result.requiredTier} or higher.`);
+}
+
+// For repeated checks across many pubkeys, use PolicyChecker (more efficient)
+const checker = new PolicyChecker(policyEvent);
+const adultResult = checker.checkAdult(userTier, userScore);
+```
+
+Reference: `src/policies.ts`
+
+### What you do NOT need to handle at this level
+
+- Zero-knowledge proofs of any kind
+- Professional body verification flows
+- Two-credential ceremonies
+- Nullifiers or document hashing
+
+---
+
+## Level 3 — Full Protocol
+
+**Effort:** Weeks to months
+**Event kinds:** 31000 (all attestation types), 30078 (policies), 30482-30484 (voting)
+**New crypto required:** Merkle trees, Pedersen range proofs (age range proofs), linkable ring signatures
+
+Level 3 is full reference implementation. This is appropriate for clients that want to act as professional verifiers, run elections, or issue and receive Tier 3/4 credentials with zero-knowledge proofs. Elections themselves (kinds 30482–30484) live in the separate `nostr-anon-vote` package, not in `signet-protocol`.
+
+### What to build (beyond Level 2)
+
+- **Two-credential ceremony:** Professional verifiers issue a Natural Person credential (kind `31000` with `type: credential`, nullifier and Merkle root) and an anonymous Persona credential simultaneously. The Natural Person credential binds to a document-based nullifier (`SHA-256(docType || country || docNumber || salt)`) to prevent duplicate identity claims. The Persona credential reveals only an age range, not the full identity.
+- **Merkle selective disclosure:** Verified attributes are stored as private leaves of a Merkle tree. Only the root is published on-chain. Users disclose individual leaves with inclusion proofs when required.
+- **Age range proofs:** Pedersen range proofs prove that a user is within an age range without revealing their exact date of birth.
+- **Professional verifier onboarding:** Verifier accounts (kind `31000` with `type: verifier`) are backed by recognised professional bodies (law societies, medical boards, notary commissions). The protocol has no central authority — trust anchors are these external bodies.
+- **Ring signatures and elections:** The voting extension (kinds `30482`–`30484`) uses linkable ring signatures for anonymous voting with double-spend prevention. It is specified in `spec/voting.md` and implemented in the separate `nostr-anon-vote` package; `signet-protocol` ships only the linkable ring signature primitives (`lsagSign`, `lsagVerify`, `computeKeyImage`).
+- **Guardian delegation:** Delegation attestations (kind `31000` with `type: delegation`) with scopes (`full`, `activity-approval`, `content-management`, `contact-approval`) support family structures and guardian-linked sub-accounts.
+- **Revocation and lifecycle:** Revocation attestations (kind `31000` with `type: revocation`) and credential chains using `supersedes`/`superseded-by` tags handle name changes, document renewal, and tier upgrades.
+- **Identity bridging:** Identity bridge attestations (kind `31000` with `type: identity-bridge`) link verified identities across protocols or jurisdictions.
+- **Anomaly detection:** The library includes heuristics for detecting suspicious vouching patterns (e.g. vouch rings, rapid bulk vouching).
+
+### Key modules in signet-protocol
+
+All modules are re-exported from the package root. You can also import them directly for tree-shaking.
+
+| Module | Source | Responsibility |
+|--------|--------|----------------|
+| Credentials | `src/credentials.ts` | Issue, parse, verify credentials including Merkle roots and nullifiers |
+| Ring signatures | `src/ring-signature.ts` | Ring signature generation and verification (via `@forgesworn/ring-sig`) |
+| Range proofs | `src/range-proof.ts` | Pedersen range proofs for age verification (via `@forgesworn/range-proof`) |
+| Merkle trees | `src/merkle.ts` | Build attribute trees, generate and verify inclusion proofs |
+| Signet Score | `src/trust-score.ts` | Weighted signal aggregation, 0–200 Signet Score computation |
+| Anomaly detection | `src/anomaly.ts` | Detect vouch ring attacks and other manipulation patterns |
+| Jurisdictions | `jurisdiction-kit` | Jurisdiction-specific rules for document types and professional bodies |
+
+All modules are re-exported from the package root (`signet-protocol`). Import from the root entry point:
+
+### Event kind reference
+
+All Signet identity attestations use a single generic kind, differentiated by `type` tag:
+
+| Kind | Type Tag | Name | Description |
+|------|----------|------|-------------|
+| 31000 | `credential` | Credential | Identity claim with optional Merkle root and nullifier |
+| 31000 | `vouch` | Vouch | Peer attestation of another pubkey's identity |
+| 31000 | `verifier` | Verifier | Professional verifier registration |
+| 31000 | `challenge` | Challenge | Challenge against a verifier's legitimacy |
+| 31000 | `revocation` | Revocation | Credential or vouch revocation |
+| 31000 | `identity-bridge` | Identity Bridge | Cross-protocol or cross-jurisdiction identity link |
+| 31000 | `delegation` | Delegation | Guardian or organisational delegation with scopes |
+| 30078 | — | Policy | Community trust threshold definitions (NIP-78) |
+| 30482 | — | Election | Voting election definition (separate NIP) |
+| 30483 | — | Ballot | Anonymous signed ballot |
+| 30484 | — | Election Result | Tallied election result |
+
+**Note:** Kind 31000 is the NIP-VA (Verifiable Attestations) kind. The `type` tag differentiates attestation types within the single kind.
+
+### Where to start
+
+The `signet-protocol` npm package contains everything. The protocol specification at `spec/protocol.md` is the authoritative source of truth for all behaviour.
+
+---
+
+## Choosing your level
+
+Start at Level 1 unless you have a specific reason to go further. Most social clients only need Level 1 — displaying trust context on profiles. Level 2 is appropriate if your community has a peer moderation culture. Level 3 is for infrastructure builders: relay operators, professional verification portals, and election platforms.
+
+You can ship Level 1 in a weekend and upgrade later. The three levels are strictly additive — nothing you build at Level 1 needs to be undone to reach Level 2 or 3.

package/docs/private-vault-v1.md

@@ -0,0 +1,104 @@
+# Private vault checkpoint v1 (staged, not released)
+
+Unstable. Import from `signet-protocol/experimental`; nothing here is exported
+from the package root, and any of it may change without a deprecation period.
+
+Keys derive flat from the tree root using `vaultPurpose`; index means rotation.
+Legacy Natural Person rails remain permanently readable. No writer is switched
+until both the app and Sapwood can restore the new dataset.
+
+The existing v2 AES-GCM/NIP-44 envelope is retained. Vault keys wrap content keys
+and sign only control events below 12 KiB of UTF-8 content. Every chunk is sealed
+to the vault key but signed by an installation device key. A checkpoint authorises
+that device and lists exact chunk event IDs, encrypted-content SHA-256 hashes,
+byte lengths and order. The complete plaintext SHA-256 is the revision. Recovery discovers and merges all
+device heads rather than selecting one global latest snapshot, so concurrent
+offline writers cannot replace each other. The reader fails closed beyond 16
+heads instead of dropping devices; head compaction is future work. Readers
+verify signatures, scope, bounds, sequence, every chunk and the revision before
+returning any data. Missing chunks never mean an empty dataset.
+
+All events use existing kind 30078. Each installation retains its own checkpoint under
+`vaultCheckpointTag(author, publisherDevicePubkey)`;
+chunks use a content-derived tag and are fetched by exact event ID. This reuses
+the existing event kind rather than allocating a new kind. Content-addressed
+chunk replacement cannot alter an already signed checkpoint reference. No public
+tags name the dataset or connect device chunks to the vault author. Routing tags
+are opaque, not secret: knowing a vault pubkey lets an observer compute its tag.
+
+Head discovery reads only kind-30078 events by the vault author whose single
+d-tag has the checkpoint shape (32 lowercase hex characters); other events by
+the vault key are ignored (by the relay reader and again by recovery) before
+any limit applies and are never decrypted. The
+shape is necessary, not sufficient, because the publisher is encrypted: the
+vault key must sign no other kind-30078 event with a 32-hex d-tag, or that
+event is read as a malformed head and the read is unusable.
+
+Checkpoints dated more than `VAULT_CLOCK_TOLERANCE_SECONDS` (300) after the
+reader's clock are rejected; every reader takes `now` as a parameter. A device
+whose clock ran ahead therefore cannot outrank its own later honest heads, but
+its future-dated head is ignored until the clock catches up. Of two events with
+the same created_at under one tag, the lower event ID is the newer (NIP-01).
+
+Checkpoint plaintext shape is exported as `VaultCheckpoint`. It contains purpose,
+rotation, sequence, revision, authorised device pubkeys and ordered chunk refs.
+`nextRotation` is optional and, when present, exactly `rotation + 1`; any other
+value makes the checkpoint invalid. Recovery begins at zero. A rotation
+must not become canonical before the new copy is fetched, decrypted and verified.
+
+Rotation is a revocation boundary. Recovery reads only the newest rotation:
+the first rotation n whose successor n + 1 holds no authentic checkpoint-shaped
+event. Before reading rotation n it always probes rotation n + 1 (one extra
+resolve and query). Once n + 1 exists, rotation n is never queried, opened,
+counted or merged, so a holder of a retired key can neither inject or tombstone
+data (backdated or not, under any publisher tag) nor block recovery with
+malformed, over-cap or junk-tag events, nor hide the successor by overwriting
+the pointer head. The newest rotation is read strictly; a pointer there to a
+rotation with no authentic checkpoint is damage (`unusable`). The rotating
+writer must carry every head's state into the new rotation before publishing
+there; nothing written under an older rotation is recovered. Sequence floors
+apply to the rotation that is read.
+
+A rotation revokes only a holder of THAT rotation's key, not the tree root: a
+holder of the root key can derive every rotation regardless. A caller that
+walks forward and finds every relay withholding the true newest rotation's
+successor cannot tell that from a vault that never rotated further, so any
+caller tracking the highest rotation it has already reached must treat a walk
+that lands below it as a rollback, not as ready.
+
+Rotation write order matters. The rotating writer first publishes the merged
+state under rotation n + 1 (every chunk, then the checkpoint) and only then
+declares `nextRotation` in rotation n. A pointer published first makes reads
+`unusable` until rotation n + 1 is complete, because a pointer to a rotation
+with no authentic checkpoint is damage. Once any authentic checkpoint-shaped
+event exists under rotation n + 1, rotation n is never read: if that event (or
+its chunks) is broken, the read is fail-closed `unusable` with no fallback to
+rotation n. Recovery walks at most 32 rotations (`MAX_ROTATION_HOPS`); a vault
+rotated more often reads `unusable`.
+
+Restore results distinguish absent, unavailable, unusable and ready. Legacy may
+be the canonical source only when the vault is absent, never merely because a
+relay is offline or a new checkpoint fails to decrypt. A previously observed
+sequence is a rollback floor. A fresh device cannot detect a relay withholding
+all newer state without another trusted source; do not claim otherwise.
+
+`createVaultRelayReader` queries at most eight `wss://` relays (plain `ws://`
+only for `localhost` and `127.0.0.1`, matching `RelayClient`). A checkpoint
+query, empty or not, completes only when every queried relay returned EOSE and
+none failed: one relay's "nothing" is not evidence of absence, and one relay's
+heads may omit a device head that another relay holds. Otherwise the query
+throws a `VaultRelayError` whose `failedRelays` names the relays that failed,
+and recovery returns `{ state: 'unavailable', failedRelays }`. A permanently
+dead configured relay therefore keeps reads `unavailable` until it is removed
+from the relay set; that is deliberate, since `unavailable` is safe and a false
+`absent` is not. A chunk fetch by exact ID succeeds once any relay returns it
+(its hash is pinned by the checkpoint); "not found" again needs every relay.
+Each relay's events are re-checked against the requested author, kind, ID and
+d-tag, checkpoint queries also drop events without a checkpoint-shaped d-tag,
+and duplicates are removed, all before a per-relay cap of 128; a relay over the
+cap counts as failed.
+
+The SDK provides stateless read/validation and forward rotation traversal.
+Writer scheduling, dataset import and durable canonical markers belong to
+consumers. The candidate Signet app implements scheduling and confirmed-copy
+state; this does not establish equivalent Sapwood behaviour.

package/docs/signet-in-5-minutes.md

@@ -0,0 +1,181 @@
+# Signet in 5 Minutes
+
+Signet is an open-source, decentralised identity verification protocol for Nostr. It lets users prove claims
+about who they are — human, professional, adult, organisation — without exposing personal data. Verification
+is anchored to professional bodies (law societies, medical boards, notary commissions) rather than any central
+authority. Trust accumulates as a continuous Signet Score (0–200, where 100 represents the current government standard) assembled from weighted signals, and is expressed as a tier badge any Nostr client can display.
+
+
+## How Trust Flows
+
+```
+  Person
+    |
+    | signs a kind 31000 self-declaration (`type: credential`)
+    v
+  Tier 1 — Self-declared
+    |
+    | three or more peers sign kind 31000 vouches (`type: vouch`)
+    v
+  Tier 2 — Web-of-trust
+    |
+    | licensed professional issues kind 31000 credential (`type: credential`)
+    | with zero-knowledge age proof and document nullifier
+    v
+  Tier 3 — Professionally verified (adult)
+    |
+    | same ceremony, scope extended to child supervision
+    v
+  Tier 4 — Professionally verified (adult + child)
+    |
+    v
+  Trust signals accumulated (professional verif, vouches, account age, identity bridges)
+    |
+    v
+  Signet Score computed (0-200, where 100 = government standard)
+    |
+    v
+  Badge displayed by client  e.g. "Verified (Tier 3) — Signet Score 106"
+```
+
+
+## The Four Tiers
+
+| Tier | Name                        | Who issues                              | What it proves                                      | Score contribution |
+|------|-----------------------------|-----------------------------------------|-----------------------------------------------------|--------------------|
+| 1    | Self-declared               | Subject themselves                      | "I exist and I own this key"                        | —                  |
+| 2    | Web-of-trust                | Peers (kind 31000, `type: vouch`)              | Enough known people can vouch for this identity     | +2–8 per vouch     |
+| 3    | Professionally verified     | Licensed professional (kind 31000, `type: credential`)      | Government document seen; adult age confirmed       | +40               |
+| 4    | Professional + child safety | Licensed professional (kind 31000, `type: credential`)      | Tier 3 plus authorisation to interact with minors   | +40               |
+
+Tier 2 requires at least 3 vouches from Tier 2+ peers (configurable per community via kind 30078 (NIP-78) policy).
+Tiers 3 and 4 are issued in a two-credential ceremony: one Natural Person credential (carries document
+nullifier and Merkle root) and one anonymous Persona credential (carries age range only, no identifying data).
+
+
+## Three Implementation Levels
+
+### Level 1 — Display badges (a weekend)
+
+Read kind 31000 (`type: credential` and `type: vouch`) from relays, call `computeBadge`, show a label.
+No cryptography required beyond Schnorr signature verification (optional).
+
+### Level 2 — Issue vouches (a few days)
+
+Add kind 31000 (`type: vouch`) vouch issuance. Requires Schnorr signing, relay write access, and basic
+kind 30078 (NIP-78) policy parsing so your client respects community verification thresholds.
+
+### Level 3 — Full protocol (weeks)
+
+Issue professional credentials, manage verifier lifecycle (kind 31000 types: verifier, challenge, revocation), build
+guardian delegation (kind 31000, `type: delegation`), support credential chains (supersedes / superseded-by),
+and integrate the voting extension (kinds 30482–30484). The voting extension is specified in `spec/voting.md` and implemented in the separate `nostr-anon-vote` package, not in `signet-protocol`; this package ships only the linkable ring signature primitives it builds on (`lsagSign`, `lsagVerify`, `computeKeyImage`).
+
+
+## How Verification Works (Tier 3 / 4)
+
+```
+  Subject                 Verifier
+    |                        |
+    |--- presents document -->|
+    |                        |
+    |        Verifier computes nullifier:
+    |        SHA-256(docType || country || docNumber || salt)
+    |        (prevents duplicate identity; document never stored)
+    |                        |
+    |        Verifier builds Merkle tree:
+    |        leaves = verified attributes (name, DOB, address, ...)
+    |        only root is published on-chain
+    |                        |
+    |        Verifier creates zero-knowledge age range proof
+    |        (proves "subject is 18+" without revealing birth date)
+    |                        |
+    |        Two credentials signed and published:
+    |          kind 31000 Natural Person  (nullifier + Merkle root, type: credential)
+    |          kind 31000 Persona         (age range only, anonymous, type: credential)
+    |                        |
+    v                        v
+               Both events published to Nostr relays
+```
+
+Professional verifiers are themselves credentialed (kind 31000, `type: verifier`) and require cross-verification
+by two other licensed professionals before becoming active. A challenge / revocation mechanism
+(kind 31000 types: `challenge` and `revocation`) allows the community to remove a fraudulent verifier.
+
+
+## Event Kinds Reference
+
+| Kind  | Type tag          | Purpose                                            |
+|-------|-------------------|----------------------------------------------------|
+| 31000 | `credential`      | Verification credential for any tier               |
+| 31000 | `vouch`           | Peer attestation (Tier 2 building block)           |
+| 30078 | —                 | Policy: community verification requirements (NIP-78) |
+| 31000 | `verifier`        | Professional verifier credential                   |
+| 31000 | `challenge`       | Report a suspected fraudulent verifier             |
+| 31000 | `revocation`      | Remove a verifier after threshold confirmations    |
+| 31000 | `identity-bridge` | Link two keypairs via ring signature               |
+| 31000 | `delegation`      | Guardian / agent delegation with scoped permission |
+| 30482 | —                 | Voting extension: define an election               |
+| 30483 | —                 | Voting extension: cast an anonymous ballot         |
+| 30484 | —                 | Voting extension: publish tallied result           |
+
+Kinds 30482–30484 are specified in `spec/voting.md` and implemented in the separate `nostr-anon-vote` package, not in `signet-protocol`.
+
+
+## Integrating at Level 1
+
+Install the library:
+
+```
+npm install signet-protocol
+```
+
+Fetch events from a relay, then call `computeBadge`:
+
+```typescript
+import { computeBadge, buildBadgeFilters, fetchFromRelay, meetsMinimumTier } from 'signet-protocol';
+import type { NostrEvent } from 'signet-protocol';
+
+// 1. Build relay filters for one or more pubkeys
+const pubkeys = ['<hex-pubkey>'];
+const filters = buildBadgeFilters(pubkeys);
+// filters = [{ kinds: [31000], '#d': ['credential:<hex-pubkey>', 'vouch:<hex-pubkey>'] }]
+
+// 2. Fetch events from your relay (fetchFromRelay is the package's own client; any Nostr client works)
+const events: NostrEvent[] = await fetchFromRelay('wss://relay.example.com', filters);
+
+// 3. Compute the badge
+const badge = await computeBadge(pubkeys[0], events, { verifySignatures: true });
+
+// badge.displayLabel  => "Verified (Tier 3)"
+// badge.score         => 106 (illustrative; see the score note below)
+// badge.tier          => 3
+// badge.vouchCount    => 5
+
+// 4. Gate a feature on minimum tier
+if (meetsMinimumTier(badge, 2)) {
+  // allow posting in a verified-only community
+}
+```
+
+`computeBadge` accepts any mix of kind 31000 (`type: credential` and `type: vouch`) events. It handles expiry, deduplication
+(one vouch counted per voucher pubkey), and optional Schnorr signature verification. The result is
+a plain object — no rendering assumptions are made.
+
+- `verifySignatures` defaults to `false`. `computeBadge(pubkey, events)` with no options checks no signatures, so keep `{ verifySignatures: true }` unless the events were already verified. `fetchFromRelay` drops events with an invalid signature or id by default; events from any other source are not checked for you.
+- `badge.score` is on the 0–200 Signet IQ scale but is a Level 1 approximation of `computeTrustScore(...).score`: it ignores account age and identity bridges and applies no per-type caps (1 professional verification, 3 in-person vouches, 5 online vouches). Use `computeTrustScore` for the full score.
+- `computeBadge` does not check who issued a Tier 3 or Tier 4 credential, and `buildBadgeFilters` fetches no verifier or revocation events. Any key can sign an event that carries `tier: 3` and it will count. To require an activated, unrevoked verifier, fetch the verifier credentials, their vouches and revocations yourself, apply `checkCrossVerification(...).activated` and `isVerifierRevoked(...)`, and drop other issuers' Tier 3 and Tier 4 credentials before calling `computeBadge` (see `llms.txt`).
+
+The `buildBadgeFilters` helper returns a standard Nostr REQ filter array ready for use with any
+relay client library.
+
+
+## Further Reading
+
+- Full protocol specification: `spec/protocol.md`
+- Voting extension: `spec/voting.md`
+- Level 1 badge library: `src/badge.ts`
+- Signet Score details: `src/trust-score.ts`
+- Full working example: `examples/full-flow.ts`
+- Jurisdiction-specific examples: `examples/jurisdictions/`
+- "Signet me" peer verification: `examples/signet-me.ts`