holosphere 2.0.0-alpha11 → 2.0.0-alpha13

package/src/federation/hologram.js

@@ -1,17 +1,23 @@
 /**
- * @fileoverview Federation and Hologram (Reference) Management.
+ * @fileoverview Unified 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.
+ * source of truth.
+ *
+ * UNIFIED MODEL: All federation is capability-based. Every hologram includes:
+ * - authorPubKey: The public key of the data owner (can be self)
+ * - capability: A capability token (self-issued for same-author federation)
+ *
+ * This unifies "in-federation" (same author) and "cross-federation" (different authors)
+ * into a single consistent model.
  *
  * @module federation/hologram
  */
 
 import { buildPath, write, read, update } from '../storage/unified-storage.js';
-import { verifyCapability } from '../crypto/secp256k1.js';
-import { getCapabilityForAuthor } from './registry.js';
+import { verifyCapability, issueCapability } from '../crypto/secp256k1.js';
+import { getCapabilityForAuthor, storeInboundCapability } from './registry.js';
 
 /** @constant {number} Maximum depth for hologram resolution chain */
 const MAX_RESOLUTION_DEPTH = 10;
@@ -79,19 +85,38 @@ export async function wouldCreateCircularHologram(client, appname, sourceHolon,
 }
 
 /**
- * Create a hologram (lightweight reference)
+ * Create a hologram (lightweight reference) - UNIFIED MODEL
+ *
+ * All holograms now include authorPubKey and capability for consistency.
+ * This unifies "in-federation" (same author) and "cross-federation" (different authors).
+ *
  * @param {string} sourceHolon - Source holon ID
  * @param {string} targetHolon - Target holon ID
  * @param {string} lensName - Lens name
  * @param {string} dataId - Data ID
  * @param {string} appname - Application namespace
- * @param {Object} options - Optional cross-holosphere settings
- * @param {string} options.authorPubKey - Source author's public key (for cross-holosphere)
- * @param {string} options.capability - Capability token (for cross-holosphere)
- * @returns {Object} Hologram object
+ * @param {Object} options - Hologram options (authorPubKey and capability are required)
+ * @param {string} options.authorPubKey - Source author's public key (REQUIRED - can be self)
+ * @param {string} options.capability - Capability token (REQUIRED - self-issued for same author)
+ * @returns {Object} Hologram object with unified structure
+ * @throws {Error} If authorPubKey or capability is missing
  */
 export function createHologram(sourceHolon, targetHolon, lensName, dataId, appname, options = {}) {
-  const { authorPubKey = null, capability = null } = options;
+  const { authorPubKey } = options;
+  let { capability } = options;
+
+  // Validate required fields for unified model
+  if (!authorPubKey) {
+    throw new Error('authorPubKey is required for hologram creation (unified model)');
+  }
+  if (!capability) {
+    throw new Error('capability is required for hologram creation (unified model)');
+  }
+
+  // Normalize capability - ensure it's the token string, not a capability object
+  if (typeof capability === 'object' && capability.token) {
+    capability = capability.token;
+  }
 
   const soul = buildPath(appname, sourceHolon, lensName, dataId);
 
@@ -104,32 +129,95 @@ export function createHologram(sourceHolon, targetHolon, lensName, dataId, appna
       holonId: sourceHolon,
       lensName,
       dataId,
+      authorPubKey,  // Always present in unified model
     },
+    capability,  // Always the token string (normalized above)
     _meta: {
       created: Date.now(),
       sourceHolon,
       source: sourceHolon,  // Alias for compatibility
+      sourcePubKey: authorPubKey,
+      grantedAt: Date.now(),
     },
   };
 
-  // Cross-holosphere enhancements
-  if (authorPubKey) {
-    hologram.crossHolosphere = true;
-    hologram.target.authorPubKey = authorPubKey;
-    hologram._meta.sourcePubKey = authorPubKey;
-  }
+  return hologram;
+}
 
-  if (capability) {
-    hologram.capability = capability;
-    hologram._meta.grantedAt = Date.now();
+/**
+ * Create a hologram with automatic capability issuance - UNIFIED MODEL
+ *
+ * This is the preferred method for creating holograms. It automatically issues
+ * a capability token (self-capability if same author, cross-capability otherwise).
+ *
+ * @param {Object} client - Nostr client instance (must have publicKey and optionally privateKey)
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} targetHolon - Target holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} appname - Application namespace
+ * @param {Object} options - Hologram options
+ * @param {string} [options.sourceAuthorPubKey] - Source author's public key (defaults to client.publicKey)
+ * @param {string} [options.targetAuthorPubKey] - Target author's public key (defaults to client.publicKey)
+ * @param {string} [options.capability] - Pre-issued capability (if not provided, one will be issued)
+ * @param {string[]} [options.permissions=['read']] - Permissions for auto-issued capability
+ * @param {number} [options.expiresIn] - Capability expiration (null for self-caps = no expiration)
+ * @returns {Promise<Object>} Hologram object with unified structure
+ */
+export async function createHologramWithCapability(client, sourceHolon, targetHolon, lensName, dataId, appname, options = {}) {
+  const {
+    sourceAuthorPubKey = client.publicKey,
+    targetAuthorPubKey = client.publicKey,
+    capability: providedCapability = null,
+    permissions = ['read'],
+    expiresIn = null,
+  } = options;
+
+  let capability = providedCapability;
+
+  // Issue capability if not provided
+  if (!capability) {
+    const isSelfCapability = sourceAuthorPubKey === targetAuthorPubKey;
+
+    // Issue capability - for self-caps, no expiration by default
+    capability = await issueCapability(
+      permissions,
+      { holonId: sourceHolon, lensName, dataId },
+      targetAuthorPubKey,
+      {
+        expiresIn: expiresIn !== null ? expiresIn : (isSelfCapability ? 365 * 24 * 60 * 60 * 1000 : 3600000), // 1 year for self, 1 hour for cross
+        issuer: sourceAuthorPubKey,
+        issuerKey: client.privateKey,
+      }
+    );
+
+    // Store the capability in registry for cross-author federation
+    if (!isSelfCapability && client.privateKey) {
+      await storeInboundCapability(client, appname, sourceAuthorPubKey, {
+        token: capability,
+        scope: { holonId: sourceHolon, lensName, dataId },
+        permissions,
+        isSelfCapability: false,
+      });
+    }
   }
 
-  return hologram;
+  return createHologram(sourceHolon, targetHolon, lensName, dataId, appname, {
+    authorPubKey: sourceAuthorPubKey,
+    capability,
+  });
 }
 
 /**
- * Resolve hologram to actual data, merging local overrides
- * Supports cross-holosphere holograms with capability token verification
+ * Resolve hologram to actual data, merging local overrides - UNIFIED MODEL
+ *
+ * In the unified model, ALL holograms have authorPubKey and capability.
+ * Resolution always:
+ * 1. Verifies the capability token
+ * 2. Fetches data with author filter
+ *
+ * This provides consistent security for both self and cross-author holograms.
+ *
  * @param {Object} client - Nostr client instance
  * @param {Object} hologram - Hologram object
  * @param {Set} visited - Visited souls (circular reference detection)
@@ -138,10 +226,11 @@ export function createHologram(sourceHolon, targetHolon, lensName, dataId, appna
  * @param {string} options.appname - Application namespace (for registry lookup)
  * @param {boolean} options.deleteCircular - If true, delete circular holograms when detected (default: true)
  * @param {string} options.hologramPath - Path of the hologram being resolved (for deletion)
+ * @param {boolean} options.skipCapabilityVerification - Skip capability check (for internal use only)
  * @returns {Promise<Object|null>} Resolved data with _hologram metadata, or null
  */
 export async function resolveHologram(client, hologram, visited = new Set(), chain = [], options = {}) {
-  const { deleteCircular = true, hologramPath = null } = options;
+  const { deleteCircular = true, hologramPath = null, skipCapabilityVerification = false } = options;
 
   if (!hologram || !hologram.hologram) {
     return hologram; // Not a hologram, return as-is
@@ -192,31 +281,38 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
 
   let sourceData;
 
-  // Handle cross-holosphere holograms
-  if (hologram.crossHolosphere && target.authorPubKey) {
-    // Get capability - try embedded first, then registry fallback
-    let capability = hologram.capability;
+  // UNIFIED MODEL: All holograms have authorPubKey and capability
+  // Get capability - try embedded first, then registry fallback
+  let capability = hologram.capability;
+  const authorPubKey = target.authorPubKey;
 
-    if (!capability && options.appname) {
-      // Fallback to registry lookup
-      const capEntry = await getCapabilityForAuthor(
-        client,
-        options.appname,
-        target.authorPubKey,
-        {
-          holonId: target.holonId,
-          lensName: target.lensName,
-          dataId: target.dataId,
-        }
-      );
-      if (capEntry) {
-        capability = capEntry.token;
+  // Normalize capability - extract token string if it's a capability object
+  if (capability && typeof capability === 'object' && capability.token) {
+    capability = capability.token;
+  }
+
+  if (!capability && options.appname && authorPubKey) {
+    // Fallback to registry lookup
+    const capEntry = await getCapabilityForAuthor(
+      client,
+      options.appname,
+      authorPubKey,
+      {
+        holonId: target.holonId,
+        lensName: target.lensName,
+        dataId: target.dataId,
       }
+    );
+    if (capEntry) {
+      // Extract token string from capability entry
+      capability = capEntry.token || capEntry;
     }
+  }
 
-    // Verify capability before resolving
+  // Verify capability (unified model - always verify unless explicitly skipped)
+  if (!skipCapabilityVerification) {
     if (!capability) {
-      console.warn(`❌ Cross-holosphere hologram missing capability: ${soul}`);
+      console.warn(`❌ Hologram missing capability: ${soul}`);
       return null;
     }
 
@@ -231,16 +327,18 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
     );
 
     if (!isValid) {
-      console.warn(`❌ Capability verification failed for cross-holosphere hologram: ${soul}`);
+      console.warn(`❌ Capability verification failed for hologram: ${soul}`);
       return null;
     }
+  }
 
-    // Read from federated source (different author)
+  // UNIFIED MODEL: Always fetch with author filter if authorPubKey is present
+  if (authorPubKey) {
     sourceData = await read(client, soul, {
-      authors: [target.authorPubKey]
+      authors: [authorPubKey]
     });
   } else {
-    // Same-holosphere resolution (original behavior)
+    // Legacy fallback for holograms without authorPubKey
     sourceData = await read(client, soul);
   }
 
@@ -259,7 +357,7 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
 }
 
 /**
- * Merge hologram local overrides with source data
+ * Merge hologram local overrides with source data - UNIFIED MODEL
  * @private
  * @param {Object} hologram - Hologram object
  * @param {Object} sourceData - Source data
@@ -267,7 +365,7 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
  */
 function mergeHologramWithSource(hologram, sourceData) {
   // Extract local overrides from the hologram (exclude hologram-specific fields)
-  const hologramOnlyFields = ['hologram', 'soul', 'target', '_meta', 'id', 'capability', 'crossHolosphere'];
+  const hologramOnlyFields = ['hologram', 'soul', 'target', '_meta', 'id', 'capability'];
   const localOverrides = {};
   const localOverrideKeys = [];
 
@@ -280,6 +378,8 @@ function mergeHologramWithSource(hologram, sourceData) {
 
   // Merge: source data + local overrides + hologram metadata
   const sourceHolon = hologram._meta?.sourceHolon || hologram._meta?.source || hologram.target?.holonId;
+  const sourcePubKey = hologram.target?.authorPubKey || hologram._meta?.sourcePubKey || null;
+
   const resolved = {
     ...sourceData,           // Original data from source
     ...localOverrides,       // Local overrides (x, y, pinned, etc.)
@@ -288,8 +388,7 @@ function mergeHologramWithSource(hologram, sourceData) {
       soul: hologram.soul,
       sourceHolon: sourceHolon,
       localOverrides: localOverrideKeys,
-      crossHolosphere: hologram.crossHolosphere || false,
-      sourcePubKey: hologram._meta?.sourcePubKey || null,
+      sourcePubKey: sourcePubKey,  // Always present in unified model
     }
   };
 
@@ -340,14 +439,21 @@ export async function setupFederation(
 }
 
 /**
- * Propagate data to federated location
- * @param {Object} client - Nostr client instance
+ * Propagate data to federated location - UNIFIED MODEL
+ *
+ * In the unified model, all holograms require authorPubKey and capability.
+ * This function automatically issues capabilities for propagation.
+ *
+ * @param {Object} client - Nostr client instance (must have publicKey)
  * @param {string} appname - Application namespace
  * @param {Object} data - Data to propagate
  * @param {string} sourceHolon - Source holon ID
  * @param {string} targetHolon - Target holon ID
  * @param {string} lensName - Lens name
  * @param {string} mode - 'reference' or 'copy'
+ * @param {Object} options - Propagation options
+ * @param {string} [options.sourceAuthorPubKey] - Source author (defaults to client.publicKey)
+ * @param {string} [options.capability] - Pre-issued capability (auto-issued if not provided)
  * @returns {Promise<boolean>} Success indicator
  */
 export async function propagateData(
@@ -357,7 +463,8 @@ export async function propagateData(
   sourceHolon,
   targetHolon,
   lensName,
-  mode = 'reference'
+  mode = 'reference',
+  options = {}
 ) {
   const dataId = data.id;
 
@@ -490,8 +597,38 @@ export async function propagateData(
       return false;
     }
 
-    // Create hologram in target
-    const hologram = createHologram(sourceHolon, targetHolon, lensName, dataId, appname);
+    // UNIFIED MODEL: Create hologram with capability
+    const sourceAuthorPubKey = options.sourceAuthorPubKey || client.publicKey;
+
+    // Determine targetAuthorPubKey - the person who should be able to read the hologram
+    // If targetHolon is a 64-char hex pubkey, use it directly as the target author
+    // Otherwise, this needs to be resolved via holon registry (TODO: add resolution)
+    const isPubkey = typeof targetHolon === 'string' && /^[0-9a-f]{64}$/i.test(targetHolon);
+    const targetAuthorPubKey = options.targetAuthorPubKey || (isPubkey ? targetHolon : client.publicKey);
+
+    console.log('[propagateData] Creating hologram with capability:', {
+      sourceHolon: sourceHolon?.slice(0, 12) + '...',
+      targetHolon: targetHolon?.slice(0, 12) + '...',
+      sourceAuthorPubKey: sourceAuthorPubKey?.slice(0, 12) + '...',
+      targetAuthorPubKey: targetAuthorPubKey?.slice(0, 12) + '...',
+      hasProvidedCapability: !!options.capability
+    });
+
+    const hologram = await createHologramWithCapability(
+      client,
+      sourceHolon,
+      targetHolon,
+      lensName,
+      dataId,
+      appname,
+      {
+        sourceAuthorPubKey,
+        targetAuthorPubKey,
+        capability: options.capability,
+        permissions: ['read'],
+      }
+    );
+
     const targetPath = buildPath(appname, targetHolon, lensName, dataId);
     const success = await write(client, targetPath, hologram);
 

package/src/federation/holon-registry.js

@@ -0,0 +1,187 @@
+/**
+ * Holon Registry - Maps holonId to public key
+ *
+ * Every holon (H3 cell, telegram chat, concept) can be registered with a keypair.
+ * The holonId IS the public key (or resolves to one via this registry).
+ *
+ * When reading data, the system resolves holonId -> pubkey to determine
+ * whose data to read and what capabilities are needed.
+ */
+
+import { writeGlobal, readGlobal, getAllGlobal } from '../storage/global-tables.js';
+
+const HOLON_REGISTRY_TABLE = '_holon-registry';
+
+/**
+ * Check if a string is a valid 64-character hex public key
+ * @param {string} str - String to check
+ * @returns {boolean} True if valid pubkey format
+ */
+export function isPubkey(str) {
+  return typeof str === 'string' && /^[0-9a-f]{64}$/i.test(str);
+}
+
+/**
+ * Register a holon -> public key mapping
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier (H3, chatId, concept, etc.)
+ * @param {string} publicKey - 64-char hex public key
+ * @param {Object} options - Registration options
+ * @param {string} [options.alias] - Human-readable name
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function registerHolon(client, appname, holonId, publicKey, options = {}) {
+  if (!isPubkey(publicKey)) {
+    throw new Error(`Invalid public key format: ${publicKey}`);
+  }
+
+  // Don't register if holonId is already a pubkey
+  if (isPubkey(holonId)) {
+    console.log('[HolonRegistry] registerHolon: holonId is already a pubkey, skipping registration');
+    return true; // No registration needed
+  }
+
+  const entry = {
+    id: holonId,
+    holonId: holonId,
+    publicKey: publicKey,
+    alias: options.alias || null,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    createdBy: client.publicKey,
+  };
+
+  console.log('[HolonRegistry] 📝 registerHolon:', {
+    holonId,
+    publicKey: publicKey?.slice(0, 12) + '...',
+    alias: options.alias
+  });
+
+  const result = await writeGlobal(client, appname, HOLON_REGISTRY_TABLE, entry);
+  console.log('[HolonRegistry] registerHolon result:', result);
+  return result;
+}
+
+/**
+ * Look up a holon's registration entry
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @returns {Promise<Object|null>} Registry entry or null
+ */
+export async function lookupHolon(client, appname, holonId) {
+  // If already a pubkey, return synthetic entry
+  if (isPubkey(holonId)) {
+    return {
+      holonId: holonId,
+      publicKey: holonId,
+      isDirect: true,
+    };
+  }
+
+  return readGlobal(client, appname, HOLON_REGISTRY_TABLE, holonId);
+}
+
+/**
+ * Resolve holonId to public key
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @returns {Promise<string|null>} Public key or null if not found
+ */
+export async function resolveHolonToPubkey(client, appname, holonId) {
+  // Direct pubkey
+  if (isPubkey(holonId)) {
+    console.log('[HolonRegistry] resolveHolonToPubkey: holonId is already a pubkey:', holonId?.slice(0, 12) + '...');
+    return holonId;
+  }
+
+  // Registry lookup
+  const entry = await lookupHolon(client, appname, holonId);
+
+  if (entry?.publicKey) {
+    console.log('[HolonRegistry] ✅ resolveHolonToPubkey: Found mapping', {
+      holonId,
+      publicKey: entry.publicKey?.slice(0, 12) + '...',
+      alias: entry.alias
+    });
+  } else {
+    console.log('[HolonRegistry] ❌ resolveHolonToPubkey: No mapping found for holonId:', holonId);
+  }
+
+  return entry?.publicKey || null;
+}
+
+/**
+ * Unregister a holon
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function unregisterHolon(client, appname, holonId) {
+  // Can't unregister a direct pubkey
+  if (isPubkey(holonId)) {
+    return false;
+  }
+
+  // Mark as deleted by writing a tombstone
+  const entry = {
+    id: holonId,
+    holonId: holonId,
+    publicKey: null,
+    _deleted: true,
+    deletedAt: Date.now(),
+    deletedBy: client.publicKey,
+  };
+
+  return writeGlobal(client, appname, HOLON_REGISTRY_TABLE, entry);
+}
+
+/**
+ * Update a holon's alias or metadata
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @param {Object} updates - Fields to update
+ * @param {string} [updates.alias] - New alias
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateHolon(client, appname, holonId, updates = {}) {
+  const existing = await lookupHolon(client, appname, holonId);
+  if (!existing || existing.isDirect) {
+    return false;
+  }
+
+  const entry = {
+    ...existing,
+    ...updates,
+    updatedAt: Date.now(),
+  };
+
+  return writeGlobal(client, appname, HOLON_REGISTRY_TABLE, entry);
+}
+
+/**
+ * List all registered holons
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Object[]>} Array of registry entries
+ */
+export async function listRegisteredHolons(client, appname) {
+  const entries = await getAllGlobal(client, appname, HOLON_REGISTRY_TABLE);
+  return (entries || []).filter(e => !e._deleted);
+}
+
+/**
+ * Find holons by public key
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} publicKey - Public key to search for
+ * @returns {Promise<Object[]>} Array of holons with this pubkey
+ */
+export async function findHolonsByPubkey(client, appname, publicKey) {
+  const all = await listRegisteredHolons(client, appname);
+  return all.filter(e => e.publicKey === publicKey);
+}

package/src/federation/index.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Federation Module Index
+ *
+ * Exports all federation-related functionality in a modular structure.
+ * The federation system is now split into smaller, focused components:
+ *
+ * - capabilities: Token issuance and verification
+ * - registry: Partner and capability storage
+ * - handshake: NIP-44 encrypted DM protocol
+ * - discovery: Nostr event-based discovery
+ * - hologram: Reference/hologram management
+ * - request-card: Card-based configuration UI
+ * - card-storage: Persistent card state management
+ * - holon-registry: HolonId to pubKey mapping
+ *
+ * @module federation
+ */
+
+// Core federation components
+export * from './registry.js';
+export * from './hologram.js';
+export * from './discovery.js';
+
+// Handshake protocol
+export * from './handshake.js';
+
+// Capability management
+export * from './capabilities.js';
+
+// Card-based configuration
+export * from './request-card.js';
+export * from './card-storage.js';
+
+// Holon registry
+export * from './holon-registry.js';
+
+// Named exports for convenience
+import * as registry from './registry.js';
+import * as hologram from './hologram.js';
+import * as discovery from './discovery.js';
+import * as handshake from './handshake.js';
+import * as capabilities from './capabilities.js';
+import * as requestCard from './request-card.js';
+import * as cardStorage from './card-storage.js';
+import * as holonRegistry from './holon-registry.js';
+
+export {
+  registry,
+  hologram,
+  discovery,
+  handshake,
+  capabilities,
+  requestCard,
+  cardStorage,
+  holonRegistry,
+};
+
+// Default export with all modules
+export default {
+  registry,
+  hologram,
+  discovery,
+  handshake,
+  capabilities,
+  requestCard,
+  cardStorage,
+  holonRegistry,
+};