effect 4.0.6 → 4.1.0

package/dist/crypto/Kdf.js

@@ -0,0 +1,212 @@
+/**
+ * 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.js";
+import * as Effect from "../Effect.js";
+import * as Layer from "../Layer.js";
+import * as CryptoError from "./CryptoError.js";
+import * as Digest from "./Digest.js";
+import * as internal from "./internal/webCrypto.js";
+import { WebCrypto } from "./WebCrypto.js";
+/**
+ * Builds the HKDF algorithm for a hash.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdf = hash => ({
+  _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 => ({
+  _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 = /*#__PURE__*/hkdf(Digest.sha1);
+/**
+ * HKDF with SHA-256.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha256 = /*#__PURE__*/hkdf(Digest.sha256);
+/**
+ * HKDF with SHA-384.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha384 = /*#__PURE__*/hkdf(Digest.sha384);
+/**
+ * HKDF with SHA-512.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hkdfSha512 = /*#__PURE__*/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 = /*#__PURE__*/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 => ({
+  _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 /*#__PURE__*/Context.Service()("effect/crypto/Kdf") {}
+const invalidArgument = description => internal.fail("Kdf", "derive", new CryptoError.InvalidArgument({
+  description
+}));
+const isIntegerIn = (n, min, max) => 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, options) => {
+  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, options) => algorithm._tag === "Hkdf" ? {
+  name: "HKDF",
+  hash: algorithm.hash.name,
+  salt: options.salt,
+  info: options.info ?? new Uint8Array()
+} : {
+  name: "PBKDF2",
+  hash: algorithm.hash.name,
+  salt: options.salt,
+  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 = /*#__PURE__*/Layer.effect(Kdf, /*#__PURE__*/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, name, false, ["deriveBits"]);
+      return new Uint8Array(await subtle.deriveBits(webCryptoParams(algorithm, options), handle, options.length * 8));
+    });
+  })
+}))));
+//# sourceMappingURL=Kdf.js.map

package/dist/crypto/Kdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Kdf.js","names":[],"sources":["../../src/crypto/Kdf.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/crypto/KeyAgreement.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Key agreement: X25519, and ECDH on P-256, P-384 and P-521.
+ *
+ * The {@link KeyAgreement} service generates key pairs, derives a shared
+ * secret from a private key and a peer's public key, and computes a private
+ * key's public key. The top-level {@link privateKey}, {@link publicKey},
+ * {@link privateKeyFromCryptoKey}, {@link publicKeyFromCryptoKey}, and
+ * {@link toBytes} functions build and export keys without a service.
+ *
+ * Keys carry their algorithm in their type, so deriving a secret from keys on
+ * different curves is a type error. The shared secret is plain bytes: pass it
+ * through `Kdf` before using it as a key.
+ *
+ * Keys are opaque. They hold either bytes or a `CryptoKey`, display only their
+ * algorithm, and compare by reference. The bytes are:
+ *
+ * - X25519: the 32-byte private key and the 32-byte public key;
+ * - ECDH: PKCS#8 for private keys, and the uncompressed SEC1 point for public
+ *   keys.
+ *
+ * Only X25519 private keys and X25519 and ECDH public keys have a raw
+ * constructor. ECDH private keys come from
+ * `KeyAgreement.generateKeyPair`, `CryptoKey`s, or key formats.
+ *
+ * **Gotchas**
+ *
+ * - X25519 needs Chrome 133, Firefox 130, or Safari 17. There is no fallback
+ *   for older browsers.
+ * - X25519 private keys are generated from `SecureRandom` bytes, so a seeded
+ *   `SecureRandom` reproduces them. ECDH key generation uses WebCrypto's own
+ *   randomness and cannot be seeded.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.ts";
+import * as Effect from "../Effect.ts";
+import type { Inspectable } from "../Inspectable.ts";
+import * as Layer from "../Layer.ts";
+import * as CryptoError from "./CryptoError.ts";
+import * as SecureRandom from "./SecureRandom.ts";
+declare const PrivateKeyTypeId: "~effect/crypto/KeyAgreement/PrivateKey";
+declare const PublicKeyTypeId: "~effect/crypto/KeyAgreement/PublicKey";
+/**
+ * An elliptic curve for ECDH.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Curve = "P-256" | "P-384" | "P-521";
+/**
+ * X25519 (RFC 7748), with 32-byte shared secrets.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface X25519 {
+    readonly _tag: "X25519";
+    readonly name: "x25519";
+}
+/**
+ * ECDH on a NIST curve, with shared secrets of the curve's coordinate size.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Ecdh<C extends Curve = Curve> {
+    readonly _tag: "Ecdh";
+    readonly name: {
+        readonly "P-256": "ecdhP256";
+        readonly "P-384": "ecdhP384";
+        readonly "P-521": "ecdhP521";
+    }[C];
+    readonly namedCurve: C;
+}
+/**
+ * A key agreement algorithm, such as {@link x25519} or {@link ecdhP256}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Algorithm = X25519 | Ecdh;
+/**
+ * X25519 (RFC 7748).
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const x25519: X25519;
+/**
+ * ECDH on P-256, with 32-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const ecdhP256: Ecdh<"P-256">;
+/**
+ * ECDH on P-384, with 48-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const ecdhP384: Ecdh<"P-384">;
+/**
+ * ECDH on P-521, with 66-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const ecdhP521: Ecdh<"P-521">;
+/**
+ * An opaque key agreement private key for the algorithm `A`.
+ *
+ * **Details**
+ *
+ * The key holds either bytes or a `CryptoKey` from
+ * {@link privateKeyFromCryptoKey}. `toString`, `toJSON`, and `inspect` show
+ * only the algorithm. Keys compare by reference and do not implement `Equal`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface PrivateKey<out A extends Algorithm = Algorithm> extends Inspectable {
+    readonly [PrivateKeyTypeId]: typeof PrivateKeyTypeId;
+    readonly algorithm: A;
+}
+/**
+ * An opaque key agreement public key for the algorithm `A`.
+ *
+ * **Details**
+ *
+ * The key holds either bytes or a `CryptoKey` from
+ * {@link publicKeyFromCryptoKey}. Keys compare by reference and do not
+ * implement `Equal`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface PublicKey<out A extends Algorithm = Algorithm> extends Inspectable {
+    readonly [PublicKeyTypeId]: typeof PublicKeyTypeId;
+    readonly algorithm: A;
+}
+/**
+ * A private key and its public key.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface KeyPair<out A extends Algorithm = Algorithm> {
+    readonly privateKey: PrivateKey<A>;
+    readonly publicKey: PublicKey<A>;
+}
+/**
+ * Checks whether a value is a {@link PrivateKey}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isPrivateKey: (u: unknown) => u is PrivateKey;
+/**
+ * Checks whether a value is a {@link PublicKey}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isPublicKey: (u: unknown) => u is PublicKey;
+declare const KeyAgreement_base: Context.ServiceClass<KeyAgreement, "effect/crypto/KeyAgreement", {
+    /**
+     * Generates a key pair. X25519 private keys are 32 bytes from
+     * `SecureRandom`. ECDH keys are generated by WebCrypto and exported to
+     * PKCS#8 and an uncompressed point.
+     */
+    readonly generateKeyPair: <A extends Algorithm>(algorithm: A) => Effect.Effect<KeyPair<A>, CryptoError.CryptoError>;
+    /**
+     * Computes the secret shared by a private key and a peer's public key on
+     * the same curve. A peer key that is not on the curve, or a low-order
+     * X25519 key that gives an all-zero secret, fails with an `InvalidKey`
+     * reason.
+     */
+    readonly deriveSharedSecret: <A extends Algorithm>(privateKey: PrivateKey<A>, publicKey: PublicKey<A>) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+    /**
+     * Computes the public key of a private key. A non-extractable `CryptoKey`
+     * fails with a `NotExtractable` reason, since its public members cannot be
+     * read.
+     */
+    readonly publicKeyOf: <A extends Algorithm>(privateKey: PrivateKey<A>) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+}>;
+/**
+ * Service that generates key pairs, derives shared secrets, and computes
+ * public keys.
+ *
+ * **Example** (Agreeing on a secret with X25519)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { KeyAgreement, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const keyAgreement = yield* KeyAgreement.KeyAgreement
+ *   const alice = yield* keyAgreement.generateKeyPair(KeyAgreement.x25519)
+ *   const bob = yield* keyAgreement.generateKeyPair(KeyAgreement.x25519)
+ *   const aliceSecret = yield* keyAgreement.deriveSharedSecret(alice.privateKey, bob.publicKey)
+ *   const bobSecret = yield* keyAgreement.deriveSharedSecret(bob.privateKey, alice.publicKey)
+ *   return aliceSecret.every((byte, i) => byte === bobSecret[i])
+ * })
+ *
+ * const layer = KeyAgreement.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export declare class KeyAgreement extends KeyAgreement_base {
+}
+/**
+ * Layer that provides `KeyAgreement` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * Every algorithm runs on `crypto.subtle`. The layer imports a byte-backed
+ * key on first use and caches the `CryptoKey`. X25519 private keys come from
+ * `SecureRandom`, so a seeded `SecureRandom` reproduces them.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layerWebCrypto: Layer.Layer<KeyAgreement, never, SecureRandom.SecureRandom>;
+/**
+ * Builds an X25519 private key from its 32 bytes.
+ *
+ * **Details**
+ *
+ * The bytes are copied. Another length fails with an `InvalidKey` reason,
+ * including the 64-byte `private key‖public key` form libsodium uses: pass
+ * its first 32 bytes. ECDH private keys have no raw form, so passing them is
+ * a type error.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const privateKey: <A extends X25519>(algorithm: A, bytes: Uint8Array) => Effect.Effect<PrivateKey<A>, CryptoError.CryptoError>;
+/**
+ * Builds a public key from its raw form: 32 bytes for X25519, or an
+ * uncompressed SEC1 point for ECDH.
+ *
+ * **Details**
+ *
+ * The bytes are copied. A wrong length, or a compressed point, fails with an
+ * `InvalidKey` reason. Only uncompressed points are taken because Safari and
+ * Firefox before 146 reject compressed ones in raw import, though they accept
+ * them inside SPKI: decode a compressed point with `KeyFormat.spki`. Whether a
+ * point is on the curve is checked when the key is first used.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const publicKey: <A extends Algorithm>(algorithm: A, bytes: Uint8Array) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+/**
+ * Builds a private key from an existing `CryptoKey`, such as a
+ * non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a private key of the algorithm's WebCrypto name and
+ * curve, with the `deriveBits` usage. Otherwise the constructor fails with an
+ * `InvalidKey` reason. The key must come from the `Crypto` object of the
+ * `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const privateKeyFromCryptoKey: <A extends Algorithm>(algorithm: A, cryptoKey: CryptoKey) => Effect.Effect<PrivateKey<A>, CryptoError.CryptoError>;
+/**
+ * Builds a public key from an existing `CryptoKey`.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a public key of the algorithm's WebCrypto name and
+ * curve. Public keys need no usages. Otherwise the constructor fails with an
+ * `InvalidKey` reason. The key must come from the `Crypto` object of the
+ * `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const publicKeyFromCryptoKey: <A extends Algorithm>(algorithm: A, cryptoKey: CryptoKey) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+/**
+ * Exports a key's stored bytes.
+ *
+ * **Details**
+ *
+ * Returns a fresh `Uint8Array`: the raw key for X25519, and PKCS#8 or the
+ * uncompressed point for ECDH. A `CryptoKey`-backed key is exported on the
+ * `WebCrypto` reference, and fails with a `NotExtractable` reason when the
+ * `CryptoKey` is not extractable.
+ *
+ * @stability unstable
+ * @category converting
+ * @since 4.0.0
+ */
+export declare const toBytes: (key: PrivateKey | PublicKey) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+export {};
+//# sourceMappingURL=KeyAgreement.d.ts.map

package/dist/crypto/KeyAgreement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyAgreement.d.ts","sourceRoot":"","sources":["../../src/crypto/KeyAgreement.ts"],"names":[],"mappings":"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"}