holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/federation/handshake.js

@@ -0,0 +1,475 @@
+/**
+ * Federation Handshake Protocol
+ *
+ * Uses NIP-44 encrypted DMs (kind 4) for bidirectional federation request/response.
+ * Falls back to NIP-04 for backward compatibility when receiving messages.
+ * 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 {
+  encryptNIP44,
+  decryptNIP44,
+  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 = encryptNIP44(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 = encryptNIP44(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 {
+      let decrypted;
+
+      // Try NIP-44 first (modern encryption)
+      try {
+        decrypted = decryptNIP44(privateKey, event.pubkey, event.content);
+      } catch (nip44Error) {
+        // Fall back to NIP-04 for backward compatibility with older clients
+        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<Object>} Result with success, requestId (if successful), error (if failed)
+ */
+export async function initiateFederationHandshake(holosphere, privateKey, params) {
+  const {
+    partnerPubKey,
+    holonId,
+    holonName,
+    lensConfig = { inbound: [], outbound: [] },
+    message,
+  } = params;
+
+  try {
+    // Get sender's public key
+    const { getPublicKey } = await import('../crypto/nostr-utils.js');
+    const senderPubKey = getPublicKey(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<Object>} Result with success and optional error
+ */
+export async function acceptFederationRequest(holosphere, privateKey, params) {
+  const {
+    request,
+    senderPubKey,
+    holonId,
+    holonName,
+    lensConfig = { inbound: [], outbound: [] },
+    message,
+  } = params;
+
+  try {
+    // Get responder's public key
+    const { getPublicKey } = await import('../crypto/nostr-utils.js');
+    const responderPubKey = getPublicKey(privateKey);
+
+    // Add sender as federated partner in Nostr registry
+    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 the actual federation record in GunDB storage
+    // This is what makes the partner appear in getFederation() / loadFederationData()
+    // Store the sender's name so we can display it without reading their settings
+    await holosphere.federateHolon(holonId, senderPubKey, {
+      lensConfig,
+      partnerName: request.senderHolonName
+    });
+
+    // 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<Object>} Result with success and optional error
+ */
+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 {*} payload - Payload to check
+ * @returns {boolean} True if payload is a FederationRequestPayload
+ */
+export function isFederationRequest(payload) {
+  return payload?.type === 'federation_request' && payload?.version === '1.0';
+}
+
+/**
+ * Check if payload is a federation response
+ * @param {*} payload - Payload to check
+ * @returns {boolean} True if payload is a FederationResponsePayload
+ */
+export function isFederationResponse(payload) {
+  return payload?.type === 'federation_response' && payload?.version === '1.0';
+}

package/src/federation/hologram.js

@@ -1,11 +1,19 @@
 /**
- * Federation and Hologram (reference) Management
+ * @fileoverview Federation and Hologram (Reference) Management.
+ *
+ * Provides hologram (lightweight reference) creation, resolution, and management.
+ * Holograms enable data to appear in multiple holons while maintaining a single
+ * source of truth. Supports circular reference detection and cross-holosphere
+ * federation with capability-based access control.
+ *
+ * @module federation/hologram
  */
 
-import { buildPath, write, read, update } from '../storage/nostr-wrapper.js';
+import { buildPath, write, read, update } from '../storage/unified-storage.js';
 import { verifyCapability } from '../crypto/secp256k1.js';
 import { getCapabilityForAuthor } from './registry.js';
 
+/** @constant {number} Maximum depth for hologram resolution chain */
 const MAX_RESOLUTION_DEPTH = 10;
 
 /**
@@ -652,7 +660,8 @@ export async function addActiveHologram(client, appname, sourceHolon, lensName,
     sourceData._meta.activeHolograms.push({
       targetHolon,
       created: now,
-      lastUpdated: now
+      lastUpdated: now,
+      platforms: {}  // Platform-specific data (e.g., telegram: { messageId: 123 })
     });
   }
 
@@ -718,6 +727,111 @@ export async function removeActiveHologram(client, appname, sourceHolon, lensNam
   return false;
 }
 
+/**
+ * Update platform-specific data for an active hologram entry
+ * Used by platform clients (Telegram, Discord, etc.) to store their message IDs
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} targetHolon - Target holon ID
+ * @param {string} platform - Platform name (e.g., 'telegram', 'discord')
+ * @param {Object} platformData - Platform-specific data (e.g., { messageId: 123 })
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateActiveHologramPlatform(client, appname, sourceHolon, lensName, dataId, targetHolon, platform, platformData) {
+  let currentAppname = appname;
+  let currentHolon = sourceHolon;
+  let currentLens = lensName;
+  let currentDataId = dataId;
+  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+
+  // Read existing source data
+  let sourceData = await read(client, sourcePath);
+  if (!sourceData) {
+    console.warn(`Source data not found at ${sourcePath}`);
+    return false;
+  }
+
+  // If source is a hologram, follow the chain to find the real source
+  let depth = 0;
+  const maxDepth = 10;
+  while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
+    depth++;
+    currentAppname = sourceData.target.appname || currentAppname;
+    currentHolon = sourceData.target.holonId;
+    currentLens = sourceData.target.lensName || currentLens;
+    currentDataId = sourceData.target.dataId || currentDataId;
+    sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+
+    sourceData = await read(client, sourcePath);
+    if (!sourceData) {
+      console.warn(`Real source data not found at ${sourcePath}`);
+      return false;
+    }
+  }
+
+  if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
+    console.warn(`No activeHolograms found for ${sourcePath}`);
+    return false;
+  }
+
+  // Find the hologram entry for this target
+  const hologramEntry = sourceData._meta.activeHolograms.find(
+    h => h.targetHolon === targetHolon
+  );
+
+  if (!hologramEntry) {
+    console.warn(`No hologram entry found for target ${targetHolon}`);
+    return false;
+  }
+
+  // Initialize platforms object if needed
+  if (!hologramEntry.platforms) {
+    hologramEntry.platforms = {};
+  }
+
+  // Update platform-specific data
+  hologramEntry.platforms[platform] = {
+    ...hologramEntry.platforms[platform],
+    ...platformData,
+    lastUpdated: Date.now()
+  };
+  hologramEntry.lastUpdated = Date.now();
+
+  // Write back to source
+  return write(client, sourcePath, sourceData);
+}
+
+/**
+ * Get active holograms for a data item, optionally filtered by platform
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} [platform] - Optional platform filter (e.g., 'telegram')
+ * @returns {Promise<Array>} Array of hologram entries
+ */
+export async function getActiveHolograms(client, appname, sourceHolon, lensName, dataId, platform = null) {
+  const sourcePath = buildPath(appname, sourceHolon, lensName, dataId);
+  const sourceData = await read(client, sourcePath);
+
+  if (!sourceData?._meta?.activeHolograms) {
+    return [];
+  }
+
+  let holograms = sourceData._meta.activeHolograms;
+
+  // Filter by platform if specified
+  if (platform) {
+    holograms = holograms.filter(h => h.platforms?.[platform]);
+  }
+
+  return holograms;
+}
+
 /**
  * Refresh lastUpdated timestamps on all activeHolograms in source data
  * Also updates the hologram objects in target holons