@originals/sdk 1.1.0

package/src/did/WebVHManager.ts

@@ -0,0 +1,489 @@
+import { KeyManager } from './KeyManager';
+import { multikey } from '../crypto/Multikey';
+import { Ed25519Signer } from '../crypto/Signer';
+import { DIDDocument, KeyPair, ExternalSigner, ExternalVerifier } from '../types';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Type definitions for didwebvh-ts (to avoid module resolution issues)
+interface VerificationMethod {
+  id?: string;
+  type: string;
+  controller?: string;
+  publicKeyMultibase: string;
+  secretKeyMultibase?: string;
+  purpose?: 'authentication' | 'assertionMethod' | 'keyAgreement' | 'capabilityInvocation' | 'capabilityDelegation';
+}
+
+interface SigningInput {
+  document: Record<string, unknown>;
+  proof: Record<string, unknown>;
+}
+
+interface SigningOutput {
+  proofValue: string;
+}
+
+interface SignerOptions {
+  verificationMethod?: VerificationMethod | null;
+  useStaticId?: boolean;
+}
+
+interface Signer {
+  sign(input: SigningInput): Promise<SigningOutput>;
+  getVerificationMethodId(): string;
+}
+
+interface Verifier {
+  verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+}
+
+interface DIDLogEntry {
+  versionId: string;
+  versionTime: string;
+  parameters: Record<string, unknown>;
+  state: Record<string, unknown>;
+  proof?: Record<string, unknown>[];
+}
+
+type DIDLog = DIDLogEntry[];
+
+/**
+ * Adapter to use Originals SDK signers with didwebvh-ts
+ */
+class OriginalsWebVHSigner implements Signer, Verifier {
+  private privateKeyMultibase: string;
+  private signer: Ed25519Signer;
+  protected verificationMethod?: VerificationMethod | null;
+  protected useStaticId: boolean;
+  private prepareDataForSigning: (document: Record<string, unknown>, proof: Record<string, unknown>) => Promise<Uint8Array>;
+
+  constructor(
+    privateKeyMultibase: string,
+    verificationMethod: VerificationMethod,
+    prepareDataForSigning: (document: Record<string, unknown>, proof: Record<string, unknown>) => Promise<Uint8Array>,
+    options: SignerOptions = {}
+  ) {
+    this.privateKeyMultibase = privateKeyMultibase;
+    this.verificationMethod = options.verificationMethod || verificationMethod;
+    this.useStaticId = options.useStaticId || false;
+    this.signer = new Ed25519Signer();
+    this.prepareDataForSigning = prepareDataForSigning;
+  }
+
+  async sign(input: SigningInput): Promise<SigningOutput> {
+    // Prepare the data for signing using didwebvh-ts's canonical approach
+    const dataToSign = await this.prepareDataForSigning(input.document, input.proof);
+    
+    // Sign using our Ed25519 signer
+    const signature: Buffer = await this.signer.sign(
+      Buffer.from(dataToSign),
+      this.privateKeyMultibase
+    );
+
+    // Encode signature as multibase
+    const proofValue = multikey.encodeMultibase(signature);
+
+    return { proofValue };
+  }
+
+  async verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean> {
+    // Decode the public key to multibase format
+    const publicKeyMultibase = multikey.encodePublicKey(publicKey, 'Ed25519');
+    
+    // Verify using our Ed25519 signer
+    const messageBuffer: Buffer = Buffer.from(message);
+    const signatureBuffer: Buffer = Buffer.from(signature);
+    
+    return this.signer.verify(
+      messageBuffer,
+      signatureBuffer,
+      publicKeyMultibase
+    );
+  }
+
+  getVerificationMethodId(): string {
+    // didwebvh-ts requires verification method to be a did:key: identifier
+    // Extract the multibase key from the verification method
+    const publicKeyMultibase = this.verificationMethod?.publicKeyMultibase;
+    if (!publicKeyMultibase) {
+      throw new Error('Verification method must have publicKeyMultibase');
+    }
+    // Return as did:key format which didwebvh-ts expects
+    return `did:key:${publicKeyMultibase}`;
+  }
+}
+
+export interface CreateWebVHOptions {
+  domain: string;
+  keyPair?: KeyPair;
+  paths?: string[];
+  portable?: boolean;
+  outputDir?: string; // Directory to save the DID log (did.jsonl)
+  externalSigner?: ExternalSigner; // External signer (e.g., Privy integration)
+  externalVerifier?: ExternalVerifier; // External verifier
+  verificationMethods?: VerificationMethod[]; // Pre-configured verification methods
+  updateKeys?: string[]; // Pre-configured update keys (e.g., ["did:key:z6Mk..."])
+}
+
+export interface CreateWebVHResult {
+  did: string;
+  didDocument: DIDDocument;
+  log: DIDLog;
+  keyPair: KeyPair;
+  logPath?: string; // Path where the DID log was saved
+}
+
+/**
+ * WebVH DID Manager for creating and managing did:webvh identifiers
+ */
+export class WebVHManager {
+  private keyManager: KeyManager;
+
+  constructor() {
+    this.keyManager = new KeyManager();
+  }
+
+  /**
+   * Creates a new did:webvh DID with proper cryptographic signing
+   * @param options - Creation options including domain and optional key pair or external signer
+   * @returns The created DID, document, log, and key pair (if generated)
+   */
+  async createDIDWebVH(options: CreateWebVHOptions): Promise<CreateWebVHResult> {
+    const { 
+      domain, 
+      keyPair: providedKeyPair, 
+      paths = [], 
+      portable = false, 
+      outputDir,
+      externalSigner,
+      externalVerifier,
+      verificationMethods: providedVerificationMethods,
+      updateKeys: providedUpdateKeys
+    } = options;
+
+    // Dynamically import didwebvh-ts to avoid module resolution issues
+    const mod = await import('didwebvh-ts') as unknown as {
+      createDID: (options: Record<string, unknown>) => Promise<{
+        did: string;
+        doc: Record<string, unknown>;
+        log: DIDLog;
+      }>;
+      prepareDataForSigning: (
+        document: Record<string, unknown>,
+        proof: Record<string, unknown>
+      ) => Promise<Uint8Array>;
+    };
+    const { createDID, prepareDataForSigning } = mod;
+
+    // Runtime validation of imported module
+    if (typeof createDID !== 'function' || typeof prepareDataForSigning !== 'function') {
+      throw new Error('Failed to load didwebvh-ts: invalid module exports');
+    }
+
+    let signer: Signer | ExternalSigner;
+    let verifier: Verifier | ExternalVerifier;
+    let keyPair: KeyPair | undefined;
+    let verificationMethods: VerificationMethod[];
+    let updateKeys: string[];
+
+    // Use external signer if provided (e.g., Privy integration)
+    if (externalSigner) {
+      if (!providedVerificationMethods || providedVerificationMethods.length === 0) {
+        throw new Error('verificationMethods are required when using externalSigner');
+      }
+      if (!providedUpdateKeys || providedUpdateKeys.length === 0) {
+        throw new Error('updateKeys are required when using externalSigner');
+      }
+      
+      signer = externalSigner;
+      verifier = externalVerifier || externalSigner as any; // Use signer as verifier if not provided
+      verificationMethods = providedVerificationMethods;
+      updateKeys = providedUpdateKeys;
+      keyPair = undefined; // No key pair when using external signer
+    } else {
+      // Generate or use provided key pair (Ed25519 for did:webvh)
+      keyPair = providedKeyPair || await this.keyManager.generateKeyPair('Ed25519');
+
+      // Create verification methods
+      verificationMethods = [
+        {
+          type: 'Multikey',
+          publicKeyMultibase: keyPair.publicKey,
+        }
+      ];
+
+      // Create signer using our adapter
+      const internalSigner = new OriginalsWebVHSigner(
+        keyPair.privateKey,
+        verificationMethods[0],
+        prepareDataForSigning,
+        { verificationMethod: verificationMethods[0] }
+      );
+
+      signer = internalSigner;
+      verifier = internalSigner; // Use the same signer as verifier
+      updateKeys = [`did:key:${keyPair.publicKey}`]; // Use did:key format for authorization
+    }
+
+    // Create the DID using didwebvh-ts
+    const result = await createDID({
+      domain,
+      signer,
+      verifier,
+      updateKeys,
+      verificationMethods,
+      context: [
+        'https://www.w3.org/ns/did/v1',
+        'https://w3id.org/security/multikey/v1'
+      ],
+      paths,
+      portable,
+      authentication: ['#key-0'],
+      assertionMethod: ['#key-0'],
+    });
+
+    // Validate the returned DID document
+    if (!this.isDIDDocument(result.doc)) {
+      throw new Error('Invalid DID document returned from createDID');
+    }
+
+    // Save the log to did.jsonl if output directory is provided
+    let logPath: string | undefined;
+    if (outputDir) {
+      logPath = await this.saveDIDLog(result.did, result.log, outputDir);
+    }
+
+    return {
+      did: result.did,
+      didDocument: result.doc,
+      log: result.log,
+      keyPair: keyPair || { publicKey: '', privateKey: '' }, // Return empty keypair if using external signer
+      logPath,
+    };
+  }
+
+  /**
+   * Validates a path segment to prevent directory traversal attacks
+   * @param segment - Path segment to validate
+   * @returns true if valid, false otherwise
+   */
+  private isValidPathSegment(segment: string): boolean {
+    // Reject empty segments, dots, or segments with path separators
+    if (!segment || segment === '.' || segment === '..') {
+      return false;
+    }
+    
+    // Reject segments containing path separators or other dangerous characters
+    if (segment.includes('/') || segment.includes('\\') || segment.includes('\0')) {
+      return false;
+    }
+    
+    // Reject absolute paths (starting with / or drive letter on Windows)
+    if (path.isAbsolute(segment)) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Type guard to validate a DID document structure
+   * @param doc - Object to validate
+   * @returns true if the object is a valid DIDDocument
+   */
+  private isDIDDocument(doc: unknown): doc is DIDDocument {
+    if (!doc || typeof doc !== 'object') {
+      return false;
+    }
+    
+    const d = doc as Record<string, unknown>;
+    
+    // Check required fields
+    if (!Array.isArray(d['@context']) || d['@context'].length === 0) {
+      return false;
+    }
+    
+    if (typeof d.id !== 'string' || !d.id.startsWith('did:')) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Saves the DID log to the appropriate did.jsonl path
+   * @param did - The DID identifier
+   * @param log - The DID log to save
+   * @param baseDir - Base directory for saving (e.g., public/.well-known)
+   * @returns The full path where the log was saved
+   */
+  async saveDIDLog(did: string, log: DIDLog, baseDir: string): Promise<string> {
+    // Parse the DID to extract domain and path components
+    // Format: did:webvh:domain[:port]:path1:path2...
+    const didParts = did.split(':');
+    if (didParts.length < 3 || didParts[0] !== 'did' || didParts[1] !== 'webvh') {
+      throw new Error('Invalid did:webvh format');
+    }
+
+    // Extract path parts (everything after domain)
+    const pathParts = didParts.slice(3);
+
+    // Validate all path segments to prevent directory traversal
+    for (const segment of pathParts) {
+      if (!this.isValidPathSegment(segment)) {
+        throw new Error(`Invalid path segment in DID: "${segment}". Path segments cannot contain '.', '..', path separators, or be absolute paths.`);
+      }
+    }
+
+    // Extract and sanitize domain for filesystem safety
+    const rawDomain = decodeURIComponent(didParts[2]);
+    // Normalize: lowercase and replace any characters not in [a-z0-9._-] with '_'
+    const safeDomain = rawDomain
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]/g, '_');
+    
+    // Validate the sanitized domain (reject '..' and other dangerous patterns)
+    if (!this.isValidPathSegment(safeDomain)) {
+      throw new Error(`Invalid domain segment in DID: "${rawDomain}"`);
+    }
+
+    // Construct the file path with domain isolation
+    // For did:webvh:example.com:user:alice -> baseDir/did/example.com/user/alice/did.jsonl
+    // For did:webvh:example.com:alice -> baseDir/did/example.com/alice/did.jsonl
+    const segments = [safeDomain, ...pathParts];
+    const didPath = path.join(baseDir, 'did', ...segments, 'did.jsonl');
+
+    // Verify the resolved path is still within baseDir (defense in depth)
+    const resolvedBaseDir = path.resolve(baseDir);
+    const resolvedPath = path.resolve(didPath);
+    const relativePath = path.relative(resolvedBaseDir, resolvedPath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      throw new Error('Invalid DID path: resolved path is outside base directory');
+    }
+
+    // Create directories if they don't exist
+    const dirPath = path.dirname(didPath);
+    await fs.promises.mkdir(dirPath, { recursive: true });
+
+    // Convert log to JSONL format (one JSON object per line)
+    const jsonlContent = log.map((entry: DIDLogEntry) => JSON.stringify(entry)).join('\n');
+
+    // Write the log file
+    await fs.promises.writeFile(didPath, jsonlContent, 'utf8');
+
+    return didPath;
+  }
+
+  /**
+   * Loads a DID log from a did.jsonl file
+   * @param logPath - Path to the did.jsonl file
+   * @returns The loaded DID log
+   */
+  async loadDIDLog(logPath: string): Promise<DIDLog> {
+    const content = await fs.promises.readFile(logPath, 'utf8');
+    const lines = content.trim().split('\n');
+    return lines.map(line => JSON.parse(line));
+  }
+
+  /**
+   * Updates a DID:WebVH document
+   * @param did - The DID to update
+   * @param currentLog - The current DID log
+   * @param updates - Updates to apply to the DID document
+   * @param signer - The signer to use (must be authorized in updateKeys)
+   * @param verifier - Optional verifier
+   * @param outputDir - Optional directory to save the updated log
+   * @returns Updated DID document and log
+   */
+  async updateDIDWebVH(options: {
+    did: string;
+    currentLog: DIDLog;
+    updates: Partial<DIDDocument>;
+    signer: ExternalSigner | { privateKey: string; publicKey: string };
+    verifier?: ExternalVerifier;
+    outputDir?: string;
+  }): Promise<{ didDocument: DIDDocument; log: DIDLog; logPath?: string }> {
+    const { did, currentLog, updates, signer: providedSigner, verifier: providedVerifier, outputDir } = options;
+
+    // Dynamically import didwebvh-ts
+    const mod = await import('didwebvh-ts') as unknown as {
+      updateDID: (options: Record<string, unknown>) => Promise<{
+        doc: Record<string, unknown>;
+        log: DIDLog;
+      }>;
+      prepareDataForSigning: (
+        document: Record<string, unknown>,
+        proof: Record<string, unknown>
+      ) => Promise<Uint8Array>;
+    };
+    const { updateDID, prepareDataForSigning } = mod;
+
+    if (typeof updateDID !== 'function') {
+      throw new Error('Failed to load didwebvh-ts: invalid module exports');
+    }
+
+    let signer: Signer | ExternalSigner;
+    let verifier: Verifier | ExternalVerifier | undefined;
+
+    // Check if using external signer or internal keypair
+    if ('sign' in providedSigner && 'getVerificationMethodId' in providedSigner) {
+      // External signer
+      signer = providedSigner as ExternalSigner;
+      verifier = providedVerifier;
+    } else {
+      // Internal signer with keypair
+      const keyPair = providedSigner as { privateKey: string; publicKey: string };
+      const verificationMethod: VerificationMethod = {
+        type: 'Multikey',
+        publicKeyMultibase: keyPair.publicKey,
+      };
+      
+      const internalSigner = new OriginalsWebVHSigner(
+        keyPair.privateKey,
+        verificationMethod,
+        prepareDataForSigning,
+        { verificationMethod }
+      );
+      
+      signer = internalSigner;
+      verifier = internalSigner;
+    }
+
+    // Get the current document from the log
+    const currentEntry = currentLog[currentLog.length - 1];
+    const currentDoc = currentEntry.state as unknown as DIDDocument;
+
+    // Merge updates with current document
+    const updatedDoc = {
+      ...currentDoc,
+      ...updates,
+      id: did, // Ensure ID doesn't change
+    };
+
+    // Update the DID using didwebvh-ts
+    const result = await updateDID({
+      log: currentLog,
+      doc: updatedDoc,
+      signer,
+      verifier,
+    });
+
+    // Validate the returned DID document
+    if (!this.isDIDDocument(result.doc)) {
+      throw new Error('Invalid DID document returned from updateDID');
+    }
+
+    // Save the updated log if output directory is provided
+    let logPath: string | undefined;
+    if (outputDir) {
+      logPath = await this.saveDIDLog(did, result.log, outputDir);
+    }
+
+    return {
+      didDocument: result.doc,
+      log: result.log,
+      logPath,
+    };
+  }
+}

package/src/did/createBtcoDidDocument.ts

@@ -0,0 +1,59 @@
+import { DIDDocument, VerificationMethod } from '../types/did';
+import { multikey, MultikeyType } from '../crypto/Multikey';
+import { validateSatoshiNumber } from '../utils/satoshi-validation';
+
+export type BitcoinNetwork = 'mainnet' | 'regtest' | 'signet';
+
+interface CreateBtcoDidDocumentParams {
+	publicKey: Uint8Array;
+	keyType: MultikeyType;
+	controller?: string;
+}
+
+function getDidPrefix(network: BitcoinNetwork): string {
+	if (network === 'mainnet') return 'did:btco';
+	if (network === 'signet') return 'did:btco:sig';
+	if (network === 'regtest') return 'did:btco:reg';
+	throw new Error(`Unsupported Bitcoin network: ${network}`);
+}
+
+function buildVerificationMethod(did: string, params: CreateBtcoDidDocumentParams): VerificationMethod {
+	const fragment = '#0';
+	const id = `${did}${fragment}`;
+	const controller = params.controller ?? did;
+	return {
+		id,
+		type: 'Multikey',
+		controller,
+		publicKeyMultibase: multikey.encodePublicKey(params.publicKey, params.keyType)
+	};
+}
+
+export function createBtcoDidDocument(
+	satNumber: number | string,
+	network: BitcoinNetwork,
+	params: CreateBtcoDidDocumentParams
+): DIDDocument {
+	// Validate satNumber parameter at entry
+	const validation = validateSatoshiNumber(satNumber);
+	if (!validation.valid) {
+		throw new Error(`Invalid satoshi number: ${validation.error}`);
+	}
+
+	const did = `${getDidPrefix(network)}:${String(satNumber)}`;
+	const vm = buildVerificationMethod(did, params);
+
+	const document: DIDDocument = {
+		'@context': [
+			'https://www.w3.org/ns/did/v1',
+			'https://w3id.org/security/multikey/v1'
+		],
+		id: did,
+		verificationMethod: [vm],
+		authentication: [vm.id],
+		assertionMethod: [vm.id]
+	};
+
+	return document;
+}
+

package/src/did/providers/OrdinalsClientProviderAdapter.ts

@@ -0,0 +1,68 @@
+import type { ResourceProviderLike } from '../BtcoDidResolver';
+import { OrdinalsClient } from '../../bitcoin/OrdinalsClient';
+
+export interface OrdinalsClientProviderConfig {
+  baseUrl: string;
+  fetchFn?: (url: string, init?: RequestInit) => Promise<Response>;
+  timeout?: number;
+}
+
+export class OrdinalsClientProviderAdapter implements ResourceProviderLike {
+  private readonly config: OrdinalsClientProviderConfig;
+
+  constructor(private client: OrdinalsClient, configOrBaseUrl: string | OrdinalsClientProviderConfig) {
+    if (typeof configOrBaseUrl === 'string') {
+      this.config = { baseUrl: configOrBaseUrl };
+    } else {
+      this.config = configOrBaseUrl;
+    }
+  }
+
+  async getSatInfo(satNumber: string): Promise<{ inscription_ids: string[] }> {
+    return this.client.getSatInfo(satNumber);
+  }
+
+  async resolveInscription(inscriptionId: string): Promise<{ id: string; sat: number; content_type: string; content_url: string }> {
+    const base = (this.config.baseUrl || '').replace(/\/$/, '');
+    if (!base) {
+      throw new Error('OrdinalsClientProviderAdapter requires a baseUrl');
+    }
+
+    try {
+      // Use configurable fetch function or default to global fetch
+      const fetchFn = this.config.fetchFn || fetch;
+      const timeout = this.config.timeout || 10000; // 10 second default timeout
+
+      const fetchOptions: RequestInit = {
+        headers: { 'Accept': 'application/json' },
+        signal: AbortSignal.timeout(timeout)
+      };
+
+      const res = await fetchFn(`${base}/inscription/${inscriptionId}`, fetchOptions);
+      if (!res.ok) {
+        // Log warning but don't throw - allow graceful degradation
+        console.warn(`Failed to resolve inscription ${inscriptionId}: HTTP ${res.status}`);
+        throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+      }
+
+      const info: any = await res.json();
+      return {
+        id: info.inscription_id || inscriptionId,
+        sat: typeof info.sat === 'number' ? info.sat : Number(info.sat || 0),
+        content_type: info.content_type || 'text/plain',
+        content_url: info.content_url || `${base}/content/${inscriptionId}`
+      };
+    } catch (err: any) {
+      // Log error for debugging but re-throw for caller to handle
+      console.warn(`Failed to resolve inscription ${inscriptionId}:`, err.message || String(err));
+      throw new Error(`Failed to resolve inscription: ${inscriptionId}`);
+    }
+  }
+
+  async getMetadata(inscriptionId: string): Promise<any> {
+    return this.client.getMetadata(inscriptionId);
+  }
+}
+
+export default OrdinalsClientProviderAdapter;
+