holosphere 2.0.0-alpha11 → 2.0.0-alpha12

package/src/federation/holon-registry.js

@@ -0,0 +1,166 @@
+/**
+ * Holon Registry - Maps holonId to public key
+ *
+ * Every holon (H3 cell, telegram chat, concept) can be registered with a keypair.
+ * The holonId IS the public key (or resolves to one via this registry).
+ *
+ * When reading data, the system resolves holonId -> pubkey to determine
+ * whose data to read and what capabilities are needed.
+ */
+
+import { writeGlobal, readGlobal, getAllGlobal } from '../storage/global-tables.js';
+
+const HOLON_REGISTRY_TABLE = '_holon-registry';
+
+/**
+ * Check if a string is a valid 64-character hex public key
+ * @param {string} str - String to check
+ * @returns {boolean} True if valid pubkey format
+ */
+export function isPubkey(str) {
+  return typeof str === 'string' && /^[0-9a-f]{64}$/i.test(str);
+}
+
+/**
+ * Register a holon -> public key mapping
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier (H3, chatId, concept, etc.)
+ * @param {string} publicKey - 64-char hex public key
+ * @param {Object} options - Registration options
+ * @param {string} [options.alias] - Human-readable name
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function registerHolon(client, appname, holonId, publicKey, options = {}) {
+  if (!isPubkey(publicKey)) {
+    throw new Error(`Invalid public key format: ${publicKey}`);
+  }
+
+  // Don't register if holonId is already a pubkey
+  if (isPubkey(holonId)) {
+    return true; // No registration needed
+  }
+
+  const entry = {
+    id: holonId,
+    holonId: holonId,
+    publicKey: publicKey,
+    alias: options.alias || null,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    createdBy: client.publicKey,
+  };
+
+  return writeGlobal(client, appname, HOLON_REGISTRY_TABLE, entry);
+}
+
+/**
+ * Look up a holon's registration entry
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @returns {Promise<Object|null>} Registry entry or null
+ */
+export async function lookupHolon(client, appname, holonId) {
+  // If already a pubkey, return synthetic entry
+  if (isPubkey(holonId)) {
+    return {
+      holonId: holonId,
+      publicKey: holonId,
+      isDirect: true,
+    };
+  }
+
+  return readGlobal(client, appname, HOLON_REGISTRY_TABLE, holonId);
+}
+
+/**
+ * Resolve holonId to public key
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @returns {Promise<string|null>} Public key or null if not found
+ */
+export async function resolveHolonToPubkey(client, appname, holonId) {
+  // Direct pubkey
+  if (isPubkey(holonId)) {
+    return holonId;
+  }
+
+  // Registry lookup
+  const entry = await lookupHolon(client, appname, holonId);
+  return entry?.publicKey || null;
+}
+
+/**
+ * Unregister a holon
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function unregisterHolon(client, appname, holonId) {
+  // Can't unregister a direct pubkey
+  if (isPubkey(holonId)) {
+    return false;
+  }
+
+  // Mark as deleted by writing a tombstone
+  const entry = {
+    id: holonId,
+    holonId: holonId,
+    publicKey: null,
+    _deleted: true,
+    deletedAt: Date.now(),
+    deletedBy: client.publicKey,
+  };
+
+  return writeGlobal(client, appname, HOLON_REGISTRY_TABLE, entry);
+}
+
+/**
+ * Update a holon's alias or metadata
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @param {Object} updates - Fields to update
+ * @param {string} [updates.alias] - New alias
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateHolon(client, appname, holonId, updates = {}) {
+  const existing = await lookupHolon(client, appname, holonId);
+  if (!existing || existing.isDirect) {
+    return false;
+  }
+
+  const entry = {
+    ...existing,
+    ...updates,
+    updatedAt: Date.now(),
+  };
+
+  return writeGlobal(client, appname, HOLON_REGISTRY_TABLE, entry);
+}
+
+/**
+ * List all registered holons
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Object[]>} Array of registry entries
+ */
+export async function listRegisteredHolons(client, appname) {
+  const entries = await getAllGlobal(client, appname, HOLON_REGISTRY_TABLE);
+  return (entries || []).filter(e => !e._deleted);
+}
+
+/**
+ * Find holons by public key
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} publicKey - Public key to search for
+ * @returns {Promise<Object[]>} Array of holons with this pubkey
+ */
+export async function findHolonsByPubkey(client, appname, publicKey) {
+  const all = await listRegisteredHolons(client, appname);
+  return all.filter(e => e.publicKey === publicKey);
+}

package/src/federation/index.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Federation Module Index
+ *
+ * Exports all federation-related functionality in a modular structure.
+ * The federation system is now split into smaller, focused components:
+ *
+ * - capabilities: Token issuance and verification
+ * - registry: Partner and capability storage
+ * - handshake: NIP-44 encrypted DM protocol
+ * - discovery: Nostr event-based discovery
+ * - hologram: Reference/hologram management
+ * - request-card: Card-based configuration UI
+ * - card-storage: Persistent card state management
+ * - holon-registry: HolonId to pubKey mapping
+ *
+ * @module federation
+ */
+
+// Core federation components
+export * from './registry.js';
+export * from './hologram.js';
+export * from './discovery.js';
+
+// Handshake protocol
+export * from './handshake.js';
+
+// Capability management
+export * from './capabilities.js';
+
+// Card-based configuration
+export * from './request-card.js';
+export * from './card-storage.js';
+
+// Holon registry
+export * from './holon-registry.js';
+
+// Named exports for convenience
+import * as registry from './registry.js';
+import * as hologram from './hologram.js';
+import * as discovery from './discovery.js';
+import * as handshake from './handshake.js';
+import * as capabilities from './capabilities.js';
+import * as requestCard from './request-card.js';
+import * as cardStorage from './card-storage.js';
+import * as holonRegistry from './holon-registry.js';
+
+export {
+  registry,
+  hologram,
+  discovery,
+  handshake,
+  capabilities,
+  requestCard,
+  cardStorage,
+  holonRegistry,
+};
+
+// Default export with all modules
+export default {
+  registry,
+  hologram,
+  discovery,
+  handshake,
+  capabilities,
+  requestCard,
+  cardStorage,
+  holonRegistry,
+};

package/src/federation/registry.js

@@ -1,6 +1,12 @@
 /**
- * Federation Registry - Manages cross-holosphere partnerships
- * Tracks federated partners and their capability tokens
+ * Federation Registry - UNIFIED MODEL
+ *
+ * Manages federation partnerships and capability tokens for both:
+ * - Self-federation (same author, different holons)
+ * - Cross-federation (different authors)
+ *
+ * In the unified model, all federation uses capabilities, including self-federation.
+ * This provides consistent security semantics across all federation types.
  */
 
 import { writeGlobal, readGlobal } from '../storage/global-tables.js';
@@ -384,3 +390,105 @@ export async function cleanupExpiredCapabilities(client, appname) {
 
   return { inboundRemoved, outboundRemoved };
 }
+
+/**
+ * Store a self-capability (for same-author federation) - UNIFIED MODEL
+ *
+ * In the unified model, self-capabilities are stored similarly to cross-capabilities
+ * but marked as self-issued. This provides consistent capability management.
+ *
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} capabilityInfo - Capability information
+ * @param {string} capabilityInfo.token - The capability token
+ * @param {Object} capabilityInfo.scope - Token scope
+ * @param {string[]} capabilityInfo.permissions - Granted permissions
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function storeSelfCapability(client, appname, capabilityInfo) {
+  const registry = await getFederationRegistry(client, appname);
+
+  // Self-capabilities are stored under the user's own pubKey
+  const selfPubKey = client.publicKey;
+
+  // Find or create self-entry
+  let selfEntry = registry.federatedWith.find(p => p.pubKey === selfPubKey);
+
+  if (!selfEntry) {
+    selfEntry = {
+      pubKey: selfPubKey,
+      alias: 'self',
+      addedAt: Date.now(),
+      addedVia: 'self_capability',
+      isSelf: true,
+      inboundCapabilities: [],
+      outboundCapabilities: [],
+      selfCapabilities: [],  // Special array for self-capabilities
+    };
+    registry.federatedWith.push(selfEntry);
+  }
+
+  if (!selfEntry.selfCapabilities) {
+    selfEntry.selfCapabilities = [];
+  }
+
+  // Check if we already have this capability (by scope match)
+  const existingIndex = selfEntry.selfCapabilities.findIndex(cap =>
+    JSON.stringify(cap.scope) === JSON.stringify(capabilityInfo.scope)
+  );
+
+  if (existingIndex >= 0) {
+    // Update existing capability
+    selfEntry.selfCapabilities[existingIndex] = {
+      ...capabilityInfo,
+      updatedAt: Date.now(),
+      isSelfCapability: true,
+    };
+  } else {
+    // Add new capability
+    selfEntry.selfCapabilities.push({
+      ...capabilityInfo,
+      issuedAt: Date.now(),
+      isSelfCapability: true,
+    });
+  }
+
+  return saveFederationRegistry(client, appname, registry);
+}
+
+/**
+ * Get self-capability for a scope - UNIFIED MODEL
+ *
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} scope - Requested scope { holonId, lensName, dataId? }
+ * @returns {Promise<Object|null>} Self-capability or null
+ */
+export async function getSelfCapability(client, appname, scope) {
+  const registry = await getFederationRegistry(client, appname);
+  const selfEntry = registry.federatedWith.find(p => p.pubKey === client.publicKey && p.isSelf);
+
+  if (!selfEntry || !selfEntry.selfCapabilities) {
+    return null;
+  }
+
+  // Find matching, non-expired self-capability
+  return selfEntry.selfCapabilities.find(cap => {
+    // Check expiration
+    if (cap.expires && cap.expires < Date.now()) {
+      return false;
+    }
+
+    // Check scope match (supports wildcards)
+    return matchScope(cap.scope, scope);
+  }) || null;
+}
+
+/**
+ * Check if a capability is a self-capability
+ * @param {Object} capabilityInfo - Capability info object
+ * @returns {boolean} True if self-capability
+ */
+export function isSelfCapability(capabilityInfo) {
+  return capabilityInfo && capabilityInfo.isSelfCapability === true;
+}