@originals/sdk 1.5.0 → 1.6.1

package/dist/cel/layers/WebVHCelManager.js

@@ -0,0 +1,291 @@
+/**
+ * WebVHCelManager - CEL Manager for did:webvh Layer
+ *
+ * Manages migration of Originals assets to the did:webvh layer (Layer 1).
+ * This layer provides HTTP-based witnessing for verifiable history.
+ *
+ * The did:webvh (Web Verifiable History) method combines domain-based
+ * resolution with cryptographic event logging for discoverable assets.
+ *
+ * @see https://identity.foundation/didwebvh/
+ */
+import { updateEventLog } from '../algorithms/updateEventLog';
+import { witnessEvent } from '../algorithms/witnessEvent';
+/**
+ * WebVHCelManager - Manages CEL-based asset migration to did:webvh layer
+ *
+ * The webvh layer is the first publication layer for Originals assets.
+ * Assets at this layer:
+ * - Have a did:webvh identifier based on a domain
+ * - Can have HTTP-based witness attestations
+ * - Are discoverable via web-based DID resolution
+ * - Can be further migrated to did:btco layer
+ *
+ * @example
+ * ```typescript
+ * const httpWitness = new HttpWitness('https://witness.example.com/api/attest');
+ * const manager = new WebVHCelManager(
+ *   async (data) => createEdDsaProof(data, privateKey),
+ *   'example.com',
+ *   [httpWitness]
+ * );
+ *
+ * const webvhLog = await manager.migrate(peerLog);
+ * ```
+ */
+export class WebVHCelManager {
+    /**
+     * Creates a new WebVHCelManager instance
+     *
+     * @param signer - Function that signs data and returns a DataIntegrityProof
+     * @param domain - The domain for the did:webvh DID (e.g., 'example.com')
+     * @param witnesses - Optional array of witness services for attestations
+     * @param config - Optional configuration options
+     */
+    constructor(signer, domain, witnesses = [], config = {}) {
+        if (typeof signer !== 'function') {
+            throw new Error('WebVHCelManager requires a signer function');
+        }
+        if (!domain || typeof domain !== 'string') {
+            throw new Error('WebVHCelManager requires a valid domain string');
+        }
+        // Basic domain validation
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9.-]*[a-zA-Z0-9]$/.test(domain) && !/^[a-zA-Z0-9]$/.test(domain)) {
+            throw new Error(`Invalid domain format: ${domain}`);
+        }
+        if (!Array.isArray(witnesses)) {
+            throw new Error('witnesses must be an array');
+        }
+        this.signer = signer;
+        this.domain = domain;
+        this.witnesses = witnesses;
+        this.config = {
+            proofPurpose: 'assertionMethod',
+            ...config,
+        };
+    }
+    /**
+     * Migrates a peer layer event log to the did:webvh layer
+     *
+     * This method:
+     * 1. Validates the input log (must have a create event with peer layer data)
+     * 2. Generates a new did:webvh DID based on the domain
+     * 3. Creates an update event with migration data
+     * 4. Optionally adds witness proofs from configured witnesses
+     * 5. Returns the updated EventLog
+     *
+     * @param peerLog - The event log from the peer layer to migrate
+     * @returns Promise resolving to an EventLog with the migration event appended
+     *
+     * @throws Error if the log is empty, deactivated, or not from peer layer
+     * @throws Error if signer produces invalid proof
+     * @throws Error if witness service fails (if witnesses configured)
+     */
+    async migrate(peerLog) {
+        // Validate input log
+        if (!peerLog || !peerLog.events || peerLog.events.length === 0) {
+            throw new Error('Cannot migrate an empty event log');
+        }
+        // Get the create event to extract source DID
+        const createEvent = peerLog.events[0];
+        if (createEvent.type !== 'create') {
+            throw new Error('First event must be a create event');
+        }
+        // Extract source data
+        const createData = createEvent.data;
+        const sourceDid = createData.did;
+        if (!sourceDid) {
+            throw new Error('Create event must have a did field');
+        }
+        // Validate source is from peer layer
+        const sourceLayer = createData.layer;
+        if (sourceLayer && sourceLayer !== 'peer') {
+            throw new Error(`Cannot migrate from ${sourceLayer} layer to webvh layer. Expected peer layer.`);
+        }
+        // Check if log is already deactivated
+        const lastEvent = peerLog.events[peerLog.events.length - 1];
+        if (lastEvent.type === 'deactivate') {
+            throw new Error('Cannot migrate a deactivated event log');
+        }
+        // Generate did:webvh DID
+        const targetDid = this.generateWebVHDid(sourceDid);
+        // Prepare migration data
+        const migrationData = {
+            sourceDid,
+            targetDid,
+            layer: 'webvh',
+            domain: this.domain,
+            migratedAt: new Date().toISOString(),
+        };
+        // Build update options
+        const updateOptions = {
+            signer: this.signer,
+            verificationMethod: this.config.verificationMethod || `${targetDid}#key-0`,
+            proofPurpose: this.config.proofPurpose,
+        };
+        // Create the update event with migration data
+        let updatedLog = await updateEventLog(peerLog, migrationData, updateOptions);
+        // Add witness proofs if witnesses are configured
+        if (this.witnesses.length > 0) {
+            // Get the last event (the migration event we just added)
+            const lastEventIndex = updatedLog.events.length - 1;
+            let witnessedEvent = updatedLog.events[lastEventIndex];
+            // Add witness proofs from each configured witness
+            for (const witness of this.witnesses) {
+                witnessedEvent = await witnessEvent(witnessedEvent, witness);
+            }
+            // Replace the last event with the witnessed version
+            updatedLog = {
+                ...updatedLog,
+                events: [
+                    ...updatedLog.events.slice(0, lastEventIndex),
+                    witnessedEvent,
+                ],
+            };
+        }
+        return updatedLog;
+    }
+    /**
+     * Generates a did:webvh DID for this domain
+     *
+     * The did:webvh format is: did:webvh:{domain}:{id}
+     * where {id} is derived from the source DID to maintain linkage.
+     *
+     * @param sourceDid - The source DID to derive the webvh DID from
+     * @returns A did:webvh string
+     */
+    generateWebVHDid(sourceDid) {
+        // Extract a stable identifier from the source DID
+        // For did:peer, extract the key portion after the method
+        let idPart;
+        if (sourceDid.startsWith('did:peer:')) {
+            // For peer DIDs, use a hash-derived portion
+            // did:peer:4zQm... -> use the multibase portion
+            const peerPart = sourceDid.replace('did:peer:', '');
+            // Take first 32 chars of the peer DID identifier for brevity
+            idPart = peerPart.substring(0, Math.min(32, peerPart.length));
+        }
+        else if (sourceDid.startsWith('did:key:')) {
+            // For key DIDs, extract the key portion
+            idPart = sourceDid.replace('did:key:', '').substring(0, 32);
+        }
+        else {
+            // For other DIDs, create a hash-based identifier
+            idPart = this.hashIdentifier(sourceDid);
+        }
+        // Sanitize for URL safety (replace invalid chars)
+        idPart = idPart.replace(/[^a-zA-Z0-9]/g, '');
+        return `did:webvh:${this.domain}:${idPart}`;
+    }
+    /**
+     * Creates a URL-safe hash-based identifier from a string
+     */
+    hashIdentifier(input) {
+        // Simple hash for identifier generation (not cryptographic)
+        let hash = 0;
+        for (let i = 0; i < input.length; i++) {
+            const char = input.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return Math.abs(hash).toString(36);
+    }
+    /**
+     * 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 derived from replaying events
+     */
+    getCurrentState(log) {
+        // Validate input log
+        if (!log || !log.events || log.events.length === 0) {
+            throw new Error('Cannot get state from an empty event log');
+        }
+        // First event must be a create event
+        const createEvent = log.events[0];
+        if (createEvent.type !== 'create') {
+            throw new Error('First event must be a create event');
+        }
+        // Extract initial state from create event
+        const createData = createEvent.data;
+        // Initialize state from create event
+        const state = {
+            did: createData.did,
+            name: createData.name,
+            layer: createData.layer || 'peer',
+            resources: createData.resources || [],
+            creator: createData.creator,
+            createdAt: createData.createdAt,
+            updatedAt: undefined,
+            deactivated: false,
+            metadata: {},
+        };
+        // Apply subsequent events
+        for (let i = 1; i < log.events.length; i++) {
+            const event = log.events[i];
+            if (event.type === 'update') {
+                const updateData = event.data;
+                // Check if this is a migration event
+                if (updateData.targetDid && updateData.layer) {
+                    // Migration event - update DID and layer
+                    state.did = updateData.targetDid;
+                    state.layer = updateData.layer;
+                    state.updatedAt = updateData.migratedAt;
+                    // Store migration info in metadata
+                    state.metadata = state.metadata || {};
+                    state.metadata.sourceDid = updateData.sourceDid;
+                    state.metadata.domain = updateData.domain;
+                }
+                else {
+                    // Regular update event
+                    if (updateData.name !== undefined) {
+                        state.name = updateData.name;
+                    }
+                    if (updateData.resources !== undefined) {
+                        state.resources = updateData.resources;
+                    }
+                    if (updateData.updatedAt !== undefined) {
+                        state.updatedAt = updateData.updatedAt;
+                    }
+                    if (updateData.did !== undefined) {
+                        state.did = updateData.did;
+                    }
+                    if (updateData.layer !== undefined) {
+                        state.layer = updateData.layer;
+                    }
+                }
+                // Store other fields in metadata
+                for (const [key, value] of Object.entries(updateData)) {
+                    if (!['name', 'resources', 'updatedAt', 'did', 'layer', 'creator', 'createdAt', 'sourceDid', 'targetDid', 'domain', 'migratedAt'].includes(key)) {
+                        state.metadata = state.metadata || {};
+                        state.metadata[key] = value;
+                    }
+                }
+            }
+            else if (event.type === 'deactivate') {
+                state.deactivated = true;
+                const deactivateData = event.data;
+                if (deactivateData.deactivatedAt !== undefined) {
+                    state.updatedAt = deactivateData.deactivatedAt;
+                }
+                if (deactivateData.reason !== undefined) {
+                    state.metadata = state.metadata || {};
+                    state.metadata.deactivationReason = deactivateData.reason;
+                }
+            }
+        }
+        return state;
+    }
+    /**
+     * Gets the domain this manager is configured for
+     */
+    get domainName() {
+        return this.domain;
+    }
+    /**
+     * Gets the number of configured witnesses
+     */
+    get witnessCount() {
+        return this.witnesses.length;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * CEL Layer Managers
+ *
+ * Layer managers handle CEL-based asset creation and management at different
+ * trust/persistence layers of the Originals Protocol:
+ *
+ * - PeerCelManager: Layer 0 (did:peer) - Local control, no witnesses
+ * - WebVHCelManager: Layer 1 (did:webvh) - HTTP-based witnessing
+ * - BtcoCelManager: Layer 2 (did:btco) - Bitcoin-based witnessing
+ */
+export * from './PeerCelManager';
+export { WebVHCelManager, type WebVHCelConfig, type WebVHMigrationData } from './WebVHCelManager';
+export { BtcoCelManager, type BtcoCelConfig, type BtcoMigrationData } from './BtcoCelManager';

package/dist/cel/layers/index.js

@@ -0,0 +1,16 @@
+/**
+ * CEL Layer Managers
+ *
+ * Layer managers handle CEL-based asset creation and management at different
+ * trust/persistence layers of the Originals Protocol:
+ *
+ * - PeerCelManager: Layer 0 (did:peer) - Local control, no witnesses
+ * - WebVHCelManager: Layer 1 (did:webvh) - HTTP-based witnessing
+ * - BtcoCelManager: Layer 2 (did:btco) - Bitcoin-based witnessing
+ */
+// Export everything from PeerCelManager including CelSigner type
+export * from './PeerCelManager';
+// Export specific items from WebVHCelManager (CelSigner is imported from PeerCelManager)
+export { WebVHCelManager } from './WebVHCelManager';
+// Export specific items from BtcoCelManager (CelSigner is imported from PeerCelManager)
+export { BtcoCelManager } from './BtcoCelManager';

package/dist/cel/serialization/cbor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CBOR Serialization for CEL Event Logs
+ *
+ * Provides compact binary serialization and parsing of EventLog objects using CBOR format.
+ * CBOR provides ~50% size reduction compared to JSON for bandwidth-sensitive applications.
+ */
+import type { EventLog } from '../types';
+/**
+ * Serialize an EventLog to CBOR binary format.
+ *
+ * CBOR provides a compact binary representation that is typically
+ * 30-50% smaller than JSON for event logs.
+ *
+ * @param log - The EventLog to serialize
+ * @returns Uint8Array containing the CBOR-encoded EventLog
+ * @throws Error if log is null or undefined
+ *
+ * @example
+ * ```typescript
+ * const log = await createEventLog(data, options);
+ * const cbor = serializeEventLogCbor(log);
+ * console.log(cbor.length); // compact binary size
+ * ```
+ */
+export declare function serializeEventLogCbor(log: EventLog): Uint8Array;
+/**
+ * Parse a CBOR binary into an EventLog.
+ *
+ * Validates the structure and types of the parsed object.
+ *
+ * @param cbor - CBOR binary data to parse
+ * @returns Parsed and validated EventLog
+ * @throws Error if CBOR is invalid or doesn't match EventLog structure
+ *
+ * @example
+ * ```typescript
+ * const cbor = readFileSync('asset.cel.cbor');
+ * const log = parseEventLogCbor(cbor);
+ * console.log(log.events.length);
+ * ```
+ */
+export declare function parseEventLogCbor(cbor: Uint8Array): EventLog;

package/dist/cel/serialization/cbor.js

@@ -0,0 +1,163 @@
+/**
+ * CBOR Serialization for CEL Event Logs
+ *
+ * Provides compact binary serialization and parsing of EventLog objects using CBOR format.
+ * CBOR provides ~50% size reduction compared to JSON for bandwidth-sensitive applications.
+ */
+import { encode, decode } from '../../utils/cbor';
+/**
+ * Check if a proof object is a WitnessProof (has witnessedAt field)
+ */
+function isWitnessProof(proof) {
+    return 'witnessedAt' in proof && typeof proof.witnessedAt === 'string';
+}
+/**
+ * Validate and reconstruct a DataIntegrityProof or WitnessProof
+ */
+function parseProof(proof) {
+    if (!proof || typeof proof !== 'object') {
+        throw new Error('Invalid proof: must be an object');
+    }
+    const p = proof;
+    // 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 = {
+        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,
+        };
+    }
+    return baseProof;
+}
+/**
+ * Validate and reconstruct a LogEntry
+ */
+function parseEntry(entry) {
+    if (!entry || typeof entry !== 'object') {
+        throw new Error('Invalid entry: must be an object');
+    }
+    const e = entry;
+    // 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 = {
+        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;
+}
+/**
+ * Serialize an EventLog to CBOR binary format.
+ *
+ * CBOR provides a compact binary representation that is typically
+ * 30-50% smaller than JSON for event logs.
+ *
+ * @param log - The EventLog to serialize
+ * @returns Uint8Array containing the CBOR-encoded EventLog
+ * @throws Error if log is null or undefined
+ *
+ * @example
+ * ```typescript
+ * const log = await createEventLog(data, options);
+ * const cbor = serializeEventLogCbor(log);
+ * console.log(cbor.length); // compact binary size
+ * ```
+ */
+export function serializeEventLogCbor(log) {
+    if (!log) {
+        throw new Error('Cannot serialize null or undefined EventLog');
+    }
+    return encode(log);
+}
+/**
+ * Parse a CBOR binary into an EventLog.
+ *
+ * Validates the structure and types of the parsed object.
+ *
+ * @param cbor - CBOR binary data to parse
+ * @returns Parsed and validated EventLog
+ * @throws Error if CBOR is invalid or doesn't match EventLog structure
+ *
+ * @example
+ * ```typescript
+ * const cbor = readFileSync('asset.cel.cbor');
+ * const log = parseEventLogCbor(cbor);
+ * console.log(log.events.length);
+ * ```
+ */
+export function parseEventLogCbor(cbor) {
+    if (!cbor || !(cbor instanceof Uint8Array)) {
+        throw new Error('Cannot parse null, undefined, or non-Uint8Array value');
+    }
+    if (cbor.length === 0) {
+        throw new Error('Cannot parse empty CBOR data');
+    }
+    let parsed;
+    try {
+        parsed = decode(cbor);
+    }
+    catch (e) {
+        throw new Error(`Invalid CBOR: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('Invalid EventLog: must be an object');
+    }
+    const obj = parsed;
+    // Validate events array
+    if (!Array.isArray(obj.events)) {
+        throw new Error('Invalid EventLog: events must be an array');
+    }
+    const 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/dist/cel/serialization/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CEL Serialization Module
+ *
+ * Provides serialization formats for EventLog:
+ * - JSON: Human-readable, standard format
+ * - CBOR: Compact binary format for bandwidth-sensitive applications
+ */
+export * from './json';
+export * from './cbor';

package/dist/cel/serialization/index.js

@@ -0,0 +1,9 @@
+/**
+ * CEL Serialization Module
+ *
+ * Provides serialization formats for EventLog:
+ * - JSON: Human-readable, standard format
+ * - CBOR: Compact binary format for bandwidth-sensitive applications
+ */
+export * from './json';
+export * from './cbor';

package/dist/cel/serialization/json.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 } from '../types';
+/**
+ * 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 declare function serializeEventLogJson(log: EventLog): string;
+/**
+ * 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 declare function parseEventLogJson(json: string): EventLog;