holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/storage/gun-auth.js

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview GunDB Authentication Handler.
+ *
+ * Handles user authentication and private data storage using Gun's user system.
+ * Private data is stored under: user.get('private').get(lens).get(key)
+ * Usernames are namespaced: ${appname}:${holonId}
+ *
+ * @module storage/gun-auth
+ */
+
+import { gunPromise, gunPut } from './gun-async.js';
+
+/**
+ * Authentication handler for GunDB backend.
+ *
+ * Manages user creation, authentication, and private data access.
+ *
+ * @class GunAuth
+ * @example
+ * const auth = new GunAuth(gun, 'myapp');
+ * await auth.createUser('holon123', 'password');
+ * await auth.authenticate('holon123', 'password');
+ */
+export class GunAuth {
+  /**
+   * Create a new authentication handler.
+   *
+   * @param {Object} gun - Gun instance
+   * @param {string} appname - Application namespace
+   */
+  constructor(gun, appname) {
+    this.gun = gun;
+    this.appname = appname;
+    this.user = null;
+    this.authenticated = false;
+    this.currentHolonId = null;
+  }
+
+  /**
+   * Generate a namespaced username for a holon
+   * @param {string} holonId - Holon ID
+   * @returns {string} Namespaced username
+   */
+  userName(holonId) {
+    return `${this.appname}:${holonId}`;
+  }
+
+  /**
+   * Authenticate a user for a specific holon
+   * @param {string} holonId - Holon ID
+   * @param {string} password - Password
+   * @returns {Promise<Object>} Authenticated user object
+   */
+  async authenticate(holonId, password) {
+    if (!holonId || !password) {
+      throw new Error('authenticate: holonId and password are required');
+    }
+
+    const username = this.userName(holonId);
+    this.user = this.gun.user();
+
+    return new Promise((resolve, reject) => {
+      this.user.auth(username, password, (ack) => {
+        if (ack.err) {
+          this.authenticated = false;
+          this.currentHolonId = null;
+          reject(new Error(ack.err));
+        } else {
+          this.authenticated = true;
+          this.currentHolonId = holonId;
+          resolve(this.user);
+        }
+      });
+    });
+  }
+
+  /**
+   * Create a new user for a holon
+   * @param {string} holonId - Holon ID
+   * @param {string} password - Password
+   * @returns {Promise<Object>} Created user object
+   */
+  async createUser(holonId, password) {
+    if (!holonId || !password) {
+      throw new Error('createUser: holonId and password are required');
+    }
+
+    const username = this.userName(holonId);
+    this.user = this.gun.user();
+
+    return new Promise((resolve, reject) => {
+      this.user.create(username, password, (ack) => {
+        if (ack.err) {
+          reject(new Error(ack.err));
+        } else {
+          // Auto-login after creation
+          this.user.auth(username, password, (authAck) => {
+            if (authAck.err) {
+              reject(new Error(authAck.err));
+            } else {
+              this.authenticated = true;
+              this.currentHolonId = holonId;
+              resolve(this.user);
+            }
+          });
+        }
+      });
+    });
+  }
+
+  /**
+   * Logout current user
+   */
+  logout() {
+    if (this.user) {
+      this.user.leave();
+    }
+    this.authenticated = false;
+    this.currentHolonId = null;
+    this.user = null;
+  }
+
+  /**
+   * Check if currently authenticated
+   * @returns {boolean} True if authenticated
+   */
+  isAuthenticated() {
+    return this.authenticated && this.user !== null;
+  }
+
+  /**
+   * Get the private data path for a lens and key
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key (optional)
+   * @returns {Object} Gun chain reference
+   */
+  getPrivatePath(lens, key = null) {
+    if (!this.isAuthenticated()) {
+      throw new Error('Not authenticated');
+    }
+
+    const basePath = this.user.get('private').get(lens);
+    return key ? basePath.get(key) : basePath;
+  }
+
+  /**
+   * Write data to private storage
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @param {Object} data - Data to write
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async writePrivate(lens, key, data) {
+    if (!this.isAuthenticated()) {
+      throw new Error('Not authenticated');
+    }
+
+    if (!data || !key) {
+      throw new Error('writePrivate: key and data are required');
+    }
+
+    try {
+      const serialized = JSON.stringify(data);
+      await gunPut(this.getPrivatePath(lens, key), serialized, 2000);
+      return true;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Read data from private storage
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @returns {Promise<Object|null>} Data or null if not found
+   */
+  async readPrivate(lens, key) {
+    if (!this.isAuthenticated()) {
+      throw new Error('Not authenticated');
+    }
+
+    try {
+      const rawData = await gunPromise(this.getPrivatePath(lens, key), 2000);
+
+      if (!rawData) {
+        return null;
+      }
+
+      // Deserialize - primary format is JSON string (like old holosphere)
+      if (typeof rawData === 'string') {
+        try {
+          return JSON.parse(rawData);
+        } catch (e) {
+          return rawData; // Return as-is if not valid JSON
+        }
+      }
+
+      // Legacy _json wrapper format
+      if (rawData._json && typeof rawData._json === 'string') {
+        try {
+          return JSON.parse(rawData._json);
+        } catch (e) {
+          return null;
+        }
+      }
+
+      // Plain object format
+      if (typeof rawData === 'object') {
+        const cleaned = { ...rawData };
+        delete cleaned['_'];
+        return cleaned;
+      }
+
+      return null;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Read all data from a private lens
+   * First gets count of items, then collects until count is reached
+   * @param {string} lens - Lens name
+   * @param {number} timeout - Timeout in ms (fallback)
+   * @returns {Promise<Object[]>} Array of data objects
+   */
+  async readAllPrivate(lens, timeout = 5000) {
+    if (!this.isAuthenticated()) {
+      throw new Error('Not authenticated');
+    }
+
+    return new Promise((resolve) => {
+      const results = [];
+      const seen = new Set();
+      const ref = this.getPrivatePath(lens);
+      let settled = false;
+      let expectedCount = 0;
+      let receivedCount = 0;
+
+      const tryResolve = () => {
+        if (settled) return;
+        if (expectedCount > 0 && receivedCount >= expectedCount) {
+          settled = true;
+          resolve(results);
+        }
+      };
+
+      const parseItem = (data) => {
+        if (!data) return null;
+        let parsed = null;
+        // Primary: JSON string format (like old holosphere)
+        if (typeof data === 'string') {
+          try {
+            parsed = JSON.parse(data);
+          } catch (e) {
+            parsed = data;
+          }
+        // Legacy: _json wrapper format
+        } else if (data._json && typeof data._json === 'string') {
+          try {
+            parsed = JSON.parse(data._json);
+          } catch (e) {}
+        // Plain object
+        } else if (typeof data === 'object') {
+          parsed = { ...data };
+          delete parsed['_'];
+        }
+        return parsed;
+      };
+
+      // Step 1: Get parent to count expected items
+      ref.once((parentData) => {
+        if (settled) return;
+
+        if (!parentData) {
+          settled = true;
+          resolve([]);
+          return;
+        }
+
+        const keys = Object.keys(parentData).filter(k => k !== '_');
+        if (keys.length === 0) {
+          settled = true;
+          resolve([]);
+          return;
+        }
+
+        // Pre-parse inline items (not Gun references)
+        for (const key of keys) {
+          const rawItem = parentData[key];
+          if (!rawItem) continue;
+
+          // Skip Gun references - will be fetched via map().once()
+          if (typeof rawItem === 'object' && rawItem['#']) continue;
+
+          const parsed = parseItem(rawItem);
+          if (parsed && !parsed._deleted && !seen.has(key)) {
+            seen.add(key);
+            results.push(parsed);
+          }
+        }
+
+        // Expected count is ALL keys (map().once() fires for all)
+        expectedCount = keys.length;
+
+        // Step 2: Collect items via map().once(), counting as we go
+        ref.map().once((data, key) => {
+          if (settled || !data || key.startsWith('_')) return;
+
+          // Count every item, but only add if not already seen
+          if (!seen.has(key)) {
+            seen.add(key);
+            const parsed = parseItem(data);
+            if (parsed && !parsed._deleted) {
+              results.push(parsed);
+            }
+          }
+          receivedCount++;
+          tryResolve();
+        });
+      });
+
+      // Fallback timeout
+      setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          resolve(results);
+        }
+      }, timeout);
+    });
+  }
+
+  /**
+   * Delete data from private storage
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async deletePrivate(lens, key) {
+    if (!this.isAuthenticated()) {
+      throw new Error('Not authenticated');
+    }
+
+    try {
+      // Get existing data to preserve ID
+      const existing = await this.readPrivate(lens, key);
+
+      // Create tombstone
+      const tombstone = {
+        id: existing?.id || key,
+        _deleted: true,
+        _deletedAt: Date.now()
+      };
+
+      await gunPut(this.getPrivatePath(lens, key), JSON.stringify(tombstone));
+      return true;
+    } catch (error) {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Create an authentication handler instance
+ * @param {Object} gun - Gun instance
+ * @param {string} appname - Application namespace
+ * @returns {GunAuth} Auth handler instance
+ */
+export function createAuthHandler(gun, appname) {
+  return new GunAuth(gun, appname);
+}
+
+export default GunAuth;