ox 0.8.0 → 0.8.2

package/core/Keystore.ts

@@ -12,6 +12,7 @@ import * as Bytes from './Bytes.js'
 import type * as Errors from './Errors.js'
 import * as Hash from './Hash.js'
 import type * as Hex from './Hex.js'
+import type { OneOf } from './internal/types.js'
 
 /** Base Derivation Options. */
 type BaseDeriveOpts<
@@ -82,11 +83,11 @@ export type ScryptDeriveOpts = BaseDeriveOpts<
  * // JSON keystore.
  * const keystore = { crypto: { ... }, id: '...', version: 3 }
  *
- * // Key that was previously derived from `Keystore.scrypt` or `Keystore.pbkdf2`.
- * const key = "0x..."
+ * // Derive the key using your password.
+ * const key = Keystore.toKey(keystore, { password: 'hunter2' })
  *
  * // Decrypt the private key.
- * const privateKey = await Keystore.decrypt(keystore, key)
+ * const privateKey = Keystore.decrypt(keystore, key)
  * // @log: "0x..."
  * ```
  *
@@ -95,11 +96,11 @@ export type ScryptDeriveOpts = BaseDeriveOpts<
  * @param options - Decryption options.
  * @returns Decrypted private key.
  */
-export async function decrypt<as extends 'Hex' | 'Bytes' = 'Hex'>(
+export function decrypt<as extends 'Hex' | 'Bytes' = 'Hex'>(
   keystore: Keystore,
   key: Key,
   options: decrypt.Options<as> = {},
-): Promise<decrypt.ReturnType<as>> {
+): decrypt.ReturnType<as> {
   const { as = 'Hex' } = options
   const key_ = Bytes.from(typeof key === 'function' ? key() : key)
 
@@ -151,7 +152,7 @@ export declare namespace decrypt {
  * const [key, opts] = Keystore.pbkdf2({ password: 'testpassword' })
  *
  * // Encrypt the private key.
- * const encrypted = await Keystore.encrypt(privateKey, key, opts)
+ * const encrypted = Keystore.encrypt(privateKey, key, opts)
  * // @log: {
  * // @log:   "crypto": {
  * // @log:     "cipher": "aes-128-ctr",
@@ -178,11 +179,11 @@ export declare namespace decrypt {
  * @param options - Encryption options.
  * @returns Encrypted keystore.
  */
-export async function encrypt(
+export function encrypt(
   privateKey: Bytes.Bytes | Hex.Hex,
   key: Key,
   options: encrypt.Options,
-): Promise<Keystore> {
+): Keystore {
   const { id = crypto.randomUUID(), kdf, kdfparams, iv } = options
 
   const key_ = Bytes.from(typeof key === 'function' ? key() : key)
@@ -315,10 +316,7 @@ export declare namespace pbkdf2Async {
  * @returns Scrypt key.
  */
 export function scrypt(options: scrypt.Options) {
-  const { iv, n = 262_144, password } = options
-
-  const p = 8
-  const r = 1
+  const { iv, n = 262_144, password, p = 8, r = 1 } = options
 
   const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
   const key = Bytes.toHex(
@@ -344,6 +342,10 @@ export declare namespace scrypt {
     iv?: Bytes.Bytes | Hex.Hex | undefined
     /** Cost factor. @default 262_144 */
     n?: number | undefined
+    /** Parallelization factor. @default 8 */
+    p?: number | undefined
+    /** Block size. @default 1 */
+    r?: number | undefined
     /** Password to derive key from. */
     password: string
     /** Salt to use for key derivation. @default `Bytes.random(32)` */
@@ -392,6 +394,133 @@ export declare namespace scryptAsync {
   type Options = scrypt.Options
 }
 
+/**
+ * Extracts a Key from a JSON Keystore to use for decryption.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Keystore } from 'ox'
+ *
+ * // JSON keystore.
+ * const keystore = { crypto: { ... }, id: '...', version: 3 }
+ *
+ * const key = Keystore.toKey(keystore, { password: 'hunter2' }) // [!code focus]
+ *
+ * const decrypted = Keystore.decrypt(keystore, key)
+ * ```
+ *
+ * @param keystore - JSON Keystore
+ * @param options - Options
+ * @returns Key
+ */
+export function toKey(keystore: Keystore, options: toKey.Options): Key {
+  const { crypto } = keystore
+  const { password } = options
+  const { cipherparams, kdf, kdfparams } = crypto
+  const { iv } = cipherparams
+  const { c, n, p, r, salt } = kdfparams as OneOf<
+    Pbkdf2DeriveOpts['kdfparams'] | ScryptDeriveOpts['kdfparams']
+  >
+
+  const [key] = (() => {
+    switch (kdf) {
+      case 'scrypt':
+        return scrypt({
+          iv: Bytes.from(`0x${iv}`),
+          n,
+          p,
+          r,
+          salt: Bytes.from(`0x${salt}`),
+          password,
+        })
+      case 'pbkdf2':
+        return pbkdf2({
+          iv: Bytes.from(`0x${iv}`),
+          iterations: c,
+          password,
+          salt: Bytes.from(`0x${salt}`),
+        })
+      default:
+        throw new Error('unsupported kdf')
+    }
+  })()
+
+  return key
+}
+
+export declare namespace toKey {
+  type Options = {
+    /** Password to derive key from. */
+    password: string
+  }
+}
+
+/**
+ * Extracts a Key asynchronously from a JSON Keystore to use for decryption.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Keystore } from 'ox'
+ *
+ * // JSON keystore.
+ * const keystore = { crypto: { ... }, id: '...', version: 3 }
+ *
+ * const key = await Keystore.toKeyAsync(keystore, { password: 'hunter2' }) // [!code focus]
+ *
+ * const decrypted = Keystore.decrypt(keystore, key)
+ * ```
+ *
+ * @param keystore - JSON Keystore
+ * @param options - Options
+ * @returns Key
+ */
+export async function toKeyAsync(
+  keystore: Keystore,
+  options: toKeyAsync.Options,
+): Promise<Key> {
+  const { crypto } = keystore
+  const { password } = options
+  const { cipherparams, kdf, kdfparams } = crypto
+  const { iv } = cipherparams
+  const { c, n, p, r, salt } = kdfparams as OneOf<
+    Pbkdf2DeriveOpts['kdfparams'] | ScryptDeriveOpts['kdfparams']
+  >
+
+  const [key] = await (async () => {
+    switch (kdf) {
+      case 'scrypt':
+        return await scryptAsync({
+          iv: Bytes.from(`0x${iv}`),
+          n,
+          p,
+          r,
+          salt: Bytes.from(`0x${salt}`),
+          password,
+        })
+      case 'pbkdf2':
+        return await pbkdf2({
+          iv: Bytes.from(`0x${iv}`),
+          iterations: c,
+          password,
+          salt: Bytes.from(`0x${salt}`),
+        })
+      default:
+        throw new Error('unsupported kdf')
+    }
+  })()
+
+  return key
+}
+
+export declare namespace toKeyAsync {
+  type Options = {
+    /** Password to derive key from. */
+    password: string
+  }
+}
+
 ///////////////////////////////////////////////////////////////////////////
 
 /** @internal */

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.
  *