@originals/sdk 1.4.3 → 1.5.0

package/dist/utils/telemetry.js

@@ -0,0 +1,24 @@
+export class StructuredError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'StructuredError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export function emitTelemetry(hooks, event) {
+    if (hooks && typeof hooks.onEvent === 'function') {
+        try {
+            hooks.onEvent({ level: 'info', ...event });
+        }
+        catch (_) { }
+    }
+}
+export function emitError(hooks, error) {
+    if (hooks && typeof hooks.onError === 'function') {
+        try {
+            hooks.onError(error);
+        }
+        catch (_) { }
+    }
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,5 @@
+import { DIDDocument, VerifiableCredential } from '../types';
+export declare function validateDID(did: string): boolean;
+export declare function validateCredential(vc: VerifiableCredential): boolean;
+export declare function validateDIDDocument(didDoc: DIDDocument): boolean;
+export declare function hashResource(content: Uint8Array): string;

package/dist/utils/validation.js

@@ -0,0 +1,98 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+export function validateDID(did) {
+    // Validate DID format according to W3C DID spec
+    const didRegex = /^did:([a-z0-9]+):(.*)/;
+    if (!didRegex.test(did)) {
+        return false;
+    }
+    const match = did.match(didRegex);
+    if (!match) {
+        return false;
+    }
+    const method = match[1];
+    // Validate supported methods
+    const supportedMethods = ['peer', 'webvh', 'btco'];
+    if (!supportedMethods.includes(method)) {
+        return false;
+    }
+    return true;
+}
+export function validateCredential(vc) {
+    // Validate VC structure according to W3C VC spec
+    if (!vc['@context'] || !Array.isArray(vc['@context'])) {
+        return false;
+    }
+    // Require VC v1 context presence
+    const contextValues = vc['@context'];
+    const hasVcV1 = contextValues.includes('https://www.w3.org/2018/credentials/v1');
+    if (!hasVcV1) {
+        return false;
+    }
+    if (!vc.type || !Array.isArray(vc.type)) {
+        return false;
+    }
+    if (!vc.type.includes('VerifiableCredential')) {
+        return false;
+    }
+    if (!vc.issuer || (!vc.issuanceDate)) {
+        return false;
+    }
+    // issuer must be a DID string or an object with DID id
+    const issuerIsValidDid = (iss) => {
+        if (typeof iss === 'string')
+            return validateDID(iss);
+        if (iss && typeof iss.id === 'string')
+            return validateDID(iss.id);
+        return false;
+    };
+    if (!issuerIsValidDid(vc.issuer)) {
+        return false;
+    }
+    // issuanceDate should be a valid ISO timestamp
+    if (typeof vc.issuanceDate !== 'string' || Number.isNaN(Date.parse(vc.issuanceDate))) {
+        return false;
+    }
+    if (!vc.credentialSubject) {
+        return false;
+    }
+    return true;
+}
+export function validateDIDDocument(didDoc) {
+    // Validate DID Document structure
+    if (!didDoc['@context'] || !Array.isArray(didDoc['@context'])) {
+        return false;
+    }
+    if (!didDoc.id || !validateDID(didDoc.id)) {
+        return false;
+    }
+    // Validate verification methods
+    if (didDoc.verificationMethod) {
+        for (const vm of didDoc.verificationMethod) {
+            if (!vm.id || !vm.type || !vm.controller || !vm.publicKeyMultibase) {
+                return false;
+            }
+            // controller should be a valid DID
+            if (typeof vm.controller !== 'string' || !validateDID(vm.controller)) {
+                return false;
+            }
+            // multibase key presence: require base58-btc multibase indicator 'z'
+            if (typeof vm.publicKeyMultibase !== 'string' || !vm.publicKeyMultibase.startsWith('z')) {
+                return false;
+            }
+        }
+    }
+    // If controller array present on the DID Document, validate entries are DIDs
+    if (Array.isArray(didDoc.controller)) {
+        const ctrls = didDoc.controller;
+        if (!ctrls.every((c) => typeof c === 'string' && validateDID(c))) {
+            return false;
+        }
+    }
+    return true;
+}
+export function hashResource(content) {
+    // Generate SHA-256 hash
+    const hash = sha256(content);
+    return bytesToHex(hash);
+}

package/dist/vc/CredentialManager.d.ts

@@ -0,0 +1,329 @@
+import { VerifiableCredential, VerifiablePresentation, CredentialSubject, OriginalsConfig, ExternalSigner, LayerType, AssetResource } from '../types';
+import { DIDManager } from '../did/DIDManager';
+/**
+ * Subject data for a ResourceCreated credential
+ */
+export interface ResourceCreatedSubject {
+    /** ID of the subject (typically the resource DID or asset DID) */
+    id: string;
+    /** Resource identifier */
+    resourceId: string;
+    /** Resource type (e.g., 'code', 'text', 'image') */
+    resourceType: string;
+    /** Content hash of the resource */
+    contentHash: string;
+    /** MIME content type */
+    contentType: string;
+    /** Creator DID */
+    creator: string;
+    /** Creation timestamp */
+    createdAt: string;
+}
+/**
+ * Subject data for a ResourceUpdated credential
+ */
+export interface ResourceUpdatedSubject {
+    /** ID of the subject (typically the asset DID) */
+    id: string;
+    /** Resource identifier */
+    resourceId: string;
+    /** Previous content hash */
+    previousHash: string;
+    /** New content hash */
+    newHash: string;
+    /** Previous version number */
+    fromVersion: number;
+    /** New version number */
+    toVersion: number;
+    /** Update timestamp */
+    updatedAt: string;
+    /** Optional description of changes */
+    updateReason?: string;
+}
+/**
+ * Subject data for a MigrationCompleted credential
+ */
+export interface MigrationSubject {
+    /** ID of the subject (typically the asset DID) */
+    id: string;
+    /** Source DID (before migration) */
+    sourceDid: string;
+    /** Target DID (after migration) */
+    targetDid?: string;
+    /** Layer migrated from */
+    fromLayer: LayerType;
+    /** Layer migrated to */
+    toLayer: LayerType;
+    /** Migration timestamp */
+    migratedAt: string;
+    /** Transaction ID (for Bitcoin migrations) */
+    transactionId?: string;
+    /** Inscription ID (for Bitcoin migrations) */
+    inscriptionId?: string;
+    /** Satoshi number (for Bitcoin migrations) */
+    satoshi?: string;
+    /** Optional reason for migration */
+    migrationReason?: string;
+}
+/**
+ * Subject data for an OwnershipTransferred credential
+ */
+export interface OwnershipSubject {
+    /** ID of the subject (typically the asset DID) */
+    id: string;
+    /** Previous owner DID or address */
+    previousOwner: string;
+    /** New owner DID or address */
+    newOwner: string;
+    /** Transfer timestamp */
+    transferredAt: string;
+    /** Transaction ID for the transfer */
+    transactionId: string;
+    /** Satoshi number of the inscription */
+    satoshi?: string;
+    /** Optional transfer reason or notes */
+    transferReason?: string;
+}
+/**
+ * Options for creating credentials with chaining
+ */
+export interface CredentialChainOptions {
+    /** Previous credential ID to chain from */
+    previousCredentialId?: string;
+    /** Hash of the previous credential for verification */
+    previousCredentialHash?: string;
+    /** Optional expiration date */
+    expirationDate?: string;
+    /** Optional credential status information */
+    credentialStatus?: {
+        id: string;
+        type: string;
+    };
+}
+/**
+ * Options for BBS+ selective disclosure
+ */
+export interface SelectiveDisclosureOptions {
+    /** JSON Pointer paths to fields that must always be disclosed */
+    mandatoryPointers: string[];
+    /** JSON Pointer paths to fields the holder can selectively disclose */
+    selectivePointers?: string[];
+}
+/**
+ * Result of creating a derived proof with selective disclosure
+ */
+export interface DerivedProofResult {
+    /** The credential with derived proof */
+    credential: VerifiableCredential;
+    /** Fields that were disclosed */
+    disclosedFields: string[];
+    /** Fields that were hidden */
+    hiddenFields: string[];
+}
+export declare class CredentialManager {
+    private config;
+    private didManager?;
+    constructor(config: OriginalsConfig, didManager?: DIDManager | undefined);
+    createResourceCredential(type: 'ResourceCreated' | 'ResourceUpdated' | 'ResourceMigrated', subject: CredentialSubject, issuer: string): Promise<VerifiableCredential>;
+    signCredential(credential: VerifiableCredential, privateKeyMultibase: string, verificationMethod: string): Promise<VerifiableCredential>;
+    /**
+     * Sign a credential using an external signer (e.g., hardware wallet, Turnkey)
+     * @param credential - The unsigned credential
+     * @param signer - External signer implementation
+     * @returns Signed verifiable credential
+     */
+    signCredentialWithExternalSigner(credential: VerifiableCredential, signer: ExternalSigner): Promise<VerifiableCredential>;
+    verifyCredential(credential: VerifiableCredential): Promise<boolean>;
+    createPresentation(credentials: VerifiableCredential[], holder: string): Promise<VerifiablePresentation>;
+    private generateProofValue;
+    private getSigner;
+    private resolveVerificationMethodMultibase;
+    private decodeMultibase;
+    /**
+     * Issue a ResourceCreated credential for a newly created resource
+     *
+     * @param resource - The created resource
+     * @param assetDid - The DID of the asset containing the resource
+     * @param creatorDid - The DID of the creator
+     * @param chainOptions - Optional chaining options for linking to previous credentials
+     * @returns Unsigned verifiable credential
+     *
+     * @example
+     * ```typescript
+     * const credential = await credentialManager.issueResourceCredential(
+     *   resource,
+     *   'did:peer:abc...',
+     *   'did:peer:creator...'
+     * );
+     * // Sign the credential with your key
+     * const signed = await credentialManager.signCredential(credential, privateKey, vmId);
+     * ```
+     */
+    issueResourceCredential(resource: AssetResource, assetDid: string, creatorDid: string, chainOptions?: CredentialChainOptions): Promise<VerifiableCredential>;
+    /**
+     * Issue a ResourceUpdated credential for a resource version update
+     *
+     * @param resourceId - The logical resource ID
+     * @param assetDid - The DID of the asset
+     * @param previousHash - Hash of the previous version
+     * @param newHash - Hash of the new version
+     * @param fromVersion - Previous version number
+     * @param toVersion - New version number
+     * @param updaterDid - DID of the entity performing the update
+     * @param updateReason - Optional reason for the update
+     * @param chainOptions - Optional chaining options
+     * @returns Unsigned verifiable credential
+     *
+     * @example
+     * ```typescript
+     * const credential = await credentialManager.issueResourceUpdateCredential(
+     *   'main.js',
+     *   'did:webvh:example.com:asset',
+     *   'abc123...',
+     *   'def456...',
+     *   1,
+     *   2,
+     *   'did:webvh:example.com:user',
+     *   'Bug fix'
+     * );
+     * ```
+     */
+    issueResourceUpdateCredential(resourceId: string, assetDid: string, previousHash: string, newHash: string, fromVersion: number, toVersion: number, updaterDid: string, updateReason?: string, chainOptions?: CredentialChainOptions): Promise<VerifiableCredential>;
+    /**
+     * Issue a MigrationCompleted credential for layer migrations
+     *
+     * Records the migration of an asset between Originals layers (peer -> webvh -> btco).
+     *
+     * @param sourceDid - The source DID (before migration)
+     * @param targetDid - The target DID (after migration, if different)
+     * @param fromLayer - The source layer
+     * @param toLayer - The target layer
+     * @param issuerDid - The DID issuing this credential
+     * @param details - Optional migration details (transactionId, inscriptionId, satoshi)
+     * @param chainOptions - Optional chaining options
+     * @returns Unsigned verifiable credential
+     *
+     * @example
+     * ```typescript
+     * const credential = await credentialManager.issueMigrationCredential(
+     *   'did:peer:abc...',
+     *   'did:webvh:example.com:asset',
+     *   'did:peer',
+     *   'did:webvh',
+     *   'did:webvh:example.com:publisher'
+     * );
+     * ```
+     */
+    issueMigrationCredential(sourceDid: string, targetDid: string | undefined, fromLayer: LayerType, toLayer: LayerType, issuerDid: string, details?: {
+        transactionId?: string;
+        inscriptionId?: string;
+        satoshi?: string;
+        migrationReason?: string;
+    }, chainOptions?: CredentialChainOptions): Promise<VerifiableCredential>;
+    /**
+     * Issue an OwnershipTransferred credential for Bitcoin-anchored asset transfers
+     *
+     * Records the transfer of ownership of a did:btco asset to a new owner.
+     *
+     * @param assetDid - The DID of the asset being transferred
+     * @param previousOwner - The previous owner (DID or Bitcoin address)
+     * @param newOwner - The new owner (Bitcoin address)
+     * @param transactionId - The Bitcoin transaction ID
+     * @param issuerDid - The DID issuing this credential
+     * @param details - Optional additional details
+     * @param chainOptions - Optional chaining options
+     * @returns Unsigned verifiable credential
+     *
+     * @example
+     * ```typescript
+     * const credential = await credentialManager.issueOwnershipCredential(
+     *   'did:btco:12345',
+     *   'bc1q...oldowner',
+     *   'bc1q...newowner',
+     *   'abc123...txid',
+     *   'did:btco:12345'
+     * );
+     * ```
+     */
+    issueOwnershipCredential(assetDid: string, previousOwner: string, newOwner: string, transactionId: string, issuerDid: string, details?: {
+        satoshi?: string;
+        transferReason?: string;
+    }, chainOptions?: CredentialChainOptions): Promise<VerifiableCredential>;
+    /**
+     * Create a credential with optional chaining to a previous credential
+     *
+     * Credential chaining creates a verifiable provenance chain by linking
+     * credentials together through their IDs and hashes.
+     *
+     * @param type - The credential type
+     * @param subject - The credential subject
+     * @param issuer - The issuer DID
+     * @param chainOptions - Optional chaining options
+     * @returns Unsigned verifiable credential with chain metadata
+     */
+    private createCredentialWithChain;
+    /**
+     * Generate a unique credential ID
+     */
+    private generateCredentialId;
+    /**
+     * Compute the hash of a credential for chaining purposes
+     *
+     * @param credential - The credential to hash
+     * @returns SHA-256 hash of the canonicalized credential
+     */
+    computeCredentialHash(credential: VerifiableCredential): Promise<string>;
+    /**
+     * Verify a credential chain by checking all previous credential links
+     *
+     * @param credentials - Array of credentials in chain order (oldest first)
+     * @returns Verification result with chain integrity status
+     */
+    verifyCredentialChain(credentials: VerifiableCredential[]): Promise<{
+        valid: boolean;
+        errors: string[];
+        chainLength: number;
+    }>;
+    /**
+     * Prepare a credential for BBS+ selective disclosure
+     *
+     * This creates a base proof that can later be derived into a proof
+     * that selectively discloses only certain fields.
+     *
+     * Note: This requires BBS+ keys and is primarily used for privacy-preserving
+     * credential presentations.
+     *
+     * @param credential - The credential to prepare
+     * @param options - Selective disclosure options
+     * @returns The credential with BBS+ base proof metadata
+     */
+    prepareSelectiveDisclosure(credential: VerifiableCredential, options: SelectiveDisclosureOptions): Promise<{
+        credential: VerifiableCredential;
+        mandatoryPointers: string[];
+        selectivePointers: string[];
+    }>;
+    /**
+     * Create a derived proof with selective disclosure
+     *
+     * Given a credential with a BBS+ base proof, creates a derived proof
+     * that only reveals the specified fields.
+     *
+     * @param credential - The credential with BBS+ base proof
+     * @param fieldsToDisclose - JSON Pointer paths to disclose
+     * @param presentationHeader - Optional presentation-specific data
+     * @returns The credential with derived proof
+     */
+    deriveSelectiveProof(credential: VerifiableCredential, fieldsToDisclose: string[], presentationHeader?: Uint8Array): Promise<DerivedProofResult>;
+    /**
+     * Extract all field paths from a credential as JSON Pointers
+     */
+    private extractFieldPaths;
+    /**
+     * Get field value from credential using JSON Pointer
+     *
+     * @param credential - The credential to read from
+     * @param pointer - JSON Pointer path (e.g., /credentialSubject/name)
+     * @returns The value at the pointer path, or undefined if not found
+     */
+    getFieldByPointer(credential: VerifiableCredential, pointer: string): any;
+}