signet-protocol 1.11.1 → 1.11.3

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` checks who issued a Tier 3 or Tier 4 credential only when you pass `isTrustedIssuer`, and `buildBadgeFilters` does not fetch verifier or revocation events. Without the option, 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, decide which issuers pass with `checkCrossVerification(...).activated` and `isVerifierRevoked(...)`, and pass `{ isTrustedIssuer: (pk) => accepted.has(pk) }` to `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/dist/badge.d.ts

@@ -26,12 +26,16 @@ export type TrustLevel = 'unverified' | 'self-declared' | 'vouched' | 'professio
  *
  * @param pubkey - The Nostr pubkey to compute a badge for
  * @param events - All relevant kind 31000 (`type: credential` and `type: vouch`) events
- * @param options - Optional configuration
+ * @param options - Optional configuration. `isTrustedIssuer`, when given, is
+ *   called with the signer of each Tier 3/4 or `verification-type: professional`
+ *   credential; credentials whose issuer it rejects are skipped. Without it,
+ *   any key's Tier 3/4 credential counts.
  * @returns Badge info for display
  */
 export declare function computeBadge(pubkey: string, events: NostrEvent[], options?: {
     verifySignatures?: boolean;
     now?: number;
+    isTrustedIssuer?: (issuerPubkey: string) => boolean;
 }): Promise<BadgeInfo>;
 /**
  * Get the trust level classification for a badge.

package/dist/badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../src/badge.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAIrE,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAkB5G;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,OAAO,CAAC,SAAS,CAAC,CAyGpB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAG1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAE/E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAYxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAS/F"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../src/badge.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAIrE,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAkB5G;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,CAAC,EAAE;IACR,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CACrD,GACA,OAAO,CAAC,SAAS,CAAC,CAgHpB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAG1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAE/E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAYxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAS/F"}

package/dist/badge.js

@@ -23,12 +23,16 @@ const TIER_TO_TRUST_LEVEL = {
  *
  * @param pubkey - The Nostr pubkey to compute a badge for
  * @param events - All relevant kind 31000 (`type: credential` and `type: vouch`) events
- * @param options - Optional configuration
+ * @param options - Optional configuration. `isTrustedIssuer`, when given, is
+ *   called with the signer of each Tier 3/4 or `verification-type: professional`
+ *   credential; credentials whose issuer it rejects are skipped. Without it,
+ *   any key's Tier 3/4 credential counts.
  * @returns Badge info for display
  */
 export async function computeBadge(pubkey, events, options) {
     const now = options?.now ?? Math.floor(Date.now() / 1000);
     const verify = options?.verifySignatures ?? false;
+    const isTrustedIssuer = options?.isTrustedIssuer;
     let highestTier = 1;
     let rawScore = 0;
     let credentialCount = 0;
@@ -61,6 +65,13 @@ export async function computeBadge(pubkey, events, options) {
         // Optional signature verification
         if (verify && !await verifyEvent(event))
             continue;
+        const rawTier = parseInt(getTagValue(event, 'tier') || '1', 10);
+        const tier = (rawTier >= 1 && rawTier <= 4 ? rawTier : 1);
+        const verificationType = getTagValue(event, 'verification-type');
+        // Optional issuer standing: professional-grade credentials need a trusted issuer
+        if (isTrustedIssuer && (tier >= 3 || verificationType === 'professional') && !isTrustedIssuer(event.pubkey)) {
+            continue;
+        }
         hasAnyCredential = true;
         credentialCount++;
         // Capture entity type from the first credential that declares one
@@ -69,11 +80,8 @@ export async function computeBadge(pubkey, events, options) {
             if (et)
                 entityType = et;
         }
-        const rawTier = parseInt(getTagValue(event, 'tier') || '1', 10);
-        const tier = (rawTier >= 1 && rawTier <= 4 ? rawTier : 1);
         if (tier > highestTier)
             highestTier = tier;
-        const verificationType = getTagValue(event, 'verification-type');
         if (verificationType === 'professional') {
             rawScore += TRUST_WEIGHTS.PROFESSIONAL_VERIFICATION;
         }
@@ -90,12 +98,13 @@ export async function computeBadge(pubkey, events, options) {
         const subject = dTag.startsWith('vouch:') ? dTag.slice('vouch:'.length) : dTag;
         if (subject !== pubkey)
             continue;
-        // One vouch per voucher
+        // One vouch per voucher. Verify before claiming the slot, so a forged
+        // vouch under a voucher's pubkey cannot shadow that voucher's real one.
         if (vouchersSeen.has(event.pubkey))
             continue;
-        vouchersSeen.add(event.pubkey);
         if (verify && !await verifyEvent(event))
             continue;
+        vouchersSeen.add(event.pubkey);
         vouchCount++;
         const method = getTagValue(event, 'method');
         const rawVoucherScore = parseInt(getTagValue(event, 'voucher-score') || '50', 10);

package/dist/badge.js.map

@@ -1 +1 @@
-{"version":3,"file":"badge.js","sourceRoot":"","sources":["../src/badge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"badge.js","sourceRoot":"","sources":["../src/badge.ts"],"names":[],"mappings":"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"}

package/dist/verifiers.d.ts

@@ -6,8 +6,19 @@ export declare function createVerifierCredential(privateKey: string, params: Ver
 /** Parse a verifier credential event */
 export declare function parseVerifier(event: NostrEvent): ParsedVerifier | null;
 /** Check if a verifier has sufficient cross-verification.
- *  Requires vouches from verified professionals in different fields. */
-export declare function checkCrossVerification(verifierPubkey: string, vouches: NostrEvent[], verifierCredentials: NostrEvent[]): {
+ *  Requires vouches from verified professionals in different fields.
+ *
+ *  The spec also requires each voucher to be an active, non-revoked verifier.
+ *  Pass `options.revocations` to skip vouchers that `isVerifierRevoked` reports
+ *  as revoked, and `options.isActiveVerifier` to skip vouchers your client does
+ *  not treat as activated. Activation is recursive (a voucher's own activation
+ *  depends on its vouchers), so the library takes it as a caller-supplied
+ *  predicate rather than resolving the chain itself. Without these options a
+ *  voucher only needs a `type: verifier` credential with a `profession` tag. */
+export declare function checkCrossVerification(verifierPubkey: string, vouches: NostrEvent[], verifierCredentials: NostrEvent[], options?: {
+    revocations?: NostrEvent[];
+    isActiveVerifier?: (voucherPubkey: string) => boolean;
+}): {
     activated: boolean;
     vouchCount: number;
     professions: string[];

package/dist/verifiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verifiers.d.ts","sourceRoot":"","sources":["../src/verifiers.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,cAAc,EACd,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB,kDAAkD;AAClD,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,cAAc,GACrB,aAAa,CA0Bf;AAED,4CAA4C;AAC5C,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,UAAU,CAAC,CAIrB;AAED,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAetE;AAED;wEACwE;AACxE,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,UAAU,EAAE,EACrB,mBAAmB,EAAE,UAAU,EAAE,GAChC;IACD,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAuDA;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,UAAU,EAAE,GACxB,OAAO,CAQT"}
+{"version":3,"file":"verifiers.d.ts","sourceRoot":"","sources":["../src/verifiers.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,cAAc,EACd,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB,kDAAkD;AAClD,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,cAAc,GACrB,aAAa,CA0Bf;AAED,4CAA4C;AAC5C,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,UAAU,CAAC,CAIrB;AAED,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAetE;AAED;;;;;;;;;gFASgF;AAChF,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,UAAU,EAAE,EACrB,mBAAmB,EAAE,UAAU,EAAE,EACjC,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC;CACvD,GACA;IACD,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CA2DA;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,UAAU,EAAE,GACxB,OAAO,CAQT"}

package/dist/verifiers.js

@@ -54,8 +54,16 @@ export function parseVerifier(event) {
     };
 }
 /** Check if a verifier has sufficient cross-verification.
- *  Requires vouches from verified professionals in different fields. */
-export function checkCrossVerification(verifierPubkey, vouches, verifierCredentials) {
+ *  Requires vouches from verified professionals in different fields.
+ *
+ *  The spec also requires each voucher to be an active, non-revoked verifier.
+ *  Pass `options.revocations` to skip vouchers that `isVerifierRevoked` reports
+ *  as revoked, and `options.isActiveVerifier` to skip vouchers your client does
+ *  not treat as activated. Activation is recursive (a voucher's own activation
+ *  depends on its vouchers), so the library takes it as a caller-supplied
+ *  predicate rather than resolving the chain itself. Without these options a
+ *  voucher only needs a `type: verifier` credential with a `profession` tag. */
+export function checkCrossVerification(verifierPubkey, vouches, verifierCredentials, options) {
     const errors = [];
     const professionsSet = new Set();
     const vouchersSeen = new Set();
@@ -86,6 +94,11 @@ export function checkCrossVerification(verifierPubkey, vouches, verifierCredenti
         const voucherProfession = verifierProfessions.get(vouch.pubkey);
         if (!voucherProfession)
             continue;
+        // Voucher must be active and not revoked, when the caller supplies the evidence
+        if (options?.revocations && isVerifierRevoked(vouch.pubkey, options.revocations))
+            continue;
+        if (options?.isActiveVerifier && !options.isActiveVerifier(vouch.pubkey))
+            continue;
         // One vouch per voucher
         if (vouchersSeen.has(vouch.pubkey))
             continue;

package/dist/verifiers.js.map

@@ -1 +1 @@
-{"version":3,"file":"verifiers.js","sourceRoot":"","sources":["../src/verifiers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"verifiers.js","sourceRoot":"","sources":["../src/verifiers.ts"],"names":[],"mappings":"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"}

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 opt-in. `computeBadge` checks who issued a Tier 3 or Tier 4 credential only when you pass `isTrustedIssuer`, and `buildBadgeFilters` does not fetch verifier or revocation events. Without the option, 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, decide which issuers pass with `checkCrossVerification(...).activated` and `isVerifierRevoked(...)`, and pass `{ isTrustedIssuer: (pk) => accepted.has(pk) }` to `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.