holosphere 2.0.0-alpha11 → 2.0.0-alpha13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holosphere",
-  "version": "2.0.0-alpha11",
+  "version": "2.0.0-alpha13",
   "description": "Holonic geospatial communication infrastructure combining H3 hexagonal indexing with distributed P2P storage",
   "type": "module",
   "bin": {
@@ -54,6 +54,7 @@
   },
   "dependencies": {
     "@noble/curves": "^1.3.0",
+    "@nostr-dev-kit/ndk": "^2.10.0",
     "ajv": "^8.12.0",
     "dotenv": "^17.2.3",
     "ethers": "^6.13.4",
@@ -64,6 +65,7 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
+    "@nostr-dev-kit/ndk-cache-dexie": "^2.5.0",
     "gun": "^0.2020.1241"
   },
   "devDependencies": {

package/src/crypto/nostr-utils.js

@@ -2,11 +2,18 @@
  * @fileoverview Browser-compatible Nostr utility functions for key handling, encryption, and event management.
  * Provides NIP-04 (legacy) and NIP-44 (modern, audited) encryption support, key conversion utilities,
  * and event creation helpers. Applications can use these utilities without directly importing nostr-tools.
+ *
+ * This module uses nostr-tools for cryptographic operations while the main client uses NDK.
+ * Both libraries are compatible and can be used together.
+ *
  * @module crypto/nostr-utils
  */
 
 import { nip04, nip44, nip19, getPublicKey as nostrGetPublicKey, finalizeEvent, verifyEvent as nostrVerifyEvent } from 'nostr-tools';
 
+// Re-export NDK types for consumers who want to use NDK directly
+export { default as NDK, NDKEvent, NDKPrivateKeySigner, NDKUser, NDKSubscriptionCacheUsage } from '@nostr-dev-kit/ndk';
+
 // ============================================================================
 // Key Conversion Utilities
 // ============================================================================

package/src/crypto/secp256k1.js

@@ -10,29 +10,15 @@
 
 import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
-
-let secp256k1 = null;
-
-/**
- * Lazy load secp256k1 module
- * @private
- */
-async function loadCrypto() {
-  if (!secp256k1) {
-    const module = await import('@noble/curves/secp256k1');
-    secp256k1 = module.secp256k1;
-  }
-  return secp256k1;
-}
+import { secp256k1 } from '@noble/curves/secp256k1';
 
 /**
  * Get public key from private key
  * @param {string} privateKey - Private key (hex string)
- * @returns {Promise<string>} Public key (hex string)
+ * @returns {string} Public key (hex string)
  */
-export async function getPublicKey(privateKey) {
-  const crypto = await loadCrypto();
-  const pubKey = crypto.getPublicKey(privateKey);
+export function getPublicKey(privateKey) {
+  const pubKey = secp256k1.getPublicKey(privateKey);
   return bytesToHex(pubKey);
 }
 
@@ -44,13 +30,11 @@ export async function getPublicKey(privateKey) {
  */
 export async function sign(content, privateKey) {
   try {
-    const crypto = await loadCrypto();
-
     // Hash content
     const msgHash = hashContent(content);
 
     // Sign - secp256k1.sign returns Signature object
-    const signature = crypto.sign(msgHash, privateKey);
+    const signature = secp256k1.sign(msgHash, privateKey);
     return signature.toCompactHex();
   } catch (error) {
     throw new Error(`Signature generation failed: ${error.message}`);
@@ -71,10 +55,8 @@ export async function verify(content, signature, publicKey) {
       throw new Error('Invalid public key format');
     }
 
-    const crypto = await loadCrypto();
-
     const msgHash = hashContent(content);
-    const isValid = crypto.verify(signature, msgHash, publicKey);
+    const isValid = secp256k1.verify(signature, msgHash, publicKey);
     return isValid;
   } catch (error) {
     // Invalid signatures or keys throw errors
@@ -127,18 +109,24 @@ export function matchScope(tokenScope, requestedScope) {
 }
 
 /**
- * Issue capability token
+ * Issue capability token - UNIFIED MODEL
+ *
+ * Supports both self-capabilities (issuer === recipient) and cross-capabilities.
+ * Self-capabilities are used for same-author federation, providing consistent
+ * security model across all federation types.
+ *
  * @param {string[]} permissions - Permissions array (e.g., ['read', 'write', 'delete'])
  * @param {Object|string} scope - Scope (holon/lens path or object). Supports wildcards: { holonId: "*", lensName: "*" }
- * @param {string} recipient - Recipient public key
+ * @param {string} recipient - Recipient public key (can be same as issuer for self-capability)
  * @param {Object} options - Options
- * @param {number} options.expiresIn - Expiration in milliseconds (default: 1 hour)
- * @param {string} options.issuer - Issuer ID
+ * @param {number} options.expiresIn - Expiration in milliseconds (default: 1 hour, longer for self-caps)
+ * @param {string} options.issuer - Issuer ID/public key
  * @param {string} options.issuerKey - Issuer private key for signing
+ * @param {boolean} options.isSelfCapability - If true, marks as self-capability (auto-detected if issuer === recipient)
  * @returns {Promise<string>} Capability token (base64-encoded JWT-like)
  */
 export async function issueCapability(permissions, scope, recipient, options = {}) {
-  const { expiresIn = 3600000, issuer = 'holosphere', issuerKey } = options;
+  const { expiresIn = 3600000, issuer = 'holosphere', issuerKey, isSelfCapability } = options;
 
   // Validate permissions
   if (!Array.isArray(permissions) || permissions.length === 0) {
@@ -165,12 +153,16 @@ export async function issueCapability(permissions, scope, recipient, options = {
     throw new Error('Invalid issuer key');
   }
 
+  // Detect self-capability (issuer === recipient)
+  const selfCap = isSelfCapability !== undefined ? isSelfCapability : (issuer === recipient);
+
   const token = {
     type: 'capability',
     permissions,
     scope,
     recipient,
     issuer,
+    isSelfCapability: selfCap,  // Mark self-capabilities for clarity
     nonce: generateNonce(),
     issued: Date.now(),
     expires: Date.now() + expiresIn,
@@ -191,6 +183,31 @@ export async function issueCapability(permissions, scope, recipient, options = {
   return encoded;
 }
 
+/**
+ * Issue a self-capability token - UNIFIED MODEL
+ *
+ * Convenience method for creating self-capabilities (same author federation).
+ * Self-capabilities have longer expiration by default (1 year).
+ *
+ * @param {string[]} permissions - Permissions array
+ * @param {Object} scope - Scope object { holonId, lensName, dataId? }
+ * @param {string} authorPubKey - Author's public key (both issuer and recipient)
+ * @param {Object} options - Options
+ * @param {string} options.privateKey - Author's private key for signing
+ * @param {number} [options.expiresIn=31536000000] - Expiration in ms (default: 1 year)
+ * @returns {Promise<string>} Self-capability token
+ */
+export async function issueSelfCapability(permissions, scope, authorPubKey, options = {}) {
+  const { privateKey, expiresIn = 365 * 24 * 60 * 60 * 1000 } = options; // 1 year default
+
+  return issueCapability(permissions, scope, authorPubKey, {
+    expiresIn,
+    issuer: authorPubKey,
+    issuerKey: privateKey,
+    isSelfCapability: true,
+  });
+}
+
 /**
  * Verify capability token
  * @param {string|Object} token - Capability token (string or object)
@@ -202,41 +219,90 @@ 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
+    }
+
     // Decode if string
     if (typeof token === 'string') {
-      const parts = token.split('.');
-      const payload = parts[0];
-      const decoded = Buffer.from ?
-        Buffer.from(payload, 'base64').toString('utf8') :
-        atob(payload);
-      tokenObj = JSON.parse(decoded);
-
-      // TODO: Verify signature if present (parts[1])
-    } else {
+      // 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;
+          const decoded = Buffer.from ?
+            Buffer.from(payload, 'base64').toString('utf8') :
+            atob(payload);
+          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));
+        return false;
+      }
+    } else if (token && typeof token === 'object') {
+      // Already decoded token object
       tokenObj = token;
+    } else {
+      console.log('[verifyCapability] ❌ Invalid token:', typeof token);
+      return false;
     }
 
     if (!tokenObj || tokenObj.type !== 'capability') {
+      console.log('[verifyCapability] ❌ Invalid token type:', { type: tokenObj?.type, tokenObj });
       return false;
     }
 
     // Check expiration
     if (Date.now() > tokenObj.expires) {
+      console.log('[verifyCapability] ❌ Token expired:', {
+        expires: tokenObj.expires,
+        now: Date.now(),
+        expiredAgo: `${(Date.now() - tokenObj.expires) / 1000}s ago`
+      });
       return false;
     }
 
     // Check scope using matchScope (supports wildcards)
     if (!matchScope(tokenObj.scope, scope)) {
+      console.log('[verifyCapability] ❌ Scope mismatch:', {
+        tokenScope: tokenObj.scope,
+        requestedScope: scope
+      });
       return false;
     }
 
     // Check permission
     if (!tokenObj.permissions.includes(requiredPermission)) {
+      console.log('[verifyCapability] ❌ Permission denied:', {
+        required: requiredPermission,
+        has: tokenObj.permissions
+      });
       return false;
     }
 
+    console.log('[verifyCapability] ✅ Capability valid');
     return true;
   } catch (error) {
+    console.log('[verifyCapability] ❌ Error:', error.message);
     return false;
   }
 }

package/src/federation/capabilities.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Federation Capabilities Module
+ *
+ * Handles capability token issuance, verification, and management
+ * for federation operations. Extracted from federation-methods.js
+ * for better modularity.
+ *
+ * @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 = [];
+
+  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);
+    }
+  }
+
+  return capabilities;
+}
+
+/**
+ * Store a capability in the registry
+ * @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
+ * @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);
+  } else {
+    return registry.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,
+};