@originals/sdk 1.5.0 → 1.6.0

package/dist/cel/serialization/json.js

@@ -0,0 +1,180 @@
+/**
+ * JSON Serialization for CEL Event Logs
+ *
+ * Provides serialization and parsing of EventLog objects to/from JSON format.
+ * Uses deterministic key ordering for consistent hashes.
+ */
+/**
+ * Sort object keys recursively for deterministic JSON output.
+ * This ensures consistent serialization for hash computations.
+ */
+function sortKeys(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sortKeys);
+    }
+    if (typeof obj === 'object') {
+        const sorted = {};
+        const keys = Object.keys(obj).sort();
+        for (const key of keys) {
+            sorted[key] = sortKeys(obj[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) {
+    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) {
+    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;
+}
+/**
+ * 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) {
+    if (!json || typeof json !== 'string') {
+        throw new Error('Cannot parse null, undefined, or non-string value');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON: ${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/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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/dist/cel/types.js

@@ -0,0 +1,7 @@
+/**
+ * CEL (Cryptographic Event Log) Types
+ *
+ * Based on W3C CCG CEL Specification v0.1
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+export {};

package/dist/cel/witnesses/BitcoinWitness.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 declare 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);
+}
+/**
+ * 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 declare class BitcoinWitness implements WitnessService {
+    private readonly bitcoinManager;
+    private readonly feeRate?;
+    private readonly verificationMethod;
+    /**
+     * Creates a new BitcoinWitness instance
+     *
+     * @param bitcoinManager - BitcoinManager instance configured with an ordinals provider
+     * @param options - Optional configuration options
+     */
+    constructor(bitcoinManager: BitcoinManager, options?: BitcoinWitnessOptions);
+    /**
+     * 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
+     */
+    witness(digestMultibase: string): Promise<BitcoinWitnessProof>;
+    /**
+     * Gets the fee rate configured for this witness (if any)
+     */
+    get configuredFeeRate(): number | undefined;
+}

package/dist/cel/witnesses/BitcoinWitness.js

@@ -0,0 +1,116 @@
+/**
+ * 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/
+ */
+/**
+ * Error thrown when the Bitcoin witness service fails
+ */
+export class BitcoinWitnessError extends Error {
+    constructor(message, digest, cause) {
+        super(message);
+        this.name = 'BitcoinWitnessError';
+        this.digest = digest;
+        this.cause = cause;
+    }
+}
+/**
+ * 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 {
+    /**
+     * Creates a new BitcoinWitness instance
+     *
+     * @param bitcoinManager - BitcoinManager instance configured with an ordinals provider
+     * @param options - Optional configuration options
+     */
+    constructor(bitcoinManager, options = {}) {
+        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) {
+        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 = {
+                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() {
+        return this.feeRate;
+    }
+}

package/dist/cel/witnesses/HttpWitness.d.ts

@@ -0,0 +1,79 @@
+/**
+ * HttpWitness - HTTP-based witness service for CEL event logs
+ *
+ * Implements the WitnessService interface for HTTP-based witness endpoints.
+ * Used primarily for the did:webvh layer to obtain third-party attestations
+ * from remote witness services.
+ *
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+import type { WitnessProof } from '../types';
+import type { WitnessService } from './WitnessService';
+/**
+ * Configuration options for HttpWitness
+ */
+export interface HttpWitnessOptions {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (for testing or alternative HTTP clients) */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Error thrown when the HTTP witness service is unavailable or returns an error
+ */
+export declare class HttpWitnessError extends Error {
+    /** HTTP status code if available */
+    readonly statusCode?: number;
+    /** Response body if available */
+    readonly responseBody?: string;
+    /** The witness URL that failed */
+    readonly witnessUrl: string;
+    constructor(message: string, witnessUrl: string, statusCode?: number, responseBody?: string);
+}
+/**
+ * HTTP-based witness service implementation
+ *
+ * Posts digestMultibase to a witness endpoint and parses the WitnessProof response.
+ *
+ * @example
+ * ```typescript
+ * const witness = new HttpWitness('https://witness.example.com/api/attest');
+ * const proof = await witness.witness('uEiD...');
+ * console.log(proof.witnessedAt); // ISO timestamp of attestation
+ * ```
+ */
+export declare class HttpWitness implements WitnessService {
+    private readonly witnessUrl;
+    private readonly timeout;
+    private readonly headers;
+    private readonly fetchFn;
+    /**
+     * Creates a new HttpWitness instance
+     *
+     * @param witnessUrl - The URL of the witness endpoint to POST to
+     * @param options - Optional configuration options
+     */
+    constructor(witnessUrl: string, options?: HttpWitnessOptions);
+    /**
+     * Witnesses a digest by posting to the HTTP endpoint
+     *
+     * @param digestMultibase - The Multibase-encoded digest to witness
+     * @returns A WitnessProof containing the attestation and witnessedAt timestamp
+     * @throws HttpWitnessError if the witness service is unavailable or returns an error
+     */
+    witness(digestMultibase: string): Promise<WitnessProof>;
+    /**
+     * Validates that the response data is a valid WitnessProof
+     *
+     * @param data - The parsed JSON response
+     * @returns A validated WitnessProof
+     * @throws HttpWitnessError if the response is not a valid WitnessProof
+     */
+    private validateWitnessProof;
+    /**
+     * Gets the witness URL this instance is configured to use
+     */
+    get url(): string;
+}