ox 0.7.2 → 0.8.1

package/core/Keystore.ts

@@ -12,14 +12,14 @@ 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 Key. */
-type BaseKey<
+/** Base Derivation Options. */
+type BaseDeriveOpts<
   kdf extends string = string,
   kdfparams extends Record<string, unknown> = Record<string, unknown>,
 > = {
   iv: Bytes.Bytes
-  key: () => string
   kdfparams: kdfparams
   kdf: kdf
 }
@@ -33,16 +33,19 @@ export type Keystore = {
       iv: string
     }
     mac: string
-  } & Pick<Key, 'kdf' | 'kdfparams'>
+  } & Pick<DeriveOpts, 'kdf' | 'kdfparams'>
   id: string
   version: 3
 }
 
 /** Key. */
-export type Key = Pbkdf2Key | ScryptKey
+export type Key = (() => Hex.Hex) | Hex.Hex
 
-/** PBKDF2 Key. */
-export type Pbkdf2Key = BaseKey<
+/** Derivation Options. */
+export type DeriveOpts = Pbkdf2DeriveOpts | ScryptDeriveOpts
+
+/** PBKDF2 Derivation Options. */
+export type Pbkdf2DeriveOpts = BaseDeriveOpts<
   'pbkdf2',
   {
     c: number
@@ -52,8 +55,8 @@ export type Pbkdf2Key = BaseKey<
   }
 >
 
-/** Scrypt Key. */
-export type ScryptKey = BaseKey<
+/** Scrypt Derivation Options. */
+export type ScryptDeriveOpts = BaseDeriveOpts<
   'scrypt',
   {
     dklen: number
@@ -80,11 +83,11 @@ export type ScryptKey = BaseKey<
  * // JSON keystore.
  * const keystore = { crypto: { ... }, id: '...', version: 3 }
  *
- * // Derive key from password.
- * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ * // 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..."
  * ```
  *
@@ -93,13 +96,13 @@ export type ScryptKey = BaseKey<
  * @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(`0x${key.key()}`)
+  const key_ = Bytes.from(typeof key === 'function' ? key() : key)
 
   const encKey = Bytes.slice(key_, 0, 16)
   const macKey = Bytes.slice(key_, 16, 32)
@@ -110,7 +113,10 @@ export async function decrypt<as extends 'Hex' | 'Bytes' = 'Hex'>(
   if (!Bytes.isEqual(mac, Bytes.from(`0x${keystore.crypto.mac}`)))
     throw new Error('corrupt keystore')
 
-  const data = ctr(encKey, key.iv).decrypt(ciphertext)
+  const data = ctr(
+    encKey,
+    Bytes.from(`0x${keystore.crypto.cipherparams.iv}`),
+  ).decrypt(ciphertext)
 
   if (as === 'Hex') return Bytes.toHex(data) as never
   return data as never
@@ -143,10 +149,10 @@ export declare namespace decrypt {
  * const privateKey = Secp256k1.randomPrivateKey()
  *
  * // Derive key from password.
- * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ * const [key, opts] = Keystore.pbkdf2({ password: 'testpassword' })
  *
  * // Encrypt the private key.
- * const encrypted = await Keystore.encrypt(privateKey, key)
+ * const encrypted = Keystore.encrypt(privateKey, key, opts)
  * // @log: {
  * // @log:   "crypto": {
  * // @log:     "cipher": "aes-128-ctr",
@@ -173,29 +179,29 @@ 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> {
-  const { id = crypto.randomUUID() } = options
+  options: encrypt.Options,
+): Keystore {
+  const { id = crypto.randomUUID(), kdf, kdfparams, iv } = options
 
-  const key_ = Bytes.from(`0x${key.key()}`)
+  const key_ = Bytes.from(typeof key === 'function' ? key() : key)
   const value_ = Bytes.from(privateKey)
 
   const encKey = Bytes.slice(key_, 0, 16)
   const macKey = Bytes.slice(key_, 16, 32)
 
-  const ciphertext = ctr(encKey, key.iv).encrypt(value_)
+  const ciphertext = ctr(encKey, iv).encrypt(value_)
   const mac = Hash.keccak256(Bytes.concat(macKey, ciphertext))
 
   return {
     crypto: {
       cipher: 'aes-128-ctr',
       ciphertext: Bytes.toHex(ciphertext).slice(2),
-      cipherparams: { iv: Bytes.toHex(key.iv).slice(2) },
-      kdf: key.kdf,
-      kdfparams: key.kdfparams,
+      cipherparams: { iv: Bytes.toHex(iv).slice(2) },
+      kdf,
+      kdfparams,
       mac: Bytes.toHex(mac).slice(2),
     } as Keystore['crypto'],
     id,
@@ -204,7 +210,7 @@ export async function encrypt(
 }
 
 export declare namespace encrypt {
-  type Options = {
+  type Options = DeriveOpts & {
     /** UUID. */
     id?: string | undefined
   }
@@ -217,7 +223,7 @@ export declare namespace encrypt {
  * ```ts twoslash
  * import { Keystore } from 'ox'
  *
- * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ * const [key, opts] = Keystore.pbkdf2({ password: 'testpassword' })
  * ```
  *
  * @param options - PBKDF2 options.
@@ -229,11 +235,10 @@ export function pbkdf2(options: pbkdf2.Options) {
   const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
   const key = Bytes.toHex(
     pbkdf2_noble(sha256, password, salt, { c: iterations, dkLen: 32 }),
-  ).slice(2)
+  )
 
-  return defineKey({
+  return defineKey(() => key, {
     iv,
-    key: () => key,
     kdfparams: {
       c: iterations,
       dklen: 32,
@@ -241,7 +246,7 @@ export function pbkdf2(options: pbkdf2.Options) {
       salt: Bytes.toHex(salt).slice(2),
     },
     kdf: 'pbkdf2',
-  }) satisfies Pbkdf2Key
+  }) satisfies [Key, Pbkdf2DeriveOpts]
 }
 
 export declare namespace pbkdf2 {
@@ -264,7 +269,7 @@ export declare namespace pbkdf2 {
  * ```ts twoslash
  * import { Keystore } from 'ox'
  *
- * const key = await Keystore.pbkdf2Async({ password: 'testpassword' })
+ * const [key, opts] = await Keystore.pbkdf2Async({ password: 'testpassword' })
  * ```
  *
  * @param options - PBKDF2 options.
@@ -279,11 +284,10 @@ export async function pbkdf2Async(options: pbkdf2.Options) {
       c: iterations,
       dkLen: 32,
     }),
-  ).slice(2)
+  )
 
-  return defineKey({
+  return defineKey(() => key, {
     iv,
-    key: () => key,
     kdfparams: {
       c: iterations,
       dklen: 32,
@@ -291,7 +295,7 @@ export async function pbkdf2Async(options: pbkdf2.Options) {
       salt: Bytes.toHex(salt).slice(2),
     },
     kdf: 'pbkdf2',
-  }) satisfies Pbkdf2Key
+  }) satisfies [Key, Pbkdf2DeriveOpts]
 }
 
 export declare namespace pbkdf2Async {
@@ -305,26 +309,22 @@ export declare namespace pbkdf2Async {
  * ```ts twoslash
  * import { Keystore } from 'ox'
  *
- * const key = Keystore.scrypt({ password: 'testpassword' })
+ * const [key, opts] = Keystore.scrypt({ password: 'testpassword' })
  * ```
  *
  * @param options - Scrypt options.
  * @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(
     scrypt_noble(password, salt, { N: n, dkLen: 32, r, p }),
-  ).slice(2)
+  )
 
-  return defineKey({
+  return defineKey(() => key, {
     iv,
-    key: () => key,
     kdfparams: {
       dklen: 32,
       n,
@@ -333,7 +333,7 @@ export function scrypt(options: scrypt.Options) {
       salt: Bytes.toHex(salt).slice(2),
     },
     kdf: 'scrypt',
-  }) satisfies ScryptKey
+  }) satisfies [Key, ScryptDeriveOpts]
 }
 
 export declare namespace scrypt {
@@ -342,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)` */
@@ -356,7 +360,7 @@ export declare namespace scrypt {
  * ```ts twoslash
  * import { Keystore } from 'ox'
  *
- * const key = await Keystore.scryptAsync({ password: 'testpassword' })
+ * const [key, opts] = await Keystore.scryptAsync({ password: 'testpassword' })
  * ```
  *
  * @param options - Scrypt options.
@@ -371,11 +375,10 @@ export async function scryptAsync(options: scrypt.Options) {
   const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
   const key = Bytes.toHex(
     await scryptAsync_noble(password, salt, { N: n, dkLen: 32, r, p }),
-  ).slice(2)
+  )
 
-  return defineKey({
+  return defineKey(() => key, {
     iv,
-    key: () => key,
     kdfparams: {
       dklen: 32,
       n,
@@ -384,29 +387,157 @@ export async function scryptAsync(options: scrypt.Options) {
       salt: Bytes.toHex(salt).slice(2),
     },
     kdf: 'scrypt',
-  }) satisfies ScryptKey
+  }) satisfies [Key, ScryptDeriveOpts]
 }
 
 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 */
-function defineKey<const key extends defineKey.Value>(
-  key: key,
-): key & { iv: Bytes.Bytes } {
-  const iv = key.iv ? Bytes.from(key.iv) : Bytes.random(16)
-  return { ...key, iv }
+function defineKey<
+  const key extends Key,
+  const options extends defineKey.Options,
+>(key: key, options: options): [key, options & { iv: Bytes.Bytes }] {
+  const iv = options.iv ? Bytes.from(options.iv) : Bytes.random(16)
+  return [key, { ...options, iv }] as never
 }
 
 /** @internal */
 declare namespace defineKey {
-  type Value<
+  type Options<
     kdf extends string = string,
     kdfparams extends Record<string, unknown> = Record<string, unknown>,
-  > = Omit<BaseKey<kdf, kdfparams>, 'iv'> & {
+  > = Omit<BaseDeriveOpts<kdf, kdfparams>, 'iv'> & {
     iv?: Bytes.Bytes | Hex.Hex | undefined
   }
 

package/index.ts

@@ -1563,9 +1563,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'
@@ -1574,10 +1574,10 @@ export * as Json from './core/Json.js'
  * const privateKey = Secp256k1.randomPrivateKey()
  *
  * // Derive a key from a password.
- * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ * const [key, opts] = Keystore.pbkdf2({ password: 'testpassword' })
  *
  * // Encrypt the private key.
- * const encrypted = await Keystore.encrypt(privateKey, key)
+ * const keystore = Keystore.encrypt(privateKey, key, opts)
  * // @log: {
  * // @log:   "crypto": {
  * // @log:     "cipher": "aes-128-ctr",
@@ -1597,10 +1597,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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ox",
   "description": "Ethereum Standard Library",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.7.2'
+export const version = '0.8.1'