@originals/sdk 1.8.1 → 1.8.2

package/src/cel/witnesses/HttpWitness.ts

@@ -0,0 +1,241 @@
+/**
+ * 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 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
+  ) {
+    super(message);
+    this.name = 'HttpWitnessError';
+    this.witnessUrl = witnessUrl;
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+}
+
+/**
+ * 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 class HttpWitness implements WitnessService {
+  private readonly witnessUrl: string;
+  private readonly timeout: number;
+  private readonly headers: Record<string, string>;
+  private readonly fetchFn: typeof globalThis.fetch;
+  
+  /**
+   * 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 = {}) {
+    if (!witnessUrl || typeof witnessUrl !== 'string') {
+      throw new Error('witnessUrl must be a non-empty string');
+    }
+    
+    // Validate URL format
+    try {
+      new URL(witnessUrl);
+    } catch {
+      throw new Error(`Invalid witness URL: ${witnessUrl}`);
+    }
+    
+    this.witnessUrl = witnessUrl;
+    this.timeout = options.timeout ?? 30000;
+    this.headers = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      ...options.headers,
+    };
+    this.fetchFn = options.fetch ?? globalThis.fetch;
+  }
+  
+  /**
+   * 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
+   */
+  async witness(digestMultibase: string): Promise<WitnessProof> {
+    if (!digestMultibase || typeof digestMultibase !== 'string') {
+      throw new Error('digestMultibase must be a non-empty string');
+    }
+    
+    // Create abort controller for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    
+    try {
+      const response = await this.fetchFn(this.witnessUrl, {
+        method: 'POST',
+        headers: this.headers,
+        body: JSON.stringify({ digest: digestMultibase }),
+        signal: controller.signal,
+      });
+      
+      clearTimeout(timeoutId);
+      
+      // Handle non-OK responses
+      if (!response.ok) {
+        let responseBody: string | undefined;
+        try {
+          responseBody = await response.text();
+        } catch {
+          // Ignore body read errors
+        }
+        
+        throw new HttpWitnessError(
+          `Witness service returned ${response.status} ${response.statusText}`,
+          this.witnessUrl,
+          response.status,
+          responseBody
+        );
+      }
+      
+      // Parse response
+      let data: unknown;
+      try {
+        data = await response.json();
+      } catch {
+        throw new HttpWitnessError(
+          'Witness service returned invalid JSON response',
+          this.witnessUrl,
+          response.status
+        );
+      }
+      
+      // Validate WitnessProof structure
+      const proof = this.validateWitnessProof(data);
+      return proof;
+      
+    } catch (error) {
+      clearTimeout(timeoutId);
+      
+      // Re-throw HttpWitnessError as-is
+      if (error instanceof HttpWitnessError) {
+        throw error;
+      }
+      
+      // Handle abort/timeout
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new HttpWitnessError(
+          `Witness service request timed out after ${this.timeout}ms`,
+          this.witnessUrl
+        );
+      }
+      
+      // Handle network errors
+      if (error instanceof TypeError) {
+        throw new HttpWitnessError(
+          `Witness service unavailable: ${error.message}`,
+          this.witnessUrl
+        );
+      }
+      
+      // Re-throw other errors
+      throw new HttpWitnessError(
+        `Witness request failed: ${error instanceof Error ? error.message : String(error)}`,
+        this.witnessUrl
+      );
+    }
+  }
+  
+  /**
+   * 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(data: unknown): WitnessProof {
+    if (!data || typeof data !== 'object') {
+      throw new HttpWitnessError(
+        'Witness service returned invalid proof: expected object',
+        this.witnessUrl
+      );
+    }
+    
+    const proof = data as Record<string, unknown>;
+    
+    // Check required DataIntegrityProof fields
+    const requiredFields = ['type', 'cryptosuite', 'created', 'verificationMethod', 'proofPurpose', 'proofValue'];
+    for (const field of requiredFields) {
+      if (typeof proof[field] !== 'string') {
+        throw new HttpWitnessError(
+          `Witness service returned invalid proof: missing or invalid '${field}' field`,
+          this.witnessUrl
+        );
+      }
+    }
+    
+    // Check WitnessProof-specific field
+    if (typeof proof.witnessedAt !== 'string') {
+      throw new HttpWitnessError(
+        "Witness service returned invalid proof: missing or invalid 'witnessedAt' field",
+        this.witnessUrl
+      );
+    }
+    
+    return {
+      type: proof.type as string,
+      cryptosuite: proof.cryptosuite as string,
+      created: proof.created as string,
+      verificationMethod: proof.verificationMethod as string,
+      proofPurpose: proof.proofPurpose as string,
+      proofValue: proof.proofValue as string,
+      witnessedAt: proof.witnessedAt as string,
+    };
+  }
+  
+  /**
+   * Gets the witness URL this instance is configured to use
+   */
+  get url(): string {
+    return this.witnessUrl;
+  }
+}

package/src/cel/witnesses/WitnessService.ts

@@ -0,0 +1,51 @@
+/**
+ * WitnessService Interface
+ * 
+ * Defines a pluggable interface for witness services that attest to the
+ * existence of events at a point in time. Witnesses add trust anchors
+ * to event logs by providing third-party attestations.
+ * 
+ * @see https://w3c-ccg.github.io/cel-spec/
+ */
+
+import type { WitnessProof } from '../types';
+
+/**
+ * Interface for witness services that can attest to event digests.
+ * 
+ * Implementations might include:
+ * - HTTP-based witness services (for did:webvh layer)
+ * - Bitcoin timestamping services (for did:btco layer)
+ * - Notary services
+ * - Blockchain-based attestation services
+ * 
+ * @example
+ * ```typescript
+ * class MyHttpWitness implements WitnessService {
+ *   constructor(private witnessUrl: string) {}
+ *   
+ *   async witness(digestMultibase: string): Promise<WitnessProof> {
+ *     const response = await fetch(this.witnessUrl, {
+ *       method: 'POST',
+ *       body: JSON.stringify({ digest: digestMultibase })
+ *     });
+ *     return response.json();
+ *   }
+ * }
+ * ```
+ */
+export interface WitnessService {
+  /**
+   * Witnesses a digest and returns a proof of attestation.
+   * 
+   * The witness should:
+   * 1. Record the digest at the current point in time
+   * 2. Generate a cryptographic proof of the attestation
+   * 3. Include a witnessedAt timestamp in the proof
+   * 
+   * @param digestMultibase - The Multibase-encoded digest to witness (from computeDigestMultibase)
+   * @returns A WitnessProof containing the attestation and witnessedAt timestamp
+   * @throws Error if the witness service is unavailable or fails
+   */
+  witness(digestMultibase: string): Promise<WitnessProof>;
+}

package/src/cel/witnesses/index.ts

@@ -0,0 +1,11 @@
+/**
+ * CEL Witness Services
+ * 
+ * Pluggable witness interfaces and implementations for third-party attestations.
+ */
+
+export type { WitnessService } from './WitnessService';
+export { HttpWitness, HttpWitnessError } from './HttpWitness';
+export type { HttpWitnessOptions } from './HttpWitness';
+export { BitcoinWitness, BitcoinWitnessError } from './BitcoinWitness';
+export type { BitcoinWitnessOptions, BitcoinWitnessProof } from './BitcoinWitness';

package/src/contexts/credentials-v1.json

@@ -0,0 +1,237 @@
+{
+  "@context": {
+    "@version": 1.1,
+    "@protected": true,
+
+    "id": "@id",
+    "type": "@type",
+
+    "VerifiableCredential": {
+      "@id": "https://www.w3.org/2018/credentials#VerifiableCredential",
+      "@context": {
+        "@version": 1.1,
+        "@protected": true,
+
+        "id": "@id",
+        "type": "@type",
+
+        "cred": "https://www.w3.org/2018/credentials#",
+        "sec": "https://w3id.org/security#",
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+
+        "credentialSchema": {
+          "@id": "cred:credentialSchema",
+          "@type": "@id",
+          "@context": {
+            "@version": 1.1,
+            "@protected": true,
+
+            "id": "@id",
+            "type": "@type",
+
+            "cred": "https://www.w3.org/2018/credentials#",
+
+            "JsonSchemaValidator2018": "cred:JsonSchemaValidator2018"
+          }
+        },
+        "credentialStatus": {"@id": "cred:credentialStatus", "@type": "@id"},
+        "credentialSubject": {"@id": "cred:credentialSubject", "@type": "@id"},
+        "evidence": {"@id": "cred:evidence", "@type": "@id"},
+        "expirationDate": {"@id": "cred:expirationDate", "@type": "xsd:dateTime"},
+        "holder": {"@id": "cred:holder", "@type": "@id"},
+        "issued": {"@id": "cred:issued", "@type": "xsd:dateTime"},
+        "issuer": {"@id": "cred:issuer", "@type": "@id"},
+        "issuanceDate": {"@id": "cred:issuanceDate", "@type": "xsd:dateTime"},
+        "proof": {"@id": "sec:proof", "@type": "@id", "@container": "@graph"},
+        "refreshService": {
+          "@id": "cred:refreshService",
+          "@type": "@id",
+          "@context": {
+            "@version": 1.1,
+            "@protected": true,
+
+            "id": "@id",
+            "type": "@type",
+
+            "cred": "https://www.w3.org/2018/credentials#",
+
+            "ManualRefreshService2018": "cred:ManualRefreshService2018"
+          }
+        },
+        "termsOfUse": {"@id": "cred:termsOfUse", "@type": "@id"},
+        "validFrom": {"@id": "cred:validFrom", "@type": "xsd:dateTime"},
+        "validUntil": {"@id": "cred:validUntil", "@type": "xsd:dateTime"}
+      }
+    },
+
+    "VerifiablePresentation": {
+      "@id": "https://www.w3.org/2018/credentials#VerifiablePresentation",
+      "@context": {
+        "@version": 1.1,
+        "@protected": true,
+
+        "id": "@id",
+        "type": "@type",
+
+        "cred": "https://www.w3.org/2018/credentials#",
+        "sec": "https://w3id.org/security#",
+
+        "holder": {"@id": "cred:holder", "@type": "@id"},
+        "proof": {"@id": "sec:proof", "@type": "@id", "@container": "@graph"},
+        "verifiableCredential": {"@id": "cred:verifiableCredential", "@type": "@id", "@container": "@graph"}
+      }
+    },
+
+    "EcdsaSecp256k1Signature2019": {
+      "@id": "https://w3id.org/security#EcdsaSecp256k1Signature2019",
+      "@context": {
+        "@version": 1.1,
+        "@protected": true,
+
+        "id": "@id",
+        "type": "@type",
+
+        "sec": "https://w3id.org/security#",
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+
+        "challenge": "sec:challenge",
+        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
+        "domain": "sec:domain",
+        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
+        "jws": "sec:jws",
+        "nonce": "sec:nonce",
+        "proofPurpose": {
+          "@id": "sec:proofPurpose",
+          "@type": "@vocab",
+          "@context": {
+            "@version": 1.1,
+            "@protected": true,
+
+            "id": "@id",
+            "type": "@type",
+
+            "sec": "https://w3id.org/security#",
+
+            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
+            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
+          }
+        },
+        "proofValue": "sec:proofValue",
+        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
+      }
+    },
+
+    "EcdsaSecp256r1Signature2019": {
+      "@id": "https://w3id.org/security#EcdsaSecp256r1Signature2019",
+      "@context": {
+        "@version": 1.1,
+        "@protected": true,
+
+        "id": "@id",
+        "type": "@type",
+
+        "sec": "https://w3id.org/security#",
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+
+        "challenge": "sec:challenge",
+        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
+        "domain": "sec:domain",
+        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
+        "jws": "sec:jws",
+        "nonce": "sec:nonce",
+        "proofPurpose": {
+          "@id": "sec:proofPurpose",
+          "@type": "@vocab",
+          "@context": {
+            "@version": 1.1,
+            "@protected": true,
+
+            "id": "@id",
+            "type": "@type",
+
+            "sec": "https://w3id.org/security#",
+
+            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
+            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
+          }
+        },
+        "proofValue": "sec:proofValue",
+        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
+      }
+    },
+
+    "Ed25519Signature2018": {
+      "@id": "https://w3id.org/security#Ed25519Signature2018",
+      "@context": {
+        "@version": 1.1,
+        "@protected": true,
+
+        "id": "@id",
+        "type": "@type",
+
+        "sec": "https://w3id.org/security#",
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+
+        "challenge": "sec:challenge",
+        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
+        "domain": "sec:domain",
+        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
+        "jws": "sec:jws",
+        "nonce": "sec:nonce",
+        "proofPurpose": {
+          "@id": "sec:proofPurpose",
+          "@type": "@vocab",
+          "@context": {
+            "@version": 1.1,
+            "@protected": true,
+
+            "id": "@id",
+            "type": "@type",
+
+            "sec": "https://w3id.org/security#",
+
+            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
+            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
+          }
+        },
+        "proofValue": "sec:proofValue",
+        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
+      }
+    },
+
+    "RsaSignature2018": {
+      "@id": "https://w3id.org/security#RsaSignature2018",
+      "@context": {
+        "@version": 1.1,
+        "@protected": true,
+
+        "challenge": "sec:challenge",
+        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
+        "domain": "sec:domain",
+        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
+        "jws": "sec:jws",
+        "nonce": "sec:nonce",
+        "proofPurpose": {
+          "@id": "sec:proofPurpose",
+          "@type": "@vocab",
+          "@context": {
+            "@version": 1.1,
+            "@protected": true,
+
+            "id": "@id",
+            "type": "@type",
+
+            "sec": "https://w3id.org/security#",
+
+            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
+            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
+          }
+        },
+        "proofValue": "sec:proofValue",
+        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
+      }
+    },
+
+    "proof": {"@id": "https://w3id.org/security#proof", "@type": "@id", "@container": "@graph"}
+  }
+}

package/src/contexts/credentials-v2-examples.json

@@ -0,0 +1,5 @@
+{
+  "@context": {
+    "@vocab": "https://www.w3.org/ns/credentials/examples#"
+  }
+}