holosphere 2.0.0-alpha13 → 2.0.0-alpha15

package/src/crypto/key-store.js

@@ -0,0 +1,356 @@
+/**
+ * @fileoverview Lens Key Store for Encrypted Federation
+ *
+ * Manages symmetric keys for encrypted lenses. Each HoloSphere instance
+ * has its own key store that tracks:
+ * - Keys we own (generated for our own lenses)
+ * - Keys we received (shared by federation partners)
+ *
+ * Keys are stored in memory and can be persisted to Nostr for recovery.
+ *
+ * @module crypto/key-store
+ */
+
+import {
+  generateLensKey,
+  wrapKeyForRecipient,
+  unwrapKey,
+  serializeLensKey,
+  deserializeLensKey
+} from './lens-keys.js';
+
+/**
+ * In-memory key store for lens symmetric keys.
+ * Each HoloSphere instance should have its own LensKeyStore.
+ *
+ * @class LensKeyStore
+ */
+export class LensKeyStore {
+  /**
+   * Creates a new LensKeyStore instance.
+   */
+  constructor() {
+    /**
+     * Keys we own (generated for our lenses).
+     * Map: lensPath -> { key: Uint8Array, wrappedForSelf: string, createdAt: number }
+     * @type {Map<string, Object>}
+     */
+    this.ownKeys = new Map();
+
+    /**
+     * Keys we received from federation partners.
+     * Map: lensPath -> { key: Uint8Array, fromPubKey: string, receivedAt: number }
+     * @type {Map<string, Object>}
+     */
+    this.receivedKeys = new Map();
+
+    /**
+     * Wrapped keys for partners (for sharing during federation).
+     * Map: lensPath -> Map<partnerPubKey, wrappedKey>
+     * @type {Map<string, Map<string, string>>}
+     */
+    this.partnerWrappedKeys = new Map();
+  }
+
+  /**
+   * Store a lens key we own (we generated it).
+   *
+   * @param {string} lensPath - Path identifying the lens (appName/holonId/lensName)
+   * @param {Uint8Array} key - 32-byte symmetric key
+   * @param {string} wrappedForSelf - NIP-44 wrapped key for self-recovery
+   */
+  storeOwnKey(lensPath, key, wrappedForSelf) {
+    this.ownKeys.set(lensPath, {
+      key,
+      wrappedForSelf,
+      createdAt: Date.now()
+    });
+  }
+
+  /**
+   * Store a lens key we received from a federation partner.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @param {Uint8Array} key - 32-byte symmetric key
+   * @param {string} fromPubKey - Public key of the partner who shared the key
+   */
+  storeReceivedKey(lensPath, key, fromPubKey) {
+    this.receivedKeys.set(lensPath, {
+      key,
+      fromPubKey,
+      receivedAt: Date.now()
+    });
+  }
+
+  /**
+   * Get the key for a lens (own or received).
+   * Own keys take precedence over received keys.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @returns {Uint8Array|null} 32-byte symmetric key or null if not found
+   */
+  getKey(lensPath) {
+    const own = this.ownKeys.get(lensPath);
+    if (own) return own.key;
+
+    const received = this.receivedKeys.get(lensPath);
+    if (received) return received.key;
+
+    return null;
+  }
+
+  /**
+   * Check if we have a key for a lens.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @returns {boolean} True if key exists
+   */
+  hasKey(lensPath) {
+    return this.ownKeys.has(lensPath) || this.receivedKeys.has(lensPath);
+  }
+
+  /**
+   * Check if we own the key for a lens (vs received it).
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @returns {boolean} True if we own the key
+   */
+  isOwnKey(lensPath) {
+    return this.ownKeys.has(lensPath);
+  }
+
+  /**
+   * Get or create a key for a lens.
+   * If key doesn't exist, generates a new one.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @param {string} ownerPrivKey - Owner's private key for wrapping
+   * @param {string} ownerPubKey - Owner's public key
+   * @returns {Object} { key: Uint8Array, isNew: boolean, wrappedForSelf: string }
+   */
+  getOrCreateKey(lensPath, ownerPrivKey, ownerPubKey) {
+    // Check if key already exists
+    const existing = this.ownKeys.get(lensPath);
+    if (existing) {
+      return {
+        key: existing.key,
+        isNew: false,
+        wrappedForSelf: existing.wrappedForSelf
+      };
+    }
+
+    // Also check received keys (shouldn't generate if we received one)
+    if (this.receivedKeys.has(lensPath)) {
+      const received = this.receivedKeys.get(lensPath);
+      return {
+        key: received.key,
+        isNew: false,
+        wrappedForSelf: null // We don't have wrapped version for received keys
+      };
+    }
+
+    // Generate new key
+    const key = generateLensKey();
+    const wrappedForSelf = wrapKeyForRecipient(key, ownerPrivKey, ownerPubKey);
+
+    // Store it
+    this.storeOwnKey(lensPath, key, wrappedForSelf);
+
+    return { key, isNew: true, wrappedForSelf };
+  }
+
+  /**
+   * Wrap a lens key for a partner (for federation sharing).
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @param {string} ownerPrivKey - Owner's private key
+   * @param {string} partnerPubKey - Partner's public key
+   * @returns {string|null} Wrapped key for partner or null if no key exists
+   */
+  wrapKeyForPartner(lensPath, ownerPrivKey, partnerPubKey) {
+    const key = this.getKey(lensPath);
+    if (!key) return null;
+
+    const wrappedKey = wrapKeyForRecipient(key, ownerPrivKey, partnerPubKey);
+
+    // Cache the wrapped key for this partner
+    if (!this.partnerWrappedKeys.has(lensPath)) {
+      this.partnerWrappedKeys.set(lensPath, new Map());
+    }
+    this.partnerWrappedKeys.get(lensPath).set(partnerPubKey, wrappedKey);
+
+    return wrappedKey;
+  }
+
+  /**
+   * Get all partners who have been given wrapped keys for a lens.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @returns {string[]} Array of partner public keys
+   */
+  getPartnersWithAccess(lensPath) {
+    const partners = this.partnerWrappedKeys.get(lensPath);
+    return partners ? Array.from(partners.keys()) : [];
+  }
+
+  /**
+   * Revoke a partner's access by removing their wrapped key.
+   * Note: This doesn't prevent them from using their cached key.
+   * For true revocation, you need to re-key the lens.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @param {string} partnerPubKey - Partner's public key
+   * @returns {boolean} True if partner was found and removed
+   */
+  revokePartnerAccess(lensPath, partnerPubKey) {
+    const partners = this.partnerWrappedKeys.get(lensPath);
+    if (partners) {
+      return partners.delete(partnerPubKey);
+    }
+    return false;
+  }
+
+  /**
+   * Re-key a lens (generate new key and re-wrap for remaining partners).
+   * Used for key rotation or access revocation.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @param {string} ownerPrivKey - Owner's private key
+   * @param {string} ownerPubKey - Owner's public key
+   * @param {string[]} [excludePartners=[]] - Partners to exclude from re-wrapping
+   * @returns {Object} { newKey, wrappedForSelf, partnerKeys: Map<pubKey, wrappedKey> }
+   */
+  rekeyLens(lensPath, ownerPrivKey, ownerPubKey, excludePartners = []) {
+    // Get current partners
+    const currentPartners = this.getPartnersWithAccess(lensPath);
+    const remainingPartners = currentPartners.filter(p => !excludePartners.includes(p));
+
+    // Generate new key
+    const newKey = generateLensKey();
+    const wrappedForSelf = wrapKeyForRecipient(newKey, ownerPrivKey, ownerPubKey);
+
+    // Store new key
+    this.storeOwnKey(lensPath, newKey, wrappedForSelf);
+
+    // Re-wrap for remaining partners
+    const partnerKeys = new Map();
+    this.partnerWrappedKeys.set(lensPath, new Map());
+
+    for (const partnerPubKey of remainingPartners) {
+      const wrappedKey = wrapKeyForRecipient(newKey, ownerPrivKey, partnerPubKey);
+      this.partnerWrappedKeys.get(lensPath).set(partnerPubKey, wrappedKey);
+      partnerKeys.set(partnerPubKey, wrappedKey);
+    }
+
+    return { newKey, wrappedForSelf, partnerKeys };
+  }
+
+  /**
+   * Receive and unwrap a key from a partner.
+   *
+   * @param {string} lensPath - Path identifying the lens
+   * @param {string} wrappedKey - NIP-44 wrapped key from partner
+   * @param {string} recipientPrivKey - Our private key
+   * @param {string} senderPubKey - Partner's public key
+   * @returns {Uint8Array} Unwrapped 32-byte symmetric key
+   */
+  receiveKey(lensPath, wrappedKey, recipientPrivKey, senderPubKey) {
+    const key = unwrapKey(wrappedKey, recipientPrivKey, senderPubKey);
+    this.storeReceivedKey(lensPath, key, senderPubKey);
+    return key;
+  }
+
+  /**
+   * Export own keys for persistent storage.
+   * Returns serializable format that can be stored in Nostr.
+   *
+   * @returns {Object[]} Array of { lensPath, wrappedForSelf, createdAt }
+   */
+  exportOwnKeys() {
+    const exported = [];
+    for (const [lensPath, data] of this.ownKeys.entries()) {
+      exported.push({
+        lensPath,
+        wrappedForSelf: data.wrappedForSelf,
+        createdAt: data.createdAt
+      });
+    }
+    return exported;
+  }
+
+  /**
+   * Import own keys from persistent storage.
+   *
+   * @param {Object[]} keyData - Array of exported key data
+   * @param {string} ownerPrivKey - Owner's private key for unwrapping
+   * @param {string} ownerPubKey - Owner's public key
+   */
+  importOwnKeys(keyData, ownerPrivKey, ownerPubKey) {
+    for (const data of keyData) {
+      const key = unwrapKey(data.wrappedForSelf, ownerPrivKey, ownerPubKey);
+      this.ownKeys.set(data.lensPath, {
+        key,
+        wrappedForSelf: data.wrappedForSelf,
+        createdAt: data.createdAt
+      });
+    }
+  }
+
+  /**
+   * Clear all keys from the store.
+   * Use with caution - this will remove all access to encrypted data.
+   */
+  clear() {
+    this.ownKeys.clear();
+    this.receivedKeys.clear();
+    this.partnerWrappedKeys.clear();
+  }
+
+  /**
+   * Get statistics about the key store.
+   *
+   * @returns {Object} { ownKeyCount, receivedKeyCount, totalPartnerGrants }
+   */
+  getStats() {
+    let totalPartnerGrants = 0;
+    for (const partners of this.partnerWrappedKeys.values()) {
+      totalPartnerGrants += partners.size;
+    }
+
+    return {
+      ownKeyCount: this.ownKeys.size,
+      receivedKeyCount: this.receivedKeys.size,
+      totalPartnerGrants
+    };
+  }
+}
+
+/**
+ * Build a lens path from components.
+ *
+ * @param {string} appName - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @param {string} lensName - Lens name
+ * @returns {string} Lens path (appName/holonId/lensName)
+ */
+export function buildLensPath(appName, holonId, lensName) {
+  return `${appName}/${holonId}/${lensName}`;
+}
+
+/**
+ * Parse a lens path into components.
+ *
+ * @param {string} lensPath - Lens path to parse
+ * @returns {Object} { appName, holonId, lensName }
+ */
+export function parseLensPath(lensPath) {
+  const parts = lensPath.split('/');
+  if (parts.length < 3) {
+    throw new Error(`Invalid lens path: ${lensPath}`);
+  }
+  return {
+    appName: parts[0],
+    holonId: parts[1],
+    lensName: parts[2]
+  };
+}

package/src/crypto/lens-keys.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Symmetric Key Management for Encrypted Federation
+ *
+ * Provides symmetric key generation, data encryption/decryption using AES-256-GCM,
+ * and key wrapping/unwrapping using NIP-44 for secure key exchange.
+ *
+ * Key Principles:
+ * - Each lens has its own symmetric key (256-bit AES key)
+ * - Data is encrypted once with the symmetric key (single source of truth)
+ * - Key = Access: Having the symmetric key means you can read the data
+ * - Key exchange happens during federation approval via NIP-44 encrypted DMs
+ *
+ * Browser-compatible: Uses @noble/ciphers for AES-GCM encryption.
+ *
+ * @module crypto/lens-keys
+ */
+
+import { gcm } from '@noble/ciphers/aes';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { encryptNIP44, decryptNIP44 } from './nostr-utils.js';
+
+/**
+ * Generate a 256-bit symmetric key for a lens.
+ * Uses cryptographically secure random bytes.
+ *
+ * @returns {Uint8Array} 32-byte (256-bit) symmetric key
+ */
+export function generateLensKey() {
+  return randomBytes(32);
+}
+
+/**
+ * Convert Uint8Array to base64 string.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function uint8ToBase64(bytes) {
+  // Browser-compatible base64 encoding
+  if (typeof btoa === 'function') {
+    return btoa(String.fromCharCode(...bytes));
+  }
+  // Node.js fallback
+  return Buffer.from(bytes).toString('base64');
+}
+
+/**
+ * Convert base64 string to Uint8Array.
+ * @param {string} base64
+ * @returns {Uint8Array}
+ */
+function base64ToUint8(base64) {
+  // Browser-compatible base64 decoding
+  if (typeof atob === 'function') {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  // Node.js fallback
+  return new Uint8Array(Buffer.from(base64, 'base64'));
+}
+
+/**
+ * Encrypt data with symmetric key using AES-256-GCM.
+ * GCM provides both confidentiality and authenticity.
+ *
+ * Format: base64(iv[12] + ciphertext_with_tag)
+ *
+ * @param {Uint8Array} key - 32-byte symmetric key
+ * @param {string} plaintext - Data to encrypt (will be UTF-8 encoded)
+ * @returns {string} Base64-encoded encrypted data (iv + ciphertext + authTag)
+ */
+export function encryptWithKey(key, plaintext) {
+  // Generate random 12-byte IV (recommended size for GCM)
+  const iv = randomBytes(12);
+
+  // Create cipher and encrypt (GCM tag is appended automatically)
+  const aes = gcm(key, iv);
+  const plaintextBytes = new TextEncoder().encode(plaintext);
+  const ciphertext = aes.encrypt(plaintextBytes);
+
+  // Concatenate: iv (12) + ciphertext (includes 16-byte auth tag at end)
+  const combined = new Uint8Array(iv.length + ciphertext.length);
+  combined.set(iv, 0);
+  combined.set(ciphertext, iv.length);
+
+  return uint8ToBase64(combined);
+}
+
+/**
+ * Decrypt data with symmetric key using AES-256-GCM.
+ *
+ * @param {Uint8Array} key - 32-byte symmetric key
+ * @param {string} ciphertext - Base64-encoded encrypted data
+ * @returns {string} Decrypted plaintext (UTF-8)
+ * @throws {Error} If decryption fails (wrong key or tampered data)
+ */
+export function decryptWithKey(key, ciphertext) {
+  // Decode base64
+  const data = base64ToUint8(ciphertext);
+
+  // Extract components
+  const iv = data.slice(0, 12);
+  const encrypted = data.slice(12); // ciphertext + authTag
+
+  // Create cipher and decrypt
+  const aes = gcm(key, iv);
+  const decrypted = aes.decrypt(encrypted);
+
+  return new TextDecoder().decode(decrypted);
+}
+
+/**
+ * Wrap a symmetric key for a recipient using NIP-44 encryption.
+ * This allows secure key exchange via Nostr DMs.
+ *
+ * @param {Uint8Array} lensKey - 32-byte symmetric key to wrap
+ * @param {string} senderPrivKey - Sender's hex private key
+ * @param {string} recipientPubKey - Recipient's hex public key
+ * @returns {string} NIP-44 encrypted wrapped key
+ */
+export function wrapKeyForRecipient(lensKey, senderPrivKey, recipientPubKey) {
+  // Convert key to base64 for NIP-44 encryption
+  const keyBase64 = uint8ToBase64(lensKey);
+  return encryptNIP44(senderPrivKey, recipientPubKey, keyBase64);
+}
+
+/**
+ * Unwrap a symmetric key received from a sender using NIP-44 decryption.
+ *
+ * @param {string} wrappedKey - NIP-44 encrypted wrapped key
+ * @param {string} recipientPrivKey - Recipient's hex private key
+ * @param {string} senderPubKey - Sender's hex public key
+ * @returns {Uint8Array} 32-byte symmetric key
+ */
+export function unwrapKey(wrappedKey, recipientPrivKey, senderPubKey) {
+  const keyBase64 = decryptNIP44(recipientPrivKey, senderPubKey, wrappedKey);
+  return base64ToUint8(keyBase64);
+}
+
+/**
+ * Serialize a lens key for persistent storage.
+ * The key is wrapped for the owner using NIP-44.
+ *
+ * @param {Uint8Array} lensKey - 32-byte symmetric key
+ * @param {string} ownerPrivKey - Owner's hex private key
+ * @param {string} ownerPubKey - Owner's hex public key
+ * @returns {Object} Serializable key data { wrappedKey, algorithm, version }
+ */
+export function serializeLensKey(lensKey, ownerPrivKey, ownerPubKey) {
+  return {
+    wrappedKey: wrapKeyForRecipient(lensKey, ownerPrivKey, ownerPubKey),
+    algorithm: 'aes-256-gcm',
+    keyWrap: 'nip44',
+    version: '1.0'
+  };
+}
+
+/**
+ * Deserialize a lens key from persistent storage.
+ *
+ * @param {Object} keyData - Serialized key data
+ * @param {string} ownerPrivKey - Owner's hex private key
+ * @param {string} ownerPubKey - Owner's hex public key
+ * @returns {Uint8Array} 32-byte symmetric key
+ */
+export function deserializeLensKey(keyData, ownerPrivKey, ownerPubKey) {
+  if (keyData.version !== '1.0') {
+    throw new Error(`Unsupported lens key version: ${keyData.version}`);
+  }
+  return unwrapKey(keyData.wrappedKey, ownerPrivKey, ownerPubKey);
+}
+
+/**
+ * Check if content is encrypted (base64-encoded AES-GCM format).
+ * Encrypted content starts with a valid base64 string of at least 28 bytes
+ * (12 IV + 16 authTag) and is not valid JSON.
+ *
+ * @param {string} content - Content string to check
+ * @returns {boolean} True if content appears to be encrypted
+ */
+export function isEncrypted(content) {
+  if (!content || typeof content !== 'string') return false;
+
+  // Quick check: if it starts with { or [, it's likely JSON
+  const trimmed = content.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    return false;
+  }
+
+  // Check if it's valid base64 with minimum length for encrypted data
+  // 12 (IV) + 16 (authTag) = 28 bytes minimum = ~38 base64 chars
+  if (content.length < 38) return false;
+
+  try {
+    const decoded = base64ToUint8(content);
+    // Minimum size check: IV (12) + authTag (16) + at least 1 byte of data
+    return decoded.length >= 29;
+  } catch {
+    return false;
+  }
+}