holosphere 2.0.0-alpha20 → 2.0.0-alpha21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holosphere",
-  "version": "2.0.0-alpha20",
+  "version": "2.0.0-alpha21",
   "description": "Holonic geospatial communication infrastructure combining H3 hexagonal indexing with distributed P2P storage",
   "type": "module",
   "bin": {

package/src/crypto/secp256k1.js

@@ -12,6 +12,15 @@ import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
 import { secp256k1, schnorr } from '@noble/curves/secp256k1';
 
+/**
+ * Check if a string is a 64-char hex public key (x-only schnorr format).
+ * @param {string} str - String to check
+ * @returns {boolean} True if string is a valid public key format
+ */
+export function isPubkey(str) {
+  return typeof str === 'string' && /^[0-9a-f]{64}$/i.test(str);
+}
+
 /**
  * Get public key from private key (x-only / schnorr format for Nostr compatibility)
  * @param {string} privateKey - Private key (hex string)
@@ -74,6 +83,98 @@ export async function verify(content, signature, publicKey) {
   }
 }
 
+/**
+ * Normalize a capability token to a plain string.
+ * Handles: object wrappers ({ token: "..." }), Buffer serialization, comma-separated byte strings.
+ * @param {string|Object} token - Token in any supported format
+ * @returns {string|null} Normalized token string, or null if invalid
+ */
+export function normalizeTokenString(token) {
+  // Handle capability object wrapper { token, scope, permissions }
+  if (token && typeof token === 'object' && token.token) {
+    token = token.token;
+  }
+
+  // Handle Buffer serialization format {"type":"Buffer","data":[...]}
+  if (token && typeof token === 'object' && token.type === 'Buffer' && Array.isArray(token.data)) {
+    try {
+      token = String.fromCharCode.apply(null, token.data);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // Handle comma-separated byte string (e.g., "123,34,116,...")
+  if (typeof token === 'string' && /^\d+(,\d+)+$/.test(token.substring(0, 50))) {
+    try {
+      const bytes = token.split(',').map(Number);
+      token = String.fromCharCode.apply(null, bytes);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  if (typeof token === 'string') {
+    return token;
+  }
+
+  return null;
+}
+
+/**
+ * Parse a capability token string into its components.
+ * Handles base64-encoded, signed (payload.signature), and raw JSON formats.
+ * @private
+ * @param {string} token - Normalized token string
+ * @returns {{ tokenObj: Object, payload: string, signature: string|null }|null} Parsed token or null
+ */
+function _parseToken(token) {
+  try {
+    if (typeof token !== 'string') return null;
+
+    let payload;
+    let signature = null;
+    let tokenObj;
+
+    if (token.startsWith('ey') || (!token.includes('.') && !token.startsWith('{'))) {
+      // Base64 encoded (with or without signature)
+      if (token.includes('.')) {
+        const parts = token.split('.');
+        signature = parts[1];
+        const decoded = typeof atob === 'function'
+          ? atob(parts[0])
+          : Buffer.from(parts[0], 'base64').toString('utf8');
+        payload = decoded;
+      } else {
+        const decoded = typeof atob === 'function'
+          ? atob(token)
+          : Buffer.from(token, 'base64').toString('utf8');
+        payload = decoded;
+      }
+      tokenObj = JSON.parse(payload);
+    } else if (token.startsWith('{')) {
+      payload = token;
+      tokenObj = JSON.parse(token);
+    } else {
+      return null;
+    }
+
+    return { tokenObj, payload, signature };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Hash a capability token using SHA-256.
+ * @param {string} token - Capability token string
+ * @returns {string} Hex-encoded SHA-256 hash
+ */
+export function hashToken(token) {
+  const encoder = new TextEncoder();
+  return bytesToHex(sha256(encoder.encode(token)));
+}
+
 /**
  * Match token scope against requested scope with wildcard support
  * Supports:
@@ -224,77 +325,26 @@ export async function issueSelfCapability(permissions, scope, authorPubKey, opti
  */
 export async function verifyCapability(token, requiredPermission, scope) {
   try {
-    let tokenObj;
-
-    // Handle capability object wrapper { token, scope, permissions }
-    // This normalizes both formats: raw token string and capability info object
-    if (token && typeof token === 'object' && token.token) {
-      token = token.token;  // Extract the actual token string
-    }
-
-    // Handle Buffer serialization format {"type":"Buffer","data":[...]}
-    // This can happen when Buffer is polyfilled and JSON serialized
-    if (token && typeof token === 'object' && token.type === 'Buffer' && Array.isArray(token.data)) {
-      try {
-        // Convert Buffer data array back to string
-        token = String.fromCharCode.apply(null, token.data);
-      } catch (e) {
-        console.log('[verifyCapability] ❌ Failed to decode Buffer object:', e.message);
-        return false;
-      }
+    const normalized = normalizeTokenString(token);
+    if (!normalized) {
+      console.log('[verifyCapability] ❌ Failed to normalize token');
+      return false;
     }
 
-    // Handle comma-separated byte string (e.g., "123,34,116,...")
-    // This can happen when Uint8Array.toString() is called
-    if (typeof token === 'string' && /^\d+(,\d+)+$/.test(token.substring(0, 50))) {
-      try {
-        const bytes = token.split(',').map(Number);
-        token = String.fromCharCode.apply(null, bytes);
-      } catch (e) {
-        console.log('[verifyCapability] ❌ Failed to decode byte string:', e.message);
-        return false;
-      }
-    }
+    let tokenObj;
 
-    // Decode if string
-    if (typeof token === 'string') {
-      // Check if it's a base64-encoded token (starts with "ey" for JSON base64)
-      if (token.startsWith('ey') || (!token.includes('.') && !token.startsWith('{'))) {
-        // Base64 encoded (with or without signature)
-        try {
-          const payload = token.includes('.') ? token.split('.')[0] : token;
-          // Prefer browser-native atob to avoid Buffer issues
-          const decoded = typeof atob === 'function'
-            ? atob(payload)
-            : Buffer.from(payload, 'base64').toString('utf8');
-          tokenObj = JSON.parse(decoded);
-        } catch (e) {
-          console.log('[verifyCapability] ❌ Token is not valid base64 JSON:', {
-            preview: token.substring(0, 50),
-            error: e.message
-          });
-          return false;
-        }
-      } else if (token.startsWith('{')) {
-        // Already JSON string
-        try {
-          tokenObj = JSON.parse(token);
-        } catch (e) {
-          console.log('[verifyCapability] ❌ Token is not valid JSON:', {
-            preview: token.substring(0, 50),
-            error: e.message
-          });
-          return false;
-        }
-      } else {
-        console.log('[verifyCapability] ❌ Unknown token format:', token.substring(0, 50));
+    // If it's a string, parse it
+    if (typeof normalized === 'string') {
+      const parsed = _parseToken(normalized);
+      if (!parsed) {
+        console.log('[verifyCapability] ❌ Failed to parse token');
         return false;
       }
-    } else if (token && typeof token === 'object') {
-      // Already decoded token object
-      tokenObj = token;
+      tokenObj = parsed.tokenObj;
+    } else if (normalized && typeof normalized === 'object') {
+      tokenObj = normalized;
     } else {
-      console.log('[verifyCapability] ❌ Invalid token:', typeof token);
+      console.log('[verifyCapability] ❌ Invalid token:', typeof normalized);
       return false;
     }
 
@@ -351,55 +401,20 @@ export async function verifyCapability(token, requiredPermission, scope) {
  */
 export async function verifyCapabilityIssuer(token, expectedIssuer) {
   try {
-    // Handle capability object wrapper
-    if (token && typeof token === 'object' && token.token) {
-      token = token.token;
-    }
-
-    // Handle Buffer serialization format
-    if (token && typeof token === 'object' && token.type === 'Buffer' && Array.isArray(token.data)) {
-      token = String.fromCharCode.apply(null, token.data);
-    }
-
-    // Must be a string at this point
-    if (typeof token !== 'string') {
-      console.log('[verifyCapabilityIssuer] ❌ Token is not a string');
+    const normalized = normalizeTokenString(token);
+    if (!normalized) {
+      console.log('[verifyCapabilityIssuer] ❌ Failed to normalize token');
       return false;
     }
 
-    // Extract payload and signature from token
-    let payload;
-    let signature;
-    let tokenObj;
-
-    if (token.includes('.')) {
-      // Token has signature: payload.signature
-      const parts = token.split('.');
-      const encodedPayload = parts[0];
-      signature = parts[1];
-
-      // Decode payload
-      const decoded = typeof atob === 'function'
-        ? atob(encodedPayload)
-        : Buffer.from(encodedPayload, 'base64').toString('utf8');
-      payload = decoded;
-      tokenObj = JSON.parse(decoded);
-    } else if (token.startsWith('ey')) {
-      // Base64 encoded without signature
-      const decoded = typeof atob === 'function'
-        ? atob(token)
-        : Buffer.from(token, 'base64').toString('utf8');
-      payload = decoded;
-      tokenObj = JSON.parse(decoded);
-    } else if (token.startsWith('{')) {
-      // Already JSON string
-      payload = token;
-      tokenObj = JSON.parse(token);
-    } else {
-      console.log('[verifyCapabilityIssuer] ❌ Unknown token format');
+    const parsed = _parseToken(normalized);
+    if (!parsed) {
+      console.log('[verifyCapabilityIssuer] ❌ Failed to parse token');
       return false;
     }
 
+    const { tokenObj, payload, signature } = parsed;
+
     // Verify issuer field matches expected
     if (tokenObj.issuer !== expectedIssuer) {
       console.log('[verifyCapabilityIssuer] ❌ Issuer mismatch:', {
@@ -418,9 +433,9 @@ export async function verifyCapabilityIssuer(token, expectedIssuer) {
         return false;
       }
     } else {
-      // No signature - for backwards compatibility, allow unsigned tokens
-      // but log a warning
-      console.log('[verifyCapabilityIssuer] ⚠️ Token has no signature - cannot verify cryptographically');
+      // No signature - cannot cryptographically verify issuer identity
+      console.log('[verifyCapabilityIssuer] ❌ Token has no signature - cannot verify issuer');
+      return false;
     }
 
     console.log('[verifyCapabilityIssuer] ✅ Issuer verified');
@@ -439,35 +454,11 @@ export async function verifyCapabilityIssuer(token, expectedIssuer) {
  * @returns {Object|null} Decoded token payload or null if invalid
  */
 export function decodeCapability(token) {
-  try {
-    // Handle capability object wrapper
-    if (token && typeof token === 'object' && token.token) {
-      token = token.token;
-    }
-
-    // Handle Buffer serialization format
-    if (token && typeof token === 'object' && token.type === 'Buffer' && Array.isArray(token.data)) {
-      token = String.fromCharCode.apply(null, token.data);
-    }
+  const normalized = normalizeTokenString(token);
+  if (!normalized) return null;
 
-    if (typeof token !== 'string') {
-      return null;
-    }
-
-    if (token.startsWith('ey') || (!token.includes('.') && !token.startsWith('{'))) {
-      const payload = token.includes('.') ? token.split('.')[0] : token;
-      const decoded = typeof atob === 'function'
-        ? atob(payload)
-        : Buffer.from(payload, 'base64').toString('utf8');
-      return JSON.parse(decoded);
-    } else if (token.startsWith('{')) {
-      return JSON.parse(token);
-    }
-
-    return null;
-  } catch (error) {
-    return null;
-  }
+  const parsed = _parseToken(normalized);
+  return parsed ? parsed.tokenObj : null;
 }
 
 /**

package/src/federation/capabilities.js

@@ -1,162 +1,46 @@
 /**
- * @fileoverview Federation Capabilities Module
+ * @fileoverview Federation Capabilities Module — Re-exports
  *
- * Handles capability token issuance, verification, and management
- * for federation operations. Extracted from federation-methods.js
- * for better modularity.
+ * This module re-exports capability functions from their canonical locations
+ * (crypto/secp256k1.js and federation/registry.js) for backward compatibility.
+ *
+ * Prefer importing directly from the canonical modules in new code.
  *
  * @module federation/capabilities
  */
 
-import * as crypto from '../crypto/secp256k1.js';
-import * as registry from './registry.js';
-import { sha256 } from '@noble/hashes/sha256';
-import { bytesToHex } from '@noble/hashes/utils';
-
-/**
- * Issue a capability token for federation
- * @param {Object} client - NostrClient instance
- * @param {string} targetPubKey - Target public key to grant access to
- * @param {Object} scope - Access scope { holonId, lensName, dataId }
- * @param {string[]} permissions - Array of permissions ('read', 'write')
- * @param {Object} options - Capability options
- * @param {number} [options.expiresIn=3600000] - Expiration time in milliseconds
- * @param {boolean} [options.isSelfCapability=false] - Whether this is a self-capability
- * @returns {Promise<string>} Capability token
- */
-export async function issueCapability(client, targetPubKey, scope, permissions, options = {}) {
-  const {
-    expiresIn = 3600000,
-    isSelfCapability = false,
-  } = options;
-
-  const token = await crypto.issueCapability(
-    permissions,
-    scope,
-    targetPubKey,
-    {
-      expiresIn,
-      issuer: client.publicKey,
-      issuerKey: client.privateKey,
-      isSelfCapability,
-    }
-  );
-
-  return token;
-}
-
-/**
- * Issue capability for a specific lens
- * @param {Object} client - NostrClient instance
- * @param {string} holonId - Holon ID
- * @param {string} lensName - Lens name
- * @param {string} targetPubKey - Target public key
- * @param {Object} options - Options
- * @returns {Promise<Object>} Capability info { token, scope, permissions }
- */
-export async function issueCapabilityForLens(client, holonId, lensName, targetPubKey, options = {}) {
-  const {
-    permissions = ['read'],
-    expiresIn = 365 * 24 * 60 * 60 * 1000, // 1 year default
-  } = options;
-
-  const scope = { holonId, lensName, dataId: '*' };
-
-  const token = await issueCapability(client, targetPubKey, scope, permissions, {
-    expiresIn,
-    isSelfCapability: client.publicKey === targetPubKey,
-  });
-
-  return {
-    token,
-    scope,
-    permissions,
-    expiresAt: Date.now() + expiresIn,
-  };
-}
-
-/**
- * Issue capabilities for multiple lenses
- * @param {Object} client - NostrClient instance
- * @param {string} holonId - Holon ID
- * @param {string[]} lensNames - Array of lens names
- * @param {string} targetPubKey - Target public key
- * @param {Object} options - Options
- * @returns {Promise<Object[]>} Array of capability info objects
- */
-export async function issueCapabilitiesForLenses(client, holonId, lensNames, targetPubKey, options = {}) {
-  const capabilities = [];
+export {
+  issueCapability,
+  verifyCapability,
+  hashToken,
+} from '../crypto/secp256k1.js';
 
-  for (const lensName of lensNames) {
-    try {
-      const capInfo = await issueCapabilityForLens(client, holonId, lensName, targetPubKey, options);
-      capabilities.push(capInfo);
-    } catch (err) {
-      console.warn(`[Capabilities] Failed to issue capability for ${lensName}:`, err.message);
-    }
-  }
+export {
+  issueCapabilityForLens,
+  issueCapabilitiesForLenses,
+  getCapabilityForAuthor as getCapabilityForPartner,
+  storeInboundCapability,
+  storeSelfCapability,
+} from './registry.js';
 
-  return capabilities;
-}
+import { storeSelfCapability, storeInboundCapability } from './registry.js';
 
 /**
- * Store a capability in the registry
+ * Store a capability in the registry (convenience wrapper)
  * @param {Object} client - NostrClient instance
  * @param {string} appname - Application namespace
  * @param {string} partnerPubKey - Partner's public key
  * @param {Object} capabilityInfo - Capability info to store
  * @param {Object} options - Options
+ * @param {boolean} [options.isSelf=false] - Whether this is a self-capability
  * @returns {Promise<boolean>} Success indicator
  */
 export async function storeCapability(client, appname, partnerPubKey, capabilityInfo, options = {}) {
   const { isSelf = false } = options;
 
   if (isSelf) {
-    return registry.storeSelfCapability(client, appname, capabilityInfo);
+    return storeSelfCapability(client, appname, capabilityInfo);
   } else {
-    return registry.storeInboundCapability(client, appname, partnerPubKey, capabilityInfo);
+    return storeInboundCapability(client, appname, partnerPubKey, capabilityInfo);
   }
 }
-
-/**
- * Hash a capability token for storage
- * @param {string} token - Capability token to hash
- * @returns {string} SHA256 hash of token
- */
-export function hashToken(token) {
-  const encoder = new TextEncoder();
-  return bytesToHex(sha256(encoder.encode(token)));
-}
-
-/**
- * Verify a capability token
- * @param {string} token - Capability token
- * @param {string} permission - Required permission
- * @param {Object} scope - Requested scope
- * @returns {Promise<boolean>} True if valid
- */
-export async function verifyCapability(token, permission, scope) {
-  return crypto.verifyCapability(token, permission, scope);
-}
-
-/**
- * Get capability for accessing a partner's data
- * @param {Object} client - NostrClient instance
- * @param {string} appname - Application namespace
- * @param {string} partnerPubKey - Partner's public key
- * @param {Object} scope - Requested scope
- * @returns {Promise<Object|null>} Capability entry or null
- */
-export async function getCapabilityForPartner(client, appname, partnerPubKey, scope) {
-  return registry.getCapabilityForAuthor(client, appname, partnerPubKey, scope);
-}
-
-export default {
-  issueCapability,
-  issueCapabilityForLens,
-  issueCapabilitiesForLenses,
-  storeCapability,
-  hashToken,
-  verifyCapability,
-  getCapabilityForPartner,
-};

package/src/federation/hologram.js

@@ -16,7 +16,7 @@
  */
 
 import { buildPath, write, read, update } from '../storage/unified-storage.js';
-import { verifyCapability, issueCapability, verifyCapabilityIssuer, decodeCapability } from '../crypto/secp256k1.js';
+import { verifyCapability, issueCapability, verifyCapabilityIssuer, decodeCapability, normalizeTokenString, isPubkey } from '../crypto/secp256k1.js';
 import { getCapabilityForAuthor, storeInboundCapability } from './registry.js';
 
 /** @constant {number} Maximum depth for hologram resolution chain */
@@ -113,10 +113,8 @@ export function createHologram(sourceHolon, targetHolon, lensName, dataId, appna
     throw new Error('capability is required for hologram creation (unified model)');
   }
 
-  // Normalize capability - ensure it's the token string, not a capability object
-  if (typeof capability === 'object' && capability.token) {
-    capability = capability.token;
-  }
+  // Normalize capability to plain token string
+  capability = normalizeTokenString(capability) || capability;
 
   const soul = buildPath(appname, sourceHolon, lensName, dataId);
 
@@ -289,9 +287,9 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
   let capability = hologram.capability;
   const authorPubKey = target.authorPubKey;
 
-  // Normalize capability - extract token string if it's a capability object
-  if (capability && typeof capability === 'object' && capability.token) {
-    capability = capability.token;
+  // Normalize capability to plain token string
+  if (capability) {
+    capability = normalizeTokenString(capability) || capability;
   }
 
   if (!capability && options.appname && authorPubKey) {
@@ -621,9 +619,7 @@ export async function propagateData(
 
     // Determine targetAuthorPubKey - the person who should be able to read the hologram
     // If targetHolon is a 64-char hex pubkey, use it directly as the target author
-    // Otherwise, this needs to be resolved via holon registry (TODO: add resolution)
-    const isPubkey = typeof targetHolon === 'string' && /^[0-9a-f]{64}$/i.test(targetHolon);
-    const targetAuthorPubKey = options.targetAuthorPubKey || (isPubkey ? targetHolon : client.publicKey);
+    const targetAuthorPubKey = options.targetAuthorPubKey || (isPubkey(targetHolon) ? targetHolon : client.publicKey);
 
     const hologram = await createHologramWithCapability(
       client,
@@ -738,36 +734,31 @@ export function getHologramSource(data) {
 }
 
 /**
- * Add a hologram reference to the source data's _meta.activeHolograms
- * This tracks all holograms pointing to this specific data item
- * If the source is itself a hologram, follows the chain to find the real source
+ * Follow a hologram chain to find the real (non-hologram) source data.
+ * If the data at the given location is a hologram, follows .target references
+ * until real data is found or max depth is reached.
+ * @private
  * @param {Object} client - Nostr client instance
  * @param {string} appname - Application namespace
- * @param {string} sourceHolon - Source holon ID (where original data lives)
- * @param {string} lensName - Lens name
+ * @param {string} holon - Starting holon ID
+ * @param {string} lens - Lens name
  * @param {string} dataId - Data ID
- * @param {string} targetHolon - Target holon ID (where hologram lives)
- * @returns {Promise<boolean>} Success indicator
+ * @param {number} [maxDepth=10] - Maximum chain depth
+ * @returns {Promise<{ sourcePath: string, sourceData: Object }|null>} Real source or null
  */
-export async function addActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon) {
+async function followToRealSource(client, appname, holon, lens, dataId, maxDepth = 10) {
   let currentAppname = appname;
-  let currentHolon = sourceHolon;
-  let currentLens = lensName;
+  let currentHolon = holon;
+  let currentLens = lens;
   let currentDataId = dataId;
   let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
 
-  // Read existing source data
-  // Note: May return null if called immediately after write (before relay persistence)
-  // This is expected - the hologram still works, we just can't track activeHolograms
   let sourceData = await read(client, sourcePath);
   if (!sourceData) {
-    return false;
+    return null;
   }
 
-  // If source is a hologram, follow the chain to find the real source
-  // This ensures activeHolograms is always tracked on the actual data, not on holograms
   let depth = 0;
-  const maxDepth = 10;
   while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
     depth++;
     currentAppname = sourceData.target.appname || currentAppname;
@@ -778,10 +769,34 @@ export async function addActiveHologram(client, appname, sourceHolon, lensName,
 
     sourceData = await read(client, sourcePath);
     if (!sourceData) {
-      return false;
+      return null;
     }
   }
 
+  return { sourcePath, sourceData };
+}
+
+/**
+ * Add a hologram reference to the source data's _meta.activeHolograms
+ * This tracks all holograms pointing to this specific data item
+ * If the source is itself a hologram, follows the chain to find the real source
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID (where original data lives)
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} targetHolon - Target holon ID (where hologram lives)
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function addActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon) {
+  // Note: May return null if called immediately after write (before relay persistence)
+  // This is expected - the hologram still works, we just can't track activeHolograms
+  const result = await followToRealSource(client, appname, sourceHolon, lensName, dataId);
+  if (!result) {
+    return false;
+  }
+
+  const { sourcePath, sourceData } = result;
 
   // Initialize _meta and activeHolograms if needed
   if (!sourceData._meta) {
@@ -827,34 +842,12 @@ export async function addActiveHologram(client, appname, sourceHolon, lensName,
  * @returns {Promise<boolean>} Success indicator
  */
 export async function removeActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon) {
-  let currentAppname = appname;
-  let currentHolon = sourceHolon;
-  let currentLens = lensName;
-  let currentDataId = dataId;
-  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
-
-  // Read existing source data
-  let sourceData = await read(client, sourcePath);
-  if (!sourceData) {
+  const result = await followToRealSource(client, appname, sourceHolon, lensName, dataId);
+  if (!result) {
     return false;
   }
 
-  // If source is a hologram, follow the chain to find the real source
-  let depth = 0;
-  const maxDepth = 10;
-  while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
-    depth++;
-    currentAppname = sourceData.target.appname || currentAppname;
-    currentHolon = sourceData.target.holonId;
-    currentLens = sourceData.target.lensName || currentLens;
-    currentDataId = sourceData.target.dataId || currentDataId;
-    sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
-
-    sourceData = await read(client, sourcePath);
-    if (!sourceData) {
-      return false;
-    }
-  }
+  const { sourcePath, sourceData } = result;
 
   if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
     return false;
@@ -887,35 +880,12 @@ export async function removeActiveHologram(client, appname, sourceHolon, lensNam
  * @returns {Promise<boolean>} Success indicator
  */
 export async function updateActiveHologramPlatform(client, appname, sourceHolon, lensName, dataId, targetHolon, platform, platformData) {
-  let currentAppname = appname;
-  let currentHolon = sourceHolon;
-  let currentLens = lensName;
-  let currentDataId = dataId;
-  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
-
-  // Read existing source data
-  // Note: May return null if called immediately after write (before relay persistence)
-  let sourceData = await read(client, sourcePath);
-  if (!sourceData) {
+  const result = await followToRealSource(client, appname, sourceHolon, lensName, dataId);
+  if (!result) {
     return false;
   }
 
-  // If source is a hologram, follow the chain to find the real source
-  let depth = 0;
-  const maxDepth = 10;
-  while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
-    depth++;
-    currentAppname = sourceData.target.appname || currentAppname;
-    currentHolon = sourceData.target.holonId;
-    currentLens = sourceData.target.lensName || currentLens;
-    currentDataId = sourceData.target.dataId || currentDataId;
-    sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
-
-    sourceData = await read(client, sourcePath);
-    if (!sourceData) {
-      return false;
-    }
-  }
+  const { sourcePath, sourceData } = result;
 
   if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
     console.warn(`No activeHolograms found for ${sourcePath}`);
@@ -1132,96 +1102,17 @@ export async function deleteHologram(client, appname, holonId, lensName, dataId,
  * @returns {Promise<Object>} Result with cleanup info
  */
 export async function cleanupCircularHolograms(client, appname, holonId, lensName, options = {}) {
-  const { dryRun = false } = options;
-  const result = {
-    scanned: 0,
-    circularFound: 0,
-    deleted: 0,
-    errors: [],
-    details: []
-  };
-
-  console.info(`🧹 ${dryRun ? '[DRY RUN] ' : ''}Cleaning up circular holograms in ${holonId}/${lensName}...`);
-
-  try {
-    // Get all data in this lens
-    const basePath = buildPath(appname, holonId, lensName);
-    // We need to iterate through all items - this requires listing capability
-    // For now, we'll rely on the caller to provide a list of IDs to check
-    // or we can use a different approach
-
-    // Alternative: Read the lens index if it exists
-    const lensIndexPath = buildPath(appname, holonId, lensName, '_index');
-    const lensIndex = await read(client, lensIndexPath);
-
-    if (!lensIndex || !Array.isArray(lensIndex.items)) {
-      console.warn(`   No index found for ${holonId}/${lensName}, cannot scan for circular references`);
-      console.info(`   Tip: Provide specific IDs to check using cleanupCircularHologramsByIds()`);
-      return result;
-    }
-
-    for (const itemId of lensIndex.items) {
-      result.scanned++;
-      const itemPath = buildPath(appname, holonId, lensName, itemId);
-      const item = await read(client, itemPath);
-
-      if (!item || item.hologram !== true || !item.target) {
-        continue; // Not a hologram, skip
-      }
-
-      // This is a hologram - check if it creates a circular reference
-      const sourceHolon = item.target.holonId;
-      const sourceDataId = item.target.dataId || itemId;
-      const sourceLens = item.target.lensName || lensName;
-
-      // Read the source data
-      const sourcePath = buildPath(item.target.appname || appname, sourceHolon, sourceLens, sourceDataId);
-      const sourceData = await read(client, sourcePath);
-
-      if (sourceData && sourceData.hologram === true && sourceData.target) {
-        // Source is also a hologram - check if it points back
-        if (sourceData.target.holonId === holonId) {
-          result.circularFound++;
-          const detail = {
-            itemId,
-            path: itemPath,
-            pointsTo: `${sourceHolon}/${sourceLens}/${sourceDataId}`,
-            circularWith: `${sourceData.target.holonId}/${sourceData.target.lensName}/${sourceData.target.dataId}`
-          };
-          result.details.push(detail);
-
-          console.warn(`   🔄 Found circular hologram:`);
-          console.warn(`      ${holonId}/${lensName}/${itemId} → ${sourceHolon}/${sourceLens}/${sourceDataId} → ${holonId}`);
-
-          if (!dryRun) {
-            // Delete this hologram
-            const deleteResult = await deleteHologram(client, appname, holonId, lensName, itemId);
-            if (deleteResult.success) {
-              result.deleted++;
-              console.info(`      ✓ Deleted circular hologram`);
-            } else {
-              result.errors.push({ itemId, error: deleteResult.error });
-              console.error(`      ❌ Failed to delete: ${deleteResult.error}`);
-            }
-          }
-        }
-      }
-    }
-
-    console.info(`🧹 Cleanup complete for ${holonId}/${lensName}:`);
-    console.info(`   Scanned: ${result.scanned}`);
-    console.info(`   Circular found: ${result.circularFound}`);
-    console.info(`   Deleted: ${result.deleted}`);
-    if (result.errors.length > 0) {
-      console.warn(`   Errors: ${result.errors.length}`);
-    }
-
-    return result;
-  } catch (error) {
-    console.error(`❌ Error during cleanup:`, error);
-    result.errors.push({ error: error.message });
-    return result;
+  // Read the lens index to get all item IDs
+  const lensIndexPath = buildPath(appname, holonId, lensName, '_index');
+  const lensIndex = await read(client, lensIndexPath);
+
+  if (!lensIndex || !Array.isArray(lensIndex.items)) {
+    console.warn(`   No index found for ${holonId}/${lensName}, cannot scan for circular references`);
+    console.info(`   Tip: Provide specific IDs to check using cleanupCircularHologramsByIds()`);
+    return { scanned: 0, circularFound: 0, deleted: 0, errors: [], details: [] };
   }
+
+  return cleanupCircularHologramsByIds(client, appname, holonId, lensName, lensIndex.items, options);
 }
 
 /**

package/src/federation/registry.js

@@ -10,7 +10,7 @@
  */
 
 import { writeGlobal, readGlobal } from '../storage/global-tables.js';
-import { matchScope } from '../crypto/secp256k1.js';
+import { matchScope, issueCapability as cryptoIssueCapability } from '../crypto/secp256k1.js';
 
 const FEDERATION_TABLE = 'federations';
 
@@ -135,6 +135,27 @@ async function getPartnerFromIndex(client, appname, partnerPubKey) {
   return null;
 }
 
+/**
+ * Find a partner in the registry using the cached O(1) index.
+ * Must be called AFTER getFederationRegistry() has been called (which populates the cache).
+ * Falls back to array.find() if cache is not available.
+ * @private
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} registryObj - The already-loaded registry object
+ * @param {string} partnerPubKey - Partner's public key
+ * @returns {Object|null} Partner object or null
+ */
+function findPartner(client, appname, registryObj, partnerPubKey) {
+  const cacheKey = getCacheKey(client, appname);
+  const cached = registryCache.get(cacheKey);
+  if (cached && cached.partnerIndex) {
+    return cached.partnerIndex.get(partnerPubKey) || null;
+  }
+  // Fallback to linear scan if index not available
+  return registryObj.federatedWith.find(p => p.pubKey === partnerPubKey) || null;
+}
+
 /**
  * Save the federation registry
  * @param {Object} client - NostrClient instance
@@ -367,7 +388,7 @@ export async function getCapabilityForAuthor(client, appname, authorPubKey, scop
  */
 export async function storeInboundCapability(client, appname, partnerPubKey, capabilityInfo) {
   const registry = await getFederationRegistry(client, appname);
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  const partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner) {
     // Auto-add partner if not exists
@@ -418,7 +439,7 @@ export async function storeInboundCapability(client, appname, partnerPubKey, cap
  */
 export async function storeOutboundCapability(client, appname, partnerPubKey, capabilityInfo) {
   const registry = await getFederationRegistry(client, appname);
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  const partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner) {
     throw new Error(`Partner ${partnerPubKey} not found in federation registry`);
@@ -449,7 +470,7 @@ export async function storeOutboundCapability(client, appname, partnerPubKey, ca
  */
 export async function revokeOutboundCapability(client, appname, partnerPubKey, tokenHash) {
   const registry = await getFederationRegistry(client, appname);
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  const partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner || !partner.outboundCapabilities) {
     return false;
@@ -702,7 +723,7 @@ export async function grantWriteAccessToHolon(client, appname, holonId, lensName
   const registry = await getFederationRegistry(client, appname);
 
   // Find or create partner entry
-  let partner = registry.federatedWith.find(p => p.pubKey === holonId);
+  let partner = findPartner(client, appname, registry, holonId);
 
   if (!partner) {
     // Auto-add partner if not exists
@@ -755,7 +776,7 @@ 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);
+  const partner = findPartner(client, appname, registry, holonId);
 
   if (!partner || !partner.writeGrants) {
     return false; // No grants to revoke
@@ -783,7 +804,7 @@ 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);
+  const partner = findPartner(client, appname, registry, holonId);
 
   if (!partner || !partner.writeGrants) {
     return [];
@@ -878,7 +899,7 @@ export async function grantAccess(client, appname, partnerPubKey, scope, permiss
   const { expiresAt = null, capabilityToken = null, direction = 'inbound' } = options;
 
   // Find or create partner entry
-  let partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  let partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner) {
     partner = {
@@ -949,7 +970,7 @@ export async function revokeAccess(client, appname, partnerPubKey, scope, permis
   const registry = await getFederationRegistry(client, appname);
   const { direction = 'inbound' } = options;
 
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  const partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner || !partner.accessGrants) {
     return false;
@@ -1005,7 +1026,7 @@ export async function findAccessGrant(client, appname, partnerPubKey, scope, per
   const { direction = 'inbound' } = options;
   const now = Date.now();
 
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  const partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner) {
     return null;
@@ -1096,7 +1117,7 @@ export async function getAccessGrants(client, appname, partnerPubKey, options =
   const { direction = 'all', includeLegacy = true } = options;
   const now = Date.now();
 
-  const partner = registry.federatedWith.find(p => p.pubKey === partnerPubKey);
+  const partner = findPartner(client, appname, registry, partnerPubKey);
 
   if (!partner) {
     return [];
@@ -1332,3 +1353,68 @@ export function convertToLegacyLensConfig(unifiedConfig) {
 
   return legacy;
 }
+
+// ============================================================================
+// Capability Issuance Helpers (moved from capabilities.js)
+// ============================================================================
+
+/**
+ * Issue capability for a specific lens
+ * @param {Object} client - NostrClient instance
+ * @param {string} holonId - Holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} targetPubKey - Target public key
+ * @param {Object} options - Options
+ * @returns {Promise<Object>} Capability info { token, scope, permissions }
+ */
+export async function issueCapabilityForLens(client, holonId, lensName, targetPubKey, options = {}) {
+  const {
+    permissions = ['read'],
+    expiresIn = 365 * 24 * 60 * 60 * 1000, // 1 year default
+  } = options;
+
+  const scope = { holonId, lensName, dataId: '*' };
+
+  const token = await cryptoIssueCapability(
+    permissions,
+    scope,
+    targetPubKey,
+    {
+      expiresIn,
+      issuer: client.publicKey,
+      issuerKey: client.privateKey,
+      isSelfCapability: client.publicKey === targetPubKey,
+    }
+  );
+
+  return {
+    token,
+    scope,
+    permissions,
+    expiresAt: Date.now() + expiresIn,
+  };
+}
+
+/**
+ * Issue capabilities for multiple lenses
+ * @param {Object} client - NostrClient instance
+ * @param {string} holonId - Holon ID
+ * @param {string[]} lensNames - Array of lens names
+ * @param {string} targetPubKey - Target public key
+ * @param {Object} options - Options
+ * @returns {Promise<Object[]>} Array of capability info objects
+ */
+export async function issueCapabilitiesForLenses(client, holonId, lensNames, targetPubKey, options = {}) {
+  const capabilities = [];
+
+  for (const lensName of lensNames) {
+    try {
+      const capInfo = await issueCapabilityForLens(client, holonId, lensName, targetPubKey, options);
+      capabilities.push(capInfo);
+    } catch (err) {
+      console.warn(`[Registry] Failed to issue capability for ${lensName}:`, err.message);
+    }
+  }
+
+  return capabilities;
+}

package/src/federation/request-card.js

@@ -8,7 +8,7 @@
  * @module federation/request-card
  */
 
-import { issueCapabilitiesForLenses } from './capabilities.js';
+import { issueCapabilitiesForLenses } from './registry.js';
 
 /**
  * @typedef {Object} LensConfig

package/src/lib/federation-methods.js

@@ -17,9 +17,25 @@ import * as federation from '../federation/hologram.js';
 import * as storage from '../storage/unified-storage.js';
 import * as nostrAsync from '../storage/nostr-async.js';
 import * as crypto from '../crypto/secp256k1.js';
+import { hashToken, isPubkey } from '../crypto/secp256k1.js';
 import { ValidationError, AuthorizationError } from './errors.js';
-import { sha256 } from '@noble/hashes/sha256';
-import { bytesToHex } from '@noble/hashes/utils';
+
+/**
+ * Normalize a holon target (string or object) to { holonId, authorPubKey }.
+ * If the holonId is a 64-char hex pubkey, uses it as the authorPubKey.
+ * @param {string|Object} input - Holon ID string or { holonId, authorPubKey }
+ * @param {string} defaultPubKey - Default author public key (typically client.publicKey)
+ * @returns {{ holonId: string, authorPubKey: string }}
+ */
+function normalizeHolonTarget(input, defaultPubKey) {
+  if (typeof input === 'string') {
+    return { holonId: input, authorPubKey: isPubkey(input) ? input : defaultPubKey };
+  }
+  return {
+    holonId: input.holonId,
+    authorPubKey: input.authorPubKey || (isPubkey(input.holonId) ? input.holonId : defaultPubKey),
+  };
+}
 
 /**
  * Mixin that adds federation methods to a HoloSphere class.
@@ -80,17 +96,8 @@ export function withFederationMethods(Base) {
       } = options;
 
       // Normalize source and target to { holonId, authorPubKey } format
-      // Helper function to detect if a string is a pubkey (64-char hex)
-      const isPubkey = (str) => typeof str === 'string' && /^[0-9a-f]{64}$/i.test(str);
-
-      // When the holon ID is a pubkey, use it as the authorPubKey for cross-holosphere federation
-      const normalizedSource = typeof source === 'string'
-        ? { holonId: source, authorPubKey: isPubkey(source) ? source : this.client.publicKey }
-        : { holonId: source.holonId, authorPubKey: source.authorPubKey || (isPubkey(source.holonId) ? source.holonId : this.client.publicKey) };
-
-      const normalizedTarget = typeof target === 'string'
-        ? { holonId: target, authorPubKey: isPubkey(target) ? target : this.client.publicKey }
-        : { holonId: target.holonId, authorPubKey: target.authorPubKey || (isPubkey(target.holonId) ? target.holonId : this.client.publicKey) };
+      const normalizedSource = normalizeHolonTarget(source, this.client.publicKey);
+      const normalizedTarget = normalizeHolonTarget(target, this.client.publicKey);
 
       // Validation
       if (normalizedSource.holonId === normalizedTarget.holonId &&
@@ -105,14 +112,20 @@ export function withFederationMethods(Base) {
       // Determine if this is self-federation or cross-federation
       const isSelfFederation = normalizedSource.authorPubKey === normalizedTarget.authorPubKey;
 
-      // Issue or use provided capability
-      let capability = providedCapability;
-      if (!capability) {
-        const expiresIn = isSelfFederation
-          ? 365 * 24 * 60 * 60 * 1000  // 1 year for self
-          : 24 * 60 * 60 * 1000;       // 24 hours for cross
+      // Issue capabilities per direction.
+      // Outbound: capability scoped to source holon (data lives in source, hologram points to source)
+      // Inbound: capability scoped to target holon (data lives in target, hologram points to target)
+      const expiresIn = isSelfFederation
+        ? 365 * 24 * 60 * 60 * 1000  // 1 year for self
+        : 24 * 60 * 60 * 1000;       // 24 hours for cross
+
+      const needsOutbound = direction === 'outbound' || direction === 'bidirectional';
+      const needsInbound = direction === 'inbound' || direction === 'bidirectional';
 
-        capability = await crypto.issueCapability(
+      // Outbound capability: scoped to source holon
+      let outboundCapability = providedCapability;
+      if (!outboundCapability && needsOutbound) {
+        outboundCapability = await crypto.issueCapability(
           permissions,
           { holonId: normalizedSource.holonId, lensName, dataId: '*' },
           normalizedTarget.authorPubKey,
@@ -124,10 +137,9 @@ export function withFederationMethods(Base) {
           }
         );
 
-        // Store capability in registry
         if (isSelfFederation) {
           await registry.storeSelfCapability(this.client, this.config.appName, {
-            token: capability,
+            token: outboundCapability,
             scope: { holonId: normalizedSource.holonId, lensName },
             permissions,
           });
@@ -137,7 +149,7 @@ export function withFederationMethods(Base) {
             this.config.appName,
             normalizedSource.authorPubKey,
             {
-              token: capability,
+              token: outboundCapability,
               scope: { holonId: normalizedSource.holonId, lensName },
               permissions,
             }
@@ -145,6 +157,41 @@ export function withFederationMethods(Base) {
         }
       }
 
+      // Inbound capability: scoped to target holon
+      let inboundCapability = providedCapability;
+      if (!inboundCapability && needsInbound) {
+        inboundCapability = await crypto.issueCapability(
+          permissions,
+          { holonId: normalizedTarget.holonId, lensName, dataId: '*' },
+          normalizedSource.authorPubKey,
+          {
+            expiresIn,
+            issuer: normalizedTarget.authorPubKey,
+            issuerKey: this.client.privateKey,
+            isSelfCapability: isSelfFederation,
+          }
+        );
+
+        if (isSelfFederation) {
+          await registry.storeSelfCapability(this.client, this.config.appName, {
+            token: inboundCapability,
+            scope: { holonId: normalizedTarget.holonId, lensName },
+            permissions,
+          });
+        } else {
+          await registry.storeInboundCapability(
+            this.client,
+            this.config.appName,
+            normalizedTarget.authorPubKey,
+            {
+              token: inboundCapability,
+              scope: { holonId: normalizedTarget.holonId, lensName },
+              permissions,
+            }
+          );
+        }
+      }
+
       // Setup federation based on direction
       const results = {
         source: normalizedSource,
@@ -153,13 +200,13 @@ export function withFederationMethods(Base) {
         direction,
         mode,
         propagate,
-        capability,
+        capability: outboundCapability || inboundCapability,
         isSelfFederation,
         propagated: { outbound: 0, inbound: 0 },
       };
 
       // Handle data propagation (skip if propagate: false)
-      if (propagate && (direction === 'outbound' || direction === 'bidirectional')) {
+      if (propagate && needsOutbound) {
         // Propagate existing data from source to target
         const sourceData = await this.read(normalizedSource.holonId, lensName, null, {
           resolveHolograms: false,
@@ -179,7 +226,7 @@ export function withFederationMethods(Base) {
               mode,
               {
                 sourceAuthorPubKey: normalizedSource.authorPubKey,
-                capability,
+                capability: outboundCapability,
               }
             );
             results.propagated.outbound++;
@@ -187,8 +234,8 @@ export function withFederationMethods(Base) {
         }
       }
 
-      if (propagate && (direction === 'inbound' || direction === 'bidirectional')) {
-        // Propagate from target to source (need capability from target author)
+      if (propagate && needsInbound) {
+        // Propagate from target to source
         const targetData = await this.read(normalizedTarget.holonId, lensName, null, {
           resolveHolograms: false,
         });
@@ -207,7 +254,7 @@ export function withFederationMethods(Base) {
               mode,
               {
                 sourceAuthorPubKey: normalizedTarget.authorPubKey,
-                capability,
+                capability: inboundCapability,
               }
             );
             results.propagated.inbound++;
@@ -239,13 +286,8 @@ export function withFederationMethods(Base) {
      * @returns {Promise<boolean>} True if unfederation succeeded
      */
     async unfederate(source, target, lensName) {
-      const normalizedSource = typeof source === 'string'
-        ? { holonId: source, authorPubKey: this.client.publicKey }
-        : { holonId: source.holonId, authorPubKey: source.authorPubKey || this.client.publicKey };
-
-      const normalizedTarget = typeof target === 'string'
-        ? { holonId: target, authorPubKey: this.client.publicKey }
-        : { holonId: target.holonId, authorPubKey: target.authorPubKey || this.client.publicKey };
+      const normalizedSource = normalizeHolonTarget(source, this.client.publicKey);
+      const normalizedTarget = normalizeHolonTarget(target, this.client.publicKey);
 
       // Remove federation config
       const configPath = storage.buildPath(this.config.appName, normalizedSource.holonId, lensName, '_federation');
@@ -481,11 +523,10 @@ export function withFederationMethods(Base) {
      * Hash a capability token for storage.
      * @private
      * @param {string} token - Capability token to hash
-     * @returns {Promise<string>} SHA256 hash of token
+     * @returns {string} SHA256 hash of token
      */
-    async _hashToken(token) {
-      const encoder = new TextEncoder();
-      return bytesToHex(sha256(encoder.encode(token)));
+    _hashToken(token) {
+      return hashToken(token);
     }
 
     // === Nostr Discovery Protocol ===