holosphere 2.0.0-alpha11 → 2.0.0-alpha12

package/src/lib/federation-methods.js

@@ -1,7 +1,13 @@
 /**
- * @fileoverview Federation methods mixin for cross-HoloSphere federation and Nostr discovery.
- * Provides federated data access, capability-based authorization, and federation request protocols
- * for connecting multiple HoloSphere instances.
+ * @fileoverview Unified Federation Methods - UNIFIED MODEL
+ *
+ * Provides a single, consistent API for all federation operations:
+ * - Same-author federation (previously "in-federation")
+ * - Cross-author federation (previously "cross-federation")
+ *
+ * All federation uses capabilities, providing consistent security semantics.
+ * The unified `federate()` method handles both cases based on parameters.
+ *
  * @module lib/federation-methods
  */
 
@@ -17,17 +23,242 @@ import { bytesToHex } from '@noble/hashes/utils';
 
 /**
  * Mixin that adds federation methods to a HoloSphere class.
- * Enables cross-HoloSphere federation with capability-based access control,
+ * Enables unified federation with capability-based access control,
  * hologram creation, and Nostr-based discovery protocols.
+ *
+ * UNIFIED MODEL: All federation uses capabilities for consistent security.
+ *
  * @param {Class} Base - Base class to extend
  * @returns {Class} Extended class with federation methods
  */
 export function withFederationMethods(Base) {
   return class extends Base {
-    // === Cross-Holosphere Federation ===
+    // === UNIFIED FEDERATION API ===
+
+    /**
+     * Federation method - UNIFIED MODEL
+     *
+     * Single entry point for all federation operations.
+     * Handles both same-author and cross-author federation consistently.
+     *
+     * @param {string|Object} source - Source holon. Can be:
+     *   - string: holonId (implies same author as client)
+     *   - { holonId, authorPubKey }: explicit author specification
+     * @param {string|Object} target - Target holon. Same format as source.
+     * @param {string} lensName - Name of the lens to federate
+     * @param {Object} [options={}] - Federation options
+     * @param {string} [options.direction='outbound'] - 'inbound', 'outbound', or 'bidirectional'
+     * @param {string} [options.mode='reference'] - 'reference' (hologram) or 'copy'
+     * @param {boolean} [options.propagate=true] - Whether to propagate existing data (false = capability only)
+     * @param {string} [options.capability] - Pre-issued capability (auto-generated if not provided)
+     * @param {string[]} [options.permissions=['read']] - Permissions for auto-issued capability
+     * @param {Function} [options.filter] - Filter function to select which data to federate
+     * @returns {Promise<Object>} Federation result with capability info
+     * @throws {ValidationError} If trying to federate a holon with itself
+     *
+     * @example
+     * // Same-author federation (simplified)
+     * await hs.federate('holon-a', 'holon-b', 'events');
+     *
+     * @example
+     * // Cross-author federation (explicit)
+     * await hs.federate(
+     *   { holonId: 'holon-a', authorPubKey: 'abc123...' },
+     *   { holonId: 'holon-b', authorPubKey: 'def456...' },
+     *   'events',
+     *   { capability: preIssuedToken }
+     * );
+     */
+    async federate(source, target, lensName, options = {}) {
+      const {
+        direction = 'outbound',
+        mode = 'reference',
+        propagate = true,
+        capability: providedCapability = null,
+        permissions = ['read'],
+        filter = null,
+      } = options;
+
+      // Normalize source and target to { holonId, authorPubKey } format
+      const normalizedSource = typeof source === 'string'
+        ? { holonId: source, authorPubKey: this.client.publicKey }
+        : { holonId: source.holonId, authorPubKey: source.authorPubKey || this.client.publicKey };
+
+      const normalizedTarget = typeof target === 'string'
+        ? { holonId: target, authorPubKey: this.client.publicKey }
+        : { holonId: target.holonId, authorPubKey: target.authorPubKey || this.client.publicKey };
+
+      // Validation
+      if (normalizedSource.holonId === normalizedTarget.holonId &&
+          normalizedSource.authorPubKey === normalizedTarget.authorPubKey) {
+        throw new ValidationError('Cannot federate a holon with itself');
+      }
+
+      if (!['inbound', 'outbound', 'bidirectional'].includes(direction)) {
+        throw new ValidationError(`Invalid direction: ${direction}. Must be 'inbound', 'outbound', or 'bidirectional'`);
+      }
+
+      // Determine if this is self-federation or cross-federation
+      const isSelfFederation = normalizedSource.authorPubKey === normalizedTarget.authorPubKey;
+
+      // Issue or use provided capability
+      let capability = providedCapability;
+      if (!capability) {
+        const expiresIn = isSelfFederation
+          ? 365 * 24 * 60 * 60 * 1000  // 1 year for self
+          : 24 * 60 * 60 * 1000;       // 24 hours for cross
+
+        capability = await crypto.issueCapability(
+          permissions,
+          { holonId: normalizedSource.holonId, lensName, dataId: '*' },
+          normalizedTarget.authorPubKey,
+          {
+            expiresIn,
+            issuer: normalizedSource.authorPubKey,
+            issuerKey: this.client.privateKey,
+            isSelfCapability: isSelfFederation,
+          }
+        );
+
+        // Store capability in registry
+        if (isSelfFederation) {
+          await registry.storeSelfCapability(this.client, this.config.appName, {
+            token: capability,
+            scope: { holonId: normalizedSource.holonId, lensName },
+            permissions,
+          });
+        } else {
+          await registry.storeInboundCapability(
+            this.client,
+            this.config.appName,
+            normalizedSource.authorPubKey,
+            {
+              token: capability,
+              scope: { holonId: normalizedSource.holonId, lensName },
+              permissions,
+            }
+          );
+        }
+      }
+
+      // Setup federation based on direction
+      const results = {
+        source: normalizedSource,
+        target: normalizedTarget,
+        lensName,
+        direction,
+        mode,
+        propagate,
+        capability,
+        isSelfFederation,
+        propagated: { outbound: 0, inbound: 0 },
+      };
+
+      // Handle data propagation (skip if propagate: false)
+      if (propagate && (direction === 'outbound' || direction === 'bidirectional')) {
+        // Propagate existing data from source to target
+        const sourceData = await this.read(normalizedSource.holonId, lensName, null, {
+          resolveHolograms: false,
+        });
+
+        if (sourceData && Array.isArray(sourceData)) {
+          for (const item of sourceData) {
+            if (filter && !filter(item)) continue;
+
+            await federation.propagateData(
+              this.client,
+              this.config.appName,
+              item,
+              normalizedSource.holonId,
+              normalizedTarget.holonId,
+              lensName,
+              mode,
+              {
+                sourceAuthorPubKey: normalizedSource.authorPubKey,
+                capability,
+              }
+            );
+            results.propagated.outbound++;
+          }
+        }
+      }
+
+      if (propagate && (direction === 'inbound' || direction === 'bidirectional')) {
+        // Propagate from target to source (need capability from target author)
+        const targetData = await this.read(normalizedTarget.holonId, lensName, null, {
+          resolveHolograms: false,
+        });
+
+        if (targetData && Array.isArray(targetData)) {
+          for (const item of targetData) {
+            if (filter && !filter(item)) continue;
+
+            await federation.propagateData(
+              this.client,
+              this.config.appName,
+              item,
+              normalizedTarget.holonId,
+              normalizedSource.holonId,
+              lensName,
+              mode,
+              {
+                sourceAuthorPubKey: normalizedTarget.authorPubKey,
+                capability,
+              }
+            );
+            results.propagated.inbound++;
+          }
+        }
+      }
+
+      // Store federation config
+      await federation.setupFederation(
+        this.client,
+        this.config.appName,
+        normalizedSource.holonId,
+        normalizedTarget.holonId,
+        lensName,
+        { direction, mode }
+      );
+
+      return results;
+    }
+
+    /**
+     * Unfederate method - UNIFIED MODEL
+     *
+     * Removes federation between source and target holons.
+     *
+     * @param {string|Object} source - Source holon (string or { holonId, authorPubKey })
+     * @param {string|Object} target - Target holon (string or { holonId, authorPubKey })
+     * @param {string} lensName - Lens name to unfederate
+     * @returns {Promise<boolean>} True if unfederation succeeded
+     */
+    async unfederate(source, target, lensName) {
+      const normalizedSource = typeof source === 'string'
+        ? { holonId: source, authorPubKey: this.client.publicKey }
+        : { holonId: source.holonId, authorPubKey: source.authorPubKey || this.client.publicKey };
+
+      const normalizedTarget = typeof target === 'string'
+        ? { holonId: target, authorPubKey: this.client.publicKey }
+        : { holonId: target.holonId, authorPubKey: target.authorPubKey || this.client.publicKey };
+
+      // Remove federation config
+      const configPath = storage.buildPath(this.config.appName, normalizedSource.holonId, lensName, '_federation');
+      try {
+        await storage.deleteData(this.client, configPath);
+      } catch (e) {
+        // Ignore errors - already unfederated or doesn't exist
+      }
+
+      return true;
+    }
+
+    // === Legacy Methods (kept for backward compatibility) ===
 
     /**
      * Add a federated HoloSphere partner by public key.
+     * @deprecated Use federate() with explicit authorPubKey instead
      * @param {string} pubKey - Public key (hex) of the federated HoloSphere
      * @param {Object} [options={}] - Federation options (metadata, capabilities, etc.)
      * @returns {Promise<Object>} Federation registration result
@@ -339,6 +570,297 @@ export function withFederationMethods(Base) {
     async getPendingFederationRequests(options = {}) {
       return discovery.getPendingFederationRequests(this.client, options);
     }
+
+    // === Federated Lens Reception (Hologram-based) ===
+
+    /**
+     * Receive data from a federated partner's lens as holograms in your own holon.
+     * This creates holograms pointing to the partner's data, allowing you to see
+     * their data in your holon while the source of truth remains with the partner.
+     *
+     * @param {string} partnerPubKey - Partner's public key
+     * @param {string} sourceHolonId - Partner's holon ID to receive data from
+     * @param {string} lensName - Lens name to receive
+     * @param {string} targetHolonId - Your holon ID where holograms will be created
+     * @param {Object} [options={}] - Reception options
+     * @param {Function} [options.filter] - Optional filter function to select which items to receive
+     * @param {boolean} [options.overwrite=false] - Whether to overwrite existing holograms
+     * @returns {Promise<Object>} Result with count of received holograms and any errors
+     * @throws {AuthorizationError} If no valid capability exists for the source
+     *
+     * @example
+     * // Receive events from a federated partner into your holon
+     * const result = await hs.receiveFederatedLens(
+     *   'partner-pubkey',
+     *   'partner-holon-id',
+     *   'events',
+     *   'my-holon-id'
+     * );
+     * console.log(`Received ${result.received} holograms`);
+     */
+    async receiveFederatedLens(partnerPubKey, sourceHolonId, lensName, targetHolonId, options = {}) {
+      const { filter = null, overwrite = false } = options;
+
+      // Get capability for accessing partner's data
+      const capabilityEntry = await registry.getCapabilityForAuthor(
+        this.client,
+        this.config.appName,
+        partnerPubKey,
+        { holonId: sourceHolonId, lensName, dataId: '*' }
+      );
+
+      if (!capabilityEntry) {
+        throw new AuthorizationError(
+          `No valid capability to access ${sourceHolonId}/${lensName} from ${partnerPubKey}`,
+          'read'
+        );
+      }
+
+      // Read all data from partner's lens
+      const sourcePath = storage.buildPath(this.config.appName, sourceHolonId, lensName);
+      const partnerData = await nostrAsync.nostrGetAll(this.client, sourcePath, 30000, {
+        authors: [partnerPubKey],
+        includeAuthor: true,
+      });
+
+      if (!partnerData || !Array.isArray(partnerData)) {
+        return { received: 0, skipped: 0, errors: [] };
+      }
+
+      const result = { received: 0, skipped: 0, errors: [] };
+
+      for (const item of partnerData) {
+        if (!item || !item.id) continue;
+
+        // Apply filter if provided
+        if (filter && !filter(item)) {
+          result.skipped++;
+          continue;
+        }
+
+        // Skip if hologram already exists and overwrite is false
+        if (!overwrite) {
+          const existingPath = storage.buildPath(this.config.appName, targetHolonId, lensName, item.id);
+          const existing = await storage.read(this.client, existingPath);
+          if (existing && existing.hologram) {
+            result.skipped++;
+            continue;
+          }
+        }
+
+        try {
+          // Create hologram in target holon pointing to partner's data
+          const hologram = await federation.createHologramWithCapability(
+            this.client,
+            sourceHolonId,
+            targetHolonId,
+            lensName,
+            item.id,
+            this.config.appName,
+            {
+              sourceAuthorPubKey: partnerPubKey,
+              targetAuthorPubKey: this.client.publicKey,
+              capability: capabilityEntry.token,
+              permissions: ['read'],
+            }
+          );
+
+          const targetPath = storage.buildPath(this.config.appName, targetHolonId, lensName, item.id);
+          await storage.write(this.client, targetPath, hologram);
+          result.received++;
+        } catch (error) {
+          result.errors.push({ id: item.id, error: error.message });
+        }
+      }
+
+      return result;
+    }
+
+    /**
+     * Subscribe to a federated partner's lens for real-time hologram updates.
+     * When the partner writes new data, holograms are automatically created in your holon.
+     *
+     * @param {string} partnerPubKey - Partner's public key
+     * @param {string} sourceHolonId - Partner's holon ID to subscribe to
+     * @param {string} lensName - Lens name to subscribe to
+     * @param {string} targetHolonId - Your holon ID where holograms will be created
+     * @param {Object} [options={}] - Subscription options
+     * @param {Function} [options.onHologram] - Callback when a new hologram is created (hologram, sourceData) => void
+     * @param {Function} [options.onError] - Callback for errors (error) => void
+     * @param {Function} [options.filter] - Optional filter function to select which items to receive
+     * @returns {Promise<Object>} Subscription object with unsubscribe() method
+     *
+     * @example
+     * // Subscribe to partner's events lens
+     * const sub = await hs.subscribeFederatedLens(
+     *   'partner-pubkey',
+     *   'partner-holon-id',
+     *   'events',
+     *   'my-holon-id',
+     *   {
+     *     onHologram: (hologram, data) => {
+     *       console.log(`New hologram received: ${data.id}`);
+     *     }
+     *   }
+     * );
+     *
+     * // Later, unsubscribe
+     * sub.unsubscribe();
+     */
+    async subscribeFederatedLens(partnerPubKey, sourceHolonId, lensName, targetHolonId, options = {}) {
+      const { onHologram, onError, filter = null } = options;
+
+      // Get capability for accessing partner's data
+      const capabilityEntry = await registry.getCapabilityForAuthor(
+        this.client,
+        this.config.appName,
+        partnerPubKey,
+        { holonId: sourceHolonId, lensName, dataId: '*' }
+      );
+
+      if (!capabilityEntry) {
+        throw new AuthorizationError(
+          `No valid capability to subscribe to ${sourceHolonId}/${lensName} from ${partnerPubKey}`,
+          'read'
+        );
+      }
+
+      // Track processed items to avoid duplicates
+      const processedIds = new Set();
+
+      // Subscribe to partner's lens path
+      const sourcePath = storage.buildPath(this.config.appName, sourceHolonId, lensName);
+
+      const handleEvent = async (data) => {
+        if (!data || !data.id) return;
+
+        // Skip if already processed
+        if (processedIds.has(data.id)) return;
+        processedIds.add(data.id);
+
+        // Apply filter if provided
+        if (filter && !filter(data)) return;
+
+        try {
+          // Check if hologram already exists
+          const existingPath = storage.buildPath(this.config.appName, targetHolonId, lensName, data.id);
+          const existing = await storage.read(this.client, existingPath);
+
+          if (existing && existing.hologram) {
+            // Hologram already exists, skip
+            return;
+          }
+
+          // Create hologram in target holon
+          const hologram = await federation.createHologramWithCapability(
+            this.client,
+            sourceHolonId,
+            targetHolonId,
+            lensName,
+            data.id,
+            this.config.appName,
+            {
+              sourceAuthorPubKey: partnerPubKey,
+              targetAuthorPubKey: this.client.publicKey,
+              capability: capabilityEntry.token,
+              permissions: ['read'],
+            }
+          );
+
+          const targetPath = storage.buildPath(this.config.appName, targetHolonId, lensName, data.id);
+          await storage.write(this.client, targetPath, hologram);
+
+          if (onHologram) {
+            onHologram(hologram, data);
+          }
+        } catch (error) {
+          if (onError) {
+            onError(error);
+          }
+        }
+      };
+
+      // Subscribe using nostr-async subscription with author filter
+      const subscription = await nostrAsync.nostrSubscribe(
+        this.client,
+        sourcePath,
+        handleEvent,
+        30000,
+        { authors: [partnerPubKey] }
+      );
+
+      return {
+        unsubscribe: () => {
+          if (subscription && subscription.unsubscribe) {
+            subscription.unsubscribe();
+          }
+          processedIds.clear();
+        },
+        processedCount: () => processedIds.size,
+      };
+    }
+
+    /**
+     * Sync all federated lenses for a holon.
+     * Receives holograms from all federated partners for their configured inbound lenses.
+     *
+     * @param {string} holonId - Your holon ID
+     * @param {Object} [options={}] - Sync options
+     * @param {boolean} [options.overwrite=false] - Whether to overwrite existing holograms
+     * @returns {Promise<Object>} Sync results per partner
+     *
+     * @example
+     * // Sync all federated data for a holon
+     * const results = await hs.syncFederatedLenses('my-holon-id');
+     * console.log(results);
+     */
+    async syncFederatedLenses(holonId, options = {}) {
+      const { overwrite = false } = options;
+
+      // Get federation configuration for this holon
+      const federationData = await this.readGlobal('federation', holonId);
+      if (!federationData) {
+        return { error: 'No federation configuration found for this holon' };
+      }
+
+      const results = {};
+
+      // Get all federated partners
+      const partners = await this.getFederatedHolospheres();
+
+      for (const partnerPubKey of partners) {
+        results[partnerPubKey] = { lenses: {}, errors: [] };
+
+        // Get partner's lens configuration
+        const partnerLensConfig = federationData.lensConfig?.[partnerPubKey];
+        const inboundLenses = partnerLensConfig?.inbound || [];
+
+        for (const lensName of inboundLenses) {
+          try {
+            // For cross-holosphere federation, the sourceHolonId would be the partner's holon
+            // We need to determine the partner's holon ID - this might be stored in the federation config
+            const partnerHolonId = partnerLensConfig?.holonId || holonId;
+
+            const result = await this.receiveFederatedLens(
+              partnerPubKey,
+              partnerHolonId,
+              lensName,
+              holonId,
+              { overwrite }
+            );
+
+            results[partnerPubKey].lenses[lensName] = result;
+          } catch (error) {
+            results[partnerPubKey].errors.push({
+              lens: lensName,
+              error: error.message,
+            });
+          }
+        }
+      }
+
+      return results;
+    }
   };
 }
 

package/src/storage/nostr-async.js

@@ -676,7 +676,7 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
  * });
  * // Later: sub.unsubscribe();
  */
-export function nostrSubscribe(client, path, callback, options = {}) {
+export async function nostrSubscribe(client, path, callback, options = {}) {
   const kind = options.kind || 30000;
 
   // Create unique key for this subscription
@@ -722,7 +722,7 @@ export function nostrSubscribe(client, path, callback, options = {}) {
     limit: 10, // Limit results for single item subscription
   };
 
-  const subscription = client.subscribe(
+  const subscription = await client.subscribe(
     filter,
     (event) => {
       // Verify event is from our public key (relay may not respect author filter)