@originals/sdk 1.8.0 → 1.8.2

package/src/cel/serialization/json.ts

@@ -0,0 +1,209 @@
+/**
+ * JSON Serialization for CEL Event Logs
+ * 
+ * Provides serialization and parsing of EventLog objects to/from JSON format.
+ * Uses deterministic key ordering for consistent hashes.
+ */
+
+import type { EventLog, LogEntry, DataIntegrityProof, WitnessProof } from '../types';
+
+/**
+ * Sort object keys recursively for deterministic JSON output.
+ * This ensures consistent serialization for hash computations.
+ */
+function sortKeys(obj: unknown): unknown {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+  
+  if (Array.isArray(obj)) {
+    return obj.map(sortKeys);
+  }
+  
+  if (typeof obj === 'object') {
+    const sorted: Record<string, unknown> = {};
+    const keys = Object.keys(obj as Record<string, unknown>).sort();
+    for (const key of keys) {
+      sorted[key] = sortKeys((obj as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  
+  return obj;
+}
+
+/**
+ * Serialize an EventLog to JSON string.
+ * 
+ * Uses deterministic key ordering for consistent output.
+ * 
+ * @param log - The EventLog to serialize
+ * @returns JSON string representation of the EventLog
+ * @throws Error if log is null or undefined
+ * 
+ * @example
+ * ```typescript
+ * const log = await createEventLog(data, options);
+ * const json = serializeEventLogJson(log);
+ * console.log(json); // '{"events":[...]}'
+ * ```
+ */
+export function serializeEventLogJson(log: EventLog): string {
+  if (!log) {
+    throw new Error('Cannot serialize null or undefined EventLog');
+  }
+  
+  const sorted = sortKeys(log);
+  return JSON.stringify(sorted, null, 2);
+}
+
+/**
+ * Check if a proof object is a WitnessProof (has witnessedAt field)
+ */
+function isWitnessProof(proof: DataIntegrityProof | WitnessProof): proof is WitnessProof {
+  return 'witnessedAt' in proof && typeof (proof as WitnessProof).witnessedAt === 'string';
+}
+
+/**
+ * Validate and reconstruct a DataIntegrityProof or WitnessProof
+ */
+function parseProof(proof: unknown): DataIntegrityProof | WitnessProof {
+  if (!proof || typeof proof !== 'object') {
+    throw new Error('Invalid proof: must be an object');
+  }
+  
+  const p = proof as Record<string, unknown>;
+  
+  // Validate required DataIntegrityProof fields
+  if (typeof p.type !== 'string') {
+    throw new Error('Invalid proof: missing or invalid type');
+  }
+  if (typeof p.cryptosuite !== 'string') {
+    throw new Error('Invalid proof: missing or invalid cryptosuite');
+  }
+  if (typeof p.created !== 'string') {
+    throw new Error('Invalid proof: missing or invalid created');
+  }
+  if (typeof p.verificationMethod !== 'string') {
+    throw new Error('Invalid proof: missing or invalid verificationMethod');
+  }
+  if (typeof p.proofPurpose !== 'string') {
+    throw new Error('Invalid proof: missing or invalid proofPurpose');
+  }
+  if (typeof p.proofValue !== 'string') {
+    throw new Error('Invalid proof: missing or invalid proofValue');
+  }
+  
+  const baseProof: DataIntegrityProof = {
+    type: p.type,
+    cryptosuite: p.cryptosuite,
+    created: p.created,
+    verificationMethod: p.verificationMethod,
+    proofPurpose: p.proofPurpose,
+    proofValue: p.proofValue,
+  };
+  
+  // Check for WitnessProof
+  if ('witnessedAt' in p) {
+    if (typeof p.witnessedAt !== 'string') {
+      throw new Error('Invalid witness proof: witnessedAt must be a string');
+    }
+    return {
+      ...baseProof,
+      witnessedAt: p.witnessedAt,
+    } as WitnessProof;
+  }
+  
+  return baseProof;
+}
+
+/**
+ * Validate and reconstruct a LogEntry
+ */
+function parseEntry(entry: unknown): LogEntry {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('Invalid entry: must be an object');
+  }
+  
+  const e = entry as Record<string, unknown>;
+  
+  // Validate type
+  if (e.type !== 'create' && e.type !== 'update' && e.type !== 'deactivate') {
+    throw new Error(`Invalid entry type: ${e.type}`);
+  }
+  
+  // Validate proof array
+  if (!Array.isArray(e.proof)) {
+    throw new Error('Invalid entry: proof must be an array');
+  }
+  
+  const parsedEntry: LogEntry = {
+    type: e.type,
+    data: e.data,
+    proof: e.proof.map(parseProof),
+  };
+  
+  // Optional previousEvent
+  if (e.previousEvent !== undefined) {
+    if (typeof e.previousEvent !== 'string') {
+      throw new Error('Invalid entry: previousEvent must be a string');
+    }
+    parsedEntry.previousEvent = e.previousEvent;
+  }
+  
+  return parsedEntry;
+}
+
+/**
+ * Parse a JSON string into an EventLog.
+ * 
+ * Validates the structure and types of the parsed object.
+ * 
+ * @param json - JSON string to parse
+ * @returns Parsed and validated EventLog
+ * @throws Error if JSON is invalid or doesn't match EventLog structure
+ * 
+ * @example
+ * ```typescript
+ * const json = '{"events":[...]}';
+ * const log = parseEventLogJson(json);
+ * console.log(log.events.length);
+ * ```
+ */
+export function parseEventLogJson(json: string): EventLog {
+  if (!json || typeof json !== 'string') {
+    throw new Error('Cannot parse null, undefined, or non-string value');
+  }
+  
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (e) {
+    throw new Error(`Invalid JSON: ${(e as Error).message}`);
+  }
+  
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Invalid EventLog: must be an object');
+  }
+  
+  const obj = parsed as Record<string, unknown>;
+  
+  // Validate events array
+  if (!Array.isArray(obj.events)) {
+    throw new Error('Invalid EventLog: events must be an array');
+  }
+  
+  const eventLog: EventLog = {
+    events: obj.events.map(parseEntry),
+  };
+  
+  // Optional previousLog
+  if (obj.previousLog !== undefined) {
+    if (typeof obj.previousLog !== 'string') {
+      throw new Error('Invalid EventLog: previousLog must be a string');
+    }
+    eventLog.previousLog = obj.previousLog;
+  }
+  
+  return eventLog;
+}

package/src/cel/types.ts

@@ -0,0 +1,160 @@
+/**
+ * CEL (Cryptographic Event Log) Types
+ * 
+ * Based on W3C CCG CEL Specification v0.1
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+
+/**
+ * Data Integrity Proof as defined in W3C Data Integrity spec
+ * Used for signing events and witness attestations
+ */
+export interface DataIntegrityProof {
+  /** The type of proof (e.g., "DataIntegrityProof") */
+  type: string;
+  /** The cryptosuite used (e.g., "eddsa-jcs-2022") */
+  cryptosuite: string;
+  /** ISO 8601 timestamp when the proof was created */
+  created: string;
+  /** DID URL of the verification method used to create the proof */
+  verificationMethod: string;
+  /** The purpose of the proof (e.g., "assertionMethod") */
+  proofPurpose: string;
+  /** The multibase-encoded proof value */
+  proofValue: string;
+}
+
+/**
+ * Witness Proof - extends DataIntegrityProof with witness-specific fields
+ * Used when a third party attests to the existence of an event at a point in time
+ */
+export interface WitnessProof extends DataIntegrityProof {
+  /** ISO 8601 timestamp when the witness attested to the event */
+  witnessedAt: string;
+}
+
+/**
+ * External Reference - points to data outside the event log
+ * Used for large resources that shouldn't be embedded in the log
+ */
+export interface ExternalReference {
+  /** Optional URLs where the data can be retrieved */
+  url?: string[];
+  /** Optional MIME type of the data */
+  mediaType?: string;
+  /** Required Multibase-encoded (base64url-nopad) Multihash (sha2-256) of the data */
+  digestMultibase: string;
+}
+
+/**
+ * Event type for log entries
+ */
+export type EventType = 'create' | 'update' | 'deactivate';
+
+/**
+ * Log Entry - a single event in the cryptographic event log
+ * Contains the event data, proof(s), and chain reference
+ */
+export interface LogEntry {
+  /** The type of event */
+  type: EventType;
+  /** The event data (schema varies by event type) */
+  data: unknown;
+  /** Multibase-encoded hash of the previous event (omitted for first event) */
+  previousEvent?: string;
+  /** One or more proofs attesting to this event (controller proof + optional witness proofs) */
+  proof: (DataIntegrityProof | WitnessProof)[];
+}
+
+/**
+ * Event Log - the complete cryptographic event log
+ * Contains a list of hash-chained events with optional chunking support
+ */
+export interface EventLog {
+  /** The list of events in chronological order */
+  events: LogEntry[];
+  /** Optional reference to a previous log file (for chunking long histories) */
+  previousLog?: string;
+}
+
+/**
+ * Verification result for a single event
+ */
+export interface EventVerification {
+  /** Index of the event in the log */
+  index: number;
+  /** The event type */
+  type: EventType;
+  /** Whether the event's proofs are valid */
+  proofValid: boolean;
+  /** Whether the hash chain link is valid (previousEvent matches) */
+  chainValid: boolean;
+  /** Any errors encountered during verification */
+  errors: string[];
+}
+
+/**
+ * Result of verifying an entire event log
+ */
+export interface VerificationResult {
+  /** Whether the entire log is valid */
+  verified: boolean;
+  /** List of errors encountered */
+  errors: string[];
+  /** Per-event verification details */
+  events: EventVerification[];
+}
+
+/**
+ * Options for creating a new event log
+ */
+export interface CreateOptions {
+  /** Signer function that produces a proof */
+  signer: (data: unknown) => Promise<DataIntegrityProof>;
+  /** The verification method DID URL */
+  verificationMethod: string;
+  /** The proof purpose (defaults to "assertionMethod") */
+  proofPurpose?: string;
+}
+
+/**
+ * Options for updating an event log
+ */
+export interface UpdateOptions extends CreateOptions {}
+
+/**
+ * Options for deactivating an event log
+ */
+export interface DeactivateOptions extends CreateOptions {}
+
+/**
+ * Options for verifying an event log
+ */
+export interface VerifyOptions {
+  /** Optional custom proof verifier */
+  verifier?: (proof: DataIntegrityProof, data: unknown) => Promise<boolean>;
+}
+
+/**
+ * Asset state derived from replaying event log
+ */
+export interface AssetState {
+  /** Current DID of the asset */
+  did: string;
+  /** Asset name */
+  name?: string;
+  /** Current layer (peer, webvh, btco) */
+  layer: 'peer' | 'webvh' | 'btco';
+  /** External resources associated with the asset */
+  resources: ExternalReference[];
+  /** Creator DID */
+  creator?: string;
+  /** Creation timestamp */
+  createdAt?: string;
+  /** Last update timestamp */
+  updatedAt?: string;
+  /** Whether the asset has been deactivated */
+  deactivated: boolean;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+}

package/src/cel/witnesses/BitcoinWitness.ts

@@ -0,0 +1,184 @@
+/**
+ * BitcoinWitness - Bitcoin-based witness service for CEL event logs
+ * 
+ * Implements the WitnessService interface using Bitcoin ordinals inscriptions.
+ * Used for the did:btco layer to anchor events on the Bitcoin blockchain,
+ * providing the highest level of immutability and timestamping.
+ * 
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+
+import type { WitnessProof } from '../types';
+import type { WitnessService } from './WitnessService';
+import type { BitcoinManager } from '../../bitcoin/BitcoinManager';
+
+/**
+ * Configuration options for BitcoinWitness
+ */
+export interface BitcoinWitnessOptions {
+  /** Fee rate in sat/vB for inscription transactions (optional - BitcoinManager will estimate if not provided) */
+  feeRate?: number;
+  /** Verification method DID URL for the witness proof */
+  verificationMethod?: string;
+}
+
+/**
+ * Error thrown when the Bitcoin witness service fails
+ */
+export class BitcoinWitnessError extends Error {
+  /** The digest that failed to be witnessed */
+  readonly digest?: string;
+  /** The underlying error message if available */
+  readonly cause?: Error;
+  
+  constructor(message: string, digest?: string, cause?: Error) {
+    super(message);
+    this.name = 'BitcoinWitnessError';
+    this.digest = digest;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Bitcoin inscription witness proof with additional Bitcoin-specific fields
+ */
+export interface BitcoinWitnessProof extends WitnessProof {
+  /** The Bitcoin transaction ID containing the witness inscription */
+  txid: string;
+  /** The block height where the inscription was confirmed (if available) */
+  blockHeight?: number;
+  /** The satoshi ordinal number anchoring the inscription */
+  satoshi: string;
+  /** The inscription ID in the format {txid}i{index} */
+  inscriptionId: string;
+}
+
+/**
+ * Bitcoin-based witness service implementation
+ * 
+ * Inscribes digestMultibase on Bitcoin via ordinals and returns a WitnessProof
+ * containing the transaction details and satoshi ordinal as anchor.
+ * 
+ * @example
+ * ```typescript
+ * const bitcoinManager = new BitcoinManager(config);
+ * const witness = new BitcoinWitness(bitcoinManager);
+ * const proof = await witness.witness('uEiD...');
+ * console.log(proof.txid); // Bitcoin transaction ID
+ * console.log(proof.satoshi); // Satoshi ordinal anchor
+ * ```
+ */
+export class BitcoinWitness implements WitnessService {
+  private readonly bitcoinManager: BitcoinManager;
+  private readonly feeRate?: number;
+  private readonly verificationMethod: string;
+  
+  /**
+   * Creates a new BitcoinWitness instance
+   * 
+   * @param bitcoinManager - BitcoinManager instance configured with an ordinals provider
+   * @param options - Optional configuration options
+   */
+  constructor(bitcoinManager: BitcoinManager, options: BitcoinWitnessOptions = {}) {
+    if (!bitcoinManager) {
+      throw new Error('BitcoinManager instance is required');
+    }
+    
+    this.bitcoinManager = bitcoinManager;
+    this.feeRate = options.feeRate;
+    this.verificationMethod = options.verificationMethod ?? 'did:btco:witness';
+  }
+  
+  /**
+   * Witnesses a digest by inscribing it on the Bitcoin blockchain
+   * 
+   * @param digestMultibase - The Multibase-encoded digest to witness
+   * @returns A BitcoinWitnessProof containing the inscription details and witnessedAt timestamp
+   * @throws BitcoinWitnessError if the inscription fails
+   */
+  async witness(digestMultibase: string): Promise<BitcoinWitnessProof> {
+    if (!digestMultibase || typeof digestMultibase !== 'string') {
+      throw new BitcoinWitnessError('digestMultibase must be a non-empty string', digestMultibase);
+    }
+    
+    // Validate multibase prefix (should start with 'u' for base64url-nopad or 'z' for base58btc)
+    const validPrefixes = ['u', 'z'];
+    if (!validPrefixes.includes(digestMultibase[0])) {
+      throw new BitcoinWitnessError(
+        `Invalid digestMultibase encoding: expected prefix 'u' or 'z', got '${digestMultibase[0]}'`,
+        digestMultibase
+      );
+    }
+    
+    try {
+      // Create witness attestation data
+      const witnessData = {
+        '@context': 'https://w3id.org/cel/v1',
+        type: 'BitcoinWitnessAttestation',
+        digestMultibase,
+        witnessedAt: new Date().toISOString(),
+      };
+      
+      // Inscribe the witness data on Bitcoin
+      const inscription = await this.bitcoinManager.inscribeData(
+        witnessData,
+        'application/json',
+        this.feeRate
+      );
+      
+      // Validate inscription result
+      if (!inscription.inscriptionId) {
+        throw new BitcoinWitnessError(
+          'Bitcoin inscription did not return a valid inscription ID',
+          digestMultibase
+        );
+      }
+      
+      if (!inscription.txid) {
+        throw new BitcoinWitnessError(
+          'Bitcoin inscription did not return a transaction ID',
+          digestMultibase
+        );
+      }
+      
+      const now = new Date().toISOString();
+      
+      // Build the WitnessProof with Bitcoin-specific extensions
+      const proof: BitcoinWitnessProof = {
+        type: 'DataIntegrityProof',
+        cryptosuite: 'bitcoin-ordinals-2024',
+        created: now,
+        verificationMethod: this.verificationMethod,
+        proofPurpose: 'assertionMethod',
+        proofValue: `z${inscription.inscriptionId}`, // Use inscription ID as proof value with multibase prefix
+        witnessedAt: now,
+        txid: inscription.txid,
+        blockHeight: inscription.blockHeight,
+        satoshi: inscription.satoshi,
+        inscriptionId: inscription.inscriptionId,
+      };
+      
+      return proof;
+      
+    } catch (error) {
+      // Re-throw BitcoinWitnessError as-is
+      if (error instanceof BitcoinWitnessError) {
+        throw error;
+      }
+      
+      // Wrap other errors
+      throw new BitcoinWitnessError(
+        `Failed to inscribe witness on Bitcoin: ${error instanceof Error ? error.message : String(error)}`,
+        digestMultibase,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+  
+  /**
+   * Gets the fee rate configured for this witness (if any)
+   */
+  get configuredFeeRate(): number | undefined {
+    return this.feeRate;
+  }
+}