signet-protocol 0.1.0

package/src/connections.ts

@@ -0,0 +1,216 @@
+// Signet Peer Connection Management
+// ECDH-based shared secret derivation and connection lifecycle
+
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+import { SignetValidationError } from './errors.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface ContactInfo {
+  name?: string;
+  mobile?: string;
+  email?: string;
+  address?: string;
+  childPubkeys?: string[];
+}
+
+/** SECURITY NOTE: sharedSecret is stored as a plain hex string in memory.
+ *  For production use, secrets should be encrypted at rest (e.g. via OS keychain
+ *  or encrypted storage). JS strings cannot be zeroed from memory. */
+export interface Connection {
+  pubkey: string;           // their public key (hex)
+  sharedSecret: string;     // ECDH-derived shared secret (hex, 32 bytes)
+  theirInfo: ContactInfo;   // what they shared with us
+  ourInfo: ContactInfo;     // what we shared with them
+  connectedAt: number;      // unix timestamp
+  method: 'qr-in-person' | 'online';
+}
+
+export interface QRPayload {
+  pubkey: string;           // our public key
+  nonce: string;            // random 32-byte hex for uniqueness
+  info?: ContactInfo;       // optional pre-selected contact info
+}
+
+// ── ECDH ─────────────────────────────────────────────────────────────────────
+
+/** Compute an ECDH shared secret from our private key and their x-only public key.
+ *  The result is the SHA-256 of the x-coordinate of the ECDH point, returned as
+ *  a 32-byte hex string.  The secret is symmetric: A(priv)+B(pub) === B(priv)+A(pub). */
+export function computeSharedSecret(myPrivateKey: string, theirPublicKey: string): string {
+  // Nostr/schnorr public keys are x-only (32 bytes).  To perform ECDH we need
+  // the full compressed point, so we prepend 0x02 (assume even y-coordinate,
+  // per BIP-340 convention used by Nostr).
+  const privBytes = hexToBytes(myPrivateKey);
+  const sharedPoint = secp256k1.getSharedSecret(privBytes, hexToBytes('02' + theirPublicKey));
+  privBytes.fill(0);
+
+  // sharedPoint is 33 bytes (compressed): prefix + x-coordinate.  Take x bytes [1..33].
+  const xBytes = sharedPoint.slice(1, 33);
+  return bytesToHex(sha256(xBytes));
+}
+
+// ── QR Payload ───────────────────────────────────────────────────────────────
+
+/**
+ * Create a QR payload containing our public key and a random nonce.
+ *
+ * **SECURITY WARNING — unencrypted payload:** The returned object is serialised
+ * as cleartext JSON by `serializeQRPayload`.  Any `ContactInfo` embedded in the
+ * payload (name, mobile, email, address, children's public keys) is transmitted
+ * without encryption.  Only display this QR code on trusted screens in
+ * controlled environments.  Do not transmit it over untrusted channels.
+ */
+export function createQRPayload(publicKey: string, info?: ContactInfo): QRPayload {
+  const nonce = bytesToHex(randomBytes(32));
+  const payload: QRPayload = { pubkey: publicKey, nonce };
+  if (info !== undefined) {
+    payload.info = info;
+  }
+  return payload;
+}
+
+/** Serialize a QR payload to a JSON string. */
+export function serializeQRPayload(payload: QRPayload): string {
+  return JSON.stringify(payload);
+}
+
+const MAX_CONTACT_FIELD_LENGTH = 256;
+const MAX_CHILD_PUBKEYS = 20;
+
+/** Validate ContactInfo field sizes to prevent oversized payloads from untrusted sources. */
+function validateContactInfo(info: unknown): void {
+  if (typeof info !== 'object' || info === null) {
+    throw new SignetValidationError('Invalid ContactInfo: must be an object');
+  }
+  const ci = info as Record<string, unknown>;
+  for (const field of ['name', 'mobile', 'email', 'address'] as const) {
+    if (ci[field] !== undefined) {
+      if (typeof ci[field] !== 'string') throw new SignetValidationError(`Invalid ContactInfo: ${field} must be a string`);
+      if ((ci[field] as string).length > MAX_CONTACT_FIELD_LENGTH) {
+        throw new SignetValidationError(`Invalid ContactInfo: ${field} exceeds ${MAX_CONTACT_FIELD_LENGTH} characters`);
+      }
+    }
+  }
+  if (ci.childPubkeys !== undefined) {
+    if (!Array.isArray(ci.childPubkeys)) throw new SignetValidationError('Invalid ContactInfo: childPubkeys must be an array');
+    if (ci.childPubkeys.length > MAX_CHILD_PUBKEYS) {
+      throw new SignetValidationError(`Invalid ContactInfo: childPubkeys exceeds ${MAX_CHILD_PUBKEYS} entries`);
+    }
+    for (const pk of ci.childPubkeys) {
+      if (typeof pk !== 'string' || !/^[0-9a-f]{64}$/i.test(pk)) {
+        throw new SignetValidationError('Invalid ContactInfo: childPubkeys must contain valid 64-char hex pubkeys');
+      }
+    }
+  }
+}
+
+/** Parse and validate a QR payload from a JSON string.
+ *  Throws if the data is not valid JSON or is missing required fields. */
+export function parseQRPayload(data: string): QRPayload {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    throw new SignetValidationError('Invalid QR payload: malformed JSON');
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new SignetValidationError('Invalid QR payload: not an object');
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  if (typeof obj.pubkey !== 'string' || !/^[0-9a-f]{64}$/i.test(obj.pubkey)) {
+    throw new SignetValidationError('Invalid QR payload: pubkey must be a 64-character hex string');
+  }
+  if (typeof obj.nonce !== 'string' || obj.nonce.length < 32 || obj.nonce.length > 128) {
+    throw new SignetValidationError('Invalid QR payload: nonce must be 32-128 hex characters');
+  }
+
+  // Validate ContactInfo field sizes if present
+  if (obj.info !== undefined) {
+    validateContactInfo(obj.info);
+  }
+
+  return parsed as QRPayload;
+}
+
+// ── Connection ───────────────────────────────────────────────────────────────
+
+/** Create a Connection from our private key and a scanned QR payload. */
+export function createConnection(
+  myPrivateKey: string,
+  qrPayload: QRPayload,
+  ourInfo: ContactInfo,
+): Connection {
+  const sharedSecret = computeSharedSecret(myPrivateKey, qrPayload.pubkey);
+  return {
+    pubkey: qrPayload.pubkey,
+    sharedSecret,
+    theirInfo: qrPayload.info ?? {},
+    ourInfo,
+    connectedAt: Math.floor(Date.now() / 1000),
+    method: 'qr-in-person',
+  };
+}
+
+// ── ConnectionStore ──────────────────────────────────────────────────────────
+
+/** Simple in-memory connection manager keyed by remote public key. */
+export class ConnectionStore {
+  private connections: Map<string, Connection> = new Map();
+
+  /** Add a connection. If a connection with the same pubkey already exists it is replaced. */
+  add(connection: Connection): void {
+    this.connections.set(connection.pubkey, connection);
+  }
+
+  /** Get a connection by remote public key. */
+  get(pubkey: string): Connection | undefined {
+    return this.connections.get(pubkey);
+  }
+
+  /** List all connections. */
+  list(): Connection[] {
+    return Array.from(this.connections.values());
+  }
+
+  /** Remove a connection by remote public key. Returns true if a connection was removed. */
+  remove(pubkey: string): boolean {
+    return this.connections.delete(pubkey);
+  }
+
+  /** Check whether a connection for the given public key exists. */
+  has(pubkey: string): boolean {
+    return this.connections.has(pubkey);
+  }
+
+  /** Export all connections as an array (for serialization). */
+  export(): Connection[] {
+    return this.list();
+  }
+
+  /** Import connections from an array, replacing any existing connections with the same pubkey. */
+  import(connections: Connection[]): void {
+    for (const conn of connections) {
+      if (!conn || typeof conn !== 'object') continue;
+      if (typeof conn.pubkey !== 'string' || !/^[0-9a-f]{64}$/i.test(conn.pubkey)) continue;
+      if (typeof conn.sharedSecret !== 'string' || !/^[0-9a-f]{64}$/i.test(conn.sharedSecret)) continue;
+      if (typeof conn.connectedAt !== 'number' || conn.connectedAt <= 0) continue;
+      if (typeof conn.theirInfo !== 'object' || conn.theirInfo === null) continue;
+      if (typeof conn.ourInfo !== 'object' || conn.ourInfo === null) continue;
+      if (conn.method !== 'qr-in-person' && conn.method !== 'online') continue;
+      // Validate ContactInfo field sizes to prevent oversized data from untrusted sources
+      try {
+        validateContactInfo(conn.theirInfo);
+        validateContactInfo(conn.ourInfo);
+      } catch {
+        continue;
+      }
+      this.connections.set(conn.pubkey, conn);
+    }
+  }
+}

package/src/constants.ts

@@ -0,0 +1,146 @@
+// Signet Protocol Constants
+import { ATTESTATION_KIND } from 'nostr-attestations';
+
+/** Generic Verifiable Attestation kind (NIP-VA, kind 31000) */
+export { ATTESTATION_KIND };
+
+/** NIP-78 App-specific Data kind (existing Nostr kind) */
+export const APP_DATA_KIND = 30078;
+
+/** Attestation type identifiers */
+export const ATTESTATION_TYPES = {
+  CREDENTIAL: 'credential',
+  VOUCH: 'vouch',
+  VERIFIER: 'verifier',
+  CHALLENGE: 'challenge',
+  REVOCATION: 'revocation',
+  IDENTITY_BRIDGE: 'identity-bridge',
+  DELEGATION: 'delegation',
+} as const;
+
+/** @deprecated — use ATTESTATION_KIND + ATTESTATION_TYPES instead */
+export const SIGNET_KINDS = {
+  CREDENTIAL: ATTESTATION_KIND,
+  VOUCH: ATTESTATION_KIND,
+  POLICY: APP_DATA_KIND,
+  VERIFIER: ATTESTATION_KIND,
+  CHALLENGE: ATTESTATION_KIND,
+  REVOCATION: ATTESTATION_KIND,
+  IDENTITY_BRIDGE: ATTESTATION_KIND,
+  DELEGATION: ATTESTATION_KIND,
+} as const;
+
+/**
+ * @deprecated NIP-VA labels are now auto-generated by nostr-attestations.
+ * Kept for backwards compatibility with parsers consuming legacy events.
+ */
+export const SIGNET_LABEL = 'signet';
+
+/** Default number of vouches needed for Tier 2 */
+export const DEFAULT_VOUCH_THRESHOLD = 3;
+
+/** Default minimum tier of vouchers for Tier 2 */
+export const DEFAULT_VOUCHER_MIN_TIER = 2;
+
+/** Default credential expiry: 2 years in seconds */
+export const DEFAULT_CREDENTIAL_EXPIRY_SECONDS = 2 * 365 * 24 * 60 * 60;
+
+/** Default number of Tier 3+ confirmations to revoke a verifier */
+export const DEFAULT_REVOCATION_THRESHOLD = 5;
+
+/** Minimum cross-verification requirements for verifier activation */
+export const VERIFIER_ACTIVATION = {
+  MIN_VOUCHES: 2,
+  MIN_PROFESSIONS: 2,
+} as const;
+
+/** Signet Score weights (default implementation, 0-200 scale) */
+export const TRUST_WEIGHTS = {
+  PROFESSIONAL_VERIFICATION: 80,
+  IN_PERSON_VOUCH: 16,
+  ONLINE_VOUCH: 4,
+  ACCOUNT_AGE_PER_YEAR: 10,
+  ACCOUNT_AGE_MAX: 30,
+  IDENTITY_BRIDGE: 50,
+} as const;
+
+/** Minimum ring size for identity bridges (anonymity threshold) */
+export const MIN_BRIDGE_RING_SIZE = 5;
+
+/** Maximum Signet Score */
+export const MAX_TRUST_SCORE = 200;
+
+/** Valid entity types */
+export const ENTITY_TYPES = [
+  'natural_person',
+  'persona',
+  'personal_agent',
+  'unlinked_personal_agent',
+  'juridical_person',
+  'juridical_persona',
+  'organised_agent',
+  'unlinked_organised_agent',
+  'unlinked_agent',
+] as const;
+
+/** Valid delegation owner → agent type mappings */
+export const DELEGATION_CONSTRAINTS: Record<string, string> = {
+  natural_person: 'personal_agent',
+  persona: 'unlinked_personal_agent',
+  juridical_person: 'organised_agent',
+  juridical_persona: 'unlinked_organised_agent',
+};
+
+/** App-friendly labels for entity types */
+export const ENTITY_LABELS: Record<string, string> = {
+  natural_person: 'Person',
+  persona: 'Alias',
+  personal_agent: 'Personal Agent',
+  unlinked_personal_agent: 'Unlinked Personal Agent',
+  juridical_person: 'Organisation',
+  juridical_persona: 'Org Alias',
+  organised_agent: 'Organised Agent',
+  unlinked_organised_agent: 'Unlinked Org Agent',
+  unlinked_agent: 'Unlinked Agent',
+};
+
+/** Domain separator for bond proof messages */
+export const BOND_DOMAIN_SEPARATOR = 'signet:bond';
+
+/** Default maximum age for bond proofs: 30 days in seconds */
+export const DEFAULT_BOND_MAX_AGE_SECS = 30 * 24 * 60 * 60;
+
+/** Valid Bitcoin address types for bond proofs */
+export const VALID_BOND_ADDRESS_TYPES = ['p2wpkh', 'p2sh', 'p2tr', 'p2pkh'] as const;
+
+/** Default asymmetric cryptographic algorithm (Nostr standard secp256k1).
+ * Tagged on events so future parsers can distinguish pre- and post-quantum events. */
+export const DEFAULT_CRYPTO_ALGORITHM = 'secp256k1' as const;
+
+/** Cold-call verification constants */
+export const COLD_CALL_CONTEXT = 'signet:cold-call';
+export const COLD_CALL_EPOCH_SECONDS = 30;
+export const COLD_CALL_TOLERANCE = 1;           // ±1 epoch
+export const WELL_KNOWN_PATH = '/.well-known/signet.json';
+export const WELL_KNOWN_MAX_SIZE = 10240;       // 10 KB
+export const WELL_KNOWN_MAX_PUBKEYS = 20;
+export const WELL_KNOWN_MAX_CACHE_HOURS = 24;
+export const SESSION_CODE_EXPIRY_SECONDS = 300; // 5 minutes
+
+/** NATO phonetic alphabet for session codes */
+export const NATO_ALPHABET = [
+  'ALFA', 'BRAVO', 'CHARLIE', 'DELTA', 'ECHO', 'FOXTROT',
+  'GOLF', 'HOTEL', 'INDIA', 'JULIET', 'KILO', 'LIMA',
+  'MIKE', 'NOVEMBER', 'OSCAR', 'PAPA', 'QUEBEC', 'ROMEO',
+  'SIERRA', 'TANGO', 'UNIFORM', 'VICTOR', 'WHISKEY',
+  'XRAY', 'YANKEE', 'ZULU',
+] as const;
+
+/** Signal ordering (protocol-mandated) */
+export const SIGNAL_PRIORITY = [
+  'professional-verification',
+  'identity-bridge',
+  'in-person-vouch',
+  'online-vouch',
+  'account-age',
+] as const;