signet-protocol 0.1.0

package/src/index.ts

@@ -0,0 +1,452 @@
+// Signet Protocol — TypeScript Library
+// Decentralised identity verification for Nostr
+
+// Types
+export type {
+  CryptoAlgorithm,
+  SignetTier,
+  VerificationType,
+  VerificationScope,
+  VerificationMethod,
+  VouchMethod,
+  EnforcementLevel,
+  ChallengeReason,
+  BondAction,
+  RevocationScope,
+  EntityType,
+  EntityMode,
+  UnsignedEvent,
+  NostrEvent,
+  CredentialParams,
+  VouchParams,
+  PolicyParams,
+  PolicyCheckResult,
+  VerifierParams,
+  ChallengeParams,
+  RevocationParams,
+  TrustSignal,
+  TrustScoreBreakdown,
+  MerkleProof,
+  SelectiveDisclosure,
+  ParsedCredential,
+  ParsedVouch,
+  ParsedPolicy,
+  ParsedVerifier,
+  ParsedChallenge,
+  ParsedRevocation,
+  ParsedDelegation,
+  ParsedIdentityBridge,
+  TwoCredentialResult,
+  CredentialChain,
+  GuardianDelegationParams,
+  GuardianDelegationScope,
+  SimpleEntityType,
+  // Bond types
+  BitcoinAddressType,
+  BondProof,
+  BondStatus,
+  BondVerificationResult,
+  BIP322Verifier,
+} from './types.js';
+
+// Entity display labels (value export from types)
+export { ENTITY_DISPLAY_LABELS } from './types.js';
+
+// Constants
+export {
+  ATTESTATION_KIND,
+  APP_DATA_KIND,
+  ATTESTATION_TYPES,
+  SIGNET_KINDS,
+  SIGNET_LABEL,
+  DEFAULT_VOUCH_THRESHOLD,
+  DEFAULT_VOUCHER_MIN_TIER,
+  DEFAULT_CREDENTIAL_EXPIRY_SECONDS,
+  DEFAULT_REVOCATION_THRESHOLD,
+  VERIFIER_ACTIVATION,
+  TRUST_WEIGHTS,
+  MAX_TRUST_SCORE,
+  SIGNAL_PRIORITY,
+  MIN_BRIDGE_RING_SIZE,
+  ENTITY_TYPES,
+  DELEGATION_CONSTRAINTS,
+  ENTITY_LABELS,
+  DEFAULT_CRYPTO_ALGORITHM,
+  // Bond constants
+  BOND_DOMAIN_SEPARATOR,
+  DEFAULT_BOND_MAX_AGE_SECS,
+  VALID_BOND_ADDRESS_TYPES,
+} from './constants.js';
+
+// Crypto
+export {
+  generateKeyPair,
+  getPublicKey,
+  signEvent,
+  verifyEvent,
+  getEventId,
+  hash,
+  hashString,
+} from './crypto.js';
+
+// Credentials (attestation type: credential)
+export {
+  buildCredentialEvent,
+  createSelfDeclaredCredential,
+  createPeerVouchedCredential,
+  createProfessionalCredential,
+  createChildSafetyCredential,
+  verifyCredential,
+  isCredentialExpired,
+  parseCredential,
+  // Ring-signature protected credentials
+  createRingProtectedCredential,
+  createRingProtectedChildCredential,
+  verifyRingProtectedContent,
+  // Credential renewal
+  renewCredential,
+  needsRenewal,
+  // Two-credential ceremony
+  createTwoCredentialCeremony,
+  // Credential chains
+  supersedeCredential,
+  resolveCredentialChain,
+  isSuperseded,
+  // Nullifier utilities
+  computeNullifier,
+  checkNullifierDuplicate,
+  buildNullifierChainTag,
+  // Multi-document nullifier families
+  computeNullifierFamily,
+  buildNullifierFamilyTags,
+  checkNullifierFamilyDuplicate,
+  // Guardian delegation
+  createGuardianDelegation,
+} from './credentials.js';
+
+export type { RingProtectedContent, DocumentDescriptor, NullifierFamily } from './credentials.js';
+
+// Vouches (attestation type: vouch)
+export {
+  buildVouchEvent,
+  createVouch,
+  parseVouch,
+  countQualifyingVouches,
+  hasEnoughVouches,
+  getVouchers,
+} from './vouches.js';
+
+// Policies (NIP-78 kind 30078)
+export {
+  buildPolicyEvent,
+  createPolicy,
+  parsePolicy,
+  checkPolicyCompliance,
+  PolicyChecker,
+} from './policies.js';
+
+// Verifiers (attestation type: verifier)
+export {
+  buildVerifierEvent,
+  createVerifierCredential,
+  parseVerifier,
+  checkCrossVerification,
+  isVerifierRevoked,
+} from './verifiers.js';
+
+// Bonds (proof-of-reserve bond attestation)
+export {
+  buildBondMessage,
+  createBondProof,
+  verifyBondProof,
+  isBondStale,
+  bondProofToTags,
+  parseBondProof,
+  checkBondCompliance,
+} from './bonds.js';
+
+export type { CreateBondProofParams, VerifyBondProofOptions } from './bonds.js';
+
+// Challenges & Revocations (attestation types: challenge, revocation)
+export {
+  buildChallengeEvent,
+  createChallenge,
+  parseChallenge,
+  buildRevocationEvent,
+  createRevocation,
+  parseRevocation,
+  countChallengeConfirmations,
+  hasReachedRevocationThreshold,
+} from './challenges.js';
+
+// Signet Score
+export {
+  computeTrustScore,
+  formatTrustDisplay,
+  verifySignalOrdering,
+} from './trust-score.js';
+
+// Merkle Tree
+export {
+  MerkleTree,
+  verifyMerkleProof,
+  verifySelectiveDisclosure,
+} from './merkle.js';
+
+// Ring Signatures
+export {
+  MAX_RING_SIZE,
+  ringSign,
+  ringVerify,
+  signCredentialRing,
+  verifyCredentialRing,
+} from './ring-signature.js';
+
+export type { RingSignature } from './ring-signature.js';
+
+// LSAG (Linkable Ring Signatures)
+export {
+  MAX_RING_SIZE as LSAG_MAX_RING_SIZE,
+  computeKeyImage,
+  lsagSign,
+  lsagVerify,
+  hasDuplicateKeyImage,
+} from './lsag.js';
+
+export type { LsagSignature } from './lsag.js';
+
+// Identity Bridge (attestation type: identity-bridge)
+export {
+  createIdentityBridge,
+  verifyIdentityBridge,
+  parseIdentityBridge,
+  selectDecoyRing,
+  computeBridgeWeight,
+} from './identity-bridge.js';
+
+// Range Proofs (Pedersen Commitments)
+export {
+  commit,
+  verifyCommitment,
+  createRangeProof,
+  verifyRangeProof,
+  createAgeRangeProof,
+  verifyAgeRangeProof,
+  serializeRangeProof,
+  deserializeRangeProof,
+} from './range-proof.js';
+
+export type { PedersenCommitment, RangeProof } from './range-proof.js';
+
+// Relay Client
+export {
+  RelayClient,
+  publishToRelays,
+  fetchFromRelay,
+} from './relay.js';
+
+export type {
+  RelayMessage,
+  NostrFilter,
+  SubscriptionCallback,
+  RelayState,
+  RelayOptions,
+} from './relay.js';
+
+// Event Store
+export { SignetStore } from './store.js';
+export type { StoreQuery } from './store.js';
+
+// Anomaly Detection
+export {
+  detectAnomalies,
+  scanForAnomalies,
+} from './anomaly.js';
+
+export type {
+  AnomalyType,
+  AnomalyFlag,
+  AnomalyConfig,
+} from './anomaly.js';
+
+// Jurisdictions (re-exported from jurisdiction-kit)
+export {
+  JURISDICTIONS,
+  getJurisdiction,
+  getJurisdictionCodes,
+  getProfessionalBodies,
+  getMutualRecognitionPartners,
+  isProfessionRegulated,
+  findJurisdictionsForProfession,
+  getDigitalConsentAge,
+  getAgeOfMajority,
+  canTransferData,
+  getAllLanguages,
+  getJurisdictionsByLanguage,
+  computeJurisdictionConfidence,
+  getJurisdictionConfidence,
+  rankJurisdictionsByConfidence,
+} from 'jurisdiction-kit';
+
+export type {
+  LegalSystem,
+  ProfessionType,
+  ProfessionalBody,
+  DataProtectionLaw,
+  ChildProtectionLaw,
+  Jurisdiction,
+  JurisdictionConfidence,
+} from 'jurisdiction-kit';
+
+// Internationalization
+export {
+  setLanguage,
+  getLanguage,
+  getSupportedLanguages,
+  t,
+  getTranslations,
+  getLanguageName,
+  getLanguageNativeName,
+  formatLocalizedTrustScore,
+  getTierDescription,
+} from './i18n.js';
+
+export type { LanguageCode, TranslationStrings } from './i18n.js';
+
+// Compliance
+export {
+  checkCredentialCompliance,
+  checkCrossBorderCompliance,
+  checkChildCompliance,
+  getConsentRequirements,
+  getRetentionGuidance,
+  checkMultiJurisdictionCompliance,
+  getMostRestrictiveRequirements,
+} from './compliance.js';
+
+export type {
+  ComplianceSeverity,
+  ComplianceIssue,
+  ComplianceResult,
+  CrossBorderResult,
+  ChildComplianceResult,
+  ConsentRequirement,
+} from './compliance.js';
+
+// Validation
+export {
+  validateCredential,
+  validateVouch,
+  validatePolicy,
+  validateVerifier,
+  validateChallenge,
+  validateRevocation,
+  validateEvent,
+  getTagValue,
+  getTagValues,
+} from './validation.js';
+
+export type { ValidationResult } from './validation.js';
+
+// Errors
+export {
+  SignetError,
+  SignetValidationError,
+  SignetCryptoError,
+} from './errors.js';
+
+// BIP-39 Wordlist
+export { wordlist as BIP39_WORDLIST } from '@scure/bip39/wordlists/english.js';
+
+// Mnemonic (BIP-39)
+export {
+  generateMnemonic,
+  mnemonicToEntropy,
+  entropyToMnemonic,
+  validateMnemonic,
+} from '@scure/bip39';
+export { mnemonicToSeedSync as mnemonicToSeed } from '@scure/bip39';
+
+// Identity Tree (nsec-tree integration)
+export {
+  createSignetIdentity,
+  createSignetIdentityFromNsec,
+  deriveAdditionalPersona,
+  deriveSubIdentity,
+  createLinkageProof,
+  verifyLinkageProof,
+  destroyIdentity,
+  NATURAL_PERSON_PERSONA,
+  ANONYMOUS_PERSONA,
+} from './identity-tree.js';
+
+export type { SignetIdentity } from './identity-tree.js';
+
+// nsec-tree re-exports
+export { zeroise } from 'nsec-tree';
+export type { TreeRoot, Identity, Persona, LinkageProof } from 'nsec-tree';
+
+// NIP-19 encoding (nsec-tree/encoding)
+export { encodeNsec, decodeNsec, encodeNpub, decodeNpub } from 'nsec-tree/encoding';
+
+// Shamir's Secret Sharing
+export {
+  splitSecret,
+  reconstructSecret,
+  shareToWords,
+  wordsToShare,
+} from '@forgesworn/shamir-words';
+
+export type { ShamirShare } from '@forgesworn/shamir-words';
+
+// Connections (ECDH / QR Exchange)
+export {
+  computeSharedSecret,
+  createQRPayload,
+  serializeQRPayload,
+  parseQRPayload,
+  createConnection,
+  ConnectionStore,
+} from './connections.js';
+
+export type { ContactInfo, Connection, QRPayload } from './connections.js';
+
+// Badge Display (Level 1 integration)
+export {
+  computeBadge,
+  getTrustLevel,
+  meetsMinimumTier,
+  filterEventsForPubkey,
+  buildBadgeFilters,
+} from './badge.js';
+
+export type { BadgeInfo, TrustLevel } from './badge.js';
+
+// Signet Words (Time-Based Verification — powered by spoken-token)
+export {
+  SIGNET_EPOCH_SECONDS,
+  SIGNET_WORD_COUNT,
+  SIGNET_TOLERANCE,
+  MAX_WORD_COUNT,
+  SIGNET_WORDLIST,
+  getEpoch,
+  deriveWords,
+  getSignetWords,
+  verifySignetWords,
+  formatSignetWords,
+  getSignetDisplay,
+} from './signet-words.js';
+
+export type { SignetWordsConfig } from './signet-words.js';
+
+// Cold-Call Verification (institutional caller verification via .well-known/signet.json + ephemeral ECDH)
+export {
+  fetchInstitutionKeys,
+  generateSessionCode,
+  deriveColdCallWords,
+  initiateColdCallVerification,
+  completeColdCallVerification,
+  type ColdCallSession,
+} from './cold-call.js';
+
+export type { InstitutionKeys, InstitutionPubkey } from './types.js';

package/src/lsag.ts

@@ -0,0 +1,53 @@
+// LSAG (Linkable Spontaneous Anonymous Group) Ring Signatures
+// Thin re-export from @forgesworn/ring-sig with Signet domain separator.
+// Extends SAG with a key image that links signatures by the same signer
+// across multiple uses of the same election, enabling double-vote detection.
+
+import {
+  computeKeyImage as _computeKeyImage,
+  hasDuplicateKeyImage as _hasDuplicateKeyImage,
+  lsagSign as _lsagSign,
+  lsagVerify as _lsagVerify,
+  type LsagSignature,
+  MAX_RING_SIZE,
+} from '@forgesworn/ring-sig';
+
+const SIGNET_LSAG_DOMAIN = 'signet-lsag-v1';
+
+export { type LsagSignature, MAX_RING_SIZE };
+
+// Key image functions do not involve challenge hashes — safe to re-export directly.
+export const computeKeyImage = _computeKeyImage;
+export const hasDuplicateKeyImage = _hasDuplicateKeyImage;
+
+/**
+ * Sign with LSAG using Signet's domain separator.
+ *
+ * @param message - The message to sign (typically `electionId:SHA-256(encryptedVote)`)
+ * @param ring - Array of x-only public keys (hex) forming the anonymity set
+ * @param signerIndex - Index of the actual signer in the ring
+ * @param privateKey - Signer's private key (hex)
+ * @param electionId - Election identifier for key image linkability
+ * @returns A linkable ring signature with Signet domain
+ */
+export function lsagSign(
+  message: string,
+  ring: string[],
+  signerIndex: number,
+  privateKey: string,
+  electionId: string,
+): LsagSignature {
+  const sig = _lsagSign(message, ring, signerIndex, privateKey, electionId, SIGNET_LSAG_DOMAIN);
+  sig.domain = SIGNET_LSAG_DOMAIN;
+  return sig;
+}
+
+/**
+ * Verify an LSAG signature.
+ *
+ * @param sig - The LSAG signature to verify
+ * @returns true if the signature is valid
+ */
+export function lsagVerify(sig: LsagSignature): boolean {
+  return _lsagVerify(sig);
+}

package/src/merkle.ts

@@ -0,0 +1,176 @@
+// Merkle Tree Selective Disclosure
+// Credential attributes as Merkle leaves — reveal chosen attributes + sibling paths
+
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+import type { MerkleProof, SelectiveDisclosure } from './types.js';
+import { SignetValidationError } from './errors.js';
+
+/**
+ * Hash a leaf node with domain separation prefix 0x00.
+ * Leaf hash: SHA-256(0x00 || "key:value")
+ * RFC 6962 domain separation prevents second-preimage attacks.
+ */
+function hashLeaf(data: string): string {
+  const prefix = new Uint8Array([0x00]);
+  const content = utf8ToBytes(data);
+  const combined = new Uint8Array(1 + content.length);
+  combined.set(prefix);
+  combined.set(content, 1);
+  return bytesToHex(sha256(combined));
+}
+
+/**
+ * Hash an internal node with domain separation prefix 0x01.
+ * Internal node hash: SHA-256(0x01 || left || right)
+ * RFC 6962 domain separation prevents second-preimage attacks.
+ */
+function hashInternal(left: string, right: string): string {
+  const prefix = new Uint8Array([0x01]);
+  const leftBytes = hexToBytes(left);
+  const rightBytes = hexToBytes(right);
+  const combined = new Uint8Array(1 + leftBytes.length + rightBytes.length);
+  combined.set(prefix);
+  combined.set(leftBytes, 1);
+  combined.set(rightBytes, 1 + leftBytes.length);
+  return bytesToHex(sha256(combined));
+}
+
+/** Combine two child hashes into a parent node.
+ *  Order is determined by tree position (left/right), NOT by hash value.
+ *  Sorting would allow proof transplanting between sibling positions. */
+function hashPairOrdered(left: string, right: string): string {
+  return hashInternal(left, right);
+}
+
+/** Build a Merkle tree from leaf values. Returns all levels (bottom-up). */
+function buildTree(leaves: string[]): string[][] {
+  if (leaves.length === 0) throw new SignetValidationError('Cannot build tree from empty leaves');
+
+  // Pad to power of 2
+  const paddedLeaves = [...leaves];
+  while (paddedLeaves.length & (paddedLeaves.length - 1)) {
+    paddedLeaves.push(hashLeaf('__padding__' + paddedLeaves.length));
+  }
+
+  const levels: string[][] = [paddedLeaves];
+  let current = paddedLeaves;
+
+  while (current.length > 1) {
+    const next: string[] = [];
+    for (let i = 0; i < current.length; i += 2) {
+      next.push(hashPairOrdered(current[i], current[i + 1]));
+    }
+    levels.push(next);
+    current = next;
+  }
+
+  return levels;
+}
+
+export class MerkleTree {
+  private levels: string[][];
+  private leafHashes: string[];
+  readonly root: string;
+
+  constructor(private attributes: Record<string, string>) {
+    for (const k of Object.keys(attributes)) {
+      if (k.includes(':')) throw new SignetValidationError(`Merkle attribute key must not contain ':': "${k}"`);
+    }
+    const entries = Object.entries(attributes).sort(([a], [b]) => a.localeCompare(b));
+    // Each leaf is hashLeaf("key:value") — domain-separated with 0x00 prefix
+    this.leafHashes = entries.map(([k, v]) => hashLeaf(`${k}:${v}`));
+    this.levels = buildTree(this.leafHashes);
+    this.root = this.levels[this.levels.length - 1][0];
+  }
+
+  /** Get the Merkle root */
+  getRoot(): string {
+    return this.root;
+  }
+
+  /** Generate a proof for a specific attribute */
+  prove(key: string): MerkleProof {
+    const entries = Object.entries(this.attributes).sort(([a], [b]) => a.localeCompare(b));
+    const idx = entries.findIndex(([k]) => k === key);
+    if (idx === -1) throw new SignetValidationError(`Attribute "${key}" not found`);
+
+    const leafHash = this.leafHashes[idx];
+    const siblings: string[] = [];
+    let currentIdx = idx;
+
+    // Pad index space to match padded tree
+    for (let level = 0; level < this.levels.length - 1; level++) {
+      const siblingIdx = currentIdx ^ 1; // flip last bit to get sibling
+      if (siblingIdx < this.levels[level].length) {
+        siblings.push(this.levels[level][siblingIdx]);
+      }
+      currentIdx = currentIdx >> 1;
+    }
+
+    return {
+      leaf: leafHash,
+      index: idx,
+      siblings,
+      root: this.root,
+    };
+  }
+
+  /** Create a selective disclosure revealing only specified attributes */
+  disclose(keys: string[]): SelectiveDisclosure {
+    const revealedAttributes: Record<string, string> = {};
+    const proofs: MerkleProof[] = [];
+
+    for (const key of keys) {
+      const entries = Object.entries(this.attributes).sort(([a], [b]) => a.localeCompare(b));
+      const entry = entries.find(([k]) => k === key);
+      if (!entry) throw new SignetValidationError(`Attribute "${key}" not found`);
+
+      revealedAttributes[key] = entry[1];
+      proofs.push(this.prove(key));
+    }
+
+    return {
+      revealedAttributes,
+      proofs,
+      merkleRoot: this.root,
+    };
+  }
+}
+
+/** Verify a Merkle proof against a root */
+export function verifyMerkleProof(
+  key: string,
+  value: string,
+  proof: MerkleProof
+): boolean {
+  let currentHash = hashLeaf(`${key}:${value}`);
+  if (currentHash !== proof.leaf) return false;
+
+  let idx = proof.index;
+  for (const sibling of proof.siblings) {
+    // Use index bit to determine left/right position — NOT sorted ordering
+    currentHash = (idx & 1) === 0
+      ? hashPairOrdered(currentHash, sibling)
+      : hashPairOrdered(sibling, currentHash);
+    idx = idx >> 1;
+  }
+
+  return currentHash === proof.root;
+}
+
+/** Verify an entire selective disclosure */
+export function verifySelectiveDisclosure(disclosure: SelectiveDisclosure): boolean {
+  const entries = Object.entries(disclosure.revealedAttributes);
+  if (entries.length !== disclosure.proofs.length) return false;
+
+  for (let i = 0; i < entries.length; i++) {
+    const [key, value] = entries[i];
+    const proof = disclosure.proofs[i];
+
+    if (proof.root !== disclosure.merkleRoot) return false;
+    if (!verifyMerkleProof(key, value, proof)) return false;
+  }
+
+  return true;
+}