@originals/sdk 1.8.1 → 1.8.2

package/src/crypto/Multikey.ts

@@ -0,0 +1,194 @@
+import { base58 } from '@scure/base';
+
+// Multicodec headers (varints) for supported key types
+export const MULTICODEC_ED25519_PUB_HEADER = new Uint8Array([0xed, 0x01]);
+export const MULTICODEC_ED25519_PRIV_HEADER = new Uint8Array([0x80, 0x26]);
+export const MULTICODEC_SECP256K1_PUB_HEADER = new Uint8Array([0xe7, 0x01]);
+export const MULTICODEC_SECP256K1_PRIV_HEADER = new Uint8Array([0x13, 0x01]);
+export const MULTICODEC_BLS12381_G2_PUB_HEADER = new Uint8Array([0xeb, 0x01]);
+export const MULTICODEC_BLS12381_G2_PRIV_HEADER = new Uint8Array([0x82, 0x26]);
+export const MULTICODEC_P256_PUB_HEADER = new Uint8Array([0x80, 0x24]);
+export const MULTICODEC_P256_PRIV_HEADER = new Uint8Array([0x81, 0x26]);
+
+export type MultikeyType = 'Ed25519' | 'Secp256k1' | 'Bls12381G2' | 'P256';
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/**
+ * Validates that a key string uses proper multikey format.
+ * @param key - The multibase-encoded key string to validate
+ * @param expectedType - The expected key type (e.g., 'Ed25519', 'Secp256k1')
+ * @param isPrivate - Whether this is a private key (true) or public key (false)
+ * @throws Error with descriptive message if validation fails
+ */
+export function validateMultikeyFormat(
+  key: string,
+  expectedType: MultikeyType,
+  isPrivate: boolean
+): void {
+  // Validate multibase prefix
+  if (!key || typeof key !== 'string') {
+    throw new Error('Invalid multibase key format. Key must be a non-empty string.');
+  }
+  
+  if (key[0] !== 'z') {
+    throw new Error(
+      'Invalid multibase key format. Keys must use z-base58btc encoding (prefix "z").'
+    );
+  }
+
+  // Attempt to decode and validate multicodec header
+  try {
+    const mc = base58.decode(key.slice(1));
+    
+    if (mc.length < 2) {
+      throw new Error(
+        'Invalid multibase key format. Keys must use multicodec headers.'
+      );
+    }
+
+    // Validate header matches expected type
+    const header = mc.slice(0, 2);
+    const expectedHeaders = isPrivate
+      ? {
+          Ed25519: MULTICODEC_ED25519_PRIV_HEADER,
+          Secp256k1: MULTICODEC_SECP256K1_PRIV_HEADER,
+          Bls12381G2: MULTICODEC_BLS12381_G2_PRIV_HEADER,
+          P256: MULTICODEC_P256_PRIV_HEADER
+        }
+      : {
+          Ed25519: MULTICODEC_ED25519_PUB_HEADER,
+          Secp256k1: MULTICODEC_SECP256K1_PUB_HEADER,
+          Bls12381G2: MULTICODEC_BLS12381_G2_PUB_HEADER,
+          P256: MULTICODEC_P256_PUB_HEADER
+        };
+
+    const expectedHeader = expectedHeaders[expectedType];
+    
+    if (header[0] !== expectedHeader[0] || header[1] !== expectedHeader[1]) {
+      throw new Error(
+        `Invalid multibase key format. Expected ${expectedType} ${
+          isPrivate ? 'private' : 'public'
+        } key with multicodec header [0x${expectedHeader[0].toString(
+          16
+        )}, 0x${expectedHeader[1].toString(16)}], but found [0x${header[0].toString(
+          16
+        )}, 0x${header[1].toString(16)}].`
+      );
+    }
+
+    // Validate key length (basic sanity check)
+    const keyBytes = mc.slice(2);
+    const expectedLengths: Record<MultikeyType, { private: number; public: number }> = {
+      Ed25519: { private: 32, public: 32 },
+      Secp256k1: { private: 32, public: 33 },
+      P256: { private: 32, public: 33 },
+      Bls12381G2: { private: 32, public: 96 }
+    };
+
+    const expectedLength = isPrivate
+      ? expectedLengths[expectedType].private
+      : expectedLengths[expectedType].public;
+
+    if (keyBytes.length !== expectedLength) {
+      throw new Error(
+        `Invalid multibase key format. Expected ${expectedType} ${
+          isPrivate ? 'private' : 'public'
+        } key to be ${expectedLength} bytes, but found ${keyBytes.length} bytes.`
+      );
+    }
+  } catch (error) {
+    // Re-throw our own errors as-is
+    if (error instanceof Error && error.message.startsWith('Invalid multibase key format')) {
+      throw error;
+    }
+    // Base58 decode errors or other unexpected errors
+    throw new Error(
+      `Invalid multibase key format. Keys must use multicodec headers. Decode error: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+}
+
+export const multikey = {
+  encodePublicKey: (publicKey: Uint8Array, type: MultikeyType): string => {
+    const header =
+      type === 'Ed25519'
+        ? MULTICODEC_ED25519_PUB_HEADER
+        : type === 'Secp256k1'
+          ? MULTICODEC_SECP256K1_PUB_HEADER
+          : type === 'Bls12381G2'
+            ? MULTICODEC_BLS12381_G2_PUB_HEADER
+            : MULTICODEC_P256_PUB_HEADER;
+    const mcBytes = concatBytes(header, publicKey);
+    return 'z' + base58.encode(mcBytes);
+  },
+
+  encodePrivateKey: (privateKey: Uint8Array, type: MultikeyType): string => {
+    const header =
+      type === 'Ed25519'
+        ? MULTICODEC_ED25519_PRIV_HEADER
+        : type === 'Secp256k1'
+          ? MULTICODEC_SECP256K1_PRIV_HEADER
+          : type === 'Bls12381G2'
+            ? MULTICODEC_BLS12381_G2_PRIV_HEADER
+            : MULTICODEC_P256_PRIV_HEADER;
+    const mcBytes = concatBytes(header, privateKey);
+    return 'z' + base58.encode(mcBytes);
+  },
+
+  encodeMultibase: (data: Uint8Array | Buffer): string => {
+    return 'z' + base58.encode(data instanceof Buffer ? new Uint8Array(data) : data);
+  },
+
+  decodePublicKey: (publicKeyMultibase: string): { key: Uint8Array; type: MultikeyType } => {
+    if (!publicKeyMultibase || publicKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid Multibase encoding');
+    }
+    const mc = base58.decode(publicKeyMultibase.slice(1));
+    const header = mc.slice(0, 2);
+    const key = mc.slice(2);
+    if (header[0] === MULTICODEC_ED25519_PUB_HEADER[0] && header[1] === MULTICODEC_ED25519_PUB_HEADER[1]) {
+      return { key, type: 'Ed25519' };
+    }
+    if (header[0] === MULTICODEC_SECP256K1_PUB_HEADER[0] && header[1] === MULTICODEC_SECP256K1_PUB_HEADER[1]) {
+      return { key, type: 'Secp256k1' };
+    }
+    if (header[0] === MULTICODEC_BLS12381_G2_PUB_HEADER[0] && header[1] === MULTICODEC_BLS12381_G2_PUB_HEADER[1]) {
+      return { key, type: 'Bls12381G2' };
+    }
+    if (header[0] === MULTICODEC_P256_PUB_HEADER[0] && header[1] === MULTICODEC_P256_PUB_HEADER[1]) {
+      return { key, type: 'P256' };
+    }
+    throw new Error('Unsupported key type');
+  },
+
+  decodePrivateKey: (privateKeyMultibase: string): { key: Uint8Array; type: MultikeyType } => {
+    if (!privateKeyMultibase || privateKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid Multibase encoding');
+    }
+    const mc = base58.decode(privateKeyMultibase.slice(1));
+    const header = mc.slice(0, 2);
+    const key = mc.slice(2);
+    if (header[0] === MULTICODEC_ED25519_PRIV_HEADER[0] && header[1] === MULTICODEC_ED25519_PRIV_HEADER[1]) {
+      return { key, type: 'Ed25519' };
+    }
+    if (header[0] === MULTICODEC_SECP256K1_PRIV_HEADER[0] && header[1] === MULTICODEC_SECP256K1_PRIV_HEADER[1]) {
+      return { key, type: 'Secp256k1' };
+    }
+    if (header[0] === MULTICODEC_BLS12381_G2_PRIV_HEADER[0] && header[1] === MULTICODEC_BLS12381_G2_PRIV_HEADER[1]) {
+      return { key, type: 'Bls12381G2' };
+    }
+    if (header[0] === MULTICODEC_P256_PRIV_HEADER[0] && header[1] === MULTICODEC_P256_PRIV_HEADER[1]) {
+      return { key, type: 'P256' };
+    }
+    throw new Error('Unsupported key type');
+  }
+};
+

package/src/crypto/Signer.ts

@@ -0,0 +1,262 @@
+// Initialize noble crypto libraries first (idempotent - safe to import multiple times)
+import './noble-init.js';
+
+export abstract class Signer {
+  abstract sign(data: Buffer, privateKeyMultibase: string): Promise<Buffer>;
+  abstract verify(data: Buffer, signature: Buffer, publicKeyMultibase: string): Promise<boolean>;
+}
+
+import { bls12_381 as bls } from '@noble/curves/bls12-381';
+import { p256 } from '@noble/curves/p256';
+import { sha256 } from '@noble/hashes/sha2.js';
+import * as secp256k1 from '@noble/secp256k1';
+import * as ed25519 from '@noble/ed25519';
+import { multikey } from './Multikey';
+
+export class ES256KSigner extends Signer {
+  async sign(data: Buffer, privateKeyMultibase: string): Promise<Buffer> {
+    if (!privateKeyMultibase || privateKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+    
+    let decoded;
+    try {
+      decoded = multikey.decodePrivateKey(privateKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+    
+    if (decoded.type !== 'Secp256k1') {
+      throw new Error('Invalid key type for ES256K');
+    }
+    
+    const privateKey = decoded.key;
+    const hash = sha256(data);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    const sigAny: any = await (secp256k1 as any).signAsync(hash, privateKey);
+    /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
+    const sigBytes: Uint8Array = sigAny instanceof Uint8Array
+      ? sigAny
+      : typeof sigAny?.toCompactRawBytes === 'function'
+        ? sigAny.toCompactRawBytes()
+        : typeof sigAny?.toRawBytes === 'function'
+          ? sigAny.toRawBytes()
+          : new Uint8Array(sigAny);
+    /* eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
+    return Buffer.from(sigBytes);
+  }
+
+  async verify(data: Buffer, signature: Buffer, publicKeyMultibase: string): Promise<boolean> {
+    if (!publicKeyMultibase || publicKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+
+    let decoded;
+    try {
+      decoded = multikey.decodePublicKey(publicKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+
+    if (decoded.type !== 'Secp256k1') {
+      throw new Error('Invalid key type for ES256K');
+    }
+
+    const publicKey = decoded.key;
+    const hash = sha256(data);
+    try {
+      return await Promise.resolve(secp256k1.verify(signature, hash, publicKey));
+    } catch {
+      return false;
+    }
+  }
+}
+
+export class Ed25519Signer extends Signer {
+  async sign(data: Buffer, privateKeyMultibase: string): Promise<Buffer> {
+    if (!privateKeyMultibase || privateKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+    
+    let decoded;
+    try {
+      decoded = multikey.decodePrivateKey(privateKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+    
+    if (decoded.type !== 'Ed25519') {
+      throw new Error('Invalid key type for Ed25519');
+    }
+    
+    const privateKey = decoded.key;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    const signature = await (ed25519 as any).signAsync(data, privateKey);
+    return Buffer.from(signature);
+  }
+
+  async verify(data: Buffer, signature: Buffer, publicKeyMultibase: string): Promise<boolean> {
+    if (!publicKeyMultibase || publicKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+    
+    let decoded;
+    try {
+      decoded = multikey.decodePublicKey(publicKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+    
+    if (decoded.type !== 'Ed25519') {
+      throw new Error('Invalid key type for Ed25519');
+    }
+    
+    const publicKey = decoded.key;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+      return await (ed25519 as any).verifyAsync(signature, data, publicKey);
+    } catch {
+      return false;
+    }
+  }
+}
+
+export class ES256Signer extends Signer {
+  async sign(data: Buffer, privateKeyMultibase: string): Promise<Buffer> {
+    if (!privateKeyMultibase || privateKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+
+    let decoded;
+    try {
+      decoded = multikey.decodePrivateKey(privateKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+
+    if (decoded.type !== 'P256') {
+      throw new Error('Invalid key type for ES256');
+    }
+
+    const privateKey = decoded.key;
+    const hash = sha256(data);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+    const sigAny: any = p256.sign(hash, privateKey);
+    /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
+    const sigBytes: Uint8Array = sigAny instanceof Uint8Array
+      ? sigAny
+      : typeof sigAny?.toCompactRawBytes === 'function'
+        ? sigAny.toCompactRawBytes()
+        : typeof sigAny?.toRawBytes === 'function'
+          ? sigAny.toRawBytes()
+          : new Uint8Array(sigAny);
+    /* eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
+    return await Promise.resolve(Buffer.from(sigBytes));
+  }
+
+  async verify(data: Buffer, signature: Buffer, publicKeyMultibase: string): Promise<boolean> {
+    if (!publicKeyMultibase || publicKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+
+    let decoded;
+    try {
+      decoded = multikey.decodePublicKey(publicKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+
+    if (decoded.type !== 'P256') {
+      throw new Error('Invalid key type for ES256');
+    }
+
+    const publicKey = decoded.key;
+    const hash = sha256(data);
+    try {
+      return await Promise.resolve(p256.verify(signature, hash, publicKey));
+    } catch {
+      return false;
+    }
+  }
+}
+
+export class Bls12381G2Signer extends Signer {
+  async sign(data: Buffer, privateKeyMultibase: string): Promise<Buffer> {
+    if (!privateKeyMultibase || privateKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+
+    let decoded;
+    try {
+      decoded = multikey.decodePrivateKey(privateKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+
+    if (decoded.type !== 'Bls12381G2') {
+      throw new Error('Invalid key type for Bls12381G2');
+    }
+
+    const sk = decoded.key;
+    const sig = bls.sign(data, sk);
+    return await Promise.resolve(Buffer.from(sig));
+  }
+
+  async verify(data: Buffer, signature: Buffer, publicKeyMultibase: string): Promise<boolean> {
+    if (!publicKeyMultibase || publicKeyMultibase[0] !== 'z') {
+      throw new Error('Invalid multibase key format. Keys must use multicodec headers.');
+    }
+
+    let decoded;
+    try {
+      decoded = multikey.decodePublicKey(publicKeyMultibase);
+    } catch (error) {
+      throw new Error(
+        `Invalid multibase key format. Keys must use multicodec headers. ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+
+    if (decoded.type !== 'Bls12381G2') {
+      throw new Error('Invalid key type for Bls12381G2');
+    }
+
+    const pk = decoded.key;
+    try {
+      return await Promise.resolve(bls.verify(signature, data, pk));
+    } catch {
+      return false;
+    }
+  }
+}
+
+

package/src/crypto/noble-init.ts

@@ -0,0 +1,138 @@
+/**
+ * Noble Crypto Library Initialization
+ * 
+ * @noble/ed25519 v2.x and @noble/secp256k1 require manual configuration of hash functions.
+ * This is by design - they don't bundle hash implementations to allow flexibility.
+ * 
+ * This module centralizes the initialization to ensure:
+ * 1. Libraries are configured before any crypto operations
+ * 2. Configuration is consistent across the SDK
+ * 3. Readonly property issues (Bun) are handled gracefully
+ * 
+ * This should be imported at the SDK entry point (index.ts) to ensure it runs first.
+ */
+
+import * as secp256k1 from '@noble/secp256k1';
+import * as ed25519 from '@noble/ed25519';
+import { sha256, sha512 } from '@noble/hashes/sha2.js';
+import { hmac } from '@noble/hashes/hmac.js';
+import { concatBytes } from '@noble/hashes/utils.js';
+
+// Implementation functions
+const sha512Impl = (...msgs: Uint8Array[]) => sha512(concatBytes(...msgs));
+const hmacSha256Impl = (key: Uint8Array, ...msgs: Uint8Array[]) =>
+  hmac(sha256, key, concatBytes(...msgs));
+
+/**
+ * Safely set a property on an object, handling readonly properties
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function safeSetProperty(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  obj: any,
+  prop: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value: any,
+  options?: { writable?: boolean; configurable?: boolean }
+): boolean {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    obj[prop] = value;
+    return true;
+  } catch {
+    // Property might be readonly, try defineProperty
+    try {
+      Object.defineProperty(obj, prop, {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        value,
+        writable: options?.writable ?? true,
+        configurable: options?.configurable ?? true,
+      });
+      return true;
+    } catch {
+      // If both fail, property might already be set or truly readonly
+      return false;
+    }
+  }
+}
+
+/**
+ * Initialize @noble/secp256k1 with hmacSha256Sync utility
+ */
+function initSecp256k1(): void {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+  const sAny: any = secp256k1 as any;
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  if (!sAny?.utils) {
+    // Try to create utils object if it doesn't exist
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      sAny.utils = {};
+    } catch {
+      // If we can't create it, try defineProperty
+      Object.defineProperty(sAny, 'utils', {
+        value: {},
+        writable: true,
+        configurable: true,
+      });
+    }
+  }
+
+  // Set hmacSha256Sync if not already set
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  if (typeof sAny.utils.hmacSha256Sync !== 'function') {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    safeSetProperty(sAny.utils, 'hmacSha256Sync', hmacSha256Impl);
+  }
+}
+
+/**
+ * Initialize @noble/ed25519 with sha512Sync utility
+ * Handles both etc.sha512Sync (v2.x) and utils.sha512Sync (backward compat)
+ */
+function initEd25519(): void {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+  const eAny: any = ed25519 as any;
+
+  // Set etc.sha512Sync for @noble/ed25519 v2.x (required)
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  if (eAny?.etc && typeof eAny.etc.sha512Sync !== 'function') {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    safeSetProperty(eAny.etc, 'sha512Sync', sha512Impl);
+  }
+
+  // Set utils.sha512Sync for backward compatibility
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  if (!eAny?.utils) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      eAny.utils = {};
+    } catch {
+      Object.defineProperty(eAny, 'utils', {
+        value: {},
+        writable: true,
+        configurable: true,
+      });
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  if (typeof eAny.utils.sha512Sync !== 'function') {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    safeSetProperty(eAny.utils, 'sha512Sync', sha512Impl);
+  }
+}
+
+/**
+ * Initialize all noble crypto libraries
+ * This should be called once at SDK startup
+ */
+export function initNobleCrypto(): void {
+  initSecp256k1();
+  initEd25519();
+}
+
+// Auto-initialize when this module is imported
+initNobleCrypto();
+