holosphere 2.0.0-alpha2 → 2.0.0-alpha4

package/src/crypto/nostr-utils.js

@@ -0,0 +1,263 @@
+/**
+ * Nostr Utility Functions
+ *
+ * Provides browser-compatible utilities for Nostr key handling and NIP-04 encryption.
+ * Apps can use these without directly importing nostr-tools.
+ */
+
+import { nip04, nip19, getPublicKey as nostrGetPublicKey, finalizeEvent, verifyEvent as nostrVerifyEvent } from 'nostr-tools';
+
+// ============================================================================
+// Key Conversion Utilities
+// ============================================================================
+
+/**
+ * Convert hex string to Uint8Array
+ * @param {string} hex - Hex string
+ * @returns {Uint8Array} Byte array
+ */
+export function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert Uint8Array to hex string
+ * @param {Uint8Array} bytes - Byte array
+ * @returns {string} Hex string
+ */
+export function bytesToHex(bytes) {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Parse an npub or hex public key string into hex format
+ * @param {string} input - npub (npub1...) or hex public key
+ * @returns {{ valid: boolean, hexPubKey?: string, error?: string }}
+ */
+export function parseNpubOrHex(input) {
+  const trimmed = input?.trim();
+
+  if (!trimmed) {
+    return { valid: false, error: 'Public key is required' };
+  }
+
+  // Check if it's already hex (64 characters)
+  if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    return { valid: true, hexPubKey: trimmed.toLowerCase() };
+  }
+
+  // Handle nostr: URI prefix
+  let npubString = trimmed;
+  if (npubString.startsWith('nostr:')) {
+    npubString = npubString.slice(6);
+  }
+
+  // Try to decode as npub
+  if (npubString.startsWith('npub1')) {
+    try {
+      const decoded = nip19.decode(npubString);
+      if (decoded.type === 'npub') {
+        return { valid: true, hexPubKey: decoded.data };
+      }
+      return { valid: false, error: 'Invalid npub format' };
+    } catch (e) {
+      return { valid: false, error: 'Invalid npub: unable to decode' };
+    }
+  }
+
+  return { valid: false, error: 'Enter a valid npub (npub1...) or 64-character hex public key' };
+}
+
+/**
+ * Convert a hex public key to npub format
+ * @param {string} hexPubKey - Hex public key (64 chars)
+ * @returns {string} npub string
+ */
+export function hexToNpub(hexPubKey) {
+  try {
+    return nip19.npubEncode(hexPubKey);
+  } catch (e) {
+    console.error('Failed to encode hex to npub:', e);
+    return hexPubKey; // Return original on error
+  }
+}
+
+/**
+ * Convert npub to hex public key
+ * @param {string} npub - npub string
+ * @returns {string|null} Hex public key or null if invalid
+ */
+export function npubToHex(npub) {
+  try {
+    const decoded = nip19.decode(npub);
+    if (decoded.type === 'npub') {
+      return decoded.data;
+    }
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Shorten a public key for display (first 8 and last 8 chars)
+ * @param {string} pubKey - Public key (hex or npub)
+ * @returns {string} Shortened key
+ */
+export function shortenPubKey(pubKey) {
+  if (!pubKey || pubKey.length <= 20) return pubKey || '';
+  return `${pubKey.slice(0, 8)}...${pubKey.slice(-8)}`;
+}
+
+/**
+ * Shorten an npub for display
+ * @param {string} npub - npub string
+ * @returns {string} Shortened npub
+ */
+export function shortenNpub(npub) {
+  if (!npub || npub.length <= 20) return npub || '';
+  return `${npub.slice(0, 12)}...${npub.slice(-8)}`;
+}
+
+/**
+ * Get public key from private key (matches nostr-tools API)
+ * @param {string} privateKey - Hex private key
+ * @returns {string} Hex public key
+ */
+export function getPublicKey(privateKey) {
+  return nostrGetPublicKey(hexToBytes(privateKey));
+}
+
+// ============================================================================
+// NIP-04 Encryption
+// ============================================================================
+
+/**
+ * Encrypt a message using NIP-04 (for DMs)
+ * @param {string} privateKey - Sender's hex private key
+ * @param {string} recipientPubKey - Recipient's hex public key
+ * @param {string} content - Plain text content
+ * @returns {Promise<string>} Encrypted content
+ */
+export async function encryptNIP04(privateKey, recipientPubKey, content) {
+  return await nip04.encrypt(privateKey, recipientPubKey, content);
+}
+
+/**
+ * Decrypt a NIP-04 encrypted message
+ * @param {string} privateKey - Recipient's hex private key
+ * @param {string} senderPubKey - Sender's hex public key
+ * @param {string} encryptedContent - Encrypted content
+ * @returns {Promise<string>} Decrypted content
+ */
+export async function decryptNIP04(privateKey, senderPubKey, encryptedContent) {
+  return await nip04.decrypt(privateKey, senderPubKey, encryptedContent);
+}
+
+// ============================================================================
+// Event Creation
+// ============================================================================
+
+/**
+ * Create and sign a Nostr event
+ * @param {number} kind - Event kind
+ * @param {string} content - Event content
+ * @param {string[][]} tags - Event tags
+ * @param {string} privateKey - Hex private key for signing
+ * @returns {Object} Signed Nostr event
+ */
+export function createSignedEvent(kind, content, tags, privateKey) {
+  const event = {
+    kind,
+    content,
+    tags,
+    created_at: Math.floor(Date.now() / 1000),
+  };
+
+  return finalizeEvent(event, hexToBytes(privateKey));
+}
+
+/**
+ * Create a NIP-04 encrypted DM event (kind 4)
+ * @param {string} recipientPubKey - Recipient's hex public key
+ * @param {string} encryptedContent - NIP-04 encrypted content
+ * @param {string} privateKey - Sender's hex private key
+ * @returns {Object} Signed DM event
+ */
+export function createDMEvent(recipientPubKey, encryptedContent, privateKey) {
+  return createSignedEvent(
+    4, // NIP-04 encrypted DM
+    encryptedContent,
+    [['p', recipientPubKey]],
+    privateKey
+  );
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Check if a string is a valid hex public key
+ * @param {string} str - String to check
+ * @returns {boolean}
+ */
+export function isValidHexPubKey(str) {
+  return typeof str === 'string' && /^[0-9a-fA-F]{64}$/.test(str);
+}
+
+/**
+ * Check if a string is a valid npub
+ * @param {string} str - String to check
+ * @returns {boolean}
+ */
+export function isValidNpub(str) {
+  if (typeof str !== 'string' || !str.startsWith('npub1')) {
+    return false;
+  }
+  try {
+    const decoded = nip19.decode(str);
+    return decoded.type === 'npub';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate a unique nonce
+ * @returns {string} Unique nonce
+ */
+export function generateNonce() {
+  return Date.now().toString(36) + Math.random().toString(36).substring(2, 15);
+}
+
+/**
+ * Sign a Nostr event (alias for createSignedEvent that accepts event object)
+ * @param {Object} event - Unsigned event object with kind, content, tags
+ * @param {string} privateKey - Hex private key for signing
+ * @returns {Object} Signed Nostr event
+ */
+export function signEvent(event, privateKey) {
+  const eventToSign = {
+    kind: event.kind,
+    content: event.content,
+    tags: event.tags || [],
+    created_at: event.created_at || Math.floor(Date.now() / 1000),
+  };
+  return finalizeEvent(eventToSign, hexToBytes(privateKey));
+}
+
+/**
+ * Verify a Nostr event signature
+ * @param {Object} event - Signed Nostr event to verify
+ * @returns {boolean} True if signature is valid
+ */
+export function verifyEvent(event) {
+  return nostrVerifyEvent(event);
+}

package/src/federation/handshake.js

@@ -0,0 +1,455 @@
+/**
+ * Federation Handshake Protocol
+ *
+ * Uses NIP-04 encrypted DMs (kind 4) for bidirectional federation request/response.
+ * When user A federates with user B's pubkey, a DM is sent to B.
+ * B can accept/reject, creating a matching federation on their side.
+ */
+
+import {
+  encryptNIP04,
+  decryptNIP04,
+  createDMEvent,
+  hexToNpub,
+  generateNonce,
+} from '../crypto/nostr-utils.js';
+import { addFederatedPartner, storeInboundCapability } from './registry.js';
+
+// ============================================================================
+// Types (documented for reference)
+// ============================================================================
+
+/**
+ * @typedef {Object} FederationRequestPayload
+ * @property {'federation_request'} type
+ * @property {'1.0'} version
+ * @property {string} requestId - Unique request ID
+ * @property {number} timestamp
+ * @property {string} senderHolonId - Holon ID of the sender
+ * @property {string} senderHolonName - Human-readable holon name
+ * @property {string} senderNpub - Sender's npub
+ * @property {Object} lensConfig - Lens configuration
+ * @property {string[]} lensConfig.inbound - Lenses sender will accept
+ * @property {string[]} lensConfig.outbound - Lenses sender will share
+ * @property {Array} capabilities - Capability tokens
+ * @property {string} [message] - Optional personal message
+ */
+
+/**
+ * @typedef {Object} FederationResponsePayload
+ * @property {'federation_response'} type
+ * @property {'1.0'} version
+ * @property {string} requestId - References original request
+ * @property {number} timestamp
+ * @property {'accepted'|'rejected'} status
+ * @property {string} [responderHolonId]
+ * @property {string} [responderHolonName]
+ * @property {string} [responderNpub]
+ * @property {Object} [lensConfig]
+ * @property {Array} [capabilities]
+ * @property {string} [message]
+ */
+
+// ============================================================================
+// Request/Response Creation
+// ============================================================================
+
+/**
+ * Create a federation request payload
+ * @param {Object} params
+ * @param {string} params.senderHolonId
+ * @param {string} params.senderHolonName
+ * @param {string} params.senderPubKey - Hex public key
+ * @param {Object} params.lensConfig - { inbound: string[], outbound: string[] }
+ * @param {Array} [params.capabilities] - Capability tokens to include
+ * @param {string} [params.message] - Optional message
+ * @returns {FederationRequestPayload}
+ */
+export function createFederationRequest({
+  senderHolonId,
+  senderHolonName,
+  senderPubKey,
+  lensConfig = { inbound: [], outbound: [] },
+  capabilities = [],
+  message,
+}) {
+  return {
+    type: 'federation_request',
+    version: '1.0',
+    requestId: generateNonce(),
+    timestamp: Date.now(),
+    senderHolonId,
+    senderHolonName,
+    senderNpub: hexToNpub(senderPubKey),
+    lensConfig,
+    capabilities,
+    message,
+  };
+}
+
+/**
+ * Create a federation response payload
+ * @param {Object} params
+ * @param {string} params.requestId - Original request ID
+ * @param {'accepted'|'rejected'} params.status
+ * @param {string} [params.responderHolonId]
+ * @param {string} [params.responderHolonName]
+ * @param {string} [params.responderPubKey] - Hex public key
+ * @param {Object} [params.lensConfig]
+ * @param {Array} [params.capabilities]
+ * @param {string} [params.message]
+ * @returns {FederationResponsePayload}
+ */
+export function createFederationResponse({
+  requestId,
+  status,
+  responderHolonId,
+  responderHolonName,
+  responderPubKey,
+  lensConfig,
+  capabilities,
+  message,
+}) {
+  return {
+    type: 'federation_response',
+    version: '1.0',
+    requestId,
+    timestamp: Date.now(),
+    status,
+    responderHolonId,
+    responderHolonName,
+    responderNpub: responderPubKey ? hexToNpub(responderPubKey) : undefined,
+    lensConfig,
+    capabilities,
+    message,
+  };
+}
+
+// ============================================================================
+// DM Sending
+// ============================================================================
+
+/**
+ * Send a federation request DM
+ * @param {Object} client - NostrClient instance with publish method
+ * @param {string} privateKey - Sender's hex private key
+ * @param {string} recipientPubKey - Recipient's hex public key
+ * @param {FederationRequestPayload} request - Request payload
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function sendFederationRequest(client, privateKey, recipientPubKey, request) {
+  try {
+    const content = JSON.stringify(request);
+    const encrypted = await encryptNIP04(privateKey, recipientPubKey, content);
+    const event = createDMEvent(recipientPubKey, encrypted, privateKey);
+
+    if (client?.publish) {
+      await client.publish(event);
+      console.log('[Handshake] Federation request sent to:', recipientPubKey.substring(0, 8) + '...');
+      return true;
+    } else {
+      console.error('[Handshake] No publish method on client');
+      return false;
+    }
+  } catch (error) {
+    console.error('[Handshake] Failed to send federation request:', error);
+    return false;
+  }
+}
+
+/**
+ * Send a federation response DM
+ * @param {Object} client - NostrClient instance with publish method
+ * @param {string} privateKey - Sender's hex private key
+ * @param {string} recipientPubKey - Recipient's hex public key
+ * @param {FederationResponsePayload} response - Response payload
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function sendFederationResponse(client, privateKey, recipientPubKey, response) {
+  try {
+    const content = JSON.stringify(response);
+    const encrypted = await encryptNIP04(privateKey, recipientPubKey, content);
+    const event = createDMEvent(recipientPubKey, encrypted, privateKey);
+
+    if (client?.publish) {
+      await client.publish(event);
+      console.log('[Handshake] Federation response sent to:', recipientPubKey.substring(0, 8) + '...');
+      return true;
+    } else {
+      console.error('[Handshake] No publish method on client');
+      return false;
+    }
+  } catch (error) {
+    console.error('[Handshake] Failed to send federation response:', error);
+    return false;
+  }
+}
+
+// ============================================================================
+// DM Subscription
+// ============================================================================
+
+/**
+ * Subscribe to incoming federation DMs
+ * @param {Object} client - NostrClient instance with subscribe method
+ * @param {string} privateKey - Recipient's hex private key
+ * @param {string} publicKey - Recipient's hex public key
+ * @param {Object} handlers
+ * @param {Function} handlers.onRequest - Called with (request, senderPubKey)
+ * @param {Function} handlers.onResponse - Called with (response, senderPubKey)
+ * @returns {Function} Unsubscribe function
+ */
+export function subscribeToFederationDMs(client, privateKey, publicKey, handlers) {
+  const { onRequest, onResponse } = handlers;
+  let isActive = true;
+  const processedEventIds = new Set();
+
+  const handleEvent = async (event) => {
+    if (!isActive) return;
+
+    // Skip duplicates
+    if (processedEventIds.has(event.id)) return;
+    processedEventIds.add(event.id);
+
+    // Only kind 4 (encrypted DM) events tagged to us
+    if (event.kind !== 4) return;
+
+    const pTag = event.tags?.find((t) => t[0] === 'p');
+    if (!pTag || pTag[1] !== publicKey) return;
+
+    try {
+      const decrypted = await decryptNIP04(privateKey, event.pubkey, event.content);
+      const payload = JSON.parse(decrypted);
+
+      if (payload.type === 'federation_request' && payload.version === '1.0') {
+        console.log('[Handshake] Received federation request from:', event.pubkey.substring(0, 8) + '...');
+        onRequest?.(payload, event.pubkey);
+      } else if (payload.type === 'federation_response' && payload.version === '1.0') {
+        console.log('[Handshake] Received federation response from:', event.pubkey.substring(0, 8) + '...');
+        onResponse?.(payload, event.pubkey);
+      }
+    } catch (error) {
+      // Silently ignore non-federation DMs
+    }
+  };
+
+  // Subscribe via client
+  // Note: client is the HoloSphere instance, client.client is the NostrClient
+  let subscription = null;
+
+  const startSubscription = async () => {
+    // Get the NostrClient from HoloSphere instance
+    const nostrClient = client?.client;
+    if (!nostrClient?.subscribe) {
+      console.warn('[Handshake] No NostrClient subscribe method available');
+      return;
+    }
+
+    const filter = {
+      kinds: [4],
+      '#p': [publicKey],
+      since: Math.floor(Date.now() / 1000) - 86400, // Last 24 hours
+    };
+
+    try {
+      // NostrClient.subscribe(filter, onEvent, options) returns { unsubscribe }
+      subscription = await nostrClient.subscribe(filter, handleEvent, {});
+      console.log('[Handshake] Federation DM subscription started');
+    } catch (error) {
+      console.error('[Handshake] Failed to subscribe:', error);
+    }
+  };
+
+  startSubscription();
+
+  // Return unsubscribe function
+  return () => {
+    isActive = false;
+    if (subscription?.unsubscribe) {
+      subscription.unsubscribe();
+    } else if (subscription?.close) {
+      subscription.close();
+    }
+  };
+}
+
+// ============================================================================
+// High-Level Handshake Operations
+// ============================================================================
+
+/**
+ * Initiate a federation handshake with a partner
+ * Creates local federation record and sends DM to partner
+ * @param {Object} holosphere - HoloSphere instance
+ * @param {string} privateKey - Sender's hex private key
+ * @param {Object} params
+ * @param {string} params.partnerPubKey - Partner's hex public key
+ * @param {string} params.holonId - Current holon ID
+ * @param {string} params.holonName - Current holon name
+ * @param {Object} [params.lensConfig] - Lens configuration
+ * @param {string} [params.message] - Optional message
+ * @returns {Promise<{ success: boolean, requestId?: string, error?: string }>}
+ */
+export async function initiateFederationHandshake(holosphere, privateKey, params) {
+  const {
+    partnerPubKey,
+    holonId,
+    holonName,
+    lensConfig = { inbound: [], outbound: [] },
+    message,
+  } = params;
+
+  try {
+    // Get sender's public key
+    const { getPublicKeyFromPrivate } = await import('../crypto/nostr-utils.js');
+    const senderPubKey = getPublicKeyFromPrivate(privateKey);
+
+    // Create federation request
+    const request = createFederationRequest({
+      senderHolonId: holonId,
+      senderHolonName: holonName,
+      senderPubKey,
+      lensConfig,
+      capabilities: [],
+      message,
+    });
+
+    // Add partner to local registry (status: pending)
+    if (holosphere.client) {
+      await addFederatedPartner(holosphere.client, holosphere.config.appName, partnerPubKey, {
+        alias: null,
+        addedVia: 'handshake_initiated',
+      });
+    }
+
+    // Send DM to partner
+    const sent = await sendFederationRequest(holosphere.client, privateKey, partnerPubKey, request);
+
+    if (sent) {
+      return { success: true, requestId: request.requestId };
+    } else {
+      return { success: false, error: 'Failed to send DM' };
+    }
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Accept a federation request
+ * Creates local federation record and sends acceptance DM
+ * @param {Object} holosphere - HoloSphere instance
+ * @param {string} privateKey - Responder's hex private key
+ * @param {Object} params
+ * @param {FederationRequestPayload} params.request - Original request
+ * @param {string} params.senderPubKey - Original sender's public key
+ * @param {string} params.holonId - Current holon ID
+ * @param {string} params.holonName - Current holon name
+ * @param {Object} [params.lensConfig] - Our lens configuration
+ * @param {string} [params.message] - Optional message
+ * @returns {Promise<{ success: boolean, error?: string }>}
+ */
+export async function acceptFederationRequest(holosphere, privateKey, params) {
+  const {
+    request,
+    senderPubKey,
+    holonId,
+    holonName,
+    lensConfig = { inbound: [], outbound: [] },
+    message,
+  } = params;
+
+  try {
+    // Get responder's public key
+    const { getPublicKeyFromPrivate } = await import('../crypto/nostr-utils.js');
+    const responderPubKey = getPublicKeyFromPrivate(privateKey);
+
+    // Add sender as federated partner
+    if (holosphere.client) {
+      await addFederatedPartner(holosphere.client, holosphere.config.appName, senderPubKey, {
+        alias: request.senderHolonName,
+        addedVia: 'handshake_accepted',
+      });
+
+      // Store any capabilities they sent
+      if (request.capabilities && request.capabilities.length > 0) {
+        for (const cap of request.capabilities) {
+          await storeInboundCapability(holosphere.client, holosphere.config.appName, senderPubKey, cap);
+        }
+      }
+    }
+
+    // Create and send response
+    const response = createFederationResponse({
+      requestId: request.requestId,
+      status: 'accepted',
+      responderHolonId: holonId,
+      responderHolonName: holonName,
+      responderPubKey,
+      lensConfig,
+      capabilities: [],
+      message,
+    });
+
+    const sent = await sendFederationResponse(holosphere.client, privateKey, senderPubKey, response);
+
+    if (sent) {
+      return { success: true };
+    } else {
+      return { success: false, error: 'Failed to send response DM' };
+    }
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Reject a federation request
+ * Sends rejection DM without creating local federation
+ * @param {Object} holosphere - HoloSphere instance
+ * @param {string} privateKey - Responder's hex private key
+ * @param {Object} params
+ * @param {string} params.requestId - Original request ID
+ * @param {string} params.senderPubKey - Original sender's public key
+ * @param {string} [params.message] - Optional rejection message
+ * @returns {Promise<{ success: boolean, error?: string }>}
+ */
+export async function rejectFederationRequest(holosphere, privateKey, params) {
+  const { requestId, senderPubKey, message } = params;
+
+  try {
+    const response = createFederationResponse({
+      requestId,
+      status: 'rejected',
+      message,
+    });
+
+    const sent = await sendFederationResponse(holosphere.client, privateKey, senderPubKey, response);
+
+    return { success: sent, error: sent ? undefined : 'Failed to send response DM' };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+// ============================================================================
+// Payload Validation
+// ============================================================================
+
+/**
+ * Check if payload is a federation request
+ * @param {any} payload
+ * @returns {payload is FederationRequestPayload}
+ */
+export function isFederationRequest(payload) {
+  return payload?.type === 'federation_request' && payload?.version === '1.0';
+}
+
+/**
+ * Check if payload is a federation response
+ * @param {any} payload
+ * @returns {payload is FederationResponsePayload}
+ */
+export function isFederationResponse(payload) {
+  return payload?.type === 'federation_response' && payload?.version === '1.0';
+}