signet-protocol 0.1.0

package/src/bonds.ts

@@ -0,0 +1,203 @@
+// Proof-of-Reserve Bond Attestation
+// Non-custodial bond system: verifiers prove Bitcoin address control via BIP-322
+
+import { BOND_DOMAIN_SEPARATOR, DEFAULT_BOND_MAX_AGE_SECS, VALID_BOND_ADDRESS_TYPES } from './constants.js';
+import { getTagValue } from './validation.js';
+import { SignetValidationError } from './errors.js';
+import type { BondProof, BondStatus, BondVerificationResult, BIP322Verifier, BitcoinAddressType, NostrEvent } from './types.js';
+
+/** Build the canonical BIP-322 message for a bond proof */
+export function buildBondMessage(
+  verifierPubkey: string,
+  amountSats: number,
+  timestamp: number,
+): string {
+  return `${BOND_DOMAIN_SEPARATOR}:${verifierPubkey}:${amountSats}:${timestamp}`;
+}
+
+export interface CreateBondProofParams {
+  address: string;
+  addressType: BitcoinAddressType;
+  amountSats: number;
+  signature: string;
+  verifierPubkey: string;
+  timestamp?: number;
+}
+
+/** Create a BondProof object (does not verify the signature) */
+export function createBondProof(params: CreateBondProofParams): BondProof {
+  const timestamp = params.timestamp ?? Math.floor(Date.now() / 1000);
+  const message = buildBondMessage(params.verifierPubkey, params.amountSats, timestamp);
+
+  return {
+    address: params.address,
+    addressType: params.addressType,
+    amountSats: params.amountSats,
+    timestamp,
+    message,
+    signature: params.signature,
+  };
+}
+
+export interface VerifyBondProofOptions {
+  /** External BIP-322 verifier. If omitted, signature is not checked (status becomes 'unverified'). */
+  verifier?: BIP322Verifier;
+  /** Maximum age in seconds (default: DEFAULT_BOND_MAX_AGE_SECS) */
+  maxAgeSecs?: number;
+  /** Minimum required amount in satoshis */
+  requiredSats?: number;
+  /** Override current time (unix seconds, for testing) */
+  now?: number;
+}
+
+/** Verify a bond proof structurally and optionally cryptographically */
+export async function verifyBondProof(
+  proof: BondProof,
+  verifierPubkey: string,
+  opts: VerifyBondProofOptions = {},
+): Promise<BondVerificationResult> {
+  const errors: string[] = [];
+  const now = opts.now ?? Math.floor(Date.now() / 1000);
+  const maxAgeSecs = opts.maxAgeSecs ?? DEFAULT_BOND_MAX_AGE_SECS;
+
+  // Structural validation
+  if (!proof.address) {
+    errors.push('Bond proof has empty address');
+  }
+  if (!proof.signature) {
+    errors.push('Bond proof has empty signature');
+  }
+  if (proof.amountSats <= 0) {
+    errors.push('Bond amount must be positive');
+  }
+  if (proof.timestamp > now) {
+    errors.push('Bond proof timestamp is in the future');
+  }
+
+  // Verify that the message matches the expected format
+  const expectedMessage = buildBondMessage(verifierPubkey, proof.amountSats, proof.timestamp);
+  if (proof.message !== expectedMessage) {
+    errors.push('Bond proof message does not match expected format for this verifier');
+  }
+
+  const ageSecs = now - proof.timestamp;
+  const fresh = ageSecs <= maxAgeSecs;
+
+  // Check threshold
+  const meetsThreshold = opts.requiredSats != null
+    ? proof.amountSats >= opts.requiredSats
+    : null;
+
+  // Signature verification
+  let signatureValid: boolean | null = null;
+
+  if (opts.verifier && errors.length === 0) {
+    try {
+      const result = await opts.verifier(proof.address, proof.message, proof.signature);
+      signatureValid = result;
+      if (!result) {
+        errors.push('BIP-322 signature verification failed');
+      }
+    } catch (err) {
+      errors.push(`BIP-322 verifier threw an error: ${err instanceof Error ? err.message : String(err)}`);
+      signatureValid = false;
+    }
+  }
+
+  // Determine overall status
+  let status: BondStatus;
+  if (errors.length > 0) {
+    status = 'invalid';
+  } else if (signatureValid === null) {
+    status = 'unverified';
+  } else if (!fresh) {
+    status = 'stale';
+  } else {
+    status = 'valid';
+  }
+
+  // If there are no structural errors but proof is stale, mark as stale (not invalid)
+  if (errors.length === 0 && signatureValid !== false && !fresh) {
+    status = 'stale';
+  }
+
+  return {
+    status,
+    signatureValid,
+    fresh,
+    ageSecs,
+    meetsThreshold,
+    errors,
+  };
+}
+
+/** Check whether a bond proof is older than the maximum allowed age */
+export function isBondStale(
+  proof: BondProof,
+  maxAgeSecs: number = DEFAULT_BOND_MAX_AGE_SECS,
+  now?: number,
+): boolean {
+  const currentTime = now ?? Math.floor(Date.now() / 1000);
+  return currentTime - proof.timestamp > maxAgeSecs;
+}
+
+/** Serialise a BondProof into Nostr event tags (6 tags) */
+export function bondProofToTags(proof: BondProof): string[][] {
+  return [
+    ['bond-address', proof.address],
+    ['bond-address-type', proof.addressType],
+    ['bond-amount', String(proof.amountSats)],
+    ['bond-timestamp', String(proof.timestamp)],
+    ['bond-message', proof.message],
+    ['bond-signature', proof.signature],
+  ];
+}
+
+/** Parse a BondProof from Nostr event tags, or return null if no bond tags are present */
+export function parseBondProof(event: NostrEvent | { tags: string[][] }): BondProof | null {
+  const address = getTagValue(event as NostrEvent, 'bond-address');
+  if (!address) return null;
+
+  const addressType = getTagValue(event as NostrEvent, 'bond-address-type') as BitcoinAddressType | undefined;
+  const amountStr = getTagValue(event as NostrEvent, 'bond-amount');
+  const timestampStr = getTagValue(event as NostrEvent, 'bond-timestamp');
+  const message = getTagValue(event as NostrEvent, 'bond-message');
+  const signature = getTagValue(event as NostrEvent, 'bond-signature');
+
+  if (!addressType || !amountStr || !timestampStr || !message || !signature) {
+    return null;
+  }
+
+  const amountSats = parseInt(amountStr, 10);
+  const timestamp = parseInt(timestampStr, 10);
+
+  if (isNaN(amountSats) || isNaN(timestamp)) {
+    return null;
+  }
+
+  return {
+    address,
+    addressType,
+    amountSats,
+    timestamp,
+    message,
+    signature,
+  };
+}
+
+/** Check whether a bond proof meets a required amount threshold */
+export function checkBondCompliance(
+  proof: BondProof | null,
+  requiredSats: number,
+): { meets: boolean; reason?: string } {
+  if (!proof) {
+    return { meets: false, reason: 'No bond proof provided' };
+  }
+  if (proof.amountSats < requiredSats) {
+    return {
+      meets: false,
+      reason: `Bond amount ${proof.amountSats} sats is below required ${requiredSats} sats`,
+    };
+  }
+  return { meets: true };
+}

package/src/challenges.ts

@@ -0,0 +1,187 @@
+// Verifier Challenge (kind 31000, type: challenge)
+// Verifier Revocation (kind 31000, type: revocation)
+
+import { createAttestation } from 'nostr-attestations';
+import { parseAttestation } from 'nostr-attestations';
+import { ATTESTATION_KIND, ATTESTATION_TYPES, DEFAULT_REVOCATION_THRESHOLD, DEFAULT_CRYPTO_ALGORITHM } from './constants.js';
+import { signEvent, getPublicKey } from './crypto.js';
+import { getTagValue } from './validation.js';
+import type {
+  NostrEvent,
+  UnsignedEvent,
+  ChallengeParams,
+  RevocationParams,
+  ParsedChallenge,
+  ParsedRevocation,
+  ChallengeReason,
+  BondAction,
+  RevocationScope,
+  SignetTier,
+  CryptoAlgorithm,
+} from './types.js';
+
+// --- Challenge attestation ---
+
+/** Build an unsigned challenge event */
+export function buildChallengeEvent(
+  reporterPubkey: string,
+  params: ChallengeParams
+): UnsignedEvent {
+  const template = createAttestation({
+    type: ATTESTATION_TYPES.CHALLENGE,
+    identifier: params.verifierPubkey,
+    subject: params.verifierPubkey,
+    occurredAt: params.occurredAt,
+    summary: `Challenge: ${params.reason}`,
+    content: params.evidence,
+    tags: [
+      ['reason', params.reason],
+      ['evidence-type', params.evidenceType],
+      ['reporter-tier', String(params.reporterTier)],
+      ['algo', DEFAULT_CRYPTO_ALGORITHM],
+    ],
+  });
+
+  return {
+    ...template,
+    pubkey: reporterPubkey,
+    created_at: Math.floor(Date.now() / 1000),
+  };
+}
+
+/** Create and sign a verifier challenge */
+export async function createChallenge(
+  reporterPrivateKey: string,
+  params: ChallengeParams
+): Promise<NostrEvent> {
+  const pubkey = getPublicKey(reporterPrivateKey);
+  const event = buildChallengeEvent(pubkey, params);
+  return signEvent(event, reporterPrivateKey);
+}
+
+/** Parse a challenge event */
+export function parseChallenge(event: NostrEvent): ParsedChallenge | null {
+  const base = parseAttestation(event);
+  if (!base) return null;
+  if (base.type !== ATTESTATION_TYPES.CHALLENGE) return null;
+
+  const algorithm = (getTagValue(event, 'algo') || DEFAULT_CRYPTO_ALGORITHM) as CryptoAlgorithm;
+  const verifierPubkey = base.identifier ?? '';
+
+  return {
+    verifierPubkey,
+    reason: (getTagValue(event, 'reason') || 'other') as ChallengeReason,
+    evidenceType: getTagValue(event, 'evidence-type') || '',
+    reporterTier: (() => { const t = parseInt(getTagValue(event, 'reporter-tier') || '1', 10); return (t >= 1 && t <= 4 ? t : 1) as SignetTier; })(),
+    algorithm,
+  };
+}
+
+// --- Revocation attestation ---
+
+/** Build an unsigned revocation event */
+export function buildRevocationEvent(
+  authorityPubkey: string,
+  params: RevocationParams
+): UnsignedEvent {
+  const template = createAttestation({
+    type: ATTESTATION_TYPES.REVOCATION,
+    identifier: params.verifierPubkey,
+    subject: params.verifierPubkey,
+    summary: params.summary,
+    content: params.summary,
+    tags: [
+      ['challenge', params.challengeEventId],
+      ['confirmations', String(params.confirmations)],
+      ['bond-action', params.bondAction],
+      ['scope', params.scope],
+      ['effective', String(params.effectiveAt)],
+      ['algo', DEFAULT_CRYPTO_ALGORITHM],
+    ],
+  });
+
+  return {
+    ...template,
+    pubkey: authorityPubkey,
+    created_at: Math.floor(Date.now() / 1000),
+  };
+}
+
+/** Create and sign a verifier revocation */
+export async function createRevocation(
+  authorityPrivateKey: string,
+  params: RevocationParams
+): Promise<NostrEvent> {
+  const pubkey = getPublicKey(authorityPrivateKey);
+  const event = buildRevocationEvent(pubkey, params);
+  return signEvent(event, authorityPrivateKey);
+}
+
+/** Parse a revocation event */
+export function parseRevocation(event: NostrEvent): ParsedRevocation | null {
+  const base = parseAttestation(event);
+  if (!base) return null;
+  if (base.type !== ATTESTATION_TYPES.REVOCATION) return null;
+
+  const algorithm = (getTagValue(event, 'algo') || DEFAULT_CRYPTO_ALGORITHM) as CryptoAlgorithm;
+  const verifierPubkey = base.identifier ?? '';
+
+  return {
+    verifierPubkey,
+    challengeEventId: getTagValue(event, 'challenge') || '',
+    confirmations: (() => { const c = parseInt(getTagValue(event, 'confirmations') || '0', 10); return isNaN(c) || c < 0 ? 0 : c; })(),
+    bondAction: (getTagValue(event, 'bond-action') || 'held') as BondAction,
+    scope: (getTagValue(event, 'scope') || 'full') as RevocationScope,
+    effectiveAt: (() => { const e = parseInt(getTagValue(event, 'effective') || '0', 10); return isNaN(e) ? 0 : e; })(),
+    algorithm,
+  };
+}
+
+/** Count Tier 3+ confirmations for a challenge */
+export function countChallengeConfirmations(
+  challengeEventId: string,
+  confirmationEvents: NostrEvent[],
+  credentialEvents: NostrEvent[]
+): number {
+  // Build a set of Tier 3+ pubkeys
+  const tier3Plus = new Set<string>();
+  for (const cred of credentialEvents) {
+    if (cred.kind !== ATTESTATION_KIND) continue;
+    if (getTagValue(cred, 'type') !== ATTESTATION_TYPES.CREDENTIAL) continue;
+    const tier = getTagValue(cred, 'tier');
+    const tierNum = tier ? parseInt(tier, 10) : NaN;
+    if (!isNaN(tierNum) && tierNum >= 3) {
+      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) tier3Plus.add(subject);
+    }
+  }
+
+  // Count unique Tier 3+ confirmations
+  const confirmedBy = new Set<string>();
+  for (const conf of confirmationEvents) {
+    // Confirmation events reference the challenge
+    const refChallenge = getTagValue(conf, 'challenge');
+    if (refChallenge !== challengeEventId) continue;
+
+    if (tier3Plus.has(conf.pubkey) && !confirmedBy.has(conf.pubkey)) {
+      confirmedBy.add(conf.pubkey);
+    }
+  }
+
+  return confirmedBy.size;
+}
+
+/** Check if a challenge has reached the revocation threshold */
+export function hasReachedRevocationThreshold(
+  confirmations: number,
+  threshold: number = DEFAULT_REVOCATION_THRESHOLD
+): boolean {
+  return confirmations >= threshold;
+}

package/src/cold-call.ts

@@ -0,0 +1,238 @@
+// Cold-Call Verification
+// Allows customers to verify unknown institutional callers via:
+//   .well-known/signet.json — institution publishes its pubkeys
+//   Ephemeral ECDH         — customer generates a one-time keypair
+//   Spoken-token words     — both sides derive the same words independently
+
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import { SignetValidationError } from './errors.js';
+import type { InstitutionKeys } from './types.js';
+import {
+  COLD_CALL_CONTEXT,
+  COLD_CALL_EPOCH_SECONDS,
+  NATO_ALPHABET,
+  WELL_KNOWN_MAX_PUBKEYS,
+  WELL_KNOWN_MAX_SIZE,
+  WELL_KNOWN_PATH,
+} from './constants.js';
+import { deriveWords } from './signet-words.js';
+
+// ── .well-known/signet.json fetching ─────────────────────────────────────────
+
+/**
+ * Fetch and validate an institution's verification keys from `.well-known/signet.json`.
+ *
+ * Always uses HTTPS. Enforces a 10 KB size limit, version 1, at most 20 pubkeys,
+ * and validates that each pubkey is a 64-char lowercase hex string.
+ *
+ * @param domain - The institution's domain (e.g. `'acmelegal.com'`). Do NOT include scheme.
+ * @returns Validated InstitutionKeys object.
+ * @throws {SignetValidationError} If the response is invalid, too large, or fails validation.
+ */
+export async function fetchInstitutionKeys(domain: string): Promise<InstitutionKeys> {
+  const url = `https://${domain}${WELL_KNOWN_PATH}`;
+
+  // Fetch with timeout (throws on network error — caller decides how to handle)
+  const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+  if (!response.ok) {
+    throw new SignetValidationError(`.well-known/signet.json fetch failed: HTTP ${response.status}`);
+  }
+
+  // Early-exit on Content-Length if available (avoids reading large bodies into memory)
+  const contentLength = response.headers.get('content-length');
+  if (contentLength && parseInt(contentLength, 10) > WELL_KNOWN_MAX_SIZE) {
+    throw new SignetValidationError(`.well-known/signet.json exceeds ${WELL_KNOWN_MAX_SIZE} bytes`);
+  }
+
+  const text = await response.text();
+
+  // Enforce size limit (Content-Length may be absent for chunked responses)
+  if (text.length > WELL_KNOWN_MAX_SIZE) {
+    throw new SignetValidationError(`.well-known/signet.json exceeds ${WELL_KNOWN_MAX_SIZE} bytes`);
+  }
+
+  // Parse with runtime type guard
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new SignetValidationError('.well-known/signet.json is not valid JSON');
+  }
+
+  if (typeof data !== 'object' || data === null) {
+    throw new SignetValidationError('.well-known/signet.json must be a JSON object');
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  if (obj['version'] !== 1) {
+    throw new SignetValidationError(`Unsupported signet.json version: ${obj['version']}`);
+  }
+
+  if (!obj['name'] || typeof obj['name'] !== 'string') {
+    throw new SignetValidationError('Missing or invalid name field');
+  }
+
+  if (!Array.isArray(obj['pubkeys']) || (obj['pubkeys'] as unknown[]).length === 0) {
+    throw new SignetValidationError('Missing or empty pubkeys array');
+  }
+
+  const pubkeys = obj['pubkeys'] as unknown[];
+
+  if (pubkeys.length > WELL_KNOWN_MAX_PUBKEYS) {
+    throw new SignetValidationError(`Too many pubkeys (max ${WELL_KNOWN_MAX_PUBKEYS})`);
+  }
+
+  for (const pk of pubkeys) {
+    if (typeof pk !== 'object' || pk === null) {
+      throw new SignetValidationError('Each pubkey entry must be an object');
+    }
+    const entry = pk as Record<string, unknown>;
+    if (typeof entry['pubkey'] !== 'string' || !/^[0-9a-f]{64}$/i.test(entry['pubkey'])) {
+      throw new SignetValidationError(`Invalid pubkey format: ${entry['id'] ?? '(unknown)'}`);
+    }
+  }
+
+  return data as InstitutionKeys;
+}
+
+// ── Session code generation ───────────────────────────────────────────────────
+
+/**
+ * Generate a human-readable session code from an ephemeral pubkey.
+ *
+ * Format: `NATOWORD-NNNN` (e.g. `BRAVO-7742`).
+ * The code is derived deterministically from the SHA-256 of the pubkey bytes.
+ *
+ * @param ephemeralPubkey - 64-char hex x-only secp256k1 public key.
+ * @returns Session code string.
+ * @throws {SignetValidationError} If the pubkey is not 64 hex characters.
+ */
+export function generateSessionCode(ephemeralPubkey: string): string {
+  if (!/^[0-9a-f]{64}$/i.test(ephemeralPubkey)) {
+    throw new SignetValidationError('Invalid ephemeral pubkey format — must be 64-char hex');
+  }
+
+  const hash = sha256(hexToBytes(ephemeralPubkey));
+  const natoIndex = hash[0] % NATO_ALPHABET.length;
+  // Use 5 bytes to derive a 0–9999 digit (avoids bias vs single byte % 10000)
+  const raw = ((hash[1] << 24) | (hash[2] << 16) | (hash[3] << 8) | hash[4]) >>> 0;
+  const digits = raw % 10000;
+  return `${NATO_ALPHABET[natoIndex]}-${digits.toString().padStart(4, '0')}`;
+}
+
+// ── Word derivation ───────────────────────────────────────────────────────────
+
+/**
+ * Derive spoken words from a cold-call ECDH shared secret.
+ *
+ * Uses context `"signet:cold-call"` (domain-separated from the "Signet me"
+ * context `"signet:verify"`), so cold-call and peer-verification words never clash.
+ *
+ * @param ecdhSecret - 32-byte ECDH shared secret (Uint8Array or 64-char hex).
+ * @param counter - Epoch counter (default: current 30-second epoch).
+ * @param wordCount - Number of words to derive (1-16, default 3).
+ * @returns Array of spoken-clarity words.
+ */
+export function deriveColdCallWords(
+  ecdhSecret: Uint8Array | string,
+  counter?: number,
+  wordCount: number = 3,
+): string[] {
+  const currentCounter = counter ?? Math.floor(Date.now() / 1000 / COLD_CALL_EPOCH_SECONDS);
+  return deriveWords(ecdhSecret, currentCounter, wordCount, COLD_CALL_CONTEXT);
+}
+
+// ── ECDH cold-call flow ───────────────────────────────────────────────────────
+
+/** The result of initiating a cold-call verification session. */
+export interface ColdCallSession {
+  /** 64-char hex x-only ephemeral public key — share this with the institution. */
+  ephemeralPubkey: string;
+  /** Human-readable session code derived from the ephemeral pubkey (e.g. `"BRAVO-7742"`). */
+  sessionCode: string;
+  /** Spoken words the customer expects to hear from the institution. */
+  words: string[];
+}
+
+/**
+ * Customer side: generate a fresh ephemeral keypair, perform ECDH with the
+ * institution's pubkey, and derive the expected spoken words.
+ *
+ * The customer MUST share `ephemeralPubkey` (or `sessionCode`) with the institution
+ * so the institution can perform the matching ECDH.
+ *
+ * The shared secret is SHA-256 of the x-coordinate of the ECDH point.
+ *
+ * @param institutionPubkey - 64-char hex x-only secp256k1 pubkey from `.well-known/signet.json`.
+ * @param wordCount - Number of words to derive (default 3).
+ * @returns ColdCallSession with ephemeral pubkey, session code, and expected words.
+ * @throws {SignetCryptoError} If ECDH produces an invalid point.
+ */
+export function initiateColdCallVerification(
+  institutionPubkey: string,
+  wordCount: number = 3,
+): ColdCallSession {
+  // Generate ephemeral keypair
+  const ephPriv = secp256k1.utils.randomSecretKey();
+  const ephPubCompressed = secp256k1.getPublicKey(ephPriv, true); // 33 bytes, 02-prefix
+
+  // ECDH: customer ephemeral private × institution public
+  // getSharedSecret expects a compressed pubkey with 02/03 prefix
+  const sharedPoint = secp256k1.getSharedSecret(ephPriv, hexToBytes('02' + institutionPubkey));
+
+  // Shared secret = SHA-256(x-coordinate of the ECDH point)
+  // sharedPoint is a 65-byte uncompressed point or 33-byte compressed; take bytes [1..33]
+  const xBytes = sharedPoint.slice(1, 33);
+  const sharedSecret = sha256(xBytes);
+
+  // Derive words at the current epoch
+  const words = deriveColdCallWords(sharedSecret, undefined, wordCount);
+
+  // Session code from the ephemeral pubkey (x-only, strip 02 prefix)
+  const ephPubHex = bytesToHex(ephPubCompressed).slice(2);
+  const sessionCode = generateSessionCode(ephPubHex);
+
+  // Zero ephemeral private key bytes (defence-in-depth; GC still owns the buffer)
+  ephPriv.fill(0);
+
+  return { ephemeralPubkey: ephPubHex, sessionCode, words };
+}
+
+/**
+ * Institution side: receive the customer's ephemeral pubkey, perform ECDH with
+ * the institution's own private key, and derive the same spoken words.
+ *
+ * If the institution reads out the returned words and they match what the customer
+ * sees, the caller is verified as genuine.
+ *
+ * @param institutionPrivkey - 64-char hex secp256k1 private key.
+ * @param ephemeralPubkey - 64-char hex x-only ephemeral pubkey from the customer.
+ * @param wordCount - Number of words to derive (must match customer's wordCount, default 3).
+ * @returns Array of spoken words — should match the customer's displayed words.
+ * @throws {SignetCryptoError} If ECDH produces an invalid point.
+ */
+export function completeColdCallVerification(
+  institutionPrivkey: string,
+  ephemeralPubkey: string,
+  wordCount: number = 3,
+): string[] {
+  if (!/^[0-9a-f]{64}$/i.test(institutionPrivkey)) {
+    throw new SignetValidationError('Invalid institution private key format — must be 64-char hex');
+  }
+  if (!/^[0-9a-f]{64}$/i.test(ephemeralPubkey)) {
+    throw new SignetValidationError('Invalid ephemeral pubkey format — must be 64-char hex');
+  }
+
+  // ECDH: institution private × customer ephemeral public
+  const privBytes = hexToBytes(institutionPrivkey);
+  const sharedPoint = secp256k1.getSharedSecret(privBytes, hexToBytes('02' + ephemeralPubkey));
+  privBytes.fill(0);
+
+  const xBytes = sharedPoint.slice(1, 33);
+  const sharedSecret = sha256(xBytes);
+
+  return deriveColdCallWords(sharedSecret, undefined, wordCount);
+}