holosphere 2.0.0-alpha11 → 2.0.0-alpha12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holosphere",
-  "version": "2.0.0-alpha11",
+  "version": "2.0.0-alpha12",
   "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)

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,
+};

package/src/federation/card-storage.js

@@ -0,0 +1,304 @@
+/**
+ * @fileoverview Federation Card Storage
+ *
+ * Persists federation card state to prevent cards from reappearing
+ * after deletion. Manages card lifecycle (pending, sent, accepted,
+ * rejected, dismissed).
+ *
+ * @module federation/card-storage
+ */
+
+import { writeGlobal, readGlobal, getAllGlobal } from '../storage/global-tables.js';
+import { serializeCard, deserializeCard, shouldDisplayCard } from './request-card.js';
+
+const FEDERATION_CARDS_TABLE = '_federation-cards';
+const DISMISSED_REQUESTS_TABLE = '_dismissed-federation-requests';
+const PROCESSED_RESPONSES_TABLE = '_processed-federation-responses';
+
+/**
+ * Save a federation card
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {Object} card - Federation card configuration
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function saveCard(client, appname, card) {
+  const serialized = serializeCard(card);
+  serialized.id = card.id;
+  return writeGlobal(client, appname, FEDERATION_CARDS_TABLE, serialized);
+}
+
+/**
+ * Get a specific federation card
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} cardId - Card ID
+ * @returns {Promise<Object|null>} Card or null
+ */
+export async function getCard(client, appname, cardId) {
+  const data = await readGlobal(client, appname, FEDERATION_CARDS_TABLE, cardId);
+  return data ? deserializeCard(data) : null;
+}
+
+/**
+ * Get all federation cards
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Object[]>} Array of cards
+ */
+export async function getAllCards(client, appname) {
+  const data = await getAllGlobal(client, appname, FEDERATION_CARDS_TABLE);
+  return (data || [])
+    .filter(d => d && !d._deleted)
+    .map(d => deserializeCard(d));
+}
+
+/**
+ * Get cards that should be displayed
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Object[]>} Array of displayable cards
+ */
+export async function getDisplayableCards(client, appname) {
+  const cards = await getAllCards(client, appname);
+  return cards.filter(shouldDisplayCard);
+}
+
+/**
+ * Get card by partner public key
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @returns {Promise<Object|null>} Card or null
+ */
+export async function getCardByPartner(client, appname, partnerPubKey) {
+  const cards = await getAllCards(client, appname);
+  return cards.find(c => c.partnerPubKey === partnerPubKey) || null;
+}
+
+/**
+ * Delete a federation card
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} cardId - Card ID
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function deleteCard(client, appname, cardId) {
+  const card = await getCard(client, appname, cardId);
+  if (!card) return false;
+
+  // Mark as deleted
+  const deleted = {
+    ...card,
+    id: cardId,
+    _deleted: true,
+    deletedAt: Date.now(),
+  };
+
+  return writeGlobal(client, appname, FEDERATION_CARDS_TABLE, deleted);
+}
+
+/**
+ * Dismiss a card (mark as dismissed so it won't reappear)
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} cardId - Card ID
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function dismissCard(client, appname, cardId) {
+  const card = await getCard(client, appname, cardId);
+  if (!card) return false;
+
+  card.status = 'dismissed';
+  card.dismissedAt = Date.now();
+
+  return saveCard(client, appname, card);
+}
+
+/**
+ * Mark a federation request as dismissed (by request ID)
+ * This prevents the request from showing up again as a card
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} requestId - Request ID from federation request
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function dismissRequest(client, appname, requestId) {
+  const entry = {
+    id: requestId,
+    dismissedAt: Date.now(),
+  };
+  return writeGlobal(client, appname, DISMISSED_REQUESTS_TABLE, entry);
+}
+
+/**
+ * Check if a request has been dismissed
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} requestId - Request ID
+ * @returns {Promise<boolean>} True if dismissed
+ */
+export async function isRequestDismissed(client, appname, requestId) {
+  const entry = await readGlobal(client, appname, DISMISSED_REQUESTS_TABLE, requestId);
+  return !!entry;
+}
+
+/**
+ * Get all dismissed request IDs
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Set<string>>} Set of dismissed request IDs
+ */
+export async function getDismissedRequestIds(client, appname) {
+  const entries = await getAllGlobal(client, appname, DISMISSED_REQUESTS_TABLE);
+  return new Set((entries || []).map(e => e.id));
+}
+
+/**
+ * Mark a federation response as processed
+ * This prevents duplicate "federation accepted" messages
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} requestId - Original request ID
+ * @param {string} responderPubKey - Responder's public key
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function markResponseProcessed(client, appname, requestId, responderPubKey) {
+  const entry = {
+    id: `${requestId}_${responderPubKey}`,
+    requestId,
+    responderPubKey,
+    processedAt: Date.now(),
+  };
+  return writeGlobal(client, appname, PROCESSED_RESPONSES_TABLE, entry);
+}
+
+/**
+ * Check if a response has already been processed
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} requestId - Original request ID
+ * @param {string} responderPubKey - Responder's public key
+ * @returns {Promise<boolean>} True if already processed
+ */
+export async function isResponseProcessed(client, appname, requestId, responderPubKey) {
+  const id = `${requestId}_${responderPubKey}`;
+  const entry = await readGlobal(client, appname, PROCESSED_RESPONSES_TABLE, id);
+  return !!entry;
+}
+
+/**
+ * Get all processed response IDs
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @returns {Promise<Set<string>>} Set of processed response IDs
+ */
+export async function getProcessedResponseIds(client, appname) {
+  const entries = await getAllGlobal(client, appname, PROCESSED_RESPONSES_TABLE);
+  return new Set((entries || []).map(e => e.id));
+}
+
+/**
+ * Update card status
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} cardId - Card ID
+ * @param {string} status - New status
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateCardStatus(client, appname, cardId, status) {
+  const card = await getCard(client, appname, cardId);
+  if (!card) return false;
+
+  card.status = status;
+  card.statusUpdatedAt = Date.now();
+
+  return saveCard(client, appname, card);
+}
+
+/**
+ * Find pending cards for a partner
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {string} partnerPubKey - Partner's public key
+ * @returns {Promise<Object[]>} Array of pending cards
+ */
+export async function findPendingCardsForPartner(client, appname, partnerPubKey) {
+  const cards = await getAllCards(client, appname);
+  return cards.filter(c =>
+    c.partnerPubKey === partnerPubKey &&
+    c.status === 'pending'
+  );
+}
+
+/**
+ * Clean up old dismissed entries (older than maxAge)
+ * @param {Object} client - NostrClient instance
+ * @param {string} appname - Application namespace
+ * @param {number} maxAge - Maximum age in milliseconds (default: 30 days)
+ * @returns {Promise<Object>} Cleanup result
+ */
+export async function cleanupOldEntries(client, appname, maxAge = 30 * 24 * 60 * 60 * 1000) {
+  const result = {
+    dismissedCleaned: 0,
+    responsesCleaned: 0,
+    cardsCleaned: 0,
+  };
+
+  const now = Date.now();
+  const cutoff = now - maxAge;
+
+  // Cleanup old dismissed requests
+  const dismissed = await getAllGlobal(client, appname, DISMISSED_REQUESTS_TABLE);
+  for (const entry of (dismissed || [])) {
+    if (entry.dismissedAt && entry.dismissedAt < cutoff) {
+      await writeGlobal(client, appname, DISMISSED_REQUESTS_TABLE, {
+        id: entry.id,
+        _deleted: true,
+      });
+      result.dismissedCleaned++;
+    }
+  }
+
+  // Cleanup old processed responses
+  const responses = await getAllGlobal(client, appname, PROCESSED_RESPONSES_TABLE);
+  for (const entry of (responses || [])) {
+    if (entry.processedAt && entry.processedAt < cutoff) {
+      await writeGlobal(client, appname, PROCESSED_RESPONSES_TABLE, {
+        id: entry.id,
+        _deleted: true,
+      });
+      result.responsesCleaned++;
+    }
+  }
+
+  // Cleanup old dismissed cards
+  const cards = await getAllCards(client, appname);
+  for (const card of cards) {
+    if (card.status === 'dismissed' && card.dismissedAt && card.dismissedAt < cutoff) {
+      await deleteCard(client, appname, card.id);
+      result.cardsCleaned++;
+    }
+  }
+
+  return result;
+}
+
+export default {
+  saveCard,
+  getCard,
+  getAllCards,
+  getDisplayableCards,
+  getCardByPartner,
+  deleteCard,
+  dismissCard,
+  dismissRequest,
+  isRequestDismissed,
+  getDismissedRequestIds,
+  markResponseProcessed,
+  isResponseProcessed,
+  getProcessedResponseIds,
+  updateCardStatus,
+  findPendingCardsForPartner,
+  cleanupOldEntries,
+};