signet-protocol 0.1.0

package/src/trust-score.ts

@@ -0,0 +1,208 @@
+// Signet Score Computation
+// Continuous 0-200 Signet Score from weighted signals
+
+import { TRUST_WEIGHTS, MAX_TRUST_SCORE, ATTESTATION_KIND, ATTESTATION_TYPES } from './constants.js';
+import { getTagValue } from './validation.js';
+import type {
+  NostrEvent,
+  TrustSignal,
+  TrustScoreBreakdown,
+  SignetTier,
+} from './types.js';
+
+/** Compute Signet Score for a subject from their credentials, vouches, and bridges */
+export function computeTrustScore(
+  subjectPubkey: string,
+  credentials: NostrEvent[],
+  vouches: NostrEvent[],
+  accountCreatedAt?: number,
+  bridges?: NostrEvent[]
+): TrustScoreBreakdown {
+  const signals: TrustSignal[] = [];
+  let rawScore = 0;
+  let highestTier: SignetTier = 1;
+  let professionalVerifications = 0;
+  let inPersonVouches = 0;
+  let onlineVouches = 0;
+
+  // Process credentials
+  const now = Math.floor(Date.now() / 1000);
+  for (const cred of credentials) {
+    if (cred.kind !== ATTESTATION_KIND) continue;
+    if (getTagValue(cred, 'type') !== ATTESTATION_TYPES.CREDENTIAL) continue;
+    const dTag = getTagValue(cred, 'd') || '';
+    const pTag = getTagValue(cred, 'p');
+    let subject: string;
+    if (dTag.startsWith('assertion:') && pTag) {
+      subject = pTag;
+    } else {
+      subject = dTag.startsWith('credential:') ? dTag.slice('credential:'.length) : dTag;
+    }
+    if (subject !== subjectPubkey) continue;
+
+    // Skip expired credentials — NaN must be treated as expired (not perpetually valid)
+    const expires = getTagValue(cred, 'expiration');
+    if (expires) {
+      const exp = parseInt(expires, 10);
+      if (isNaN(exp) || exp < now) continue;
+    }
+
+    const rawTier = parseInt(getTagValue(cred, 'tier') || '1', 10);
+    const tier = (!isNaN(rawTier) && rawTier >= 1 && rawTier <= 4 ? rawTier : 1) as SignetTier;
+    if (tier > highestTier) highestTier = tier;
+
+    const verificationType = getTagValue(cred, 'verification-type');
+    if (verificationType === 'professional') {
+      professionalVerifications++;
+      const weight = TRUST_WEIGHTS.PROFESSIONAL_VERIFICATION;
+      rawScore += weight;
+      signals.push({
+        type: 'professional-verification',
+        weight,
+        source: cred.pubkey,
+      });
+    }
+  }
+
+  // Process vouches
+  const vouchersSeen = new Set<string>();
+  for (const vouch of vouches) {
+    if (vouch.kind !== ATTESTATION_KIND) continue;
+    if (getTagValue(vouch, 'type') !== ATTESTATION_TYPES.VOUCH) continue;
+    const dTag = getTagValue(vouch, 'd') || '';
+    const subject = dTag.startsWith('vouch:') ? dTag.slice('vouch:'.length) : dTag;
+    if (subject !== subjectPubkey) continue;
+
+    // One vouch per voucher
+    if (vouchersSeen.has(vouch.pubkey)) continue;
+    vouchersSeen.add(vouch.pubkey);
+
+    const method = getTagValue(vouch, 'method');
+    const rawVoucherScore = parseInt(getTagValue(vouch, 'voucher-score') || '50', 10);
+    const voucherScore = isNaN(rawVoucherScore) ? 50 : Math.max(0, Math.min(rawVoucherScore, MAX_TRUST_SCORE));
+    const scoreMultiplier = voucherScore / MAX_TRUST_SCORE;
+
+    if (method === 'in-person') {
+      inPersonVouches++;
+      const weight = TRUST_WEIGHTS.IN_PERSON_VOUCH * scoreMultiplier;
+      rawScore += weight;
+      signals.push({
+        type: 'in-person-vouch',
+        weight,
+        source: vouch.pubkey,
+        score: voucherScore,
+      });
+    } else {
+      onlineVouches++;
+      const weight = TRUST_WEIGHTS.ONLINE_VOUCH * scoreMultiplier;
+      rawScore += weight;
+      signals.push({
+        type: 'online-vouch',
+        weight,
+        source: vouch.pubkey,
+        score: voucherScore,
+      });
+    }
+  }
+
+  // Process identity bridges
+  if (bridges) {
+    for (const bridge of bridges) {
+      if (bridge.kind !== ATTESTATION_KIND) continue;
+      if (getTagValue(bridge, 'type') !== ATTESTATION_TYPES.IDENTITY_BRIDGE) continue;
+      if (bridge.pubkey !== subjectPubkey) continue;
+
+      const rawRingMinTier = parseInt(getTagValue(bridge, 'ring-min-tier') || '1', 10);
+      const ringMinTier = (!isNaN(rawRingMinTier) && rawRingMinTier >= 1 && rawRingMinTier <= 4 ? rawRingMinTier : 1) as SignetTier;
+      const weight = TRUST_WEIGHTS.IDENTITY_BRIDGE * (ringMinTier / 4);
+      rawScore += weight;
+      signals.push({
+        type: 'identity-bridge',
+        weight,
+        source: bridge.pubkey,
+      });
+      // Only count one bridge per account
+      break;
+    }
+  }
+
+  // Account age
+  let accountAgeDays = 0;
+  if (accountCreatedAt) {
+    accountAgeDays = Math.max(0, Math.floor((now - accountCreatedAt) / (24 * 60 * 60)));
+    const years = accountAgeDays / 365;
+    const ageWeight = Math.min(
+      years * TRUST_WEIGHTS.ACCOUNT_AGE_PER_YEAR,
+      TRUST_WEIGHTS.ACCOUNT_AGE_MAX
+    );
+    rawScore += ageWeight;
+    signals.push({
+      type: 'account-age',
+      weight: ageWeight,
+    });
+  }
+
+  // Cap at MAX_TRUST_SCORE
+  const score = Math.min(Math.round(rawScore), MAX_TRUST_SCORE);
+
+  return {
+    score,
+    tier: highestTier,
+    professionalVerifications,
+    inPersonVouches,
+    onlineVouches,
+    accountAgeDays,
+    signals,
+  };
+}
+
+/** Get a human-readable Signet Score display */
+export function formatTrustDisplay(breakdown: TrustScoreBreakdown): string {
+  const checkmarks = breakdown.tier >= 2 ? '✓'.repeat(breakdown.tier - 1) : '';
+  const tierLabel = ['', 'Self-declared', 'Web-of-trust', 'Verified', 'Verified (Child Safety)'][breakdown.tier];
+
+  const lines = [
+    `${checkmarks} Tier ${breakdown.tier} (${tierLabel})`,
+    `Signet Score: ${breakdown.score}`,
+  ];
+
+  if (breakdown.professionalVerifications > 0) {
+    lines.push(`  Prof verified: ${breakdown.professionalVerifications}`);
+  }
+  if (breakdown.inPersonVouches > 0) {
+    lines.push(`  In-person vouches: ${breakdown.inPersonVouches}`);
+  }
+  if (breakdown.onlineVouches > 0) {
+    lines.push(`  Online vouches: ${breakdown.onlineVouches}`);
+  }
+  if (breakdown.accountAgeDays > 0) {
+    const years = (breakdown.accountAgeDays / 365).toFixed(1);
+    lines.push(`  Account age: ${years} years`);
+  }
+
+  return lines.join('\n');
+}
+
+/** Verify the signal ordering invariant:
+ *  professional verification > identity bridge > in-person vouch > online vouch > account age */
+export function verifySignalOrdering(signals: TrustSignal[]): boolean {
+  const maxWeight = (type: TrustSignal['type']): number => {
+    const weights = signals.filter((s) => s.type === type).map((s) => s.weight);
+    return weights.length > 0 ? Math.max(...weights) : 0;
+  };
+
+  const profMax = maxWeight('professional-verification');
+  const bridgeMax = maxWeight('identity-bridge');
+  const inPersonMax = maxWeight('in-person-vouch');
+
+  // Professional verification must exceed identity bridge
+  if (profMax > 0 && bridgeMax > 0 && profMax <= bridgeMax) return false;
+
+  // Identity bridge must exceed in-person vouch
+  if (bridgeMax > 0 && inPersonMax > 0 && bridgeMax <= inPersonMax) return false;
+
+  // Professional verification must exceed in-person vouch
+  if (profMax > 0 && inPersonMax > 0 && profMax <= inPersonMax) return false;
+
+  return true;
+}

package/src/types.ts

@@ -0,0 +1,482 @@
+// Signet Protocol Types
+// All TypeScript interfaces for the 11 Nostr event kinds (8 core + 3 voting extension) and supporting structures
+
+/** Asymmetric cryptographic algorithm for event signing and key agreement.
+ * 'secp256k1' is the current Nostr standard. Additional algorithms
+ * (e.g. post-quantum lattice-based schemes) may be added in future versions. */
+export type CryptoAlgorithm = 'secp256k1' | (string & {});
+
+/** Verification tier levels */
+export type SignetTier = 1 | 2 | 3 | 4;
+
+/** How the verification was performed */
+export type VerificationType = 'self' | 'peer' | 'professional';
+
+/** Scope of verification */
+export type VerificationScope = 'adult' | 'adult+child';
+
+/** Method of verification */
+export type VerificationMethod =
+  | 'self-declaration'
+  | 'in-person'
+  | 'online'
+  | 'in-person-id';
+
+/** Vouch method */
+export type VouchMethod = 'in-person' | 'online';
+
+/** Policy enforcement level */
+export type EnforcementLevel = 'client' | 'relay' | 'both';
+
+/** Challenge reasons */
+export type ChallengeReason =
+  | 'anomalous-volume'
+  | 'registry-mismatch'
+  | 'fraudulent-attestation'
+  | 'licence-revoked'
+  | 'other';
+
+/** Bond action on revocation */
+export type BondAction = 'slashed' | 'returned' | 'held';
+
+/** Revocation scope */
+export type RevocationScope = 'full' | 'partial';
+
+// --- Base Nostr Event ---
+
+export interface UnsignedEvent {
+  kind: number;
+  pubkey: string;
+  created_at: number;
+  tags: string[][];
+  content: string;
+}
+
+export interface NostrEvent extends UnsignedEvent {
+  id: string;
+  sig: string;
+}
+
+// --- Verification Credential (type: credential) ---
+
+export interface CredentialParams {
+  subjectPubkey: string;
+  tier: SignetTier;
+  type: VerificationType;
+  scope: VerificationScope;
+  method: VerificationMethod;
+  expiresAt: number;
+  profession?: string;
+  jurisdiction?: string;
+  ageRange?: string; // e.g. "8-12", "18+"
+  content?: string;  // ZKP proof blob
+  entityType?: EntityType;
+  nullifier?: string;
+  merkleRoot?: string;
+  guardianPubkeys?: string[];
+  supersedes?: string; // event ID of superseded credential
+  occurredAt?: number; // unix timestamp for when verification occurred (distinct from publication time)
+  assertionEventId?: string; // Tier 1 self-declaration event ID (REQUIRED for Tier 2-4, assertion-first pattern)
+  assertionRelay?: string; // relay hint for the assertion event
+}
+
+// --- Vouch Attestation (type: vouch) ---
+
+export interface VouchParams {
+  subjectPubkey: string;
+  method: VouchMethod;
+  context?: string;
+  voucherTier: SignetTier;
+  voucherScore: number;
+  occurredAt?: number;
+}
+
+// --- Community Verification Policy (NIP-78) ---
+
+export interface PolicyParams {
+  communityId: string;
+  adultMinTier: SignetTier;
+  childMinTier: SignetTier;
+  enforcement: EnforcementLevel;
+  minScore?: number;
+  modMinTier?: SignetTier;
+  verifierBond?: number;
+  revocationThreshold?: number;
+  description?: string;
+}
+
+export interface PolicyCheckResult {
+  allowed: boolean;
+  reason?: string;
+  requiredTier: SignetTier;
+  actualTier: SignetTier;
+  requiredScore?: number;
+  actualScore?: number;
+}
+
+// --- Proof-of-Reserve Bond ---
+
+/** Bitcoin address type for bond proofs */
+export type BitcoinAddressType = 'p2wpkh' | 'p2sh' | 'p2tr' | 'p2pkh';
+
+/** A proof-of-reserve bond attestation */
+export interface BondProof {
+  address: string;
+  addressType: BitcoinAddressType;
+  amountSats: number;
+  timestamp: number;
+  message: string;
+  signature: string;
+}
+
+export type BondStatus = 'valid' | 'stale' | 'invalid' | 'unverified';
+
+export interface BondVerificationResult {
+  status: BondStatus;
+  signatureValid: boolean | null;
+  fresh: boolean;
+  ageSecs: number;
+  meetsThreshold: boolean | null;
+  errors: string[];
+}
+
+export type BIP322Verifier = (
+  address: string,
+  message: string,
+  signature: string,
+) => boolean | Promise<boolean>;
+
+// --- Verifier Credential (type: verifier) ---
+
+export interface VerifierParams {
+  profession: string;
+  jurisdiction: string;
+  licenceHash: string;
+  professionalBody: string;
+  statement?: string;
+  bondProof?: BondProof;
+}
+
+// --- Verifier Challenge (type: challenge) ---
+
+export interface ChallengeParams {
+  verifierPubkey: string;
+  reason: ChallengeReason;
+  evidenceType: string;
+  reporterTier: SignetTier;
+  evidence: string;
+  occurredAt?: number;
+}
+
+// --- Verifier Revocation (type: revocation) ---
+
+export interface RevocationParams {
+  verifierPubkey: string;
+  challengeEventId: string;
+  confirmations: number;
+  bondAction: BondAction;
+  scope: RevocationScope;
+  effectiveAt: number;
+  summary: string;
+}
+
+// --- Signet Score ---
+
+export interface TrustSignal {
+  type: 'professional-verification' | 'in-person-vouch' | 'online-vouch' | 'account-age' | 'identity-bridge';
+  weight: number;
+  source?: string; // pubkey of signal source
+  score?: number;  // source's own score (for vouch multiplier)
+}
+
+export interface TrustScoreBreakdown {
+  score: number; // 0-200 (Signet Score)
+  tier: SignetTier;
+  professionalVerifications: number;
+  inPersonVouches: number;
+  onlineVouches: number;
+  accountAgeDays: number;
+  signals: TrustSignal[];
+}
+
+// --- Merkle Selective Disclosure ---
+
+export interface MerkleProof {
+  leaf: string;
+  index: number;
+  siblings: string[];
+  root: string;
+}
+
+export interface SelectiveDisclosure {
+  revealedAttributes: Record<string, string>;
+  proofs: MerkleProof[];
+  merkleRoot: string;
+}
+
+// --- Parsed event helpers ---
+
+export interface ParsedCredential {
+  subjectPubkey: string;
+  tier: SignetTier;
+  type: VerificationType;
+  scope: VerificationScope;
+  method: VerificationMethod;
+  profession?: string;
+  jurisdiction?: string;
+  ageRange?: string;
+  expiresAt?: number;
+  entityType?: EntityType;
+  nullifier?: string;
+  merkleRoot?: string;
+  guardianPubkeys?: string[];
+  supersedes?: string;
+  supersededBy?: string;
+  occurredAt?: number;
+  algorithm: CryptoAlgorithm;
+}
+
+export interface ParsedVouch {
+  subjectPubkey: string;
+  method: VouchMethod;
+  context?: string;
+  voucherTier: SignetTier;
+  voucherScore: number;
+  algorithm: CryptoAlgorithm;
+}
+
+export interface ParsedPolicy {
+  communityId: string;
+  adultMinTier: SignetTier;
+  childMinTier: SignetTier;
+  enforcement: EnforcementLevel;
+  minScore?: number;
+  modMinTier?: SignetTier;
+  verifierBond?: number;
+  revocationThreshold?: number;
+  algorithm: CryptoAlgorithm;
+}
+
+export interface ParsedVerifier {
+  profession: string;
+  jurisdiction: string;
+  licenceHash: string;
+  professionalBody: string;
+  algorithm: CryptoAlgorithm;
+  bondProof?: BondProof;
+}
+
+export interface ParsedChallenge {
+  verifierPubkey: string;
+  reason: ChallengeReason;
+  evidenceType: string;
+  reporterTier: SignetTier;
+  algorithm: CryptoAlgorithm;
+}
+
+export interface ParsedRevocation {
+  verifierPubkey: string;
+  challengeEventId: string;
+  confirmations: number;
+  bondAction: BondAction;
+  scope: RevocationScope;
+  effectiveAt: number;
+  algorithm: CryptoAlgorithm;
+}
+
+// --- Entity Type Classification ---
+
+/** Entity type classification (§17 of spec) */
+export type EntityType =
+  | 'natural_person'
+  | 'persona'
+  | 'personal_agent'
+  | 'unlinked_personal_agent'
+  | 'juridical_person'
+  | 'juridical_persona'
+  | 'organised_agent'
+  | 'unlinked_organised_agent'
+  | 'unlinked_agent';
+
+/** Developer-friendly entity type labels */
+export type SimpleEntityType = 'person' | 'persona' | 'organisation' | 'agent';
+
+/** Maps full entity types to simplified labels */
+export const ENTITY_DISPLAY_LABELS: Record<EntityType, SimpleEntityType> = {
+  natural_person: 'person',
+  persona: 'persona',
+  juridical_person: 'organisation',
+  juridical_persona: 'organisation',
+  personal_agent: 'agent',
+  organised_agent: 'agent',
+  unlinked_agent: 'agent',
+  unlinked_personal_agent: 'agent',
+  unlinked_organised_agent: 'agent',
+};
+
+/** Dynamic mode signaling for teleoperated/autonomous entities (§17.9) */
+export type EntityMode =
+  | 'teleoperated'
+  | 'autonomous'
+  | 'assisted';
+
+// --- Agent Delegation ---
+
+export interface ParsedDelegation {
+  agentPubkey: string;
+  entityType: 'personal_agent' | 'unlinked_personal_agent' | 'organised_agent' | 'unlinked_organised_agent';
+  ownerPubkey: string;
+  expiresAt?: number;
+  algorithm: CryptoAlgorithm;
+}
+
+// --- Voting Extension (spec/voting.md) ---
+
+/** Election scale */
+export type ElectionScale = 'organisational' | 'community' | 'national';
+
+/** Re-vote policy */
+export type ReVotePolicy = 'allowed' | 'denied';
+
+/** Kind 30482: Election Definition */
+export interface ElectionParams {
+  electionId: string;
+  title: string;
+  description?: string;
+  options: string[];
+  scale: ElectionScale;
+  eligibleEntityTypes: EntityType[];
+  eligibleMinTier: SignetTier;
+  eligibleCommunity?: string;
+  opens: number;
+  closes: number;
+  reVote: ReVotePolicy;
+  tallyPubkeys: string[];
+  tallyThreshold?: [m: number, n: number];
+  ringSize?: number;
+}
+
+export interface ParsedElection {
+  electionId: string;
+  title: string;
+  description?: string;
+  options: string[];
+  scale: ElectionScale;
+  eligibleEntityTypes: EntityType[];
+  eligibleMinTier: SignetTier;
+  eligibleCommunity?: string;
+  opens: number;
+  closes: number;
+  reVote: ReVotePolicy;
+  tallyPubkeys: string[];
+  tallyThreshold?: [m: number, n: number];
+  ringSize?: number;
+  authorityPubkey: string;
+  algorithm: CryptoAlgorithm;
+}
+
+/** Kind 30483: Ballot */
+export interface BallotParams {
+  electionId: string;
+  electionEventId: string;
+  keyImage: string;
+  ringSig: string;
+  encryptedVote: string;
+}
+
+export interface ParsedBallot {
+  electionId: string;
+  electionEventId: string;
+  keyImage: string;
+  ringSig: string;
+  encryptedVote: string;
+  ephemeralPubkey: string;
+  timestamp: number;
+  algorithm: CryptoAlgorithm;
+}
+
+/** Kind 30484: Election Result */
+export interface ElectionResultParams {
+  electionId: string;
+  electionEventId: string;
+  results: Array<{ option: string; count: number }>;
+  totalBallots: number;
+  totalEligible: number;
+  totalInvalid?: number;
+  tallyProof?: string;
+}
+
+export interface ParsedElectionResult {
+  electionId: string;
+  electionEventId: string;
+  results: Array<{ option: string; count: number }>;
+  totalBallots: number;
+  totalEligible: number;
+  totalInvalid: number;
+  tallyProof?: string;
+  tallierPubkey: string;
+  algorithm: CryptoAlgorithm;
+}
+
+// --- Two-Credential Ceremony ---
+
+export interface TwoCredentialResult {
+  naturalPerson: NostrEvent;
+  persona: NostrEvent;
+  merkleLeaves: Record<string, string>;
+  merkleProofs: MerkleProof[];
+}
+
+export interface CredentialChain {
+  current: NostrEvent;
+  history: NostrEvent[];
+}
+
+// --- Guardian Delegation ---
+
+export interface GuardianDelegationParams {
+  childPubkey: string;
+  delegatePubkey: string;
+  scope: GuardianDelegationScope;
+  expiresAt?: number;
+  occurredAt?: number;
+}
+
+export type GuardianDelegationScope =
+  | 'full'
+  | 'activity-approval'
+  | 'content-management'
+  | 'contact-approval';
+
+// --- Cold-Call Verification ---
+
+/** A single institutional verification pubkey */
+export interface InstitutionPubkey {
+  id: string;
+  pubkey: string;         // 64-char hex, secp256k1 x-only
+  label: string;
+  created: string;        // ISO 8601
+}
+
+/** .well-known/signet.json response */
+export interface InstitutionKeys {
+  version: number;
+  name: string;
+  pubkeys: InstitutionPubkey[];
+  relay?: string;
+  policy?: {
+    rotation?: string;
+    contact?: string;
+  };
+}
+
+// --- Identity Bridge (type: identity-bridge) ---
+
+export interface ParsedIdentityBridge {
+  anonPubkey: string;
+  ringMinTier: SignetTier;
+  ringSize: number;
+  ring: string[];
+  timestamp: number;
+  algorithm: CryptoAlgorithm;
+}

package/src/utils.ts

@@ -0,0 +1,20 @@
+/** Zero out a Uint8Array buffer (best-effort secure wipe). */
+export function zeroBytes(buf: Uint8Array): void {
+  buf.fill(0);
+}
+
+/**
+ * Constant-time comparison of two equal-length Uint8Arrays.
+ * Always compares all bytes; does not short-circuit on content.
+ *
+ * NOTE: The length check IS an early return (not constant-time w.r.t. length),
+ * but all callers compare fixed-size buffers (32-byte scalars), so this is safe.
+ */
+export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}