holosphere 2.0.0-alpha1 → 2.0.0-alpha4

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

@@ -1,17 +1,30 @@
 /**
  * GunDB Storage Backend
- * Wraps existing gun-wrapper.js as a StorageBackend
+ * Full-featured backend with authentication, schema validation, references, and global tables
  */
 
 import { StorageBackend } from '../backend-interface.js';
 import * as wrapper from '../gun-wrapper.js';
 import { gunPromise, gunPut, gunMap, gunCollect } from '../gun-async.js';
+import { GunReferenceHandler } from '../gun-references.js';
+import { GunAuth } from '../gun-auth.js';
+import { GunSchemaValidator } from '../gun-schema.js';
 
 export class GunDBBackend extends StorageBackend {
   constructor(config) {
     super(config);
     this.gun = null;
     this.keyPair = null;
+    this.appName = config.appName || 'holosphere';
+
+    // New modules
+    this.references = null;
+    this.auth = null;
+    this.schemaValidator = null;
+
+    // Subscription tracking
+    this.subscriptions = new Map();
+    this.subscriptionCounter = 0;
   }
 
   async init() {
@@ -50,28 +63,93 @@ export class GunDBBackend extends StorageBackend {
         }
       } else {
         // SEA not available, use simple identifier
-        this.publicKey = this.config.appName || 'gundb-user';
+        this.publicKey = this.appName;
       }
     } catch (error) {
       // SEA might not be loaded
-      this.publicKey = this.config.appName || 'gundb-user';
+      this.publicKey = this.appName;
     }
+
+    // Initialize modules
+    this.references = new GunReferenceHandler(this.appName);
+    this.auth = new GunAuth(this.gun, this.appName);
+    this.schemaValidator = new GunSchemaValidator({
+      strict: this.config.strict || false,
+      cacheMaxAge: this.config.schemaCacheMaxAge || 3600000
+    });
+
+    // Try to initialize schema validator (may fail if AJV not installed)
+    await this.schemaValidator.init();
   }
 
+  // ============================================================================
+  // PATH BUILDING
+  // ============================================================================
+
   buildPath(appName, holonId, lensName, key = null) {
     return wrapper.buildPath(appName, holonId, lensName, key);
   }
 
+  buildGlobalPath(tableName, key = null) {
+    return wrapper.buildGlobalPath(this.appName, tableName, key);
+  }
+
+  // ============================================================================
+  // BASIC CRUD OPERATIONS
+  // ============================================================================
+
   async write(path, data, options = {}) {
+    // Validate against schema if strict mode
+    if (this.schemaValidator && this.schemaValidator.isStrict()) {
+      const pathParts = path.split('/');
+      if (pathParts.length >= 3) {
+        const lens = pathParts[2];
+        // Skip validation for references
+        if (!this.isReference(data)) {
+          const result = await this.schemaValidator.validateData(
+            this.gun, this.appName, lens, data
+          );
+          if (!result.valid) {
+            throw new Error(`Schema validation failed: ${JSON.stringify(result.errors)}`);
+          }
+        }
+      }
+    }
+
     return wrapper.write(this.gun, path, data);
   }
 
   async read(path, options = {}) {
-    return wrapper.read(this.gun, path);
+    const data = await wrapper.read(this.gun, path);
+
+    // Resolve references if requested
+    if (data && options.resolveReferences && this.isReference(data)) {
+      return this.resolveReference(data);
+    }
+
+    return data;
   }
 
   async readAll(path, options = {}) {
-    return wrapper.readAll(this.gun, path);
+    const items = await wrapper.readAll(this.gun, path);
+
+    // Resolve references if requested
+    if (options.resolveReferences) {
+      const resolved = [];
+      for (const item of items) {
+        if (this.isReference(item)) {
+          const resolvedItem = await this.resolveReference(item);
+          if (resolvedItem) {
+            resolved.push(resolvedItem);
+          }
+        } else {
+          resolved.push(item);
+        }
+      }
+      return resolved;
+    }
+
+    return items;
   }
 
   async update(path, updates) {
@@ -83,7 +161,6 @@ export class GunDBBackend extends StorageBackend {
   }
 
   async deleteAll(path) {
-    // Gun doesn't have a native deleteAll, so we iterate and delete
     const items = await this.readAll(path);
     let count = 0;
 
@@ -98,58 +175,272 @@ export class GunDBBackend extends StorageBackend {
     return { success: true, count };
   }
 
+  // ============================================================================
+  // GLOBAL TABLE OPERATIONS
+  // ============================================================================
+
+  async writeGlobal(tableName, data) {
+    return wrapper.writeGlobal(this.gun, this.appName, tableName, data);
+  }
+
+  async readGlobal(tableName, key) {
+    return wrapper.readGlobal(this.gun, this.appName, tableName, key);
+  }
+
+  async readAllGlobal(tableName, timeout = 5000) {
+    return wrapper.readAllGlobal(this.gun, this.appName, tableName, timeout);
+  }
+
+  async deleteGlobal(tableName, key) {
+    return wrapper.deleteGlobal(this.gun, this.appName, tableName, key);
+  }
+
+  async deleteAllGlobal(tableName) {
+    return wrapper.deleteAllGlobal(this.gun, this.appName, tableName);
+  }
+
+  // ============================================================================
+  // REFERENCE OPERATIONS
+  // ============================================================================
+
+  /**
+   * Create a reference to data
+   */
+  createReference(holon, lens, data) {
+    return this.references.createReference(holon, lens, data);
+  }
+
+  /**
+   * Check if data is a reference
+   */
+  isReference(data) {
+    return this.references.isReference(data);
+  }
+
+  /**
+   * Resolve a reference to get actual data
+   */
+  async resolveReference(reference, options = {}) {
+    return this.references.resolveReference(this.gun, reference, options);
+  }
+
+  /**
+   * Parse a soul path
+   */
+  parseSoulPath(soul) {
+    return this.references.parseSoulPath(soul);
+  }
+
+  /**
+   * Get soul for data
+   */
+  getSoul(holon, lens, key) {
+    return this.references.getSoul(holon, lens, key);
+  }
+
+  // ============================================================================
+  // AUTHENTICATION OPERATIONS
+  // ============================================================================
+
+  /**
+   * Authenticate for a holon
+   */
+  async authenticate(holonId, password) {
+    return this.auth.authenticate(holonId, password);
+  }
+
+  /**
+   * Create a new user
+   */
+  async createUser(holonId, password) {
+    return this.auth.createUser(holonId, password);
+  }
+
+  /**
+   * Logout current user
+   */
+  logout() {
+    this.auth.logout();
+  }
+
+  /**
+   * Check if authenticated
+   */
+  isAuthenticated() {
+    return this.auth.isAuthenticated();
+  }
+
+  /**
+   * Write to private storage
+   */
+  async writePrivate(lens, key, data) {
+    return this.auth.writePrivate(lens, key, data);
+  }
+
+  /**
+   * Read from private storage
+   */
+  async readPrivate(lens, key) {
+    return this.auth.readPrivate(lens, key);
+  }
+
+  /**
+   * Read all from private lens
+   */
+  async readAllPrivate(lens, timeout = 2000) {
+    return this.auth.readAllPrivate(lens, timeout);
+  }
+
+  /**
+   * Delete from private storage
+   */
+  async deletePrivate(lens, key) {
+    return this.auth.deletePrivate(lens, key);
+  }
+
+  // ============================================================================
+  // SCHEMA OPERATIONS
+  // ============================================================================
+
+  /**
+   * Set a schema for a lens
+   */
+  async setSchema(lens, schema) {
+    return this.schemaValidator.setSchema(this.gun, this.appName, lens, schema);
+  }
+
+  /**
+   * Get a schema for a lens
+   */
+  async getSchema(lens, options = {}) {
+    return this.schemaValidator.getSchema(this.gun, this.appName, lens, options);
+  }
+
+  /**
+   * Get all schemas
+   */
+  async getAllSchemas() {
+    return this.schemaValidator.getAllSchemas(this.gun, this.appName);
+  }
+
+  /**
+   * Delete a schema
+   */
+  async deleteSchema(lens) {
+    return this.schemaValidator.deleteSchema(this.gun, this.appName, lens);
+  }
+
+  /**
+   * Validate data against a schema
+   */
+  validate(schema, data) {
+    return this.schemaValidator.validate(schema, data);
+  }
+
+  /**
+   * Validate data against a lens schema
+   */
+  async validateData(lens, data) {
+    return this.schemaValidator.validateData(this.gun, this.appName, lens, data);
+  }
+
+  /**
+   * Clear schema cache
+   */
+  clearSchemaCache(lens = null) {
+    this.schemaValidator.clearCache(lens);
+  }
+
+  // ============================================================================
+  // SUBSCRIPTIONS
+  // ============================================================================
+
   async subscribe(path, callback, options = {}) {
-    // Determine if this is a prefix subscription (no key) or single item
+    const subscriptionId = ++this.subscriptionCounter;
     const pathParts = path.split('/');
     const isPrefix = pathParts.length <= 3;
 
+    const subscription = {
+      id: subscriptionId,
+      path,
+      active: true,
+      gunRef: null
+    };
+
     if (isPrefix) {
-      // Subscribe to all items under this prefix
       const ref = this.gun.get(path);
-      const handlers = [];
+      subscription.gunRef = ref;
+
+      ref.map().on(async (data, key) => {
+        if (!this.subscriptions.get(subscriptionId)?.active) return;
+        if (!data || key.startsWith('_') || data._deleted) return;
+
+        // Parse data
+        let parsed = wrapper.parse(data);
+        if (!parsed) return;
 
-      ref.map().on((data, key) => {
-        if (data && !key.startsWith('_') && !data._deleted) {
-          callback(data, key);
+        // Resolve references if requested
+        if (options.resolveReferences && this.isReference(parsed)) {
+          parsed = await this.resolveReference(parsed);
+        }
+
+        if (parsed) {
+          callback(parsed, key);
         }
       });
+    } else {
+      const ref = this.gun.get(path);
+      subscription.gunRef = ref;
 
-      // Store reference for cleanup
-      handlers.push(ref);
+      ref.on(async (data, key) => {
+        if (!this.subscriptions.get(subscriptionId)?.active) return;
+        if (!data) return;
 
-      return {
-        unsubscribe: () => {
-          handlers.forEach(h => {
-            try {
-              h.off();
-            } catch (e) {
-              // Ignore cleanup errors
-            }
-          });
-        },
-      };
-    } else {
-      // Subscribe to single item
-      const unsubFn = wrapper.subscribe(this.gun, path, callback);
-      return {
-        unsubscribe: typeof unsubFn === 'function' ? unsubFn : () => {},
-      };
+        let parsed = wrapper.parse(data);
+        if (!parsed || parsed._deleted) return;
+
+        if (options.resolveReferences && this.isReference(parsed)) {
+          parsed = await this.resolveReference(parsed);
+        }
+
+        if (parsed) {
+          callback(parsed, key);
+        }
+      });
     }
+
+    this.subscriptions.set(subscriptionId, subscription);
+
+    return {
+      id: subscriptionId,
+      unsubscribe: () => {
+        const sub = this.subscriptions.get(subscriptionId);
+        if (sub) {
+          sub.active = false;
+          if (sub.gunRef) {
+            try {
+              sub.gunRef.off();
+            } catch (e) {}
+          }
+          this.subscriptions.delete(subscriptionId);
+        }
+      }
+    };
   }
 
+  // ============================================================================
+  // EXPORT/IMPORT
+  // ============================================================================
+
   async exportData(pathPrefix = '') {
     const records = [];
-
-    // Get the app-level data
-    const appName = this.config.appName || 'holosphere';
-    const basePath = pathPrefix || appName;
+    const basePath = pathPrefix || this.appName;
 
     try {
       const items = await gunMap(this.gun.get(basePath), 2000);
 
       for (const [key, data] of Object.entries(items)) {
         if (!key.startsWith('_') && data && typeof data === 'object' && !data._deleted) {
-          // Recursively collect nested data
           await this._collectRecords(basePath, key, data, records);
         }
       }
@@ -164,14 +455,12 @@ export class GunDBBackend extends StorageBackend {
     const currentPath = `${basePath}/${key}`;
 
     if (data.id) {
-      // This is a leaf data node
       records.push({
         path: currentPath,
         data: this._cleanGunData(data),
         timestamp: data._meta?.timestamp || Date.now(),
       });
     } else {
-      // This might be a nested structure, explore further
       try {
         const nested = await gunMap(this.gun.get(currentPath), 500);
         for (const [nestedKey, nestedData] of Object.entries(nested)) {
@@ -179,14 +468,11 @@ export class GunDBBackend extends StorageBackend {
             await this._collectRecords(currentPath, nestedKey, nestedData, records);
           }
         }
-      } catch (e) {
-        // Ignore nested exploration errors
-      }
+      } catch (e) {}
     }
   }
 
   _cleanGunData(data) {
-    // Remove Gun's internal metadata
     const cleaned = { ...data };
     delete cleaned['_'];
     return cleaned;
@@ -208,14 +494,56 @@ export class GunDBBackend extends StorageBackend {
     return results;
   }
 
+  // ============================================================================
+  // LIFECYCLE
+  // ============================================================================
+
   close() {
-    // Gun doesn't have explicit close, but we can try to clean up
+    // 1. Unsubscribe all active subscriptions
+    for (const [id, subscription] of this.subscriptions) {
+      if (subscription.active) {
+        subscription.active = false;
+        if (subscription.gunRef) {
+          try {
+            subscription.gunRef.off();
+          } catch (e) {}
+        }
+      }
+    }
+    this.subscriptions.clear();
+
+    // 2. Clear schema cache
+    if (this.schemaValidator) {
+      this.schemaValidator.clearCache();
+    }
+
+    // 3. Logout auth
+    if (this.auth) {
+      this.auth.logout();
+    }
+
+    // 4. Clean up Gun connections
     if (this.gun) {
       try {
-        // Attempt to close any connections
+        // Clean up mesh connections
+        const mesh = this.gun.back('opt.mesh');
+        if (mesh) {
+          if (mesh.way) {
+            Object.values(mesh.way).forEach(conn => {
+              if (conn?.wire?.close) conn.wire.close();
+            });
+          }
+          if (mesh.opt?.peers) mesh.opt.peers = {};
+        }
+
+        // Close web server if present
+        const server = this.gun.back('opt.web');
+        if (server?.close) server.close();
+
+        // Turn off all listeners
         this.gun.off();
-      } catch (e) {
-        // Ignore cleanup errors
+      } catch (error) {
+        console.warn('Error during Gun cleanup:', error);
       }
     }
   }
@@ -226,6 +554,9 @@ export class GunDBBackend extends StorageBackend {
       publicKey: this.publicKey,
       peers: this.config.peers || [],
       connected: !!this.gun,
+      authenticated: this.isAuthenticated(),
+      subscriptionCount: this.subscriptions.size,
+      schemaValidationEnabled: this.schemaValidator?.isStrict() || false
     };
   }
 }

package/src/storage/global-tables.js

@@ -3,7 +3,7 @@
  * Non-location-specific storage (FR-044, FR-045)
  */
 
-import { write, read, readAll, update, deleteData, deleteAll } from './nostr-wrapper.js';
+import { write, read, readAll, update, deleteData, deleteAll, subscribe } from './unified-storage.js';
 
 /**
  * Write data to global table
@@ -79,3 +79,30 @@ export async function deleteAllGlobal(client, appname, table) {
   const path = `${appname}/${table}`;
   return deleteAll(client, path);
 }
+
+/**
+ * Get all data from global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @returns {Promise<Object[]>} Array of data objects
+ */
+export async function getAllGlobal(client, appname, table) {
+  const path = `${appname}/${table}`;
+  return readAll(client, path);
+}
+
+/**
+ * Subscribe to global table changes
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @param {string} key - Data key (optional, if not provided subscribes to all)
+ * @param {Function} callback - Called on data changes
+ * @param {Object} options - Subscription options
+ * @returns {Promise<Object>} Subscription object with unsubscribe method
+ */
+export async function subscribeGlobal(client, appname, table, key, callback, options = {}) {
+  const path = key ? `${appname}/${table}/${key}` : `${appname}/${table}`;
+  return subscribe(client, path, callback, options);
+}