signet-protocol 1.11.1 → 1.11.3

package/examples/signet-me.ts

@@ -0,0 +1,253 @@
+// Example: Full "Signet Me" Flow
+// Profile creation → backup → connection → verification words
+//
+// Run: npx tsx examples/signet-me.ts
+
+import {
+  generateMnemonic,
+  validateMnemonic,
+  mnemonicToEntropy,
+  entropyToMnemonic,
+  createSignetIdentity,
+  deriveAdditionalPersona,
+  splitSecret,
+  reconstructSecret,
+  shareToWords,
+  wordsToShare,
+  createQRPayload,
+  serializeQRPayload,
+  parseQRPayload,
+  computeSharedSecret,
+  createConnection,
+  getSignetWords,
+  verifySignetWords,
+  formatSignetWords,
+  getSignetDisplay,
+} from '../src/index.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1: Alice creates her identity
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('═══════════════════════════════════════════════════');
+console.log('  STEP 1: Profile Creation');
+console.log('═══════════════════════════════════════════════════\n');
+
+const aliceMnemonic = generateMnemonic();
+const aliceIdentity = createSignetIdentity(aliceMnemonic);
+const alice = {
+  privateKey: bytesToHex(aliceIdentity.naturalPerson.identity.privateKey),
+  publicKey: bytesToHex(aliceIdentity.naturalPerson.identity.publicKey),
+};
+
+console.log('Alice creates a new Signet identity:\n');
+console.log(`  Mnemonic:    ${aliceMnemonic}`);
+console.log(`  Public Key:  ${alice.publicKey.slice(0, 16)}...`);
+console.log(`  Valid:        ${validateMnemonic(aliceMnemonic)}`);
+
+// Alice also derives a child persona
+const aliceChildPersona = deriveAdditionalPersona(aliceIdentity.root, 'child', 0);
+const aliceChild = {
+  publicKey: bytesToHex(aliceChildPersona.identity.publicKey),
+};
+console.log(`\n  Child's Key: ${aliceChild.publicKey.slice(0, 16)}... (persona: child)`);
+aliceIdentity.root.destroy();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2: Alice backs up her seed using Shamir's Secret Sharing
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  STEP 2: Shared Backup (Shamir 2-of-3)');
+console.log('═══════════════════════════════════════════════════\n');
+
+const entropy = mnemonicToEntropy(aliceMnemonic);
+const shares = splitSecret(entropy, 2, 3);
+
+console.log('Alice splits her seed into 3 shares (any 2 reconstruct):\n');
+for (const share of shares) {
+  const words = shareToWords(share);
+  console.log(`  Share ${share.id}: ${words.slice(0, 4).join(' ')}... (${words.length} words)`);
+}
+
+// Verify reconstruction with shares 1 and 3 (skipping share 2)
+const reconstructed = reconstructSecret(
+  [wordsToShare(shareToWords(shares[0])), wordsToShare(shareToWords(shares[2]))],
+  2
+);
+const reconstructedMnemonic = entropyToMnemonic(reconstructed);
+console.log(`\n  Reconstructed from shares 1 + 3: ${reconstructedMnemonic === aliceMnemonic ? 'SUCCESS ✓' : 'FAILED ✗'}`);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3: Bob creates his identity
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  STEP 3: Bob Creates His Identity');
+console.log('═══════════════════════════════════════════════════\n');
+
+const bobMnemonic = generateMnemonic();
+const bobIdentity = createSignetIdentity(bobMnemonic);
+const bob = {
+  privateKey: bytesToHex(bobIdentity.naturalPerson.identity.privateKey),
+  publicKey: bytesToHex(bobIdentity.naturalPerson.identity.publicKey),
+};
+const bobChildPersona = deriveAdditionalPersona(bobIdentity.root, 'child', 0);
+const bobChild = {
+  publicKey: bytesToHex(bobChildPersona.identity.publicKey),
+};
+bobIdentity.root.destroy();
+
+console.log(`Bob's identity:`);
+console.log(`  Public Key:  ${bob.publicKey.slice(0, 16)}...`);
+console.log(`  Child's Key: ${bobChild.publicKey.slice(0, 16)}...`);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 4: Alice and Bob meet in person — QR code exchange
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  STEP 4: In-Person Connection (QR Exchange)');
+console.log('═══════════════════════════════════════════════════\n');
+
+// Alice shows her QR code with selected contact info
+const aliceQR = createQRPayload(alice.publicKey, {
+  name: 'Alice',
+  mobile: '+44 7700 900000',
+  childPubkeys: [aliceChild.publicKey],
+});
+
+// Bob shows his QR code
+const bobQR = createQRPayload(bob.publicKey, {
+  name: 'Bob',
+  mobile: '+44 7700 900001',
+  address: '42 Oak Lane, London',
+  childPubkeys: [bobChild.publicKey],
+});
+
+console.log('Alice and Bob meet at a local meetup. They scan each other\'s QR codes.\n');
+
+// Simulate the QR scan — each party scans the other's serialized payload
+const aliceScannedBob = parseQRPayload(serializeQRPayload(bobQR));
+const bobScannedAlice = parseQRPayload(serializeQRPayload(aliceQR));
+
+// Each creates a connection
+const aliceConnection = createConnection(alice.privateKey, aliceScannedBob, {
+  name: 'Alice',
+  mobile: '+44 7700 900000',
+  childPubkeys: [aliceChild.publicKey],
+});
+
+const bobConnection = createConnection(bob.privateKey, bobScannedAlice, {
+  name: 'Bob',
+  mobile: '+44 7700 900001',
+  address: '42 Oak Lane, London',
+  childPubkeys: [bobChild.publicKey],
+});
+
+console.log(`Alice → Bob shared secret: ${aliceConnection.sharedSecret.slice(0, 16)}...`);
+console.log(`Bob → Alice shared secret: ${bobConnection.sharedSecret.slice(0, 16)}...`);
+console.log(`Secrets match:             ${aliceConnection.sharedSecret === bobConnection.sharedSecret ? 'YES ✓' : 'NO ✗'}`);
+console.log(`\nAlice sees Bob's info:`);
+console.log(`  Name:   ${aliceConnection.theirInfo.name}`);
+console.log(`  Mobile: ${aliceConnection.theirInfo.mobile}`);
+console.log(`  Kids:   ${aliceConnection.theirInfo.childPubkeys?.length} child key(s)`);
+console.log(`\nBob sees Alice's info:`);
+console.log(`  Name:   ${bobConnection.theirInfo.name}`);
+console.log(`  Mobile: ${bobConnection.theirInfo.mobile}`);
+console.log(`  Kids:   ${bobConnection.theirInfo.childPubkeys?.length} child key(s)`);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 5: Months later — Bob calls Alice asking for money
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  STEP 5: "Signet Me" — Phone Verification');
+console.log('═══════════════════════════════════════════════════\n');
+
+console.log('Six months later, Bob calls Alice:');
+console.log('"Hey Alice, it\'s Bob. I\'m in a tight spot — can you send');
+console.log(' some cash to my new bank account?"');
+console.log('');
+console.log('Alice: "Sure, no problem. Signet me first."\n');
+
+// Both open each other's profiles at the same time
+const now = Date.now();
+
+const aliceSees = getSignetDisplay(aliceConnection.sharedSecret, now);
+const bobSees = getSignetDisplay(bobConnection.sharedSecret, now);
+
+console.log('Alice opens Bob\'s profile and sees:');
+console.log(`  My Signet: ${aliceSees.formatted}`);
+console.log(`  Expires in: ${aliceSees.expiresIn.toFixed(0)}s`);
+console.log('');
+console.log('Bob opens Alice\'s profile and sees:');
+console.log(`  My Signet: ${bobSees.formatted}`);
+console.log(`  Expires in: ${bobSees.expiresIn.toFixed(0)}s`);
+console.log('');
+console.log(`Words match: ${aliceSees.formatted === bobSees.formatted ? 'YES ✓' : 'NO ✗'}`);
+
+// Bob reads the words to Alice
+const bobReadsWords = getSignetWords(bobConnection.sharedSecret, now);
+const aliceVerifies = verifySignetWords(aliceConnection.sharedSecret, bobReadsWords, now);
+
+console.log(`\nBob reads: "${formatSignetWords(bobReadsWords)}"`);
+console.log(`Alice verifies: ${aliceVerifies ? 'MATCH ✓ — It\'s really Bob!' : 'NO MATCH ✗ — Impostor!'}`);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 6: Demonstrating word rotation
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  STEP 6: Word Rotation');
+console.log('═══════════════════════════════════════════════════\n');
+
+console.log('Words rotate every 30 seconds:\n');
+for (let i = 0; i < 4; i++) {
+  const futureTime = now + i * 30_000;
+  const words = getSignetWords(aliceConnection.sharedSecret, futureTime);
+  const label = i === 0 ? 'Now     ' : `+${i * 30}s     `;
+  console.log(`  ${label} ${formatSignetWords(words)}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 7: Bank scenario
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  STEP 7: Bank Verification');
+console.log('═══════════════════════════════════════════════════\n');
+
+// The bank has a Nostr keypair too
+const bankMnemonic = generateMnemonic();
+const bankIdentity = createSignetIdentity(bankMnemonic);
+const bank = {
+  privateKey: bytesToHex(bankIdentity.naturalPerson.identity.privateKey),
+  publicKey: bytesToHex(bankIdentity.naturalPerson.identity.publicKey),
+};
+bankIdentity.root.destroy();
+
+// Alice visits the bank and scans their QR code
+const bankQR = createQRPayload(bank.publicKey, { name: 'High Street Bank' });
+const aliceBankConnection = createConnection(alice.privateKey, parseQRPayload(serializeQRPayload(bankQR)), {
+  name: 'Alice',
+});
+
+// Bank also stores the connection
+const bankAliceSecret = computeSharedSecret(bank.privateKey, alice.publicKey);
+
+console.log('"The bank" calls Alice about suspicious activity.\n');
+console.log('Alice: "Read me my signet."\n');
+
+const bankNow = Date.now();
+const bankWords = getSignetWords(bankAliceSecret, bankNow);
+const aliceBankWords = getSignetWords(aliceBankConnection.sharedSecret, bankNow);
+
+console.log(`Bank agent reads:  ${formatSignetWords(bankWords)}`);
+console.log(`Alice sees:        ${formatSignetWords(aliceBankWords)}`);
+console.log(`Match:             ${formatSignetWords(bankWords) === formatSignetWords(aliceBankWords) ? 'YES ✓ — It\'s really the bank.' : 'NO ✗ — Scam call!'}`);
+
+console.log('\n═══════════════════════════════════════════════════');
+console.log('  Done. Your signet is your proof.');
+console.log('═══════════════════════════════════════════════════');

package/llms-full.txt

@@ -24,6 +24,7 @@ const events = await fetchFromRelay('wss://relay.example.com', filters);
 // Compute badge (async: returns Promise<BadgeInfo>)
 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 "Trust & Badges")
 
 // Gate features on verification level
 if (meetsMinimumTier(badge, 2)) {
@@ -31,6 +32,8 @@ if (meetsMinimumTier(badge, 2)) {
 }
 ```
 
+`verifySignatures` defaults to `false` in `computeBadge`, so keep `{ verifySignatures: true }` in copied code unless the events were already verified. `computeBadge` also does not check who issued a Tier 3 or Tier 4 credential; see "Who may issue Tier 3 and Tier 4" before gating on a professional tier.
+
 `fetchFromRelay(relayUrl: string, filters: NostrFilter[]): Promise<NostrEvent[]>` connects, collects events until EOSE and disconnects. Non-localhost relay URLs must be `wss://`. Any other Nostr client works equally well: pass the `buildBadgeFilters` output as REQ filters and give the returned events to `computeBadge`.
 
 ## Key Concepts
@@ -48,13 +51,16 @@ Conventions used throughout:
 - Of the `create*` functions documented in this file, the event-signing ones (credentials, vouches, policies, verifiers, challenges, revocations, identity bridges, guardian delegations) are async and return a signed `Promise<NostrEvent>` (with `id` and `sig`). The matching `build*Event` functions return an unsigned `UnsignedEvent`. The documented `create*` helpers that are not event signers return what is stated beside them: `createAgeRangeProof` (synchronous, `RangeProof`), `createSignetIdentity` / `createSignetIdentityFromNsec` (synchronous, `SignetIdentity`) and `createLinkageProof` (synchronous, `LinkageProof`). The package root exports other `create*` functions that this file does not cover (for example `createTwoCredentialCeremony`, `createBondProof`); check their return types in `src/` rather than assuming the event-signer shape.
 - Tiers are `SignetTier` (`1 | 2 | 3 | 4`). Timestamps (`expiresAt`, `occurredAt`, `accountCreatedAt`) are unix seconds.
 - Throws use the `SignetError` hierarchy (`SignetValidationError`, `SignetCryptoError`).
+- Types are exported from the package root as type-only exports (use `import type { NostrEvent } from 'signet-protocol'`; they have no runtime value): `NostrEvent` (`{ id, pubkey, created_at, kind, tags: string[][], content, sig }`), `UnsignedEvent` (the same without `id` and `sig`), `NostrFilter` (`{ ids?, authors?, kinds?, '#d'?, '#p'?, '#L'?, '#l'?, since?, until?, limit? }`), `BadgeInfo` and `RangeProof`. The error classes `SignetError`, `SignetValidationError` and `SignetCryptoError` are exported from the root as ordinary values you can use with `instanceof`. `src/errors.ts` also defines `SignetVotingError`, but it is not exported from the root and nothing in this package throws it.
+- Arguments named `events`, `credentials`, `vouches`, `bridges`, `revocations`, `verifierCredentials` and `confirmationEvents` are raw signed `NostrEvent[]` as returned by a relay, not parsed objects (`ParsedCredential`, `ParsedVouch` and so on). The functions read the tags themselves and skip events of the wrong kind or `type`. Unless a signature check is stated beside a function, it does not verify signatures: verify first, or fetch with `fetchFromRelay`, whose `RelayClient` drops events with an invalid signature or id by default.
+- Issuer standing is not checked by the Level 1 and scoring functions. See "Who may issue Tier 3 and Tier 4" below.
 
 ### Credentials (kind 31000, type: credential)
 - `createSelfDeclaredCredential(privateKey, scope = 'adult', expiresAt?)`: Tier 1. `scope` is `'adult' | 'adult+child'`.
 - `createPeerVouchedCredential(issuerPrivateKey, subjectPubkey, opts)`: Tier 2. `opts: { assertionEventId: string; assertionRelay?: string; expiresAt?: number }`. `assertionEventId` is the subject's Tier 1 event.
 - `createProfessionalCredential(verifierPrivateKey, subjectPubkey, opts)`: Tier 3. `opts: { assertionEventId: string; profession: string; jurisdiction: string; actualAge: number; assertionRelay?: string; expiresAt?: number; occurredAt?: number; proofBlob?: string }`. Generates an `'18+'` range proof from `actualAge` into the event content.
 - `createChildSafetyCredential(verifierPrivateKey, subjectPubkey, opts)`: Tier 4. Same `opts` as Tier 3 plus `ageRange: string` (the range proved, e.g. `'8-12'`).
-- `verifyCredential(event)`: `Promise<{ signatureValid: boolean; structureValid: boolean; expired: boolean; errors: string[] }>`
+- `verifyCredential(event: NostrEvent)`: `Promise<{ signatureValid: boolean; structureValid: boolean; expired: boolean; errors: string[] }>`. Checks the event's own Schnorr signature, tag structure (for example a Tier 3 or Tier 4 credential must carry `verification-type: professional` and a `profession` tag) and expiry. It does not look at who signed it: a valid result does not mean the issuer is an activated, unrevoked verifier. See "Who may issue Tier 3 and Tier 4".
 - `parseCredential(event)`: `ParsedCredential | null`
 
 `ageRange` format everywhere: `'<min>-<max>'` inclusive (e.g. `'8-12'`, `'13-17'`) or `'<min>+'` (e.g. `'18+'`, upper bound 150). Anything else fails to parse.
@@ -63,16 +69,26 @@ Default credential expiry is two years (`DEFAULT_CREDENTIAL_EXPIRY_SECONDS`) whe
 
 ### Vouches (kind 31000, type: vouch)
 - `createVouch(voucherPrivateKey, params)`: vouch for another user. `params: { subjectPubkey: string; method: 'in-person' | 'online'; voucherTier: SignetTier; voucherScore: number; context?: string; occurredAt?: number }`. `voucherScore` is the voucher's own Signet IQ (0–200).
-- `hasEnoughVouches(vouches, subjectPubkey, threshold = 3, minVoucherTier = 2)`: `boolean`. `true` when the number of qualifying vouches (one per voucher, voucher tier ≥ `minVoucherTier`) reaches `threshold`. `countQualifyingVouches(vouches, subjectPubkey, minVoucherTier?)` returns the count.
+- `hasEnoughVouches(vouches: NostrEvent[], subjectPubkey: string, threshold = 3, minVoucherTier: SignetTier = 2)`: `boolean`. `vouches` is raw kind 31000 vouch events (`NostrEvent[]`), not `ParsedVouch` objects. `true` when the number of qualifying vouches (one per voucher, `voucher-tier` tag ≥ `minVoucherTier`) reaches `threshold`. It does not verify signatures, and the voucher tier is the self-reported tag, not looked up. `countQualifyingVouches(vouches: NostrEvent[], subjectPubkey: string, minVoucherTier?: SignetTier)` returns the count.
 
 ### Trust & Badges
-- `computeBadge(pubkey, events, opts?)`: `Promise<BadgeInfo>`. `opts: { verifySignatures?: boolean (default false); now?: number }`. `BadgeInfo: { pubkey, tier, tierLabel, score, isVerified, displayLabel, credentialCount, vouchCount, entityType? }`.
-- `buildBadgeFilters(pubkeys: string[])`: `Array<{ kinds: number[]; '#d': string[] }>`. One filter for kind 31000 with d-tags `credential:<pubkey>` and `vouch:<pubkey>` for each pubkey.
+- `computeBadge(pubkey: string, events: NostrEvent[], opts?)`: `Promise<BadgeInfo>`. `opts: { verifySignatures?: boolean (default false); now?: number; isTrustedIssuer?: (issuerPubkey: string) => boolean }`. `BadgeInfo: { pubkey, tier, tierLabel, score, isVerified, displayLabel, credentialCount, vouchCount, entityType? }`. `verifySignatures` defaults to `false`: with the default, `computeBadge` does not check any signature, so a call that omits it trusts every event it is given. Pass `{ verifySignatures: true }` unless the events came from `fetchFromRelay` or another source that has already dropped events with an invalid signature or id. `computeBadge` reads the `tier`, `verification-type`, `expiration`, `method` and `voucher-score` tags. It does not run `validateCredential`. It checks who signed a credential only when `isTrustedIssuer` is given: the predicate is called with `event.pubkey` of each credential that has `tier` 3 or 4 or `verification-type: professional`, and a credential it rejects is skipped (it adds nothing to the tier, score or `credentialCount`). Without the predicate, issuer standing is not enforced (see "Who may issue Tier 3 and Tier 4"). With `verifySignatures: true`, a vouch whose signature fails does not take its voucher's one-vouch slot.
+- `buildBadgeFilters(pubkeys: string[])`: `Array<{ kinds: number[]; '#d': string[] }>`. One filter for kind 31000 with d-tags `credential:<pubkey>` and `vouch:<pubkey>` for each pubkey. It fetches no verifier, challenge or revocation events, so the events it returns cannot be used to check issuer standing.
 - `meetsMinimumTier(badge: BadgeInfo, minTier: SignetTier)`: `boolean`. `true` only when `badge.isVerified` and `badge.tier >= minTier`.
-- `computeTrustScore(subjectPubkey, credentials, vouches, accountCreatedAt?, bridges?)`: `TrustScoreBreakdown` (`{ score, tier, professionalVerifications, inPersonVouches, onlineVouches, accountAgeDays, signals }`). This is the full Signet IQ. It does not verify signatures.
+- `computeTrustScore(subjectPubkey: string, credentials: NostrEvent[], vouches: NostrEvent[], accountCreatedAt?: number, bridges?: NostrEvent[])`: `TrustScoreBreakdown` (`{ score, tier, professionalVerifications, inPersonVouches, onlineVouches, accountAgeDays, signals }`). This is the full Signet IQ. `credentials`, `vouches` and `bridges` are raw kind 31000 events (`NostrEvent[]`), not parsed objects. It does not verify signatures and, like `computeBadge`, does not check issuer standing. `bridges` are matched by `event.pubkey === subjectPubkey` and are not ring-signature verified here: run `verifyIdentityBridge` first.
 
 `badge.score` is on the same 0–200 scale and uses the same weights as `computeTrustScore(...).score` (professional verification 80, in-person vouch up to 16, online vouch up to 4, each vouch scaled by the voucher's score ÷ 200), but it is a Level 1 approximation, not the full IQ: `computeBadge` ignores account age and identity bridges and does not apply the per-type caps (1 professional, 3 in-person vouches, 5 online vouches). Use `computeTrustScore` when you need the full IQ.
 
+### Who may issue Tier 3 and Tier 4
+
+The library does not enforce issuer standing in `computeTrustScore`, `verifyCredential` or `countChallengeConfirmations`, and `computeBadge` enforces it only through the `isTrustedIssuer` option. A kind 31000 `type: credential` event that carries `tier: 3` (or 4) and `verification-type: professional` counts toward the tier and the score whichever key signed it, including a key that has never published a verifier credential, and `verifySignatures: true` only proves the signer wrote the event. `buildBadgeFilters` fetches only `credential:` and `vouch:` events, so a badge built from its output cannot tell a licensed verifier from any other key. The protocol requires issuers of Tier 3 and Tier 4 to be activated, unrevoked verifiers (see `spec/protocol.md`); your client has to decide which issuers pass and give `computeBadge` that decision:
+
+1. Fetch the candidate issuer's `type: verifier` credential, the vouches for that issuer, the verifier credentials of those vouchers, and any `type: revocation` events (all kind 31000). `buildBadgeFilters` does not fetch these, so build your own filters.
+2. Treat an issuer as acceptable only when `checkCrossVerification(issuerPubkey, vouches, verifierCredentials, { revocations, isActiveVerifier }).activated` is `true` and `isVerifierRevoked(issuerPubkey, revocations)` is `false`.
+3. Call `computeBadge(pubkey, events, { verifySignatures: true, isTrustedIssuer: (pk) => accepted.has(pk) })`, where `accepted` holds the issuers that passed step 2.
+
+Voucher activation is recursive (a voucher is active only if its own vouchers are), so `checkCrossVerification` takes it as the `isActiveVerifier` predicate rather than resolving the chain. Start from verifiers your client already accepts. Without `isActiveVerifier` and `revocations`, a voucher only needs a verifier credential with a `profession` tag.
+
 ### Policies (kind 30078, NIP-78)
 - `createPolicy(operatorPrivateKey, params)`: community verification requirements. `params: { communityId: string; adultMinTier: SignetTier; childMinTier: SignetTier; enforcement: 'client' | 'relay' | 'both'; minScore?: number; modMinTier?: SignetTier; verifierBond?: number; revocationThreshold?: number; description?: string }`. The d-tag is `signet:policy:<communityId>`.
 - `new PolicyChecker(policyEvent: NostrEvent)`: throws `SignetValidationError('Invalid policy event')` if the event is not a valid policy. Methods: `getPolicy(): ParsedPolicy`, `checkAdult(tier, score)`, `checkChild(tier, score)`, `checkModerator(tier, score)`. Each check returns `PolicyCheckResult`: `{ allowed: boolean; reason?: string; requiredTier: SignetTier; actualTier: SignetTier; requiredScore?: number; actualScore?: number }`.
@@ -80,20 +96,20 @@ Default credential expiry is two years (`DEFAULT_CREDENTIAL_EXPIRY_SECONDS`) whe
 
 ### Verifiers (kind 31000, type: verifier)
 - `createVerifierCredential(privateKey, params)`: register as professional verifier. `params: { profession: string; jurisdiction: string; licenceHash: string; professionalBody: string; statement?: string; bondProof?: BondProof }`.
-- `checkCrossVerification(verifierPubkey, vouches, verifierCredentials)`: activation check. Returns `{ activated: boolean; vouchCount: number; professions: string[]; errors: string[] }`.
-- `isVerifierRevoked(verifierPubkey, revocations)`: `boolean`
+- `checkCrossVerification(verifierPubkey: string, vouches: NostrEvent[], verifierCredentials: NostrEvent[], options?: { revocations?: NostrEvent[]; isActiveVerifier?: (voucherPubkey: string) => boolean })`: activation check. `vouches` is kind 31000 vouch events (`NostrEvent[]`) and `verifierCredentials` is kind 31000 `type: verifier` events (`NostrEvent[]`), not parsed objects. Returns `{ activated: boolean; vouchCount: number; professions: string[]; errors: string[] }`. `activated` is `true` when at least `VERIFIER_ACTIVATION.MIN_VOUCHES` vouches for `verifierPubkey` come from distinct vouchers that each appear in `verifierCredentials` with a `profession` tag, and those vouchers cover at least `VERIFIER_ACTIVATION.MIN_PROFESSIONS` different professions. It does not verify signatures. The spec also requires each voucher to be an active, non-revoked verifier: pass `options.revocations` to skip any voucher `isVerifierRevoked` reports as revoked, and `options.isActiveVerifier` to skip vouchers your client does not treat as activated. Without these options neither is checked.
+- `isVerifierRevoked(verifierPubkey: string, revocations: NostrEvent[])`: `boolean`. `true` when any kind 31000 `type: revocation` event in `revocations` targets `verifierPubkey`. It does not verify signatures or check who signed the revocation.
 
 ### Challenges and Revocations (kind 31000, type: challenge / revocation)
 - `createChallenge(reporterPrivateKey, params)`: `Promise<NostrEvent>`. `params: { verifierPubkey: string; reason: 'anomalous-volume' | 'registry-mismatch' | 'fraudulent-attestation' | 'licence-revoked' | 'other'; evidenceType: string; reporterTier: SignetTier; evidence: string; occurredAt?: number }`. `evidence` becomes the event content.
 - `createRevocation(authorityPrivateKey, params)`: `Promise<NostrEvent>`. `params: { verifierPubkey: string; challengeEventId: string; confirmations: number; bondAction: 'slashed' | 'returned' | 'held'; scope: 'full' | 'partial'; effectiveAt: number; summary: string }`.
-- `countChallengeConfirmations(challengeEventId, confirmationEvents, credentialEvents)`: `number`
+- `countChallengeConfirmations(challengeEventId: string, confirmationEvents: NostrEvent[], credentialEvents: NostrEvent[])`: `number`. All arrays are raw `NostrEvent[]`. Counts distinct confirmation signers whose `challenge` tag equals `challengeEventId` and who hold a credential event with a `tier` tag of 3 or higher in `credentialEvents`. It does not verify signatures or the issuers of those credentials.
 - `hasReachedRevocationThreshold(confirmations, threshold = 5)`: `boolean`
 - `parseChallenge(event)` / `parseRevocation(event)`: parsed object or `null`.
 
 ### Identity Bridge (kind 31000, type: identity-bridge)
-- `createIdentityBridge(anonPrivateKey, realPrivateKey, ring, signerIndex, ringMinTier, opts?)`: link anonymous account to verified identity via ring signature. `ring: string[]` of pubkeys (at least 5, `MIN_BRIDGE_RING_SIZE`); `opts: { occurredAt?: number }`. Signed by the anonymous key.
-- `selectDecoyRing(verifiedPubkeys, realPubkey, ringSize = 5)`: `{ ring: string[]; signerIndex: number }`
-- `verifyIdentityBridge(event, opts?)`: `Promise<boolean>`. `opts: { maxAgeSeconds?: number }` (default 24 hours; `0` disables the freshness check).
+- `createIdentityBridge(anonPrivateKey: string, realPrivateKey: string, ring: string[], signerIndex: number, ringMinTier: SignetTier, opts?)`: `Promise<NostrEvent>`. Links an anonymous account to a verified identity via ring signature. `ring: string[]` is the anonymity set of verified pubkeys (at least 5, `MIN_BRIDGE_RING_SIZE`) and must contain the public key of `realPrivateKey`. `signerIndex` is the zero-based position in `ring` of that real public key (`selectDecoyRing` returns it for you); a wrong index makes ring signing throw (`Private key does not match ring member at signerIndex`). `ringMinTier` is the lowest verification tier among the ring members, which you assert yourself: it is written to the event's `ring-min-tier` tag and scales the bridge's contribution to `computeTrustScore` (`TRUST_WEIGHTS.IDENTITY_BRIDGE` of 50 × `ringMinTier` ÷ 4). Neither `createIdentityBridge` nor `verifyIdentityBridge` checks that the ring members hold that tier. `opts: { occurredAt?: number }`. Signed by the anonymous key.
+- `selectDecoyRing(verifiedPubkeys: string[], realPubkey: string, ringSize = 5)`: `{ ring: string[]; signerIndex: number }`. Picks decoys from `verifiedPubkeys` (`realPubkey` is filtered out of the pool if present) and places `realPubkey` at a random position. Throws if the pool has fewer than `ringSize - 1` other pubkeys.
+- `verifyIdentityBridge(event: NostrEvent, opts?)`: `Promise<boolean>`. `opts: { maxAgeSeconds?: number }` (default 24 hours; `0` disables the freshness check).
 
 ### ZKP Age Proofs
 - `createAgeRangeProof(age: number, ageRange: string, subjectPubkey?: string)`: `RangeProof` (synchronous). `subjectPubkey` binds the proof to one credential.
@@ -124,6 +140,8 @@ The voting extension (kinds 30482–30484) is specified in `spec/voting.md` and
 
 ## Optional
 
+These paths ship in the npm package (`spec/`, `examples/`, and the `docs/` pages named below and in the experimental section above), so the relative links resolve inside `node_modules/signet-protocol/`. The examples import from the package's own `src/` directory; in your own code import from `signet-protocol`.
+
 - [llms-full.txt](llms-full.txt): llms.txt plus the full protocol and voting specifications and the developer guides in one file
 - [Full protocol specification](spec/protocol.md)
 - [Voting extension specification](spec/voting.md)
@@ -503,6 +521,8 @@ Minimum requirement for verifier activation:
 - At least 2 different professions represented
 - Vouchers must themselves be active, non-revoked verifiers
 
+Activation is recursive: whether a voucher is active depends on its own vouchers. A client therefore resolves it from a set of verifiers it already accepts and cannot derive it from a single verifier's vouches alone. A client counting vouches (for activation or for a score) MUST check each vouch's signature before treating that voucher as seen, so that an invalid event carrying a voucher's pubkey cannot displace the voucher's valid vouch.
+
 ### Layer 3 — Rate Limiting / Anomaly Detection
 
 All credentials are public Nostr events. Issuance volume is visible to the entire network.
@@ -3406,7 +3426,7 @@ kind 30078 (NIP-78) policy parsing so your client respects community verificatio
 
 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).
+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)
@@ -3456,6 +3476,8 @@ by two other licensed professionals before becoming active. A challenge / revoca
 | 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
 
@@ -3483,7 +3505,7 @@ const events: NostrEvent[] = await fetchFromRelay('wss://relay.example.com', fil
 const badge = await computeBadge(pubkeys[0], events, { verifySignatures: true });
 
 // badge.displayLabel  => "Verified (Tier 3)"
-// badge.score         => 106
+// badge.score         => 106 (illustrative; see the score note below)
 // badge.tier          => 3
 // badge.vouchCount    => 5
 
@@ -3497,6 +3519,10 @@ if (meetsMinimumTier(badge, 2)) {
 (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` 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`).
+
 The `buildBadgeFilters` helper returns a standard Nostr REQ filter array ready for use with any
 relay client library.
 
@@ -3551,19 +3577,21 @@ npm install signet-protocol
 ### Code example
 
 ```typescript
-import { computeBadge, buildBadgeFilters } from 'signet-protocol';
+import { computeBadge, buildBadgeFilters, fetchFromRelay } from 'signet-protocol';
+
+const pubkey = '<hex-pubkey>';
 
-// 1. Fetch events from relay
+// 1. Fetch events from a relay (fetchFromRelay is the package's own client; any Nostr client works)
 const filters = buildBadgeFilters([pubkey]);
-// Send a REQ message to your relay with these filters.
 // 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); // async: returns Promise<BadgeInfo>
+const badge = await computeBadge(pubkey, events, { verifySignatures: true }); // async: returns Promise<BadgeInfo>
 
 // 3. Display
 if (badge.isVerified) {
-  showBadge(badge.tierLabel, badge.score);
+  console.log(badge.tierLabel, badge.score); // replace with your own rendering
 }
 ```
 
@@ -3590,6 +3618,11 @@ The `badge` object includes:
 - 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
@@ -3681,7 +3714,7 @@ Reference: `src/policies.ts`
 **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.
+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)
 
@@ -3689,7 +3722,7 @@ Level 3 is full reference implementation. This is appropriate for clients that w
 - **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.
+- **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.

package/llms.txt

@@ -24,6 +24,7 @@ const events = await fetchFromRelay('wss://relay.example.com', filters);
 // Compute badge (async: returns Promise<BadgeInfo>)
 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 "Trust & Badges")
 
 // Gate features on verification level
 if (meetsMinimumTier(badge, 2)) {
@@ -31,6 +32,8 @@ if (meetsMinimumTier(badge, 2)) {
 }
 ```
 
+`verifySignatures` defaults to `false` in `computeBadge`, so keep `{ verifySignatures: true }` in copied code unless the events were already verified. `computeBadge` also does not check who issued a Tier 3 or Tier 4 credential; see "Who may issue Tier 3 and Tier 4" before gating on a professional tier.
+
 `fetchFromRelay(relayUrl: string, filters: NostrFilter[]): Promise<NostrEvent[]>` connects, collects events until EOSE and disconnects. Non-localhost relay URLs must be `wss://`. Any other Nostr client works equally well: pass the `buildBadgeFilters` output as REQ filters and give the returned events to `computeBadge`.
 
 ## Key Concepts
@@ -48,13 +51,16 @@ Conventions used throughout:
 - Of the `create*` functions documented in this file, the event-signing ones (credentials, vouches, policies, verifiers, challenges, revocations, identity bridges, guardian delegations) are async and return a signed `Promise<NostrEvent>` (with `id` and `sig`). The matching `build*Event` functions return an unsigned `UnsignedEvent`. The documented `create*` helpers that are not event signers return what is stated beside them: `createAgeRangeProof` (synchronous, `RangeProof`), `createSignetIdentity` / `createSignetIdentityFromNsec` (synchronous, `SignetIdentity`) and `createLinkageProof` (synchronous, `LinkageProof`). The package root exports other `create*` functions that this file does not cover (for example `createTwoCredentialCeremony`, `createBondProof`); check their return types in `src/` rather than assuming the event-signer shape.
 - Tiers are `SignetTier` (`1 | 2 | 3 | 4`). Timestamps (`expiresAt`, `occurredAt`, `accountCreatedAt`) are unix seconds.
 - Throws use the `SignetError` hierarchy (`SignetValidationError`, `SignetCryptoError`).
+- Types are exported from the package root as type-only exports (use `import type { NostrEvent } from 'signet-protocol'`; they have no runtime value): `NostrEvent` (`{ id, pubkey, created_at, kind, tags: string[][], content, sig }`), `UnsignedEvent` (the same without `id` and `sig`), `NostrFilter` (`{ ids?, authors?, kinds?, '#d'?, '#p'?, '#L'?, '#l'?, since?, until?, limit? }`), `BadgeInfo` and `RangeProof`. The error classes `SignetError`, `SignetValidationError` and `SignetCryptoError` are exported from the root as ordinary values you can use with `instanceof`. `src/errors.ts` also defines `SignetVotingError`, but it is not exported from the root and nothing in this package throws it.
+- Arguments named `events`, `credentials`, `vouches`, `bridges`, `revocations`, `verifierCredentials` and `confirmationEvents` are raw signed `NostrEvent[]` as returned by a relay, not parsed objects (`ParsedCredential`, `ParsedVouch` and so on). The functions read the tags themselves and skip events of the wrong kind or `type`. Unless a signature check is stated beside a function, it does not verify signatures: verify first, or fetch with `fetchFromRelay`, whose `RelayClient` drops events with an invalid signature or id by default.
+- Issuer standing is not checked by the Level 1 and scoring functions. See "Who may issue Tier 3 and Tier 4" below.
 
 ### Credentials (kind 31000, type: credential)
 - `createSelfDeclaredCredential(privateKey, scope = 'adult', expiresAt?)`: Tier 1. `scope` is `'adult' | 'adult+child'`.
 - `createPeerVouchedCredential(issuerPrivateKey, subjectPubkey, opts)`: Tier 2. `opts: { assertionEventId: string; assertionRelay?: string; expiresAt?: number }`. `assertionEventId` is the subject's Tier 1 event.
 - `createProfessionalCredential(verifierPrivateKey, subjectPubkey, opts)`: Tier 3. `opts: { assertionEventId: string; profession: string; jurisdiction: string; actualAge: number; assertionRelay?: string; expiresAt?: number; occurredAt?: number; proofBlob?: string }`. Generates an `'18+'` range proof from `actualAge` into the event content.
 - `createChildSafetyCredential(verifierPrivateKey, subjectPubkey, opts)`: Tier 4. Same `opts` as Tier 3 plus `ageRange: string` (the range proved, e.g. `'8-12'`).
-- `verifyCredential(event)`: `Promise<{ signatureValid: boolean; structureValid: boolean; expired: boolean; errors: string[] }>`
+- `verifyCredential(event: NostrEvent)`: `Promise<{ signatureValid: boolean; structureValid: boolean; expired: boolean; errors: string[] }>`. Checks the event's own Schnorr signature, tag structure (for example a Tier 3 or Tier 4 credential must carry `verification-type: professional` and a `profession` tag) and expiry. It does not look at who signed it: a valid result does not mean the issuer is an activated, unrevoked verifier. See "Who may issue Tier 3 and Tier 4".
 - `parseCredential(event)`: `ParsedCredential | null`
 
 `ageRange` format everywhere: `'<min>-<max>'` inclusive (e.g. `'8-12'`, `'13-17'`) or `'<min>+'` (e.g. `'18+'`, upper bound 150). Anything else fails to parse.
@@ -63,16 +69,26 @@ Default credential expiry is two years (`DEFAULT_CREDENTIAL_EXPIRY_SECONDS`) whe
 
 ### Vouches (kind 31000, type: vouch)
 - `createVouch(voucherPrivateKey, params)`: vouch for another user. `params: { subjectPubkey: string; method: 'in-person' | 'online'; voucherTier: SignetTier; voucherScore: number; context?: string; occurredAt?: number }`. `voucherScore` is the voucher's own Signet IQ (0–200).
-- `hasEnoughVouches(vouches, subjectPubkey, threshold = 3, minVoucherTier = 2)`: `boolean`. `true` when the number of qualifying vouches (one per voucher, voucher tier ≥ `minVoucherTier`) reaches `threshold`. `countQualifyingVouches(vouches, subjectPubkey, minVoucherTier?)` returns the count.
+- `hasEnoughVouches(vouches: NostrEvent[], subjectPubkey: string, threshold = 3, minVoucherTier: SignetTier = 2)`: `boolean`. `vouches` is raw kind 31000 vouch events (`NostrEvent[]`), not `ParsedVouch` objects. `true` when the number of qualifying vouches (one per voucher, `voucher-tier` tag ≥ `minVoucherTier`) reaches `threshold`. It does not verify signatures, and the voucher tier is the self-reported tag, not looked up. `countQualifyingVouches(vouches: NostrEvent[], subjectPubkey: string, minVoucherTier?: SignetTier)` returns the count.
 
 ### Trust & Badges
-- `computeBadge(pubkey, events, opts?)`: `Promise<BadgeInfo>`. `opts: { verifySignatures?: boolean (default false); now?: number }`. `BadgeInfo: { pubkey, tier, tierLabel, score, isVerified, displayLabel, credentialCount, vouchCount, entityType? }`.
-- `buildBadgeFilters(pubkeys: string[])`: `Array<{ kinds: number[]; '#d': string[] }>`. One filter for kind 31000 with d-tags `credential:<pubkey>` and `vouch:<pubkey>` for each pubkey.
+- `computeBadge(pubkey: string, events: NostrEvent[], opts?)`: `Promise<BadgeInfo>`. `opts: { verifySignatures?: boolean (default false); now?: number; isTrustedIssuer?: (issuerPubkey: string) => boolean }`. `BadgeInfo: { pubkey, tier, tierLabel, score, isVerified, displayLabel, credentialCount, vouchCount, entityType? }`. `verifySignatures` defaults to `false`: with the default, `computeBadge` does not check any signature, so a call that omits it trusts every event it is given. Pass `{ verifySignatures: true }` unless the events came from `fetchFromRelay` or another source that has already dropped events with an invalid signature or id. `computeBadge` reads the `tier`, `verification-type`, `expiration`, `method` and `voucher-score` tags. It does not run `validateCredential`. It checks who signed a credential only when `isTrustedIssuer` is given: the predicate is called with `event.pubkey` of each credential that has `tier` 3 or 4 or `verification-type: professional`, and a credential it rejects is skipped (it adds nothing to the tier, score or `credentialCount`). Without the predicate, issuer standing is not enforced (see "Who may issue Tier 3 and Tier 4"). With `verifySignatures: true`, a vouch whose signature fails does not take its voucher's one-vouch slot.
+- `buildBadgeFilters(pubkeys: string[])`: `Array<{ kinds: number[]; '#d': string[] }>`. One filter for kind 31000 with d-tags `credential:<pubkey>` and `vouch:<pubkey>` for each pubkey. It fetches no verifier, challenge or revocation events, so the events it returns cannot be used to check issuer standing.
 - `meetsMinimumTier(badge: BadgeInfo, minTier: SignetTier)`: `boolean`. `true` only when `badge.isVerified` and `badge.tier >= minTier`.
-- `computeTrustScore(subjectPubkey, credentials, vouches, accountCreatedAt?, bridges?)`: `TrustScoreBreakdown` (`{ score, tier, professionalVerifications, inPersonVouches, onlineVouches, accountAgeDays, signals }`). This is the full Signet IQ. It does not verify signatures.
+- `computeTrustScore(subjectPubkey: string, credentials: NostrEvent[], vouches: NostrEvent[], accountCreatedAt?: number, bridges?: NostrEvent[])`: `TrustScoreBreakdown` (`{ score, tier, professionalVerifications, inPersonVouches, onlineVouches, accountAgeDays, signals }`). This is the full Signet IQ. `credentials`, `vouches` and `bridges` are raw kind 31000 events (`NostrEvent[]`), not parsed objects. It does not verify signatures and, like `computeBadge`, does not check issuer standing. `bridges` are matched by `event.pubkey === subjectPubkey` and are not ring-signature verified here: run `verifyIdentityBridge` first.
 
 `badge.score` is on the same 0–200 scale and uses the same weights as `computeTrustScore(...).score` (professional verification 80, in-person vouch up to 16, online vouch up to 4, each vouch scaled by the voucher's score ÷ 200), but it is a Level 1 approximation, not the full IQ: `computeBadge` ignores account age and identity bridges and does not apply the per-type caps (1 professional, 3 in-person vouches, 5 online vouches). Use `computeTrustScore` when you need the full IQ.
 
+### Who may issue Tier 3 and Tier 4
+
+The library does not enforce issuer standing in `computeTrustScore`, `verifyCredential` or `countChallengeConfirmations`, and `computeBadge` enforces it only through the `isTrustedIssuer` option. A kind 31000 `type: credential` event that carries `tier: 3` (or 4) and `verification-type: professional` counts toward the tier and the score whichever key signed it, including a key that has never published a verifier credential, and `verifySignatures: true` only proves the signer wrote the event. `buildBadgeFilters` fetches only `credential:` and `vouch:` events, so a badge built from its output cannot tell a licensed verifier from any other key. The protocol requires issuers of Tier 3 and Tier 4 to be activated, unrevoked verifiers (see `spec/protocol.md`); your client has to decide which issuers pass and give `computeBadge` that decision:
+
+1. Fetch the candidate issuer's `type: verifier` credential, the vouches for that issuer, the verifier credentials of those vouchers, and any `type: revocation` events (all kind 31000). `buildBadgeFilters` does not fetch these, so build your own filters.
+2. Treat an issuer as acceptable only when `checkCrossVerification(issuerPubkey, vouches, verifierCredentials, { revocations, isActiveVerifier }).activated` is `true` and `isVerifierRevoked(issuerPubkey, revocations)` is `false`.
+3. Call `computeBadge(pubkey, events, { verifySignatures: true, isTrustedIssuer: (pk) => accepted.has(pk) })`, where `accepted` holds the issuers that passed step 2.
+
+Voucher activation is recursive (a voucher is active only if its own vouchers are), so `checkCrossVerification` takes it as the `isActiveVerifier` predicate rather than resolving the chain. Start from verifiers your client already accepts. Without `isActiveVerifier` and `revocations`, a voucher only needs a verifier credential with a `profession` tag.
+
 ### Policies (kind 30078, NIP-78)
 - `createPolicy(operatorPrivateKey, params)`: community verification requirements. `params: { communityId: string; adultMinTier: SignetTier; childMinTier: SignetTier; enforcement: 'client' | 'relay' | 'both'; minScore?: number; modMinTier?: SignetTier; verifierBond?: number; revocationThreshold?: number; description?: string }`. The d-tag is `signet:policy:<communityId>`.
 - `new PolicyChecker(policyEvent: NostrEvent)`: throws `SignetValidationError('Invalid policy event')` if the event is not a valid policy. Methods: `getPolicy(): ParsedPolicy`, `checkAdult(tier, score)`, `checkChild(tier, score)`, `checkModerator(tier, score)`. Each check returns `PolicyCheckResult`: `{ allowed: boolean; reason?: string; requiredTier: SignetTier; actualTier: SignetTier; requiredScore?: number; actualScore?: number }`.
@@ -80,20 +96,20 @@ Default credential expiry is two years (`DEFAULT_CREDENTIAL_EXPIRY_SECONDS`) whe
 
 ### Verifiers (kind 31000, type: verifier)
 - `createVerifierCredential(privateKey, params)`: register as professional verifier. `params: { profession: string; jurisdiction: string; licenceHash: string; professionalBody: string; statement?: string; bondProof?: BondProof }`.
-- `checkCrossVerification(verifierPubkey, vouches, verifierCredentials)`: activation check. Returns `{ activated: boolean; vouchCount: number; professions: string[]; errors: string[] }`.
-- `isVerifierRevoked(verifierPubkey, revocations)`: `boolean`
+- `checkCrossVerification(verifierPubkey: string, vouches: NostrEvent[], verifierCredentials: NostrEvent[], options?: { revocations?: NostrEvent[]; isActiveVerifier?: (voucherPubkey: string) => boolean })`: activation check. `vouches` is kind 31000 vouch events (`NostrEvent[]`) and `verifierCredentials` is kind 31000 `type: verifier` events (`NostrEvent[]`), not parsed objects. Returns `{ activated: boolean; vouchCount: number; professions: string[]; errors: string[] }`. `activated` is `true` when at least `VERIFIER_ACTIVATION.MIN_VOUCHES` vouches for `verifierPubkey` come from distinct vouchers that each appear in `verifierCredentials` with a `profession` tag, and those vouchers cover at least `VERIFIER_ACTIVATION.MIN_PROFESSIONS` different professions. It does not verify signatures. The spec also requires each voucher to be an active, non-revoked verifier: pass `options.revocations` to skip any voucher `isVerifierRevoked` reports as revoked, and `options.isActiveVerifier` to skip vouchers your client does not treat as activated. Without these options neither is checked.
+- `isVerifierRevoked(verifierPubkey: string, revocations: NostrEvent[])`: `boolean`. `true` when any kind 31000 `type: revocation` event in `revocations` targets `verifierPubkey`. It does not verify signatures or check who signed the revocation.
 
 ### Challenges and Revocations (kind 31000, type: challenge / revocation)
 - `createChallenge(reporterPrivateKey, params)`: `Promise<NostrEvent>`. `params: { verifierPubkey: string; reason: 'anomalous-volume' | 'registry-mismatch' | 'fraudulent-attestation' | 'licence-revoked' | 'other'; evidenceType: string; reporterTier: SignetTier; evidence: string; occurredAt?: number }`. `evidence` becomes the event content.
 - `createRevocation(authorityPrivateKey, params)`: `Promise<NostrEvent>`. `params: { verifierPubkey: string; challengeEventId: string; confirmations: number; bondAction: 'slashed' | 'returned' | 'held'; scope: 'full' | 'partial'; effectiveAt: number; summary: string }`.
-- `countChallengeConfirmations(challengeEventId, confirmationEvents, credentialEvents)`: `number`
+- `countChallengeConfirmations(challengeEventId: string, confirmationEvents: NostrEvent[], credentialEvents: NostrEvent[])`: `number`. All arrays are raw `NostrEvent[]`. Counts distinct confirmation signers whose `challenge` tag equals `challengeEventId` and who hold a credential event with a `tier` tag of 3 or higher in `credentialEvents`. It does not verify signatures or the issuers of those credentials.
 - `hasReachedRevocationThreshold(confirmations, threshold = 5)`: `boolean`
 - `parseChallenge(event)` / `parseRevocation(event)`: parsed object or `null`.
 
 ### Identity Bridge (kind 31000, type: identity-bridge)
-- `createIdentityBridge(anonPrivateKey, realPrivateKey, ring, signerIndex, ringMinTier, opts?)`: link anonymous account to verified identity via ring signature. `ring: string[]` of pubkeys (at least 5, `MIN_BRIDGE_RING_SIZE`); `opts: { occurredAt?: number }`. Signed by the anonymous key.
-- `selectDecoyRing(verifiedPubkeys, realPubkey, ringSize = 5)`: `{ ring: string[]; signerIndex: number }`
-- `verifyIdentityBridge(event, opts?)`: `Promise<boolean>`. `opts: { maxAgeSeconds?: number }` (default 24 hours; `0` disables the freshness check).
+- `createIdentityBridge(anonPrivateKey: string, realPrivateKey: string, ring: string[], signerIndex: number, ringMinTier: SignetTier, opts?)`: `Promise<NostrEvent>`. Links an anonymous account to a verified identity via ring signature. `ring: string[]` is the anonymity set of verified pubkeys (at least 5, `MIN_BRIDGE_RING_SIZE`) and must contain the public key of `realPrivateKey`. `signerIndex` is the zero-based position in `ring` of that real public key (`selectDecoyRing` returns it for you); a wrong index makes ring signing throw (`Private key does not match ring member at signerIndex`). `ringMinTier` is the lowest verification tier among the ring members, which you assert yourself: it is written to the event's `ring-min-tier` tag and scales the bridge's contribution to `computeTrustScore` (`TRUST_WEIGHTS.IDENTITY_BRIDGE` of 50 × `ringMinTier` ÷ 4). Neither `createIdentityBridge` nor `verifyIdentityBridge` checks that the ring members hold that tier. `opts: { occurredAt?: number }`. Signed by the anonymous key.
+- `selectDecoyRing(verifiedPubkeys: string[], realPubkey: string, ringSize = 5)`: `{ ring: string[]; signerIndex: number }`. Picks decoys from `verifiedPubkeys` (`realPubkey` is filtered out of the pool if present) and places `realPubkey` at a random position. Throws if the pool has fewer than `ringSize - 1` other pubkeys.
+- `verifyIdentityBridge(event: NostrEvent, opts?)`: `Promise<boolean>`. `opts: { maxAgeSeconds?: number }` (default 24 hours; `0` disables the freshness check).
 
 ### ZKP Age Proofs
 - `createAgeRangeProof(age: number, ageRange: string, subjectPubkey?: string)`: `RangeProof` (synchronous). `subjectPubkey` binds the proof to one credential.
@@ -124,6 +140,8 @@ The voting extension (kinds 30482–30484) is specified in `spec/voting.md` and
 
 ## Optional
 
+These paths ship in the npm package (`spec/`, `examples/`, and the `docs/` pages named below and in the experimental section above), so the relative links resolve inside `node_modules/signet-protocol/`. The examples import from the package's own `src/` directory; in your own code import from `signet-protocol`.
+
 - [llms-full.txt](llms-full.txt): llms.txt plus the full protocol and voting specifications and the developer guides in one file
 - [Full protocol specification](spec/protocol.md)
 - [Voting extension specification](spec/voting.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signet-protocol",
-  "version": "1.11.1",
+  "version": "1.11.3",
   "description": "Decentralised identity verification protocol for Nostr",
   "homepage": "https://github.com/forgesworn/signet#readme",
   "type": "module",
@@ -19,6 +19,12 @@
   "files": [
     "dist",
     "src",
+    "spec",
+    "examples",
+    "docs/signet-in-5-minutes.md",
+    "docs/implementation-levels.md",
+    "docs/private-vault-v1.md",
+    "docs/bot-ownership-v1.md",
     "llms.txt",
     "llms-full.txt"
   ],