yakmesh 2.8.2 → 3.0.0

package/server/crypto/annex.js

@@ -0,0 +1,247 @@
+/**
+ * Server-side ANNEX - Post-Quantum Encrypted Sessions
+ * 
+ * Handles ANNEX key exchange and message encryption/decryption for
+ * browser clients connecting via WebSocket.
+ * 
+ * Protocol (server perspective):
+ * 1. Receive client's ML-KEM-768 public key
+ * 2. Encapsulate shared secret, send ciphertext to client
+ * 3. Both derive AES-256-GCM key from shared secret
+ * 4. All subsequent messages encrypted/decrypted via session
+ * 
+ * @module server/crypto/annex
+ * @license MIT
+ * @copyright 2026 YAKMESH Contributors
+ */
+
+import { randomBytes, createCipheriv, createDecipheriv, createHash } from 'crypto';
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+
+// Configuration (must match client)
+const ANNEX_CONFIG = {
+  nonceSize: 12,
+  keyDerivationSalt: 'YAKMESH-ANNEX-VANI-2026',
+  sessionTimeout: 3600000,      // 1 hour session lifetime
+  maxMessagesPerKey: 50000,     // Force re-handshake after N messages
+};
+
+/**
+ * ServerAnnexSession - Server-side encrypted session with a browser client
+ */
+export class ServerAnnexSession {
+  constructor(options = {}) {
+    this.sessionId = options.sessionId;
+    this.clientId = options.clientId || 'client';
+    this.serverId = options.serverId || 'server';
+    
+    // Encryption key (derived from shared secret)
+    this.encryptionKey = null;
+    
+    // Sequence counters for replay protection
+    this.sendSequence = 0;
+    this.recvSequence = 0;
+    this.messageCount = 0;
+    
+    // State
+    this.established = false;
+    this.createdAt = Date.now();
+    this.lastActivity = Date.now();
+  }
+  
+  /**
+   * Check if session has exceeded its lifetime or message limit
+   */
+  isExpired() {
+    if (!this.established) return false;
+    const age = Date.now() - this.createdAt;
+    return age > ANNEX_CONFIG.sessionTimeout || 
+           this.messageCount >= ANNEX_CONFIG.maxMessagesPerKey;
+  }
+  
+  /**
+   * Check if session is approaching expiry (80% of limits)
+   * Used to trigger proactive rekey before hard expiry
+   */
+  isNearingExpiry() {
+    if (!this.established) return false;
+    const age = Date.now() - this.createdAt;
+    return age > ANNEX_CONFIG.sessionTimeout * 0.8 || 
+           this.messageCount >= ANNEX_CONFIG.maxMessagesPerKey * 0.8;
+  }
+  
+  /**
+   * Rekey the session with a new client public key.
+   * Preserves the connection but rotates the encryption key.
+   * Returns new ciphertext to send back to client.
+   */
+  async rekey(publicKeyHex) {
+    const oldKey = this.encryptionKey;
+    
+    // Generate new shared secret from client's new public key
+    const publicKey = hexToBytes(publicKeyHex);
+    const { sharedSecret, cipherText } = ml_kem768.encapsulate(publicKey);
+    
+    // Derive fresh AES-256 key
+    this.encryptionKey = this._deriveKey(sharedSecret);
+    
+    // Zero old key and shared secret
+    if (oldKey?.fill) oldKey.fill(0);
+    if (sharedSecret?.fill) sharedSecret.fill(0);
+    
+    // Reset counters but preserve session identity
+    this.sendSequence = 0;
+    this.recvSequence = 0;
+    this.messageCount = 0;
+    this.createdAt = Date.now();
+    this.lastActivity = Date.now();
+    
+    console.log(`[ServerAnnex] Session ${this.sessionId} rekeyed successfully`);
+    
+    return bytesToHex(cipherText);
+  }
+  
+  /**
+   * Handle client's public key - encapsulate shared secret
+   * Returns ciphertext to send back to client
+   */
+  async handlePublicKey(publicKeyHex) {
+    const publicKey = hexToBytes(publicKeyHex);
+    
+    // Server encapsulates - generates random shared secret + ciphertext
+    const { sharedSecret, cipherText } = ml_kem768.encapsulate(publicKey);
+    
+    // Derive AES-256 key from shared secret
+    this.encryptionKey = this._deriveKey(sharedSecret);
+    
+    // Zero shared secret immediately — only the derived key is needed from here
+    // sharedSecret is a Uint8Array from ml-kem768
+    if (sharedSecret?.fill) sharedSecret.fill(0);
+    
+    this.established = true;
+    
+    console.log(`[ServerAnnex] Session ${this.sessionId} established with ${this.clientId}`);
+    
+    return bytesToHex(cipherText);
+  }
+  
+  /**
+   * Derive AES-256 key from shared secret using SHA3-256
+   */
+  _deriveKey(sharedSecret) {
+    // Hash: sharedSecret + salt + sessionId + clientId + serverId
+    const keyMaterial = Buffer.concat([
+      Buffer.from(sharedSecret),
+      Buffer.from(ANNEX_CONFIG.keyDerivationSalt),
+      Buffer.from(this.sessionId),
+      Buffer.from(this.clientId),  // Client is "local" from their perspective
+      Buffer.from(this.serverId),   // Server is "remote" from their perspective
+    ]);
+    
+    // Use SHA3-256 to derive 32-byte AES key
+    const key = Buffer.from(sha3_256(keyMaterial));
+    
+    return key;
+  }
+  
+  /**
+   * Encrypt data for transmission to client
+   * Returns { nonce, ciphertext, authTag, sequence } as hex strings
+   */
+  encrypt(plaintext) {
+    if (!this.established || !this.encryptionKey) {
+      throw new Error('Session not established');
+    }
+    
+    const nonce = randomBytes(ANNEX_CONFIG.nonceSize);
+    
+    // Encode plaintext
+    const data = typeof plaintext === 'string'
+      ? Buffer.from(plaintext)
+      : Buffer.from(JSON.stringify(plaintext));
+    
+    // AAD for GCM authentication
+    const aadString = `${this.sessionId}:${this.sendSequence}`;
+    
+    // Create cipher with AAD
+    const cipher = createCipheriv('aes-256-gcm', this.encryptionKey, nonce);
+    cipher.setAAD(Buffer.from(aadString));
+    
+    // Encrypt
+    const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    
+    const sequence = this.sendSequence;
+    this.sendSequence++;
+    this.messageCount++;
+    this.lastActivity = Date.now();
+    
+    return {
+      nonce: bytesToHex(nonce),
+      ciphertext: bytesToHex(ciphertext),
+      authTag: bytesToHex(authTag),
+      sequence,
+    };
+  }
+  
+  /**
+   * Decrypt received data from client
+   * Returns plaintext string (JSON)
+   */
+  decrypt(encryptedData) {
+    if (!this.established || !this.encryptionKey) {
+      throw new Error('Session not established');
+    }
+    
+    const { nonce, ciphertext, authTag, sequence } = encryptedData;
+    
+    // Replay protection — reject any sequence not strictly greater than last received
+    if (typeof sequence !== 'number' || sequence <= this.recvSequence) {
+      throw new Error(`Replay detected: sequence ${sequence} <= ${this.recvSequence}`);
+    }
+    
+    const nonceBuffer = Buffer.from(hexToBytes(nonce));
+    const ciphertextBuffer = Buffer.from(hexToBytes(ciphertext));
+    const authTagBuffer = Buffer.from(hexToBytes(authTag));
+    
+    // Create decipher with AAD
+    const decipher = createDecipheriv('aes-256-gcm', this.encryptionKey, nonceBuffer);
+    decipher.setAAD(Buffer.from(`${this.sessionId}:${sequence}`));
+    decipher.setAuthTag(authTagBuffer);
+    
+    // Decrypt
+    const plaintext = Buffer.concat([decipher.update(ciphertextBuffer), decipher.final()]);
+    
+    this.recvSequence = sequence;
+    this.messageCount++;
+    this.lastActivity = Date.now();
+    
+    return plaintext.toString('utf8');
+  }
+  
+  /**
+   * Destroy session and zero keys
+   */
+  destroy() {
+    if (this.encryptionKey) {
+      this.encryptionKey.fill(0);
+      this.encryptionKey = null;
+    }
+    this.established = false;
+    console.log(`[ServerAnnex] Session ${this.sessionId} destroyed`);
+  }
+}
+
+// Handshake message types (must match client)
+export const ANNEX_HANDSHAKE_TYPE = {
+  PUBLIC_KEY: 'annex:public_key',
+  ENCAPSULATED: 'annex:encapsulated',
+  ENCRYPTED: 'annex:encrypted',
+  ERROR: 'annex:error',
+  REKEY: 'annex:rekey',       // Server -> Client: session needs rekeying
+  REKEY_ACK: 'annex:rekey_ack', // Client -> Server: new public key for rekey
+};
+
+export default ServerAnnexSession;

package/server/darshan-api.js

@@ -0,0 +1,343 @@
+/**
+ * DARSHAN Content Streaming API
+ * 
+ * "Content stays on the altar. Pilgrims come to see."
+ * 
+ * Exposes the DARSHAN protocol as HTTP endpoints for:
+ * - Content registration and listing
+ * - Stream requests and chunk delivery
+ * - View attestation and proof-of-viewing
+ * - Bandwidth control and quality selection
+ * 
+ * DARSHAN is the streaming backbone for yakapp-studio content sharing.
+ * Creators keep sovereignty — no copies leave unless explicitly permitted.
+ * 
+ * @module server/darshan-api
+ * @license MIT
+ * @copyright 2026 YAKMESH™ Contributors
+ */
+
+import { Router } from 'express';
+import { createLogger } from '../utils/logger.js';
+
+const log = createLogger('server:darshan');
+
+/**
+ * Create the DARSHAN API router.
+ * 
+ * @param {Object} params
+ * @param {Object} params.darshanGateway - DarshanGateway instance (content host)
+ * @param {Object} params.gossip - GossipProtocol instance
+ * @param {Object} params.identity - NodeIdentity instance
+ * @param {Function} params.writeLimiter - Express rate limiter for writes
+ * @param {Function} params.requirePeerAuth - Peer auth middleware
+ * @returns {Router} Express router mounted at /darshan
+ */
+export function createDarshanAPI({
+  darshanGateway,
+  gossip,
+  identity,
+  writeLimiter,
+  requirePeerAuth,
+}) {
+  const router = Router();
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STATUS
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  router.get('/status', (req, res) => {
+    res.json({
+      darshan: 'operational',
+      stats: darshanGateway.stats,
+      contentCount: darshanGateway.contents.size,
+      activeStreams: darshanGateway.streams.size,
+    });
+  });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CONTENT REGISTRY
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * GET /darshan/content — List available content (public metadata only)
+   */
+  router.get('/content', (req, res) => {
+    const type = req.query.type || null;
+    const limit = Math.min(parseInt(req.query.limit) || 50, 200);
+    
+    let contents = [];
+    for (const content of darshanGateway.contents.values()) {
+      // Check exclusions
+      if (darshanGateway.exclusions.has(content.contentId)) continue;
+      
+      if (type && content.contentType !== type) continue;
+      
+      contents.push(content.getPublicMetadata());
+    }
+    
+    contents = contents.slice(0, limit);
+    
+    res.json({
+      contents,
+      total: contents.length,
+      nodeId: identity.identity.nodeId,
+    });
+  });
+
+  /**
+   * GET /darshan/content/:contentId — Get content metadata
+   */
+  router.get('/content/:contentId', (req, res) => {
+    const { contentId } = req.params;
+    const content = darshanGateway.contents.get(contentId);
+    
+    if (!content || darshanGateway.exclusions.has(contentId)) {
+      return res.status(404).json({ error: 'Content not found' });
+    }
+
+    res.json(content.getPublicMetadata());
+  });
+
+  /**
+   * POST /darshan/content — Register content for sharing
+   */
+  router.post('/content', writeLimiter, requirePeerAuth, (req, res) => {
+    const { path, name, description, contentType, mimeType, permissions, accessList } = req.body;
+    
+    if (!path) {
+      return res.status(400).json({ error: 'path required' });
+    }
+    
+    // Path traversal defense — reject .., absolute paths, drive letters, and null bytes.
+    // DARSHAN content paths must be relative within the host's content root.
+    // IMPORTANT: URL-decode BEFORE checking, to catch %2e%2e (%2e = .) bypass.
+    let normalizedPath;
+    try {
+      normalizedPath = decodeURIComponent(String(path)).replace(/\\/g, '/');
+    } catch {
+      return res.status(400).json({ error: 'Invalid path: malformed encoding' });
+    }
+    if (normalizedPath.includes('\0') ||            // Null byte injection
+        normalizedPath.includes('..') ||            // Traversal
+        normalizedPath.startsWith('/') ||           // Absolute path
+        /^[a-zA-Z]:/.test(normalizedPath)) {        // Windows drive letter
+      return res.status(400).json({ error: 'Invalid path: traversal or absolute paths not allowed' });
+    }
+
+    darshanGateway.registerContent({
+      path,
+      name,
+      description,
+      contentType,
+      mimeType,
+      permissions,
+      accessList,
+    }).then(result => {
+      if (result.success !== false) {
+        // Announce to mesh
+        gossip.spreadRumor('darshan:content:available', {
+          contentId: result.contentId || result.content?.contentId,
+          hostNodeId: identity.identity.nodeId,
+          metadata: result.content?.getPublicMetadata?.() || result,
+        });
+      }
+      res.json(result);
+    }).catch(error => {
+      res.status(500).json({ error: error.message });
+    });
+  });
+
+  /**
+   * DELETE /darshan/content/:contentId — Unregister content
+   */
+  router.delete('/content/:contentId', writeLimiter, requirePeerAuth, (req, res) => {
+    const { contentId } = req.params;
+    
+    const content = darshanGateway.contents.get(contentId);
+    if (!content) {
+      return res.status(404).json({ error: 'Content not found' });
+    }
+
+    darshanGateway.contents.delete(contentId);
+    if (content.path) {
+      darshanGateway.contentByPath.delete(content.path);
+    }
+
+    // Announce removal to mesh
+    gossip.spreadRumor('darshan:content:removed', {
+      contentId,
+      hostNodeId: identity.identity.nodeId,
+    });
+
+    res.json({ success: true });
+  });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STREAMING
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * POST /darshan/stream — Request a stream
+   */
+  router.post('/stream', writeLimiter, requirePeerAuth, (req, res) => {
+    const { contentId, quality, viewerNodeId } = req.body;
+    
+    if (!contentId) {
+      return res.status(400).json({ error: 'contentId required' });
+    }
+
+    const content = darshanGateway.contents.get(contentId);
+    if (!content || darshanGateway.exclusions.has(contentId)) {
+      return res.status(404).json({ error: 'Content not found' });
+    }
+
+    // Check access if GUMBA-controlled
+    if (content.accessList) {
+      // Access verification would go through GUMBA — simplified for now
+      const viewer = viewerNodeId || req.authenticatedPeer;
+      if (!viewer) {
+        return res.status(403).json({ error: 'GUMBA access proof required' });
+      }
+    }
+
+    try {
+      const stream = darshanGateway.createStream?.(contentId, {
+        quality,
+        viewerNodeId: viewerNodeId || req.authenticatedPeer || 'anonymous',
+      });
+
+      if (stream) {
+        res.json({
+          success: true,
+          streamId: stream.streamId || stream.id,
+          contentId,
+          totalChunks: Math.ceil(content.size / content.chunkSize || 65536),
+          chunkHashes: content.chunkHashes,
+        });
+      } else {
+        // Fallback: return content info for direct streaming
+        content.viewCount++;
+        darshanGateway.stats.streamsCreated++;
+        res.json({
+          success: true,
+          contentId,
+          size: content.size,
+          mimeType: content.mimeType,
+          hash: content.hash,
+        });
+      }
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  /**
+   * GET /darshan/stream/:streamId/chunk/:index — Get a chunk
+   */
+  router.get('/stream/:streamId/chunk/:index', (req, res) => {
+    const { streamId, index } = req.params;
+    const chunkIndex = parseInt(index);
+    
+    const stream = darshanGateway.streams.get(streamId);
+    if (!stream) {
+      return res.status(404).json({ error: 'Stream not found or expired' });
+    }
+
+    try {
+      const chunk = stream.getChunk?.(chunkIndex);
+      if (chunk) {
+        res.set('Content-Type', 'application/octet-stream');
+        res.set('X-Chunk-Index', chunkIndex.toString());
+        res.set('X-Chunk-Hash', chunk.hash || '');
+        res.send(chunk.data || chunk);
+      } else {
+        res.status(404).json({ error: 'Chunk not available' });
+      }
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // VIEW ATTESTATION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * POST /darshan/attest — Submit a view attestation (proof of viewing)
+   */
+  router.post('/attest', requirePeerAuth, (req, res) => {
+    const { contentId, viewerNodeId, streamId, duration, bytesConsumed } = req.body;
+    
+    if (!contentId || !viewerNodeId) {
+      return res.status(400).json({ error: 'contentId and viewerNodeId required' });
+    }
+
+    try {
+      const attestation = darshanGateway.createAttestation?.({
+        contentId,
+        viewerNodeId,
+        streamId,
+        duration,
+        bytesConsumed,
+      });
+
+      if (attestation) {
+        res.json({
+          success: true,
+          attestationId: attestation.attestationId || attestation.id,
+        });
+      } else {
+        // Track basic stats even without full attestation module
+        const content = darshanGateway.contents.get(contentId);
+        if (content) {
+          content.viewCount++;
+          content.totalBytesServed += bytesConsumed || 0;
+        }
+        darshanGateway.stats.attestationsCreated++;
+        res.json({ success: true, tracked: true });
+      }
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  /**
+   * GET /darshan/attestations/:contentId — Get view attestations for content
+   */
+  router.get('/attestations/:contentId', (req, res) => {
+    const { contentId } = req.params;
+    
+    const attestations = [];
+    for (const att of darshanGateway.attestations.values()) {
+      if (att.contentId === contentId) {
+        attestations.push(att.toJSON ? att.toJSON() : att);
+      }
+    }
+
+    res.json({ attestations, total: attestations.length });
+  });
+
+  log.info('✓ DARSHAN API initialized (content streaming + attestation)');
+
+  return router;
+}
+
+/**
+ * Wire DARSHAN gossip handlers into the mesh rumor stream.
+ */
+export function wireDarshanGossip(mesh, darshanGateway) {
+  mesh.on('rumor', (topic, data, origin) => {
+    // Content availability announcements from other nodes
+    if (topic === 'darshan:content:available') {
+      darshanGateway.emit?.('remote:content:available', data);
+    }
+
+    // Content removal announcements
+    if (topic === 'darshan:content:removed') {
+      darshanGateway.emit?.('remote:content:removed', data);
+    }
+  });
+
+  log.info('✓ DARSHAN gossip handlers wired into mesh');
+}