holosphere 1.1.19 → 2.0.0-alpha0

package/src/federation/registry.js

@@ -0,0 +1,386 @@
+/**
+ * Federation Registry - Manages cross-holosphere partnerships
+ * Tracks federated partners and their capability tokens
+ */
+
+import { writeGlobal, readGlobal } from '../storage/global-tables.js';
+import { matchScope } from '../crypto/secp256k1.js';
+
+const FEDERATION_TABLE = 'federations';
+
+/**
+ * Get the federation registry for this holosphere
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Object>} Federation registry
+ */
+export async function getFederationRegistry(client, appname) {
+  const registry = await readGlobal(client, appname, FEDERATION_TABLE, client.publicKey);
+
+  return registry || {
+    id: client.publicKey,
+    federatedWith: [],
+    discoveryEnabled: false,
+    autoAccept: false,
+    defaultScope: { holonId: '*', lensName: '*' },
+    defaultPermissions: ['read'],
+  };
+}
+
+/**
+ * Save the federation registry
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} registry - Registry to save
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function saveFederationRegistry(client, appname, registry) {
+  return writeGlobal(client, appname, FEDERATION_TABLE, registry);
+}
+
+/**
+ * Add a federated partner
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @param {Object} options - Partner options
+ * @param {string} options.alias - Human-readable name
+ * @param {string} options.addedVia - How the partner was added ('manual' or 'nostr_discovery')
+ * @param {Object[]} options.inboundCapabilities - Capabilities they've granted us
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function addFederatedPartner(client, appname, partnerPubKey, options = {}) {
+  const registry = await getFederationRegistry(client, appname);
+
+  // Check if already exists
+  const existingIndex = registry.federatedWith.findIndex(p => p.pubKey === partnerPubKey);
+
+  if (existingIndex >= 0) {
+    // Update existing entry
+    const existing = registry.federatedWith[existingIndex];
+
+    if (options.alias) {
+      existing.alias = options.alias;
+    }
+
+    if (options.inboundCapabilities) {
+      existing.inboundCapabilities = [
+        ...(existing.inboundCapabilities || []),
+        ...options.inboundCapabilities
+      ];
+    }
+
+    existing.updatedAt = Date.now();
+    registry.federatedWith[existingIndex] = existing;
+  } else {
+    // Add new partner
+    registry.federatedWith.push({
+      pubKey: partnerPubKey,
+      alias: options.alias || null,
+      addedAt: Date.now(),
+      addedVia: options.addedVia || 'manual',
+      inboundCapabilities: options.inboundCapabilities || [],
+      outboundCapabilities: [],
+    });
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Remove a federated partner
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key to remove
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function removeFederatedPartner(client, appname, partnerPubKey) {
+  const registry = await getFederationRegistry(client, appname);
+
+  const initialLength = registry.federatedWith.length;
+  registry.federatedWith = registry.federatedWith.filter(p => p.pubKey !== partnerPubKey);
+
+  if (registry.federatedWith.length === initialLength) {
+    return false; // Partner not found
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Get all federated author public keys
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<string[]>} Array of federated public keys
+ */
+export async function getFederatedAuthors(client, appname) {
+  const registry = await getFederationRegistry(client, appname);
+  return registry.federatedWith.map(p => p.pubKey);
+}
+
+/**
+ * Get a specific federated partner
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @returns {Promise<Object|null>} Partner info or null
+ */
+export async function getFederatedPartner(client, appname, partnerPubKey) {
+  const registry = await getFederationRegistry(client, appname);
+  return registry.federatedWith.find(p => p.pubKey === partnerPubKey) || null;
+}
+
+/**
+ * Get capability for a specific author and scope
+ * Finds a valid, non-expired capability that covers the requested scope
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} authorPubKey - Author's public key
+ * @param {Object} scope - Requested scope { holonId, lensName, dataId? }
+ * @returns {Promise<Object|null>} Capability entry or null
+ */
+export async function getCapabilityForAuthor(client, appname, authorPubKey, scope) {
+  const registry = await getFederationRegistry(client, appname);
+  const partner = registry.federatedWith.find(p => p.pubKey === authorPubKey);
+
+  if (!partner || !partner.inboundCapabilities) {
+    return null;
+  }
+
+  // Find matching, non-expired capability
+  return partner.inboundCapabilities.find(cap => {
+    // Check expiration
+    if (cap.expires && cap.expires < Date.now()) {
+      return false;
+    }
+
+    // Check scope match (supports wildcards)
+    return matchScope(cap.scope, scope);
+  }) || null;
+}
+
+/**
+ * Store an inbound capability (one we received from a partner)
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @param {Object} capabilityInfo - Capability information
+ * @param {string} capabilityInfo.token - The capability token
+ * @param {Object} capabilityInfo.scope - Token scope
+ * @param {string[]} capabilityInfo.permissions - Granted permissions
+ * @param {number} capabilityInfo.expires - Expiration timestamp
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function storeInboundCapability(client, appname, partnerPubKey, capabilityInfo) {
+  const registry = await getFederationRegistry(client, appname);
+  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+
+  if (!partner) {
+    // Auto-add partner if not exists
+    return addFederatedPartner(client, appname, partnerPubKey, {
+      addedVia: 'capability_received',
+      inboundCapabilities: [capabilityInfo]
+    });
+  }
+
+  if (!partner.inboundCapabilities) {
+    partner.inboundCapabilities = [];
+  }
+
+  // Check if we already have this capability (by scope match)
+  const existingIndex = partner.inboundCapabilities.findIndex(cap =>
+    JSON.stringify(cap.scope) === JSON.stringify(capabilityInfo.scope)
+  );
+
+  if (existingIndex >= 0) {
+    // Update existing capability
+    partner.inboundCapabilities[existingIndex] = {
+      ...capabilityInfo,
+      updatedAt: Date.now()
+    };
+  } else {
+    // Add new capability
+    partner.inboundCapabilities.push({
+      ...capabilityInfo,
+      receivedAt: Date.now()
+    });
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Store an outbound capability (one we issued to a partner)
+ * We only store the hash, not the full token
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @param {Object} capabilityInfo - Capability information
+ * @param {string} capabilityInfo.tokenHash - SHA-256 hash of the token
+ * @param {Object} capabilityInfo.scope - Token scope
+ * @param {string[]} capabilityInfo.permissions - Granted permissions
+ * @param {number} capabilityInfo.expires - Expiration timestamp
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function storeOutboundCapability(client, appname, partnerPubKey, capabilityInfo) {
+  const registry = await getFederationRegistry(client, appname);
+  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+
+  if (!partner) {
+    throw new Error(`Partner ${partnerPubKey} not found in federation registry`);
+  }
+
+  if (!partner.outboundCapabilities) {
+    partner.outboundCapabilities = [];
+  }
+
+  partner.outboundCapabilities.push({
+    tokenHash: capabilityInfo.tokenHash,
+    scope: capabilityInfo.scope,
+    permissions: capabilityInfo.permissions,
+    issuedAt: Date.now(),
+    expires: capabilityInfo.expires,
+  });
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Revoke an outbound capability (by token hash)
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @param {string} tokenHash - Hash of the token to revoke
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function revokeOutboundCapability(client, appname, partnerPubKey, tokenHash) {
+  const registry = await getFederationRegistry(client, appname);
+  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+
+  if (!partner || !partner.outboundCapabilities) {
+    return false;
+  }
+
+  const initialLength = partner.outboundCapabilities.length;
+  partner.outboundCapabilities = partner.outboundCapabilities.filter(
+    cap => cap.tokenHash !== tokenHash
+  );
+
+  if (partner.outboundCapabilities.length === initialLength) {
+    return false; // Token not found
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Update federation discovery settings
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} settings - Discovery settings
+ * @param {boolean} settings.discoveryEnabled - Enable Nostr discovery
+ * @param {boolean} settings.autoAccept - Auto-accept federation requests
+ * @param {Object} settings.defaultScope - Default scope for auto-accepted federations
+ * @param {string[]} settings.defaultPermissions - Default permissions for auto-accepted federations
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateDiscoverySettings(client, appname, settings) {
+  const registry = await getFederationRegistry(client, appname);
+
+  if (settings.discoveryEnabled !== undefined) {
+    registry.discoveryEnabled = settings.discoveryEnabled;
+  }
+  if (settings.autoAccept !== undefined) {
+    registry.autoAccept = settings.autoAccept;
+  }
+  if (settings.defaultScope !== undefined) {
+    registry.defaultScope = settings.defaultScope;
+  }
+  if (settings.defaultPermissions !== undefined) {
+    registry.defaultPermissions = settings.defaultPermissions;
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Get all federated authors that have granted capabilities for a given scope
+ * Returns pubKeys of partners who have given us access to read/write their data
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} scope - Requested scope { holonId?, lensName?, dataId? }
+ * @param {string} permission - Required permission ('read' or 'write')
+ * @returns {Promise<Array>} Array of { pubKey, capability } for matching partners
+ */
+export async function getFederatedAuthorsForScope(client, appname, scope = {}, permission = 'read') {
+  const registry = await getFederationRegistry(client, appname);
+  const now = Date.now();
+  const results = [];
+
+  for (const partner of registry.federatedWith) {
+    if (!partner.inboundCapabilities || partner.inboundCapabilities.length === 0) {
+      continue;
+    }
+
+    // Find a valid capability that covers this scope
+    for (const cap of partner.inboundCapabilities) {
+      // Check expiration
+      if (cap.expires && cap.expires < now) {
+        continue;
+      }
+
+      // Check permission
+      if (cap.permissions && !cap.permissions.includes(permission)) {
+        continue;
+      }
+
+      // Check scope match (supports wildcards)
+      if (matchScope(cap.scope, scope)) {
+        results.push({
+          pubKey: partner.pubKey,
+          capability: cap,
+        });
+        break; // One valid capability per partner is enough
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Clean up expired capabilities from the registry
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Object>} Cleanup result { inboundRemoved, outboundRemoved }
+ */
+export async function cleanupExpiredCapabilities(client, appname) {
+  const registry = await getFederationRegistry(client, appname);
+  const now = Date.now();
+  let inboundRemoved = 0;
+  let outboundRemoved = 0;
+
+  for (const partner of registry.federatedWith) {
+    if (partner.inboundCapabilities) {
+      const beforeCount = partner.inboundCapabilities.length;
+      partner.inboundCapabilities = partner.inboundCapabilities.filter(
+        cap => !cap.expires || cap.expires > now
+      );
+      inboundRemoved += beforeCount - partner.inboundCapabilities.length;
+    }
+
+    if (partner.outboundCapabilities) {
+      const beforeCount = partner.outboundCapabilities.length;
+      partner.outboundCapabilities = partner.outboundCapabilities.filter(
+        cap => !cap.expires || cap.expires > now
+      );
+      outboundRemoved += beforeCount - partner.outboundCapabilities.length;
+    }
+  }
+
+  if (inboundRemoved > 0 || outboundRemoved > 0) {
+    await saveFederationRegistry(client, appname, registry);
+  }
+
+  return { inboundRemoved, outboundRemoved };
+}

package/src/hierarchical/upcast.js

@@ -0,0 +1,110 @@
+/**
+ * Hierarchical Aggregation (Upcast Operations)
+ * FR-025 to FR-027
+ */
+
+import { getParents, isValidH3 } from '../spatial/h3-operations.js';
+import { createHologram } from '../federation/hologram.js';
+import { write } from '../storage/nostr-wrapper.js';
+
+/**
+ * Upcast data to parent holons in hierarchy
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Source holon ID (must be H3)
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {Object} options - Upcast options
+ * @param {number} options.maxLevel - Maximum levels to propagate (default: 3)
+ * @param {string} options.operation - 'summarize', 'aggregate', or 'concatenate'
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function upcast(client, appname, holonId, lensName, dataId, options = {}) {
+  const { maxLevel = 3, operation = 'summarize' } = options;
+
+  // Validate H3 format
+  if (!isValidH3(holonId)) {
+    throw new Error('Upcast only supported for geographic (H3) holons, not noospheric holons');
+  }
+
+  // Get parent holons
+  const parents = getParents(holonId);
+  const targetParents = parents.slice(0, maxLevel);
+
+  if (targetParents.length === 0) {
+    return true; // Already at root
+  }
+
+  // Create holograms in parent holons
+  const promises = targetParents.map(async (parentHolon) => {
+    return propagateToParent(client, appname, holonId, parentHolon, lensName, dataId, operation);
+  });
+
+  await Promise.all(promises);
+  return true;
+}
+
+/**
+ * Propagate data to parent holon
+ * @private
+ */
+async function propagateToParent(
+  client,
+  appname,
+  sourceHolon,
+  parentHolon,
+  lensName,
+  dataId,
+  operation
+) {
+  // Create hologram reference
+  const hologram = createHologram(sourceHolon, parentHolon, lensName, dataId, appname);
+
+  // Add operation metadata
+  hologram._meta.operation = operation;
+  hologram._meta.upcast = true;
+
+  // Write to parent holon
+  const path = `${appname}/${parentHolon}/${lensName}/${dataId}`;
+  return write(client, path, hologram);
+}
+
+/**
+ * Summarize operation (count aggregation)
+ * @param {Object[]} items - Data items
+ * @returns {Object} Summary object
+ */
+export function summarize(items) {
+  return {
+    operation: 'summarize',
+    count: items.length,
+    summary: true,
+  };
+}
+
+/**
+ * Aggregate operation (merge objects)
+ * @param {Object[]} items - Data items
+ * @returns {Object} Aggregated object
+ */
+export function aggregate(items) {
+  const result = { operation: 'aggregate' };
+
+  for (const item of items) {
+    Object.assign(result, item);
+  }
+
+  return result;
+}
+
+/**
+ * Concatenate operation (array merge)
+ * @param {Array[]} items - Array items
+ * @returns {Array} Concatenated array
+ */
+export function concatenate(items) {
+  return {
+    operation: 'concatenate',
+    items: items.flat(),
+  };
+}