holosphere 2.0.0-alpha20 → 2.0.0-alpha22

package/src/federation/registry.js

@@ -1,41 +1,30 @@
 /**
- * Federation Registry - UNIFIED MODEL
+ * Federation Registry — Simplified.
  *
- * Manages federation partnerships and capability tokens for both:
- * - Self-federation (same author, different holons)
- * - Cross-federation (different authors)
+ * Federation = a list of pubkeys whose data I want to see.
+ * That's it. No capability tokens, no scoped permissions, no expiration.
  *
- * In the unified model, all federation uses capabilities, including self-federation.
- * This provides consistent security semantics across all federation types.
+ * Everyone can write everywhere (Nostr is open-write).
+ * Non-federated writes are simply invisible on read (filtered out).
+ *
+ * The registry stores:
+ * - federatedWith: [{ pubKey, alias, addedAt, addedVia }]
+ * - capabilityWriters: [{ pubKey, addedAt }]  (external writers, e.g. QR code)
  */
 
 import { writeGlobal, readGlobal } from '../storage/global-tables.js';
-import { matchScope } from '../crypto/secp256k1.js';
 
 const FEDERATION_TABLE = 'federations';
 
 // ============================================================================
-// Registry Cache - Avoids repeated storage reads
+// Registry Cache
 // ============================================================================
 
-/**
- * @typedef {Object} CachedRegistry
- * @property {Object} registry - The federation registry data
- * @property {Map<string, Object>} partnerIndex - Index of partners by pubKey for O(1) lookup
- * @property {number} timestamp - When the cache was created
- */
-
-/** @type {Map<string, CachedRegistry>} Cache keyed by `${clientPubKey}:${appname}` */
+/** @type {Map<string, { registry: Object, partnerIndex: Map, timestamp: number }>} */
 const registryCache = new Map();
 
-/** Cache TTL in milliseconds (10 seconds) */
 const CACHE_TTL_MS = 10000;
 
-/**
- * Build an index of partners by pubKey for O(1) lookups
- * @param {Object[]} federatedWith - Array of partner objects
- * @returns {Map<string, Object>} Partner index
- */
 function buildPartnerIndex(federatedWith) {
   const index = new Map();
   for (const partner of federatedWith) {
@@ -46,40 +35,30 @@ function buildPartnerIndex(federatedWith) {
   return index;
 }
 
-/**
- * Get cache key for a client/appname combination
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @returns {string} Cache key
- */
 function getCacheKey(client, appname) {
   return `${client.publicKey}:${appname}`;
 }
 
-/**
- * Invalidate the registry cache for a specific client/appname
- * Call this after any write operation
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- */
 export function invalidateRegistryCache(client, appname) {
-  const key = getCacheKey(client, appname);
-  registryCache.delete(key);
+  registryCache.delete(getCacheKey(client, appname));
 }
 
+// ============================================================================
+// Core Registry CRUD
+// ============================================================================
+
 /**
- * Get the federation registry for this holosphere (with caching)
+ * Get the federation registry (with caching).
  * @param {Object} client - NostrClient instance
  * @param {string} appname - Application namespace
  * @param {Object} [options] - Options
- * @param {boolean} [options.skipCache=false] - Force fresh read from storage
+ * @param {boolean} [options.skipCache=false] - Force fresh read
  * @returns {Promise<Object>} Federation registry
  */
 export async function getFederationRegistry(client, appname, options = {}) {
   const cacheKey = getCacheKey(client, appname);
   const now = Date.now();
 
-  // Check cache first (unless skipCache is set)
   if (!options.skipCache) {
     const cached = registryCache.get(cacheKey);
     if (cached && (now - cached.timestamp) < CACHE_TTL_MS) {
@@ -87,118 +66,57 @@ export async function getFederationRegistry(client, appname, options = {}) {
     }
   }
 
-  // Read from storage
   const registry = await readGlobal(client, appname, FEDERATION_TABLE, client.publicKey) || {
     id: client.publicKey,
     federatedWith: [],
     capabilityWriters: [],
-    discoveryEnabled: false,
-    autoAccept: false,
-    defaultScope: { holonId: '*', lensName: '*' },
-    defaultPermissions: ['read'],
   };
 
-  // Ensure capabilityWriters array exists (for registries created before this field)
-  if (!registry.capabilityWriters) {
-    registry.capabilityWriters = [];
-  }
+  // Ensure arrays exist
+  if (!registry.federatedWith) registry.federatedWith = [];
+  if (!registry.capabilityWriters) registry.capabilityWriters = [];
 
-  // Build partner index and cache
-  const partnerIndex = buildPartnerIndex(registry.federatedWith || []);
-  registryCache.set(cacheKey, {
-    registry,
-    partnerIndex,
-    timestamp: now,
-  });
+  const partnerIndex = buildPartnerIndex(registry.federatedWith);
+  registryCache.set(cacheKey, { registry, partnerIndex, timestamp: now });
 
   return registry;
 }
 
 /**
- * Get partner from cache index (O(1) lookup)
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} partnerPubKey - Partner's public key
- * @returns {Promise<Object|null>} Partner object or null
- */
-async function getPartnerFromIndex(client, appname, partnerPubKey) {
-  const cacheKey = getCacheKey(client, appname);
-
-  // Ensure registry is loaded and cached
-  await getFederationRegistry(client, appname);
-
-  const cached = registryCache.get(cacheKey);
-  if (cached && cached.partnerIndex) {
-    return cached.partnerIndex.get(partnerPubKey) || null;
-  }
-
-  return null;
-}
-
-/**
- * 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
+ * Save the federation registry.
  */
 export async function saveFederationRegistry(client, appname, registry) {
-  // Invalidate cache before write so next read gets fresh data
   invalidateRegistryCache(client, appname);
   return writeGlobal(client, appname, FEDERATION_TABLE, registry);
 }
 
 /**
- * Add a federated partner
+ * Add a federated partner (just a pubkey).
  * @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
+ * @param {string} [options.alias] - Human-readable name
+ * @param {string} [options.addedVia] - How the partner was added
  * @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];
-
+    // Update alias if provided
     if (options.alias) {
-      existing.alias = options.alias;
-    }
-
-    if (options.inboundCapabilities) {
-      // Merge and deduplicate capabilities by scope to prevent accumulation
-      const allCaps = [
-        ...(existing.inboundCapabilities || []),
-        ...options.inboundCapabilities
-      ];
-      // Keep only unique capabilities (by scope), preferring newer ones (last in array)
-      const seen = new Map();
-      for (const cap of allCaps) {
-        const scopeKey = `${cap.scope?.holonId}:${cap.scope?.lensName}:${cap.scope?.dataId}`;
-        seen.set(scopeKey, cap);  // Later entries overwrite earlier (newer wins)
-      }
-      existing.inboundCapabilities = Array.from(seen.values());
+      registry.federatedWith[existingIndex].alias = options.alias;
     }
-
-    existing.updatedAt = Date.now();
-    registry.federatedWith[existingIndex] = existing;
+    registry.federatedWith[existingIndex].updatedAt = Date.now();
   } else {
-    // Add new partner
     registry.federatedWith.push({
       pubKey: partnerPubKey,
       alias: options.alias || null,
       addedAt: Date.now(),
       addedVia: options.addedVia || 'manual',
-      inboundCapabilities: options.inboundCapabilities || [],
-      outboundCapabilities: [],
     });
   }
 
@@ -206,58 +124,62 @@ export async function addFederatedPartner(client, appname, partnerPubKey, option
 }
 
 /**
- * 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
+ * Remove a federated partner.
  */
 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 false;
   }
 
   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
+ * Get all federated author public keys.
  */
 export async function getFederatedAuthors(client, appname) {
   const registry = await getFederationRegistry(client, appname);
   return registry.federatedWith.map(p => p.pubKey);
 }
 
+/**
+ * Check if a pubkey is in the federation.
+ * This is THE core federation check — O(1) via cached index.
+ *
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} pubKey - Public key to check
+ * @returns {Promise<boolean>} True if pubkey is federated
+ */
+export async function isFederated(client, appname, pubKey) {
+  // Self is always "federated"
+  if (pubKey === client.publicKey) return true;
+
+  await getFederationRegistry(client, appname);
+  const cacheKey = getCacheKey(client, appname);
+  const cached = registryCache.get(cacheKey);
+  if (cached && cached.partnerIndex) {
+    return cached.partnerIndex.has(pubKey);
+  }
+  return false;
+}
+
 // ============================================================================
 // Capability Writers (External writers registered via app-level authorization)
 // ============================================================================
 
 /**
- * Add a capability writer — an external pubkey authorized to write to this holon
- * via app-level capability tokens (e.g., QR codes). Their pubkey is recorded so
- * their data is included in future read queries.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} writerPubKey - Writer's public key to register
- * @returns {Promise<boolean>} Success indicator
+ * Add a capability writer — an external pubkey authorized to write to this holon.
  */
 export async function addCapabilityWriter(client, appname, writerPubKey) {
   const registry = await getFederationRegistry(client, appname);
 
-  // Deduplicate
   const exists = registry.capabilityWriters.some(w => w.pubKey === writerPubKey);
-  if (exists) {
-    return true; // Already registered
-  }
+  if (exists) return true;
 
   registry.capabilityWriters.push({
     pubKey: writerPubKey,
@@ -269,10 +191,6 @@ export async function addCapabilityWriter(client, appname, writerPubKey) {
 
 /**
  * Get all capability writer public keys.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @returns {Promise<string[]>} Array of capability writer pubkeys
  */
 export async function getCapabilityWriters(client, appname) {
   const registry = await getFederationRegistry(client, appname);
@@ -281,1054 +199,32 @@ export async function getCapabilityWriters(client, appname) {
 
 /**
  * Remove a capability writer.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} writerPubKey - Writer's public key to remove
- * @returns {Promise<boolean>} Success indicator
  */
 export async function removeCapabilityWriter(client, appname, writerPubKey) {
   const registry = await getFederationRegistry(client, appname);
-
   const initialLength = registry.capabilityWriters.length;
   registry.capabilityWriters = registry.capabilityWriters.filter(w => w.pubKey !== writerPubKey);
 
   if (registry.capabilityWriters.length === initialLength) {
-    return false; // Writer not found
-  }
-
-  return saveFederationRegistry(client, appname, registry);
-}
-
-/**
- * Get a specific federated partner (O(1) lookup via index)
- * @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) {
-  return getPartnerFromIndex(client, appname, partnerPubKey);
-}
-
-/**
- * Get capability for a specific author and scope
- * Finds a valid, non-expired capability that covers the requested scope
- * Uses O(1) partner lookup via index
- * @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) {
-  // Use O(1) index lookup instead of array.find()
-  const partner = await getPartnerFromIndex(client, appname, authorPubKey);
-
-  if (!partner) {
-    return null;
-  }
-
-  if (!partner.inboundCapabilities || partner.inboundCapabilities.length === 0) {
-    return null;
-  }
-
-  const now = Date.now();
-
-  // Find matching, non-expired capability
-  // Note: We still iterate through capabilities here, but there are typically
-  // only a few per partner (often just one wildcard capability)
-  for (const cap of partner.inboundCapabilities) {
-    // Check expiration
-    if (cap.expires && cap.expires < now) {
-      continue;
-    }
-
-    // Check scope match (supports wildcards)
-    if (matchScope(cap.scope, scope)) {
-      return cap;
-    }
-  }
-
-  return 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 };
-}
-
-/**
- * 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;
-}
-
 // ============================================================================
-// Write Grant Functions (Cross-Holon Write Access)
+// Partner Lookup
 // ============================================================================
 
 /**
- * Grant write access to a holon for a specific lens.
- * This allows all members of the granted holon to write to the specified lens.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} holonId - The holon (pubKey) being granted write access
- * @param {string} lensName - The lens to grant write access to (or '*' for all lenses)
- * @param {Object} [options={}] - Grant options
- * @param {number} [options.expiresAt] - Optional expiration timestamp
- * @returns {Promise<boolean>} Success indicator
- */
-export async function grantWriteAccessToHolon(client, appname, holonId, lensName, options = {}) {
-  console.warn('[Deprecated] grantWriteAccessToHolon() is deprecated. Use grantAccess() instead.');
-  const registry = await getFederationRegistry(client, appname);
-
-  // Find or create partner entry
-  let partner = registry.federatedWith.find(p => p.pubKey === holonId);
-
-  if (!partner) {
-    // Auto-add partner if not exists
-    partner = {
-      pubKey: holonId,
-      alias: null,
-      addedAt: Date.now(),
-      addedVia: 'write_grant',
-      inboundCapabilities: [],
-      outboundCapabilities: [],
-      writeGrants: [],
-    };
-    registry.federatedWith.push(partner);
-  }
-
-  if (!partner.writeGrants) {
-    partner.writeGrants = [];
-  }
-
-  // Check if grant already exists
-  const existingIndex = partner.writeGrants.findIndex(g => g.lensName === lensName);
-
-  const grant = {
-    lensName,
-    grantedAt: Date.now(),
-    expiresAt: options.expiresAt || null,
-  };
-
-  if (existingIndex >= 0) {
-    // Update existing grant
-    partner.writeGrants[existingIndex] = grant;
-  } else {
-    // Add new grant
-    partner.writeGrants.push(grant);
-  }
-
-  return saveFederationRegistry(client, appname, registry);
-}
-
-/**
- * Revoke write access from a holon for a specific lens.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} holonId - The holon to revoke write access from
- * @param {string} lensName - The lens to revoke write access for
- * @returns {Promise<boolean>} Success indicator
- */
-export async function revokeWriteAccess(client, appname, holonId, lensName) {
-  console.warn('[Deprecated] revokeWriteAccess() is deprecated. Use revokeAccess() instead.');
-  const registry = await getFederationRegistry(client, appname);
-
-  const partner = registry.federatedWith.find(p => p.pubKey === holonId);
-
-  if (!partner || !partner.writeGrants) {
-    return false; // No grants to revoke
-  }
-
-  const initialLength = partner.writeGrants.length;
-  partner.writeGrants = partner.writeGrants.filter(g => g.lensName !== lensName);
-
-  if (partner.writeGrants.length === initialLength) {
-    return false; // Grant not found
-  }
-
-  return saveFederationRegistry(client, appname, registry);
-}
-
-/**
- * Get all write grants for a specific holon.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} holonId - The holon to get write grants for
- * @returns {Promise<Array>} Array of write grants { lensName, grantedAt, expiresAt }
- */
-export async function getWriteGrantsForHolon(client, appname, holonId) {
-  console.warn('[Deprecated] getWriteGrantsForHolon() is deprecated. Use getAccessGrants() instead.');
-  const registry = await getFederationRegistry(client, appname);
-
-  const partner = registry.federatedWith.find(p => p.pubKey === holonId);
-
-  if (!partner || !partner.writeGrants) {
-    return [];
-  }
-
-  // Filter out expired grants
-  const now = Date.now();
-  return partner.writeGrants.filter(g => !g.expiresAt || g.expiresAt > now);
-}
-
-/**
- * Check if a holon has write access to a specific lens.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} holonId - The holon to check
- * @param {string} lensName - The lens to check access for
- * @returns {Promise<boolean>} True if holon has write access
- */
-export async function hasWriteAccess(client, appname, holonId, lensName) {
-  console.warn('[Deprecated] hasWriteAccess() is deprecated. Use findAccessGrant() instead.');
-  const grants = await getWriteGrantsForHolon(client, appname, holonId);
-
-  // Check for exact lens match or wildcard
-  return grants.some(g => g.lensName === lensName || g.lensName === '*');
-}
-
-/**
- * Get all holons that have been granted write access to any lens.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @returns {Promise<Array>} Array of { holonId, writeGrants }
- */
-export async function getAllWriteGrants(client, appname) {
-  console.warn('[Deprecated] getAllWriteGrants() is deprecated. Use getAccessGrants() instead.');
-  const registry = await getFederationRegistry(client, appname);
-  const now = Date.now();
-  const results = [];
-
-  for (const partner of registry.federatedWith) {
-    if (partner.writeGrants && partner.writeGrants.length > 0) {
-      // Filter out expired grants
-      const validGrants = partner.writeGrants.filter(g => !g.expiresAt || g.expiresAt > now);
-
-      if (validGrants.length > 0) {
-        results.push({
-          holonId: partner.pubKey,
-          alias: partner.alias,
-          writeGrants: validGrants,
-        });
-      }
-    }
-  }
-
-  return results;
-}
-
-// ============================================================================
-// UNIFIED ACCESS GRANTS (New Unified Model)
-// ============================================================================
-
-/**
- * @typedef {Object} AccessGrant
- * @property {Object} scope - Grant scope
- * @property {string} [scope.holonId] - Holon ID pattern (or '*' for all)
- * @property {string} [scope.lensName] - Lens name pattern (or '*' for all)
- * @property {string[]} permissions - Array of permissions ('read', 'write')
- * @property {number} grantedAt - When the grant was created
- * @property {number|null} expiresAt - When the grant expires (null for never)
- * @property {string} [capabilityToken] - Optional capability token for cryptographic verification
- * @property {'inbound'|'outbound'} direction - Direction of the grant
- */
-
-/**
- * Grant unified access to a partner.
- * This is the new unified method that replaces separate read/write grant functions.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} partnerPubKey - Partner's public key
- * @param {Object} scope - Access scope { holonId, lensName }
- * @param {string[]} permissions - Array of permissions ('read', 'write')
- * @param {Object} [options={}] - Grant options
- * @param {number} [options.expiresAt] - Expiration timestamp
- * @param {string} [options.capabilityToken] - Capability token for verification
- * @param {'inbound'|'outbound'} [options.direction='inbound'] - Grant direction
- * @returns {Promise<boolean>} Success indicator
- */
-export async function grantAccess(client, appname, partnerPubKey, scope, permissions, options = {}) {
-  const registry = await getFederationRegistry(client, appname);
-  const { expiresAt = null, capabilityToken = null, direction = 'inbound' } = options;
-
-  // Find or create partner entry
-  let partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
-
-  if (!partner) {
-    partner = {
-      pubKey: partnerPubKey,
-      alias: null,
-      addedAt: Date.now(),
-      addedVia: 'access_grant',
-      inboundCapabilities: [],
-      outboundCapabilities: [],
-      writeGrants: [],
-      accessGrants: [], // New unified array
-    };
-    registry.federatedWith.push(partner);
-  }
-
-  // Ensure accessGrants array exists
-  if (!partner.accessGrants) {
-    partner.accessGrants = [];
-  }
-
-  // Normalize scope
-  const normalizedScope = {
-    holonId: scope.holonId || '*',
-    lensName: scope.lensName || '*',
-  };
-
-  // Check if grant already exists for this scope and direction
-  const existingIndex = partner.accessGrants.findIndex(g =>
-    g.scope.holonId === normalizedScope.holonId &&
-    g.scope.lensName === normalizedScope.lensName &&
-    g.direction === direction
-  );
-
-  const grant = {
-    scope: normalizedScope,
-    permissions: [...permissions],
-    grantedAt: Date.now(),
-    expiresAt,
-    capabilityToken,
-    direction,
-  };
-
-  if (existingIndex >= 0) {
-    // Update existing grant
-    partner.accessGrants[existingIndex] = grant;
-  } else {
-    // Add new grant
-    partner.accessGrants.push(grant);
-  }
-
-  return saveFederationRegistry(client, appname, registry);
-}
-
-/**
- * Revoke access from a partner.
- * Removes specific permissions from an existing grant.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} partnerPubKey - Partner's public key
- * @param {Object} scope - Access scope { holonId, lensName }
- * @param {string[]} [permissions] - Permissions to revoke (if omitted, revokes entire grant)
- * @param {Object} [options={}] - Revoke options
- * @param {'inbound'|'outbound'} [options.direction='inbound'] - Grant direction
- * @returns {Promise<boolean>} Success indicator
+ * Get a specific federated partner (O(1) lookup via index).
  */
-export async function revokeAccess(client, appname, partnerPubKey, scope, permissions = null, options = {}) {
-  const registry = await getFederationRegistry(client, appname);
-  const { direction = 'inbound' } = options;
-
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
-
-  if (!partner || !partner.accessGrants) {
-    return false;
-  }
-
-  const normalizedScope = {
-    holonId: scope.holonId || '*',
-    lensName: scope.lensName || '*',
-  };
-
-  const grantIndex = partner.accessGrants.findIndex(g =>
-    g.scope.holonId === normalizedScope.holonId &&
-    g.scope.lensName === normalizedScope.lensName &&
-    g.direction === direction
-  );
-
-  if (grantIndex < 0) {
-    return false;
-  }
-
-  if (permissions === null) {
-    // Remove entire grant
-    partner.accessGrants.splice(grantIndex, 1);
-  } else {
-    // Remove specific permissions
-    const grant = partner.accessGrants[grantIndex];
-    grant.permissions = grant.permissions.filter(p => !permissions.includes(p));
-
-    // If no permissions left, remove the grant entirely
-    if (grant.permissions.length === 0) {
-      partner.accessGrants.splice(grantIndex, 1);
-    }
-  }
-
-  return saveFederationRegistry(client, appname, registry);
-}
-
-/**
- * Find an access grant for a partner matching the given scope and permission.
- * Checks unified accessGrants first, then falls back to legacy structures for backward compatibility.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} partnerPubKey - Partner's public key
- * @param {Object} scope - Access scope { holonId, lensName }
- * @param {string} permission - Permission to check ('read' or 'write')
- * @param {Object} [options={}] - Options
- * @param {'inbound'|'outbound'} [options.direction='inbound'] - Grant direction
- * @returns {Promise<AccessGrant|null>} Matching grant or null
- */
-export async function findAccessGrant(client, appname, partnerPubKey, scope, permission, options = {}) {
-  const registry = await getFederationRegistry(client, appname);
-  const { direction = 'inbound' } = options;
-  const now = Date.now();
-
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
-
-  if (!partner) {
-    return null;
-  }
-
-  // Check unified accessGrants first
-  if (partner.accessGrants && partner.accessGrants.length > 0) {
-    for (const grant of partner.accessGrants) {
-      // Check expiration
-      if (grant.expiresAt && grant.expiresAt < now) {
-        continue;
-      }
-
-      // Check direction
-      if (grant.direction !== direction) {
-        continue;
-      }
-
-      // Check permission
-      if (!grant.permissions.includes(permission)) {
-        continue;
-      }
-
-      // Check scope match
-      if (matchScope(grant.scope, scope)) {
-        return grant;
-      }
-    }
-  }
-
-  // Fall back to legacy structures for backward compatibility
-  if (permission === 'read' && direction === 'inbound') {
-    // Check inboundCapabilities
-    if (partner.inboundCapabilities) {
-      for (const cap of partner.inboundCapabilities) {
-        if (cap.expires && cap.expires < now) continue;
-        if (cap.permissions && !cap.permissions.includes('read')) continue;
-        if (matchScope(cap.scope, scope)) {
-          return {
-            scope: cap.scope,
-            permissions: cap.permissions || ['read'],
-            grantedAt: cap.receivedAt || Date.now(),
-            expiresAt: cap.expires || null,
-            capabilityToken: cap.token,
-            direction: 'inbound',
-            _legacy: true,
-          };
-        }
-      }
-    }
-  }
-
-  if (permission === 'write' && direction === 'inbound') {
-    // Check writeGrants
-    if (partner.writeGrants) {
-      for (const wg of partner.writeGrants) {
-        if (wg.expiresAt && wg.expiresAt < now) continue;
-        if (wg.lensName === scope.lensName || wg.lensName === '*') {
-          return {
-            scope: { holonId: '*', lensName: wg.lensName },
-            permissions: ['write'],
-            grantedAt: wg.grantedAt || Date.now(),
-            expiresAt: wg.expiresAt || null,
-            direction: 'inbound',
-            _legacy: true,
-          };
-        }
-      }
-    }
+export async function getFederatedPartner(client, appname, partnerPubKey) {
+  await getFederationRegistry(client, appname);
+  const cacheKey = getCacheKey(client, appname);
+  const cached = registryCache.get(cacheKey);
+  if (cached && cached.partnerIndex) {
+    return cached.partnerIndex.get(partnerPubKey) || null;
   }
-
   return null;
 }
-
-/**
- * Get all access grants for a partner.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} partnerPubKey - Partner's public key
- * @param {Object} [options={}] - Options
- * @param {'inbound'|'outbound'|'all'} [options.direction='all'] - Filter by direction
- * @param {boolean} [options.includeLegacy=true] - Include legacy grants
- * @returns {Promise<AccessGrant[]>} Array of access grants
- */
-export async function getAccessGrants(client, appname, partnerPubKey, options = {}) {
-  const registry = await getFederationRegistry(client, appname);
-  const { direction = 'all', includeLegacy = true } = options;
-  const now = Date.now();
-
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
-
-  if (!partner) {
-    return [];
-  }
-
-  const results = [];
-
-  // Add unified accessGrants
-  if (partner.accessGrants) {
-    for (const grant of partner.accessGrants) {
-      // Filter expired
-      if (grant.expiresAt && grant.expiresAt < now) continue;
-      // Filter by direction
-      if (direction !== 'all' && grant.direction !== direction) continue;
-      results.push(grant);
-    }
-  }
-
-  // Add legacy grants if requested
-  if (includeLegacy) {
-    // Convert inboundCapabilities
-    if (partner.inboundCapabilities && (direction === 'all' || direction === 'inbound')) {
-      for (const cap of partner.inboundCapabilities) {
-        if (cap.expires && cap.expires < now) continue;
-        results.push({
-          scope: cap.scope,
-          permissions: cap.permissions || ['read'],
-          grantedAt: cap.receivedAt || Date.now(),
-          expiresAt: cap.expires || null,
-          capabilityToken: cap.token,
-          direction: 'inbound',
-          _legacy: true,
-        });
-      }
-    }
-
-    // Convert writeGrants
-    if (partner.writeGrants && (direction === 'all' || direction === 'inbound')) {
-      for (const wg of partner.writeGrants) {
-        if (wg.expiresAt && wg.expiresAt < now) continue;
-        results.push({
-          scope: { holonId: '*', lensName: wg.lensName },
-          permissions: ['write'],
-          grantedAt: wg.grantedAt || Date.now(),
-          expiresAt: wg.expiresAt || null,
-          direction: 'inbound',
-          _legacy: true,
-        });
-      }
-    }
-  }
-
-  return results;
-}
-
-/**
- * Migrate legacy grants to unified accessGrants structure.
- * This should be called during registry load to auto-migrate old data.
- *
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @returns {Promise<Object>} Migration result { migratedPartners, migratedGrants }
- */
-export async function migrateToUnifiedGrants(client, appname) {
-  const registry = await getFederationRegistry(client, appname);
-  let migratedPartners = 0;
-  let migratedGrants = 0;
-
-  for (const partner of registry.federatedWith) {
-    let partnerModified = false;
-
-    // Initialize accessGrants if not present
-    if (!partner.accessGrants) {
-      partner.accessGrants = [];
-    }
-
-    // Migrate inboundCapabilities
-    if (partner.inboundCapabilities && partner.inboundCapabilities.length > 0) {
-      for (const cap of partner.inboundCapabilities) {
-        // Check if already migrated
-        const alreadyMigrated = partner.accessGrants.some(g =>
-          g.scope.holonId === cap.scope?.holonId &&
-          g.scope.lensName === cap.scope?.lensName &&
-          g.direction === 'inbound' &&
-          g._migratedFrom === 'inboundCapability'
-        );
-
-        if (!alreadyMigrated && cap.scope) {
-          partner.accessGrants.push({
-            scope: { holonId: cap.scope.holonId || '*', lensName: cap.scope.lensName || '*' },
-            permissions: cap.permissions || ['read'],
-            grantedAt: cap.receivedAt || Date.now(),
-            expiresAt: cap.expires || null,
-            capabilityToken: cap.token,
-            direction: 'inbound',
-            _migratedFrom: 'inboundCapability',
-          });
-          migratedGrants++;
-          partnerModified = true;
-        }
-      }
-    }
-
-    // Migrate writeGrants
-    if (partner.writeGrants && partner.writeGrants.length > 0) {
-      for (const wg of partner.writeGrants) {
-        // Check if already migrated
-        const alreadyMigrated = partner.accessGrants.some(g =>
-          g.scope.lensName === wg.lensName &&
-          g.permissions.includes('write') &&
-          g.direction === 'inbound' &&
-          g._migratedFrom === 'writeGrant'
-        );
-
-        if (!alreadyMigrated) {
-          partner.accessGrants.push({
-            scope: { holonId: '*', lensName: wg.lensName },
-            permissions: ['write'],
-            grantedAt: wg.grantedAt || Date.now(),
-            expiresAt: wg.expiresAt || null,
-            direction: 'inbound',
-            _migratedFrom: 'writeGrant',
-          });
-          migratedGrants++;
-          partnerModified = true;
-        }
-      }
-    }
-
-    if (partnerModified) {
-      migratedPartners++;
-    }
-  }
-
-  if (migratedGrants > 0) {
-    await saveFederationRegistry(client, appname, registry);
-  }
-
-  return { migratedPartners, migratedGrants };
-}
-
-/**
- * Convert legacy lensConfig format (v1.0) to unified permissions format (v2.0).
- *
- * @param {Object} legacyConfig - Legacy lens config { inbound, outbound, writeInbound, writeOutbound }
- * @returns {Object} Unified permissions format { version, permissions }
- */
-export function convertLegacyLensConfig(legacyConfig) {
-  if (!legacyConfig) return { version: '2.0', permissions: {} };
-
-  const permissions = {};
-
-  // Process inbound (read receive)
-  for (const lens of (legacyConfig.inbound || [])) {
-    if (!permissions[lens]) {
-      permissions[lens] = { receive: [], share: [] };
-    }
-    if (!permissions[lens].receive.includes('read')) {
-      permissions[lens].receive.push('read');
-    }
-  }
-
-  // Process outbound (read share)
-  for (const lens of (legacyConfig.outbound || [])) {
-    if (!permissions[lens]) {
-      permissions[lens] = { receive: [], share: [] };
-    }
-    if (!permissions[lens].share.includes('read')) {
-      permissions[lens].share.push('read');
-    }
-  }
-
-  // Process writeInbound (write receive)
-  for (const lens of (legacyConfig.writeInbound || [])) {
-    if (!permissions[lens]) {
-      permissions[lens] = { receive: [], share: [] };
-    }
-    if (!permissions[lens].receive.includes('write')) {
-      permissions[lens].receive.push('write');
-    }
-  }
-
-  // Process writeOutbound (write share)
-  for (const lens of (legacyConfig.writeOutbound || [])) {
-    if (!permissions[lens]) {
-      permissions[lens] = { receive: [], share: [] };
-    }
-    if (!permissions[lens].share.includes('write')) {
-      permissions[lens].share.push('write');
-    }
-  }
-
-  return { version: '2.0', permissions };
-}
-
-/**
- * Convert unified permissions format (v2.0) to legacy lensConfig format (v1.0).
- * Useful for backward compatibility with older clients.
- *
- * @param {Object} unifiedConfig - Unified permissions { version, permissions }
- * @returns {Object} Legacy lens config { inbound, outbound, writeInbound, writeOutbound }
- */
-export function convertToLegacyLensConfig(unifiedConfig) {
-  if (!unifiedConfig || !unifiedConfig.permissions) {
-    return { inbound: [], outbound: [], writeInbound: [], writeOutbound: [] };
-  }
-
-  const legacy = {
-    inbound: [],
-    outbound: [],
-    writeInbound: [],
-    writeOutbound: [],
-  };
-
-  for (const [lensName, perms] of Object.entries(unifiedConfig.permissions)) {
-    // Read receive → inbound
-    if (perms.receive?.includes('read')) {
-      legacy.inbound.push(lensName);
-    }
-    // Read share → outbound
-    if (perms.share?.includes('read')) {
-      legacy.outbound.push(lensName);
-    }
-    // Write receive → writeInbound
-    if (perms.receive?.includes('write')) {
-      legacy.writeInbound.push(lensName);
-    }
-    // Write share → writeOutbound
-    if (perms.share?.includes('write')) {
-      legacy.writeOutbound.push(lensName);
-    }
-  }
-
-  return legacy;
-}