holosphere 1.1.19 → 2.0.0-alpha0

package/src/content/social-protocols.js

@@ -0,0 +1,168 @@
+/**
+ * Social Protocol Adapters (Nostr, ActivityPub)
+ */
+
+// Import ValidationError from the validator module
+import { ValidationError } from '../schema/validator.js';
+
+/**
+ * Validate Nostr NIP-01 event format
+ * @param {Object} event - Nostr event
+ * @param {boolean} partial - Allow partial events (missing id, pubkey, sig)
+ * @returns {boolean} True if valid
+ * @throws {ValidationError} If strict validation fails
+ */
+export function validateNostrEvent(event, partial = true, throwOnError = false) {
+  if (!event || typeof event !== 'object') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format');
+    return false;
+  }
+
+  // Required fields always
+  if (typeof event.kind !== 'number') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - kind must be a number');
+    return false;
+  }
+  if (!Array.isArray(event.tags)) {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - tags must be an array');
+    return false;
+  }
+  if (typeof event.content !== 'string') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - content must be a string');
+    return false;
+  }
+  if (typeof event.created_at !== 'number') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - created_at must be a number');
+    return false;
+  }
+
+  // Optional for partial events (will be added by system)
+  if (!partial) {
+    if (typeof event.id !== 'string') {
+      if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - id must be a string');
+      return false;
+    }
+    if (typeof event.pubkey !== 'string') {
+      if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - pubkey must be a string');
+      return false;
+    }
+    if (typeof event.sig !== 'string') {
+      if (throwOnError) throw new ValidationError('ValidationError: Invalid Nostr event format - sig must be a string');
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validate ActivityPub object format
+ * @param {Object} object - ActivityPub object
+ * @param {boolean} throwOnError - Throw ValidationError on failure
+ * @param {boolean} requireId - Require id field (default: false, will be auto-generated)
+ * @returns {boolean} True if valid
+ * @throws {ValidationError} If strict validation fails
+ */
+export function validateActivityPubObject(object, throwOnError = false, requireId = false) {
+  if (!object || typeof object !== 'object') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid ActivityPub object format');
+    return false;
+  }
+  if (!object['@context']) {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid ActivityPub object format - @context is required');
+    return false;
+  }
+  if (typeof object.type !== 'string') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid ActivityPub object format - type must be a string');
+    return false;
+  }
+  // ID is optional - will be auto-generated if not provided
+  if (requireId && typeof object.id !== 'string') {
+    if (throwOnError) throw new ValidationError('ValidationError: Invalid ActivityPub object format - id must be a string');
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Transform Nostr event to HoloSphere format
+ * @param {Object} event - Nostr event
+ * @returns {Object} HoloSphere data object
+ */
+export function transformNostrEvent(event) {
+  // Generate missing fields if needed
+  const id = event.id || `nostr-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  const pubkey = event.pubkey || 'anonymous';
+  const sig = event.sig || '';
+
+  return {
+    id,
+    protocol: 'nostr',
+    originalFormat: 'nip-01',
+    pubkey,
+    sig, // Keep original field name for compatibility
+    created_at: event.created_at,
+    kind: event.kind,
+    // Gun doesn't support arrays, so serialize as JSON string
+    tags: JSON.stringify(event.tags),
+    content: event.content,
+    signature: sig, // Also include as signature for clarity
+    _meta: {
+      timestamp: event.created_at * 1000,
+      protocol: 'nostr',
+    },
+  };
+}
+
+/**
+ * Transform ActivityPub object to HoloSphere format
+ * @param {Object} object - ActivityPub object
+ * @returns {Object} HoloSphere data object
+ */
+export function transformActivityPubObject(object) {
+  // Generate ID if not provided
+  const id = object.id || `ap-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+  return {
+    id,
+    protocol: 'activitypub',
+    type: object.type,
+    actor: object.actor,
+    published: object.published,
+    content: object.content || object.name,
+    originalObject: { ...object, id }, // Add generated ID to original object
+    _meta: {
+      timestamp: object.published ? new Date(object.published).getTime() : Date.now(),
+      protocol: 'activitypub',
+    },
+  };
+}
+
+/**
+ * Filter social content by access level
+ * @param {Object[]} content - Social content array
+ * @param {string} accessLevel - Access level filter
+ * @returns {Object[]} Filtered content
+ */
+export function filterByAccessLevel(content, accessLevel) {
+  if (!accessLevel) return content;
+
+  return content.filter((item) => {
+    return !item.accessLevel || item.accessLevel === accessLevel;
+  });
+}
+
+/**
+ * Filter social content by protocol
+ * @param {Object[]} content - Social content array
+ * @param {string} protocol - Protocol filter ('nostr' or 'activitypub')
+ * @returns {Object[]} Filtered content
+ */
+export function filterByProtocol(content, protocol) {
+  if (!protocol || protocol === 'all') return content;
+  if (!Array.isArray(content)) return [];
+
+  return content.filter((item) => {
+    return item.protocol === protocol;
+  });
+}

package/src/core/holosphere.js

@@ -0,0 +1,273 @@
+import { createClient } from '../storage/nostr-client.js';
+import { BackendFactory } from '../storage/backend-factory.js';
+import pkg from '../../package.json' with { type: 'json' };
+
+/**
+ * Get environment variable (works in Node.js, returns undefined in browser)
+ * @param {string} name - Environment variable name
+ * @returns {string|undefined}
+ */
+function getEnv(name) {
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[name];
+  }
+  return undefined;
+}
+
+/**
+ * Parse relay URLs from environment variable or use defaults
+ * @returns {string[]}
+ */
+function getDefaultRelays() {
+  const envRelays = getEnv('HOLOSPHERE_RELAYS');
+  if (envRelays) {
+    return envRelays.split(',').map(r => r.trim()).filter(r => r);
+  }
+  return ['wss://relay.holons.io'];
+}
+
+/**
+ * HoloSphere - Holonic Geospatial Communication Infrastructure
+ * Combines H3 hexagonal indexing with distributed P2P storage
+ * Supports multiple storage backends: nostr, gundb, activitypub
+ */
+export class HoloSphere {
+  /**
+   * @param {Object} config - Configuration options
+   * @param {string} config.appName - Application namespace (default: '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 {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
+   */
+  constructor(config = {}) {
+    // Allow string as shorthand for appName (backward compatibility)
+    if (typeof config === 'string') {
+      config = { appName: config };
+    }
+
+    // Validate config
+    if (config && typeof config !== 'object') {
+      throw new TypeError('Config must be an object');
+    }
+
+    // Validate individual config properties
+    if (config.appName !== undefined && typeof config.appName !== 'string') {
+      throw new TypeError('config.appName must be a string');
+    }
+    if (config.relays !== undefined && !Array.isArray(config.relays)) {
+      throw new TypeError('config.relays must be an array');
+    }
+    if (config.logLevel !== undefined && !['ERROR', 'WARN', 'INFO', 'DEBUG'].includes(config.logLevel)) {
+      throw new TypeError('config.logLevel must be one of: ERROR, WARN, INFO, DEBUG');
+    }
+    if (config.backend !== undefined && !BackendFactory.isAvailable(config.backend)) {
+      throw new TypeError(`config.backend must be one of: ${BackendFactory.getAvailableBackends().join(', ')}`);
+    }
+
+    // Set defaults (with environment variable fallbacks)
+    this.config = {
+      appName: config.appName || getEnv('HOLOSPHERE_APP_NAME') || 'holosphere',
+      backend: config.backend || 'nostr',
+      relays: config.relays || getDefaultRelays(),
+      privateKey: config.privateKey || getEnv('HOLOSPHERE_PRIVATE_KEY'),
+      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'WARN',
+      hybridMode: config.hybridMode !== false, // Enable by default
+    };
+
+    // Store raw config for backend initialization
+    this._rawConfig = config;
+
+    // Initialize logging
+    this.logLevels = { ERROR: 0, WARN: 1, INFO: 2, DEBUG: 3 };
+    this.currentLogLevel = this.logLevels[this.config.logLevel] || 1;
+
+    // Backend instance (set during initialization)
+    this._backend = null;
+
+    // For backward compatibility with Nostr, initialize synchronously
+    // Other backends use async initialization via _backendReady
+    if (this.config.backend === 'nostr') {
+      this._initNostrSync(config);
+    } else {
+      // Async initialization for other backends
+      this._backendReady = this._initBackendAsync(config);
+    }
+
+    // Metrics tracking
+    this._metrics = {
+      writes: 0,
+      reads: 0,
+      subscriptions: 0,
+    };
+  }
+
+  /**
+   * Initialize Nostr backend synchronously (for backward compatibility)
+   * @private
+   */
+  _initNostrSync(config) {
+    try {
+      this.client = createClient({
+        relays: this.config.relays,
+        privateKey: this.config.privateKey,
+        enableReconnect: config.enableReconnect !== false,
+        enablePing: config.enablePing !== false,
+        appName: this.config.appName,
+        radisk: config.radisk !== false,
+        persistence: config.persistence !== false,
+        dataDir: config.dataDir,
+      });
+
+      // Log startup information
+      this._logStartup({
+        version: pkg.version,
+        appName: this.config.appName,
+        backend: 'nostr',
+        relays: this.config.relays,
+        publicKey: this.client.publicKey,
+        logLevel: this.config.logLevel,
+        persistence: config.persistence !== false,
+        reconnect: config.enableReconnect !== false,
+        dataDir: config.dataDir,
+      });
+
+      // Backend ready immediately for Nostr
+      this._backendReady = Promise.resolve();
+    } catch (error) {
+      this._log('ERROR', 'Nostr client initialization failed', { error: error.message });
+      throw new Error(`Nostr client initialization failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Initialize non-Nostr backends asynchronously
+   * @private
+   */
+  async _initBackendAsync(config) {
+    const backendType = this.config.backend;
+    const backendSpecificConfig = config[backendType] || {};
+
+    try {
+      // Merge common config with backend-specific config
+      const backendConfig = {
+        appName: this.config.appName,
+        privateKey: this.config.privateKey,
+        persistence: config.persistence !== false,
+        dataDir: config.dataDir,
+        ...backendSpecificConfig,
+      };
+
+      this._backend = await BackendFactory.create(backendType, backendConfig);
+
+      // For compatibility, also set client if backend has one
+      this.client = this._backend.client || this._backend;
+
+      // Log startup information
+      this._logStartup({
+        version: pkg.version,
+        appName: this.config.appName,
+        backend: backendType,
+        publicKey: this._backend.publicKey,
+        logLevel: this.config.logLevel,
+        persistence: config.persistence !== false,
+        ...this._backend.getStatus(),
+      });
+    } catch (error) {
+      this._log('ERROR', `${backendType} backend initialization failed`, { error: error.message });
+      throw new Error(`${backendType} backend initialization failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Ensure backend is ready before operations
+   * @returns {Promise<void>}
+   */
+  async ready() {
+    if (this._backendReady) {
+      await this._backendReady;
+    }
+  }
+
+  /**
+   * Get the storage backend instance
+   * @returns {StorageBackend|null}
+   */
+  get backend() {
+    return this._backend;
+  }
+
+  /**
+   * Internal structured logging
+   * @private
+   */
+  _log(level, message, data = {}) {
+    if (this.logLevels[level] <= this.currentLogLevel) {
+      const logEntry = {
+        timestamp: Date.now(),
+        level,
+        message,
+        app: this.config.appName,
+        ...data,
+      };
+      console.log(JSON.stringify(logEntry));
+    }
+  }
+
+  /**
+   * Log startup information in a user-friendly format
+   * @private
+   */
+  _logStartup(info) {
+    // Only log if INFO or DEBUG level
+    if (this.currentLogLevel >= this.logLevels.INFO) {
+      console.log('\n' + '='.repeat(60));
+      console.log('  HoloSphere - Holonic Geospatial Infrastructure');
+      console.log('='.repeat(60));
+      console.log(`  Version:        ${info.version}`);
+      console.log(`  App Name:       ${info.appName}`);
+      console.log(`  Backend:        ${info.backend || 'nostr'}`);
+      console.log(`  Public Key:     ${info.publicKey ? info.publicKey.substring(0, 16) + '...' : 'N/A'}`);
+      console.log(`  Log Level:      ${info.logLevel}`);
+      console.log(`  Persistence:    ${info.persistence ? 'Enabled' : 'Disabled'}${info.dataDir ? ` (${info.dataDir})` : ''}`);
+
+      // Backend-specific info
+      if (info.backend === 'nostr' || !info.backend) {
+        console.log(`  Auto-reconnect: ${info.reconnect ? 'Enabled' : 'Disabled'}`);
+        console.log('\n  Connected Relays:');
+        if (!info.relays || info.relays.length === 0) {
+          console.log('    (none - running in local mode)');
+        } else {
+          info.relays.forEach((relay, idx) => {
+            console.log(`    ${idx + 1}. ${relay}`);
+          });
+        }
+      } else if (info.backend === 'gundb') {
+        console.log('\n  Gun Peers:');
+        if (!info.peers || info.peers.length === 0) {
+          console.log('    (none - running in local mode)');
+        } else {
+          info.peers.forEach((peer, idx) => {
+            console.log(`    ${idx + 1}. ${peer}`);
+          });
+        }
+      } else if (info.backend === 'activitypub') {
+        console.log(`  Server URL:     ${info.serverUrl || 'N/A'}`);
+        console.log(`  Actor ID:       ${info.actorId || 'N/A'}`);
+      }
+
+      console.log('='.repeat(60) + '\n');
+    }
+  }
+
+  /**
+   * Get metrics
+   * @returns {Object} Operation counts
+   */
+  metrics() {
+    return { ...this._metrics };
+  }
+}

package/src/crypto/secp256k1.js

@@ -0,0 +1,259 @@
+/**
+ * Cryptographic Operations (secp256k1)
+ * Lazy-loaded for performance
+ */
+
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+
+let secp256k1 = null;
+
+/**
+ * Lazy load secp256k1 module
+ * @private
+ */
+async function loadCrypto() {
+  if (!secp256k1) {
+    const module = await import('@noble/curves/secp256k1');
+    secp256k1 = module.secp256k1;
+  }
+  return secp256k1;
+}
+
+/**
+ * Get public key from private key
+ * @param {string} privateKey - Private key (hex string)
+ * @returns {Promise<string>} Public key (hex string)
+ */
+export async function getPublicKey(privateKey) {
+  const crypto = await loadCrypto();
+  const pubKey = crypto.getPublicKey(privateKey);
+  return bytesToHex(pubKey);
+}
+
+/**
+ * Sign content with private key
+ * @param {string} content - Content to sign (will be hashed)
+ * @param {string} privateKey - Private key (hex string)
+ * @returns {Promise<string>} Signature (hex string)
+ */
+export async function sign(content, privateKey) {
+  try {
+    const crypto = await loadCrypto();
+
+    // Hash content
+    const msgHash = hashContent(content);
+
+    // Sign - secp256k1.sign returns Signature object
+    const signature = crypto.sign(msgHash, privateKey);
+    return signature.toCompactHex();
+  } catch (error) {
+    throw new Error(`Signature generation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Verify signature
+ * @param {string} content - Original content
+ * @param {string} signature - Signature (hex string)
+ * @param {string} publicKey - Public key (hex string)
+ * @returns {Promise<boolean>} True if valid
+ */
+export async function verify(content, signature, publicKey) {
+  try {
+    // Validate public key format
+    if (!publicKey || typeof publicKey !== 'string' || publicKey.length < 64) {
+      throw new Error('Invalid public key format');
+    }
+
+    const crypto = await loadCrypto();
+
+    const msgHash = hashContent(content);
+    const isValid = crypto.verify(signature, msgHash, publicKey);
+    return isValid;
+  } catch (error) {
+    // Invalid signatures or keys throw errors
+    // For test compatibility, rethrow if it's a validation error
+    if (error.message === 'Invalid public key format') {
+      throw error;
+    }
+    // Otherwise return false for invalid signatures
+    return false;
+  }
+}
+
+/**
+ * Match token scope against requested scope with wildcard support
+ * Supports:
+ * - Exact match: { holonId: "abc", lensName: "quests" }
+ * - Item-level: { holonId: "abc", lensName: "quests", dataId: "quest-001" }
+ * - Wildcards: { holonId: "*", lensName: "*" } matches everything
+ * @param {Object} tokenScope - Scope from capability token
+ * @param {Object} requestedScope - Scope being requested
+ * @returns {boolean} True if token scope covers requested scope
+ */
+export function matchScope(tokenScope, requestedScope) {
+  // Handle string scopes (legacy support)
+  if (typeof tokenScope === 'string' || typeof requestedScope === 'string') {
+    const tokenStr = typeof tokenScope === 'string' ? tokenScope : JSON.stringify(tokenScope);
+    const reqStr = typeof requestedScope === 'string' ? requestedScope : JSON.stringify(requestedScope);
+    return tokenStr === reqStr;
+  }
+
+  // Handle holonId
+  if (tokenScope.holonId !== '*' && tokenScope.holonId !== requestedScope.holonId) {
+    return false;
+  }
+
+  // Handle lensName
+  if (tokenScope.lensName !== '*' && tokenScope.lensName !== requestedScope.lensName) {
+    return false;
+  }
+
+  // Handle optional dataId (item-level scope)
+  // If token has specific dataId (not wildcard), it must match requested dataId
+  if (tokenScope.dataId && tokenScope.dataId !== '*') {
+    if (requestedScope.dataId && tokenScope.dataId !== requestedScope.dataId) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Issue capability token
+ * @param {string[]} permissions - Permissions array (e.g., ['read', 'write', 'delete'])
+ * @param {Object|string} scope - Scope (holon/lens path or object). Supports wildcards: { holonId: "*", lensName: "*" }
+ * @param {string} recipient - Recipient public key
+ * @param {Object} options - Options
+ * @param {number} options.expiresIn - Expiration in milliseconds (default: 1 hour)
+ * @param {string} options.issuer - Issuer ID
+ * @param {string} options.issuerKey - Issuer private key for signing
+ * @returns {Promise<string>} Capability token (base64-encoded JWT-like)
+ */
+export async function issueCapability(permissions, scope, recipient, options = {}) {
+  const { expiresIn = 3600000, issuer = 'holosphere', issuerKey } = options;
+
+  // Validate permissions
+  if (!Array.isArray(permissions) || permissions.length === 0) {
+    throw new Error('Permissions array cannot be empty');
+  }
+
+  // Validate scope - now supports wildcards
+  if (typeof scope === 'object') {
+    // holonId is required (can be '*' for wildcard)
+    if (scope.holonId === undefined || scope.holonId === '') {
+      throw new Error('Invalid scope: holonId is required (use "*" for wildcard)');
+    }
+    // lensName is required (can be '*' for wildcard)
+    if (scope.lensName === undefined || scope.lensName === '') {
+      throw new Error('Invalid scope: lensName is required (use "*" for wildcard)');
+    }
+    // dataId is optional (can be specific value, '*', or omitted)
+  } else if (typeof scope === 'string' && scope === '') {
+    throw new Error('Invalid scope: cannot be empty string');
+  }
+
+  // Validate issuerKey if provided
+  if (issuerKey && (typeof issuerKey !== 'string' || issuerKey.length < 32)) {
+    throw new Error('Invalid issuer key');
+  }
+
+  const token = {
+    type: 'capability',
+    permissions,
+    scope,
+    recipient,
+    issuer,
+    nonce: generateNonce(),
+    issued: Date.now(),
+    expires: Date.now() + expiresIn,
+  };
+
+  // Encode token as base64
+  const payload = JSON.stringify(token);
+  const encoded = Buffer.from ?
+    Buffer.from(payload).toString('base64') :
+    btoa(payload);
+
+  // If issuerKey provided, sign the token
+  if (issuerKey) {
+    const signature = await sign(payload, issuerKey);
+    return `${encoded}.${signature}`;
+  }
+
+  return encoded;
+}
+
+/**
+ * Verify capability token
+ * @param {string|Object} token - Capability token (string or object)
+ * @param {string} requiredPermission - Required permission
+ * @param {Object|string} scope - Scope to check (supports wildcards in token scope)
+ * @returns {Promise<boolean>} True if valid
+ */
+export async function verifyCapability(token, requiredPermission, scope) {
+  try {
+    let tokenObj;
+
+    // Decode if string
+    if (typeof token === 'string') {
+      const parts = token.split('.');
+      const payload = parts[0];
+      const decoded = Buffer.from ?
+        Buffer.from(payload, 'base64').toString('utf8') :
+        atob(payload);
+      tokenObj = JSON.parse(decoded);
+
+      // TODO: Verify signature if present (parts[1])
+    } else {
+      tokenObj = token;
+    }
+
+    if (!tokenObj || tokenObj.type !== 'capability') {
+      return false;
+    }
+
+    // Check expiration
+    if (Date.now() > tokenObj.expires) {
+      return false;
+    }
+
+    // Check scope using matchScope (supports wildcards)
+    if (!matchScope(tokenObj.scope, scope)) {
+      return false;
+    }
+
+    // Check permission
+    if (!tokenObj.permissions.includes(requiredPermission)) {
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Generate unique nonce
+ * @private
+ */
+function generateNonce() {
+  return (
+    Date.now().toString(36) + Math.random().toString(36).substring(2, 15)
+  );
+}
+
+/**
+ * Hash content using SHA-256
+ * @private
+ */
+function hashContent(content) {
+  const str = typeof content === 'string' ? content : JSON.stringify(content);
+  const encoder = new TextEncoder();
+  const data = encoder.encode(str);
+  const hash = sha256(data);
+  return bytesToHex(hash);
+}