signet-protocol 0.1.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "signet-protocol",
+  "version": "0.1.0",
+  "description": "Decentralised identity verification protocol for Nostr",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "nostr",
+    "identity",
+    "verification",
+    "zkp",
+    "signet",
+    "web-of-trust",
+    "age-verification",
+    "zero-knowledge-proofs",
+    "child-safety",
+    "privacy",
+    "decentralised-identity",
+    "ring-signatures",
+    "pedersen-range-proofs",
+    "secp256k1"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forgesworn/signet-protocol.git"
+  },
+  "dependencies": {
+    "@forgesworn/range-proof": "^2.0.0",
+    "@forgesworn/ring-sig": "^3.0.0",
+    "@forgesworn/shamir-words": "^1.0.0",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "@scure/bip39": "^2.0.1",
+    "jurisdiction-kit": "^1.0.0",
+    "nostr-attestations": "^2.3.1",
+    "nsec-tree": "^1.4.1",
+    "spoken-token": "^2.0.3"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^25.3.3",
+    "semantic-release": "^25.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "funding": {
+    "type": "lightning",
+    "url": "lightning:thedonkey@strike.me"
+  }
+}

package/src/anomaly.ts

@@ -0,0 +1,307 @@
+// Verifier Anomaly Detection
+// Statistical analysis of verifier issuance patterns
+// Layer 3 of the anti-corruption framework
+
+import { ATTESTATION_KIND, ATTESTATION_TYPES } from './constants.js';
+import { getTagValue } from './validation.js';
+import type { NostrEvent } from './types.js';
+
+/** Types of anomaly flags */
+export type AnomalyType = 'volume' | 'temporal' | 'geographic' | 'pattern';
+
+/** A detected anomaly */
+export interface AnomalyFlag {
+  type: AnomalyType;
+  verifierPubkey: string;
+  severity: 'low' | 'medium' | 'high';
+  description: string;
+  evidence: {
+    metric: string;
+    value: number;
+    threshold: number;
+  };
+}
+
+/** Anomaly detection configuration */
+export interface AnomalyConfig {
+  /** Max credentials per week before flagging (default: 20) */
+  maxWeeklyVolume: number;
+  /** Max credentials per hour before flagging (default: 5) */
+  maxHourlyVolume: number;
+  /** Max percentage of credentials in a single foreign jurisdiction (default: 30) */
+  maxForeignJurisdictionPercent: number;
+  /** Min time between consecutive credentials in seconds (default: 300 = 5 min) */
+  minTimeBetweenCredentials: number;
+  /** Volume multiplier vs network average to flag (default: 5) */
+  volumeMultiplierThreshold: number;
+}
+
+const DEFAULT_CONFIG: AnomalyConfig = {
+  maxWeeklyVolume: 20,
+  maxHourlyVolume: 5,
+  maxForeignJurisdictionPercent: 30,
+  minTimeBetweenCredentials: 300,
+  volumeMultiplierThreshold: 5,
+};
+
+/**
+ * Analyze a verifier's issuance patterns for anomalies.
+ *
+ * @param verifierPubkey - The verifier to analyze
+ * @param allCredentials - All credential events (kind 31000, type: credential) in the store
+ * @param verifierCredential - The verifier's own credential (kind 31000, type: verifier)
+ * @param config - Detection thresholds
+ */
+export function detectAnomalies(
+  verifierPubkey: string,
+  allCredentials: NostrEvent[],
+  verifierCredential?: NostrEvent,
+  config: Partial<AnomalyConfig> = {}
+): AnomalyFlag[] {
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+  const flags: AnomalyFlag[] = [];
+
+  // Get this verifier's issued credentials
+  const issued = allCredentials.filter(
+    (e) => e.kind === ATTESTATION_KIND && getTagValue(e, 'type') === ATTESTATION_TYPES.CREDENTIAL && e.pubkey === verifierPubkey
+  );
+
+  if (issued.length === 0) return flags;
+
+  // Sort by time
+  const sorted = [...issued].sort((a, b) => a.created_at - b.created_at);
+
+  // --- Volume Analysis ---
+  flags.push(...analyzeVolume(verifierPubkey, sorted, allCredentials, cfg));
+
+  // --- Temporal Analysis ---
+  flags.push(...analyzeTemporal(verifierPubkey, sorted, cfg));
+
+  // --- Geographic Analysis ---
+  if (verifierCredential) {
+    flags.push(...analyzeGeographic(verifierPubkey, sorted, verifierCredential, cfg));
+  }
+
+  // --- Pattern Analysis ---
+  flags.push(...analyzePatterns(verifierPubkey, sorted));
+
+  return flags;
+}
+
+/** Volume anomaly detection */
+function analyzeVolume(
+  verifierPubkey: string,
+  issued: NostrEvent[],
+  allCredentials: NostrEvent[],
+  cfg: AnomalyConfig
+): AnomalyFlag[] {
+  const flags: AnomalyFlag[] = [];
+  const now = Math.floor(Date.now() / 1000);
+  const oneWeek = 7 * 24 * 60 * 60;
+  const oneHour = 60 * 60;
+
+  // Weekly volume
+  const weeklyCount = issued.filter((e) => e.created_at > now - oneWeek).length;
+  if (weeklyCount > cfg.maxWeeklyVolume) {
+    flags.push({
+      type: 'volume',
+      verifierPubkey,
+      severity: weeklyCount > cfg.maxWeeklyVolume * 3 ? 'high' : 'medium',
+      description: `Issued ${weeklyCount} credentials this week (threshold: ${cfg.maxWeeklyVolume})`,
+      evidence: { metric: 'weekly_volume', value: weeklyCount, threshold: cfg.maxWeeklyVolume },
+    });
+  }
+
+  // Hourly volume (burst detection)
+  const hourlyCount = issued.filter((e) => e.created_at > now - oneHour).length;
+  if (hourlyCount > cfg.maxHourlyVolume) {
+    flags.push({
+      type: 'volume',
+      verifierPubkey,
+      severity: 'high',
+      description: `Issued ${hourlyCount} credentials in the last hour (threshold: ${cfg.maxHourlyVolume})`,
+      evidence: { metric: 'hourly_volume', value: hourlyCount, threshold: cfg.maxHourlyVolume },
+    });
+  }
+
+  // Compare to network average
+  const allVerifiers = new Set(
+    allCredentials.filter((e) => e.kind === ATTESTATION_KIND && getTagValue(e, 'type') === ATTESTATION_TYPES.CREDENTIAL).map((e) => e.pubkey)
+  );
+  if (allVerifiers.size > 1) {
+    const totalCredentials = allCredentials.filter(
+      (e) => e.kind === ATTESTATION_KIND && getTagValue(e, 'type') === ATTESTATION_TYPES.CREDENTIAL && e.created_at > now - oneWeek
+    ).length;
+    const networkAvg = totalCredentials / allVerifiers.size;
+
+    if (networkAvg > 0 && weeklyCount > networkAvg * cfg.volumeMultiplierThreshold) {
+      flags.push({
+        type: 'volume',
+        verifierPubkey,
+        severity: 'high',
+        description: `Weekly volume ${weeklyCount} is ${(weeklyCount / networkAvg).toFixed(1)}x the network average of ${networkAvg.toFixed(1)}`,
+        evidence: {
+          metric: 'volume_vs_average',
+          value: weeklyCount / networkAvg,
+          threshold: cfg.volumeMultiplierThreshold,
+        },
+      });
+    }
+  }
+
+  return flags;
+}
+
+/** Temporal anomaly detection */
+function analyzeTemporal(
+  verifierPubkey: string,
+  sorted: NostrEvent[],
+  cfg: AnomalyConfig
+): AnomalyFlag[] {
+  const flags: AnomalyFlag[] = [];
+
+  if (sorted.length < 2) return flags;
+
+  // Check minimum time between consecutive credentials
+  let rapidCount = 0;
+  let minGap = Infinity;
+
+  for (let i = 1; i < sorted.length; i++) {
+    const gap = sorted[i].created_at - sorted[i - 1].created_at;
+    if (gap < cfg.minTimeBetweenCredentials) {
+      rapidCount++;
+    }
+    if (gap < minGap) minGap = gap;
+  }
+
+  if (rapidCount > 0) {
+    flags.push({
+      type: 'temporal',
+      verifierPubkey,
+      severity: rapidCount > 5 ? 'high' : 'medium',
+      description: `${rapidCount} credential pairs issued less than ${cfg.minTimeBetweenCredentials}s apart (min gap: ${minGap}s). Suggests rubber-stamping, not in-person verification.`,
+      evidence: { metric: 'rapid_issuance_count', value: rapidCount, threshold: 0 },
+    });
+  }
+
+  return flags;
+}
+
+/** Geographic anomaly detection */
+function analyzeGeographic(
+  verifierPubkey: string,
+  issued: NostrEvent[],
+  verifierCredential: NostrEvent,
+  cfg: AnomalyConfig
+): AnomalyFlag[] {
+  const flags: AnomalyFlag[] = [];
+
+  const verifierJurisdiction = getTagValue(verifierCredential, 'jurisdiction');
+  if (!verifierJurisdiction) return flags;
+
+  // Count jurisdictions in issued credentials
+  const jurisdictionCounts = new Map<string, number>();
+  for (const cred of issued) {
+    const j = getTagValue(cred, 'jurisdiction') || 'unknown';
+    jurisdictionCounts.set(j, (jurisdictionCounts.get(j) || 0) + 1);
+  }
+
+  // Check for high foreign jurisdiction percentage
+  for (const [jurisdiction, count] of jurisdictionCounts) {
+    if (jurisdiction === verifierJurisdiction) continue;
+
+    const percent = (count / issued.length) * 100;
+    if (percent > cfg.maxForeignJurisdictionPercent) {
+      flags.push({
+        type: 'geographic',
+        verifierPubkey,
+        severity: percent > 60 ? 'high' : 'medium',
+        description: `${percent.toFixed(0)}% of credentials (${count}/${issued.length}) issued in ${jurisdiction}, but verifier is registered in ${verifierJurisdiction}`,
+        evidence: {
+          metric: 'foreign_jurisdiction_percent',
+          value: percent,
+          threshold: cfg.maxForeignJurisdictionPercent,
+        },
+      });
+    }
+  }
+
+  return flags;
+}
+
+/** Pattern anomaly detection */
+function analyzePatterns(
+  verifierPubkey: string,
+  sorted: NostrEvent[]
+): AnomalyFlag[] {
+  const flags: AnomalyFlag[] = [];
+
+  if (sorted.length < 5) return flags;
+
+  // Check for repeated subjects (same person verified multiple times)
+  const subjectCounts = new Map<string, number>();
+  for (const cred of sorted) {
+    const subject = getTagValue(cred, 'd') || '';
+    subjectCounts.set(subject, (subjectCounts.get(subject) || 0) + 1);
+  }
+
+  const duplicates = Array.from(subjectCounts.entries()).filter(([, count]) => count > 1);
+  if (duplicates.length > 0) {
+    const totalDupes = duplicates.reduce((sum, [, count]) => sum + count - 1, 0);
+    flags.push({
+      type: 'pattern',
+      verifierPubkey,
+      severity: 'low',
+      description: `${duplicates.length} subjects verified multiple times (${totalDupes} extra verifications)`,
+      evidence: { metric: 'duplicate_subjects', value: duplicates.length, threshold: 0 },
+    });
+  }
+
+  // Check for disproportionate tier 4 issuance
+  let tier4Count = 0;
+  for (const cred of sorted) {
+    if (getTagValue(cred, 'tier') === '4') tier4Count++;
+  }
+
+  const tier4Percent = (tier4Count / sorted.length) * 100;
+  if (tier4Count > 3 && tier4Percent > 80) {
+    flags.push({
+      type: 'pattern',
+      verifierPubkey,
+      severity: 'medium',
+      description: `${tier4Percent.toFixed(0)}% of credentials are Tier 4 (${tier4Count}/${sorted.length}). Unusually high child verification rate.`,
+      evidence: { metric: 'tier4_percent', value: tier4Percent, threshold: 80 },
+    });
+  }
+
+  return flags;
+}
+
+/**
+ * Get a summary of all flagged verifiers from a set of credentials.
+ */
+export function scanForAnomalies(
+  allCredentials: NostrEvent[],
+  verifierCredentials: NostrEvent[],
+  config?: Partial<AnomalyConfig>
+): Map<string, AnomalyFlag[]> {
+  const results = new Map<string, AnomalyFlag[]>();
+
+  // Get unique verifier pubkeys from credentials
+  const verifiers = new Set(
+    allCredentials
+      .filter((e) => e.kind === ATTESTATION_KIND && getTagValue(e, 'type') === ATTESTATION_TYPES.CREDENTIAL)
+      .map((e) => e.pubkey)
+  );
+
+  for (const pubkey of verifiers) {
+    const verifierCred = verifierCredentials.find((c) => c.pubkey === pubkey);
+    const flags = detectAnomalies(pubkey, allCredentials, verifierCred, config);
+
+    if (flags.length > 0) {
+      results.set(pubkey, flags);
+    }
+  }
+
+  return results;
+}

package/src/badge.ts

@@ -0,0 +1,208 @@
+// Level 1 Badge Display Library
+// Minimal drop-in module for Nostr clients to display Signet trust badges.
+// Requires only kind 31000 (type: credential and type: vouch) and Schnorr verification.
+
+import { ATTESTATION_KIND, ATTESTATION_TYPES, TRUST_WEIGHTS, MAX_TRUST_SCORE } from './constants.js';
+import { verifyEvent } from './crypto.js';
+import { getTagValue } from './validation.js';
+import type { NostrEvent, SignetTier } from './types.js';
+
+// --- Types ---
+
+export interface BadgeInfo {
+  /** The pubkey this badge describes */
+  pubkey: string;
+  /** Highest verification tier (1-4) */
+  tier: SignetTier;
+  /** Human-readable tier label */
+  tierLabel: string;
+  /** Signet Score (0-200) */
+  score: number;
+  /** Whether the user has any valid credentials */
+  isVerified: boolean;
+  /** Short display string, e.g. "Verified (Tier 3)" */
+  displayLabel: string;
+  /** Number of valid credentials */
+  credentialCount: number;
+  /** Number of valid vouches */
+  vouchCount: number;
+}
+
+export type TrustLevel = 'unverified' | 'self-declared' | 'vouched' | 'professional' | 'professional-child';
+
+const TIER_LABELS: Record<SignetTier, string> = {
+  1: 'Self-declared',
+  2: 'Web-of-trust',
+  3: 'Verified',
+  4: 'Verified (Child Safety)',
+};
+
+const TIER_TO_TRUST_LEVEL: Record<SignetTier, TrustLevel> = {
+  1: 'self-declared',
+  2: 'vouched',
+  3: 'professional',
+  4: 'professional-child',
+};
+
+// --- Core Functions ---
+
+/**
+ * Compute badge info for a pubkey from their credentials and vouches.
+ * This is the main entry point for Level 1 integration.
+ *
+ * @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
+ * @returns Badge info for display
+ */
+export async function computeBadge(
+  pubkey: string,
+  events: NostrEvent[],
+  options?: { verifySignatures?: boolean; now?: number }
+): Promise<BadgeInfo> {
+  const now = options?.now ?? Math.floor(Date.now() / 1000);
+  const verify = options?.verifySignatures ?? false;
+
+  let highestTier: SignetTier = 1;
+  let rawScore = 0;
+  let credentialCount = 0;
+  let hasAnyCredential = false;
+
+  // Process credentials
+  for (const event of events) {
+    if (event.kind !== ATTESTATION_KIND) continue;
+    if (getTagValue(event, 'type') !== ATTESTATION_TYPES.CREDENTIAL) continue;
+    const dTag = getTagValue(event, 'd') || '';
+    const pTag = getTagValue(event, 'p');
+    let subject: string;
+    if (dTag.startsWith('assertion:') && pTag) {
+      subject = pTag;
+    } else {
+      subject = dTag.startsWith('credential:') ? dTag.slice('credential:'.length) : dTag;
+    }
+    if (subject !== pubkey) continue;
+
+    // Check expiry — NaN must be treated as expired (not perpetually valid)
+    const expires = getTagValue(event, 'expiration');
+    if (expires) {
+      const exp = parseInt(expires, 10);
+      if (isNaN(exp) || exp < now) continue;
+    }
+
+    // Optional signature verification
+    if (verify && !await verifyEvent(event)) continue;
+
+    hasAnyCredential = true;
+    credentialCount++;
+
+    const rawTier = parseInt(getTagValue(event, 'tier') || '1', 10);
+    const tier = (rawTier >= 1 && rawTier <= 4 ? rawTier : 1) as SignetTier;
+    if (tier > highestTier) highestTier = tier;
+
+    const verificationType = getTagValue(event, 'verification-type');
+    if (verificationType === 'professional') {
+      rawScore += TRUST_WEIGHTS.PROFESSIONAL_VERIFICATION;
+    }
+  }
+
+  // Process vouches
+  const vouchersSeen = new Set<string>();
+  let vouchCount = 0;
+
+  for (const event of events) {
+    if (event.kind !== ATTESTATION_KIND) continue;
+    if (getTagValue(event, 'type') !== ATTESTATION_TYPES.VOUCH) continue;
+    const dTag = getTagValue(event, 'd') || '';
+    const subject = dTag.startsWith('vouch:') ? dTag.slice('vouch:'.length) : dTag;
+    if (subject !== pubkey) continue;
+
+    // One vouch per voucher
+    if (vouchersSeen.has(event.pubkey)) continue;
+    vouchersSeen.add(event.pubkey);
+
+    if (verify && !await verifyEvent(event)) continue;
+
+    vouchCount++;
+
+    const method = getTagValue(event, 'method');
+    const rawVoucherScore = parseInt(getTagValue(event, 'voucher-score') || '50', 10);
+    const voucherScore = isNaN(rawVoucherScore) ? 50 : Math.max(0, Math.min(rawVoucherScore, MAX_TRUST_SCORE));
+    const multiplier = voucherScore / MAX_TRUST_SCORE;
+
+    if (method === 'in-person') {
+      rawScore += TRUST_WEIGHTS.IN_PERSON_VOUCH * multiplier;
+    } else {
+      rawScore += TRUST_WEIGHTS.ONLINE_VOUCH * multiplier;
+    }
+  }
+
+  const score = Math.min(Math.round(rawScore), MAX_TRUST_SCORE);
+  const tierLabel = TIER_LABELS[highestTier];
+
+  let displayLabel: string;
+  if (!hasAnyCredential && vouchCount === 0) {
+    displayLabel = 'Unverified';
+  } else {
+    displayLabel = `${tierLabel} (Tier ${highestTier})`;
+  }
+
+  return {
+    pubkey,
+    tier: highestTier,
+    tierLabel,
+    score,
+    isVerified: hasAnyCredential,
+    displayLabel,
+    credentialCount,
+    vouchCount,
+  };
+}
+
+/**
+ * Get the trust level classification for a badge.
+ */
+export function getTrustLevel(badge: BadgeInfo): TrustLevel {
+  if (!badge.isVerified && badge.vouchCount === 0) return 'unverified';
+  return TIER_TO_TRUST_LEVEL[badge.tier];
+}
+
+/**
+ * Check if a pubkey has at least the required tier.
+ * Useful for gating access to features or communities.
+ */
+export function meetsMinimumTier(badge: BadgeInfo, minTier: SignetTier): boolean {
+  return badge.isVerified && badge.tier >= minTier;
+}
+
+/**
+ * Filter a set of events to only those relevant for a given pubkey.
+ * Useful when you have a mixed bag of events from a relay query.
+ */
+export function filterEventsForPubkey(pubkey: string, events: NostrEvent[]): NostrEvent[] {
+  return events.filter(event => {
+    if (event.kind !== ATTESTATION_KIND) return false;
+    const eventType = getTagValue(event, 'type');
+    if (eventType !== ATTESTATION_TYPES.CREDENTIAL && eventType !== ATTESTATION_TYPES.VOUCH) {
+      return false;
+    }
+    const dTag = getTagValue(event, 'd') || '';
+    // Strip type prefix from d-tag to get subject
+    const subject = dTag.includes(':') ? dTag.slice(dTag.indexOf(':') + 1) : dTag;
+    return subject === pubkey;
+  });
+}
+
+/**
+ * Build a Nostr filter for fetching badge-relevant events for one or more pubkeys.
+ * Returns filters suitable for use with REQ messages.
+ */
+export function buildBadgeFilters(pubkeys: string[]): Array<{ kinds: number[]; '#d': string[] }> {
+  // With the generic attestation kind, d-tags are now prefixed with the type
+  const dTags = pubkeys.flatMap(pk => [`credential:${pk}`, `vouch:${pk}`]);
+  return [
+    {
+      kinds: [ATTESTATION_KIND],
+      '#d': dTags,
+    },
+  ];
+}