@wallaby-cash/cryptography 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @wallaby-cash/cryptography
+
+## 1.0.0
+
+### Major Changes
+
+- Initial release of @wallaby-cash/cryptography package
+
+  This release includes:
+  - Identity creation with public/private key pairs
+  - Message signing and verification
+  - Public key encryption and decryption
+  - Keccak256 hashing utilities
+  - Public key recovery from signatures
+  - Public key derivation from private keys

package/README.md

@@ -0,0 +1,121 @@
+# @wallaby-cash/cryptography
+
+Cryptography utilities for Wallaby Cash, providing Ethereum-compatible cryptographic operations.
+
+## Installation
+
+```bash
+npm install @wallaby-cash/cryptography
+# or
+bun add @wallaby-cash/cryptography
+# or
+yarn add @wallaby-cash/cryptography
+```
+
+## Features
+
+- **Identity Creation**: Generate new cryptographic identities with public/private key pairs
+- **Signing**: Sign messages with private keys
+- **Encryption**: Encrypt and decrypt data using public/private key cryptography
+- **Hashing**: Keccak256 hashing utilities
+- **Key Recovery**: Recover public keys from signatures
+- **Key Derivation**: Derive public keys from private keys
+
+## Usage
+
+```typescript
+import {
+  createIdentity,
+  sign,
+  encryptWithPublicKey,
+  decryptWithPrivateKey,
+  hash,
+  publicKeyByPrivateKey,
+  recoverPublicKey
+} from '@wallaby-cash/cryptography';
+
+// Create a new identity
+const identity = createIdentity();
+console.log('Public Key:', identity.publicKey);
+console.log('Private Key:', identity.privateKey);
+
+// Sign a message
+const message = 'Hello, Wallaby!';
+const signature = sign(identity.privateKey, message);
+
+// Hash data
+const hashed = hash.keccak256('some data');
+
+// Encrypt and decrypt
+const encrypted = await encryptWithPublicKey(identity.publicKey, 'secret message');
+const decrypted = await decryptWithPrivateKey(identity.privateKey, encrypted);
+
+// Derive public key from private key
+const pubKey = publicKeyByPrivateKey(identity.privateKey);
+
+// Recover public key from signature
+const recoveredPubKey = recoverPublicKey(signature, message);
+```
+
+## API Reference
+
+### `createIdentity()`
+Generates a new cryptographic identity with a public/private key pair.
+
+**Returns:** `{ publicKey: string, privateKey: string }`
+
+### `sign(privateKey: string, message: string)`
+Signs a message with a private key.
+
+**Parameters:**
+- `privateKey`: The private key to sign with
+- `message`: The message to sign
+
+**Returns:** Signature object
+
+### `encryptWithPublicKey(publicKey: string, data: string)`
+Encrypts data using a public key.
+
+**Parameters:**
+- `publicKey`: The recipient's public key
+- `data`: The data to encrypt
+
+**Returns:** `Promise<EncryptedData>`
+
+### `decryptWithPrivateKey(privateKey: string, encrypted: EncryptedData)`
+Decrypts data using a private key.
+
+**Parameters:**
+- `privateKey`: The private key to decrypt with
+- `encrypted`: The encrypted data object
+
+**Returns:** `Promise<string>`
+
+### `hash.keccak256(data: string)`
+Hashes data using Keccak256.
+
+**Parameters:**
+- `data`: The data to hash
+
+**Returns:** Hash string
+
+### `publicKeyByPrivateKey(privateKey: string)`
+Derives a public key from a private key.
+
+**Parameters:**
+- `privateKey`: The private key
+
+**Returns:** `string` - The derived public key
+
+### `recoverPublicKey(signature: Signature, message: string)`
+Recovers the public key from a signature and message.
+
+**Parameters:**
+- `signature`: The signature object
+- `message`: The original message
+
+**Returns:** `string` - The recovered public key
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@wallaby-cash/cryptography",
+  "version": "1.0.0",
+  "description": "Cryptography utilities for Wallaby Cash",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cryptography",
+    "encryption",
+    "ethereum",
+    "secp256k1",
+    "wallaby"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wallaby-cash/sdk-monorepo.git",
+    "directory": "packages/cryptography"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "generate:component": "turbo gen react-component",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@wallaby-cash/eslint-config": "*",
+    "@wallaby-cash/typescript-config": "*",
+    "@types/node": "^22.15.3",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2"
+  },
+  "dependencies": {
+    "ethereum-cryptography": "^3.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  }
+}

package/src/createIdentity.ts

@@ -0,0 +1,66 @@
+import { getRandomBytesSync as randomBytes } from 'ethereum-cryptography/random.js';
+import { addLeading0x, stripHexPrefix, concatUint8Arrays } from './util';
+import { publicKeyByPrivateKey } from './publicKeyByPrivateKey';
+import { bytesToHex } from 'ethereum-cryptography/utils';
+import { keccak256 } from 'ethereum-cryptography/keccak';
+
+export const DEFAULT_ENTROPY_BYTES = 32;
+export const MINIMUM_SHANNON_ENTROPY = 4;
+
+/**
+ * creates a new private key
+ * @param { Uint8Array } entropy - optional entropy to create the private key
+ * @returns a new private key
+ */
+export const createPrivateKey = (entropy?: Uint8Array) => {
+  if (entropy) {
+    if (!(entropy instanceof Uint8Array) || entropy.length < DEFAULT_ENTROPY_BYTES) {
+      throw new Error(`entropy must be a Uint8Array of at least ${DEFAULT_ENTROPY_BYTES} bytes`);
+    }
+
+    // Check byte diversity
+    const uniqueBytes = new Set(entropy);
+    if (uniqueBytes.size < Math.min(8, entropy.length / 4)) {
+      throw new Error(`entropy is too repetitive (only ${uniqueBytes.size} unique byte values)`);
+    }
+
+    // Estimate Shannon entropy
+    const byteCounts = new Uint32Array(256);
+    entropy.forEach((b) => byteCounts[b]!++);
+    const total = entropy.length;
+    let shannonEntropy = 0;
+    for (let i = 0; i < 256; i++) {
+      if (byteCounts[i]! > 0) {
+        const p = byteCounts[i]! / total;
+        shannonEntropy -= p * Math.log2(p);
+      }
+    }
+    if (shannonEntropy < MINIMUM_SHANNON_ENTROPY) {
+      throw new Error(`entropy has low Shannon entropy (${shannonEntropy.toFixed(2)} bits/byte)`);
+    }
+
+    const outerHex = keccak256(entropy);
+    return addLeading0x(bytesToHex(outerHex));
+  } else {
+    const innerHex = keccak256(concatUint8Arrays([randomBytes(32), randomBytes(32)]));
+    const middleHex = concatUint8Arrays([concatUint8Arrays([randomBytes(32), innerHex]), randomBytes(32)]);
+    const outerHex = keccak256(middleHex);
+    return addLeading0x(bytesToHex(outerHex));
+  }
+};
+
+/**
+ * creates a new identity
+ * @param { Uint8Array } entropy - optional entropy to create the private key
+ * @returns a new pair of private and public key
+ */
+export const createIdentity = (entropy?: Uint8Array) => {
+  const privateKey = createPrivateKey(entropy);
+
+  const walletPublicKey = publicKeyByPrivateKey(privateKey);
+  const identity = {
+    privateKey: privateKey,
+    publicKey: stripHexPrefix(walletPublicKey),
+  };
+  return identity;
+};

package/src/decryptWithPrivateKey.ts

@@ -0,0 +1,10 @@
+import { stripHexPrefix } from './util';
+import { decrypt } from './encryption-utils';
+import { Encrypted } from './types';
+
+export const decryptWithPrivateKey = (privateKey: string, encrypted: Encrypted) => {
+  // remove '0x' from privateKey
+  const twoStripped = stripHexPrefix(privateKey);
+
+  return decrypt(twoStripped, encrypted);
+};

package/src/encryptWithPublicKey.ts

@@ -0,0 +1,12 @@
+import { decompress } from './util';
+import { encrypt } from './encryption-utils';
+import { EncryptionOptions } from './types';
+
+export const encryptWithPublicKey = (publicKey: string, message: string, options?: EncryptionOptions) => {
+  // ensure its an uncompressed publicKey
+  const decompressedKey = decompress(publicKey);
+
+  // re-add the compression-flag
+  const pubString = '04' + decompressedKey;
+  return encrypt(pubString, message, options);
+};

package/src/encryption-utils.ts

@@ -0,0 +1,93 @@
+import { sha512 } from 'ethereum-cryptography/sha512.js';
+import { secp256k1 } from 'ethereum-cryptography/secp256k1';
+import { getRandomBytesSync as randomBytes } from 'ethereum-cryptography/random.js';
+import { hexToBytes, bytesToHex, bytesToUtf8 } from 'ethereum-cryptography/utils.js';
+import { encrypt as aesEncrypt, decrypt as aesDecrypt } from 'ethereum-cryptography/aes.js';
+import { Encrypted, EncryptionOptions } from './types';
+import { hmacSha256Sign } from './sign';
+import { concatUint8Arrays, utf8ToBytes } from './util';
+
+/**
+ *  See https://github.com/bitchan/eccrypto for the original implementation that eth-crypto used, it's ancient and not maintained.
+ */
+
+/**
+ * Encrypts a message using the recipient's public key.
+ * @param {string} publicKeyTo - The recipient's public key.
+ * @param {string} msg - The message to encrypt.
+ * @returns {Encrypted} The encrypted message.
+ */
+
+export const encrypt = (publicKeyTo: string, msg: string, options?: EncryptionOptions): Encrypted => {
+  const ephemPrivateKey = options?.ephemPrivateKey ? hexToBytes(options.ephemPrivateKey) : randomBytes(32);
+  const iv = randomBytes(16);
+
+  const compressedPub = secp256k1.getPublicKey(ephemPrivateKey); // defaults to compressed format
+  const point = secp256k1.ProjectivePoint.fromHex(compressedPub); // decompress the pub into an EC point
+  const ephemPublicKey = point.toRawBytes(false); // Get uncompressed SEC1 format pub
+  const sharedSecret = secp256k1.getSharedSecret(ephemPrivateKey, hexToBytes(publicKeyTo), true).slice(1);
+  const hash = sha512(sharedSecret);
+  const encryptionKey = hash.subarray(0, 32);
+  const macKey = hash.subarray(32);
+  const message = utf8ToBytes(msg);
+  const data = aesEncrypt(message, encryptionKey, iv, 'aes-256-cbc');
+  const dataToMac = concatUint8Arrays([iv, ephemPublicKey, data]);
+  const mac = hmacSha256Sign(macKey, dataToMac);
+
+  return {
+    iv: bytesToHex(iv),
+    ephemPublicKey: bytesToHex(ephemPublicKey),
+    ciphertext: bytesToHex(data),
+    mac: bytesToHex(mac),
+  };
+};
+
+/**
+ * Decrypts an encrypted message using the recipient's private key.
+ * @param {string} privateKey - The recipient's private key.
+ * @param {Encrypted} opts - The encrypted message.
+ * @returns {string} The decrypted message.
+ */
+export const decrypt = (privateKey: string, opts: Encrypted) => {
+  let sharedSecret: Uint8Array;
+  try {
+    sharedSecret = secp256k1.getSharedSecret(hexToBytes(privateKey), opts.ephemPublicKey, true).slice(1);
+  } catch (e) {
+    throw new Error(`Invalid MAC: data integrity check failed: ${e}`);
+  }
+
+  const hash = sha512(sharedSecret);
+  const encryptionKey = hash.subarray(0, 32);
+  const macKey = hash.subarray(32);
+
+  const ciphertext = hexToBytes(opts.ciphertext);
+  const iv = hexToBytes(opts.iv);
+  const ephemPublicKey = hexToBytes(opts.ephemPublicKey);
+  const receivedMac = hexToBytes(opts.mac);
+
+  // Recompute MAC
+  const dataToMac = concatUint8Arrays([iv, ephemPublicKey, ciphertext]);
+  const expectedMac = hmacSha256Sign(macKey, dataToMac);
+
+  if (!constantTimeEqual(expectedMac, receivedMac)) {
+    throw new Error('Invalid MAC: data integrity check failed');
+  }
+
+  const decrypted = aesDecrypt(ciphertext, encryptionKey, iv, 'aes-256-cbc');
+  return bytesToUtf8(decrypted);
+};
+
+/**
+ * Compares two Uint8Arrays in constant time to prevent timing attacks.
+ * @param {Uint8Array} a - The first array.
+ * @param {Uint8Array} b - The second array.
+ * @returns {boolean} True if the arrays are equal, false otherwise.
+ */
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i]! ^ b[i]!;
+  }
+  return result === 0;
+}

package/src/hash.ts

@@ -0,0 +1,14 @@
+import { bytesToHex, hexToBytes } from 'ethereum-cryptography/utils.js';
+import { keccak256 as _keccak256 } from 'ethereum-cryptography/keccak.js';
+import { addLeading0x, utf8ToBytes } from './util';
+
+const solidityPackedKeccak256 = (value: string) => {
+  const bytes = utf8ToBytes(value);
+  const hex = addLeading0x(bytesToHex(bytes));
+  const hash = _keccak256(hexToBytes(hex));
+  return addLeading0x(bytesToHex(hash));
+};
+
+export const keccak256 = (params: string) => {
+  return solidityPackedKeccak256(params);
+};

package/src/index.ts

@@ -0,0 +1,33 @@
+import { createIdentity } from './createIdentity';
+import { sign } from './sign';
+import { encryptWithPublicKey } from './encryptWithPublicKey';
+import { decryptWithPrivateKey } from './decryptWithPrivateKey';
+import { keccak256 } from './hash';
+import { publicKeyByPrivateKey } from './publicKeyByPrivateKey';
+import { recoverPublicKey } from './recoverPublicKey';
+
+const hash = {
+  keccak256,
+};
+
+export {
+  createIdentity,
+  decryptWithPrivateKey,
+  encryptWithPublicKey,
+  hash,
+  keccak256,
+  publicKeyByPrivateKey,
+  recoverPublicKey,
+  sign,
+};
+
+export default {
+  createIdentity,
+  decryptWithPrivateKey,
+  encryptWithPublicKey,
+  hash,
+  keccak256,
+  publicKeyByPrivateKey,
+  recoverPublicKey,
+  sign,
+};

package/src/publicKeyByPrivateKey.ts

@@ -0,0 +1,17 @@
+import { decompress, stripHexPrefix } from './util';
+import { secp256k1 } from 'ethereum-cryptography/secp256k1.js';
+import { bytesToHex } from 'ethereum-cryptography/utils';
+
+/**
+ * Generate publicKey from the privateKey.
+ * This creates the uncompressed publicKey,
+ * where 04 has stripped from left
+ * @returns {string}
+ */
+
+export const publicKeyByPrivateKey = (privateKey: string) => {
+  const key = stripHexPrefix(privateKey);
+  const compressedPub = secp256k1.getPublicKey(key); // defaults to compressed format
+  const point = secp256k1.ProjectivePoint.fromHex(compressedPub); // decompress the pub into an EC point
+  return decompress(bytesToHex(point.toRawBytes(false))); // Get uncompressed SEC1 format pub
+};

package/src/recoverPublicKey.ts

@@ -0,0 +1,26 @@
+import { ecdsaRecover } from 'ethereum-cryptography/secp256k1-compat';
+import { stripHexPrefix } from './util';
+import { bytesToHex, hexToBytes } from 'ethereum-cryptography/utils';
+
+/**
+ * returns the publicKey for the privateKey with which the messageHash was signed
+ * @param  {string} signature
+ * @param  {string} hash
+ * @return {string} publicKey
+ */
+export const recoverPublicKey = (signature: string, hash: string) => {
+  const noHex = stripHexPrefix(signature);
+
+  // split into v-value and sig
+  const sigOnly = noHex.substring(0, noHex.length - 2); // all but last 2 chars
+  const vValue = noHex.slice(-2); // last 2 chars
+
+  const recoveryNumber = vValue === '1c' ? 1 : 0;
+
+  let pubKey = bytesToHex(ecdsaRecover(hexToBytes(sigOnly), recoveryNumber, hexToBytes(stripHexPrefix(hash)), false));
+
+  // remove trailing '04'
+  pubKey = pubKey.slice(2);
+
+  return pubKey;
+};

package/src/sign.ts

@@ -0,0 +1,27 @@
+import { secp256k1 } from 'ethereum-cryptography/secp256k1.js';
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha2';
+import { hexToBytes } from 'ethereum-cryptography/utils';
+import { addLeading0x, isHexString, stripHexPrefix } from './util';
+
+/**
+ * signs the given message
+ * @param  {string} privateKey
+ * @param  {string} hash
+ * @return {string} hexString
+ */
+export const sign = (privateKey: string, hash: string) => {
+  const hashWith0x = addLeading0x(hash);
+  if (hashWith0x.length !== 66 || !isHexString(hashWith0x)) throw new Error('Can only sign hashes, given: ' + hash);
+
+  const sigObj = secp256k1.sign(hexToBytes(stripHexPrefix(hash)), hexToBytes(stripHexPrefix(privateKey)));
+
+  const recoveryId = sigObj.recovery === 1 ? '1c' : '1b';
+  const newSignature = '0x' + sigObj.toCompactHex() + recoveryId;
+  return newSignature;
+};
+
+export const hmacSha256Sign = (key: Uint8Array, msg: Uint8Array) => {
+  const result = hmac(sha256, key, msg);
+  return result;
+};

package/src/types.ts

@@ -0,0 +1,10 @@
+export type Encrypted = {
+  iv: string;
+  ephemPublicKey: string;
+  ciphertext: string;
+  mac: string;
+};
+
+export type EncryptionOptions = {
+  ephemPrivateKey?: string;
+};

package/src/util.ts

@@ -0,0 +1,110 @@
+import { hexToBytes } from 'ethereum-cryptography/utils';
+
+/**
+ * Returns a `Boolean` on whether or not the a `String` starts with '0x'
+ * @param str the string input value
+ * @return a boolean if it is or is not hex prefixed
+ * @throws if the str input is not a string
+ */
+export const isHexPrefixed = (str: string) => {
+  if (typeof str !== 'string') {
+    throw new Error(`[isHexPrefixed] input must be type 'string', received type ${typeof str}`);
+  }
+
+  return str[0] === '0' && str[1] === 'x';
+};
+
+/**
+ * Removes '0x' from a given `String` if present
+ * @param str the string value
+ * @returns the string without 0x prefix
+ */
+export const stripHexPrefix = (str: string): string => {
+  if (typeof str !== 'string') throw new Error(`[stripHexPrefix] input must be type 'string', received ${typeof str}`);
+
+  return isHexPrefixed(str) ? str.slice(2) : str;
+};
+
+/**
+ * Is the string a hex string.
+ *
+ * @param  value
+ * @param  length
+ * @returns  output the string is a hex string
+ */
+export const isHexString = (value: string, length?: number): boolean => {
+  if (typeof value !== 'string' || !value.match(/^0x[0-9A-Fa-f]+$/)) return false;
+
+  if (length && value.length !== 2 + 2 * length) return false;
+
+  return true;
+};
+
+/**
+ * Adds '0x' to a given `String` if not present
+ * @param str the string input value
+ * @return the string with a 0x prefix
+ */
+
+export const addLeading0x = (str: string) => {
+  if (!str.startsWith('0x')) return '0x' + str;
+  else return str;
+};
+
+export const decompress = (startsWith02Or03: string) => {
+  const testByteArray = hexToBytes(startsWith02Or03);
+  let startsWith04 = startsWith02Or03;
+  if (testByteArray.length === 64) {
+    startsWith04 = '04' + startsWith02Or03;
+  }
+  return startsWith04.substring(2);
+};
+
+/** Helper function to concat UInt8Arrays mimicking the behaviour of the
+ *  Buffer.concat function in Node.js
+ */
+
+export const concatUint8Arrays = (uint8arrays: Uint8Array[]) => {
+  const totalLength = uint8arrays.reduce((total, uint8array) => total + uint8array.byteLength, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  uint8arrays.forEach((uint8array) => {
+    result.set(uint8array, offset);
+    offset += uint8array.byteLength;
+  });
+  return result;
+};
+
+/**
+ * Converts a UTF-8 string to a Uint8Array without using TextEncoder, which is not available in mobile
+ * @example utf8ToBytes('abc') // new Uint8Array([97, 98, 99])
+ */
+export const utf8ToBytes = (str: string): Uint8Array => {
+  if (typeof str !== 'string') throw new Error(`utf8ToBytes expected string, got ${typeof str}`);
+  const bytes = [];
+
+  for (let i = 0; i < str.length; i++) {
+    const codePoint = str.codePointAt(i);
+
+    if (!codePoint) {
+      throw new Error('Invalid code point');
+    }
+
+    if (codePoint < 0x80) {
+      bytes.push(codePoint);
+    } else if (codePoint < 0x800) {
+      bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+    } else if (codePoint < 0x10000) {
+      bytes.push(0xe0 | (codePoint >> 12), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+    } else {
+      i++; // skip one iteration since we have a surrogate pair
+      bytes.push(
+        0xf0 | (codePoint >> 18),
+        0x80 | ((codePoint >> 12) & 0x3f),
+        0x80 | ((codePoint >> 6) & 0x3f),
+        0x80 | (codePoint & 0x3f),
+      );
+    }
+  }
+  return new Uint8Array(bytes);
+};