@originals/sdk 1.5.0 → 1.6.0

package/dist/cel/OriginalsCel.js

@@ -0,0 +1,349 @@
+/**
+ * OriginalsCel - Unified SDK Entry Point for CEL Operations
+ *
+ * Provides a single, simplified interface for all Cryptographic Event Log
+ * operations across all layers (peer, webvh, btco).
+ *
+ * This class delegates to the appropriate layer manager based on
+ * the configured layer and the current state of the event log.
+ *
+ * @example
+ * ```typescript
+ * // Create a peer-layer asset
+ * const cel = new OriginalsCel({
+ *   layer: 'peer',
+ *   signer: async (data) => createEdDsaProof(data, privateKey),
+ * });
+ *
+ * const log = await cel.create('My Asset', [
+ *   { digestMultibase: 'uXYZ...', mediaType: 'image/png' }
+ * ]);
+ *
+ * // Update the asset
+ * const updated = await cel.update(log, { description: 'Updated' });
+ *
+ * // Verify the log
+ * const result = await cel.verify(updated);
+ *
+ * // Migrate to webvh layer
+ * const migrated = await cel.migrate(updated, 'webvh');
+ * ```
+ */
+import { PeerCelManager } from './layers/PeerCelManager';
+import { WebVHCelManager } from './layers/WebVHCelManager';
+import { BtcoCelManager } from './layers/BtcoCelManager';
+import { verifyEventLog } from './algorithms/verifyEventLog';
+/**
+ * OriginalsCel - Unified SDK for Cryptographic Event Log operations
+ *
+ * Provides a consistent API for creating, updating, verifying, and migrating
+ * assets across all supported layers (peer, webvh, btco).
+ */
+export class OriginalsCel {
+    /**
+     * Creates a new OriginalsCel instance
+     *
+     * @param options - Configuration options
+     * @param options.layer - The target layer for operations (peer, webvh, btco)
+     * @param options.signer - Function that signs data and returns a DataIntegrityProof
+     * @param options.config - Optional layer-specific configuration
+     *
+     * @throws Error if signer is not a function
+     * @throws Error if layer is invalid
+     */
+    constructor(options) {
+        if (typeof options.signer !== 'function') {
+            throw new Error('OriginalsCel requires a signer function');
+        }
+        const validLayers = ['peer', 'webvh', 'btco'];
+        if (!validLayers.includes(options.layer)) {
+            throw new Error(`Invalid layer: ${options.layer}. Must be one of: ${validLayers.join(', ')}`);
+        }
+        this.layer = options.layer;
+        this.signer = options.signer;
+        this.config = options.config || {};
+    }
+    /**
+     * Gets or creates the PeerCelManager instance
+     */
+    get peerManager() {
+        if (!this._peerManager) {
+            this._peerManager = new PeerCelManager(this.signer, this.config.peer);
+        }
+        return this._peerManager;
+    }
+    /**
+     * Gets or creates the WebVHCelManager instance
+     *
+     * @throws Error if domain is not configured for webvh operations
+     */
+    getWebVHManager(domain) {
+        const webvhDomain = domain || this.config.webvh?.domain;
+        if (!webvhDomain) {
+            throw new Error('WebVH operations require a domain. Provide it in config.webvh.domain');
+        }
+        // Always create a new instance with the current domain to support different domains
+        return new WebVHCelManager(this.signer, webvhDomain, this.config.webvh?.witnesses || [], this.config.webvh);
+    }
+    /**
+     * Gets or creates the BtcoCelManager instance
+     *
+     * @throws Error if BitcoinManager is not configured for btco operations
+     */
+    get btcoManager() {
+        if (!this._btcoManager) {
+            const bitcoinManager = this.config.btco?.bitcoinManager;
+            if (!bitcoinManager) {
+                throw new Error('BTCO operations require a BitcoinManager. Provide it in config.btco.bitcoinManager');
+            }
+            this._btcoManager = new BtcoCelManager(this.signer, bitcoinManager, this.config.btco);
+        }
+        return this._btcoManager;
+    }
+    /**
+     * Creates a new asset with a CEL event log
+     *
+     * This method creates an asset at the configured layer. Note that
+     * new assets can only be created at the peer layer - for other layers,
+     * create at peer first and then migrate.
+     *
+     * @param name - Human-readable name for the asset
+     * @param resources - External resources associated with the asset
+     * @returns Promise resolving to an EventLog with the create event
+     *
+     * @throws Error if signer produces invalid proof
+     * @throws Error if trying to create at non-peer layer
+     *
+     * @example
+     * ```typescript
+     * const log = await cel.create('My Asset', [
+     *   createExternalReference(imageData, 'image/png')
+     * ]);
+     * ```
+     */
+    async create(name, resources) {
+        // Assets can only be created at the peer layer
+        // Other layers require migration from peer
+        if (this.layer !== 'peer') {
+            throw new Error(`Cannot create assets at ${this.layer} layer directly. ` +
+                `Create at peer layer first, then use migrate() to move to ${this.layer}.`);
+        }
+        return this.peerManager.create(name, resources);
+    }
+    /**
+     * Updates an existing event log by appending an update event
+     *
+     * The new event is cryptographically linked to the previous event
+     * via a hash chain (previousEvent field).
+     *
+     * @param log - The existing event log to update
+     * @param data - The update data (new metadata, resources, etc.)
+     * @returns Promise resolving to a new EventLog with the update event appended
+     *
+     * @throws Error if the log is empty or deactivated
+     * @throws Error if signer produces invalid proof
+     *
+     * @example
+     * ```typescript
+     * const updated = await cel.update(log, {
+     *   description: 'Updated description',
+     *   tags: ['art', 'digital']
+     * });
+     * ```
+     */
+    async update(log, data) {
+        // Determine the current layer of the log
+        const currentLayer = this.getCurrentLayer(log);
+        // Use the appropriate manager based on current layer
+        switch (currentLayer) {
+            case 'peer':
+                return this.peerManager.update(log, data);
+            case 'webvh': {
+                // For webvh, we need to use the webvh manager
+                // Get domain from the log if possible
+                const webvhDomain = this.extractDomainFromLog(log);
+                return this.getWebVHManager(webvhDomain).migrate(log).then(
+                // webvh manager doesn't have update, use peer manager's algorithm
+                () => this.peerManager.update(log, data));
+            }
+            case 'btco':
+                // For btco, updates use the same underlying algorithm
+                return this.peerManager.update(log, data);
+            default: {
+                // TypeScript exhaustiveness check
+                const _exhaustive = currentLayer;
+                throw new Error(`Unknown layer: ${String(_exhaustive)}`);
+            }
+        }
+    }
+    /**
+     * Verifies all proofs and hash chain integrity in an event log
+     *
+     * This method verifies:
+     * - Each event has at least one proof
+     * - Each proof is structurally valid
+     * - The hash chain is intact (each event links to previous)
+     *
+     * @param log - The event log to verify
+     * @param options - Optional verification options
+     * @returns Promise resolving to VerificationResult with detailed status
+     *
+     * @example
+     * ```typescript
+     * const result = await cel.verify(log);
+     * if (result.verified) {
+     *   console.log('Log is valid!');
+     * } else {
+     *   console.error('Verification failed:', result.errors);
+     * }
+     * ```
+     */
+    async verify(log, options) {
+        return verifyEventLog(log, options);
+    }
+    /**
+     * Migrates an event log to a target layer
+     *
+     * Migration adds an update event with migration data and (optionally)
+     * witness proofs. The valid migration paths are:
+     * - peer → webvh
+     * - webvh → btco
+     * - peer → btco (requires intermediate webvh migration)
+     *
+     * @param log - The event log to migrate
+     * @param targetLayer - The layer to migrate to
+     * @param options - Optional migration options (e.g., domain for webvh)
+     * @returns Promise resolving to the migrated EventLog
+     *
+     * @throws Error if migration path is invalid
+     * @throws Error if required config is missing for target layer
+     *
+     * @example
+     * ```typescript
+     * // Migrate peer to webvh
+     * const webvhLog = await cel.migrate(peerLog, 'webvh', {
+     *   domain: 'example.com'
+     * });
+     *
+     * // Migrate webvh to btco
+     * const btcoLog = await cel.migrate(webvhLog, 'btco');
+     * ```
+     */
+    async migrate(log, targetLayer, options) {
+        const currentLayer = this.getCurrentLayer(log);
+        // Validate migration path
+        if (currentLayer === targetLayer) {
+            throw new Error(`Log is already at ${targetLayer} layer`);
+        }
+        if (currentLayer === 'btco') {
+            throw new Error('Cannot migrate from btco layer - it is the final layer');
+        }
+        // Perform migration based on current and target layers
+        switch (targetLayer) {
+            case 'peer':
+                throw new Error('Cannot migrate to peer layer - it is the initial layer');
+            case 'webvh': {
+                if (currentLayer !== 'peer') {
+                    throw new Error(`Invalid migration: ${currentLayer} → webvh. Can only migrate peer → webvh.`);
+                }
+                const domain = options?.domain || this.config.webvh?.domain;
+                return this.getWebVHManager(domain).migrate(log);
+            }
+            case 'btco': {
+                if (currentLayer === 'peer') {
+                    // Need to do two-step migration: peer → webvh → btco
+                    throw new Error('Cannot migrate directly from peer to btco. ' +
+                        'Migrate to webvh first, then to btco.');
+                }
+                if (currentLayer !== 'webvh') {
+                    throw new Error(`Invalid migration: ${String(currentLayer)} → btco. Can only migrate webvh → btco.`);
+                }
+                return this.btcoManager.migrate(log);
+            }
+            default: {
+                // TypeScript exhaustiveness check
+                const _exhaustive = targetLayer;
+                throw new Error(`Unknown target layer: ${String(_exhaustive)}`);
+            }
+        }
+    }
+    /**
+     * Derives the current asset state by replaying all events in the log
+     *
+     * @param log - The event log to derive state from
+     * @returns The current AssetState
+     *
+     * @example
+     * ```typescript
+     * const state = cel.getCurrentState(log);
+     * console.log(state.name);        // Asset name
+     * console.log(state.layer);       // Current layer
+     * console.log(state.deactivated); // Whether deactivated
+     * ```
+     */
+    getCurrentState(log) {
+        // Determine current layer and use appropriate manager
+        const currentLayer = this.getCurrentLayer(log);
+        switch (currentLayer) {
+            case 'peer':
+                return this.peerManager.getCurrentState(log);
+            case 'webvh': {
+                // WebVH manager also handles state derivation correctly
+                const domain = this.extractDomainFromLog(log) || 'unknown.com';
+                return this.getWebVHManager(domain).getCurrentState(log);
+            }
+            case 'btco':
+                return this.btcoManager.getCurrentState(log);
+            default:
+                // Fallback to peer manager which handles all event types
+                return this.peerManager.getCurrentState(log);
+        }
+    }
+    /**
+     * Determines the current layer of an event log by examining its events
+     *
+     * @param log - The event log to examine
+     * @returns The current layer of the log
+     */
+    getCurrentLayer(log) {
+        if (!log || !log.events || log.events.length === 0) {
+            return 'peer'; // Default for empty logs
+        }
+        let currentLayer = 'peer';
+        for (const event of log.events) {
+            const eventData = event.data;
+            if (event.type === 'create') {
+                currentLayer = eventData.layer || 'peer';
+            }
+            else if (event.type === 'update' && eventData.targetDid && eventData.layer) {
+                // This is a migration event
+                currentLayer = eventData.layer;
+            }
+        }
+        return currentLayer;
+    }
+    /**
+     * Extracts the domain from a webvh log's migration event
+     *
+     * @param log - The event log to examine
+     * @returns The domain if found, undefined otherwise
+     */
+    extractDomainFromLog(log) {
+        if (!log || !log.events) {
+            return undefined;
+        }
+        for (const event of log.events) {
+            const eventData = event.data;
+            if (eventData.domain) {
+                return eventData.domain;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Gets the configured layer for this instance
+     */
+    get currentLayer() {
+        return this.layer;
+    }
+}

package/dist/cel/algorithms/createEventLog.d.ts

@@ -0,0 +1,32 @@
+/**
+ * createEventLog Algorithm
+ *
+ * Creates a new Cryptographic Event Log with an initial "create" event.
+ * The create event is the first event in a log and has no previousEvent reference.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import type { EventLog, CreateOptions } from '../types';
+/**
+ * Creates a new event log with a single "create" event.
+ *
+ * This is the first step in creating a CEL-based provenance chain.
+ * The create event establishes the initial state of an asset.
+ *
+ * @param data - The initial data for the asset (e.g., name, resources, metadata)
+ * @param options - Signing options including signer function and verification method
+ * @returns A new EventLog containing a single create event
+ *
+ * @example
+ * ```typescript
+ * const log = await createEventLog(
+ *   { name: 'My Asset', resources: [...] },
+ *   {
+ *     signer: async (data) => createEdDsaProof(data, privateKey),
+ *     verificationMethod: 'did:key:z6Mk...',
+ *     proofPurpose: 'assertionMethod'
+ *   }
+ * );
+ * ```
+ */
+export declare function createEventLog(data: unknown, options: CreateOptions): Promise<EventLog>;

package/dist/cel/algorithms/createEventLog.js

@@ -0,0 +1,56 @@
+/**
+ * createEventLog Algorithm
+ *
+ * Creates a new Cryptographic Event Log with an initial "create" event.
+ * The create event is the first event in a log and has no previousEvent reference.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+/**
+ * Creates a new event log with a single "create" event.
+ *
+ * This is the first step in creating a CEL-based provenance chain.
+ * The create event establishes the initial state of an asset.
+ *
+ * @param data - The initial data for the asset (e.g., name, resources, metadata)
+ * @param options - Signing options including signer function and verification method
+ * @returns A new EventLog containing a single create event
+ *
+ * @example
+ * ```typescript
+ * const log = await createEventLog(
+ *   { name: 'My Asset', resources: [...] },
+ *   {
+ *     signer: async (data) => createEdDsaProof(data, privateKey),
+ *     verificationMethod: 'did:key:z6Mk...',
+ *     proofPurpose: 'assertionMethod'
+ *   }
+ * );
+ * ```
+ */
+export async function createEventLog(data, options) {
+    const { signer, verificationMethod, proofPurpose = 'assertionMethod' } = options;
+    // Create the event structure without proof first
+    const eventBase = {
+        type: 'create',
+        data,
+        // Note: First event has no previousEvent
+    };
+    // Generate proof using the provided signer
+    const proof = await signer(eventBase);
+    // Validate the proof has required fields
+    if (!proof.type || !proof.cryptosuite || !proof.proofValue) {
+        throw new Error('Invalid proof: missing required fields (type, cryptosuite, proofValue)');
+    }
+    // Construct the complete log entry
+    const entry = {
+        type: 'create',
+        data,
+        proof: [proof],
+    };
+    // Return the new event log
+    const eventLog = {
+        events: [entry],
+    };
+    return eventLog;
+}

package/dist/cel/algorithms/deactivateEventLog.d.ts

@@ -0,0 +1,35 @@
+/**
+ * deactivateEventLog Algorithm
+ *
+ * Seals an event log with a "deactivate" event. Once deactivated,
+ * no further events should be added to the log.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import type { EventLog, DeactivateOptions } from '../types';
+/**
+ * Deactivates an event log by appending a final "deactivate" event.
+ *
+ * The deactivate event seals the log, indicating that no further
+ * events should be added. This is used to mark an asset as retired,
+ * revoked, or otherwise no longer active.
+ *
+ * @param log - The existing event log to deactivate
+ * @param reason - The reason for deactivation (e.g., "retired", "revoked", "superseded")
+ * @param options - Signing options including signer function and verification method
+ * @returns A new EventLog with the deactivate event appended (input is not mutated)
+ *
+ * @example
+ * ```typescript
+ * const deactivatedLog = await deactivateEventLog(
+ *   existingLog,
+ *   'Asset has been superseded by a new version',
+ *   {
+ *     signer: async (data) => createEdDsaProof(data, privateKey),
+ *     verificationMethod: 'did:key:z6Mk...',
+ *     proofPurpose: 'assertionMethod'
+ *   }
+ * );
+ * ```
+ */
+export declare function deactivateEventLog(log: EventLog, reason: string, options: DeactivateOptions): Promise<EventLog>;

package/dist/cel/algorithms/deactivateEventLog.js

@@ -0,0 +1,91 @@
+/**
+ * deactivateEventLog Algorithm
+ *
+ * Seals an event log with a "deactivate" event. Once deactivated,
+ * no further events should be added to the log.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import { computeDigestMultibase } from '../hash';
+/**
+ * Serializes a LogEntry to a deterministic byte representation for hashing.
+ * Uses JSON with sorted keys for reproducibility.
+ *
+ * @param entry - The log entry to serialize
+ * @returns UTF-8 encoded bytes
+ */
+function serializeEntry(entry) {
+    // Use JSON with sorted keys for deterministic serialization
+    const json = JSON.stringify(entry, Object.keys(entry).sort());
+    return new TextEncoder().encode(json);
+}
+/**
+ * Deactivates an event log by appending a final "deactivate" event.
+ *
+ * The deactivate event seals the log, indicating that no further
+ * events should be added. This is used to mark an asset as retired,
+ * revoked, or otherwise no longer active.
+ *
+ * @param log - The existing event log to deactivate
+ * @param reason - The reason for deactivation (e.g., "retired", "revoked", "superseded")
+ * @param options - Signing options including signer function and verification method
+ * @returns A new EventLog with the deactivate event appended (input is not mutated)
+ *
+ * @example
+ * ```typescript
+ * const deactivatedLog = await deactivateEventLog(
+ *   existingLog,
+ *   'Asset has been superseded by a new version',
+ *   {
+ *     signer: async (data) => createEdDsaProof(data, privateKey),
+ *     verificationMethod: 'did:key:z6Mk...',
+ *     proofPurpose: 'assertionMethod'
+ *   }
+ * );
+ * ```
+ */
+export async function deactivateEventLog(log, reason, options) {
+    const { signer, verificationMethod, proofPurpose = 'assertionMethod' } = options;
+    // Validate input log
+    if (!log.events || log.events.length === 0) {
+        throw new Error('Cannot deactivate an empty event log');
+    }
+    // Check if log is already deactivated
+    const lastEvent = log.events[log.events.length - 1];
+    if (lastEvent.type === 'deactivate') {
+        throw new Error('Event log is already deactivated');
+    }
+    // Compute the digestMultibase of the last event
+    const previousEvent = computeDigestMultibase(serializeEntry(lastEvent));
+    // Deactivation data includes the reason
+    const deactivationData = {
+        reason,
+        deactivatedAt: new Date().toISOString(),
+    };
+    // Create the event structure without proof first
+    const eventBase = {
+        type: 'deactivate',
+        data: deactivationData,
+        previousEvent,
+    };
+    // Generate proof using the provided signer
+    const proof = await signer(eventBase);
+    // Validate the proof has required fields
+    if (!proof.type || !proof.cryptosuite || !proof.proofValue) {
+        throw new Error('Invalid proof: missing required fields (type, cryptosuite, proofValue)');
+    }
+    // Construct the complete log entry
+    const entry = {
+        type: 'deactivate',
+        data: deactivationData,
+        previousEvent,
+        proof: [proof],
+    };
+    // Return a new event log (immutable - does not mutate input)
+    const eventLog = {
+        events: [...log.events, entry],
+        // Preserve previousLog reference if it exists
+        ...(log.previousLog ? { previousLog: log.previousLog } : {}),
+    };
+    return eventLog;
+}

package/dist/cel/algorithms/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CEL Algorithms
+ *
+ * Core algorithms for working with Cryptographic Event Logs.
+ */
+export { createEventLog } from './createEventLog';
+export { updateEventLog } from './updateEventLog';
+export { deactivateEventLog } from './deactivateEventLog';
+export { verifyEventLog } from './verifyEventLog';
+export { witnessEvent } from './witnessEvent';

package/dist/cel/algorithms/index.js

@@ -0,0 +1,10 @@
+/**
+ * CEL Algorithms
+ *
+ * Core algorithms for working with Cryptographic Event Logs.
+ */
+export { createEventLog } from './createEventLog';
+export { updateEventLog } from './updateEventLog';
+export { deactivateEventLog } from './deactivateEventLog';
+export { verifyEventLog } from './verifyEventLog';
+export { witnessEvent } from './witnessEvent';

package/dist/cel/algorithms/updateEventLog.d.ts

@@ -0,0 +1,34 @@
+/**
+ * updateEventLog Algorithm
+ *
+ * Appends an update event to an existing Cryptographic Event Log.
+ * Each update event references the previous event via a hash chain.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import type { EventLog, UpdateOptions } from '../types';
+/**
+ * Updates an event log by appending a new "update" event.
+ *
+ * The new event is cryptographically linked to the previous event
+ * via a hash of the last event (previousEvent field).
+ *
+ * @param log - The existing event log to update
+ * @param data - The update data (e.g., modified metadata, new resources)
+ * @param options - Signing options including signer function and verification method
+ * @returns A new EventLog with the update event appended (input is not mutated)
+ *
+ * @example
+ * ```typescript
+ * const updatedLog = await updateEventLog(
+ *   existingLog,
+ *   { name: 'Updated Asset Name', version: 2 },
+ *   {
+ *     signer: async (data) => createEdDsaProof(data, privateKey),
+ *     verificationMethod: 'did:key:z6Mk...',
+ *     proofPurpose: 'assertionMethod'
+ *   }
+ * );
+ * ```
+ */
+export declare function updateEventLog(log: EventLog, data: unknown, options: UpdateOptions): Promise<EventLog>;