@originals/sdk 1.5.0 → 1.6.0

package/dist/cel/algorithms/updateEventLog.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { 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);
+}
+/**
+ * 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 async function updateEventLog(log, data, options) {
+    const { signer, verificationMethod, proofPurpose = 'assertionMethod' } = options;
+    // Validate input log
+    if (!log.events || log.events.length === 0) {
+        throw new Error('Cannot update an empty event log');
+    }
+    // Get the last event to compute the hash chain link
+    const lastEvent = log.events[log.events.length - 1];
+    // Compute the digestMultibase of the last event
+    const previousEvent = computeDigestMultibase(serializeEntry(lastEvent));
+    // Create the event structure without proof first
+    const eventBase = {
+        type: 'update',
+        data,
+        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: 'update',
+        data,
+        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/verifyEventLog.d.ts

@@ -0,0 +1,45 @@
+/**
+ * verifyEventLog Algorithm
+ *
+ * Verifies all proofs and hash chain integrity in a Cryptographic Event Log.
+ * Returns detailed per-event verification status.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import type { EventLog, VerifyOptions, VerificationResult } from '../types';
+/**
+ * Verifies all proofs and hash chain integrity in an event log.
+ *
+ * This algorithm verifies:
+ * - Each event has at least one proof
+ * - Each proof is structurally valid (type, cryptosuite, proofValue, verificationMethod, proofPurpose)
+ * - Proofs use valid cryptosuite (eddsa-jcs-2022 or eddsa-rdfc-2022)
+ * - The first event has no previousEvent field
+ * - Each subsequent event's previousEvent matches the digestMultibase of the prior event
+ *
+ * For full cryptographic verification, provide a custom verifier function
+ * in the options that can resolve the public key from the verificationMethod.
+ *
+ * @param log - The event log to verify
+ * @param options - Optional verification options including custom verifier
+ * @returns VerificationResult with detailed per-event status including chainValid
+ *
+ * @example
+ * ```typescript
+ * // Basic structural and chain verification
+ * const result = await verifyEventLog(eventLog);
+ * if (result.verified) {
+ *   console.log('All proofs are valid and hash chain is intact');
+ * }
+ *
+ * // With custom cryptographic verifier
+ * const result = await verifyEventLog(eventLog, {
+ *   verifier: async (proof, data) => {
+ *     // Resolve public key and verify signature
+ *     const publicKey = await resolvePublicKey(proof.verificationMethod);
+ *     return verifyEdDsaSignature(data, proof.proofValue, publicKey);
+ *   }
+ * });
+ * ```
+ */
+export declare function verifyEventLog(log: EventLog, options?: VerifyOptions): Promise<VerificationResult>;

package/dist/cel/algorithms/verifyEventLog.js

@@ -0,0 +1,255 @@
+/**
+ * verifyEventLog Algorithm
+ *
+ * Verifies all proofs and hash chain integrity in a Cryptographic Event Log.
+ * Returns detailed per-event verification status.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import { computeDigestMultibase } from '../hash';
+/**
+ * Serializes data to JCS (JSON Canonicalization Scheme) format.
+ * Uses JSON with sorted keys for deterministic serialization.
+ *
+ * @param data - The data to serialize
+ * @returns UTF-8 encoded bytes
+ */
+function serializeToJcs(data) {
+    // JCS uses JSON with lexicographically sorted keys
+    const json = JSON.stringify(data, (_, value) => {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return Object.keys(value).sort().reduce((sorted, key) => {
+                sorted[key] = value[key];
+                return sorted;
+            }, {});
+        }
+        return value;
+    });
+    return new TextEncoder().encode(json);
+}
+/**
+ * Serializes a LogEntry to a deterministic byte representation for hashing.
+ * Uses JSON with sorted keys for reproducibility.
+ * This must match the serialization used in createEventLog/updateEventLog.
+ *
+ * @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);
+}
+/**
+ * Default proof verifier using eddsa-jcs-2022 cryptosuite.
+ *
+ * This is a basic implementation that validates proof structure.
+ * For full cryptographic verification, a custom verifier should be provided
+ * that has access to the public key from the verificationMethod.
+ *
+ * @param proof - The proof to verify
+ * @param data - The data that was signed
+ * @returns True if proof structure is valid
+ */
+async function defaultVerifier(proof, data) {
+    // Validate proof has required fields
+    if (!proof.type || proof.type !== 'DataIntegrityProof') {
+        return false;
+    }
+    if (!proof.cryptosuite) {
+        return false;
+    }
+    if (!proof.proofValue || typeof proof.proofValue !== 'string' || proof.proofValue.length === 0) {
+        return false;
+    }
+    if (!proof.verificationMethod || typeof proof.verificationMethod !== 'string') {
+        return false;
+    }
+    if (!proof.proofPurpose || typeof proof.proofPurpose !== 'string') {
+        return false;
+    }
+    // Check for valid cryptosuite
+    const validCryptosuites = ['eddsa-jcs-2022', 'eddsa-rdfc-2022'];
+    if (!validCryptosuites.includes(proof.cryptosuite)) {
+        return false;
+    }
+    // Validate proofValue is properly formatted (multibase encoded)
+    // Most proofValues start with 'z' (base58btc) or 'u' (base64url)
+    if (!proof.proofValue.startsWith('z') && !proof.proofValue.startsWith('u')) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Verifies the hash chain for a single event.
+ *
+ * @param event - The current event to verify
+ * @param index - The index of the event in the log
+ * @param previousEvent - The previous event in the log (undefined for first event)
+ * @returns Object with chainValid boolean and any errors
+ */
+function verifyChain(event, index, previousEvent) {
+    const errors = [];
+    if (index === 0) {
+        // First event must NOT have previousEvent
+        if (event.previousEvent !== undefined) {
+            errors.push(`Event ${index}: First event must not have previousEvent field`);
+            return { chainValid: false, errors };
+        }
+    }
+    else {
+        // Subsequent events must have previousEvent that matches hash of prior event
+        if (event.previousEvent === undefined) {
+            errors.push(`Event ${index}: Missing previousEvent reference`);
+            return { chainValid: false, errors };
+        }
+        if (!previousEvent) {
+            errors.push(`Event ${index}: Cannot verify chain - previous event not provided`);
+            return { chainValid: false, errors };
+        }
+        // Compute the expected hash of the previous event
+        const expectedHash = computeDigestMultibase(serializeEntry(previousEvent));
+        if (event.previousEvent !== expectedHash) {
+            errors.push(`Event ${index}: Hash chain broken - previousEvent does not match hash of prior event`);
+            return { chainValid: false, errors };
+        }
+    }
+    return { chainValid: true, errors: [] };
+}
+/**
+ * Verifies a single event's proofs.
+ *
+ * @param event - The event to verify
+ * @param index - The index of the event in the log
+ * @param verifier - The proof verification function
+ * @param previousEvent - The previous event in the log (undefined for first event)
+ * @returns EventVerification result
+ */
+async function verifyEvent(event, index, verifier, previousEvent) {
+    const errors = [];
+    // Verify hash chain
+    const chainResult = verifyChain(event, index, previousEvent);
+    const chainValid = chainResult.chainValid;
+    errors.push(...chainResult.errors);
+    // Check that event has proofs
+    if (!event.proof || !Array.isArray(event.proof) || event.proof.length === 0) {
+        errors.push(`Event ${index}: No proofs found`);
+        return {
+            index,
+            type: event.type,
+            proofValid: false,
+            chainValid,
+            errors,
+        };
+    }
+    // Verify each proof
+    let allProofsValid = true;
+    const eventData = {
+        type: event.type,
+        data: event.data,
+        ...(event.previousEvent ? { previousEvent: event.previousEvent } : {}),
+    };
+    for (let proofIndex = 0; proofIndex < event.proof.length; proofIndex++) {
+        const proof = event.proof[proofIndex];
+        try {
+            const isValid = await verifier(proof, eventData);
+            if (!isValid) {
+                allProofsValid = false;
+                errors.push(`Event ${index}, Proof ${proofIndex}: Verification failed`);
+            }
+        }
+        catch (error) {
+            allProofsValid = false;
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            errors.push(`Event ${index}, Proof ${proofIndex}: ${message}`);
+        }
+    }
+    return {
+        index,
+        type: event.type,
+        proofValid: allProofsValid,
+        chainValid,
+        errors,
+    };
+}
+/**
+ * Verifies all proofs and hash chain integrity in an event log.
+ *
+ * This algorithm verifies:
+ * - Each event has at least one proof
+ * - Each proof is structurally valid (type, cryptosuite, proofValue, verificationMethod, proofPurpose)
+ * - Proofs use valid cryptosuite (eddsa-jcs-2022 or eddsa-rdfc-2022)
+ * - The first event has no previousEvent field
+ * - Each subsequent event's previousEvent matches the digestMultibase of the prior event
+ *
+ * For full cryptographic verification, provide a custom verifier function
+ * in the options that can resolve the public key from the verificationMethod.
+ *
+ * @param log - The event log to verify
+ * @param options - Optional verification options including custom verifier
+ * @returns VerificationResult with detailed per-event status including chainValid
+ *
+ * @example
+ * ```typescript
+ * // Basic structural and chain verification
+ * const result = await verifyEventLog(eventLog);
+ * if (result.verified) {
+ *   console.log('All proofs are valid and hash chain is intact');
+ * }
+ *
+ * // With custom cryptographic verifier
+ * const result = await verifyEventLog(eventLog, {
+ *   verifier: async (proof, data) => {
+ *     // Resolve public key and verify signature
+ *     const publicKey = await resolvePublicKey(proof.verificationMethod);
+ *     return verifyEdDsaSignature(data, proof.proofValue, publicKey);
+ *   }
+ * });
+ * ```
+ */
+export async function verifyEventLog(log, options) {
+    const errors = [];
+    const eventVerifications = [];
+    // Use custom verifier if provided, otherwise use default
+    const verifier = options?.verifier ?? defaultVerifier;
+    // Validate log structure
+    if (!log || !log.events) {
+        return {
+            verified: false,
+            errors: ['Invalid event log: missing events array'],
+            events: [],
+        };
+    }
+    if (!Array.isArray(log.events)) {
+        return {
+            verified: false,
+            errors: ['Invalid event log: events is not an array'],
+            events: [],
+        };
+    }
+    if (log.events.length === 0) {
+        return {
+            verified: false,
+            errors: ['Invalid event log: empty events array'],
+            events: [],
+        };
+    }
+    // Verify each event's proofs and hash chain
+    for (let i = 0; i < log.events.length; i++) {
+        const event = log.events[i];
+        const previousEvent = i > 0 ? log.events[i - 1] : undefined;
+        const eventResult = await verifyEvent(event, i, verifier, previousEvent);
+        eventVerifications.push(eventResult);
+        if (!eventResult.proofValid || !eventResult.chainValid) {
+            errors.push(...eventResult.errors);
+        }
+    }
+    // Determine overall verification status (both proofs AND chain must be valid)
+    const allProofsValid = eventVerifications.every(ev => ev.proofValid);
+    const allChainsValid = eventVerifications.every(ev => ev.chainValid);
+    return {
+        verified: allProofsValid && allChainsValid,
+        errors,
+        events: eventVerifications,
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * witnessEvent Algorithm
+ *
+ * Adds a witness proof to an existing log entry. The witness proof is
+ * appended to the event's proof array, preserving the original controller proof.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import type { LogEntry } from '../types';
+import type { WitnessService } from '../witnesses/WitnessService';
+/**
+ * Adds a witness proof to an event by calling a witness service.
+ *
+ * The witness service attests to the event's digest and returns a proof
+ * that is appended to the event's proof array. This does not replace
+ * the original controller proof - it adds an additional attestation.
+ *
+ * @param event - The log entry to witness
+ * @param witness - The witness service to use for attestation
+ * @returns A new LogEntry with the witness proof appended to the proof array
+ *
+ * @example
+ * ```typescript
+ * const httpWitness = new HttpWitness('https://witness.example.com');
+ * const witnessedEvent = await witnessEvent(myEvent, httpWitness);
+ * // witnessedEvent.proof now has 2 proofs: original + witness
+ * ```
+ */
+export declare function witnessEvent(event: LogEntry, witness: WitnessService): Promise<LogEntry>;

package/dist/cel/algorithms/witnessEvent.js

@@ -0,0 +1,75 @@
+/**
+ * witnessEvent Algorithm
+ *
+ * Adds a witness proof to an existing log entry. The witness proof is
+ * appended to the event's proof array, preserving the original controller proof.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import { computeDigestMultibase } from '../hash';
+/**
+ * Serializes a log entry to bytes for hashing.
+ * Uses deterministic JSON serialization with sorted keys.
+ */
+function serializeEntry(entry) {
+    // Create a canonical representation with sorted keys
+    const canonical = JSON.stringify(entry, (key, value) => {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return Object.keys(value)
+                .sort()
+                .reduce((sorted, k) => {
+                sorted[k] = value[k];
+                return sorted;
+            }, {});
+        }
+        return value;
+    });
+    return new TextEncoder().encode(canonical);
+}
+/**
+ * Adds a witness proof to an event by calling a witness service.
+ *
+ * The witness service attests to the event's digest and returns a proof
+ * that is appended to the event's proof array. This does not replace
+ * the original controller proof - it adds an additional attestation.
+ *
+ * @param event - The log entry to witness
+ * @param witness - The witness service to use for attestation
+ * @returns A new LogEntry with the witness proof appended to the proof array
+ *
+ * @example
+ * ```typescript
+ * const httpWitness = new HttpWitness('https://witness.example.com');
+ * const witnessedEvent = await witnessEvent(myEvent, httpWitness);
+ * // witnessedEvent.proof now has 2 proofs: original + witness
+ * ```
+ */
+export async function witnessEvent(event, witness) {
+    // Validate inputs
+    if (!event) {
+        throw new Error('Event is required');
+    }
+    if (!event.proof || event.proof.length === 0) {
+        throw new Error('Event must have at least one proof (controller proof)');
+    }
+    if (!witness) {
+        throw new Error('Witness service is required');
+    }
+    // Compute digest of the event
+    const eventBytes = serializeEntry(event);
+    const digestMultibase = computeDigestMultibase(eventBytes);
+    // Get witness proof
+    const witnessProof = await witness.witness(digestMultibase);
+    // Validate witness proof has required fields
+    if (!witnessProof.type || !witnessProof.cryptosuite || !witnessProof.proofValue) {
+        throw new Error('Invalid witness proof: missing required fields (type, cryptosuite, proofValue)');
+    }
+    if (!witnessProof.witnessedAt) {
+        throw new Error('Invalid witness proof: missing witnessedAt timestamp');
+    }
+    // Return new event with witness proof appended (immutable - don't modify input)
+    return {
+        ...event,
+        proof: [...event.proof, witnessProof],
+    };
+}

package/dist/cel/cli/create.d.ts

@@ -0,0 +1,36 @@
+#!/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]
+ */
+/**
+ * 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;
+}
+/**
+ * Execute the create command
+ */
+export declare function createCommand(flags: CreateFlags): Promise<CreateResult>;