@originals/sdk 1.8.0 → 1.8.2

package/src/cel/cli/create.ts

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+/**
+ * CLI Create Command
+ * 
+ * Creates a new CEL asset with an initial event.
+ * Generates Ed25519 key pair if --key not provided.
+ * 
+ * Usage: originals-cel create --name <name> --file <path> [options]
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { DataIntegrityProof } from '../types';
+import { PeerCelManager, CelSigner } from '../layers/PeerCelManager';
+import { createExternalReference } from '../ExternalReferenceManager';
+import { serializeEventLogJson } from '../serialization/json';
+import { serializeEventLogCbor } from '../serialization/cbor';
+import { multikey } from '../../crypto/Multikey';
+
+/**
+ * Flags parsed from command line arguments
+ */
+export interface CreateFlags {
+  name?: string;
+  file?: string;
+  key?: string;
+  output?: string;
+  format?: string;
+  help?: boolean;
+  h?: boolean;
+}
+
+/**
+ * Result of the create command
+ */
+export interface CreateResult {
+  success: boolean;
+  message: string;
+  log?: unknown;
+  keyGenerated?: boolean;
+  privateKey?: string;
+  publicKey?: string;
+}
+
+/**
+ * Lookup table for common file extensions to MIME types
+ */
+const MIME_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.json': 'application/json',
+  '.txt': 'text/plain',
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.mp3': 'audio/mpeg',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.zip': 'application/zip',
+  '.bin': 'application/octet-stream',
+};
+
+/**
+ * Gets MIME type from file extension
+ */
+function getMimeType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+/**
+ * Generates an Ed25519 key pair for signing
+ */
+async function generateKeyPair(): Promise<{ privateKey: string; publicKey: string }> {
+  const ed25519 = await import('@noble/ed25519');
+  const privateKeyBytes = ed25519.utils.randomPrivateKey();
+  const publicKeyBytes = await (ed25519 as any).getPublicKeyAsync(privateKeyBytes);
+  
+  return {
+    privateKey: multikey.encodePrivateKey(privateKeyBytes as Uint8Array, 'Ed25519'),
+    publicKey: multikey.encodePublicKey(publicKeyBytes as Uint8Array, 'Ed25519'),
+  };
+}
+
+/**
+ * Loads an Ed25519 private key from a file
+ * Supports both raw multibase format and JSON format { privateKey: "z..." }
+ */
+async function loadPrivateKey(keyPath: string): Promise<{ privateKey: string; publicKey: string }> {
+  if (!fs.existsSync(keyPath)) {
+    throw new Error(`Key file not found: ${keyPath}`);
+  }
+  
+  const content = fs.readFileSync(keyPath, 'utf-8').trim();
+  
+  let privateKey: string;
+  
+  // Try parsing as JSON first
+  try {
+    const parsed = JSON.parse(content);
+    if (parsed.privateKey) {
+      privateKey = parsed.privateKey;
+    } else {
+      throw new Error('JSON key file must contain "privateKey" field');
+    }
+  } catch (e) {
+    // Not JSON, treat as raw multibase key
+    if (content.startsWith('z')) {
+      privateKey = content;
+    } else {
+      throw new Error('Key file must contain a z-base58btc multibase-encoded Ed25519 private key');
+    }
+  }
+  
+  // Validate and decode to get public key
+  const decoded = multikey.decodePrivateKey(privateKey);
+  if (decoded.type !== 'Ed25519') {
+    throw new Error(`Expected Ed25519 key, got ${decoded.type}`);
+  }
+  
+  // Derive public key from private key
+  const ed25519 = await import('@noble/ed25519');
+  const publicKeyBytes = await (ed25519 as any).getPublicKeyAsync(decoded.key);
+  const publicKey = multikey.encodePublicKey(publicKeyBytes as Uint8Array, 'Ed25519');
+  
+  return { privateKey, publicKey };
+}
+
+/**
+ * Creates a signer function from a private key
+ */
+function createSigner(privateKey: string, publicKey: string): CelSigner {
+  return async (data: unknown): Promise<DataIntegrityProof> => {
+    const ed25519 = await import('@noble/ed25519');
+    const decoded = multikey.decodePrivateKey(privateKey);
+    
+    // Serialize data for signing (deterministic JSON)
+    const dataStr = JSON.stringify(data, Object.keys(data as object).sort());
+    const dataBytes = new TextEncoder().encode(dataStr);
+    
+    // Sign the data
+    const signature = await (ed25519 as any).signAsync(dataBytes, decoded.key);
+    const proofValue = multikey.encodeMultibase(new Uint8Array(signature));
+    
+    return {
+      type: 'DataIntegrityProof',
+      cryptosuite: 'eddsa-jcs-2022',
+      created: new Date().toISOString(),
+      verificationMethod: `did:key:${publicKey}#${publicKey}`,
+      proofPurpose: 'assertionMethod',
+      proofValue,
+    };
+  };
+}
+
+/**
+ * Execute the create command
+ */
+export async function createCommand(flags: CreateFlags): Promise<CreateResult> {
+  // Check for help flag
+  if (flags.help || flags.h) {
+    return {
+      success: true,
+      message: 'Use --help with the main CLI for full help text',
+    };
+  }
+  
+  // Validate required arguments
+  if (!flags.name) {
+    return {
+      success: false,
+      message: 'Error: --name is required. Usage: originals-cel create --name <name> --file <path>',
+    };
+  }
+  
+  if (!flags.file) {
+    return {
+      success: false,
+      message: 'Error: --file is required. Usage: originals-cel create --name <name> --file <path>',
+    };
+  }
+  
+  // Validate format flag
+  const format = (flags.format || 'json').toLowerCase();
+  if (format !== 'json' && format !== 'cbor') {
+    return {
+      success: false,
+      message: 'Error: --format must be "json" or "cbor"',
+    };
+  }
+  
+  // Check if file exists
+  if (!fs.existsSync(flags.file)) {
+    return {
+      success: false,
+      message: `Error: File not found: ${flags.file}`,
+    };
+  }
+  
+  // Read file content
+  let fileContent: Uint8Array;
+  try {
+    fileContent = new Uint8Array(fs.readFileSync(flags.file));
+  } catch (e) {
+    return {
+      success: false,
+      message: `Error: Failed to read file: ${(e as Error).message}`,
+    };
+  }
+  
+  // Get or generate key pair
+  let privateKey: string;
+  let publicKey: string;
+  let keyGenerated = false;
+  
+  if (flags.key) {
+    try {
+      const loaded = await loadPrivateKey(flags.key);
+      privateKey = loaded.privateKey;
+      publicKey = loaded.publicKey;
+    } catch (e) {
+      return {
+        success: false,
+        message: `Error: Failed to load key: ${(e as Error).message}`,
+      };
+    }
+  } else {
+    // Generate new key pair
+    const generated = await generateKeyPair();
+    privateKey = generated.privateKey;
+    publicKey = generated.publicKey;
+    keyGenerated = true;
+  }
+  
+  // Create signer
+  const signer = createSigner(privateKey, publicKey);
+  
+  // Determine media type from file extension
+  const mediaType = getMimeType(flags.file);
+  
+  // Create external reference for the file
+  const resource = createExternalReference(fileContent, mediaType);
+  
+  // Create PeerCelManager and create the asset
+  const manager = new PeerCelManager(signer, {
+    verificationMethod: `did:key:${publicKey}#${publicKey}`,
+    proofPurpose: 'assertionMethod',
+  });
+  
+  let eventLog;
+  try {
+    eventLog = await manager.create(flags.name, [resource]);
+  } catch (e) {
+    return {
+      success: false,
+      message: `Error: Failed to create asset: ${(e as Error).message}`,
+    };
+  }
+  
+  // Serialize output
+  let output: string | Uint8Array;
+  try {
+    if (format === 'cbor') {
+      output = serializeEventLogCbor(eventLog);
+    } else {
+      output = serializeEventLogJson(eventLog);
+    }
+  } catch (e) {
+    return {
+      success: false,
+      message: `Error: Failed to serialize event log: ${(e as Error).message}`,
+    };
+  }
+  
+  // Write output
+  if (flags.output) {
+    try {
+      if (format === 'cbor') {
+        fs.writeFileSync(flags.output, output as Uint8Array);
+      } else {
+        fs.writeFileSync(flags.output, output as string, 'utf-8');
+      }
+    } catch (e) {
+      return {
+        success: false,
+        message: `Error: Failed to write output file: ${(e as Error).message}`,
+      };
+    }
+  } else {
+    // Write to stdout
+    if (format === 'cbor') {
+      // For CBOR, output as base64 to stdout since it's binary
+      const base64 = Buffer.from(output as Uint8Array).toString('base64');
+      process.stdout.write(base64);
+    } else {
+      process.stdout.write(output as string);
+    }
+  }
+  
+  // Build result
+  const result: CreateResult = {
+    success: true,
+    message: flags.output
+      ? `Created CEL asset "${flags.name}" and saved to ${flags.output}`
+      : `Created CEL asset "${flags.name}"`,
+    log: eventLog,
+    keyGenerated,
+  };
+  
+  // Include key info if generated
+  if (keyGenerated) {
+    result.privateKey = privateKey;
+    result.publicKey = publicKey;
+    
+    // Print key info to stderr so it doesn't mix with JSON output
+    console.error(`\n⚠️  New Ed25519 key pair generated. Save these keys securely!`);
+    console.error(`Private Key: ${privateKey}`);
+    console.error(`Public Key:  ${publicKey}`);
+    console.error(`\nTo reuse this key, save it to a file and use --key <path>\n`);
+  }
+  
+  return result;
+}

package/src/cel/cli/index.ts

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+/**
+ * Originals CEL CLI
+ *
+ * Command-line interface for working with CEL (Cryptographic Event Log) assets.
+ * Part of the Originals Protocol SDK.
+ */
+
+import { createCommand, CreateFlags } from './create';
+import { verifyCommand, VerifyFlags } from './verify';
+import { inspectCommand, InspectFlags } from './inspect';
+import { migrateCommand, MigrateFlags } from './migrate';
+
+// Version from package.json - will be replaced at build time or read dynamically
+const VERSION = '1.5.0';
+
+const HELP_TEXT = `
+originals-cel - Cryptographic Event Log CLI for Originals Protocol
+
+USAGE:
+  originals-cel <command> [options]
+
+COMMANDS:
+  create    Create a new CEL asset with an initial event
+  verify    Verify an existing CEL event log
+  inspect   Inspect a CEL log in human-readable format
+  migrate   Migrate a CEL asset between layers (peer → webvh → btco)
+
+GLOBAL OPTIONS:
+  --help, -h       Show help for a command
+  --version, -v    Show version number
+
+EXAMPLES:
+  originals-cel create --name "My Asset" --file ./image.png
+  originals-cel verify --log ./asset.cel.json
+  originals-cel inspect --log ./asset.cel.json
+  originals-cel migrate --log ./asset.cel.json --to webvh --domain example.com
+
+For more information on a specific command:
+  originals-cel <command> --help
+`;
+
+const CREATE_HELP = `
+originals-cel create - Create a new CEL asset
+
+USAGE:
+  originals-cel create --name <name> --file <path> [options]
+
+REQUIRED:
+  --name <name>        Name of the asset
+  --file <path>        Path to the content file
+
+OPTIONS:
+  --key <path>         Path to Ed25519 private key (generates new if not provided)
+  --output <path>      Output file path (stdout if not provided)
+  --format <type>      Output format: json (default) or cbor
+  --help, -h           Show this help message
+
+EXAMPLES:
+  originals-cel create --name "My Art" --file ./artwork.png
+  originals-cel create --name "Document" --file ./doc.pdf --output ./doc.cel.json
+  originals-cel create --name "Asset" --file ./data.bin --format cbor --output ./asset.cel.cbor
+`;
+
+const VERIFY_HELP = `
+originals-cel verify - Verify a CEL event log
+
+USAGE:
+  originals-cel verify --log <path> [options]
+
+REQUIRED:
+  --log <path>         Path to the CEL event log file (.cel.json or .cel.cbor)
+
+OPTIONS:
+  --help, -h           Show this help message
+
+OUTPUT:
+  Displays verification result with event-by-event breakdown.
+  Shows witness attestations if present.
+  Exit code 0 on success, 1 on verification failure.
+
+EXAMPLES:
+  originals-cel verify --log ./asset.cel.json
+  originals-cel verify --log ./asset.cel.cbor
+`;
+
+const INSPECT_HELP = `
+originals-cel inspect - Inspect a CEL log in human-readable format
+
+USAGE:
+  originals-cel inspect --log <path> [options]
+
+REQUIRED:
+  --log <path>         Path to the CEL event log file
+
+OPTIONS:
+  --help, -h           Show this help message
+
+OUTPUT:
+  Pretty-prints event timeline with timestamps.
+  Shows current state derived from events.
+  Lists witnesses and attestation times.
+  Shows layer history if migrations are present.
+
+EXAMPLES:
+  originals-cel inspect --log ./asset.cel.json
+`;
+
+const MIGRATE_HELP = `
+originals-cel migrate - Migrate a CEL asset between layers
+
+USAGE:
+  originals-cel migrate --log <path> --to <layer> [options]
+
+REQUIRED:
+  --log <path>         Path to the CEL event log file
+  --to <layer>         Target layer: webvh or btco
+
+OPTIONS:
+  --domain <domain>    Domain for webvh layer (required for --to webvh)
+  --wallet <path>      Path to Bitcoin wallet key (required for --to btco)
+  --output <path>      Output file path (stdout if not provided)
+  --help, -h           Show this help message
+
+MIGRATION PATHS:
+  peer → webvh         Requires --domain
+  webvh → btco         Requires --wallet
+
+EXAMPLES:
+  originals-cel migrate --log ./asset.cel.json --to webvh --domain example.com
+  originals-cel migrate --log ./asset.cel.json --to btco --wallet ./wallet.key
+  originals-cel migrate --log ./asset.cel.json --to webvh --domain example.com --output ./migrated.cel.json
+`;
+
+/**
+ * Parse command line arguments into a structured object
+ */
+function parseArgs(args: string[]): {
+  command: string | null;
+  flags: Record<string, string | boolean>;
+} {
+  const flags: Record<string, string | boolean> = {};
+  let command: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+
+      // Check if next arg exists and doesn't start with --
+      if (nextArg && !nextArg.startsWith('-')) {
+        flags[key] = nextArg;
+        i++; // Skip the value
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith('-')) {
+      const key = arg.slice(1);
+      flags[key] = true;
+    } else if (!command) {
+      command = arg;
+    }
+  }
+
+  return { command, flags };
+}
+
+/**
+ * Print message to stdout
+ */
+function print(message: string): void {
+  console.log(message);
+}
+
+/**
+ * Print error message to stderr and exit
+ */
+function error(message: string, exitCode = 1): never {
+  console.error(`Error: ${message}`);
+  process.exit(exitCode);
+}
+
+/**
+ * Show help for a specific command
+ */
+function showCommandHelp(command: string): void {
+  switch (command) {
+    case 'create':
+      print(CREATE_HELP);
+      break;
+    case 'verify':
+      print(VERIFY_HELP);
+      break;
+    case 'inspect':
+      print(INSPECT_HELP);
+      break;
+    case 'migrate':
+      print(MIGRATE_HELP);
+      break;
+    default:
+      error(`Unknown command: ${command}`);
+  }
+}
+
+/**
+ * Run the create command asynchronously
+ */
+async function runCreateCommand(flags: Record<string, string | boolean>): Promise<void> {
+  try {
+    const createFlags: CreateFlags = {
+      name: typeof flags.name === 'string' ? flags.name : undefined,
+      file: typeof flags.file === 'string' ? flags.file : undefined,
+      key: typeof flags.key === 'string' ? flags.key : undefined,
+      output: typeof flags.output === 'string' ? flags.output : undefined,
+      format: typeof flags.format === 'string' ? flags.format : undefined,
+      help: flags.help === true,
+      h: flags.h === true,
+    };
+    
+    const result = await createCommand(createFlags);
+    
+    if (!result.success) {
+      error(result.message.replace('Error: ', ''));
+    }
+  } catch (e) {
+    error((e as Error).message);
+  }
+}
+
+/**
+ * Run the verify command asynchronously
+ */
+async function runVerifyCommand(flags: Record<string, string | boolean>): Promise<void> {
+  try {
+    const verifyFlags: VerifyFlags = {
+      log: typeof flags.log === 'string' ? flags.log : undefined,
+      help: flags.help === true,
+      h: flags.h === true,
+    };
+    
+    const result = await verifyCommand(verifyFlags);
+    
+    if (!result.success) {
+      error(result.message.replace('Error: ', ''));
+    }
+    
+    // Exit with appropriate code based on verification result
+    if (result.verified === false) {
+      process.exit(1);
+    }
+  } catch (e) {
+    error((e as Error).message);
+  }
+}
+
+/**
+ * Run the inspect command asynchronously
+ */
+async function runInspectCommand(flags: Record<string, string | boolean>): Promise<void> {
+  try {
+    const inspectFlags: InspectFlags = {
+      log: typeof flags.log === 'string' ? flags.log : undefined,
+      help: flags.help === true,
+      h: flags.h === true,
+    };
+    
+    const result = await inspectCommand(inspectFlags);
+    
+    if (!result.success) {
+      error(result.message.replace('Error: ', ''));
+    }
+  } catch (e) {
+    error((e as Error).message);
+  }
+}
+
+/**
+ * Run the migrate command asynchronously
+ */
+async function runMigrateCommand(flags: Record<string, string | boolean>): Promise<void> {
+  try {
+    const migrateFlags: MigrateFlags = {
+      log: typeof flags.log === 'string' ? flags.log : undefined,
+      to: typeof flags.to === 'string' ? flags.to : undefined,
+      domain: typeof flags.domain === 'string' ? flags.domain : undefined,
+      wallet: typeof flags.wallet === 'string' ? flags.wallet : undefined,
+      output: typeof flags.output === 'string' ? flags.output : undefined,
+      format: typeof flags.format === 'string' ? flags.format : undefined,
+      help: flags.help === true,
+      h: flags.h === true,
+    };
+    
+    const result = await migrateCommand(migrateFlags);
+    
+    if (!result.success) {
+      error(result.message.replace('Error: ', ''));
+    }
+  } catch (e) {
+    error((e as Error).message);
+  }
+}
+
+/**
+ * Main CLI entry point
+ */
+export function main(args: string[] = process.argv.slice(2)): void {
+  const { command, flags } = parseArgs(args);
+
+  // Handle --version / -v
+  if (flags.version || flags.v) {
+    print(`originals-cel v${VERSION}`);
+    return;
+  }
+
+  // Handle --help / -h without command
+  if (!command || flags.help || flags.h) {
+    if (command && command !== 'help') {
+      showCommandHelp(command);
+    } else {
+      print(HELP_TEXT);
+    }
+    return;
+  }
+
+  // Route to subcommands
+  switch (command) {
+    case 'create':
+      if (flags.help || flags.h) {
+        print(CREATE_HELP);
+        return;
+      }
+      // Run create command asynchronously
+      runCreateCommand(flags);
+      return;
+
+    case 'verify':
+      if (flags.help || flags.h) {
+        print(VERIFY_HELP);
+        return;
+      }
+      // Run verify command asynchronously
+      runVerifyCommand(flags);
+      return;
+
+    case 'inspect':
+      if (flags.help || flags.h) {
+        print(INSPECT_HELP);
+        return;
+      }
+      // Run inspect command asynchronously
+      runInspectCommand(flags);
+      return;
+
+    case 'migrate':
+      if (flags.help || flags.h) {
+        print(MIGRATE_HELP);
+        return;
+      }
+      // Run migrate command asynchronously
+      runMigrateCommand(flags);
+      return;
+
+    case 'help':
+      // Handle "originals-cel help <command>"
+      const helpTarget = args[1];
+      if (helpTarget && !helpTarget.startsWith('-')) {
+        showCommandHelp(helpTarget);
+      } else {
+        print(HELP_TEXT);
+      }
+      break;
+
+    default:
+      error(`Unknown command: ${command}\n\nRun 'originals-cel --help' for usage.`);
+  }
+}
+
+// Run if executed directly
+if (typeof process !== 'undefined' && process.argv[1]?.includes('cli')) {
+  main();
+}