holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/crypto/nostr-utils.js

@@ -1,9 +1,8 @@
 /**
- * Nostr Utility Functions
- *
- * Provides browser-compatible utilities for Nostr key handling and encryption.
- * Supports both NIP-04 (legacy) and NIP-44 (modern, audited) encryption.
- * Apps can use these without directly importing nostr-tools.
+ * @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.
+ * @module crypto/nostr-utils
  */
 
 import { nip04, nip44, nip19, getPublicKey as nostrGetPublicKey, finalizeEvent, verifyEvent as nostrVerifyEvent } from 'nostr-tools';
@@ -13,9 +12,9 @@ import { nip04, nip44, nip19, getPublicKey as nostrGetPublicKey, finalizeEvent,
 // ============================================================================
 
 /**
- * Convert hex string to Uint8Array
- * @param {string} hex - Hex string
- * @returns {Uint8Array} Byte array
+ * Convert hex string to Uint8Array.
+ * @param {string} hex - Hexadecimal string (even length)
+ * @returns {Uint8Array} Byte array representation
  */
 export function hexToBytes(hex) {
   const bytes = new Uint8Array(hex.length / 2);
@@ -26,9 +25,9 @@ export function hexToBytes(hex) {
 }
 
 /**
- * Convert Uint8Array to hex string
- * @param {Uint8Array} bytes - Byte array
- * @returns {string} Hex string
+ * Convert Uint8Array to hex string.
+ * @param {Uint8Array} bytes - Byte array to convert
+ * @returns {string} Hexadecimal string representation
  */
 export function bytesToHex(bytes) {
   return Array.from(bytes)
@@ -37,9 +36,10 @@ export function bytesToHex(bytes) {
 }
 
 /**
- * Parse an npub or hex public key string into hex format
- * @param {string} input - npub (npub1...) or hex public key
- * @returns {{ valid: boolean, hexPubKey?: string, error?: string }}
+ * Parse an npub or hex public key string into hex format.
+ * Handles nostr: URI prefix and validates both npub and hex formats.
+ * @param {string} input - npub string (npub1...) or 64-character hex public key
+ * @returns {Object} Validation result with valid, hexPubKey (if valid), error (if invalid)
  */
 export function parseNpubOrHex(input) {
   const trimmed = input?.trim();
@@ -76,9 +76,9 @@ export function parseNpubOrHex(input) {
 }
 
 /**
- * Convert a hex public key to npub format
- * @param {string} hexPubKey - Hex public key (64 chars)
- * @returns {string} npub string
+ * Convert a hex public key to npub format.
+ * @param {string} hexPubKey - Hex public key (64 characters)
+ * @returns {string} npub-encoded public key (npub1...)
  */
 export function hexToNpub(hexPubKey) {
   try {
@@ -90,9 +90,9 @@ export function hexToNpub(hexPubKey) {
 }
 
 /**
- * Convert npub to hex public key
- * @param {string} npub - npub string
- * @returns {string|null} Hex public key or null if invalid
+ * Convert npub to hex public key.
+ * @param {string} npub - npub-encoded public key string
+ * @returns {string|null} 64-character hex public key or null if invalid
  */
 export function npubToHex(npub) {
   try {
@@ -107,9 +107,9 @@ export function npubToHex(npub) {
 }
 
 /**
- * Shorten a public key for display (first 8 and last 8 chars)
- * @param {string} pubKey - Public key (hex or npub)
- * @returns {string} Shortened key
+ * Shorten a public key for display (first 8 and last 8 chars).
+ * @param {string} pubKey - Public key in hex or npub format
+ * @returns {string} Shortened key with ellipsis (e.g., 'abcd1234...wxyz9876')
  */
 export function shortenPubKey(pubKey) {
   if (!pubKey || pubKey.length <= 20) return pubKey || '';
@@ -117,9 +117,9 @@ export function shortenPubKey(pubKey) {
 }
 
 /**
- * Shorten an npub for display
- * @param {string} npub - npub string
- * @returns {string} Shortened npub
+ * Shorten an npub for display (first 12 and last 8 chars).
+ * @param {string} npub - npub-encoded public key
+ * @returns {string} Shortened npub with ellipsis
  */
 export function shortenNpub(npub) {
   if (!npub || npub.length <= 20) return npub || '';
@@ -127,9 +127,10 @@ export function shortenNpub(npub) {
 }
 
 /**
- * Get public key from private key (matches nostr-tools API)
- * @param {string} privateKey - Hex private key
- * @returns {string} Hex public key
+ * Derive public key from private key using secp256k1.
+ * Matches nostr-tools getPublicKey API.
+ * @param {string} privateKey - 64-character hex private key
+ * @returns {string} Derived 64-character hex public key
  */
 export function getPublicKey(privateKey) {
   return nostrGetPublicKey(hexToBytes(privateKey));
@@ -140,22 +141,23 @@ export function getPublicKey(privateKey) {
 // ============================================================================
 
 /**
- * Encrypt a message using NIP-04 (for DMs)
- * @param {string} privateKey - Sender's hex private key
- * @param {string} recipientPubKey - Recipient's hex public key
- * @param {string} content - Plain text content
- * @returns {Promise<string>} Encrypted content
+ * Encrypt a message using NIP-04 (legacy DM encryption).
+ * Uses AES-256-CBC with base64 encoding. Consider using NIP-44 for new implementations.
+ * @param {string} privateKey - Sender's 64-character hex private key
+ * @param {string} recipientPubKey - Recipient's 64-character hex public key
+ * @param {string} content - Plain text message content
+ * @returns {Promise<string>} NIP-04 encrypted content string
  */
 export async function encryptNIP04(privateKey, recipientPubKey, content) {
   return await nip04.encrypt(privateKey, recipientPubKey, content);
 }
 
 /**
- * Decrypt a NIP-04 encrypted message
- * @param {string} privateKey - Recipient's hex private key
- * @param {string} senderPubKey - Sender's hex public key
- * @param {string} encryptedContent - Encrypted content
- * @returns {Promise<string>} Decrypted content
+ * Decrypt a NIP-04 encrypted message.
+ * @param {string} privateKey - Recipient's 64-character hex private key
+ * @param {string} senderPubKey - Sender's 64-character hex public key
+ * @param {string} encryptedContent - NIP-04 encrypted content string
+ * @returns {Promise<string>} Decrypted plain text content
  */
 export async function decryptNIP04(privateKey, senderPubKey, encryptedContent) {
   return await nip04.decrypt(privateKey, senderPubKey, encryptedContent);
@@ -166,12 +168,12 @@ export async function decryptNIP04(privateKey, senderPubKey, encryptedContent) {
 // ============================================================================
 
 /**
- * Encrypt a message using NIP-44 (modern encryption standard)
- * Uses ChaCha20 + HMAC-SHA256, audited by Cure53
- * @param {string} privateKey - Sender's hex private key
- * @param {string} recipientPubKey - Recipient's hex public key
- * @param {string} content - Plain text content
- * @returns {string} Encrypted content (base64)
+ * Encrypt a message using NIP-44 (modern, audited encryption standard).
+ * Uses ChaCha20-Poly1305 + HMAC-SHA256, audited by Cure53. Recommended for new implementations.
+ * @param {string} privateKey - Sender's 64-character hex private key
+ * @param {string} recipientPubKey - Recipient's 64-character hex public key
+ * @param {string} content - Plain text message content
+ * @returns {string} NIP-44 encrypted content (base64-encoded)
  */
 export function encryptNIP44(privateKey, recipientPubKey, content) {
   const privKeyBytes = hexToBytes(privateKey);
@@ -181,11 +183,11 @@ export function encryptNIP44(privateKey, recipientPubKey, content) {
 }
 
 /**
- * Decrypt a NIP-44 encrypted message
- * @param {string} privateKey - Recipient's hex private key
- * @param {string} senderPubKey - Sender's hex public key
- * @param {string} encryptedContent - Encrypted content (base64)
- * @returns {string} Decrypted content
+ * Decrypt a NIP-44 encrypted message.
+ * @param {string} privateKey - Recipient's 64-character hex private key
+ * @param {string} senderPubKey - Sender's 64-character hex public key
+ * @param {string} encryptedContent - NIP-44 encrypted content (base64-encoded)
+ * @returns {string} Decrypted plain text content
  */
 export function decryptNIP44(privateKey, senderPubKey, encryptedContent) {
   const privKeyBytes = hexToBytes(privateKey);
@@ -199,12 +201,13 @@ export function decryptNIP44(privateKey, senderPubKey, encryptedContent) {
 // ============================================================================
 
 /**
- * Create and sign a Nostr event
- * @param {number} kind - Event kind
- * @param {string} content - Event content
- * @param {string[][]} tags - Event tags
- * @param {string} privateKey - Hex private key for signing
- * @returns {Object} Signed Nostr event
+ * Create and sign a Nostr event.
+ * Automatically adds created_at timestamp, computes event ID, and generates signature.
+ * @param {number} kind - Event kind (e.g., 1 for text note, 4 for DM)
+ * @param {string} content - Event content string
+ * @param {string[][]} tags - Array of tag arrays (e.g., [['p', 'pubkey'], ['e', 'eventId']])
+ * @param {string} privateKey - 64-character hex private key for signing
+ * @returns {Object} Signed Nostr event with id, pubkey, sig, and all fields
  */
 export function createSignedEvent(kind, content, tags, privateKey) {
   const event = {
@@ -218,11 +221,12 @@ export function createSignedEvent(kind, content, tags, privateKey) {
 }
 
 /**
- * Create a NIP-04 encrypted DM event (kind 4)
- * @param {string} recipientPubKey - Recipient's hex public key
- * @param {string} encryptedContent - NIP-04 encrypted content
- * @param {string} privateKey - Sender's hex private key
- * @returns {Object} Signed DM event
+ * Create a NIP-04 encrypted DM event (kind 4).
+ * Creates and signs a direct message event with proper recipient tagging.
+ * @param {string} recipientPubKey - Recipient's 64-character hex public key
+ * @param {string} encryptedContent - NIP-04 encrypted message content
+ * @param {string} privateKey - Sender's 64-character hex private key
+ * @returns {Object} Signed Nostr DM event (kind 4) with ['p', recipientPubKey] tag
  */
 export function createDMEvent(recipientPubKey, encryptedContent, privateKey) {
   return createSignedEvent(
@@ -238,18 +242,18 @@ export function createDMEvent(recipientPubKey, encryptedContent, privateKey) {
 // ============================================================================
 
 /**
- * Check if a string is a valid hex public key
- * @param {string} str - String to check
- * @returns {boolean}
+ * Check if a string is a valid hex public key (64 hex characters).
+ * @param {string} str - String to validate
+ * @returns {boolean} True if valid 64-character hex string
  */
 export function isValidHexPubKey(str) {
   return typeof str === 'string' && /^[0-9a-fA-F]{64}$/.test(str);
 }
 
 /**
- * Check if a string is a valid npub
- * @param {string} str - String to check
- * @returns {boolean}
+ * Check if a string is a valid npub (starts with npub1 and decodes correctly).
+ * @param {string} str - String to validate
+ * @returns {boolean} True if valid npub format
  */
 export function isValidNpub(str) {
   if (typeof str !== 'string' || !str.startsWith('npub1')) {
@@ -264,18 +268,19 @@ export function isValidNpub(str) {
 }
 
 /**
- * Generate a unique nonce
- * @returns {string} Unique nonce
+ * Generate a unique nonce using timestamp and random value.
+ * @returns {string} Unique nonce string combining base36 timestamp and random suffix
  */
 export function generateNonce() {
   return Date.now().toString(36) + Math.random().toString(36).substring(2, 15);
 }
 
 /**
- * Sign a Nostr event (alias for createSignedEvent that accepts event object)
- * @param {Object} event - Unsigned event object with kind, content, tags
- * @param {string} privateKey - Hex private key for signing
- * @returns {Object} Signed Nostr event
+ * Sign a Nostr event object.
+ * Accepts an event object instead of individual parameters. Adds created_at if missing.
+ * @param {Object} event - Unsigned event object with kind, content, and tags
+ * @param {string} privateKey - 64-character hex private key for signing
+ * @returns {Object} Signed Nostr event with id, pubkey, and sig fields added
  */
 export function signEvent(event, privateKey) {
   const eventToSign = {
@@ -288,9 +293,10 @@ export function signEvent(event, privateKey) {
 }
 
 /**
- * Verify a Nostr event signature
- * @param {Object} event - Signed Nostr event to verify
- * @returns {boolean} True if signature is valid
+ * Verify a Nostr event signature using secp256k1.
+ * Validates that the event ID matches the event data and the signature is valid.
+ * @param {Object} event - Signed Nostr event with id, pubkey, and sig fields
+ * @returns {boolean} True if event signature is cryptographically valid
  */
 export function verifyEvent(event) {
   return nostrVerifyEvent(event);

package/src/crypto/secp256k1.js

@@ -1,6 +1,11 @@
 /**
- * Cryptographic Operations (secp256k1)
- * Lazy-loaded for performance
+ * @fileoverview Cryptographic Operations using secp256k1.
+ *
+ * Provides signing, verification, and capability token operations using
+ * the secp256k1 elliptic curve (same curve used by Bitcoin and Nostr).
+ * Uses lazy loading for the crypto module to improve startup performance.
+ *
+ * @module crypto/secp256k1
  */
 
 import { sha256 } from '@noble/hashes/sha256';

package/src/federation/handshake.js

@@ -300,7 +300,7 @@ export function subscribeToFederationDMs(client, privateKey, publicKey, handlers
  * @param {string} params.holonName - Current holon name
  * @param {Object} [params.lensConfig] - Lens configuration
  * @param {string} [params.message] - Optional message
- * @returns {Promise<{ success: boolean, requestId?: string, error?: string }>}
+ * @returns {Promise<Object>} Result with success, requestId (if successful), error (if failed)
  */
 export async function initiateFederationHandshake(holosphere, privateKey, params) {
   const {
@@ -359,7 +359,7 @@ export async function initiateFederationHandshake(holosphere, privateKey, params
  * @param {string} params.holonName - Current holon name
  * @param {Object} [params.lensConfig] - Our lens configuration
  * @param {string} [params.message] - Optional message
- * @returns {Promise<{ success: boolean, error?: string }>}
+ * @returns {Promise<Object>} Result with success and optional error
  */
 export async function acceptFederationRequest(holosphere, privateKey, params) {
   const {
@@ -432,7 +432,7 @@ export async function acceptFederationRequest(holosphere, privateKey, params) {
  * @param {string} params.requestId - Original request ID
  * @param {string} params.senderPubKey - Original sender's public key
  * @param {string} [params.message] - Optional rejection message
- * @returns {Promise<{ success: boolean, error?: string }>}
+ * @returns {Promise<Object>} Result with success and optional error
  */
 export async function rejectFederationRequest(holosphere, privateKey, params) {
   const { requestId, senderPubKey, message } = params;
@@ -458,8 +458,8 @@ export async function rejectFederationRequest(holosphere, privateKey, params) {
 
 /**
  * Check if payload is a federation request
- * @param {any} payload
- * @returns {payload is FederationRequestPayload}
+ * @param {*} payload - Payload to check
+ * @returns {boolean} True if payload is a FederationRequestPayload
  */
 export function isFederationRequest(payload) {
   return payload?.type === 'federation_request' && payload?.version === '1.0';
@@ -467,8 +467,8 @@ export function isFederationRequest(payload) {
 
 /**
  * Check if payload is a federation response
- * @param {any} payload
- * @returns {payload is FederationResponsePayload}
+ * @param {*} payload - Payload to check
+ * @returns {boolean} True if payload is a FederationResponsePayload
  */
 export function isFederationResponse(payload) {
   return payload?.type === 'federation_response' && payload?.version === '1.0';

package/src/federation/hologram.js

@@ -1,11 +1,19 @@
 /**
- * Federation and Hologram (reference) Management
+ * @fileoverview Federation and Hologram (Reference) Management.
+ *
+ * Provides hologram (lightweight reference) creation, resolution, and management.
+ * Holograms enable data to appear in multiple holons while maintaining a single
+ * source of truth. Supports circular reference detection and cross-holosphere
+ * federation with capability-based access control.
+ *
+ * @module federation/hologram
  */
 
 import { buildPath, write, read, update } from '../storage/unified-storage.js';
 import { verifyCapability } from '../crypto/secp256k1.js';
 import { getCapabilityForAuthor } from './registry.js';
 
+/** @constant {number} Maximum depth for hologram resolution chain */
 const MAX_RESOLUTION_DEPTH = 10;
 
 /**

package/src/hierarchical/upcast.js

@@ -1,6 +1,7 @@
 /**
- * Hierarchical Aggregation (Upcast Operations)
- * FR-025 to FR-027
+ * @fileoverview Hierarchical aggregation (upcast) operations for propagating data to parent holons.
+ * Implements upcast operations (FR-025 to FR-027) for H3-based geographic hierarchies.
+ * @module hierarchical/upcast
  */
 
 import { getParents, isValidH3 } from '../spatial/h3-operations.js';
@@ -8,15 +9,17 @@ import { createHologram } from '../federation/hologram.js';
 import { write } from '../storage/unified-storage.js';
 
 /**
- * Upcast data to parent holons in hierarchy
+ * Upcast data to parent holons in the H3 hierarchy.
+ * Creates holograms in parent holons referencing the source data.
  * @param {Object} hs - HoloSphere instance
- * @param {string} holonId - Source holon ID (must be H3)
- * @param {string} lensName - Lens name
- * @param {string} dataId - Data ID
- * @param {Object} options - Upcast options
- * @param {number} options.maxLevel - Maximum levels to propagate (default: 3)
- * @param {string} options.operation - 'summarize', 'aggregate', or 'concatenate'
- * @returns {Promise<boolean>} Success indicator
+ * @param {string} holonId - Source holon ID (must be valid H3 index)
+ * @param {string} lensName - Lens name for the data
+ * @param {string} dataId - Data identifier to upcast
+ * @param {Object} [options={}] - Upcast configuration options
+ * @param {number} [options.maxLevel=3] - Maximum levels to propagate upward
+ * @param {string} [options.operation='concatenate'] - Aggregation operation: 'summarize', 'aggregate', or 'concatenate'
+ * @returns {Promise<boolean>} True if upcast succeeded
+ * @throws {Error} If holonId is not a valid H3 index
  */
 export async function upcast(hs, holonId, lensName, dataId, options = {}) {
   const { maxLevel = 3, operation = 'concatenate' } = options;
@@ -46,8 +49,16 @@ export async function upcast(hs, holonId, lensName, dataId, options = {}) {
 }
 
 /**
- * Propagate data to parent holon
+ * Propagate data to a parent holon by creating a hologram reference.
  * @private
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application name
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} parentHolon - Parent holon ID to propagate to
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data identifier
+ * @param {string} operation - Aggregation operation type
+ * @returns {Promise<Object>} Write operation result
  */
 async function propagateToParent(
   client,
@@ -71,9 +82,10 @@ async function propagateToParent(
 }
 
 /**
- * Summarize operation (count aggregation)
- * @param {Object[]} items - Data items
- * @returns {Object} Summary object
+ * Summarize operation for count-based aggregation.
+ * Returns a summary object with the count of items.
+ * @param {Object[]} items - Array of data items to summarize
+ * @returns {Object} Summary object with operation type, count, and summary flag
  */
 export function summarize(items) {
   return {
@@ -84,9 +96,10 @@ export function summarize(items) {
 }
 
 /**
- * Aggregate operation (merge objects)
- * @param {Object[]} items - Data items
- * @returns {Object} Aggregated object
+ * Aggregate operation for merging objects.
+ * Combines all items into a single object using Object.assign.
+ * @param {Object[]} items - Array of objects to merge
+ * @returns {Object} Aggregated object with all properties merged
  */
 export function aggregate(items) {
   const result = { operation: 'aggregate' };
@@ -99,9 +112,10 @@ export function aggregate(items) {
 }
 
 /**
- * Concatenate operation (array merge)
- * @param {Array[]} items - Array items
- * @returns {Array} Concatenated array
+ * Concatenate operation for flattening nested arrays.
+ * Flattens all input arrays into a single array.
+ * @param {Array[]} items - Array of arrays to concatenate
+ * @returns {Object} Object with operation type and flattened items array
  */
 export function concatenate(items) {
   return {