sailfork / t3code-github / .repos/ effect/ packages/ platform/ node-shared/ src/ NodeCrypto.ts

/**
 * Node.js layers for the `effect/crypto` modules, also used by Bun.
 *
 * {@link layerDigest} runs MD5 and SHA on `node:crypto`, {@link layerMac} runs
 * HMAC on `node:crypto`, {@link layerKdf} adds Argon2id, {@link layerAead}
 * runs ChaCha20-Poly1305 on `node:crypto`, and {@link layerSecureRandom},
 * {@link layerCipher}, {@link layerSignature}, {@link layerKeyAgreement}, and
 * {@link layerKeyWrap} run the core WebCrypto layers. Each Node.js layer
 * handles only the algorithms and keys it exists for and hands the rest to
 * the core WebCrypto implementation. Layers that need `SecureRandom` get it
 * from {@link layerSecureRandom}, so no layer here has requirements.
 * {@link layer} provides every family at once; provide a family's own layer to
 * pick services selectively.
 *
 * `CryptoKey`-backed keys go through Node.js's `crypto.subtle`, because
 * `KeyObject.from(cryptoKey)` is deprecated (DEP0204). A `CryptoKey` must
 * come from the `WebCrypto` reference: Node.js rejects one from another
 * reference with a `TypeError`, which is a defect.
 *
 * @stability unstable
 * @since 1.0.0
 */
import * as Aead from "effect/crypto/Aead"
import * as Cipher from "effect/crypto/Cipher"
import * as CryptoError from "effect/crypto/CryptoError"
import * as Digest from "effect/crypto/Digest"
import * as Kdf from "effect/crypto/Kdf"
import * as KeyAgreement from "effect/crypto/KeyAgreement"
import * as KeyWrap from "effect/crypto/KeyWrap"
import * as Mac from "effect/crypto/Mac"
import * as SecureRandom from "effect/crypto/SecureRandom"
import * as Signature from "effect/crypto/Signature"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"
import * as NodeCrypto from "node:crypto"

/**
 * Layer that provides `SecureRandom` from `getRandomValues` on the `WebCrypto`
 * reference.
 *
 * **Details**
 *
 * This is `SecureRandom.layerWebCrypto`, re-exported so that Node.js programs
 * take every crypto layer from `NodeCrypto`. `node:crypto` adds nothing here.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerSecureRandom: Layer.Layer<SecureRandom.SecureRandom> = SecureRandom.layerWebCrypto

const nodeHashNames: Record<Digest.Algorithm["name"], string> = {
  "MD5": "md5",
  "SHA-1": "sha1",
  "SHA-256": "sha256",
  "SHA-384": "sha384",
  "SHA-512": "sha512"
}

// Copies the Buffer, which may be a view into Node's shared pool.
const nodeDigest = (algorithm: Digest.Algorithm, data: Uint8Array): Uint8Array =>
  new Uint8Array(NodeCrypto.createHash(nodeHashNames[algorithm.name]).update(data).digest())

/**
 * Layer that provides `Digest` using `createHash` from `node:crypto`.
 *
 * **Details**
 *
 * MD5 and the SHA algorithms run synchronously on `node:crypto`. On Node.js,
 * `crypto.subtle.digest` sends each call to the threadpool, which is
 * noticeably slower for small inputs. Output is identical to
 * `Digest.layerWebCrypto`.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerDigest: Layer.Layer<Digest.Digest> = Layer.succeed(Digest.Digest, {
  digest: (algorithm, data) => Effect.sync(() => nodeDigest(algorithm, data)),
  digestHex: (algorithm, data) =>
    Effect.sync(() => NodeCrypto.createHash(nodeHashNames[algorithm.name]).update(data).digest("hex"))
})

// Copies the Buffer, which may be a view into Node's shared pool.
const nodeHmac = (hash: Digest.Algorithm["name"], key: Uint8Array, data: Uint8Array): Uint8Array =>
  new Uint8Array(NodeCrypto.createHmac(nodeHashNames[hash], key).update(data).digest())

/**
 * Layer that provides `Mac` using `createHmac` from `node:crypto`.
 *
 * **Details**
 *
 * Byte-backed keys sign and verify synchronously on `node:crypto`, since
 * webhook verification is a server hot path. `CryptoKey`-backed keys go
 * through Node.js's `crypto.subtle`, and generated keys come from
 * {@link layerSecureRandom}. This is `Mac.layerWebCryptoWith` with a
 * `node:crypto` primitive, so output and errors are identical to
 * `Mac.layerWebCrypto`.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerMac: Layer.Layer<Mac.Mac> = Mac.layerWebCryptoWith({
  hmac: nodeHmac
}).pipe(Layer.provide(layerSecureRandom))

const kdfFailure = (reason: CryptoError.CryptoErrorReason): Effect.Effect<never, CryptoError.CryptoError> =>
  Effect.fail(new CryptoError.CryptoError({ module: "Kdf", method: "derive", reason }))

const argon2Unsupported = (cause?: unknown) =>
  kdfFailure(
    new CryptoError.Unsupported({
      description: "NodeCrypto.layerKdf does not provide argon2id on this runtime",
      ...(cause === undefined ? {} : { cause })
    })
  )

// Only a missing Argon2id engine is a typed failure; anything else is a defect.
const argon2Failure = (cause: unknown): Effect.Effect<never, CryptoError.CryptoError> =>
  typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ERR_CRYPTO_ARGON2_NOT_SUPPORTED"
    ? argon2Unsupported(cause)
    : Effect.die(cause)

const isIntegerIn = (n: number, min: number, max: number): boolean => Number.isSafeInteger(n) && n >= min && n <= max

type DeriveOptions = Parameters<Kdf.Kdf["Service"]["derive"]>[2]

// The RFC 9106 bounds, checked before `node:crypto`, which throws on them.
const argon2Problem = (algorithm: Kdf.Argon2id, options: DeriveOptions): string | undefined => {
  if (options.info !== undefined) return "info only applies to HKDF"
  const uint32 = (n: number) => isIntegerIn(n, 1, 0xffff_ffff)
  if (!uint32(algorithm.passes) || !isIntegerIn(algorithm.parallelism, 1, 0xff_ffff)) {
    return "passes must be between 1 and 2^32 - 1 and parallelism between 1 and 2^24 - 1"
  }
  if (!uint32(algorithm.memory) || algorithm.memory < 8 * algorithm.parallelism) {
    return "memory must be at least 8 KiB per lane and below 2^32 KiB"
  }
  if (options.salt.length < 8) return "salt must be at least 8 bytes"
  return isIntegerIn(options.length, 4, 0xffff_ffff) ? undefined : "length must be between 4 and 2^32 - 1 bytes"
}

const argon2id = (algorithm: Kdf.Argon2id, secret: Uint8Array, options: DeriveOptions) =>
  Effect.callback<Uint8Array, CryptoError.CryptoError>((resume) => {
    const problem = argon2Problem(algorithm, options)
    if (problem !== undefined) return resume(kdfFailure(new CryptoError.InvalidArgument({ description: problem })))
    // Checked at call time, since Node.js added `argon2` in 24.7.
    if (typeof NodeCrypto.argon2 !== "function") return resume(argon2Unsupported())
    try {
      NodeCrypto.argon2("argon2id", {
        message: secret,
        nonce: options.salt,
        memory: algorithm.memory,
        passes: algorithm.passes,
        parallelism: algorithm.parallelism,
        tagLength: options.length
      }, (cause, key) => {
        if (cause) resume(argon2Failure(cause))
        else resume(Effect.succeed(new Uint8Array(key.buffer, key.byteOffset, key.length)))
      })
    } catch (cause) {
      resume(argon2Failure(cause))
    }
  }).pipe(Effect.uninterruptible)

/**
 * Layer that provides `Kdf`, adding Argon2id from `node:crypto`.
 *
 * **Details**
 *
 * Argon2id runs on `argon2` from `node:crypto`, which needs Node.js 24.7 or
 * later linked against OpenSSL 3.2, or Bun 1.4. Support is checked at call
 * time: on other runtimes, deriving with Argon2id fails with an `Unsupported`
 * reason. HKDF and PBKDF2 go through `Kdf.layerWebCrypto`, which keeps them
 * off the event loop.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerKdf: Layer.Layer<Kdf.Kdf> = Layer.effect(
  Kdf.Kdf,
  Effect.gen(function*() {
    const core = yield* Kdf.Kdf
    return Kdf.Kdf.of({
      derive: (algorithm, secret, options) =>
        algorithm._tag === "Argon2id" ? argon2id(algorithm, secret, options) : core.derive(algorithm, secret, options)
    })
  })
).pipe(Layer.provide(Kdf.layerWebCrypto))

// Copies into a fresh array, wiping the parts, so no plaintext stays in
// Node.js's shared Buffer pool.
const concat = (parts: ReadonlyArray<Uint8Array>): Uint8Array => {
  const output = new Uint8Array(parts.reduce((length, part) => length + part.length, 0))
  let offset = 0
  for (const part of parts) {
    output.set(part, offset)
    offset += part.length
    part.fill(0)
  }
  return output
}

const nodeChacha: Aead.Implementation = {
  encrypt: (key, nonce, plaintext, aad) => {
    const cipher = NodeCrypto.createCipheriv("chacha20-poly1305", key, nonce, { authTagLength: 16 })
    cipher.setAAD(aad)
    return concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()])
  },
  decrypt: (key, nonce, ciphertext, aad) => {
    const decipher = NodeCrypto.createDecipheriv("chacha20-poly1305", key, nonce, { authTagLength: 16 })
    decipher.setAAD(aad)
    decipher.setAuthTag(ciphertext.subarray(ciphertext.length - 16))
    const plaintext = decipher.update(ciphertext.subarray(0, ciphertext.length - 16))
    try {
      // `final` throws only when the tag does not match.
      return concat([plaintext, decipher.final()])
    } catch {
      plaintext.fill(0)
      return undefined
    }
  }
}

/**
 * Layer that provides `Aead`, running ChaCha20-Poly1305 on `node:crypto`.
 *
 * **Details**
 *
 * Byte-backed ChaCha20-Poly1305 keys encrypt and decrypt synchronously on
 * `node:crypto`. AES-GCM runs on `crypto.subtle` and XChaCha20-Poly1305 on its
 * pure TypeScript implementation. This is `Aead.layerWebCryptoWith` with a
 * `node:crypto` implementation, so arguments are checked and errors reported
 * as in `Aead.layerWebCrypto`. Bun's `node:crypto` lacks ChaCha20-Poly1305, so
 * on Bun this layer runs the core implementation. Output is identical to
 * `Aead.layerWebCrypto`. Generated keys come from {@link layerSecureRandom}.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerAead: Layer.Layer<Aead.Aead> = Aead.layerWebCryptoWith(
  NodeCrypto.getCiphers().includes("chacha20-poly1305") ? { implementations: { chacha20Poly1305: nodeChacha } } : {}
).pipe(Layer.provide(layerSecureRandom))

/**
 * Layer that provides `Cipher` from `crypto.subtle` on the `WebCrypto`
 * reference.
 *
 * **Details**
 *
 * This is `Cipher.layerWebCrypto` with {@link layerSecureRandom}, so that
 * Node.js programs take every crypto layer from `NodeCrypto`. Node.js's
 * `crypto.subtle` already runs AES-CTR and AES-CBC on OpenSSL.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerCipher: Layer.Layer<Cipher.Cipher> = Cipher.layerWebCrypto.pipe(
  Layer.provide(layerSecureRandom)
)

/**
 * Layer that provides `Signature` on Node.js's `crypto.subtle`.
 *
 * **Details**
 *
 * This is `Signature.layerWebCrypto` with {@link layerSecureRandom}, so that
 * Node.js programs take every crypto layer from `NodeCrypto`.
 * `CryptoKey`-backed keys go through Node.js's `crypto.subtle`, because
 * `KeyObject.from(cryptoKey)` is deprecated (DEP0204).
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerSignature: Layer.Layer<Signature.Signature> = Signature.layerWebCrypto.pipe(
  Layer.provide(layerSecureRandom)
)

/**
 * Layer that provides `KeyAgreement` on Node.js's `crypto.subtle`.
 *
 * **Details**
 *
 * This is `KeyAgreement.layerWebCrypto` with {@link layerSecureRandom}, so
 * that Node.js programs take every crypto layer from `NodeCrypto`.
 * `CryptoKey`-backed keys go through Node.js's `crypto.subtle`, because
 * `KeyObject.from(cryptoKey)` is deprecated (DEP0204).
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerKeyAgreement: Layer.Layer<KeyAgreement.KeyAgreement> = KeyAgreement.layerWebCrypto.pipe(
  Layer.provide(layerSecureRandom)
)

/**
 * Layer that provides `KeyWrap` on Node.js's `crypto.subtle`.
 *
 * **Details**
 *
 * This is `KeyWrap.layerWebCrypto` with {@link layerSecureRandom}, so that
 * Node.js programs take every crypto layer from `NodeCrypto`. Node.js's
 * `crypto.subtle` runs AES-KW and RSA-OAEP on OpenSSL. `CryptoKey`-backed
 * keys go through it, because `KeyObject.from(cryptoKey)` is deprecated
 * (DEP0204).
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerKeyWrap: Layer.Layer<KeyWrap.KeyWrap> = KeyWrap.layerWebCrypto.pipe(
  Layer.provide(layerSecureRandom)
)

/**
 * Layer that provides every `effect/crypto` service with the Node.js
 * implementations.
 *
 * **Details**
 *
 * This merges the family layers of this module, so it requires nothing. It
 * keeps the `node:crypto` implementations of {@link layerDigest},
 * {@link layerMac}, {@link layerKdf}, and {@link layerAead}.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layer: Layer.Layer<
  | SecureRandom.SecureRandom
  | Digest.Digest
  | Mac.Mac
  | Kdf.Kdf
  | Aead.Aead
  | Cipher.Cipher
  | Signature.Signature
  | KeyAgreement.KeyAgreement
  | KeyWrap.KeyWrap
> = Layer.mergeAll(
  layerSecureRandom,
  layerDigest,
  layerMac,
  layerKdf,
  layerAead,
  layerCipher,
  layerSignature,
  layerKeyAgreement,
  layerKeyWrap
)