ox 0.8.0 → 0.8.2

package/core/X25519.ts

@@ -0,0 +1,202 @@
+import { x25519 } from '@noble/curves/ed25519'
+import * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import * as Hex from './Hex.js'
+
+/** Re-export of noble/curves X25519 utilities. */
+export const noble = x25519
+
+/**
+ * Creates a new X25519 key pair consisting of a private key and its corresponding public key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { X25519 } from 'ox'
+ *
+ * const { privateKey, publicKey } = X25519.createKeyPair()
+ * ```
+ *
+ * @param options - The options to generate the key pair.
+ * @returns The generated key pair containing both private and public keys.
+ */
+export function createKeyPair<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  options: createKeyPair.Options<as> = {},
+): createKeyPair.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const privateKey = randomPrivateKey({ as })
+  const publicKey = getPublicKey({ privateKey, as })
+
+  return {
+    privateKey: privateKey as never,
+    publicKey: publicKey as never,
+  }
+}
+
+export declare namespace createKeyPair {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private and public keys.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> = {
+    privateKey:
+      | (as extends 'Bytes' ? Bytes.Bytes : never)
+      | (as extends 'Hex' ? Hex.Hex : never)
+    publicKey:
+      | (as extends 'Bytes' ? Bytes.Bytes : never)
+      | (as extends 'Hex' ? Hex.Hex : never)
+  }
+
+  type ErrorType =
+    | Hex.fromBytes.ErrorType
+    | randomPrivateKey.ErrorType
+    | getPublicKey.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Computes the X25519 public key from a provided private key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { X25519 } from 'ox'
+ *
+ * const publicKey = X25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @param options - The options to compute the public key.
+ * @returns The computed public key.
+ */
+export function getPublicKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  options: getPublicKey.Options<as>,
+): getPublicKey.ReturnType<as> {
+  const { as = 'Hex', privateKey } = options
+  const privateKeyBytes = Bytes.from(privateKey)
+  const publicKeyBytes = x25519.getPublicKey(privateKeyBytes)
+  if (as === 'Hex') return Hex.fromBytes(publicKeyBytes) as never
+  return publicKeyBytes as never
+}
+
+export declare namespace getPublicKey {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned public key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+    /**
+     * Private key to compute the public key from.
+     */
+    privateKey: Hex.Hex | Bytes.Bytes
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Computes a shared secret using X25519 elliptic curve Diffie-Hellman between a private key and a public key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { X25519 } from 'ox'
+ *
+ * const { privateKey: privateKeyA } = X25519.createKeyPair()
+ * const { publicKey: publicKeyB } = X25519.createKeyPair()
+ *
+ * const sharedSecret = X25519.getSharedSecret({
+ *   privateKey: privateKeyA,
+ *   publicKey: publicKeyB
+ * })
+ * ```
+ *
+ * @param options - The options to compute the shared secret.
+ * @returns The computed shared secret.
+ */
+export function getSharedSecret<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  options: getSharedSecret.Options<as>,
+): getSharedSecret.ReturnType<as> {
+  const { as = 'Hex', privateKey, publicKey } = options
+  const privateKeyBytes = Bytes.from(privateKey)
+  const publicKeyBytes = Bytes.from(publicKey)
+  const sharedSecretBytes = x25519.getSharedSecret(
+    privateKeyBytes,
+    publicKeyBytes,
+  )
+  if (as === 'Hex') return Hex.fromBytes(sharedSecretBytes) as never
+  return sharedSecretBytes as never
+}
+
+export declare namespace getSharedSecret {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned shared secret.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+    /**
+     * Private key to use for the shared secret computation.
+     */
+    privateKey: Hex.Hex | Bytes.Bytes
+    /**
+     * Public key to use for the shared secret computation.
+     */
+    publicKey: Hex.Hex | Bytes.Bytes
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Generates a random X25519 private key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { X25519 } from 'ox'
+ *
+ * const privateKey = X25519.randomPrivateKey()
+ * ```
+ *
+ * @param options - The options to generate the private key.
+ * @returns The generated private key.
+ */
+export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  options: randomPrivateKey.Options<as> = {},
+): randomPrivateKey.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = x25519.utils.randomPrivateKey()
+  if (as === 'Hex') return Hex.fromBytes(bytes) as never
+  return bytes as never
+}
+
+export declare namespace randomPrivateKey {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType = Hex.fromBytes.ErrorType | Errors.GlobalErrorType
+}

package/index.ts

@@ -1336,6 +1336,38 @@ export * as Caches from './core/Caches.js'
  */
 export * as ContractAddress from './core/ContractAddress.js'
 
+/**
+ * Utilities for working with Ed25519 signatures and key pairs.
+ *
+ * Ed25519 is a modern elliptic curve signature scheme that provides strong security
+ * guarantees and high performance. It is widely used in various cryptographic applications.
+ *
+ * @example
+ * ### Creating Key Pairs
+ *
+ * ```ts twoslash
+ * import { Ed25519 } from 'ox'
+ *
+ * const { privateKey, publicKey } = Ed25519.createKeyPair()
+ * ```
+ *
+ * @example
+ * ### Signing & Verifying
+ *
+ * ```ts twoslash
+ * import { Ed25519 } from 'ox'
+ *
+ * const { privateKey, publicKey } = Ed25519.createKeyPair()
+ * const payload = '0xdeadbeef'
+ *
+ * const signature = Ed25519.sign({ payload, privateKey })
+ * const isValid = Ed25519.verify({ payload, publicKey, signature })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Ed25519 from './core/Ed25519.js'
+
 /**
  * Utility functions for working with ENS names.
  *
@@ -1563,9 +1595,9 @@ export * as Json from './core/Json.js'
  * Utilities & types for working with [Keystores](https://ethereum.org/en/developers/docs/data-structures-and-encoding/web3-secret-storage).
  *
  * @example
- * ### Encrypting & Decrypting Private Keys
+ * ### Encrypting Private Keys
  *
- * Private keys can be encrypted into a JSON keystore using {@link ox#Keystore.(encrypt:function)} and decrypted using {@link ox#Keystore.(decrypt:function)}:
+ * Private keys can be encrypted into a JSON keystore using {@link ox#Keystore.(encrypt:function)}:
  *
  * ```ts twoslash
  * import { Keystore, Secp256k1 } from 'ox'
@@ -1577,7 +1609,7 @@ export * as Json from './core/Json.js'
  * const [key, opts] = Keystore.pbkdf2({ password: 'testpassword' })
  *
  * // Encrypt the private key.
- * const encrypted = await Keystore.encrypt(privateKey, key, opts)
+ * const keystore = Keystore.encrypt(privateKey, key, opts)
  * // @log: {
  * // @log:   "crypto": {
  * // @log:     "cipher": "aes-128-ctr",
@@ -1597,10 +1629,26 @@ export * as Json from './core/Json.js'
  * // @log:   "id": "...",
  * // @log:   "version": 3,
  * // @log: }
+ * ```
+ *
+ * @example
+ * ### Decrypting Private Keys
+ *
+ * Private keys can be decrypted from a JSON keystore using {@link ox#Keystore.(decrypt:function)}:
+ *
+ * ```ts twoslash
+ * // @noErrors
+ * import { Keystore, Secp256k1 } from 'ox'
+ *
+ * const keystore = { crypto: { ... }, id: '...', version: 3 }
+ *
+ * // Derive the key.
+ * const key = Keystore.toKey(keystore, { password: 'testpassword' })
  *
  * // Decrypt the private key.
- * const decrypted = await Keystore.decrypt(encrypted, key)
+ * const decrypted = Keystore.decrypt(keystore, key)
  * // @log: "0x..."
+ *
  * ```
  *
  * @category Crypto
@@ -3499,3 +3547,38 @@ export * as WebCryptoP256 from './core/WebCryptoP256.js'
  * @category Execution Spec
  */
 export * as Withdrawal from './core/Withdrawal.js'
+
+/**
+ * Utilities for working with X25519 elliptic curve Diffie-Hellman key agreement.
+ *
+ * X25519 is a high-performance elliptic curve that can be used to perform
+ * Diffie-Hellman key agreement to derive shared secrets between parties.
+ * It is designed for use with the elliptic curve Diffie-Hellman (ECDH) key agreement scheme.
+ *
+ * @example
+ * ### Creating Key Pairs
+ *
+ * ```ts twoslash
+ * import { X25519 } from 'ox'
+ *
+ * const { privateKey, publicKey } = X25519.createKeyPair()
+ * ```
+ *
+ * @example
+ * ### Deriving Shared Secrets
+ *
+ * ```ts twoslash
+ * import { X25519 } from 'ox'
+ *
+ * const { privateKey: privateKeyA } = X25519.createKeyPair()
+ * const { publicKey: publicKeyB } = X25519.createKeyPair()
+ *
+ * const sharedSecret = X25519.getSharedSecret({
+ *   privateKey: privateKeyA,
+ *   publicKey: publicKeyB
+ * })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as X25519 from './core/X25519.js'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ox",
   "description": "Ethereum Standard Library",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -173,6 +173,11 @@
       "import": "./_esm/core/ContractAddress.js",
       "default": "./_cjs/core/ContractAddress.js"
     },
+    "./Ed25519": {
+      "types": "./_types/core/Ed25519.d.ts",
+      "import": "./_esm/core/Ed25519.js",
+      "default": "./_cjs/core/Ed25519.js"
+    },
     "./Ens": {
       "types": "./_types/core/Ens.d.ts",
       "import": "./_esm/core/Ens.js",
@@ -378,6 +383,11 @@
       "import": "./_esm/core/Withdrawal.js",
       "default": "./_cjs/core/Withdrawal.js"
     },
+    "./X25519": {
+      "types": "./_types/core/X25519.d.ts",
+      "import": "./_esm/core/X25519.js",
+      "default": "./_cjs/core/X25519.js"
+    },
     "./erc4337/EntryPoint": {
       "types": "./_types/erc4337/EntryPoint.d.ts",
       "import": "./_esm/erc4337/EntryPoint.js",

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.8.0'
+export const version = '0.8.2'