signet-protocol 0.1.0

package/src/identity-bridge.ts

@@ -0,0 +1,262 @@
+// Identity Bridge (kind 31000, type: identity-bridge)
+// Allows an anonymous account to cryptographically prove it is controlled by
+// a verified real account, without revealing which one. Uses SAG ring signatures.
+//
+// Published from the anon account. Content contains a ring signature proving
+// one of N verified accounts also controls this anon account.
+
+import { createAttestation } from 'nostr-attestations';
+import { parseAttestation } from 'nostr-attestations';
+import { ATTESTATION_KIND, ATTESTATION_TYPES, MIN_BRIDGE_RING_SIZE, TRUST_WEIGHTS, DEFAULT_CRYPTO_ALGORITHM } from './constants.js';
+import { getPublicKey, signEvent, verifyEvent } from './crypto.js';
+import { ringSign, ringVerify } from './ring-signature.js';
+import { getTagValue } from './validation.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import type { NostrEvent, SignetTier, ParsedIdentityBridge, CryptoAlgorithm } from './types.js';
+import { SignetValidationError, SignetCryptoError } from './errors.js';
+import type { RingSignature } from './ring-signature.js';
+
+/** Generate a cryptographically secure random integer in [0, max) using rejection sampling */
+function secureRandomInt(max: number): number {
+  if (!Number.isInteger(max) || !Number.isSafeInteger(max) || max <= 0) {
+    throw new SignetCryptoError(`secureRandomInt: max must be a positive safe integer, got ${max}`);
+  }
+  const limit = Math.floor(0x100000000 / max) * max;
+  let val: number;
+  do {
+    const bytes = randomBytes(4);
+    val = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0;
+  } while (val >= limit);
+  return val % max;
+}
+
+/**
+ * Select decoy ring members from a set of verified pubkeys.
+ * Inserts the real pubkey at a random position among the decoys.
+ *
+ * @param verifiedPubkeys - Pool of verified pubkeys to choose decoys from (must not include realPubkey)
+ * @param realPubkey - The real verified account's pubkey
+ * @param ringSize - Desired ring size (minimum MIN_BRIDGE_RING_SIZE)
+ * @returns { ring, signerIndex } — the ring array and the position of the real signer
+ */
+export function selectDecoyRing(
+  verifiedPubkeys: string[],
+  realPubkey: string,
+  ringSize: number = MIN_BRIDGE_RING_SIZE
+): { ring: string[]; signerIndex: number } {
+  if (ringSize < MIN_BRIDGE_RING_SIZE) {
+    throw new SignetValidationError(`Ring size must be at least ${MIN_BRIDGE_RING_SIZE}`);
+  }
+  // Filter out the real pubkey from candidates
+  const candidates = verifiedPubkeys.filter((pk) => pk !== realPubkey);
+  const decoyCount = ringSize - 1;
+  if (candidates.length < decoyCount) {
+    throw new SignetValidationError(
+      `Not enough verified pubkeys for ring: need ${decoyCount} decoys, have ${candidates.length}`
+    );
+  }
+
+  // Shuffle and pick decoys (Fisher-Yates partial shuffle, CSPRNG)
+  const shuffled = [...candidates];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = secureRandomInt(i + 1);
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  const decoys = shuffled.slice(0, decoyCount);
+
+  // Insert real pubkey at a random position (CSPRNG)
+  const signerIndex = secureRandomInt(ringSize);
+  const ring: string[] = [];
+  let decoyIdx = 0;
+  for (let i = 0; i < ringSize; i++) {
+    if (i === signerIndex) {
+      ring.push(realPubkey);
+    } else {
+      ring.push(decoys[decoyIdx++]);
+    }
+  }
+
+  return { ring, signerIndex };
+}
+
+/**
+ * Compute the trust weight contribution of an identity bridge based on the
+ * minimum tier of ring members.
+ */
+export function computeBridgeWeight(ringMinTier: SignetTier): number {
+  return TRUST_WEIGHTS.IDENTITY_BRIDGE * (ringMinTier / 4);
+}
+
+/**
+ * Create an identity bridge event (kind 31000, type: identity-bridge).
+ * Published from the anonymous account, it proves the anon account owner
+ * also controls one of the verified accounts in the ring.
+ *
+ * @param anonPrivateKey - Private key of the anonymous account (signs the Nostr event)
+ * @param realPrivateKey - Private key of the real verified account (signs the ring signature)
+ * @param ring - Array of verified pubkeys forming the anonymity set
+ * @param signerIndex - Position of the real account in the ring
+ * @param ringMinTier - Minimum verification tier among ring members
+ * @returns Signed kind 31000 (type: identity-bridge) NostrEvent
+ */
+export async function createIdentityBridge(
+  anonPrivateKey: string,
+  realPrivateKey: string,
+  ring: string[],
+  signerIndex: number,
+  ringMinTier: SignetTier,
+  opts?: { occurredAt?: number }
+): Promise<NostrEvent> {
+  if (ring.length < MIN_BRIDGE_RING_SIZE) {
+    throw new SignetValidationError(`Ring must have at least ${MIN_BRIDGE_RING_SIZE} members`);
+  }
+
+  const anonPubkey = getPublicKey(anonPrivateKey);
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  // The binding message ties the anon pubkey to this timestamp
+  const bindingMessage = `signet:identity-bridge:${anonPubkey}:${timestamp}`;
+
+  // Ring signature: real private key signs binding message inside the ring
+  const ringSig = ringSign(bindingMessage, ring, signerIndex, realPrivateKey);
+
+  const contentPayload = JSON.stringify({
+    ringSig: {
+      ring: ringSig.ring,
+      c0: ringSig.c0,
+      responses: ringSig.responses,
+      message: ringSig.message,
+      domain: ringSig.domain,
+    },
+    timestamp,
+  });
+
+  const template = createAttestation({
+    type: ATTESTATION_TYPES.IDENTITY_BRIDGE,
+    occurredAt: opts?.occurredAt,
+    summary: 'Anonymous account linked to verified identity via ring signature',
+    tags: [
+      ['ring-min-tier', String(ringMinTier)],
+      ['ring-size', String(ring.length)],
+      ['algo', DEFAULT_CRYPTO_ALGORITHM],
+    ],
+    content: contentPayload,
+  });
+
+  const unsigned = {
+    ...template,
+    pubkey: anonPubkey,
+    created_at: timestamp,
+  };
+
+  return signEvent(unsigned, anonPrivateKey);
+}
+
+/** Default maximum age for an identity bridge event: 24 hours */
+const DEFAULT_MAX_AGE_SECONDS = 24 * 60 * 60;
+
+/**
+ * Verify an identity bridge event.
+ * Checks: Nostr signature, ring signature validity, ring size >= minimum,
+ * and optionally that the bridge is not too old (replay resistance).
+ *
+ * @param event - The identity bridge event to verify
+ * @param opts - Optional verification parameters
+ * @param opts.maxAgeSeconds - Maximum age of the bridge in seconds (default: 24h).
+ *                             Set to 0 to disable freshness checking.
+ */
+export async function verifyIdentityBridge(
+  event: NostrEvent,
+  opts?: { maxAgeSeconds?: number }
+): Promise<boolean> {
+  // Check kind + type tag
+  if (event.kind !== ATTESTATION_KIND) return false;
+  if (getTagValue(event, 'type') !== ATTESTATION_TYPES.IDENTITY_BRIDGE) return false;
+
+  // Verify Nostr event signature
+  const validEvent = await verifyEvent(event);
+  if (!validEvent) return false;
+
+  // Parse content
+  let parsed: { ringSig: RingSignature; timestamp: number };
+  try {
+    const raw = JSON.parse(event.content);
+    if (!raw || typeof raw !== 'object' ||
+        !raw.ringSig || typeof raw.ringSig !== 'object' ||
+        !Array.isArray(raw.ringSig.ring) || typeof raw.ringSig.message !== 'string' ||
+        typeof raw.timestamp !== 'number') {
+      return false;
+    }
+    parsed = raw;
+  } catch {
+    return false;
+  }
+
+  // Verify ring size
+  const ringSize = parseInt(getTagValue(event, 'ring-size') || '0', 10);
+  if (ringSize < MIN_BRIDGE_RING_SIZE) return false;
+  if (parsed.ringSig.ring.length !== ringSize) return false;
+
+  // Verify binding message format and timestamp consistency
+  const expectedMessage = `signet:identity-bridge:${event.pubkey}:${parsed.timestamp}`;
+  if (parsed.ringSig.message !== expectedMessage) return false;
+
+  // Verify timestamp in binding message matches event created_at
+  if (parsed.timestamp !== event.created_at) return false;
+
+  // Freshness check: reject bridges older than maxAgeSeconds (replay resistance)
+  const maxAge = opts?.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+  if (maxAge > 0) {
+    const now = Math.floor(Date.now() / 1000);
+    if (now - parsed.timestamp > maxAge) return false;
+  }
+
+  // Verify ring signature
+  return ringVerify(parsed.ringSig);
+}
+
+/**
+ * Parse an identity bridge event into a structured form.
+ */
+export function parseIdentityBridge(event: NostrEvent): ParsedIdentityBridge | null {
+  const base = parseAttestation(event);
+  if (!base) return null;
+  if (base.type !== ATTESTATION_TYPES.IDENTITY_BRIDGE) return null;
+
+  try {
+    const parsed = JSON.parse(event.content);
+
+    if (!parsed || typeof parsed !== 'object' ||
+        !parsed.ringSig || typeof parsed.ringSig !== 'object' ||
+        !Array.isArray(parsed.ringSig.ring) ||
+        typeof parsed.ringSig.message !== 'string' ||
+        typeof parsed.ringSig.c0 !== 'string' ||
+        !Array.isArray(parsed.ringSig.responses) ||
+        typeof parsed.timestamp !== 'number') {
+      return null;
+    }
+
+    // Validate ring elements are strings
+    if (!parsed.ringSig.ring.every((r: unknown) => typeof r === 'string')) {
+      return null;
+    }
+
+    const rawMinTier = parseInt(getTagValue(event, 'ring-min-tier') || '1', 10);
+    const ringMinTier = (!isNaN(rawMinTier) && rawMinTier >= 1 && rawMinTier <= 4 ? rawMinTier : 1) as SignetTier;
+    const ringSize = parseInt(getTagValue(event, 'ring-size') || '0', 10);
+    if (isNaN(ringSize) || ringSize < 0 || ringSize > 1000) return null;
+
+    const algorithm = (getTagValue(event, 'algo') || DEFAULT_CRYPTO_ALGORITHM) as CryptoAlgorithm;
+
+    return {
+      anonPubkey: event.pubkey,
+      ringMinTier,
+      ringSize,
+      ring: parsed.ringSig.ring,
+      timestamp: parsed.timestamp,
+      algorithm,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/identity-tree.ts

@@ -0,0 +1,90 @@
+import { fromMnemonic, fromNsec, zeroise, createBlindProof, createFullProof, verifyProof } from 'nsec-tree'
+import { derivePersona, deriveFromPersona } from 'nsec-tree/persona'
+import type { TreeRoot, Persona, Identity, LinkageProof } from 'nsec-tree'
+import { SignetValidationError } from './errors.js'
+
+/** Purpose strings for signet's two required personas. */
+export const NATURAL_PERSON_PERSONA = 'natural-person'
+export const ANONYMOUS_PERSONA = 'persona'
+
+/** A signet identity backed by an nsec-tree derivation tree. */
+export interface SignetIdentity {
+  readonly root: TreeRoot
+  readonly naturalPerson: Persona
+  readonly persona: Persona
+  readonly mnemonic?: string
+}
+
+function deriveRequiredPersonas(root: TreeRoot): { naturalPerson: Persona; persona: Persona } {
+  const naturalPerson = derivePersona(root, NATURAL_PERSON_PERSONA)
+  const persona = derivePersona(root, ANONYMOUS_PERSONA)
+  return { naturalPerson, persona }
+}
+
+/**
+ * Create a signet identity from a BIP-39 mnemonic.
+ * Derives the tree root via nsec-tree's `fromMnemonic()` (path m/44'/1237'/727'/0'/0'),
+ * then derives both required personas.
+ */
+export function createSignetIdentity(mnemonic: string, passphrase?: string): SignetIdentity {
+  const root = fromMnemonic(mnemonic, passphrase)
+  const { naturalPerson, persona } = deriveRequiredPersonas(root)
+  return { root, naturalPerson, persona, mnemonic }
+}
+
+/**
+ * Create a signet identity from an existing nsec.
+ * Wraps the nsec through nsec-tree's HMAC separation layer,
+ * then derives both required personas.
+ */
+export function createSignetIdentityFromNsec(nsec: string | Uint8Array): SignetIdentity {
+  const root = fromNsec(nsec)
+  const { naturalPerson, persona } = deriveRequiredPersonas(root)
+  return { root, naturalPerson, persona }
+}
+
+/**
+ * Derive an additional named persona from the tree root.
+ * Use for optional personas beyond the two required ones.
+ */
+export function deriveAdditionalPersona(root: TreeRoot, name: string, index = 0): Persona {
+  if (!name) {
+    throw new SignetValidationError('Persona name must not be empty')
+  }
+  return derivePersona(root, name, index)
+}
+
+/**
+ * Derive a sub-identity within a persona (two-level hierarchy).
+ * Useful for group signing or isolated sub-keys under a persona.
+ */
+export function deriveSubIdentity(persona: Persona, purpose: string, index = 0): Identity {
+  return deriveFromPersona(persona, purpose, index)
+}
+
+/**
+ * Create a linkage proof proving the tree root owns a child identity.
+ * Blind proofs reveal nothing about derivation; full proofs include purpose and index.
+ */
+export function createLinkageProof(
+  root: TreeRoot,
+  child: Identity,
+  type: 'blind' | 'full',
+): LinkageProof {
+  return type === 'blind'
+    ? createBlindProof(root, child)
+    : createFullProof(root, child)
+}
+
+/** Re-export nsec-tree's proof verification. */
+export const verifyLinkageProof = verifyProof
+
+/**
+ * Destroy a signet identity: zeroes the tree root secret and both persona private keys.
+ * After calling this, the identity is unusable.
+ */
+export function destroyIdentity(identity: SignetIdentity): void {
+  zeroise(identity.naturalPerson.identity)
+  zeroise(identity.persona.identity)
+  identity.root.destroy()
+}