verify --chain

jsr.json

···
 {
   "name": "@atscan/plcbundle-bun",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "license": "MIT",
   "exports": "./src/index.ts"
 }

package.json

···
 {
   "name": "@atscan/plcbundle-bun",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "description": "Bun library for working with DID PLC bundle archives (plcbundle)",
   "main": "./src/index.ts",

src/cmds/verify.ts

···
 
 OPTIONS:
   --dir <path>      Bundle directory (default: ./)
-  --bundle <num>    Bundle number to verify (required)
+  --bundle <num>    Bundle number to verify (required unless --chain is used)
+  --chain           Verify entire chain instead of single bundle
+  --start <num>     Start bundle for chain verification (default: 1)
+  --end <num>       End bundle for chain verification (default: last bundle)
+
+EXAMPLES:
+  plcbundle-bun verify --bundle 42
+  plcbundle-bun verify --chain
+  plcbundle-bun verify --chain --start 1 --end 100
     `);
     return;
   }
···
     options: {
       dir: { type: 'string', default: './' },
       bundle: { type: 'string' },
+      chain: { type: 'boolean', default: false },
+      start: { type: 'string' },
+      end: { type: 'string' },
     },
     strict: false,
   });
 
+  const dir = (values.dir as string) || './';
+  const bundleInstance = new PLCBundle(dir);
+  
+  // Chain verification
+  if (values.chain) {
+    const stats = await bundleInstance.getStats();
+    const start = values.start ? parseInt(values.start as string) : 1;
+    const end = values.end ? parseInt(values.end as string) : stats.lastBundle;
+    
+    console.log(`Verifying chain: bundles ${start}-${end}\n`);
+    
+    const startTime = Date.now();
+    
+    const result = await bundleInstance.verifyChain({
+      start,
+      end,
+      onProgress: (current, total) => {
+        process.stdout.write(`Verified ${current}/${total} bundles\r`);
+      },
+    });
+    
+    const elapsed = (Date.now() - startTime) / 1000;
+    
+    console.log('\n');
+    
+    if (result.valid) {
+      console.log(`✓ Chain verification passed`);
+      console.log(`  Verified bundles: ${result.validBundles}`);
+      console.log(`  Time elapsed:     ${elapsed.toFixed(2)}s`);
+    } else {
+      console.error(`✗ Chain verification failed`);
+      console.error(`  Valid bundles:   ${result.validBundles}`);
+      console.error(`  Invalid bundles: ${result.invalidBundles}`);
+      console.error('');
+      
+      result.errors.forEach(({ bundleNum, errors }) => {
+        console.error(`Bundle ${bundleNum}:`);
+        errors.forEach(e => console.error(`  - ${e}`));
+      });
+      
+      process.exit(1);
+    }
+    
+    return;
+  }
+  
+  // Single bundle verification
   if (!values.bundle || typeof values.bundle !== 'string') {
-    console.error('Error: --bundle is required');
+    console.error('Error: --bundle is required (or use --chain)');
     process.exit(1);
   }
   
-  const dir = (values.dir as string) || './';
   const num = parseInt(values.bundle);
-  const bundle = new PLCBundle(dir);
-  
-  const result = await bundle.verifyBundle(num);
+  const result = await bundleInstance.verifyBundle(num);
   
   if (result.valid) {
     console.log(`✓ Bundle ${num} is valid`);

src/index.ts

···
   ProcessOptions,
   CloneOptions,
   CloneStats,
+  ChainVerificationResult,
 } from './types';

src/plcbundle.ts

···
   ProcessOptions,
   ProcessStats,
   CloneOptions,
-  CloneStats
+  CloneStats,
+  ChainVerificationResult
 } from './types';
 
 /**
···
       updatedAt: index.updated_at,
     };
   }
+
+    /**
+   * Verify the integrity of the entire bundle chain.
+   * 
+   * This method validates:
+   * - Each bundle's compressed and content hashes
+   * - The chain hash linking each bundle to its parent
+   * - The continuity of the chain (no missing bundles)
+   * - The genesis bundle has correct initial hash
+   * 
+   * @param options - Verification options
+   * @param options.start - First bundle to verify (default: 1)
+   * @param options.end - Last bundle to verify (default: last available bundle)
+   * @param options.onProgress - Callback for progress updates
+   * @returns Promise resolving to chain verification result
+   * 
+   * @example Verify entire chain
+   * ```ts
+   * const result = await bundle.verifyChain();
+   * 
+   * if (result.valid) {
+   *   console.log(`✓ All ${result.totalBundles} bundles verified`);
+   * } else {
+   *   console.error(`✗ Chain invalid: ${result.invalidBundles} errors`);
+   *   result.errors.forEach(({ bundleNum, errors }) => {
+   *     console.error(`Bundle ${bundleNum}:`);
+   *     errors.forEach(e => console.error(`  - ${e}`));
+   *   });
+   * }
+   * ```
+   * 
+   * @example Verify range with progress
+   * ```ts
+   * const result = await bundle.verifyChain({
+   *   start: 1,
+   *   end: 100,
+   *   onProgress: (current, total) => {
+   *     console.log(`Verified ${current}/${total} bundles`);
+   *   }
+   * });
+   * ```
+   */
+  async verifyChain(options: {
+    start?: number;
+    end?: number;
+    onProgress?: (current: number, total: number) => void;
+  } = {}): Promise<ChainVerificationResult> {
+    const index = await this.loadIndex();
+    
+    const start = options.start || 1;
+    const end = options.end || index.last_bundle;
+    
+    // Validate range
+    if (start < 1 || end > index.last_bundle || start > end) {
+      throw new Error(`Invalid bundle range ${start}-${end} (available: 1-${index.last_bundle})`);
+    }
+    
+    const result: ChainVerificationResult = {
+      valid: true,
+      totalBundles: end - start + 1,
+      validBundles: 0,
+      invalidBundles: 0,
+      errors: [],
+    };
+    
+    let previousHash = '';
+    
+    for (let bundleNum = start; bundleNum <= end; bundleNum++) {
+      const metadata = index.bundles.find(b => b.bundle_number === bundleNum);
+      
+      if (!metadata) {
+        result.valid = false;
+        result.invalidBundles++;
+        result.errors.push({
+          bundleNum,
+          errors: ['Bundle missing from index'],
+        });
+        continue;
+      }
+      
+      const bundleErrors: string[] = [];
+      
+      // Verify bundle file hashes
+      const verification = await this.verifyBundle(bundleNum);
+      if (!verification.valid) {
+        bundleErrors.push(...verification.errors);
+      }
+      
+      // Verify chain linkage
+      if (bundleNum === 1) {
+        // Genesis bundle should have empty parent
+        if (metadata.parent !== '') {
+          bundleErrors.push(`Genesis bundle should have empty parent, got: ${metadata.parent}`);
+        }
+        
+        // Verify genesis hash format
+        const expectedHash = this.calculateChainHash('', metadata.content_hash, true);
+        if (metadata.hash !== expectedHash) {
+          bundleErrors.push(`Invalid genesis chain hash: ${metadata.hash} != ${expectedHash}`);
+        }
+      } else {
+        // Verify parent reference
+        if (metadata.parent !== previousHash) {
+          bundleErrors.push(`Parent hash mismatch: expected ${previousHash}, got ${metadata.parent}`);
+        }
+        
+        // Verify chain hash
+        const expectedHash = this.calculateChainHash(metadata.parent, metadata.content_hash, false);
+        if (metadata.hash !== expectedHash) {
+          bundleErrors.push(`Invalid chain hash: ${metadata.hash} != ${expectedHash}`);
+        }
+      }
+      
+      // Record results
+      if (bundleErrors.length > 0) {
+        result.valid = false;
+        result.invalidBundles++;
+        result.errors.push({
+          bundleNum,
+          errors: bundleErrors,
+        });
+      } else {
+        result.validBundles++;
+      }
+      
+      previousHash = metadata.hash;
+      
+      // Report progress
+      if (options.onProgress) {
+        options.onProgress(bundleNum - start + 1, result.totalBundles);
+      }
+    }
+    
+    return result;
+  }
+
 }

src/types.ts

···
   /** Bytes downloaded so far (including skipped bundles) */
   downloadedBytes: number;
 }
+
+/**
+ * Result of chain verification.
+ * 
+ * Contains overall validity status and detailed information about
+ * any issues found in the bundle chain.
+ */
+export interface ChainVerificationResult {
+  /** Whether the entire chain is valid */
+  valid: boolean;
+  
+  /** Total number of bundles verified */
+  totalBundles: number;
+  
+  /** Number of bundles that passed verification */
+  validBundles: number;
+  
+  /** Number of bundles that failed verification */
+  invalidBundles: number;
+  
+  /** Detailed errors for each invalid bundle */
+  errors: Array<{
+    bundleNum: number;
+    errors: string[];
+  }>;
+}