holosphere 2.0.0-alpha13 → 2.0.0-alpha15

package/src/federation/registry.js

@@ -14,16 +14,81 @@ import { matchScope } from '../crypto/secp256k1.js';
 
 const FEDERATION_TABLE = 'federations';
 
+// ============================================================================
+// Registry Cache - Avoids repeated storage reads
+// ============================================================================
+
+/**
+ * @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}` */
+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) {
+    if (partner.pubKey) {
+      index.set(partner.pubKey, partner);
+    }
+  }
+  return index;
+}
+
 /**
- * Get the federation registry for this holosphere
+ * 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);
+}
+
+/**
+ * Get the federation registry for this holosphere (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
  * @returns {Promise<Object>} Federation registry
  */
-export async function getFederationRegistry(client, appname) {
-  const registry = await readGlobal(client, appname, FEDERATION_TABLE, client.publicKey);
+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) {
+      return cached.registry;
+    }
+  }
 
-  return registry || {
+  // Read from storage
+  const registry = await readGlobal(client, appname, FEDERATION_TABLE, client.publicKey) || {
     id: client.publicKey,
     federatedWith: [],
     discoveryEnabled: false,
@@ -31,6 +96,37 @@ export async function getFederationRegistry(client, appname) {
     defaultScope: { holonId: '*', lensName: '*' },
     defaultPermissions: ['read'],
   };
+
+  // Build partner index and cache
+  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;
 }
 
 /**
@@ -41,6 +137,8 @@ export async function getFederationRegistry(client, appname) {
  * @returns {Promise<boolean>} Success indicator
  */
 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);
 }
 
@@ -70,10 +168,18 @@ export async function addFederatedPartner(client, appname, partnerPubKey, option
     }
 
     if (options.inboundCapabilities) {
-      existing.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());
     }
 
     existing.updatedAt = Date.now();
@@ -125,20 +231,20 @@ export async function getFederatedAuthors(client, appname) {
 }
 
 /**
- * Get a specific federated partner
+ * 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) {
-  const registry = await getFederationRegistry(client, appname);
-  return registry.federatedWith.find(p => p.pubKey === partnerPubKey) || null;
+  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
@@ -146,62 +252,35 @@ export async function getFederatedPartner(client, appname, partnerPubKey) {
  * @returns {Promise<Object|null>} Capability entry or null
  */
 export async function getCapabilityForAuthor(client, appname, authorPubKey, scope) {
-  const registry = await getFederationRegistry(client, appname);
-
-  console.log('[Registry] 🔍 getCapabilityForAuthor called:', {
-    authorPubKey: authorPubKey?.slice(0, 12) + '...',
-    scope,
-    federatedWithCount: registry.federatedWith?.length || 0,
-    federatedPartners: registry.federatedWith?.map(p => p.pubKey?.slice(0, 12) + '...') || []
-  });
-
-  const partner = registry.federatedWith.find(p => p.pubKey === authorPubKey);
+  // Use O(1) index lookup instead of array.find()
+  const partner = await getPartnerFromIndex(client, appname, authorPubKey);
 
   if (!partner) {
-    console.log('[Registry] ❌ Partner not found in federatedWith');
     return null;
   }
 
   if (!partner.inboundCapabilities || partner.inboundCapabilities.length === 0) {
-    console.log('[Registry] ❌ Partner has no inboundCapabilities:', {
-      partnerPubKey: authorPubKey?.slice(0, 12) + '...',
-      hasInboundCaps: !!partner.inboundCapabilities,
-      inboundCapsLength: partner.inboundCapabilities?.length || 0
-    });
     return null;
   }
 
-  console.log('[Registry] Partner found with inboundCapabilities:', {
-    partnerPubKey: authorPubKey?.slice(0, 12) + '...',
-    capsCount: partner.inboundCapabilities.length,
-    capScopes: partner.inboundCapabilities.map(c => c.scope)
-  });
+  const now = Date.now();
 
   // Find matching, non-expired capability
-  const result = partner.inboundCapabilities.find(cap => {
+  // 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 < Date.now()) {
-      console.log('[Registry] Capability expired:', { expires: cap.expires, now: Date.now() });
-      return false;
+    if (cap.expires && cap.expires < now) {
+      continue;
     }
 
     // Check scope match (supports wildcards)
-    const matches = matchScope(cap.scope, scope);
-    console.log('[Registry] Scope match check:', {
-      capScope: cap.scope,
-      requestedScope: scope,
-      matches
-    });
-    return matches;
-  }) || null;
-
-  if (result) {
-    console.log('[Registry] ✅ Matching capability found');
-  } else {
-    console.log('[Registry] ❌ No matching capability found');
+    if (matchScope(cap.scope, scope)) {
+      return cap;
+    }
   }
 
-  return result;
+  return null;
 }
 
 /**
@@ -217,17 +296,10 @@ export async function getCapabilityForAuthor(client, appname, authorPubKey, scop
  * @returns {Promise<boolean>} Success indicator
  */
 export async function storeInboundCapability(client, appname, partnerPubKey, capabilityInfo) {
-  console.log('[Registry] 📥 storeInboundCapability called:', {
-    partnerPubKey: partnerPubKey?.slice(0, 12) + '...',
-    scope: capabilityInfo?.scope,
-    hasToken: !!capabilityInfo?.token
-  });
-
   const registry = await getFederationRegistry(client, appname);
   const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
 
   if (!partner) {
-    console.log('[Registry] Partner not in registry, auto-adding with capability');
     // Auto-add partner if not exists
     return addFederatedPartner(client, appname, partnerPubKey, {
       addedVia: 'capability_received',
@@ -245,14 +317,12 @@ export async function storeInboundCapability(client, appname, partnerPubKey, cap
   );
 
   if (existingIndex >= 0) {
-    console.log('[Registry] Updating existing capability at index:', existingIndex);
     // Update existing capability
     partner.inboundCapabilities[existingIndex] = {
       ...capabilityInfo,
       updatedAt: Date.now()
     };
   } else {
-    console.log('[Registry] Adding new capability, total will be:', partner.inboundCapabilities.length + 1);
     // Add new capability
     partner.inboundCapabilities.push({
       ...capabilityInfo,
@@ -260,9 +330,7 @@ export async function storeInboundCapability(client, appname, partnerPubKey, cap
     });
   }
 
-  const result = await saveFederationRegistry(client, appname, registry);
-  console.log('[Registry] ✅ Capability stored, registry saved:', result);
-  return result;
+  return saveFederationRegistry(client, appname, registry);
 }
 
 /**
@@ -542,3 +610,655 @@ export async function getSelfCapability(client, appname, scope) {
 export function isSelfCapability(capabilityInfo) {
   return capabilityInfo && capabilityInfo.isSelfCapability === true;
 }
+
+// ============================================================================
+// Write Grant Functions (Cross-Holon Write Access)
+// ============================================================================
+
+/**
+ * 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
+ */
+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,
+          };
+        }
+      }
+    }
+  }
+
+  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;
+}