@originals/sdk 1.8.0 → 1.8.2

package/src/resources/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Resource types for the Originals SDK ResourceManager.
+ * 
+ * Resources in the Originals protocol are immutable, content-addressed entities
+ * that can be versioned through a linked hash chain.
+ */
+
+import { AssetResource } from '../types/common';
+
+/**
+ * Supported resource types for categorization
+ */
+export type ResourceType = 
+  | 'image'
+  | 'text'
+  | 'code'
+  | 'data'
+  | 'audio'
+  | 'video'
+  | 'document'
+  | 'binary'
+  | 'other';
+
+/**
+ * Options for creating a new resource
+ */
+export interface ResourceOptions {
+  /** Logical resource ID (optional - will be generated if not provided) */
+  id?: string;
+  
+  /** Resource type category */
+  type: ResourceType;
+  
+  /** MIME content type (e.g., 'text/plain', 'image/png') */
+  contentType: string;
+  
+  /** Optional URL if resource is externally hosted */
+  url?: string;
+  
+  /** Optional description of the resource */
+  description?: string;
+  
+  /** Maximum allowed size in bytes (optional, uses default if not specified) */
+  maxSize?: number;
+}
+
+/**
+ * Options for updating an existing resource
+ */
+export interface ResourceUpdateOptions {
+  /** New content type (optional - inherits from previous version if not specified) */
+  contentType?: string;
+  
+  /** Description of changes made in this version */
+  changes?: string;
+}
+
+/**
+ * Result of resource validation
+ */
+export interface ResourceValidationResult {
+  /** Whether the resource is valid */
+  valid: boolean;
+  
+  /** Array of error messages if validation failed */
+  errors: string[];
+  
+  /** Array of warning messages (non-fatal issues) */
+  warnings: string[];
+}
+
+/**
+ * A resource with its content and metadata
+ */
+export interface Resource extends AssetResource {
+  /** The actual content (for in-memory resources) */
+  content?: string;
+  
+  /** Binary content as base64-encoded string */
+  contentBase64?: string;
+  
+  /** Description of the resource */
+  description?: string;
+}
+
+/**
+ * Complete history of a resource including all versions
+ */
+export interface ResourceVersionHistory {
+  /** Logical resource ID (stable across all versions) */
+  resourceId: string;
+  
+  /** All versions in chronological order (oldest first) */
+  versions: Resource[];
+  
+  /** The current (latest) version */
+  currentVersion: Resource;
+  
+  /** Total number of versions */
+  versionCount: number;
+}
+
+/**
+ * Configuration for the ResourceManager
+ */
+export interface ResourceManagerConfig {
+  /** Default maximum resource size in bytes (default: 10MB) */
+  defaultMaxSize?: number;
+  
+  /** Whether to store content in memory (default: true) */
+  storeContent?: boolean;
+  
+  /** Allowed MIME types (if empty, all types allowed) */
+  allowedContentTypes?: string[];
+  
+  /** Whether to enable strict MIME type validation (default: true) */
+  strictMimeValidation?: boolean;
+}
+
+/**
+ * Common MIME types and their resource type mappings
+ */
+export const MIME_TYPE_MAP: Record<string, ResourceType> = {
+  // Images
+  'image/png': 'image',
+  'image/jpeg': 'image',
+  'image/gif': 'image',
+  'image/webp': 'image',
+  'image/svg+xml': 'image',
+  'image/bmp': 'image',
+  'image/tiff': 'image',
+  
+  // Text
+  'text/plain': 'text',
+  'text/html': 'text',
+  'text/css': 'text',
+  'text/csv': 'text',
+  'text/markdown': 'text',
+  
+  // Code
+  'text/javascript': 'code',
+  'application/javascript': 'code',
+  'text/typescript': 'code',
+  'application/typescript': 'code',
+  'text/x-python': 'code',
+  'application/x-python-code': 'code',
+  'text/x-rust': 'code',
+  'text/x-go': 'code',
+  'text/x-java': 'code',
+  'text/x-c': 'code',
+  'text/x-cpp': 'code',
+  
+  // Data formats
+  'application/json': 'data',
+  'application/xml': 'data',
+  'text/xml': 'data',
+  'application/yaml': 'data',
+  'text/yaml': 'data',
+  'application/toml': 'data',
+  
+  // Documents
+  'application/pdf': 'document',
+  'application/msword': 'document',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'document',
+  'application/vnd.ms-excel': 'document',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'document',
+  'application/vnd.ms-powerpoint': 'document',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'document',
+  
+  // Audio
+  'audio/mpeg': 'audio',
+  'audio/mp3': 'audio',
+  'audio/wav': 'audio',
+  'audio/ogg': 'audio',
+  'audio/webm': 'audio',
+  'audio/flac': 'audio',
+  
+  // Video
+  'video/mp4': 'video',
+  'video/webm': 'video',
+  'video/ogg': 'video',
+  'video/quicktime': 'video',
+  'video/x-msvideo': 'video',
+  
+  // Binary
+  'application/octet-stream': 'binary',
+  'application/zip': 'binary',
+  'application/gzip': 'binary',
+  'application/x-tar': 'binary',
+  'application/wasm': 'binary',
+};
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_RESOURCE_CONFIG: Required<ResourceManagerConfig> = {
+  defaultMaxSize: 10 * 1024 * 1024, // 10MB
+  storeContent: true,
+  allowedContentTypes: [],
+  strictMimeValidation: true,
+};
+

package/src/storage/LocalStorageAdapter.ts

@@ -0,0 +1,64 @@
+// Local adapter is optional in this environment; keeping implementation but avoid Node typings
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { GetObjectResult, LocalStorageAdapterOptions, StorageAdapter } from './StorageAdapter';
+
+export class LocalStorageAdapter implements StorageAdapter {
+  private baseDir: string;
+  private baseUrl?: string;
+
+  constructor(options: LocalStorageAdapterOptions) {
+    this.baseDir = options.baseDir;
+    this.baseUrl = options.baseUrl;
+  }
+
+  private resolvePath(domain: string, objectPath: string): string {
+    const safeDomain = domain.replace(/[^a-zA-Z0-9.-]/g, '_');
+    const cleanPath = objectPath.replace(/^\/+/, '');
+    return path.join(this.baseDir, safeDomain, cleanPath);
+  }
+
+  private toUrl(domain: string, objectPath: string): string {
+    const cleanPath = objectPath.replace(/^\/+/, '');
+    if (this.baseUrl) {
+      const trimmed = this.baseUrl.replace(/\/$/, '');
+      return `${trimmed}/${domain}/${cleanPath}`;
+    }
+    return `file://${this.resolvePath(domain, cleanPath)}`;
+  }
+
+  async putObject(domain: string, objectPath: string, content: Uint8Array | string): Promise<string> {
+    const fullPath = this.resolvePath(domain, objectPath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    const data = typeof content === 'string' ? Buffer.from(content) : Buffer.from(content);
+    await fs.writeFile(fullPath, data);
+    return this.toUrl(domain, objectPath);
+  }
+
+  async getObject(domain: string, objectPath: string): Promise<GetObjectResult | null> {
+    const fullPath = this.resolvePath(domain, objectPath);
+    try {
+      const content = await fs.readFile(fullPath);
+      return { content: new Uint8Array(content) };
+    } catch (e: unknown) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+      const error = e as any;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      if (error && error.code === 'ENOENT') return null;
+      throw e;
+    }
+  }
+
+  async exists(domain: string, objectPath: string): Promise<boolean> {
+    const fullPath = this.resolvePath(domain, objectPath);
+    try {
+      await fs.access(fullPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+

package/src/storage/MemoryStorageAdapter.ts

@@ -0,0 +1,29 @@
+import { GetObjectResult, StorageAdapter } from './StorageAdapter';
+
+type DomainPath = string;
+
+const globalStore: Map<DomainPath, Uint8Array> = new Map();
+
+function key(domain: string, objectPath: string): string {
+  const cleanPath = objectPath.replace(/^\/+/, '');
+  return `${domain}::${cleanPath}`;
+}
+
+export class MemoryStorageAdapter implements StorageAdapter {
+  putObject(domain: string, objectPath: string, content: Uint8Array | string): Promise<string> {
+    const data = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+    globalStore.set(key(domain, objectPath), data);
+    return Promise.resolve(`mem://${domain}/${objectPath.replace(/^\/+/, '')}`);
+  }
+
+  getObject(domain: string, objectPath: string): Promise<GetObjectResult | null> {
+    const stored = globalStore.get(key(domain, objectPath));
+    if (!stored) return Promise.resolve(null);
+    return Promise.resolve({ content: stored });
+  }
+
+  exists(domain: string, objectPath: string): Promise<boolean> {
+    return Promise.resolve(globalStore.has(key(domain, objectPath)));
+  }
+}
+

package/src/storage/StorageAdapter.ts

@@ -0,0 +1,25 @@
+export interface PutOptions {
+  contentType?: string;
+}
+
+export interface GetObjectResult {
+  content: Uint8Array;
+  contentType?: string;
+}
+
+export interface StorageAdapter {
+  // Writes content at a path under a logical domain root and returns a public URL
+  putObject(domain: string, path: string, content: Uint8Array | string, options?: PutOptions): Promise<string>;
+
+  // Reads content from a path under a domain root
+  getObject(domain: string, path: string): Promise<GetObjectResult | null>;
+
+  // Checks whether a path exists
+  exists(domain: string, path: string): Promise<boolean>;
+}
+
+export interface LocalStorageAdapterOptions {
+  baseDir: string;
+  baseUrl?: string;
+}
+

package/src/storage/index.ts

@@ -0,0 +1,3 @@
+export * from './StorageAdapter';
+export * from './MemoryStorageAdapter';
+

package/src/types/bitcoin.ts

@@ -0,0 +1,98 @@
+// Bitcoin/Ordinals types
+export interface OrdinalsInscription {
+  satoshi: string; // Unique satoshi identifier
+  inscriptionId: string;
+  content: Buffer;
+  contentType: string;
+  txid: string;
+  vout: number;
+  blockHeight?: number;
+}
+
+export interface BitcoinTransaction {
+  txid: string;
+  vin: TransactionInput[];
+  vout: TransactionOutput[];
+  fee: number;
+  blockHeight?: number;
+  confirmations?: number;
+}
+
+export interface TransactionInput {
+  txid: string;
+  vout: number;
+  scriptSig?: string;
+  witness?: string[];
+}
+
+export interface TransactionOutput {
+  value: number; // satoshis
+  scriptPubKey: string;
+  address?: string;
+}
+
+export interface Utxo {
+  txid: string;
+  vout: number;
+  value: number; // satoshis
+  scriptPubKey?: string;
+  address?: string;
+  inscriptions?: string[]; // inscription ids located on this outpoint
+  locked?: boolean; // if true, cannot be spent due to wallet locks
+}
+
+/**
+ * Extended UTXO interface that tracks whether it contains an Ordinals resource (inscription)
+ */
+export interface ResourceUtxo extends Utxo {
+  /** True if this UTXO contains an inscription or other Ordinals resource */
+  hasResource?: boolean;
+}
+
+/**
+ * Strategy for selecting UTXOs
+ */
+export type UtxoSelectionStrategy = 'minimize_change' | 'minimize_inputs' | 'optimize_size';
+
+/**
+ * Options for resource-aware UTXO selection
+ */
+export interface ResourceUtxoSelectionOptions {
+  /** Required amount in satoshis */
+  requiredAmount: number;
+  /** Fee rate in satoshis per vbyte */
+  feeRate: number;
+  /** Allow using UTXOs that contain resources (default: false) */
+  allowResourceUtxos?: boolean;
+  /** Prefer older UTXOs (default: false) */
+  preferOlder?: boolean;
+  /** Prefer UTXOs with value closer to required amount (default: false) */
+  preferCloserAmount?: boolean;
+  /** List of UTXO IDs to avoid using (format: "txid:vout") */
+  avoidUtxoIds?: string[];
+}
+
+/**
+ * Result of resource-aware UTXO selection
+ */
+export interface ResourceUtxoSelectionResult {
+  /** Selected UTXOs for the transaction */
+  selectedUtxos: ResourceUtxo[];
+  /** Total value of selected UTXOs */
+  totalSelectedValue: number;
+  /** Estimated transaction fee in satoshis */
+  estimatedFee: number;
+  /** Change amount in satoshis (0 if less than dust) */
+  changeAmount: number;
+}
+
+export const DUST_LIMIT_SATS = 546;
+
+export interface KeyPair {
+  privateKey: string; // multibase encoded
+  publicKey: string;  // multibase encoded
+}
+
+export type KeyType = 'ES256K' | 'Ed25519' | 'ES256';
+
+

package/src/types/common.ts

@@ -0,0 +1,92 @@
+import { StorageAdapter, FeeOracleAdapter, OrdinalsProvider } from '../adapters';
+import { TelemetryHooks } from '../utils/telemetry';
+import type { LogLevel, LogOutput } from '../utils/Logger';
+import type { EventLoggingConfig } from '../utils/EventLogger';
+import type { WebVHNetworkName } from './network';
+
+// Base types for the Originals protocol
+export type LayerType = 'did:peer' | 'did:webvh' | 'did:btco';
+
+export interface OriginalsConfig {
+  network: 'mainnet' | 'regtest' | 'signet';
+  bitcoinRpcUrl?: string;
+  defaultKeyType: 'ES256K' | 'Ed25519' | 'ES256';
+  keyStore?: KeyStore;
+  enableLogging?: boolean;
+  // WebVH network selection (defaults to 'pichu' - production)
+  webvhNetwork?: WebVHNetworkName;
+  // Optional pluggable adapters
+  storageAdapter?: StorageAdapter;
+  feeOracle?: FeeOracleAdapter;
+  ordinalsProvider?: OrdinalsProvider;
+  // Optional telemetry hooks
+  telemetry?: TelemetryHooks;
+  // Enhanced logging configuration
+  logging?: {
+    level?: LogLevel;
+    outputs?: LogOutput[];
+    includeTimestamps?: boolean;
+    includeContext?: boolean;
+    eventLogging?: EventLoggingConfig;
+    sanitizeLogs?: boolean; // Remove sensitive data
+  };
+  // Metrics configuration
+  metrics?: {
+    enabled?: boolean;
+    exportFormat?: 'json' | 'prometheus';
+    collectCache?: boolean;
+  };
+}
+
+export interface AssetResource {
+  id: string;                      // Logical resource ID (stable across versions)
+  type: string;                    // 'image', 'text', 'code', 'data', etc.
+  url?: string;
+  content?: string;
+  contentType: string;
+  hash: string;                    // Content hash (unique per version)
+  size?: number;
+  version?: number;                // Version number (default 1)
+  previousVersionHash?: string;    // Link to previous version (by content hash)
+  createdAt?: string;              // ISO timestamp of when this version was created
+}
+
+export interface KeyStore {
+  getPrivateKey(verificationMethodId: string): Promise<string | null>;
+  setPrivateKey(verificationMethodId: string, privateKey: string): Promise<void>;
+}
+
+/**
+ * External signer interface for DID operations (compatible with didwebvh-ts)
+ * This allows integration with external key management systems like Turnkey
+ */
+export interface ExternalSigner {
+  /**
+   * Sign data and return a proof value
+   * @param input - The signing input containing document and proof
+   * @returns The proof value (typically multibase-encoded signature)
+   */
+  sign(input: { document: Record<string, unknown>; proof: Record<string, unknown> }): Promise<{ proofValue: string }>;
+  
+  /**
+   * Get the verification method ID for this signer
+   * @returns The verification method ID (e.g., "did:key:z6Mk...")
+   */
+  getVerificationMethodId(): string;
+}
+
+/**
+ * External verifier interface for DID operations (compatible with didwebvh-ts)
+ */
+export interface ExternalVerifier {
+  /**
+   * Verify a signature
+   * @param signature - The signature bytes
+   * @param message - The message bytes that were signed
+   * @param publicKey - The public key bytes
+   * @returns True if the signature is valid
+   */
+  verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+}
+
+

package/src/types/credentials.ts

@@ -0,0 +1,89 @@
+import { LayerType } from './common';
+
+// Verifiable Credentials types
+export interface VerifiableCredential {
+  '@context': string[];
+  type: string[];
+  id?: string;
+  issuer: string | Issuer;
+  issuanceDate: string;
+  expirationDate?: string;
+  credentialSubject: CredentialSubject;
+  credentialStatus?: CredentialStatus;
+  proof?: Proof | Proof[];
+}
+
+export interface Issuer {
+  id: string;
+  name?: string;
+}
+
+export interface CredentialSubject {
+  id?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+export interface CredentialStatus {
+  id: string;
+  type: string;
+}
+
+export interface Proof {
+  type: string;
+  created: string;
+  verificationMethod: string;
+  proofPurpose: string;
+  proofValue: string;
+}
+
+export interface VerifiablePresentation {
+  '@context': string[];
+  type: string[];
+  id?: string;
+  holder: string;
+  verifiableCredential: VerifiableCredential[];
+  proof?: Proof | Proof[];
+}
+
+export interface ResourceCreatedCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string;
+    resourceId: string;
+    resourceType: string;
+    createdAt: string;
+    creator: string;
+  };
+}
+
+export interface ResourceUpdatedCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string;
+    resourceId: string;
+    updatedAt: string;
+    updateReason?: string;
+  };
+}
+
+export interface ResourceMigratedCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string;
+    resourceId: string;
+    fromLayer: LayerType;
+    toLayer: LayerType;
+    migratedAt: string;
+    migrationReason?: string;
+  };
+}
+
+export interface KeyRecoveryCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string; // DID that was recovered
+    recoveredAt: string; // ISO 8601 timestamp
+    recoveryReason: string; // "key_compromise" or other reason
+    previousVerificationMethods: string[]; // IDs of compromised keys
+    newVerificationMethod: string; // ID of new key
+  };
+}
+
+

package/src/types/did.ts

@@ -0,0 +1,31 @@
+// W3C DID Document types
+export interface DIDDocument {
+  '@context': string[];
+  id: string;
+  verificationMethod?: VerificationMethod[];
+  authentication?: (string | VerificationMethod)[];
+  assertionMethod?: (string | VerificationMethod)[];
+  keyAgreement?: (string | VerificationMethod)[];
+  capabilityInvocation?: (string | VerificationMethod)[];
+  capabilityDelegation?: (string | VerificationMethod)[];
+  service?: ServiceEndpoint[];
+  controller?: string[];
+  alsoKnownAs?: string[];
+}
+
+export interface VerificationMethod {
+  id: string;
+  type: string;
+  controller: string;
+  publicKeyMultibase: string;
+  revoked?: string; // ISO 8601 timestamp when the key was revoked
+  compromised?: string; // ISO 8601 timestamp when the key was marked as compromised
+}
+
+export interface ServiceEndpoint {
+  id: string;
+  type: string;
+  serviceEndpoint: string | object;
+}
+
+

package/src/types/external-shims.d.ts

@@ -0,0 +1,53 @@
+declare module 'cbor-js' {
+  export function encode(value: unknown): ArrayBuffer | Uint8Array;
+  export function decode(buffer: ArrayBufferLike): unknown;
+  const _default: {
+    encode: typeof encode;
+    decode: typeof decode;
+  };
+  export default _default;
+}
+
+declare module 'multiformats/bases/base64' {
+  export const base64url: {
+    encode: (bytes: Uint8Array) => string;
+    decode: (s: string) => Uint8Array;
+  };
+}
+
+declare module 'jsonld';
+declare module 'b58';
+declare module '@aviarytech/did-peer' {
+  export interface ServiceEndpoint {
+    id: string;
+    type: string;
+    serviceEndpoint: string | Record<string, unknown>;
+    [key: string]: unknown;
+  }
+
+  export interface IDIDDocument {
+    '@context'?: string | string[];
+    id: string;
+    controller?: string | string[];
+    verificationMethod?: IDIDDocumentVerificationMethod[];
+    authentication?: Array<string | IDIDDocumentVerificationMethod>;
+    assertionMethod?: Array<string | IDIDDocumentVerificationMethod>;
+    keyAgreement?: Array<string | IDIDDocumentVerificationMethod>;
+    capabilityInvocation?: Array<string | IDIDDocumentVerificationMethod>;
+    capabilityDelegation?: Array<string | IDIDDocumentVerificationMethod>;
+    service?: ServiceEndpoint[];
+    [key: string]: unknown;
+  }
+
+  export type IDIDDocumentVerificationMethod = { id?: string; type: string; controller?: string; publicKeyMultibase?: string };
+  export function create(numalgo: number, authenticationKeys: IDIDDocumentVerificationMethod[], encryptionKeys?: IDIDDocumentVerificationMethod[], service?: ServiceEndpoint): Promise<string>;
+  export function createNumAlgo0(authenticationKey: IDIDDocumentVerificationMethod): Promise<string>;
+  export function createNumAlgo2(authenticationKeys: IDIDDocumentVerificationMethod[], encryptionKeys?: IDIDDocumentVerificationMethod[], service?: ServiceEndpoint[]): Promise<string>;
+  export function createNumAlgo4(authenticationKeys: IDIDDocumentVerificationMethod[], encryptionKeys?: IDIDDocumentVerificationMethod[], service?: ServiceEndpoint[]): Promise<string>;
+  export function resolve(did: string, repository?: Record<string, unknown>): Promise<IDIDDocument>;
+}
+
+// Global shims for non-DOM/node test environments
+declare const global: Record<string, unknown> & typeof globalThis;
+declare function setTimeout(handler: (...args: unknown[]) => void, timeout?: number, ...args: unknown[]): number;
+