signet-protocol 0.1.0

package/src/ring-signature.ts

@@ -0,0 +1,76 @@
+// SAG Ring Signatures — thin re-export from @forgesworn/ring-sig with Signet domain separator
+// Proves "one of N public keys signed this message" without revealing which one.
+// Used for Tier 3/4 issuer privacy: "a professional verified this" without revealing which professional.
+
+import { ringSign as _ringSign, ringVerify as _ringVerify, type RingSignature, MAX_RING_SIZE } from '@forgesworn/ring-sig';
+
+const SIGNET_SAG_DOMAIN = 'signet-sag-v1';
+
+export { MAX_RING_SIZE, type RingSignature };
+
+/**
+ * Sign a message with a ring signature using Signet's domain separator.
+ *
+ * @param message - The message to sign (will be hashed)
+ * @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)
+ * @returns A ring signature
+ */
+export function ringSign(
+  message: string,
+  ring: string[],
+  signerIndex: number,
+  privateKey: string
+): RingSignature {
+  const sig = _ringSign(message, ring, signerIndex, privateKey, SIGNET_SAG_DOMAIN);
+  // Ensure the domain is carried in the signature so ringVerify uses the correct domain
+  sig.domain = SIGNET_SAG_DOMAIN;
+  return sig;
+}
+
+/**
+ * Verify a ring signature.
+ *
+ * @param sig - The ring signature to verify
+ * @returns true if the signature is valid
+ */
+export function ringVerify(sig: RingSignature): boolean {
+  return _ringVerify(sig);
+}
+
+/**
+ * Create a ring signature for a Signet credential.
+ * Wraps ringSign with credential-specific message construction.
+ *
+ * @param credentialEventId - The event ID of the credential being signed
+ * @param subjectPubkey - The pubkey of the person being verified
+ * @param ring - Array of verifier pubkeys forming the anonymity set
+ * @param signerIndex - Index of the actual signing verifier
+ * @param privateKey - Signing verifier's private key
+ */
+export function signCredentialRing(
+  credentialEventId: string,
+  subjectPubkey: string,
+  ring: string[],
+  signerIndex: number,
+  privateKey: string
+): RingSignature {
+  const message = `signet:credential:${credentialEventId}:${subjectPubkey}`;
+  const sig = _ringSign(message, ring, signerIndex, privateKey, SIGNET_SAG_DOMAIN);
+  sig.domain = SIGNET_SAG_DOMAIN;
+  return sig;
+}
+
+/**
+ * Verify a ring signature on a Signet credential.
+ */
+export function verifyCredentialRing(
+  sig: RingSignature,
+  credentialEventId: string,
+  subjectPubkey: string
+): boolean {
+  const expectedMessage = `signet:credential:${credentialEventId}:${subjectPubkey}`;
+  if (sig.message !== expectedMessage) return false;
+  return _ringVerify(sig);
+}

package/src/signet-words.ts

@@ -0,0 +1,122 @@
+// Signet Words — Time-based word verification ("signet me")
+// Signet handles identity (who you are). Spoken-token handles token derivation.
+// Uses SPOKEN-DERIVE (HMAC-SHA256) and the spoken-clarity wordlist.
+
+import { deriveTokenBytes } from 'spoken-token';
+import { encodeAsWords } from 'spoken-token/encoding';
+import { WORDLIST } from 'spoken-token/wordlist';
+import { constantTimeEqual } from './utils.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+import { SignetValidationError } from './errors.js';
+
+/** The Canary spoken-clarity wordlist used for Signet word verification. */
+export { WORDLIST as SIGNET_WORDLIST } from 'spoken-token/wordlist';
+
+/** Default: words rotate every 30 seconds */
+export const SIGNET_EPOCH_SECONDS = 30;
+
+/** Default: 3 words per signet */
+export const SIGNET_WORD_COUNT = 3;
+
+/** Default: accept +/-1 epoch window for clock skew tolerance */
+export const SIGNET_TOLERANCE = 1;
+
+/** Maximum supported word count (limited by HMAC output bytes: 32 bytes / 2 bytes per word = 16) */
+export const MAX_WORD_COUNT = 16;
+
+/** Context string for Signet word derivation via CANARY-DERIVE */
+const SIGNET_CONTEXT = 'signet:verify';
+
+/** Configuration options for signet words */
+export interface SignetWordsConfig {
+  /** Number of words to derive (1-16, default: 3) */
+  wordCount?: number;
+  /** Epoch interval in seconds (default: 30) */
+  epochSeconds?: number;
+  /** Tolerance in epochs, +/- (default: 1) */
+  tolerance?: number;
+}
+
+/** Return the current epoch index for a given interval. */
+export function getEpoch(timestampMs?: number, epochSeconds: number = SIGNET_EPOCH_SECONDS): number {
+  if (epochSeconds < 1) throw new SignetValidationError('epochSeconds must be >= 1');
+  return Math.floor((timestampMs ?? Date.now()) / (epochSeconds * 1000));
+}
+
+/** Derive N words from a shared secret and epoch number.
+ *  Uses SPOKEN-DERIVE (HMAC-SHA256) and encodes as spoken-clarity words.
+ *  @param sharedSecret - Hex string or Uint8Array shared secret (minimum 16 bytes).
+ *  @param epoch - Time-based epoch counter (uint32).
+ *  @param wordCount - Number of words to derive (1-16, default 3).
+ *  @param context - Domain-separation context string (default: 'signet:verify'). */
+export function deriveWords(
+  sharedSecret: Uint8Array | string,
+  epoch: number,
+  wordCount: number = SIGNET_WORD_COUNT,
+  context: string = SIGNET_CONTEXT,
+): string[] {
+  if (wordCount < 1 || wordCount > MAX_WORD_COUNT) {
+    throw new SignetValidationError(`wordCount must be between 1 and ${MAX_WORD_COUNT}`);
+  }
+
+  const bytes = deriveTokenBytes(sharedSecret, context, epoch);
+  return encodeAsWords(bytes, wordCount, WORDLIST);
+}
+
+/** Get the current word sequence for a shared secret. */
+export function getSignetWords(sharedSecret: string, timestampMs?: number, config?: SignetWordsConfig): string[] {
+  const epochSeconds = config?.epochSeconds ?? SIGNET_EPOCH_SECONDS;
+  const wordCount = config?.wordCount ?? SIGNET_WORD_COUNT;
+  return deriveWords(sharedSecret, getEpoch(timestampMs, epochSeconds), wordCount);
+}
+
+/** Verify that the given words match the current epoch (+/- tolerance).
+ *  Returns true if the words match any epoch within the tolerance window. */
+export function verifySignetWords(
+  sharedSecret: string,
+  words: string[],
+  timestampMs?: number,
+  config?: SignetWordsConfig,
+): boolean {
+  const epochSeconds = config?.epochSeconds ?? SIGNET_EPOCH_SECONDS;
+  const wordCount = config?.wordCount ?? SIGNET_WORD_COUNT;
+  const tolerance = config?.tolerance ?? SIGNET_TOLERANCE;
+  const currentEpoch = getEpoch(timestampMs, epochSeconds);
+
+  for (let offset = -tolerance; offset <= tolerance; offset++) {
+    const candidate = deriveWords(sharedSecret, currentEpoch + offset, wordCount);
+    if (candidate.length === words.length) {
+      const a = utf8ToBytes(candidate.join('\0'));
+      const b = utf8ToBytes(words.join('\0'));
+      if (constantTimeEqual(a, b)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/** Format words with middle-dot separator: "ocean · tiger · marble" */
+export function formatSignetWords(words: string[]): string {
+  return words.join(' \u00b7 ');
+}
+
+/** Get everything needed for UI display: words, formatted string, and countdown. */
+export function getSignetDisplay(
+  sharedSecret: string,
+  timestampMs?: number,
+  config?: SignetWordsConfig,
+): { words: string[]; formatted: string; expiresIn: number } {
+  const epochSeconds = config?.epochSeconds ?? SIGNET_EPOCH_SECONDS;
+  const now = timestampMs ?? Date.now();
+  const words = getSignetWords(sharedSecret, now, config);
+  const formatted = formatSignetWords(words);
+
+  // Seconds until the next epoch boundary
+  const epochMs = epochSeconds * 1000;
+  const msIntoEpoch = now % epochMs;
+  const expiresIn = (epochMs - msIntoEpoch) / 1000;
+
+  return { words, formatted, expiresIn };
+}

package/src/store.ts

@@ -0,0 +1,336 @@
+// Signet Event Store
+// In-memory event storage with query support and JSON serialization
+
+import { ATTESTATION_KIND, ATTESTATION_TYPES, APP_DATA_KIND } from './constants.js';
+import { getTagValue, validateFieldSizeBounds } from './validation.js';
+import { SignetValidationError } from './errors.js';
+import type {
+  NostrEvent,
+  ParsedCredential,
+} from './types.js';
+import { parseCredential } from './credentials.js';
+
+/** Query options for filtering events */
+export interface StoreQuery {
+  kinds?: number[];
+  authors?: string[];
+  subjects?: string[];  // query by 'd' tag
+  since?: number;
+  until?: number;
+  limit?: number;
+}
+
+/**
+ * In-memory Signet event store.
+ * Stores events indexed by kind, author, and subject for fast queries.
+ * Handles replaceable event semantics (kind 30xxx: newer replaces older for same d-tag).
+ */
+export class SignetStore {
+  private events = new Map<string, NostrEvent>();
+
+  // Indexes for fast queries
+  private byKind = new Map<number, Set<string>>();
+  private byAuthor = new Map<string, Set<string>>();
+  private bySubject = new Map<string, Set<string>>();
+
+  /** Add an event to the store. Returns true if added (not a duplicate/older). */
+  add(event: NostrEvent): boolean {
+    // Check if this is a replaceable event (kind 30000-39999)
+    if (event.kind >= 30000 && event.kind < 40000) {
+      const dTag = getTagValue(event, 'd');
+
+      // Find existing event with same replace key
+      for (const [id, existing] of this.events) {
+        if (existing.kind === event.kind && existing.pubkey === event.pubkey) {
+          const existingD = getTagValue(existing, 'd');
+          if (existingD === dTag) {
+            if (existing.created_at >= event.created_at) {
+              return false; // existing is newer or same
+            }
+            // Remove older event
+            this.remove(id);
+            break;
+          }
+        }
+      }
+    }
+
+    // Deduplicate by event ID
+    if (this.events.has(event.id)) return false;
+
+    this.events.set(event.id, event);
+    this.indexEvent(event);
+    return true;
+  }
+
+  /** Remove an event by ID */
+  remove(id: string): boolean {
+    const event = this.events.get(id);
+    if (!event) return false;
+
+    this.events.delete(id);
+    this.deindexEvent(event);
+    return true;
+  }
+
+  /** Get an event by ID */
+  get(id: string): NostrEvent | undefined {
+    return this.events.get(id);
+  }
+
+  /** Check if an event exists */
+  has(id: string): boolean {
+    return this.events.has(id);
+  }
+
+  /** Total number of events */
+  get size(): number {
+    return this.events.size;
+  }
+
+  /** Query events with filters */
+  query(q: StoreQuery = {}): NostrEvent[] {
+    let candidateIds: Set<string> | null = null;
+
+    // Narrow by kind
+    if (q.kinds?.length) {
+      const kindIds = new Set<string>();
+      for (const kind of q.kinds) {
+        const ids = this.byKind.get(kind);
+        if (ids) ids.forEach((id) => kindIds.add(id));
+      }
+      candidateIds = kindIds;
+    }
+
+    // Narrow by author
+    if (q.authors?.length) {
+      const authorIds = new Set<string>();
+      for (const author of q.authors) {
+        const ids = this.byAuthor.get(author);
+        if (ids) ids.forEach((id) => authorIds.add(id));
+      }
+      candidateIds = candidateIds
+        ? intersect(candidateIds, authorIds)
+        : authorIds;
+    }
+
+    // Narrow by subject
+    if (q.subjects?.length) {
+      const subjectIds = new Set<string>();
+      for (const subject of q.subjects) {
+        const ids = this.bySubject.get(subject);
+        if (ids) ids.forEach((id) => subjectIds.add(id));
+      }
+      candidateIds = candidateIds
+        ? intersect(candidateIds, subjectIds)
+        : subjectIds;
+    }
+
+    // Collect events
+    const ids = candidateIds ?? new Set(this.events.keys());
+    let results: NostrEvent[] = [];
+    for (const id of ids) {
+      const event = this.events.get(id);
+      if (!event) continue;
+
+      if (q.since && event.created_at < q.since) continue;
+      if (q.until && event.created_at > q.until) continue;
+
+      results.push(event);
+    }
+
+    // Sort by created_at descending (newest first)
+    results.sort((a, b) => b.created_at - a.created_at);
+
+    if (q.limit && results.length > q.limit) {
+      results = results.slice(0, q.limit);
+    }
+
+    return results;
+  }
+
+  // --- Convenience query methods ---
+
+  /** Get all credentials for a subject */
+  getCredentials(subjectPubkey: string): NostrEvent[] {
+    return this.query({ kinds: [ATTESTATION_KIND], subjects: [`credential:${subjectPubkey}`, subjectPubkey] })
+      .filter((e) => getTagValue(e, 'type') === ATTESTATION_TYPES.CREDENTIAL);
+  }
+
+  /** Get the highest-tier credential for a subject */
+  getHighestCredential(subjectPubkey: string): ParsedCredential | null {
+    const creds = this.getCredentials(subjectPubkey);
+    let highest: ParsedCredential | null = null;
+
+    for (const cred of creds) {
+      const parsed = parseCredential(cred);
+      if (parsed && (!highest || parsed.tier > highest.tier)) {
+        highest = parsed;
+      }
+    }
+
+    return highest;
+  }
+
+  /** Get all vouches for a subject */
+  getVouches(subjectPubkey: string): NostrEvent[] {
+    return this.query({ kinds: [ATTESTATION_KIND], subjects: [`vouch:${subjectPubkey}`, subjectPubkey] })
+      .filter((e) => getTagValue(e, 'type') === ATTESTATION_TYPES.VOUCH);
+  }
+
+  /** Get the community policy for a community */
+  getPolicy(communityId: string): NostrEvent | undefined {
+    const policies = this.query({ kinds: [APP_DATA_KIND] });
+    return policies.find((p) => {
+      const dTag = getTagValue(p, 'd') || '';
+      return dTag === `signet:policy:${communityId}`;
+    });
+  }
+
+  /** Get a verifier credential */
+  getVerifierCredential(verifierPubkey: string): NostrEvent | undefined {
+    const creds = this.query({ kinds: [ATTESTATION_KIND], authors: [verifierPubkey] })
+      .filter((e) => getTagValue(e, 'type') === ATTESTATION_TYPES.VERIFIER);
+    return creds[0];
+  }
+
+  /** Get all challenges against a verifier */
+  getChallenges(verifierPubkey: string): NostrEvent[] {
+    return this.query({ kinds: [ATTESTATION_KIND], subjects: [`challenge:${verifierPubkey}`, verifierPubkey] })
+      .filter((e) => getTagValue(e, 'type') === ATTESTATION_TYPES.CHALLENGE);
+  }
+
+  /** Get all revocations for a verifier */
+  getRevocations(verifierPubkey: string): NostrEvent[] {
+    return this.query({ kinds: [ATTESTATION_KIND], subjects: [`revocation:${verifierPubkey}`, verifierPubkey] })
+      .filter((e) => getTagValue(e, 'type') === ATTESTATION_TYPES.REVOCATION);
+  }
+
+  /** Check if a verifier is revoked */
+  isRevoked(verifierPubkey: string): boolean {
+    return this.getRevocations(verifierPubkey).length > 0;
+  }
+
+  /** Get all credentials issued by a verifier */
+  getCredentialsByIssuer(issuerPubkey: string): NostrEvent[] {
+    return this.query({ kinds: [ATTESTATION_KIND], authors: [issuerPubkey] })
+      .filter((e) => getTagValue(e, 'type') === ATTESTATION_TYPES.CREDENTIAL);
+  }
+
+  // --- Serialization ---
+
+  /** Export all events as JSON */
+  export(): string {
+    return JSON.stringify(Array.from(this.events.values()));
+  }
+
+  /** Import events from JSON.
+   *
+   * WARNING: This method validates structural shape and field-size bounds but does
+   * NOT verify event signatures. Callers are responsible for verifying cryptographic
+   * validity before importing untrusted data. The RelayClient verifies signatures
+   * by default — this gap only affects direct callers of store.import(). */
+  import(json: string): number {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      throw new SignetValidationError('Import data is not valid JSON');
+    }
+    if (!Array.isArray(parsed)) {
+      throw new SignetValidationError('Import data must be a JSON array');
+    }
+    const MAX_IMPORT_SIZE = 10_000;
+    if (parsed.length > MAX_IMPORT_SIZE) {
+      throw new SignetValidationError(`Import array too large: ${parsed.length} items (max ${MAX_IMPORT_SIZE})`);
+    }
+    const events: NostrEvent[] = [];
+    for (const item of parsed) {
+      if (
+        typeof item !== 'object' || item === null ||
+        typeof item.id !== 'string' ||
+        typeof item.pubkey !== 'string' ||
+        typeof item.kind !== 'number' ||
+        typeof item.created_at !== 'number' ||
+        !Array.isArray(item.tags) ||
+        typeof item.content !== 'string' ||
+        typeof item.sig !== 'string' ||
+        !item.tags.every((t: unknown) => Array.isArray(t) && t.every((v: unknown) => typeof v === 'string'))
+      ) {
+        continue; // skip malformed entries
+      }
+      // Validate hex format of id, pubkey, sig
+      if (!/^[0-9a-f]{64}$/.test(item.id) || !/^[0-9a-f]{64}$/.test(item.pubkey) || !/^[0-9a-f]{128}$/.test(item.sig)) {
+        continue;
+      }
+      // Validate field-size bounds on imported events
+      const boundsErrors: string[] = [];
+      validateFieldSizeBounds(item as NostrEvent, boundsErrors);
+      if (boundsErrors.length > 0) continue;
+
+      events.push(item as NostrEvent);
+    }
+    let added = 0;
+    for (const event of events) {
+      if (this.add(event)) added++;
+    }
+    return added;
+  }
+
+  /** Clear all events */
+  clear(): void {
+    this.events.clear();
+    this.byKind.clear();
+    this.byAuthor.clear();
+    this.bySubject.clear();
+  }
+
+  // --- Index management ---
+
+  private indexEvent(event: NostrEvent): void {
+    // Index by kind
+    if (!this.byKind.has(event.kind)) this.byKind.set(event.kind, new Set());
+    this.byKind.get(event.kind)!.add(event.id);
+
+    // Index by author
+    if (!this.byAuthor.has(event.pubkey)) this.byAuthor.set(event.pubkey, new Set());
+    this.byAuthor.get(event.pubkey)!.add(event.id);
+
+    // Index by subject (d tag)
+    const subject = getTagValue(event, 'd');
+    if (subject) {
+      if (!this.bySubject.has(subject)) this.bySubject.set(subject, new Set());
+      this.bySubject.get(subject)!.add(event.id);
+    }
+
+    // Also index by p tag (many events reference subjects via p tag)
+    const pTags = event.tags.filter((t) => t[0] === 'p').map((t) => t[1]);
+    for (const p of pTags) {
+      if (!this.bySubject.has(p)) this.bySubject.set(p, new Set());
+      this.bySubject.get(p)!.add(event.id);
+    }
+  }
+
+  private deindexEvent(event: NostrEvent): void {
+    this.byKind.get(event.kind)?.delete(event.id);
+    this.byAuthor.get(event.pubkey)?.delete(event.id);
+
+    const subject = getTagValue(event, 'd');
+    if (subject) this.bySubject.get(subject)?.delete(event.id);
+
+    const pTags = event.tags.filter((t) => t[0] === 'p').map((t) => t[1]);
+    for (const p of pTags) {
+      this.bySubject.get(p)?.delete(event.id);
+    }
+  }
+}
+
+/** Set intersection */
+function intersect(a: Set<string>, b: Set<string>): Set<string> {
+  const result = new Set<string>();
+  const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+  for (const item of smaller) {
+    if (larger.has(item)) result.add(item);
+  }
+  return result;
+}