holosphere 2.0.0-alpha1 → 2.0.0-alpha11

package/src/crypto/nostr-utils.js

@@ -0,0 +1,303 @@
+/**
+ * @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';
+
+// ============================================================================
+// Key Conversion Utilities
+// ============================================================================
+
+/**
+ * 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);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * 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)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * 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();
+
+  if (!trimmed) {
+    return { valid: false, error: 'Public key is required' };
+  }
+
+  // Check if it's already hex (64 characters)
+  if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    return { valid: true, hexPubKey: trimmed.toLowerCase() };
+  }
+
+  // Handle nostr: URI prefix
+  let npubString = trimmed;
+  if (npubString.startsWith('nostr:')) {
+    npubString = npubString.slice(6);
+  }
+
+  // Try to decode as npub
+  if (npubString.startsWith('npub1')) {
+    try {
+      const decoded = nip19.decode(npubString);
+      if (decoded.type === 'npub') {
+        return { valid: true, hexPubKey: decoded.data };
+      }
+      return { valid: false, error: 'Invalid npub format' };
+    } catch (e) {
+      return { valid: false, error: 'Invalid npub: unable to decode' };
+    }
+  }
+
+  return { valid: false, error: 'Enter a valid npub (npub1...) or 64-character hex public key' };
+}
+
+/**
+ * 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 {
+    return nip19.npubEncode(hexPubKey);
+  } catch (e) {
+    console.error('Failed to encode hex to npub:', e);
+    return hexPubKey; // Return original on error
+  }
+}
+
+/**
+ * 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 {
+    const decoded = nip19.decode(npub);
+    if (decoded.type === 'npub') {
+      return decoded.data;
+    }
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 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 || '';
+  return `${pubKey.slice(0, 8)}...${pubKey.slice(-8)}`;
+}
+
+/**
+ * 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 || '';
+  return `${npub.slice(0, 12)}...${npub.slice(-8)}`;
+}
+
+/**
+ * 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));
+}
+
+// ============================================================================
+// NIP-04 Encryption
+// ============================================================================
+
+/**
+ * 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 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);
+}
+
+// ============================================================================
+// NIP-44 Encryption (Modern, Audited - Replaces NIP-04)
+// ============================================================================
+
+/**
+ * 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);
+  // nostr-tools nip44 expects pubkey as hex string, not bytes
+  const conversationKey = nip44.v2.utils.getConversationKey(privKeyBytes, recipientPubKey);
+  return nip44.v2.encrypt(content, conversationKey);
+}
+
+/**
+ * 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);
+  // nostr-tools nip44 expects pubkey as hex string, not bytes
+  const conversationKey = nip44.v2.utils.getConversationKey(privKeyBytes, senderPubKey);
+  return nip44.v2.decrypt(encryptedContent, conversationKey);
+}
+
+// ============================================================================
+// Event Creation
+// ============================================================================
+
+/**
+ * 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 = {
+    kind,
+    content,
+    tags,
+    created_at: Math.floor(Date.now() / 1000),
+  };
+
+  return finalizeEvent(event, hexToBytes(privateKey));
+}
+
+/**
+ * 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(
+    4, // NIP-04 encrypted DM
+    encryptedContent,
+    [['p', recipientPubKey]],
+    privateKey
+  );
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * 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 (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')) {
+    return false;
+  }
+  try {
+    const decoded = nip19.decode(str);
+    return decoded.type === 'npub';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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 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 = {
+    kind: event.kind,
+    content: event.content,
+    tags: event.tags || [],
+    created_at: event.created_at || Math.floor(Date.now() / 1000),
+  };
+  return finalizeEvent(eventToSign, hexToBytes(privateKey));
+}
+
+/**
+ * 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';