holosphere 2.0.0-alpha7 → 2.0.0-alpha8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holosphere",
-  "version": "2.0.0-alpha7",
+  "version": "2.0.0-alpha8",
   "description": "Holonic geospatial communication infrastructure combining H3 hexagonal indexing with distributed P2P storage",
   "type": "module",
   "bin": {
@@ -19,6 +19,8 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:cdn": "vite build --config vite.config.cdn.js",
+    "build:all": "npm run build && npm run build:cdn",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

package/src/cdn-entry.js

@@ -0,0 +1,22 @@
+/**
+ * CDN Entry Point for HoloSphere
+ *
+ * This file creates a clean global API for browser usage.
+ * After including the script, use: new HoloSphere({ appName: 'my-app' })
+ *
+ * Also exposes h3 library as window.h3 for hexagon visualization.
+ */
+
+// Import the main class
+import { HoloSphere } from './index.js';
+
+// Import h3-js for hexagon boundary visualization
+import * as h3 from 'h3-js';
+
+// Expose h3 globally for widget use
+if (typeof window !== 'undefined') {
+  window.h3 = h3;
+}
+
+// Export only the main class as default
+export default HoloSphere;

package/src/contracts/queries.js

@@ -6,7 +6,22 @@
  */
 
 import { ethers } from 'ethers';
-import { ContractABIs } from './index.js';
+// Import ABIs directly to avoid circular dependency with index.js
+import SplitterABI from './abis/Splitter.json' with { type: 'json' };
+import ManagedABI from './abis/Managed.json' with { type: 'json' };
+import ZonedABI from './abis/Zoned.json' with { type: 'json' };
+import AppreciativeABI from './abis/Appreciative.json' with { type: 'json' };
+import BundleABI from './abis/Bundle.json' with { type: 'json' };
+import HolonsABI from './abis/Holons.json' with { type: 'json' };
+
+const ContractABIs = {
+  Splitter: SplitterABI,
+  Managed: ManagedABI,
+  Zoned: ZonedABI,
+  Appreciative: AppreciativeABI,
+  Bundle: BundleABI,
+  Holons: HolonsABI
+};
 
 /**
  * Helper to format wei to ETH

package/src/core/holosphere.js

@@ -61,7 +61,7 @@ export class HoloSphere {
    * @param {string} config.backend - Storage backend: 'nostr' | 'gundb' | 'activitypub' (default: 'nostr')
    * @param {string[]} config.relays - Nostr relay URLs (default from HOLOSPHERE_RELAYS env or ['wss://relay.holons.io', 'wss://relay.nostr.band'])
    * @param {string} config.privateKey - Private key for signing (hex format, optional)
-   * @param {string} config.logLevel - Log verbosity: ERROR|WARN|INFO|DEBUG (default: 'WARN')
+   * @param {string} config.logLevel - Log verbosity: ERROR|WARN|INFO|DEBUG (default: 'INFO')
    * @param {boolean} config.hybridMode - Enable hybrid mode (local + relay queries) (default: true)
    * @param {Object} config.gundb - GunDB-specific configuration
    * @param {Object} config.activitypub - ActivityPub-specific configuration
@@ -97,7 +97,7 @@ export class HoloSphere {
       backend: config.backend || 'nostr',
       relays: config.relays || getDefaultRelays(),
       privateKey: config.privateKey || getEnv('HOLOSPHERE_PRIVATE_KEY'),
-      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'WARN',
+      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'INFO',
       hybridMode: config.hybridMode !== false, // Enable by default
     };
 

package/src/crypto/nostr-utils.js

@@ -1,11 +1,12 @@
 /**
  * Nostr Utility Functions
  *
- * Provides browser-compatible utilities for Nostr key handling and NIP-04 encryption.
+ * Provides browser-compatible utilities for Nostr key handling and encryption.
+ * Supports both NIP-04 (legacy) and NIP-44 (modern, audited) encryption.
  * Apps can use these without directly importing nostr-tools.
  */
 
-import { nip04, nip19, getPublicKey as nostrGetPublicKey, finalizeEvent, verifyEvent as nostrVerifyEvent } from 'nostr-tools';
+import { nip04, nip44, nip19, getPublicKey as nostrGetPublicKey, finalizeEvent, verifyEvent as nostrVerifyEvent } from 'nostr-tools';
 
 // ============================================================================
 // Key Conversion Utilities
@@ -160,6 +161,39 @@ export async function decryptNIP04(privateKey, senderPubKey, encryptedContent) {
   return await nip04.decrypt(privateKey, senderPubKey, encryptedContent);
 }
 
+// ============================================================================
+// NIP-44 Encryption (Modern, Audited - Replaces NIP-04)
+// ============================================================================
+
+/**
+ * Encrypt a message using NIP-44 (modern encryption standard)
+ * Uses ChaCha20 + HMAC-SHA256, audited by Cure53
+ * @param {string} privateKey - Sender's hex private key
+ * @param {string} recipientPubKey - Recipient's hex public key
+ * @param {string} content - Plain text content
+ * @returns {string} Encrypted content (base64)
+ */
+export function encryptNIP44(privateKey, recipientPubKey, content) {
+  const privKeyBytes = hexToBytes(privateKey);
+  // nostr-tools nip44 expects pubkey as hex string, not bytes
+  const conversationKey = nip44.v2.utils.getConversationKey(privKeyBytes, recipientPubKey);
+  return nip44.v2.encrypt(content, conversationKey);
+}
+
+/**
+ * Decrypt a NIP-44 encrypted message
+ * @param {string} privateKey - Recipient's hex private key
+ * @param {string} senderPubKey - Sender's hex public key
+ * @param {string} encryptedContent - Encrypted content (base64)
+ * @returns {string} Decrypted content
+ */
+export function decryptNIP44(privateKey, senderPubKey, encryptedContent) {
+  const privKeyBytes = hexToBytes(privateKey);
+  // nostr-tools nip44 expects pubkey as hex string, not bytes
+  const conversationKey = nip44.v2.utils.getConversationKey(privKeyBytes, senderPubKey);
+  return nip44.v2.decrypt(encryptedContent, conversationKey);
+}
+
 // ============================================================================
 // Event Creation
 // ============================================================================

package/src/federation/handshake.js

@@ -1,12 +1,15 @@
 /**
  * Federation Handshake Protocol
  *
- * Uses NIP-04 encrypted DMs (kind 4) for bidirectional federation request/response.
+ * 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,
@@ -140,7 +143,7 @@ export function createFederationResponse({
 export async function sendFederationRequest(client, privateKey, recipientPubKey, request) {
   try {
     const content = JSON.stringify(request);
-    const encrypted = await encryptNIP04(privateKey, recipientPubKey, content);
+    const encrypted = encryptNIP44(privateKey, recipientPubKey, content);
     const event = createDMEvent(recipientPubKey, encrypted, privateKey);
 
     if (client?.publish) {
@@ -168,7 +171,7 @@ export async function sendFederationRequest(client, privateKey, recipientPubKey,
 export async function sendFederationResponse(client, privateKey, recipientPubKey, response) {
   try {
     const content = JSON.stringify(response);
-    const encrypted = await encryptNIP04(privateKey, recipientPubKey, content);
+    const encrypted = encryptNIP44(privateKey, recipientPubKey, content);
     const event = createDMEvent(recipientPubKey, encrypted, privateKey);
 
     if (client?.publish) {
@@ -218,7 +221,16 @@ export function subscribeToFederationDMs(client, privateKey, publicKey, handlers
     if (!pTag || pTag[1] !== publicKey) return;
 
     try {
-      const decrypted = await decryptNIP04(privateKey, event.pubkey, event.content);
+      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') {

package/src/index.js

@@ -170,6 +170,7 @@ class HoloSphereBase extends HoloSphereCore {
     }
 
     const path = storage.buildPath(this.config.appName, holonId, lensName, data.id);
+    this._log('DEBUG', 'write', { holonId, lensName, dataId: data.id, path });
     const existingData = await storage.read(this.client, path);
 
     // Handle hologram writes
@@ -286,10 +287,17 @@ class HoloSphereBase extends HoloSphereCore {
           data.target.lensName,
           data.target.dataId
         );
+        this._log('DEBUG', 'resolving hologram', {
+          hologramId: data.id,
+          sourcePath,
+          targetHolon: data.target.holonId,
+          targetLens: data.target.lensName,
+          targetDataId: data.target.dataId
+        });
 
         // Circular reference detection
         if (visited.has(sourcePath)) {
-          console.warn(`Circular hologram reference detected: ${sourcePath}`);
+          this._log('WARN', 'Circular hologram reference detected', { sourcePath });
           return null;
         }
         visited.add(sourcePath);
@@ -301,6 +309,7 @@ class HoloSphereBase extends HoloSphereCore {
         }
 
         const sourceData = await storage.read(this.client, sourcePath, resolveOptions);
+        this._log('DEBUG', 'hologram source fetched', { found: !!sourceData, sourcePath });
         if (sourceData) {
           // If source is also a hologram, recursively resolve it
           let resolvedSource = sourceData;
@@ -369,14 +378,19 @@ class HoloSphereBase extends HoloSphereCore {
 
     if (dataId) {
       const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+      this._log('DEBUG', 'read', { holonId, lensName, dataId, path });
       result = await storage.read(this.client, path);
+      this._log('DEBUG', 'read result', { found: !!result, isHologram: result?.hologram === true });
     } else {
       const path = storage.buildPath(this.config.appName, holonId, lensName);
+      this._log('DEBUG', 'readAll', { holonId, lensName, path });
       result = await storage.readAll(this.client, path);
+      this._log('DEBUG', 'readAll result', { count: Array.isArray(result) ? result.length : 0 });
     }
 
     const { resolveHolograms = true } = options;
-    if (resolveHolograms) {
+    if (resolveHolograms && result) {
+      this._log('DEBUG', 'resolving holograms', { itemCount: Array.isArray(result) ? result.length : 1 });
       result = await this._resolveHolograms(result);
     }
 

package/src/storage/backends/gundb-backend.js

@@ -25,28 +25,61 @@ export class GunDBBackend extends StorageBackend {
     // Subscription tracking
     this.subscriptions = new Map();
     this.subscriptionCounter = 0;
+
+    // Write cache for immediate consistency
+    // Gun's readAll/map().once() doesn't immediately see new writes - this cache bridges that gap
+    this.writeCache = new Map(); // path -> Map(id -> {data, timestamp})
+    this.writeCacheTTL = 300000; // Cache entries expire after 5 minutes (increased from 30s)
+
+    // Pending writes queue for retry
+    this.pendingWrites = new Map(); // path -> {data, retries, lastAttempt}
+    this.maxWriteRetries = 5;
+    this.writeRetryInterval = 10000; // 10 seconds between retries
   }
 
   async init() {
     // Dynamically import Gun to avoid issues if not installed
     let Gun;
     try {
+      console.log('[gundb-backend] Importing Gun...');
       const gunModule = await import('gun');
       Gun = gunModule.default || gunModule;
+      console.log('[gundb-backend] Gun imported:', typeof Gun);
     } catch (error) {
       throw new Error(
         'GunDB backend requires the "gun" package. Install it with: npm install gun'
       );
     }
 
+    // In Node.js, Gun needs a file path for radisk persistence
+    // Default to 'radata' if not specified
+    const dataDir = this.config.dataDir || 'radata';
+
     const gunConfig = {
       peers: this.config.peers || [],
       radisk: this.config.radisk !== false,
       localStorage: this.config.localStorage !== false,
-      file: this.config.dataDir,
+      file: dataDir,
     };
 
+    console.log('[gundb-backend] Gun config:', JSON.stringify(gunConfig));
+
     this.gun = Gun(gunConfig);
+    console.log('[gundb-backend] Gun instance created:', !!this.gun);
+
+    // Test basic Gun functionality
+    try {
+      const testKey = `_test_${Date.now()}`;
+      this.gun.get(testKey).put({ test: true }, (ack) => {
+        console.log('[gundb-backend] Gun test write ack:', ack);
+      });
+      console.log('[gundb-backend] Gun test write initiated');
+    } catch (e) {
+      console.error('[gundb-backend] Gun test write failed:', e.message);
+    }
+
+    // Add a small delay to let Gun initialize
+    await new Promise(resolve => setTimeout(resolve, 500));
 
     // Generate or use provided key pair using Gun's SEA
     try {
@@ -82,6 +115,111 @@ export class GunDBBackend extends StorageBackend {
     await this.schemaValidator.init();
   }
 
+  // ============================================================================
+  // WRITE CACHE (for immediate consistency)
+  // ============================================================================
+
+  /**
+   * Add item to the local write cache for immediate consistency
+   * @private
+   */
+  _addToWriteCache(path, data) {
+    if (!data || !data.id) return;
+
+    // Extract the parent path (without the data id)
+    const parentPath = path.substring(0, path.lastIndexOf('/'));
+    if (!parentPath) return;
+
+    if (!this.writeCache.has(parentPath)) {
+      this.writeCache.set(parentPath, new Map());
+    }
+
+    const pathCache = this.writeCache.get(parentPath);
+    pathCache.set(data.id.toString(), {
+      data: data,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Remove item from write cache (e.g., on delete)
+   * @private
+   */
+  _removeFromWriteCache(path, id) {
+    // Extract the parent path
+    const parentPath = path.substring(0, path.lastIndexOf('/'));
+    const pathCache = this.writeCache.get(parentPath);
+    if (pathCache) {
+      pathCache.delete(id.toString());
+    }
+  }
+
+  /**
+   * Get cached writes for a path, filtering out expired entries
+   * @private
+   */
+  _getWriteCacheEntries(path) {
+    const pathCache = this.writeCache.get(path);
+    if (!pathCache) return [];
+
+    const now = Date.now();
+    const validEntries = [];
+
+    for (const [id, entry] of pathCache) {
+      if (now - entry.timestamp < this.writeCacheTTL) {
+        validEntries.push(entry.data);
+      } else {
+        // Clean up expired entries
+        pathCache.delete(id);
+      }
+    }
+
+    return validEntries;
+  }
+
+  /**
+   * Merge cached writes with results from Gun
+   * @private
+   */
+  _mergeWithWriteCache(path, gunResults) {
+    const cachedWrites = this._getWriteCacheEntries(path);
+    if (cachedWrites.length === 0) return gunResults;
+
+    // Create a map by ID for deduplication
+    const resultMap = new Map();
+
+    // Add Gun results first
+    for (const item of gunResults) {
+      if (item && item.id) {
+        resultMap.set(item.id.toString(), item);
+      }
+    }
+
+    // Overlay cached writes (they're more recent)
+    for (const item of cachedWrites) {
+      if (item && item.id && !item._deleted) {
+        resultMap.set(item.id.toString(), item);
+      } else if (item && item.id && item._deleted) {
+        // Remove deleted items
+        resultMap.delete(item.id.toString());
+      }
+    }
+
+    return Array.from(resultMap.values());
+  }
+
+  /**
+   * Clear write cache for a specific path or all paths
+   * @param {string} [path] - Optional path to clear, clears all if not provided
+   */
+  clearWriteCache(path = null) {
+    if (path) {
+      this.writeCache.delete(path);
+    } else {
+      this.writeCache.clear();
+    }
+  }
+
   // ============================================================================
   // PATH BUILDING
   // ============================================================================
@@ -116,7 +254,59 @@ export class GunDBBackend extends StorageBackend {
       }
     }
 
-    return wrapper.write(this.gun, path, data);
+    // Add to write cache FIRST for immediate consistency
+    // This ensures readAll returns the new data even if Gun write is slow/times out
+    this._addToWriteCache(path, data);
+
+    // Try to write to Gun with retry on timeout
+    const result = await this._writeWithRetry(path, data);
+
+    return result;
+  }
+
+  /**
+   * Write to Gun with automatic retry on timeout
+   * @private
+   */
+  async _writeWithRetry(path, data, attempt = 0) {
+    const result = await wrapper.write(this.gun, path, data);
+
+    if (result.timeout && attempt < this.maxWriteRetries) {
+      // Queue for background retry
+      this.pendingWrites.set(path, {
+        data,
+        retries: attempt + 1,
+        lastAttempt: Date.now()
+      });
+
+      // Schedule retry
+      this._scheduleRetry(path);
+    } else if (!result.timeout) {
+      // Success - remove from pending
+      this.pendingWrites.delete(path);
+    }
+
+    return result;
+  }
+
+  /**
+   * Schedule a background retry for a pending write
+   * @private
+   */
+  _scheduleRetry(path) {
+    setTimeout(async () => {
+      const pending = this.pendingWrites.get(path);
+      if (!pending) return;
+
+      if (pending.retries >= this.maxWriteRetries) {
+        console.warn(`[gundb-backend] Max retries reached for: ${path}`);
+        this.pendingWrites.delete(path);
+        return;
+      }
+
+      console.log(`[gundb-backend] Retrying write (attempt ${pending.retries + 1}): ${path}`);
+      await this._writeWithRetry(path, pending.data, pending.retries);
+    }, this.writeRetryInterval);
   }
 
   async read(path, options = {}) {
@@ -131,7 +321,10 @@ export class GunDBBackend extends StorageBackend {
   }
 
   async readAll(path, options = {}) {
-    const items = await wrapper.readAll(this.gun, path);
+    const gunItems = await wrapper.readAll(this.gun, path);
+
+    // Merge with write cache for immediate consistency
+    const items = this._mergeWithWriteCache(path, gunItems);
 
     // Resolve references if requested
     if (options.resolveReferences) {
@@ -157,7 +350,24 @@ export class GunDBBackend extends StorageBackend {
   }
 
   async delete(path) {
-    return wrapper.deleteData(this.gun, path);
+    const result = await wrapper.deleteData(this.gun, path);
+
+    // Extract id from path and mark as deleted in cache
+    const pathParts = path.split('/');
+    const id = pathParts[pathParts.length - 1];
+    if (id) {
+      // Add tombstone to cache so readAll doesn't return this item
+      const parentPath = path.substring(0, path.lastIndexOf('/'));
+      if (!this.writeCache.has(parentPath)) {
+        this.writeCache.set(parentPath, new Map());
+      }
+      this.writeCache.get(parentPath).set(id.toString(), {
+        data: { id, _deleted: true },
+        timestamp: Date.now()
+      });
+    }
+
+    return result;
   }
 
   async deleteAll(path) {
@@ -180,7 +390,62 @@ export class GunDBBackend extends StorageBackend {
   // ============================================================================
 
   async writeGlobal(tableName, data) {
-    return wrapper.writeGlobal(this.gun, this.appName, tableName, data);
+    // Add to write cache FIRST for immediate consistency
+    // This ensures readAllGlobal returns the new data even if Gun write is slow/times out
+    const path = this.buildGlobalPath(tableName, data.id);
+    this._addToWriteCache(path, data);
+
+    // Try to write to Gun with retry on timeout
+    const result = await this._writeGlobalWithRetry(tableName, data);
+
+    return result;
+  }
+
+  /**
+   * Write to global table with automatic retry on timeout
+   * @private
+   */
+  async _writeGlobalWithRetry(tableName, data, attempt = 0) {
+    const path = this.buildGlobalPath(tableName, data.id);
+    const result = await wrapper.writeGlobal(this.gun, this.appName, tableName, data);
+
+    if (result.timeout && attempt < this.maxWriteRetries) {
+      // Queue for background retry
+      this.pendingWrites.set(path, {
+        data: { tableName, data },
+        isGlobal: true,
+        retries: attempt + 1,
+        lastAttempt: Date.now()
+      });
+
+      // Schedule retry
+      this._scheduleGlobalRetry(path, tableName);
+    } else if (!result.timeout) {
+      // Success - remove from pending
+      this.pendingWrites.delete(path);
+    }
+
+    return result;
+  }
+
+  /**
+   * Schedule a background retry for a pending global write
+   * @private
+   */
+  _scheduleGlobalRetry(path, tableName) {
+    setTimeout(async () => {
+      const pending = this.pendingWrites.get(path);
+      if (!pending || !pending.isGlobal) return;
+
+      if (pending.retries >= this.maxWriteRetries) {
+        console.warn(`[gundb-backend] Max retries reached for global: ${path}`);
+        this.pendingWrites.delete(path);
+        return;
+      }
+
+      console.log(`[gundb-backend] Retrying global write (attempt ${pending.retries + 1}): ${path}`);
+      await this._writeGlobalWithRetry(tableName, pending.data.data, pending.retries);
+    }, this.writeRetryInterval);
   }
 
   async readGlobal(tableName, key) {
@@ -188,11 +453,27 @@ export class GunDBBackend extends StorageBackend {
   }
 
   async readAllGlobal(tableName, timeout = 5000) {
-    return wrapper.readAllGlobal(this.gun, this.appName, tableName, timeout);
+    const gunItems = await wrapper.readAllGlobal(this.gun, this.appName, tableName, timeout);
+
+    // Merge with write cache for immediate consistency
+    const path = this.buildGlobalPath(tableName);
+    return this._mergeWithWriteCache(path, gunItems);
   }
 
   async deleteGlobal(tableName, key) {
-    return wrapper.deleteGlobal(this.gun, this.appName, tableName, key);
+    const result = await wrapper.deleteGlobal(this.gun, this.appName, tableName, key);
+
+    // Mark as deleted in cache
+    const path = this.buildGlobalPath(tableName);
+    if (!this.writeCache.has(path)) {
+      this.writeCache.set(path, new Map());
+    }
+    this.writeCache.get(path).set(key.toString(), {
+      data: { id: key, _deleted: true },
+      timestamp: Date.now()
+    });
+
+    return result;
   }
 
   async deleteAllGlobal(tableName) {
@@ -517,12 +798,15 @@ export class GunDBBackend extends StorageBackend {
       this.schemaValidator.clearCache();
     }
 
-    // 3. Logout auth
+    // 3. Clear write cache
+    this.writeCache.clear();
+
+    // 4. Logout auth
     if (this.auth) {
       this.auth.logout();
     }
 
-    // 4. Clean up Gun connections
+    // 5. Clean up Gun connections
     if (this.gun) {
       try {
         // Clean up mesh connections