holosphere 2.0.0-alpha11 → 2.0.0-alpha13

package/src/federation/registry.js

@@ -1,6 +1,12 @@
 /**
- * Federation Registry - Manages cross-holosphere partnerships
- * Tracks federated partners and their capability tokens
+ * Federation Registry - UNIFIED MODEL
+ *
+ * Manages federation partnerships and capability tokens for both:
+ * - Self-federation (same author, different holons)
+ * - Cross-federation (different authors)
+ *
+ * In the unified model, all federation uses capabilities, including self-federation.
+ * This provides consistent security semantics across all federation types.
  */
 
 import { writeGlobal, readGlobal } from '../storage/global-tables.js';
@@ -141,22 +147,61 @@ export async function getFederatedPartner(client, appname, partnerPubKey) {
  */
 export async function getCapabilityForAuthor(client, appname, authorPubKey, scope) {
   const registry = await getFederationRegistry(client, appname);
+
+  console.log('[Registry] 🔍 getCapabilityForAuthor called:', {
+    authorPubKey: authorPubKey?.slice(0, 12) + '...',
+    scope,
+    federatedWithCount: registry.federatedWith?.length || 0,
+    federatedPartners: registry.federatedWith?.map(p => p.pubKey?.slice(0, 12) + '...') || []
+  });
+
   const partner = registry.federatedWith.find(p => p.pubKey === authorPubKey);
 
-  if (!partner || !partner.inboundCapabilities) {
+  if (!partner) {
+    console.log('[Registry] ❌ Partner not found in federatedWith');
+    return null;
+  }
+
+  if (!partner.inboundCapabilities || partner.inboundCapabilities.length === 0) {
+    console.log('[Registry] ❌ Partner has no inboundCapabilities:', {
+      partnerPubKey: authorPubKey?.slice(0, 12) + '...',
+      hasInboundCaps: !!partner.inboundCapabilities,
+      inboundCapsLength: partner.inboundCapabilities?.length || 0
+    });
     return null;
   }
 
+  console.log('[Registry] Partner found with inboundCapabilities:', {
+    partnerPubKey: authorPubKey?.slice(0, 12) + '...',
+    capsCount: partner.inboundCapabilities.length,
+    capScopes: partner.inboundCapabilities.map(c => c.scope)
+  });
+
   // Find matching, non-expired capability
-  return partner.inboundCapabilities.find(cap => {
+  const result = partner.inboundCapabilities.find(cap => {
     // Check expiration
     if (cap.expires && cap.expires < Date.now()) {
+      console.log('[Registry] Capability expired:', { expires: cap.expires, now: Date.now() });
       return false;
     }
 
     // Check scope match (supports wildcards)
-    return matchScope(cap.scope, scope);
+    const matches = matchScope(cap.scope, scope);
+    console.log('[Registry] Scope match check:', {
+      capScope: cap.scope,
+      requestedScope: scope,
+      matches
+    });
+    return matches;
   }) || null;
+
+  if (result) {
+    console.log('[Registry] ✅ Matching capability found');
+  } else {
+    console.log('[Registry] ❌ No matching capability found');
+  }
+
+  return result;
 }
 
 /**
@@ -172,10 +217,17 @@ export async function getCapabilityForAuthor(client, appname, authorPubKey, scop
  * @returns {Promise<boolean>} Success indicator
  */
 export async function storeInboundCapability(client, appname, partnerPubKey, capabilityInfo) {
+  console.log('[Registry] 📥 storeInboundCapability called:', {
+    partnerPubKey: partnerPubKey?.slice(0, 12) + '...',
+    scope: capabilityInfo?.scope,
+    hasToken: !!capabilityInfo?.token
+  });
+
   const registry = await getFederationRegistry(client, appname);
   const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
 
   if (!partner) {
+    console.log('[Registry] Partner not in registry, auto-adding with capability');
     // Auto-add partner if not exists
     return addFederatedPartner(client, appname, partnerPubKey, {
       addedVia: 'capability_received',
@@ -193,12 +245,14 @@ export async function storeInboundCapability(client, appname, partnerPubKey, cap
   );
 
   if (existingIndex >= 0) {
+    console.log('[Registry] Updating existing capability at index:', existingIndex);
     // Update existing capability
     partner.inboundCapabilities[existingIndex] = {
       ...capabilityInfo,
       updatedAt: Date.now()
     };
   } else {
+    console.log('[Registry] Adding new capability, total will be:', partner.inboundCapabilities.length + 1);
     // Add new capability
     partner.inboundCapabilities.push({
       ...capabilityInfo,
@@ -206,7 +260,9 @@ export async function storeInboundCapability(client, appname, partnerPubKey, cap
     });
   }
 
-  return saveFederationRegistry(client, appname, registry);
+  const result = await saveFederationRegistry(client, appname, registry);
+  console.log('[Registry] ✅ Capability stored, registry saved:', result);
+  return result;
 }
 
 /**
@@ -384,3 +440,105 @@ export async function cleanupExpiredCapabilities(client, appname) {
 
   return { inboundRemoved, outboundRemoved };
 }
+
+/**
+ * Store a self-capability (for same-author federation) - UNIFIED MODEL
+ *
+ * In the unified model, self-capabilities are stored similarly to cross-capabilities
+ * but marked as self-issued. This provides consistent capability management.
+ *
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} capabilityInfo - Capability information
+ * @param {string} capabilityInfo.token - The capability token
+ * @param {Object} capabilityInfo.scope - Token scope
+ * @param {string[]} capabilityInfo.permissions - Granted permissions
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function storeSelfCapability(client, appname, capabilityInfo) {
+  const registry = await getFederationRegistry(client, appname);
+
+  // Self-capabilities are stored under the user's own pubKey
+  const selfPubKey = client.publicKey;
+
+  // Find or create self-entry
+  let selfEntry = registry.federatedWith.find(p => p.pubKey === selfPubKey);
+
+  if (!selfEntry) {
+    selfEntry = {
+      pubKey: selfPubKey,
+      alias: 'self',
+      addedAt: Date.now(),
+      addedVia: 'self_capability',
+      isSelf: true,
+      inboundCapabilities: [],
+      outboundCapabilities: [],
+      selfCapabilities: [],  // Special array for self-capabilities
+    };
+    registry.federatedWith.push(selfEntry);
+  }
+
+  if (!selfEntry.selfCapabilities) {
+    selfEntry.selfCapabilities = [];
+  }
+
+  // Check if we already have this capability (by scope match)
+  const existingIndex = selfEntry.selfCapabilities.findIndex(cap =>
+    JSON.stringify(cap.scope) === JSON.stringify(capabilityInfo.scope)
+  );
+
+  if (existingIndex >= 0) {
+    // Update existing capability
+    selfEntry.selfCapabilities[existingIndex] = {
+      ...capabilityInfo,
+      updatedAt: Date.now(),
+      isSelfCapability: true,
+    };
+  } else {
+    // Add new capability
+    selfEntry.selfCapabilities.push({
+      ...capabilityInfo,
+      issuedAt: Date.now(),
+      isSelfCapability: true,
+    });
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Get self-capability for a scope - UNIFIED MODEL
+ *
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} scope - Requested scope { holonId, lensName, dataId? }
+ * @returns {Promise<Object|null>} Self-capability or null
+ */
+export async function getSelfCapability(client, appname, scope) {
+  const registry = await getFederationRegistry(client, appname);
+  const selfEntry = registry.federatedWith.find(p => p.pubKey === client.publicKey && p.isSelf);
+
+  if (!selfEntry || !selfEntry.selfCapabilities) {
+    return null;
+  }
+
+  // Find matching, non-expired self-capability
+  return selfEntry.selfCapabilities.find(cap => {
+    // Check expiration
+    if (cap.expires && cap.expires < Date.now()) {
+      return false;
+    }
+
+    // Check scope match (supports wildcards)
+    return matchScope(cap.scope, scope);
+  }) || null;
+}
+
+/**
+ * Check if a capability is a self-capability
+ * @param {Object} capabilityInfo - Capability info object
+ * @returns {boolean} True if self-capability
+ */
+export function isSelfCapability(capabilityInfo) {
+  return capabilityInfo && capabilityInfo.isSelfCapability === true;
+}

package/src/federation/request-card.js

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview Federation Request Card Configuration
+ *
+ * Provides a card-based configuration system for federation requests.
+ * After inputting a public key, displays a card with all available lenses
+ * that can be configured for the federation request.
+ *
+ * @module federation/request-card
+ */
+
+import { issueCapabilitiesForLenses } from './capabilities.js';
+
+/**
+ * @typedef {Object} LensConfig
+ * @property {string} name - Lens name
+ * @property {boolean} enabled - Whether lens is enabled for federation
+ * @property {string} direction - 'inbound', 'outbound', or 'bidirectional'
+ * @property {string[]} permissions - Permissions to grant ('read', 'write')
+ */
+
+/**
+ * @typedef {Object} FederationCardConfig
+ * @property {string} partnerPubKey - Partner's public key
+ * @property {string} partnerName - Partner's display name (optional)
+ * @property {string} holonId - Local holon ID
+ * @property {string} holonName - Local holon display name
+ * @property {LensConfig[]} lenses - Lens configurations
+ * @property {string} message - Optional message to partner
+ * @property {number} createdAt - Card creation timestamp
+ * @property {string} status - 'pending', 'sent', 'accepted', 'rejected', 'dismissed'
+ */
+
+/**
+ * @typedef {Object} CardDisplayOptions
+ * @property {number} initialLensCount - Number of lenses to show initially (default: 3)
+ * @property {boolean} expanded - Whether card is expanded to show all lenses
+ * @property {boolean} showPermissions - Whether to show permission toggles
+ */
+
+// Default number of lenses to show before "Show more" button
+const DEFAULT_INITIAL_LENS_COUNT = 3;
+
+/**
+ * Create a federation request card configuration
+ * @param {Object} params - Card parameters
+ * @param {string} params.partnerPubKey - Partner's public key
+ * @param {string} params.partnerName - Partner's display name
+ * @param {string} params.holonId - Local holon ID
+ * @param {string} params.holonName - Local holon display name
+ * @param {string[]} params.availableLenses - All available lens names
+ * @param {Object} params.defaultConfig - Default lens configuration
+ * @returns {FederationCardConfig} Card configuration
+ */
+export function createFederationCard({
+  partnerPubKey,
+  partnerName = null,
+  holonId,
+  holonName,
+  availableLenses = [],
+  defaultConfig = {},
+}) {
+  const {
+    defaultDirection = 'bidirectional',
+    defaultPermissions = ['read'],
+    enabledByDefault = true,
+  } = defaultConfig;
+
+  // Create lens configurations for all available lenses
+  const lenses = availableLenses.map(name => ({
+    name,
+    enabled: enabledByDefault,
+    direction: defaultDirection,
+    permissions: [...defaultPermissions],
+  }));
+
+  return {
+    id: `fedcard_${partnerPubKey.substring(0, 8)}_${Date.now()}`,
+    partnerPubKey,
+    partnerName,
+    holonId,
+    holonName,
+    lenses,
+    message: '',
+    createdAt: Date.now(),
+    status: 'pending',
+    expanded: false,
+  };
+}
+
+/**
+ * Update a lens configuration in a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {string} lensName - Lens name to update
+ * @param {Partial<LensConfig>} updates - Updates to apply
+ * @returns {FederationCardConfig} Updated card
+ */
+export function updateLensConfig(card, lensName, updates) {
+  const lensIndex = card.lenses.findIndex(l => l.name === lensName);
+  if (lensIndex === -1) return card;
+
+  const updatedLenses = [...card.lenses];
+  updatedLenses[lensIndex] = {
+    ...updatedLenses[lensIndex],
+    ...updates,
+  };
+
+  return {
+    ...card,
+    lenses: updatedLenses,
+  };
+}
+
+/**
+ * Toggle a lens enabled/disabled state
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {string} lensName - Lens name to toggle
+ * @returns {FederationCardConfig} Updated card
+ */
+export function toggleLens(card, lensName) {
+  const lens = card.lenses.find(l => l.name === lensName);
+  if (!lens) return card;
+
+  return updateLensConfig(card, lensName, { enabled: !lens.enabled });
+}
+
+/**
+ * Enable all lenses in a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card
+ */
+export function enableAllLenses(card) {
+  return {
+    ...card,
+    lenses: card.lenses.map(l => ({ ...l, enabled: true })),
+  };
+}
+
+/**
+ * Disable all lenses in a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card
+ */
+export function disableAllLenses(card) {
+  return {
+    ...card,
+    lenses: card.lenses.map(l => ({ ...l, enabled: false })),
+  };
+}
+
+/**
+ * Toggle card expansion to show all lenses
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card
+ */
+export function toggleCardExpansion(card) {
+  return {
+    ...card,
+    expanded: !card.expanded,
+  };
+}
+
+/**
+ * Get lenses to display based on expansion state
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {number} initialCount - Number of lenses to show when collapsed
+ * @returns {Object} { visibleLenses, hiddenCount, isExpanded }
+ */
+export function getVisibleLenses(card, initialCount = DEFAULT_INITIAL_LENS_COUNT) {
+  const allLenses = card.lenses;
+  const isExpanded = card.expanded;
+
+  if (isExpanded || allLenses.length <= initialCount) {
+    return {
+      visibleLenses: allLenses,
+      hiddenCount: 0,
+      isExpanded: true,
+    };
+  }
+
+  return {
+    visibleLenses: allLenses.slice(0, initialCount),
+    hiddenCount: allLenses.length - initialCount,
+    isExpanded: false,
+  };
+}
+
+/**
+ * Get enabled lenses from a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {LensConfig[]} Enabled lenses
+ */
+export function getEnabledLenses(card) {
+  return card.lenses.filter(l => l.enabled);
+}
+
+/**
+ * Get lens configuration for handshake (inbound/outbound arrays)
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Object} { inbound: string[], outbound: string[] }
+ */
+export function getLensConfigForHandshake(card) {
+  const inbound = [];
+  const outbound = [];
+
+  for (const lens of card.lenses) {
+    if (!lens.enabled) continue;
+
+    if (lens.direction === 'inbound' || lens.direction === 'bidirectional') {
+      inbound.push(lens.name);
+    }
+    if (lens.direction === 'outbound' || lens.direction === 'bidirectional') {
+      outbound.push(lens.name);
+    }
+  }
+
+  return { inbound, outbound };
+}
+
+/**
+ * Update card status
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {string} status - New status
+ * @returns {FederationCardConfig} Updated card
+ */
+export function updateCardStatus(card, status) {
+  return {
+    ...card,
+    status,
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * Dismiss a card (mark as dismissed so it doesn't reappear)
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card with dismissed status
+ */
+export function dismissCard(card) {
+  return updateCardStatus(card, 'dismissed');
+}
+
+/**
+ * Check if a card should be displayed
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {boolean} True if card should be displayed
+ */
+export function shouldDisplayCard(card) {
+  return card.status !== 'dismissed' && card.status !== 'rejected';
+}
+
+/**
+ * Convert card configuration to handshake request params
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Object} Params for initiateFederationHandshake
+ */
+export function cardToHandshakeParams(card) {
+  const lensConfig = getLensConfigForHandshake(card);
+
+  return {
+    partnerPubKey: card.partnerPubKey,
+    holonId: card.holonId,
+    holonName: card.holonName,
+    lensConfig,
+    message: card.message,
+  };
+}
+
+/**
+ * Generate capabilities for a card's outbound lenses
+ * @param {Object} client - NostrClient instance
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Promise<Object[]>} Array of capability info objects
+ */
+export async function generateCapabilitiesForCard(client, card) {
+  const { outbound } = getLensConfigForHandshake(card);
+
+  if (outbound.length === 0) {
+    return [];
+  }
+
+  return issueCapabilitiesForLenses(
+    client,
+    card.holonId,
+    outbound,
+    card.partnerPubKey,
+    { permissions: ['read'] }
+  );
+}
+
+/**
+ * Render card as a simple text representation (for CLI/logs)
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {CardDisplayOptions} options - Display options
+ * @returns {string} Text representation
+ */
+export function renderCardAsText(card, options = {}) {
+  const { initialLensCount = DEFAULT_INITIAL_LENS_COUNT } = options;
+  const { visibleLenses, hiddenCount, isExpanded } = getVisibleLenses(card, initialLensCount);
+  const { inbound, outbound } = getLensConfigForHandshake(card);
+
+  const lines = [
+    `┌─────────────────────────────────────────────────────┐`,
+    `│ Federation Request                                  │`,
+    `├─────────────────────────────────────────────────────┤`,
+    `│ Partner: ${(card.partnerName || card.partnerPubKey.substring(0, 16) + '...').padEnd(40)}│`,
+    `│ Status:  ${card.status.padEnd(40)}│`,
+    `├─────────────────────────────────────────────────────┤`,
+    `│ Lenses:                                             │`,
+  ];
+
+  for (const lens of visibleLenses) {
+    const status = lens.enabled ? '✓' : '○';
+    const dir = lens.direction === 'bidirectional' ? '↔' :
+                lens.direction === 'inbound' ? '←' : '→';
+    lines.push(`│   ${status} ${lens.name.padEnd(20)} ${dir.padEnd(22)}│`);
+  }
+
+  if (hiddenCount > 0) {
+    lines.push(`│   ... and ${hiddenCount} more lenses (click to expand)    │`);
+  }
+
+  lines.push(`├─────────────────────────────────────────────────────┤`);
+  lines.push(`│ Sharing: ${outbound.length} lenses  |  Receiving: ${inbound.length} lenses`.padEnd(52) + `│`);
+  lines.push(`└─────────────────────────────────────────────────────┘`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Serialize card for storage
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Object} Serialized card
+ */
+export function serializeCard(card) {
+  return {
+    ...card,
+    serializedAt: Date.now(),
+  };
+}
+
+/**
+ * Deserialize card from storage
+ * @param {Object} data - Serialized card data
+ * @returns {FederationCardConfig} Card configuration
+ */
+export function deserializeCard(data) {
+  return {
+    ...data,
+    expanded: data.expanded || false,
+    lenses: data.lenses || [],
+  };
+}
+
+export default {
+  createFederationCard,
+  updateLensConfig,
+  toggleLens,
+  enableAllLenses,
+  disableAllLenses,
+  toggleCardExpansion,
+  getVisibleLenses,
+  getEnabledLenses,
+  getLensConfigForHandshake,
+  updateCardStatus,
+  dismissCard,
+  shouldDisplayCard,
+  cardToHandshakeParams,
+  generateCapabilitiesForCard,
+  renderCardAsText,
+  serializeCard,
+  deserializeCard,
+  DEFAULT_INITIAL_LENS_COUNT,
+};

package/src/hierarchical/upcast.js

@@ -1,11 +1,14 @@
 /**
  * @fileoverview Hierarchical aggregation (upcast) operations for propagating data to parent holons.
  * Implements upcast operations (FR-025 to FR-027) for H3-based geographic hierarchies.
+ *
+ * UNIFIED MODEL: Uses createHologramWithCapability for consistent capability-based federation.
+ *
  * @module hierarchical/upcast
  */
 
 import { getParents, isValidH3 } from '../spatial/h3-operations.js';
-import { createHologram } from '../federation/hologram.js';
+import { createHologramWithCapability } from '../federation/hologram.js';
 import { write } from '../storage/unified-storage.js';
 
 /**
@@ -50,6 +53,7 @@ export async function upcast(hs, holonId, lensName, dataId, options = {}) {
 
 /**
  * Propagate data to a parent holon by creating a hologram reference.
+ * UNIFIED MODEL: Uses createHologramWithCapability for consistent capability-based federation.
  * @private
  * @param {Object} client - Nostr client instance
  * @param {string} appname - Application name
@@ -69,8 +73,20 @@ async function propagateToParent(
   dataId,
   operation
 ) {
-  // Create hologram reference
-  const hologram = createHologram(sourceHolon, parentHolon, lensName, dataId, appname);
+  // UNIFIED MODEL: Create hologram with capability
+  const hologram = await createHologramWithCapability(
+    client,
+    sourceHolon,
+    parentHolon,
+    lensName,
+    dataId,
+    appname,
+    {
+      // Use client's public key as source author (self-federation for upcast)
+      sourceAuthorPubKey: client.publicKey,
+      permissions: ['read'],
+    }
+  );
 
   // Add operation metadata
   hologram._meta.operation = operation;