ox 0.8.1 → 0.8.2

package/core/P256.ts

@@ -9,6 +9,54 @@ import * as Entropy from './internal/entropy.js'
 /** Re-export of noble/curves P256 utilities. */
 export const noble = secp256r1
 
+/**
+ * Creates a new P256 ECDSA key pair consisting of a private key and its corresponding public key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const { privateKey, publicKey } = P256.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 })
+
+  return {
+    privateKey: privateKey as never,
+    publicKey,
+  }
+}
+
+export declare namespace createKeyPair {
+  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'> = {
+    privateKey:
+      | (as extends 'Bytes' ? Bytes.Bytes : never)
+      | (as extends 'Hex' ? Hex.Hex : never)
+    publicKey: PublicKey.PublicKey
+  }
+
+  type ErrorType =
+    | Hex.fromBytes.ErrorType
+    | PublicKey.from.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the P256 ECDSA public key from a provided private key.
  *
@@ -45,6 +93,71 @@ export declare namespace getPublicKey {
   type ErrorType = Errors.GlobalErrorType
 }
 
+/**
+ * Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman) between a private key and a public key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const { privateKey: privateKeyA } = P256.createKeyPair()
+ * const { publicKey: publicKeyB } = P256.createKeyPair()
+ *
+ * const sharedSecret = P256.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 point = secp256r1.ProjectivePoint.fromHex(
+    PublicKey.toHex(publicKey).slice(2),
+  )
+  const privateKeyHex =
+    typeof privateKey === 'string'
+      ? privateKey.slice(2)
+      : Hex.fromBytes(privateKey).slice(2)
+  const sharedPoint = point.multiply(
+    secp256r1.utils.normPrivateKeyToScalar(privateKeyHex),
+  )
+  const sharedSecret = sharedPoint.toRawBytes(true) // compressed format
+  if (as === 'Hex') return Hex.fromBytes(sharedSecret) as never
+  return sharedSecret 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: PublicKey.PublicKey<boolean>
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Hex.fromBytes.ErrorType
+    | PublicKey.toHex.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Generates a random P256 ECDSA private key.
  *
@@ -204,8 +317,7 @@ export declare namespace sign {
  * ```ts twoslash
  * import { P256 } from 'ox'
  *
- * const privateKey = P256.randomPrivateKey()
- * const publicKey = P256.getPublicKey({ privateKey })
+ * const { privateKey, publicKey } = P256.createKeyPair()
  * const signature = P256.sign({ payload: '0xdeadbeef', privateKey })
  *
  * const verified = P256.verify({ // [!code focus]

package/core/Secp256k1.ts

@@ -11,6 +11,54 @@ import type { OneOf } from './internal/types.js'
 /** Re-export of noble/curves secp256k1 utilities. */
 export const noble = secp256k1
 
+/**
+ * Creates a new secp256k1 ECDSA key pair consisting of a private key and its corresponding public key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const { privateKey, publicKey } = Secp256k1.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 })
+
+  return {
+    privateKey: privateKey as never,
+    publicKey,
+  }
+}
+
+export declare namespace createKeyPair {
+  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'> = {
+    privateKey:
+      | (as extends 'Bytes' ? Bytes.Bytes : never)
+      | (as extends 'Hex' ? Hex.Hex : never)
+    publicKey: PublicKey.PublicKey
+  }
+
+  type ErrorType =
+    | Hex.fromBytes.ErrorType
+    | PublicKey.from.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the secp256k1 ECDSA public key from a provided private key.
  *
@@ -48,6 +96,68 @@ export declare namespace getPublicKey {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman) between a private key and a public key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const { privateKey: privateKeyA } = Secp256k1.createKeyPair()
+ * const { publicKey: publicKeyB } = Secp256k1.createKeyPair()
+ *
+ * const sharedSecret = Secp256k1.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 point = secp256k1.ProjectivePoint.fromHex(
+    PublicKey.toHex(publicKey).slice(2),
+  )
+  const sharedPoint = point.multiply(
+    secp256k1.utils.normPrivateKeyToScalar(Hex.from(privateKey).slice(2)),
+  )
+  const sharedSecret = sharedPoint.toRawBytes(true) // compressed format
+  if (as === 'Hex') return Hex.fromBytes(sharedSecret) as never
+  return sharedSecret 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: PublicKey.PublicKey<boolean>
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Hex.from.ErrorType
+    | PublicKey.toHex.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Generates a random ECDSA private key on the secp256k1 curve.
  *

package/core/WebCryptoP256.ts

@@ -1,7 +1,7 @@
 import { p256 } from '@noble/curves/p256'
 import * as Bytes from './Bytes.js'
 import type * as Errors from './Errors.js'
-import type * as Hex from './Hex.js'
+import * as Hex from './Hex.js'
 import * as PublicKey from './PublicKey.js'
 import type * as Signature from './Signature.js'
 import type { Compute } from './internal/types.js'
@@ -68,6 +68,146 @@ export declare namespace createKeyPair {
   type ErrorType = PublicKey.from.ErrorType | Errors.GlobalErrorType
 }
 
+/**
+ * Generates an ECDH P256 key pair for key agreement that includes:
+ *
+ * - a `privateKey` of type [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
+ * - a `publicKey` of type {@link ox#PublicKey.PublicKey}
+ *
+ * @example
+ * ```ts twoslash
+ * import { WebCryptoP256 } from 'ox'
+ *
+ * const { publicKey, privateKey } = await WebCryptoP256.createKeyPairECDH()
+ * // @log: {
+ * // @log:   privateKey: CryptoKey {},
+ * // @log:   publicKey: {
+ * // @log:     x: 59295962801117472859457908919941473389380284132224861839820747729565200149877n,
+ * // @log:     y: 24099691209996290925259367678540227198235484593389470330605641003500238088869n,
+ * // @log:     prefix: 4,
+ * // @log:   },
+ * // @log: }
+ * ```
+ *
+ * @param options - Options for creating the key pair.
+ * @returns The key pair.
+ */
+export async function createKeyPairECDH(
+  options: createKeyPairECDH.Options = {},
+): Promise<createKeyPairECDH.ReturnType> {
+  const { extractable = false } = options
+  const keypair = await globalThis.crypto.subtle.generateKey(
+    {
+      name: 'ECDH',
+      namedCurve: 'P-256',
+    },
+    extractable,
+    ['deriveKey', 'deriveBits'],
+  )
+  const publicKey_raw = await globalThis.crypto.subtle.exportKey(
+    'raw',
+    keypair.publicKey,
+  )
+  const publicKey = PublicKey.from(new Uint8Array(publicKey_raw))
+  return {
+    privateKey: keypair.privateKey,
+    publicKey,
+  }
+}
+
+export declare namespace createKeyPairECDH {
+  type Options = {
+    /** A boolean value indicating whether it will be possible to export the private key using `globalThis.crypto.subtle.exportKey()`. */
+    extractable?: boolean | undefined
+  }
+
+  type ReturnType = Compute<{
+    privateKey: CryptoKey
+    publicKey: PublicKey.PublicKey
+  }>
+
+  type ErrorType = PublicKey.from.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman) between a private key and a public key using Web Crypto APIs.
+ *
+ * @example
+ * ```ts twoslash
+ * import { WebCryptoP256 } from 'ox'
+ *
+ * const { privateKey: privateKeyA } = await WebCryptoP256.createKeyPairECDH()
+ * const { publicKey: publicKeyB } = await WebCryptoP256.createKeyPairECDH()
+ *
+ * const sharedSecret = await WebCryptoP256.getSharedSecret({
+ *   privateKey: privateKeyA,
+ *   publicKey: publicKeyB
+ * })
+ * ```
+ *
+ * @param options - The options to compute the shared secret.
+ * @returns The computed shared secret.
+ */
+export async function getSharedSecret<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  options: getSharedSecret.Options<as>,
+): Promise<getSharedSecret.ReturnType<as>> {
+  const { as = 'Hex', privateKey, publicKey } = options
+
+  if (privateKey.algorithm.name === 'ECDSA') {
+    throw new Error(
+      'privateKey is not compatible with ECDH. please use `createKeyPairECDH` to create an ECDH key.',
+    )
+  }
+
+  const publicKeyCrypto = await globalThis.crypto.subtle.importKey(
+    'raw',
+    PublicKey.toBytes(publicKey),
+    { name: 'ECDH', namedCurve: 'P-256' },
+    false,
+    [],
+  )
+
+  const sharedSecretBuffer = await globalThis.crypto.subtle.deriveBits(
+    {
+      name: 'ECDH',
+      public: publicKeyCrypto,
+    },
+    privateKey,
+    256, // 32 bytes * 8 bits/byte
+  )
+
+  const sharedSecret = new Uint8Array(sharedSecretBuffer)
+  if (as === 'Hex') return Hex.fromBytes(sharedSecret) as never
+  return sharedSecret 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 (must be a CryptoKey for ECDH).
+     */
+    privateKey: CryptoKey
+    /**
+     * Public key to use for the shared secret computation.
+     */
+    publicKey: PublicKey.PublicKey<boolean>
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | PublicKey.toBytes.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Signs a payload with the provided `CryptoKey` private key and returns a P256 signature.
  *

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.
  *
@@ -3515,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'