effect 4.0.6 → 4.1.0

package/src/crypto/Digest.ts

@@ -0,0 +1,167 @@
+/**
+ * Message digests: MD5, SHA-1, SHA-256, SHA-384, and SHA-512.
+ *
+ * The {@link Digest} service computes digests and lowercase hex strings.
+ * Provide {@link layerWebCrypto} to run it on the `WebCrypto` reference,
+ * or mock the service with `Layer.mock`.
+ *
+ * MD5 runs a pure TypeScript implementation vendored from `@noble/hashes`
+ * 2.4.0, because WebCrypto does not provide it. Whether the `@noble/hashes`
+ * audit covers its MD5 code has not been confirmed. The SHA algorithms run on
+ * `crypto.subtle`.
+ *
+ * Output is stable byte for byte, so digests can be persisted.
+ *
+ * **Gotchas**
+ *
+ * MD5 and SHA-1 are broken for collision resistance. Use them only for
+ * interoperability with existing protocols and checksums.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
+import * as Hex from "../encoding/Hex.ts"
+import * as Layer from "../Layer.ts"
+import { webCryptoDigest } from "./internal/digest.ts"
+import * as Md5 from "./internal/md5.ts"
+import { WebCrypto } from "./WebCrypto.ts"
+
+/**
+ * A digest algorithm, such as {@link sha256}.
+ *
+ * **Details**
+ *
+ * `name` is the WebCrypto algorithm name. `implementation` is the pure
+ * TypeScript code for algorithms that WebCrypto does not provide, which a
+ * layer calls when it has no native mapping for `name`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Algorithm {
+  readonly name: "MD5" | "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
+  readonly outputLength: number
+  readonly implementation: ((data: Uint8Array) => Uint8Array) | undefined
+}
+
+/**
+ * MD5 (RFC 1321), with a 16-byte output.
+ *
+ * **Gotchas**
+ *
+ * MD5 is broken for collision resistance. Use it only for interoperability
+ * with existing protocols and checksums.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const md5: Algorithm = { name: "MD5", outputLength: 16, implementation: Md5.md5 }
+
+/**
+ * SHA-1, with a 20-byte output.
+ *
+ * **Gotchas**
+ *
+ * SHA-1 is broken for collision resistance. Use it only for interoperability
+ * with existing protocols.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const sha1: Algorithm = { name: "SHA-1", outputLength: 20, implementation: undefined }
+
+/**
+ * SHA-256, with a 32-byte output.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const sha256: Algorithm = { name: "SHA-256", outputLength: 32, implementation: undefined }
+
+/**
+ * SHA-384, with a 48-byte output.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const sha384: Algorithm = { name: "SHA-384", outputLength: 48, implementation: undefined }
+
+/**
+ * SHA-512, with a 64-byte output.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const sha512: Algorithm = { name: "SHA-512", outputLength: 64, implementation: undefined }
+
+/**
+ * Converts a hash name to an algorithm-name suffix: `"SHA-256"` to `"Sha256"`.
+ *
+ * @internal
+ */
+export const nameSuffix = (hash: Algorithm): string =>
+  hash.name.charAt(0) + hash.name.slice(1).toLowerCase().replace("-", "")
+
+/**
+ * Service that computes message digests.
+ *
+ * **Example** (Hashing with SHA-256)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { Digest } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const digest = yield* Digest.Digest
+ *   return yield* digest.digestHex(Digest.sha256, new TextEncoder().encode("abc"))
+ * })
+ *
+ * const hex = await Effect.runPromise(program.pipe(Effect.provide(Digest.layerWebCrypto)))
+ * hex.length // => 64
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class Digest extends Context.Service<Digest, {
+  /**
+   * Computes the digest of `data`.
+   */
+  readonly digest: (algorithm: Algorithm, data: Uint8Array) => Effect.Effect<Uint8Array>
+  /**
+   * Computes the digest of `data` as lowercase hex.
+   */
+  readonly digestHex: (algorithm: Algorithm, data: Uint8Array) => Effect.Effect<string>
+}>()("effect/crypto/Digest") {}
+
+/**
+ * Layer that provides `Digest` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * The SHA algorithms run on `crypto.subtle`, and MD5 on the pure TypeScript
+ * implementation. Without `crypto.subtle`, the layer still builds and MD5
+ * keeps working, but SHA digests die.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCrypto: Layer.Layer<Digest> = Layer.effect(
+  Digest,
+  WebCrypto.use((crypto) =>
+    Effect.succeed({
+      digest: (algorithm, data) => webCryptoDigest(crypto, algorithm, data),
+      digestHex: (algorithm, data) => Effect.map(webCryptoDigest(crypto, algorithm, data), Hex.encode)
+    })
+  )
+)

package/src/crypto/Kdf.ts

@@ -0,0 +1,315 @@
+/**
+ * Key derivation: HKDF, PBKDF2, and Argon2id.
+ *
+ * The {@link Kdf} service derives bytes from a secret with an algorithm value
+ * such as {@link hkdfSha256}, {@link pbkdf2Sha256}, or `argon2id()`. The
+ * output is plain bytes: turn it into a typed key with the target family's raw
+ * constructor, such as `Mac.key`.
+ *
+ * **Gotchas**
+ *
+ * - The secret is bytes, with no string overload. Encode passwords yourself,
+ *   and normalize their Unicode form first if users type them on different
+ *   platforms.
+ * - `layerWebCrypto` does not provide Argon2id, because WebCrypto has no
+ *   Argon2. Deriving with it fails with an `Unsupported` reason, so programs
+ *   can fall back to PBKDF2. `NodeCrypto.layerKdf` provides Argon2id on
+ *   Node.js 24.7 or later and Bun 1.4.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
+import * as Layer from "../Layer.ts"
+import * as CryptoError from "./CryptoError.ts"
+import * as Digest from "./Digest.ts"
+import * as internal from "./internal/webCrypto.ts"
+import { WebCrypto } from "./WebCrypto.ts"
+
+/**
+ * HKDF (RFC 5869) with a hash, from {@link hkdf}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Hkdf {
+  readonly _tag: "Hkdf"
+  readonly name: string
+  readonly hash: Digest.Algorithm
+}
+
+/**
+ * PBKDF2 (RFC 8018) with a hash and an iteration count, from {@link pbkdf2}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Pbkdf2 {
+  readonly _tag: "Pbkdf2"
+  readonly name: string
+  readonly hash: Digest.Algorithm
+  readonly iterations: number
+}
+
+/**
+ * Argon2id (RFC 9106) with its cost parameters, from {@link argon2id}.
+ *
+ * **Details**
+ *
+ * `memory` is in KiB, `passes` is the number of passes over the memory, and
+ * `parallelism` is the number of lanes.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Argon2id {
+  readonly _tag: "Argon2id"
+  readonly name: string
+  readonly memory: number
+  readonly passes: number
+  readonly parallelism: number
+}
+
+/**
+ * A key derivation algorithm.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Algorithm = Hkdf | Pbkdf2 | Argon2id
+
+/**
+ * Builds the HKDF algorithm for a hash.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdf = (hash: Digest.Algorithm): Hkdf => ({ _tag: "Hkdf", name: `hkdf${Digest.nameSuffix(hash)}`, hash })
+
+/**
+ * Builds a PBKDF2 algorithm for a hash and an iteration count.
+ *
+ * **Details**
+ *
+ * Deriving with an iteration count outside 1 to 2^31 - 1 fails with an
+ * `InvalidArgument` reason.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const pbkdf2 = (options: { readonly hash: Digest.Algorithm; readonly iterations: number }): Pbkdf2 => ({
+  _tag: "Pbkdf2",
+  name: `pbkdf2${Digest.nameSuffix(options.hash)}`,
+  hash: options.hash,
+  iterations: options.iterations
+})
+
+/**
+ * HKDF with SHA-1.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha1: Hkdf = hkdf(Digest.sha1)
+
+/**
+ * HKDF with SHA-256.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha256: Hkdf = hkdf(Digest.sha256)
+
+/**
+ * HKDF with SHA-384.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha384: Hkdf = hkdf(Digest.sha384)
+
+/**
+ * HKDF with SHA-512.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha512: Hkdf = hkdf(Digest.sha512)
+
+/**
+ * PBKDF2 with SHA-256 at 600,000 iterations, OWASP's current figure.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const pbkdf2Sha256: Pbkdf2 = pbkdf2({ hash: Digest.sha256, iterations: 600_000 })
+
+/**
+ * Builds an Argon2id algorithm, with `memory` in KiB.
+ *
+ * **Details**
+ *
+ * Omitted costs default to RFC 9106's second recommended setting: 64 MiB of
+ * memory (`65_536`), 3 passes, and 4 lanes.
+ *
+ * **Gotchas**
+ *
+ * `Kdf.layerWebCrypto` does not provide Argon2id. Use `NodeCrypto.layerKdf`,
+ * or fall back to PBKDF2 on the `Unsupported` reason.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const argon2id = (options?: {
+  readonly memory?: number | undefined
+  readonly passes?: number | undefined
+  readonly parallelism?: number | undefined
+}): Argon2id => ({
+  _tag: "Argon2id",
+  name: "argon2id",
+  memory: options?.memory ?? 65_536,
+  passes: options?.passes ?? 3,
+  parallelism: options?.parallelism ?? 4
+})
+
+/**
+ * Service that derives bytes from a secret.
+ *
+ * **Example** (Deriving a key with HKDF)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { Kdf } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const kdf = yield* Kdf.Kdf
+ *   return yield* kdf.derive(Kdf.hkdfSha256, new Uint8Array(32), {
+ *     salt: new Uint8Array(16),
+ *     info: new TextEncoder().encode("encryption"),
+ *     length: 32
+ *   })
+ * })
+ *
+ * const bytes = await Effect.runPromise(program.pipe(Effect.provide(Kdf.layerWebCrypto)))
+ * bytes.length // => 32
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class Kdf extends Context.Service<Kdf, {
+  /**
+   * Derives `length` bytes from `secret`.
+   *
+   * `info` only applies to HKDF; passing it with PBKDF2 or Argon2id fails
+   * with an `InvalidArgument` reason.
+   */
+  readonly derive: (
+    algorithm: Algorithm,
+    secret: Uint8Array,
+    options: {
+      readonly salt: Uint8Array
+      readonly length: number
+      readonly info?: Uint8Array | undefined
+    }
+  ) => Effect.Effect<Uint8Array, CryptoError.CryptoError>
+}>()("effect/crypto/Kdf") {}
+
+type DeriveOptions = Parameters<Kdf["Service"]["derive"]>[2]
+
+const invalidArgument = (description: string) =>
+  internal.fail("Kdf", "derive", new CryptoError.InvalidArgument({ description }))
+
+const isIntegerIn = (n: number, min: number, max: number): boolean => Number.isSafeInteger(n) && n >= min && n <= max
+
+// Checks the arguments before they reach Web Crypto, which takes a 32-bit bit
+// length that some backends wrap instead of rejecting. Node.js aborts the
+// process on PBKDF2 iteration counts above 2^31 - 1.
+const checkArguments = (
+  algorithm: Algorithm,
+  options: DeriveOptions
+): Effect.Effect<never, CryptoError.CryptoError> | undefined => {
+  if (algorithm._tag !== "Hkdf" && options.info !== undefined) return invalidArgument("info only applies to HKDF")
+  if (algorithm._tag === "Argon2id") return undefined
+  if (algorithm.hash.name === "MD5") return invalidArgument(`${algorithm._tag} needs a SHA hash, not MD5`)
+  if (algorithm._tag === "Hkdf") {
+    const maxLength = 255 * algorithm.hash.outputLength
+    return isIntegerIn(options.length, 1, maxLength)
+      ? undefined
+      : invalidArgument(`length must be between 1 and ${maxLength} bytes for ${algorithm.name}`)
+  }
+  if (!isIntegerIn(algorithm.iterations, 1, 0x7fff_ffff)) {
+    return invalidArgument("iterations must be between 1 and 2^31 - 1")
+  }
+  return isIntegerIn(options.length, 1, 0x1fff_ffff)
+    ? undefined
+    : invalidArgument("length must be between 1 and 2^29 - 1 bytes")
+}
+
+const webCryptoParams = (algorithm: Hkdf | Pbkdf2, options: DeriveOptions): HkdfParams | Pbkdf2Params =>
+  algorithm._tag === "Hkdf"
+    ? {
+      name: "HKDF",
+      hash: algorithm.hash.name,
+      salt: options.salt as BufferSource,
+      info: (options.info ?? new Uint8Array()) as BufferSource
+    }
+    : {
+      name: "PBKDF2",
+      hash: algorithm.hash.name,
+      salt: options.salt as BufferSource,
+      iterations: algorithm.iterations
+    }
+
+/**
+ * Layer that provides `Kdf` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * HKDF and PBKDF2 run on `crypto.subtle`, off the event loop where the runtime
+ * supports it. Argon2id fails with an `Unsupported` reason.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCrypto: Layer.Layer<Kdf> = Layer.effect(
+  Kdf,
+  WebCrypto.use((crypto) =>
+    Effect.succeed(Kdf.of({
+      derive: (algorithm, secret, options) =>
+        Effect.suspend(() => {
+          const failure = checkArguments(algorithm, options)
+          if (failure !== undefined) return failure
+          if (algorithm._tag === "Argon2id") {
+            return internal.fail(
+              "Kdf",
+              "derive",
+              new CryptoError.Unsupported({ description: "Kdf.layerWebCrypto does not provide argon2id" })
+            )
+          }
+          const name = algorithm._tag === "Hkdf" ? "HKDF" : "PBKDF2"
+          return internal.run("Kdf", "derive", algorithm.name, crypto, async (subtle) => {
+            const handle = await subtle.importKey("raw", secret as BufferSource, name, false, ["deriveBits"])
+            return new Uint8Array(
+              await subtle.deriveBits(webCryptoParams(algorithm, options), handle, options.length * 8)
+            )
+          })
+        })
+    }))
+  )
+)