@originals/sdk 1.1.0

package/dist/utils/satoshi-validation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Maximum number of satoshis in Bitcoin's total supply (21 million BTC)
+ * 21,000,000 BTC * 100,000,000 satoshis/BTC = 2,100,000,000,000,000 satoshis
+ */
+export declare const MAX_SATOSHI_SUPPLY = 2100000000000000;
+/**
+ * Validation result interface for satoshi number validation
+ */
+export interface SatoshiValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validates a satoshi number for use in Bitcoin ordinals and did:btco DIDs.
+ *
+ * @param satoshi - The satoshi identifier to validate (string or number)
+ * @returns Validation result with descriptive error if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateSatoshiNumber('123456');
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export declare function validateSatoshiNumber(satoshi: string | number): SatoshiValidationResult;
+/**
+ * Parses a satoshi identifier from various formats and validates it.
+ *
+ * Supported formats:
+ * - Plain satoshi number: "123456"
+ * - did:btco DID: "did:btco:123456", "did:btco:test:123456", "did:btco:sig:123456"
+ * - Ordinal notation: "123456" (same as plain number, for future extensions)
+ *
+ * @param identifier - The identifier to parse
+ * @returns The extracted satoshi number
+ * @throws {StructuredError} If the identifier format is invalid or satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * const satoshi = parseSatoshiIdentifier('did:btco:123456');
+ * console.log(satoshi); // 123456
+ * ```
+ */
+export declare function parseSatoshiIdentifier(identifier: string): number;
+/**
+ * Validates a satoshi number and throws an error if invalid.
+ * Convenience wrapper around validateSatoshiNumber for code that expects exceptions.
+ *
+ * @param satoshi - The satoshi identifier to validate
+ * @throws {StructuredError} If the satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidSatoshi('123456'); // OK
+ * assertValidSatoshi(''); // throws StructuredError
+ * ```
+ */
+export declare function assertValidSatoshi(satoshi: string | number): void;

package/dist/utils/satoshi-validation.js

@@ -0,0 +1,156 @@
+import { StructuredError } from './telemetry';
+/**
+ * Maximum number of satoshis in Bitcoin's total supply (21 million BTC)
+ * 21,000,000 BTC * 100,000,000 satoshis/BTC = 2,100,000,000,000,000 satoshis
+ */
+export const MAX_SATOSHI_SUPPLY = 2100000000000000;
+/**
+ * Validates a satoshi number for use in Bitcoin ordinals and did:btco DIDs.
+ *
+ * @param satoshi - The satoshi identifier to validate (string or number)
+ * @returns Validation result with descriptive error if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateSatoshiNumber('123456');
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export function validateSatoshiNumber(satoshi) {
+    // Check for null, undefined, or empty string
+    if (satoshi === null || satoshi === undefined || satoshi === '') {
+        return {
+            valid: false,
+            error: 'Satoshi identifier cannot be null, undefined, or empty string'
+        };
+    }
+    // Convert to string for validation
+    const satoshiStr = String(satoshi).trim();
+    // Check for empty string after trimming
+    if (satoshiStr === '') {
+        return {
+            valid: false,
+            error: 'Satoshi identifier cannot be empty or whitespace-only string'
+        };
+    }
+    // Check for numeric format (must be all digits, no decimals, no scientific notation)
+    if (!/^[0-9]+$/.test(satoshiStr)) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier must be a non-negative integer (no decimals, no scientific notation, no non-numeric characters)'
+        };
+    }
+    // Convert to number for range validation
+    const satoshiNum = Number(satoshiStr);
+    // Check for valid number conversion
+    if (!Number.isFinite(satoshiNum)) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier must be a finite number'
+        };
+    }
+    // Check for decimals (would be truncated by Number())
+    if (satoshiNum !== Math.floor(satoshiNum)) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier cannot contain decimal places'
+        };
+    }
+    // Check for negative numbers
+    if (satoshiNum < 0) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier must be non-negative (>= 0)'
+        };
+    }
+    // Check for maximum supply range
+    if (satoshiNum > MAX_SATOSHI_SUPPLY) {
+        return {
+            valid: false,
+            error: `Satoshi identifier must be within Bitcoin's total supply (0 to ${MAX_SATOSHI_SUPPLY.toLocaleString()})`
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Parses a satoshi identifier from various formats and validates it.
+ *
+ * Supported formats:
+ * - Plain satoshi number: "123456"
+ * - did:btco DID: "did:btco:123456", "did:btco:test:123456", "did:btco:sig:123456"
+ * - Ordinal notation: "123456" (same as plain number, for future extensions)
+ *
+ * @param identifier - The identifier to parse
+ * @returns The extracted satoshi number
+ * @throws {StructuredError} If the identifier format is invalid or satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * const satoshi = parseSatoshiIdentifier('did:btco:123456');
+ * console.log(satoshi); // 123456
+ * ```
+ */
+export function parseSatoshiIdentifier(identifier) {
+    if (!identifier || typeof identifier !== 'string') {
+        throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', 'Satoshi identifier must be a non-empty string');
+    }
+    const trimmed = identifier.trim();
+    if (trimmed === '') {
+        throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', 'Satoshi identifier cannot be empty or whitespace-only');
+    }
+    let satoshiStr;
+    // Check if it's a did:btco DID
+    if (trimmed.startsWith('did:btco:')) {
+        const parts = trimmed.split(':');
+        // Handle different network prefixes:
+        // did:btco:123456 (mainnet)
+        // did:btco:test:123456 (testnet)
+        // did:btco:sig:123456 (signet)
+        if (parts.length === 3) {
+            // Mainnet format: did:btco:satoshi
+            satoshiStr = parts[2];
+        }
+        else if (parts.length === 4) {
+            // Network-specific format: did:btco:network:satoshi
+            const network = parts[2];
+            if (network !== 'test' && network !== 'sig') {
+                throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', `Invalid did:btco DID format: unsupported network "${network}"`);
+            }
+            satoshiStr = parts[3];
+        }
+        else {
+            throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', 'Invalid did:btco DID format: expected "did:btco:satoshi" or "did:btco:network:satoshi"');
+        }
+    }
+    else {
+        // Assume it's a plain satoshi number
+        satoshiStr = trimmed;
+    }
+    // Validate the extracted satoshi
+    const validation = validateSatoshiNumber(satoshiStr);
+    if (!validation.valid) {
+        throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', validation.error || 'Invalid satoshi identifier');
+    }
+    return Number(satoshiStr);
+}
+/**
+ * Validates a satoshi number and throws an error if invalid.
+ * Convenience wrapper around validateSatoshiNumber for code that expects exceptions.
+ *
+ * @param satoshi - The satoshi identifier to validate
+ * @throws {StructuredError} If the satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidSatoshi('123456'); // OK
+ * assertValidSatoshi(''); // throws StructuredError
+ * ```
+ */
+export function assertValidSatoshi(satoshi) {
+    const result = validateSatoshiNumber(satoshi);
+    if (!result.valid) {
+        throw new StructuredError('INVALID_SATOSHI', result.error || 'Invalid satoshi identifier');
+    }
+}

package/dist/utils/serialization.d.ts

@@ -0,0 +1,14 @@
+import { DIDDocument, VerifiableCredential } from '../types';
+type DocumentLoader = (url: string) => Promise<{
+    documentUrl: string;
+    document: any;
+    contextUrl: string | null;
+}>;
+export declare function serializeDIDDocument(didDoc: DIDDocument): string;
+export declare function deserializeDIDDocument(data: string): DIDDocument;
+export declare function serializeCredential(vc: VerifiableCredential): string;
+export declare function deserializeCredential(data: string): VerifiableCredential;
+export declare function canonicalizeDocument(doc: any, options?: {
+    documentLoader?: DocumentLoader;
+}): Promise<string>;
+export {};

package/dist/utils/serialization.js

@@ -0,0 +1,76 @@
+import jsonld from 'jsonld';
+// Import context documents from src/contexts
+import credentialsV1Context from '../contexts/credentials-v1.json';
+import credentialsV2Context from '../contexts/credentials-v2.json';
+import dataIntegrityV2Context from '../contexts/data-integrity-v2.json';
+import didsContext from '../contexts/dids.json';
+import ed255192020Context from '../contexts/ed255192020.json';
+import ordinalsContext from '../contexts/ordinals-plus.json';
+import originalsContext from '../contexts/originals.json';
+// Full context documents for proper canonicalization
+const PRELOADED_CONTEXTS = {
+    // W3C and standard contexts
+    'https://www.w3.org/2018/credentials/v1': credentialsV1Context,
+    'https://www.w3.org/ns/credentials/v2': credentialsV2Context,
+    'https://w3id.org/security/data-integrity/v2': dataIntegrityV2Context,
+    'https://www.w3.org/ns/did/v1': didsContext,
+    'https://w3id.org/security/suites/ed25519-2020/v1': ed255192020Context,
+    // Custom contexts
+    'https://ordinals.plus/vocab/v1': ordinalsContext,
+    // Originals network contexts (all three networks use the same context document)
+    'https://originals.build/context': originalsContext, // Legacy
+    'https://pichu.originals.build/context': originalsContext, // Production
+    'https://cleffa.originals.build/context': originalsContext, // Staging
+    'https://magby.originals.build/context': originalsContext, // Development
+};
+const defaultDocumentLoader = async (url) => {
+    const preloaded = PRELOADED_CONTEXTS[url];
+    if (preloaded) {
+        return { documentUrl: url, document: preloaded, contextUrl: null };
+    }
+    throw new Error(`Document not found in PRELOADED_CONTEXTS: ${url}`);
+};
+export function serializeDIDDocument(didDoc) {
+    // Serialize to JSON-LD with proper context
+    return JSON.stringify(didDoc, null, 2);
+}
+export function deserializeDIDDocument(data) {
+    // Parse from JSON-LD
+    try {
+        const parsed = JSON.parse(data);
+        return parsed;
+    }
+    catch (error) {
+        throw new Error('Invalid DID Document JSON');
+    }
+}
+export function serializeCredential(vc) {
+    // Serialize VC to JSON-LD
+    return JSON.stringify(vc, null, 2);
+}
+export function deserializeCredential(data) {
+    // Parse VC from JSON-LD
+    try {
+        const parsed = JSON.parse(data);
+        return parsed;
+    }
+    catch (error) {
+        throw new Error('Invalid Verifiable Credential JSON');
+    }
+}
+export async function canonicalizeDocument(doc, options = {}) {
+    try {
+        return await jsonld.canonize(doc, {
+            algorithm: 'URDNA2015',
+            format: 'application/n-quads',
+            documentLoader: options.documentLoader ?? defaultDocumentLoader,
+            useNative: false,
+            rdfDirection: 'i18n-datatype',
+            safe: false // Disable safe mode to allow custom contexts
+        });
+    }
+    catch (error) {
+        const message = error?.message ?? String(error);
+        throw new Error(`Failed to canonicalize document: ${message}`);
+    }
+}

package/dist/utils/telemetry.d.ts

@@ -0,0 +1,17 @@
+export type TelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface TelemetryEvent {
+    name: string;
+    level?: TelemetryLevel;
+    attributes?: Record<string, unknown>;
+}
+export interface TelemetryHooks {
+    onEvent?: (event: TelemetryEvent) => void;
+    onError?: (error: StructuredError) => void;
+}
+export declare class StructuredError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function emitTelemetry(hooks: TelemetryHooks | undefined, event: TelemetryEvent): void;
+export declare function emitError(hooks: TelemetryHooks | undefined, error: StructuredError): void;

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,22 @@
+import { VerifiableCredential, VerifiablePresentation, CredentialSubject, OriginalsConfig, ExternalSigner } from '../types';
+import { DIDManager } from '../did/DIDManager';
+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, Privy)
+     * @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;
+}