yakmesh 2.8.2 → 3.0.0

package/adapters/content-adapter.js

@@ -0,0 +1,273 @@
+/**
+ * Yakmesh - Content Adapter Base Class
+ * 
+ * Specialized adapter for content distribution via DARSHAN protocol.
+ * Designed for scripture, documents, educational materials, and other
+ * content that benefits from the view-not-copy paradigm.
+ * 
+ * @module adapters/content-adapter
+ * @version 1.0.0
+ */
+
+import { EventEmitter } from 'events';
+
+/**
+ * Capability declarations for content adapters
+ * Adapters MUST declare their capabilities upfront
+ */
+export const CONTENT_CAPABILITIES = {
+  // Content types this adapter can serve
+  SERVE_PDF: 'serve:pdf',
+  SERVE_TEXT: 'serve:text',
+  SERVE_AUDIO: 'serve:audio',
+  SERVE_VIDEO: 'serve:video',
+  
+  // Search/lookup capabilities
+  SEARCH_FULLTEXT: 'search:fulltext',
+  SEARCH_REFERENCE: 'search:reference',  // e.g., John 3:16
+  
+  // Chat integration capabilities
+  CHAT_QUOTE: 'chat:quote',          // Can generate quotes for KATHA
+  CHAT_EMBED: 'chat:embed',          // Can embed previews in chat
+  CHAT_LOOKUP: 'chat:lookup',        // Can respond to lookup commands
+  
+  // Network capabilities
+  NET_STREAM: 'net:stream',          // Can stream via DARSHAN
+  NET_DOWNLOAD: 'net:download',      // Allows downloads (opt-in)
+  NET_CACHE: 'net:cache',            // Can be cached by peers
+};
+
+/**
+ * Content metadata standard
+ */
+export class ContentMetadata {
+  constructor({
+    id,
+    title,
+    author = null,
+    copyright = null,
+    license = null,
+    version = '1.0.0',
+    language = 'en',
+    contentType = 'application/pdf',
+    size = 0,
+    hash = null,
+    created = new Date(),
+    modified = new Date(),
+    tags = [],
+    references = {},  // e.g., { 'John 3:16': { page: 42, position: 0.3 } }
+  } = {}) {
+    this.id = id;
+    this.title = title;
+    this.author = author;
+    this.copyright = copyright;
+    this.license = license;
+    this.version = version;
+    this.language = language;
+    this.contentType = contentType;
+    this.size = size;
+    this.hash = hash;
+    this.created = created;
+    this.modified = modified;
+    this.tags = tags;
+    this.references = references;
+  }
+  
+  toJSON() {
+    return { ...this };
+  }
+}
+
+/**
+ * Abstract base class for content distribution adapters
+ */
+export class ContentAdapter extends EventEmitter {
+  /**
+   * @param {Object} config - Adapter configuration
+   * @param {string} config.name - Human-readable adapter name
+   * @param {string} config.id - Unique adapter identifier
+   * @param {string[]} config.capabilities - Array of CONTENT_CAPABILITIES
+   * @param {Object} config.darshan - DARSHAN instance for streaming
+   */
+  constructor(config = {}) {
+    super();
+    
+    if (new.target === ContentAdapter) {
+      throw new Error('ContentAdapter is abstract and cannot be instantiated directly');
+    }
+    
+    this.name = config.name || 'UnnamedContentAdapter';
+    this.id = config.id || 'content-adapter-' + Date.now();
+    this.capabilities = new Set(config.capabilities || []);
+    this.darshan = config.darshan || null;
+    
+    // Content catalog
+    this.catalog = new Map();  // id -> ContentMetadata
+    
+    // Statistics
+    this.stats = {
+      contentServed: 0,
+      searchQueries: 0,
+      chatQuotes: 0,
+      errors: [],
+    };
+    
+    // Security: Validate capabilities
+    this._validateCapabilities();
+  }
+  
+  /**
+   * Initialize the adapter and build content catalog
+   * @abstract
+   */
+  async init() {
+    throw new Error('init() must be implemented by subclass');
+  }
+  
+  /**
+   * Get list of available content
+   * @returns {ContentMetadata[]}
+   */
+  listContent() {
+    return Array.from(this.catalog.values());
+  }
+  
+  /**
+   * Get content metadata by ID
+   * @param {string} id - Content ID
+   * @returns {ContentMetadata|null}
+   */
+  getContentMeta(id) {
+    return this.catalog.get(id) || null;
+  }
+  
+  /**
+   * Search content by query
+   * @abstract
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<Object[]>} Search results
+   */
+  async search(query, options = {}) {
+    throw new Error('search() must be implemented by subclass');
+  }
+  
+  /**
+   * Lookup content by reference (e.g., 'John 3:16')
+   * @abstract
+   * @param {string} reference - Reference string
+   * @returns {Promise<Object|null>} Lookup result
+   */
+  async lookupReference(reference) {
+    throw new Error('lookupReference() must be implemented by subclass');
+  }
+  
+  /**
+   * Get content stream for DARSHAN
+   * @abstract
+   * @param {string} id - Content ID
+   * @param {Object} options - Stream options (range, quality, etc.)
+   * @returns {Promise<ReadableStream>}
+   */
+  async getContentStream(id, options = {}) {
+    throw new Error('getContentStream() must be implemented by subclass');
+  }
+  
+  /**
+   * Generate a quotable snippet for KATHA chat
+   * @param {string} reference - Content reference
+   * @param {Object} options - Quote options
+   * @returns {Promise<Object>} Quote object for KATHA
+   */
+  async generateChatQuote(reference, options = {}) {
+    if (!this.capabilities.has(CONTENT_CAPABILITIES.CHAT_QUOTE)) {
+      throw new Error('Adapter does not support chat quotes');
+    }
+    
+    const result = await this.lookupReference(reference);
+    if (!result) {
+      return null;
+    }
+    
+    this.stats.chatQuotes++;
+    
+    return {
+      type: 'content-quote',
+      adapter: this.id,
+      reference,
+      text: result.text,
+      metadata: {
+        source: this.name,
+        contentId: result.contentId,
+        position: result.position,
+      },
+      // Security: Sign the quote so it can be verified
+      verified: true,
+    };
+  }
+  
+  /**
+   * Register content with DARSHAN for streaming
+   * @param {string} id - Content ID
+   * @param {Object} options - Registration options
+   */
+  async registerWithDarshan(id, options = {}) {
+    if (!this.darshan) {
+      throw new Error('DARSHAN instance not configured');
+    }
+    
+    const meta = this.catalog.get(id);
+    if (!meta) {
+      throw new Error('Content not found: ' + id);
+    }
+    
+    // Register as a DARSHAN content source
+    await this.darshan.registerContent(id, {
+      title: meta.title,
+      type: meta.contentType,
+      size: meta.size,
+      getStream: () => this.getContentStream(id),
+      allowDownload: options.allowDownload || false,
+      // DARSHAN handles view-not-copy enforcement
+    });
+    
+    this.emit('content-registered', { id, meta });
+  }
+  
+  /**
+   * Validate declared capabilities
+   * @private
+   */
+  _validateCapabilities() {
+    const validCaps = new Set(Object.values(CONTENT_CAPABILITIES));
+    for (const cap of this.capabilities) {
+      if (!validCaps.has(cap)) {
+        console.warn(\Unknown capability declared: \\);
+      }
+    }
+  }
+  
+  /**
+   * Check if adapter has a capability
+   * @param {string} capability - Capability to check
+   * @returns {boolean}
+   */
+  hasCapability(capability) {
+    return this.capabilities.has(capability);
+  }
+  
+  /**
+   * Get adapter statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      name: this.name,
+      id: this.id,
+      capabilities: Array.from(this.capabilities),
+      catalogSize: this.catalog.size,
+    };
+  }
+}
+
+export default ContentAdapter;

package/content/api.js

@@ -2,10 +2,14 @@
  * YAKMESH™ Public Content API
  * HTTP endpoints for public content delivery
  * 
+ * Content integrity = SHA3-256 hash match.
+ * Content authorship = publisher ML-DSA-65 signature.
+ * No voting, no quorum, no consensus proofs.
+ * 
  * Public (no auth required):
  * - GET /content/:hash - Fetch content by hash
  * - GET /content/:hash/meta - Fetch metadata only
- * - GET /content/:hash/proof - Fetch consensus proof
+ * - GET /content/:hash/integrity - Fetch integrity info (hash + publisher sig)
  * - GET /content/list - List available content
  * 
  * Authenticated (rate limited):
@@ -18,18 +22,19 @@
  */
 
 import { Router } from 'express';
-import { ContentStore, ContentType, ContentStatus, computeContentHash } from './store.js';
+import { ContentStore, ContentType, ContentStatus, computeContentHash, isTritAddress } from './store.js';
 
 /**
  * Create content API router
  */
 export function createContentAPI(contentStore, options = {}) {
   const router = Router();
-  
+
   const {
     writeLimiter,
     readLimiter,
     validateString,
+    requirePeerAuth,
   } = options;
 
   // =========================================
@@ -38,22 +43,20 @@ export function createContentAPI(contentStore, options = {}) {
 
   /**
    * GET /content/:hash
-   * Fetch content by hash with optional proof
+   * Fetch content by hash
    * 
    * Query params:
-   * - proof=1 : Include consensus proof in response headers
    * - download=1 : Force download (Content-Disposition)
    */
   router.get('/:hash', readLimiter, (req, res) => {
     const { hash } = req.params;
-    const includeProof = req.query.proof === '1';
     const download = req.query.download === '1';
 
     // Get content with metadata
     const result = contentStore.getWithProof(hash);
-    
+
     if (!result) {
-      return res.status(404).json({ 
+      return res.status(404).json({
         error: 'Content not found',
         hash,
         hint: 'Content may not have synced yet. Try again later.',
@@ -64,19 +67,22 @@ export function createContentAPI(contentStore, options = {}) {
     res.setHeader('Content-Type', result.meta?.contentType || 'application/octet-stream');
     res.setHeader('Content-Length', result.meta?.size || result.content.length);
     res.setHeader('X-Content-Hash', result.hash);
+    res.setHeader('X-Content-Hash-144T', result.hash144t || result.meta?.hash144t || '');
     res.setHeader('X-Content-Status', result.meta?.status || 'unknown');
-    
-    // Cache headers (immutable content = cache forever)
+
+    // Cache headers (verified content = cache forever)
     if (result.verified) {
       res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+      res.setHeader('X-Verified', 'true');
     } else {
       res.setHeader('Cache-Control', 'public, max-age=60');
+      res.setHeader('X-Verified', 'false');
     }
 
-    // Include proof in headers if requested
-    if (includeProof && result.proof) {
-      res.setHeader('X-Consensus-Proof', JSON.stringify(result.proof));
-      res.setHeader('X-Verified', result.verified ? 'true' : 'false');
+    // Publisher signature header
+    if (result.meta?.publisherSignature) {
+      res.setHeader('X-Publisher-Signature', result.meta.publisherSignature);
+      res.setHeader('X-Published-By', result.meta.publishedBy || 'unknown');
     }
 
     // Download disposition
@@ -95,7 +101,7 @@ export function createContentAPI(contentStore, options = {}) {
   router.get('/:hash/meta', readLimiter, (req, res) => {
     const { hash } = req.params;
     const meta = contentStore.getMeta(hash);
-    
+
     if (!meta) {
       return res.status(404).json({ error: 'Content not found', hash });
     }
@@ -104,30 +110,31 @@ export function createContentAPI(contentStore, options = {}) {
   });
 
   /**
-   * GET /content/:hash/proof
-   * Fetch consensus proof for light client verification
+   * GET /content/:hash/integrity
+   * Fetch integrity info for content verification
+   * Returns hash, publisher identity, publisher signature, and verification status.
+   * Any client can independently verify: hash(content) === hash AND
+   * verify(hash, publisherSignature, publisherPubKey) === true.
    */
-  router.get('/:hash/proof', readLimiter, (req, res) => {
+  router.get('/:hash/integrity', readLimiter, (req, res) => {
     const { hash } = req.params;
     const meta = contentStore.getMeta(hash);
-    
+
     if (!meta) {
       return res.status(404).json({ error: 'Content not found', hash });
     }
 
-    if (!meta.consensusProof) {
-      return res.status(404).json({ 
-        error: 'No consensus proof yet',
-        hash,
-        status: meta.status,
-        hint: 'Content may still be pending consensus.',
-      });
-    }
-
     res.json({
-      hash,
+      hash: meta.hash,
+      hash144t: meta.hash144t,
+      ioName: meta.ioName,
       verified: meta.status === ContentStatus.VERIFIED,
-      proof: meta.consensusProof.toJSON ? meta.consensusProof.toJSON() : meta.consensusProof,
+      status: meta.status,
+      publishedBy: meta.publishedBy,
+      publisherSignature: meta.publisherSignature || null,
+      contentType: meta.contentType,
+      size: meta.size,
+      createdAt: meta.createdAt,
     });
   });
 
@@ -143,7 +150,7 @@ export function createContentAPI(contentStore, options = {}) {
    */
   router.get('/', readLimiter, (req, res) => {
     const { tag, status, limit = 100, offset = 0 } = req.query;
-    
+
     const items = contentStore.list({
       tag,
       status,
@@ -164,7 +171,7 @@ export function createContentAPI(contentStore, options = {}) {
    */
   router.head('/:hash', readLimiter, (req, res) => {
     const { hash } = req.params;
-    
+
     if (contentStore.has(hash)) {
       const meta = contentStore.getMeta(hash);
       res.setHeader('Content-Type', meta?.contentType || 'application/octet-stream');
@@ -199,7 +206,7 @@ export function createContentAPI(contentStore, options = {}) {
    * - name: optional name
    * - tags: comma-separated tags
    */
-  router.post('/publish', writeLimiter, async (req, res) => {
+  router.post('/publish', writeLimiter, requirePeerAuth, async (req, res) => {
     try {
       let content;
       let options = {};
@@ -216,7 +223,7 @@ export function createContentAPI(contentStore, options = {}) {
           tags: req.body.tags || [],
           ttl: req.body.ttl || 0,
         };
-      } 
+      }
       // Handle raw body
       else if (req.body && Buffer.isBuffer(req.body)) {
         content = req.body;
@@ -245,9 +252,11 @@ export function createContentAPI(contentStore, options = {}) {
       res.status(201).json({
         success: true,
         hash: result.hash,
+        hash144t: result.hash144t,
+        ioName: result.ioName,
         status: result.status,
         meta: result.meta?.toJSON ? result.meta.toJSON() : result.meta,
-        url: `/content/${result.hash}`,
+        url: `/content/${result.hash144t || result.hash}`,
       });
     } catch (error) {
       res.status(500).json({ error: error.message });
@@ -260,7 +269,7 @@ export function createContentAPI(contentStore, options = {}) {
    */
   router.post('/request', writeLimiter, async (req, res) => {
     const { hash } = req.body;
-    
+
     if (!hash) {
       return res.status(400).json({ error: 'Hash required' });
     }
@@ -277,7 +286,7 @@ export function createContentAPI(contentStore, options = {}) {
 
       // Request from mesh
       const result = await contentStore.request(hash);
-      
+
       res.json({
         found: true,
         local: false,
@@ -297,9 +306,9 @@ export function createContentAPI(contentStore, options = {}) {
    * DELETE /content/:hash
    * Remove content (local only - cannot remove from mesh)
    */
-  router.delete('/:hash', writeLimiter, (req, res) => {
+  router.delete('/:hash', writeLimiter, requirePeerAuth, (req, res) => {
     const { hash } = req.params;
-    
+
     if (!contentStore.has(hash)) {
       return res.status(404).json({ error: 'Content not found', hash });
     }
@@ -329,13 +338,13 @@ export function createContentAPI(contentStore, options = {}) {
    */
   router.post('/verify', readLimiter, (req, res) => {
     const content = req.body.content || req.body;
-    
+
     if (!content) {
       return res.status(400).json({ error: 'Content required' });
     }
 
     const hash = computeContentHash(content);
-    
+
     res.json({
       hash,
       exists: contentStore.has(hash),

package/content/index.js

@@ -1,6 +1,6 @@
 /**
  * YAKMESH™ Content Module
- * Content-addressed storage with public delivery
+ * Content-addressed storage with integrity verification
  * 
  * @module content
  * @license MIT
@@ -12,8 +12,8 @@ export {
   ContentType, 
   ContentStatus, 
   ContentMetadata,
-  ConsensusProof,
   computeContentHash,
+  deriveContentName,
 } from './store.js';
 
 export { createContentAPI } from './api.js';