GRANTH ग्रन्थ

Self-contained, mathematically verified documentation that ships with every YAKMESH node.

Design Principles

Module Structure

yakmesh-node/
├── docs/                      # Documentation module
│   ├── index.js               # Module exports
│   ├── bundle.js              # Generated at build time
│   ├── verify.js              # Hash verification functions
│   ├── serve.js               # HTTP/yak:// serving integration
│   └── BUNDLE_HASH            # SHA3-256 of entire bundle
│
└── scripts/
    └── build-docs-bundle.js   # Build script (runs at npm build)

Verification Flow

┌─────────────────────────────────────────────────────────────┐
│                      BUILD TIME                              │
├─────────────────────────────────────────────────────────────┤
│  1. Read all files from website/docs/                        │
│  2. Compute SHA3-256 hash for each file                      │
│  3. Compute BUNDLE_HASH = SHA3-256(sorted file hashes)       │
│  4. Generate bundle.js with embedded content + hashes        │
│  5. Commit to release                                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      RUNTIME                                 │
├─────────────────────────────────────────────────────────────┤
│  1. Node starts                                              │
│  2. Optional: verifyDocsBundle() checks all hashes           │
│  3. Serve docs at yak://docs.yakmesh/ or /docs/              │
│  4. Each file served with X-Content-Hash header              │
│  5. Clients can independently verify                         │
└─────────────────────────────────────────────────────────────┘

The yak:// Protocol

Documentation is accessible via the native YAKMESH protocol:

yak://docs.yakmesh/                    → Documentation index
yak://docs.yakmesh/mandala             → MANDALA protocol docs
yak://docs.yakmesh/getting-started     → Getting started guide

When a node receives a request for yak://docs.yakmesh/mandala:

1. Looks up mandala.html in the hardcoded bundle
2. Verifies file hash matches (already trusted at install, optional re-check)
3. Serves content locally — zero network round-trip

Bundle Generation

Build Script: scripts/build-docs-bundle.js

/**
 * YAKMESH Documentation Bundle Generator
 * 
 * Reads website/docs/ and generates a hardcoded bundle
 * with SHA3-256 verification hashes.
 * 
 * Run: npm run build:docs
 */

import { sha3_256 } from '@noble/hashes/sha3';
import { bytesToHex } from '@noble/hashes/utils';
import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
import { join, relative, extname } from 'path';

const DOCS_SOURCE = './website/docs';
const BUNDLE_OUTPUT = './docs/bundle.js';

// Collect all files recursively
function collectFiles(dir, base = dir) {
  const files = [];
  for (const entry of readdirSync(dir)) {
    const path = join(dir, entry);
    if (statSync(path).isDirectory()) {
      files.push(...collectFiles(path, base));
    } else {
      files.push({
        path: relative(base, path).replace(/\\/g, '/'),
        content: readFileSync(path),
      });
    }
  }
  return files;
}

// Compute file hash
function hashFile(content) {
  return bytesToHex(sha3_256(content));
}

// Build the bundle
const files = collectFiles(DOCS_SOURCE);
const fileIndex = {};
const hashes = [];

for (const file of files) {
  const hash = hashFile(file.content);
  fileIndex[file.path] = {
    hash,
    size: file.content.length,
    contentType: getContentType(file.path),
  };
  hashes.push(hash);
}

// Bundle hash = hash of sorted individual hashes
hashes.sort();
const BUNDLE_HASH = bytesToHex(sha3_256(hashes.join('')));

// Generate bundle.js
const bundle = `// AUTO-GENERATED - DO NOT EDIT
// Generated: ${new Date().toISOString()}
// YAKMESH Documentation Bundle

export const BUNDLE_HASH = '${BUNDLE_HASH}';
export const BUNDLE_VERSION = '${process.env.npm_package_version || '0.0.0'}';
export const FILE_INDEX = ${JSON.stringify(fileIndex, null, 2)};

// File contents stored separately for efficiency
// (or embedded as base64 for single-file distribution)
`;

writeFileSync(BUNDLE_OUTPUT, bundle);
console.log(`✅ Bundle generated: ${BUNDLE_HASH}`);

Verification API

docs/verify.js

/**
 * Verify documentation bundle integrity
 */
import { sha3_256 } from '@noble/hashes/sha3';
import { bytesToHex } from '@noble/hashes/utils';
import { BUNDLE_HASH, FILE_INDEX } from './bundle.js';

/**
 * Verify a single file's content matches its hash
 */
export function verifyFile(path, content) {
  const expected = FILE_INDEX[path]?.hash;
  if (!expected) return { valid: false, error: 'File not in bundle' };
  
  const actual = bytesToHex(sha3_256(content));
  return {
    valid: actual === expected,
    expected,
    actual,
  };
}

/**
 * Verify entire bundle integrity
 * Returns true only if ALL files are verified
 */
export function verifyBundle(fileContents) {
  const hashes = [];
  
  for (const [path, meta] of Object.entries(FILE_INDEX)) {
    const content = fileContents[path];
    if (!content) return { valid: false, error: `Missing: ${path}` };
    
    const result = verifyFile(path, content);
    if (!result.valid) return { valid: false, error: `Tampered: ${path}` };
    
    hashes.push(result.actual);
  }
  
  // Verify bundle hash
  hashes.sort();
  const computedBundle = bytesToHex(sha3_256(hashes.join('')));
  
  return {
    valid: computedBundle === BUNDLE_HASH,
    bundleHash: BUNDLE_HASH,
    computed: computedBundle,
  };
}

/**
 * Get bundle info without verification
 */
export function getBundleInfo() {
  return {
    hash: BUNDLE_HASH,
    fileCount: Object.keys(FILE_INDEX).length,
    files: Object.keys(FILE_INDEX),
  };
}

Serving Integration

docs/serve.js

/**
 * Serve hardcoded documentation via HTTP or yak://
 */
import { Router } from 'express';
import { FILE_INDEX, BUNDLE_HASH } from './bundle.js';
import { readFileSync } from 'fs';
import { join } from 'path';

const DOCS_DIR = join(__dirname, '../../website/docs');

/**
 * Create Express router for /docs/
 */
export function createDocsRouter() {
  const router = Router();

  // Serve index
  router.get('/', (req, res) => {
    res.redirect('/docs/index.html');
  });

  // Serve any doc file
  router.get('/:file', (req, res) => {
    const file = req.params.file;
    const meta = FILE_INDEX[file];
    
    if (!meta) {
      return res.status(404).json({ 
        error: 'Documentation file not found',
        available: Object.keys(FILE_INDEX).filter(f => f.endsWith('.html')),
      });
    }

    // Read from embedded bundle (production) or disk (development)
    const content = readFileSync(join(DOCS_DIR, file));
    
    res.setHeader('Content-Type', meta.contentType);
    res.setHeader('X-Content-Hash', meta.hash);
    res.setHeader('X-Bundle-Hash', BUNDLE_HASH);
    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
    
    res.send(content);
  });

  // Bundle info endpoint
  router.get('/_bundle', (req, res) => {
    res.json({
      hash: BUNDLE_HASH,
      fileCount: Object.keys(FILE_INDEX).length,
      files: FILE_INDEX,
    });
  });

  return router;
}

Usage

Building the Bundle

# Generate docs bundle before release
npm run build:docs

# Full build (includes docs)
npm run build

Accessing Documentation

# Via HTTP (when webserver enabled)
http://localhost:8080/docs/
http://localhost:8080/docs/mandala.html

# Via yak:// protocol
yak://docs.yakmesh/
yak://docs.yakmesh/mandala

# Programmatic access
import { getBundleInfo, verifyBundle } from 'yakmesh/docs';

const info = getBundleInfo();
console.log(`Docs bundle: ${info.hash}`);
console.log(`Files: ${info.fileCount}`);

Security Model

• Immutability: Docs cannot be modified without changing the bundle hash
• No Network Trust: Verification is local, mathematical, instant
• Tamper Detection: Any modification fails hash verification
• Release Binding: Docs version matches software version
• No Propagation: Docs don't spread via gossip — prevents poisoning attacks