holosphere 2.0.0-alpha1 → 2.0.0-alpha11

package/src/lib/federation-methods.js

@@ -0,0 +1,345 @@
+/**
+ * @fileoverview Federation methods mixin for cross-HoloSphere federation and Nostr discovery.
+ * Provides federated data access, capability-based authorization, and federation request protocols
+ * for connecting multiple HoloSphere instances.
+ * @module lib/federation-methods
+ */
+
+import * as registry from '../federation/registry.js';
+import * as discovery from '../federation/discovery.js';
+import * as federation from '../federation/hologram.js';
+import * as storage from '../storage/unified-storage.js';
+import * as nostrAsync from '../storage/nostr-async.js';
+import * as crypto from '../crypto/secp256k1.js';
+import { ValidationError, AuthorizationError } from './errors.js';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+
+/**
+ * Mixin that adds federation methods to a HoloSphere class.
+ * Enables cross-HoloSphere federation with capability-based access control,
+ * hologram creation, and Nostr-based discovery protocols.
+ * @param {Class} Base - Base class to extend
+ * @returns {Class} Extended class with federation methods
+ */
+export function withFederationMethods(Base) {
+  return class extends Base {
+    // === Cross-Holosphere Federation ===
+
+    /**
+     * Add a federated HoloSphere partner by public key.
+     * @param {string} pubKey - Public key (hex) of the federated HoloSphere
+     * @param {Object} [options={}] - Federation options (metadata, capabilities, etc.)
+     * @returns {Promise<Object>} Federation registration result
+     * @throws {ValidationError} If pubKey is invalid
+     */
+    async addFederatedHolosphere(pubKey, options = {}) {
+      if (!pubKey || typeof pubKey !== 'string') {
+        throw new ValidationError('pubKey must be a valid public key string');
+      }
+      return registry.addFederatedPartner(
+        this.client,
+        this.config.appName,
+        pubKey,
+        options
+      );
+    }
+
+    /**
+     * Remove a federated HoloSphere partner.
+     * @param {string} pubKey - Public key of the partner to remove
+     * @returns {Promise<void>}
+     */
+    async removeFederatedHolosphere(pubKey) {
+      return registry.removeFederatedPartner(
+        this.client,
+        this.config.appName,
+        pubKey
+      );
+    }
+
+    /**
+     * Get all federated HoloSphere public keys.
+     * @returns {Promise<string[]>} Array of federated public keys
+     */
+    async getFederatedHolospheres() {
+      return registry.getFederatedAuthors(
+        this.client,
+        this.config.appName
+      );
+    }
+
+    /**
+     * Get the complete federation registry.
+     * @returns {Promise<Object>} Federation registry with all partners and capabilities
+     */
+    async getFederationRegistry() {
+      return registry.getFederationRegistry(
+        this.client,
+        this.config.appName
+      );
+    }
+
+    /**
+     * Store an inbound capability token from a federated partner.
+     * @param {string} partnerPubKey - Partner's public key
+     * @param {Object} capabilityInfo - Capability token and metadata
+     * @returns {Promise<void>}
+     */
+    async storeInboundCapability(partnerPubKey, capabilityInfo) {
+      return registry.storeInboundCapability(
+        this.client,
+        this.config.appName,
+        partnerPubKey,
+        capabilityInfo
+      );
+    }
+
+    /**
+     * Read data from a federated source with capability verification.
+     * @param {string} sourcePubKey - Source HoloSphere public key
+     * @param {string} holonId - Holon ID to read from
+     * @param {string} lensName - Lens name to read from
+     * @param {string|null} [dataId=null] - Optional specific data ID (null for all)
+     * @returns {Promise<Object|Object[]>} Data from federated source
+     * @throws {AuthorizationError} If capability verification fails
+     */
+    async readFromFederatedSource(sourcePubKey, holonId, lensName, dataId = null) {
+      const capabilityEntry = await registry.getCapabilityForAuthor(
+        this.client,
+        this.config.appName,
+        sourcePubKey,
+        { holonId, lensName, dataId }
+      );
+
+      if (!capabilityEntry) {
+        throw new AuthorizationError('No valid capability for federated source', 'read');
+      }
+
+      const isValid = await this.verifyCapability(
+        capabilityEntry.token,
+        'read',
+        { holonId, lensName, dataId }
+      );
+
+      if (!isValid) {
+        throw new AuthorizationError('Capability verification failed', 'read');
+      }
+
+      if (dataId) {
+        const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+        return nostrAsync.nostrGet(this.client, path, 30000, {
+          authors: [sourcePubKey],
+          includeAuthor: true,
+        });
+      } else {
+        const path = storage.buildPath(this.config.appName, holonId, lensName);
+        return nostrAsync.nostrGetAll(this.client, path, 30000, {
+          authors: [sourcePubKey],
+          includeAuthor: true,
+        });
+      }
+    }
+
+    /**
+     * Create a cross-HoloSphere hologram reference.
+     * Links data from another HoloSphere into this one using capability-based access.
+     * @param {string} sourcePubKey - Source HoloSphere public key
+     * @param {string} sourceHolon - Source holon ID
+     * @param {string} lensName - Lens name
+     * @param {string} dataId - Data ID
+     * @param {string} targetHolon - Target holon in this HoloSphere
+     * @param {Object} [options={}] - Hologram options
+     * @param {boolean} [options.embedCapability=true] - Embed capability in hologram
+     * @returns {Promise<Object>} Created hologram
+     * @throws {AuthorizationError} If no valid capability exists
+     */
+    async createCrossHolosphereHologram(sourcePubKey, sourceHolon, lensName, dataId, targetHolon, options = {}) {
+      const { embedCapability = true } = options;
+
+      const capabilityEntry = await registry.getCapabilityForAuthor(
+        this.client,
+        this.config.appName,
+        sourcePubKey,
+        { holonId: sourceHolon, lensName, dataId }
+      );
+
+      if (!capabilityEntry) {
+        throw new AuthorizationError('No valid capability for cross-holosphere hologram', 'read');
+      }
+
+      const hologram = federation.createHologram(
+        sourceHolon,
+        targetHolon,
+        lensName,
+        dataId,
+        this.config.appName,
+        {
+          authorPubKey: sourcePubKey,
+          capability: embedCapability ? capabilityEntry.token : null,
+        }
+      );
+
+      const targetPath = storage.buildPath(this.config.appName, targetHolon, lensName, dataId);
+      await storage.write(this.client, targetPath, hologram);
+
+      return hologram;
+    }
+
+    /**
+     * Issue a capability token for federated access.
+     * Grants another HoloSphere permission to access data with specified scope.
+     * @param {string} targetPubKey - Target HoloSphere public key to grant access to
+     * @param {Object} scope - Access scope (holonId, lensName, dataId patterns)
+     * @param {string[]} permissions - Array of permissions ('read', 'write', etc.)
+     * @param {Object} [options={}] - Capability options
+     * @param {number} [options.expiresIn=3600000] - Expiration time in milliseconds
+     * @param {boolean} [options.trackInRegistry=true] - Store in federation registry
+     * @returns {Promise<string>} Capability token
+     */
+    async issueCapabilityForFederation(targetPubKey, scope, permissions, options = {}) {
+      const { expiresIn = 3600000, trackInRegistry = true } = options;
+
+      const token = await crypto.issueCapability(
+        permissions,
+        scope,
+        targetPubKey,
+        {
+          expiresIn,
+          issuerKey: this.client.privateKey,
+        }
+      );
+
+      if (trackInRegistry) {
+        const partner = await registry.getFederatedPartner(
+          this.client,
+          this.config.appName,
+          targetPubKey
+        );
+
+        if (!partner) {
+          await registry.addFederatedPartner(
+            this.client,
+            this.config.appName,
+            targetPubKey,
+            { addedVia: 'capability_issued' }
+          );
+        }
+
+        await registry.storeOutboundCapability(
+          this.client,
+          this.config.appName,
+          targetPubKey,
+          {
+            tokenHash: await this._hashToken(token),
+            scope,
+            permissions,
+            expires: Date.now() + expiresIn,
+          }
+        );
+      }
+
+      return token;
+    }
+
+    /**
+     * Hash a capability token for storage.
+     * @private
+     * @param {string} token - Capability token to hash
+     * @returns {Promise<string>} SHA256 hash of token
+     */
+    async _hashToken(token) {
+      const encoder = new TextEncoder();
+      return bytesToHex(sha256(encoder.encode(token)));
+    }
+
+    // === Nostr Discovery Protocol ===
+
+    /**
+     * Send a federation request to another HoloSphere via Nostr.
+     * @param {string} targetPubKey - Target HoloSphere public key
+     * @param {Object} [options={}] - Request options (message, metadata, etc.)
+     * @returns {Promise<Object>} Request event
+     */
+    async sendFederationRequest(targetPubKey, options = {}) {
+      return discovery.sendFederationRequest(
+        this.client,
+        this.config.appName,
+        targetPubKey,
+        options
+      );
+    }
+
+    /**
+     * Subscribe to incoming federation requests.
+     * @param {Function} callback - Callback function (request) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
+    async subscribeFederationRequests(callback) {
+      return discovery.subscribeFederationRequests(this.client, callback);
+    }
+
+    /**
+     * Accept a federation request and establish partnership.
+     * @param {Object} request - Federation request object
+     * @param {Object} [options={}] - Acceptance options (capabilities to grant, etc.)
+     * @returns {Promise<Object>} Acceptance event
+     */
+    async acceptFederationRequest(request, options = {}) {
+      return discovery.acceptFederationRequest(
+        this.client,
+        this.config.appName,
+        request,
+        options
+      );
+    }
+
+    /**
+     * Decline a federation request.
+     * @param {Object} request - Federation request object
+     * @param {string} [reason=''] - Optional reason for declining
+     * @returns {Promise<Object>} Decline event
+     */
+    async declineFederationRequest(request, reason = '') {
+      return discovery.declineFederationRequest(
+        this.client,
+        this.config.appName,
+        request,
+        reason
+      );
+    }
+
+    /**
+     * Subscribe to federation request acceptances.
+     * @param {Function} callback - Callback function (acceptance) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
+    async subscribeFederationAcceptances(callback) {
+      return discovery.subscribeFederationAcceptances(
+        this.client,
+        this.config.appName,
+        callback
+      );
+    }
+
+    /**
+     * Subscribe to federation request declines.
+     * @param {Function} callback - Callback function (decline) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
+    async subscribeFederationDeclines(callback) {
+      return discovery.subscribeFederationDeclines(this.client, callback);
+    }
+
+    /**
+     * Get all pending federation requests.
+     * @param {Object} [options={}] - Query options (limit, since, etc.)
+     * @returns {Promise<Object[]>} Array of pending requests
+     */
+    async getPendingFederationRequests(options = {}) {
+      return discovery.getPendingFederationRequests(this.client, options);
+    }
+  };
+}
+
+export default withFederationMethods;

package/src/lib/index.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview HoloSphere library modules and mixin composition utilities.
+ * Exports AI, contract, and federation method mixins for extending the base HoloSphere class.
+ * @module lib/index
+ */
+
+export { withAIMethods } from './ai-methods.js';
+export { withContractMethods } from './contract-methods.js';
+export { withFederationMethods } from './federation-methods.js';
+export { AuthorizationError, ValidationError } from './errors.js';
+
+/**
+ * Compose multiple mixins into a single class.
+ * Applies mixins in order from left to right.
+ * @param {Class} BaseClass - Base class to extend
+ * @param {...Function} mixins - Mixin functions to apply sequentially
+ * @returns {Class} Composed class with all mixins applied
+ * @example
+ * const EnhancedClass = compose(BaseClass, withAIMethods, withContractMethods);
+ */
+export function compose(BaseClass, ...mixins) {
+  return mixins.reduce((acc, mixin) => mixin(acc), BaseClass);
+}
+
+export default {
+  withAIMethods,
+  withContractMethods,
+  withFederationMethods,
+  compose
+};

package/src/schema/validator.js

@@ -1,17 +1,36 @@
 /**
- * JSON Schema Validation with Ajv and caching
+ * @fileoverview JSON Schema Validation with Ajv and caching.
+ *
+ * Provides JSON Schema validation using Ajv (Another JSON Schema Validator)
+ * with schema compilation caching for improved performance on repeated validations.
+ *
+ * @module schema/validator
  */
 
 import Ajv from 'ajv';
 
+/** @type {Ajv} Ajv instance configured for validation */
 const ajv = new Ajv({ allErrors: true, strict: false });
+
+/** @type {Map<string, {validator: Function, timestamp: number}>} Schema cache */
 const schemaCache = new Map();
-const CACHE_TTL = 3600000; // 1 hour in milliseconds
+
+/** @constant {number} Cache TTL in milliseconds (1 hour) */
+const CACHE_TTL = 3600000;
 
 /**
- * Validation Error class
+ * Custom error class for validation failures.
+ *
+ * @class ValidationError
+ * @extends Error
  */
 export class ValidationError extends Error {
+  /**
+   * Creates a new ValidationError.
+   *
+   * @param {string} message - Error message
+   * @param {Array} [errors=[]] - Array of Ajv error objects
+   */
   constructor(message, errors = []) {
     super(message);
     this.name = 'ValidationError';

package/src/spatial/h3-operations.js

@@ -1,3 +1,15 @@
+/**
+ * @fileoverview H3 Hexagonal Spatial Operations.
+ *
+ * Provides functions for working with H3 hexagonal hierarchical spatial indexing.
+ * H3 divides the world into hexagonal cells at 16 resolution levels (0-15),
+ * where resolution 0 covers the entire globe and resolution 15 provides
+ * approximately 0.5 square meter precision.
+ *
+ * @module spatial/h3-operations
+ * @see {@link https://h3geo.org/ H3 Spatial Indexing}
+ */
+
 import {
   latLngToCell,
   cellToParent,
@@ -7,7 +19,11 @@ import {
 } from 'h3-js';
 
 /**
- * Convert geographic coordinates to H3 holon ID
+ * Converts geographic coordinates to an H3 holon ID.
+ *
+ * @example
+ * // Get H3 cell for a location at resolution 9
+ * const holonId = toHolon(40.7128, -74.0060, 9); // New York City
  * @param {number} lat - Latitude (-90 to 90)
  * @param {number} lng - Longitude (-180 to 180)
  * @param {number} resolution - H3 resolution (0-15)
@@ -92,8 +108,8 @@ export function getChildren(holonId) {
  */
 export function isValidH3(holonId) {
   if (typeof holonId !== 'string') return false;
-  if (holonId.length < 15) return false;
-  if (!holonId.startsWith('8')) return false;
+  // H3 indexes are 15-character hex strings, but can vary slightly
+  // Use h3-js isValidCell for proper validation
   return isValidCell(holonId);
 }
 

package/src/storage/backend-factory.js

@@ -1,8 +1,13 @@
 /**
- * Factory for creating storage backends
- * Supports lazy loading of backend implementations
+ * @fileoverview Factory for Creating Storage Backends.
+ *
+ * Provides a factory pattern for creating and managing storage backend instances.
+ * Supports lazy loading of backend implementations to reduce initial bundle size.
+ *
+ * @module storage/backend-factory
  */
 
+/** @type {Object<string, string>} Map of backend types to their module paths */
 const BACKEND_MODULES = {
   nostr: './backends/nostr-backend.js',
   gundb: './backends/gundb-backend.js',

package/src/storage/backend-interface.js

@@ -1,8 +1,27 @@
 /**
- * Abstract Storage Backend Interface
- * All storage backends must implement this interface
+ * @fileoverview Abstract Storage Backend Interface.
+ *
+ * Defines the contract that all storage backends must implement.
+ * Provides a consistent API for CRUD operations, subscriptions,
+ * and data migration across different storage technologies.
+ *
+ * @module storage/backend-interface
+ */
+
+/**
+ * Abstract base class for storage backends.
+ * All concrete backends (Nostr, GunDB, ActivityPub) must extend this class.
+ *
+ * @abstract
+ * @class StorageBackend
  */
 export class StorageBackend {
+  /**
+   * Creates a new StorageBackend instance.
+   *
+   * @param {Object} config - Backend-specific configuration
+   * @throws {Error} If instantiated directly (abstract class)
+   */
   constructor(config) {
     if (new.target === StorageBackend) {
       throw new Error('StorageBackend is abstract and cannot be instantiated directly');

package/src/storage/backends/activitypub/server.js

@@ -1,19 +1,41 @@
 /**
- * Self-hosted ActivityPub server for HoloSphere
- * Provides federation with Mastodon, Pleroma, and other ActivityPub servers
+ * @fileoverview Self-hosted ActivityPub server for HoloSphere federation.
+ * Provides complete ActivityPub protocol support for federation with Mastodon, Pleroma,
+ * and other fediverse servers. Includes WebFinger, NodeInfo, actor endpoints, and SSE subscriptions.
+ * @module storage/backends/activitypub/server
  */
 
 import express from 'express';
 import crypto from 'crypto';
 import { createPersistentStorage } from '../../persistent-storage.js';
 
+/** @constant {string} ActivityStreams JSON-LD context */
 const ACTIVITY_STREAMS_CONTEXT = 'https://www.w3.org/ns/activitystreams';
+/** @constant {string} Security vocabulary JSON-LD context */
 const SECURITY_CONTEXT = 'https://w3id.org/security/v1';
 
 /**
- * ActivityPub Server for HoloSphere
+ * Self-hosted ActivityPub server for HoloSphere data federation.
+ * Implements WebFinger discovery, actor endpoints, inbox/outbox, and HoloSphere data API.
+ *
+ * @class ActivityPubServer
+ * @example
+ * const server = new ActivityPubServer({
+ *   port: 3000,
+ *   domain: 'holon.example.com',
+ *   dataDir: './data'
+ * });
+ * await server.start();
  */
 export class ActivityPubServer {
+  /**
+   * Create a new ActivityPub server instance.
+   * @param {Object} [config={}] - Server configuration
+   * @param {number} [config.port=3000] - HTTP port to listen on
+   * @param {string} [config.domain='localhost'] - Server domain for URLs
+   * @param {string} [config.protocol='http'] - Protocol (http or https)
+   * @param {string} [config.dataDir] - Data directory for persistent storage
+   */
   constructor(config = {}) {
     this.config = {
       port: config.port || 3000,

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

@@ -1,11 +1,34 @@
 /**
- * ActivityPub Storage Backend
- * Client adapter for connecting to an ActivityPub server
+ * @fileoverview ActivityPub storage backend client adapter.
+ * Provides HTTP-based connectivity to an ActivityPub server for federated data storage
+ * and real-time subscriptions via Server-Sent Events.
+ * @module storage/backends/activitypub-backend
  */
 
 import { StorageBackend } from '../backend-interface.js';
 
+/**
+ * ActivityPub storage backend implementation.
+ * Client adapter for connecting to an ActivityPub server via HTTP API
+ * with SSE-based real-time subscriptions.
+ *
+ * @class ActivityPubBackend
+ * @extends StorageBackend
+ * @example
+ * const backend = await BackendFactory.create('activitypub', {
+ *   serverUrl: 'https://ap.example.com',
+ *   appName: 'myapp',
+ *   apiKey: 'secret-key'
+ * });
+ */
 export class ActivityPubBackend extends StorageBackend {
+  /**
+   * Create a new ActivityPub backend instance.
+   * @param {Object} config - Backend configuration
+   * @param {string} config.serverUrl - ActivityPub server URL
+   * @param {string} [config.appName='holosphere'] - Application/actor name
+   * @param {string} [config.apiKey] - Optional API key for authentication
+   */
   constructor(config) {
     super(config);
     this.serverUrl = config.serverUrl;