effect 4.0.7 → 4.1.1

package/dist/crypto/Aead.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Authenticated encryption: AES-GCM, ChaCha20-Poly1305, and
+ * XChaCha20-Poly1305.
+ *
+ * The {@link Aead} service generates keys, encrypts, and decrypts. The
+ * top-level {@link key}, {@link fromCryptoKey}, and {@link toBytes} functions
+ * build and export keys without a service.
+ *
+ * Ciphertext is `ciphertext‖tag` with a 16-byte tag for every algorithm, the
+ * layout WebCrypto produces. A tampered ciphertext, tag, or additional data
+ * fails decryption with a `DecryptionFailed` reason that carries no detail.
+ *
+ * AES-GCM runs on `crypto.subtle`. ChaCha20-Poly1305 and XChaCha20-Poly1305
+ * run a pure TypeScript implementation vendored from `@noble/ciphers` 2.4.0,
+ * because WebCrypto does not provide them everywhere. Cure53 audited
+ * `@noble/ciphers` 1.0.0 in 2024.
+ *
+ * Keys are opaque. They hold either key bytes or, for AES-GCM, a `CryptoKey`,
+ * display only their algorithm, and compare by reference.
+ *
+ * **Gotchas**
+ *
+ * Never reuse a nonce with the same key. Random 12-byte nonces risk a
+ * collision after about 2^32 messages under one key: use a counter, or
+ * XChaCha20-Poly1305, whose 24-byte nonces can be random.
+ *
+ * @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";
+import * as WebCrypto from "./WebCrypto.ts";
+declare const TypeId: "~effect/crypto/Aead/Key";
+/**
+ * The synchronous code of an algorithm: the pure TypeScript code of one that
+ * WebCrypto does not provide, or a native implementation passed to
+ * {@link layerWebCryptoWith}.
+ *
+ * **Details**
+ *
+ * `encrypt` returns `ciphertext‖tag`. `decrypt` takes `ciphertext‖tag` and
+ * returns `undefined` when the tag does not match. Both receive arguments the
+ * layer has already checked.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Implementation {
+    readonly encrypt: (key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array) => Uint8Array;
+    readonly decrypt: (key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array) => Uint8Array | undefined;
+}
+/**
+ * An authenticated encryption algorithm, such as {@link aes256Gcm}.
+ *
+ * **Details**
+ *
+ * `keyLength` and `nonceLength` are in bytes. `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: "aes128Gcm" | "aes256Gcm" | "chacha20Poly1305" | "xchacha20Poly1305";
+    readonly keyLength: 16 | 32;
+    readonly nonceLength: 12 | 24;
+    readonly implementation: Implementation | undefined;
+}
+/**
+ * AES-GCM, from {@link aes128Gcm} or {@link aes256Gcm}: the algorithms that
+ * run on `crypto.subtle`, and the only ones {@link fromCryptoKey} accepts.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface AesGcm extends Algorithm {
+    readonly name: "aes128Gcm" | "aes256Gcm";
+    readonly nonceLength: 12;
+    readonly implementation: undefined;
+}
+/**
+ * AES-128-GCM, with a 16-byte key and a 12-byte nonce.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const aes128Gcm: AesGcm;
+/**
+ * AES-256-GCM, with a 32-byte key and a 12-byte nonce.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const aes256Gcm: AesGcm;
+/**
+ * ChaCha20-Poly1305 (RFC 8439), with a 32-byte key and a 12-byte nonce.
+ *
+ * **Details**
+ *
+ * Runs the pure TypeScript implementation under `layerWebCrypto`, even where
+ * `crypto.subtle` provides it, so every runtime takes one code path.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const chacha20Poly1305: Algorithm;
+/**
+ * XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha-03), with a 32-byte key and a
+ * 24-byte nonce.
+ *
+ * **When to use**
+ *
+ * Use when nonces are generated randomly, since 24-byte nonces make
+ * collisions negligible. The output is compatible with libsodium's
+ * `crypto_aead_xchacha20poly1305_ietf`.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const xchacha20Poly1305: Algorithm;
+/**
+ * An opaque authenticated encryption key for the algorithm `A`.
+ *
+ * **Details**
+ *
+ * The key holds either key bytes or a `CryptoKey` from {@link fromCryptoKey}.
+ * `toString`, `toJSON`, and `inspect` show only the algorithm. Keys compare
+ * by reference and do not implement `Equal`, because comparing key bytes is
+ * not constant time.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Key<out A extends Algorithm = Algorithm> extends Inspectable {
+    readonly [TypeId]: typeof TypeId;
+    readonly algorithm: A;
+}
+/**
+ * Checks whether a value is a {@link Key}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isKey: (u: unknown) => u is Key;
+declare const Aead_base: Context.ServiceClass<Aead, "effect/crypto/Aead", {
+    /**
+     * Generates a random key of the algorithm's length from `SecureRandom`
+     * bytes.
+     */
+    readonly generateKey: <A extends Algorithm>(algorithm: A) => Effect.Effect<Key<A>, CryptoError.CryptoError>;
+    /**
+     * Encrypts `plaintext` and appends the 16-byte tag.
+     *
+     * `nonce` must have the algorithm's nonce length. `aad` is authenticated
+     * without being encrypted and defaults to empty.
+     */
+    readonly encrypt: (key: Key, plaintext: Uint8Array, options: {
+        readonly nonce: Uint8Array;
+        readonly aad?: Uint8Array | undefined;
+    }) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+    /**
+     * Checks the tag at the end of `ciphertext` and decrypts the rest, failing
+     * with a `DecryptionFailed` reason when the tag does not match.
+     *
+     * `nonce` and `aad` must be the ones used to encrypt.
+     */
+    readonly decrypt: (key: Key, ciphertext: Uint8Array, options: {
+        readonly nonce: Uint8Array;
+        readonly aad?: Uint8Array | undefined;
+    }) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+}>;
+/**
+ * Service that generates keys, encrypts, and decrypts with authentication.
+ *
+ * **Example** (Encrypting with XChaCha20-Poly1305)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { Aead, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const aead = yield* Aead.Aead
+ *   const random = yield* SecureRandom.SecureRandom
+ *   const key = yield* aead.generateKey(Aead.xchacha20Poly1305)
+ *   const nonce = yield* random.randomBytes(24)
+ *   const sealed = yield* aead.encrypt(key, new TextEncoder().encode("secret"), { nonce })
+ *   const opened = yield* aead.decrypt(key, sealed, { nonce })
+ *   return [sealed.length, new TextDecoder().decode(opened)]
+ * })
+ *
+ * const layer = Aead.layerWebCrypto.pipe(Layer.provideMerge(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => [22, "secret"]
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export declare class Aead extends Aead_base {
+}
+/**
+ * Builds an `Aead` layer on the `WebCrypto` reference that runs the given
+ * implementations for byte-backed keys.
+ *
+ * **When to use**
+ *
+ * Use to run an algorithm on a runtime's native code, as `NodeCrypto.layerAead`
+ * does for ChaCha20-Poly1305 with `node:crypto`.
+ *
+ * **Details**
+ *
+ * `implementations` maps algorithm names to implementations that replace
+ * `crypto.subtle` or the algorithm's pure TypeScript code. They follow the
+ * {@link Implementation} contract and run only for byte-backed keys, after the
+ * layer has checked the nonce, plaintext, and ciphertext lengths, so errors are
+ * those of {@link layerWebCrypto}. `CryptoKey`-backed keys run on
+ * `crypto.subtle`, and generated keys come from `SecureRandom`. Without
+ * `implementations`, the layer is {@link layerWebCrypto}.
+ *
+ * **Gotchas**
+ *
+ * An implementation receives the key's own bytes, not a copy, so it must not
+ * modify or keep them.
+ *
+ * **Example** (Running ChaCha20-Poly1305 natively)
+ *
+ * ```ts
+ * import { Layer } from "effect"
+ * import { Aead, SecureRandom } from "effect/crypto"
+ *
+ * declare const nativeChacha: Aead.Implementation
+ *
+ * const layer = Aead.layerWebCryptoWith({
+ *   implementations: { chacha20Poly1305: nativeChacha }
+ * }).pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * ```
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layerWebCryptoWith: (options: {
+    readonly implementations?: Partial<Record<Algorithm["name"], Implementation>> | undefined;
+}) => Layer.Layer<Aead, never, SecureRandom.SecureRandom>;
+/**
+ * Layer that provides `Aead` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * AES-GCM runs on `crypto.subtle`. The layer imports a byte-backed key on
+ * first use and caches the `CryptoKey`. ChaCha20-Poly1305 and
+ * XChaCha20-Poly1305 always run the pure TypeScript implementation, with no
+ * feature detection. Generated keys come from `SecureRandom`, so a seeded
+ * `SecureRandom` gives reproducible keys.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layerWebCrypto: Layer.Layer<Aead, never, SecureRandom.SecureRandom>;
+/**
+ * Builds a key from raw key bytes.
+ *
+ * **Details**
+ *
+ * Copies the bytes, including Node.js `Buffer` inputs. A length other than
+ * the algorithm's key length fails with an `InvalidKey` reason. AES-192 is
+ * not supported.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const key: <A extends Algorithm>(algorithm: A, bytes: Uint8Array) => Effect.Effect<Key<A>, CryptoError.CryptoError>;
+/**
+ * Builds an AES-GCM key from an existing `CryptoKey`, such as a
+ * non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a secret AES-GCM key of the algorithm's length with
+ * both the `encrypt` and `decrypt` usages, since a key reaches both
+ * operations. Otherwise the constructor fails with an `InvalidKey` reason. It
+ * must come from the `Crypto` object of the `WebCrypto` reference.
+ *
+ * ChaCha20-Poly1305 and XChaCha20-Poly1305 never run on `crypto.subtle`, so
+ * passing them is a type error.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const fromCryptoKey: <A extends AesGcm>(algorithm: A, cryptoKey: WebCrypto.CryptoKey) => Effect.Effect<Key<A>, CryptoError.CryptoError>;
+/**
+ * Exports a key's bytes.
+ *
+ * **Details**
+ *
+ * Returns a fresh `Uint8Array` that shares no memory with the key. 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: Key) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+export {};
+//# sourceMappingURL=Aead.d.ts.map

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

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

package/dist/crypto/Aead.js

@@ -0,0 +1,331 @@
+/**
+ * Authenticated encryption: AES-GCM, ChaCha20-Poly1305, and
+ * XChaCha20-Poly1305.
+ *
+ * The {@link Aead} service generates keys, encrypts, and decrypts. The
+ * top-level {@link key}, {@link fromCryptoKey}, and {@link toBytes} functions
+ * build and export keys without a service.
+ *
+ * Ciphertext is `ciphertext‖tag` with a 16-byte tag for every algorithm, the
+ * layout WebCrypto produces. A tampered ciphertext, tag, or additional data
+ * fails decryption with a `DecryptionFailed` reason that carries no detail.
+ *
+ * AES-GCM runs on `crypto.subtle`. ChaCha20-Poly1305 and XChaCha20-Poly1305
+ * run a pure TypeScript implementation vendored from `@noble/ciphers` 2.4.0,
+ * because WebCrypto does not provide them everywhere. Cure53 audited
+ * `@noble/ciphers` 1.0.0 in 2024.
+ *
+ * Keys are opaque. They hold either key bytes or, for AES-GCM, a `CryptoKey`,
+ * display only their algorithm, and compare by reference.
+ *
+ * **Gotchas**
+ *
+ * Never reuse a nonce with the same key. Random 12-byte nonces risk a
+ * collision after about 2^32 messages under one key: use a counter, or
+ * XChaCha20-Poly1305, whose 24-byte nonces can be random.
+ *
+ * @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 Predicate from "../Predicate.js";
+import * as CryptoError from "./CryptoError.js";
+import * as Chacha from "./internal/chacha.js";
+import * as KeyModel from "./internal/key.js";
+import * as internal from "./internal/webCrypto.js";
+import * as SecureRandom from "./SecureRandom.js";
+import * as WebCrypto from "./WebCrypto.js";
+const TypeId = "~effect/crypto/Aead/Key";
+/**
+ * AES-128-GCM, with a 16-byte key and a 12-byte nonce.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const aes128Gcm = {
+  name: "aes128Gcm",
+  keyLength: 16,
+  nonceLength: 12,
+  implementation: undefined
+};
+/**
+ * AES-256-GCM, with a 32-byte key and a 12-byte nonce.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const aes256Gcm = {
+  name: "aes256Gcm",
+  keyLength: 32,
+  nonceLength: 12,
+  implementation: undefined
+};
+const chachaImplementation = aead => ({
+  encrypt: (key, nonce, plaintext, aad) => aead(key, nonce, aad).encrypt(plaintext),
+  decrypt: (key, nonce, ciphertext, aad) => aead(key, nonce, aad).decrypt(ciphertext)
+});
+/**
+ * ChaCha20-Poly1305 (RFC 8439), with a 32-byte key and a 12-byte nonce.
+ *
+ * **Details**
+ *
+ * Runs the pure TypeScript implementation under `layerWebCrypto`, even where
+ * `crypto.subtle` provides it, so every runtime takes one code path.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const chacha20Poly1305 = {
+  name: "chacha20Poly1305",
+  keyLength: 32,
+  nonceLength: 12,
+  implementation: /* @__PURE__ */chachaImplementation(Chacha.chacha20Poly1305)
+};
+/**
+ * XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha-03), with a 32-byte key and a
+ * 24-byte nonce.
+ *
+ * **When to use**
+ *
+ * Use when nonces are generated randomly, since 24-byte nonces make
+ * collisions negligible. The output is compatible with libsodium's
+ * `crypto_aead_xchacha20poly1305_ietf`.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const xchacha20Poly1305 = {
+  name: "xchacha20Poly1305",
+  keyLength: 32,
+  nonceLength: 24,
+  implementation: /* @__PURE__ */chachaImplementation(Chacha.xchacha20Poly1305)
+};
+const KeyProto = /*#__PURE__*/KeyModel.redactedProto(TypeId, "Aead.Key");
+/**
+ * Checks whether a value is a {@link Key}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export const isKey = u => Predicate.hasProperty(u, TypeId);
+/**
+ * Service that generates keys, encrypts, and decrypts with authentication.
+ *
+ * **Example** (Encrypting with XChaCha20-Poly1305)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { Aead, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const aead = yield* Aead.Aead
+ *   const random = yield* SecureRandom.SecureRandom
+ *   const key = yield* aead.generateKey(Aead.xchacha20Poly1305)
+ *   const nonce = yield* random.randomBytes(24)
+ *   const sealed = yield* aead.encrypt(key, new TextEncoder().encode("secret"), { nonce })
+ *   const opened = yield* aead.decrypt(key, sealed, { nonce })
+ *   return [sealed.length, new TextDecoder().decode(opened)]
+ * })
+ *
+ * const layer = Aead.layerWebCrypto.pipe(Layer.provideMerge(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => [22, "secret"]
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class Aead extends /*#__PURE__*/Context.Service()("effect/crypto/Aead") {}
+const fail = (method, reason) => internal.fail("Aead", method, reason);
+const decryptionFailed = () => fail("decrypt", new CryptoError.DecryptionFailed());
+// GCM limits the plaintext to 2^39 - 256 bits.
+const maxGcmPlaintext = 2 ** 36 - 32;
+const tagLength = 16;
+// Every check runs before any work, so the pure TypeScript code only throws on
+// a bug, and WebCrypto's `OperationError` only means a failed tag check.
+const checkArguments = (method, key, data, options) => {
+  const algorithm = key.algorithm;
+  if (options.nonce.length !== algorithm.nonceLength) {
+    return fail(method, new CryptoError.InvalidArgument({
+      description: `${algorithm.name} nonces must contain exactly ${algorithm.nonceLength} bytes`
+    }));
+  }
+  if (method === "encrypt") {
+    if (algorithm.implementation === undefined && data.length > maxGcmPlaintext) {
+      return fail(method, new CryptoError.InvalidArgument({
+        description: "AES-GCM plaintext cannot exceed 2^36 - 32 bytes"
+      }));
+    }
+  } else if (data.length < tagLength) {
+    return decryptionFailed();
+  }
+  return undefined;
+};
+const runImplementation = (method, implementation, key, data, options) => {
+  const stored = KeyModel.material(key);
+  if (stored._tag !== "Bytes") {
+    return fail(method, new CryptoError.InvalidKey({
+      description: `${key.algorithm.name} keys must hold bytes`
+    }));
+  }
+  const aad = options.aad ?? new Uint8Array(0);
+  if (method === "encrypt") {
+    return Effect.sync(() => implementation.encrypt(stored.bytes, options.nonce, data, aad));
+  }
+  return Effect.suspend(() => {
+    const plaintext = implementation.decrypt(stored.bytes, options.nonce, data, aad);
+    return plaintext === undefined ? decryptionFailed() : Effect.succeed(plaintext);
+  });
+};
+/**
+ * Builds an `Aead` layer on the `WebCrypto` reference that runs the given
+ * implementations for byte-backed keys.
+ *
+ * **When to use**
+ *
+ * Use to run an algorithm on a runtime's native code, as `NodeCrypto.layerAead`
+ * does for ChaCha20-Poly1305 with `node:crypto`.
+ *
+ * **Details**
+ *
+ * `implementations` maps algorithm names to implementations that replace
+ * `crypto.subtle` or the algorithm's pure TypeScript code. They follow the
+ * {@link Implementation} contract and run only for byte-backed keys, after the
+ * layer has checked the nonce, plaintext, and ciphertext lengths, so errors are
+ * those of {@link layerWebCrypto}. `CryptoKey`-backed keys run on
+ * `crypto.subtle`, and generated keys come from `SecureRandom`. Without
+ * `implementations`, the layer is {@link layerWebCrypto}.
+ *
+ * **Gotchas**
+ *
+ * An implementation receives the key's own bytes, not a copy, so it must not
+ * modify or keep them.
+ *
+ * **Example** (Running ChaCha20-Poly1305 natively)
+ *
+ * ```ts
+ * import { Layer } from "effect"
+ * import { Aead, SecureRandom } from "effect/crypto"
+ *
+ * declare const nativeChacha: Aead.Implementation
+ *
+ * const layer = Aead.layerWebCryptoWith({
+ *   implementations: { chacha20Poly1305: nativeChacha }
+ * }).pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * ```
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCryptoWith = options => Layer.effect(Aead, Effect.gen(function* () {
+  const random = yield* SecureRandom.SecureRandom;
+  const crypto = yield* WebCrypto.WebCrypto;
+  const cryptoKeyFor = KeyModel.makeCache((subtle, bytes) => subtle.importKey("raw", bytes, "AES-GCM", false, ["encrypt", "decrypt"]));
+  const implementations = options.implementations;
+  // A supplied implementation runs only for byte-backed keys, so CryptoKeys
+  // stay on `crypto.subtle`.
+  const implementationFor = key => {
+    const supplied = implementations?.[key.algorithm.name];
+    return supplied !== undefined && KeyModel.material(key)._tag === "Bytes" ? supplied : key.algorithm.implementation;
+  };
+  const gcm = (method, key, data, options) => {
+    const params = {
+      name: "AES-GCM",
+      iv: options.nonce,
+      tagLength: 128,
+      ...(options.aad === undefined ? {} : {
+        additionalData: options.aad
+      })
+    };
+    return internal.run("Aead", method, key.algorithm.name, crypto, async subtle => new Uint8Array(await subtle[method](params, await cryptoKeyFor(subtle, key), data)), cause => internal.webCryptoError("Aead", method, key.algorithm.name, cause, method === "decrypt" ? () => new CryptoError.DecryptionFailed() : undefined));
+  };
+  const run = method => (key, data, options) => Effect.suspend(() => {
+    const failure = checkArguments(method, key, data, options);
+    if (failure !== undefined) return failure;
+    const implementation = implementationFor(key);
+    return implementation === undefined ? gcm(method, key, data, options) : runImplementation(method, implementation, key, data, options);
+  });
+  return Aead.of({
+    generateKey: algorithm => Effect.map(random.randomBytes(algorithm.keyLength), bytes => KeyModel.makeBytes(KeyProto, algorithm, bytes)),
+    encrypt: run("encrypt"),
+    decrypt: run("decrypt")
+  });
+}));
+/**
+ * Layer that provides `Aead` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * AES-GCM runs on `crypto.subtle`. The layer imports a byte-backed key on
+ * first use and caches the `CryptoKey`. ChaCha20-Poly1305 and
+ * XChaCha20-Poly1305 always run the pure TypeScript implementation, with no
+ * feature detection. Generated keys come from `SecureRandom`, so a seeded
+ * `SecureRandom` gives reproducible keys.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCrypto = /*#__PURE__*/layerWebCryptoWith({});
+/**
+ * Builds a key from raw key bytes.
+ *
+ * **Details**
+ *
+ * Copies the bytes, including Node.js `Buffer` inputs. A length other than
+ * the algorithm's key length fails with an `InvalidKey` reason. AES-192 is
+ * not supported.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const key = (algorithm, bytes) => KeyModel.fromBytes("Aead", "key", KeyProto, algorithm, bytes, KeyModel.checkKeyLength(algorithm));
+/**
+ * Builds an AES-GCM key from an existing `CryptoKey`, such as a
+ * non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a secret AES-GCM key of the algorithm's length with
+ * both the `encrypt` and `decrypt` usages, since a key reaches both
+ * operations. Otherwise the constructor fails with an `InvalidKey` reason. It
+ * must come from the `Crypto` object of the `WebCrypto` reference.
+ *
+ * ChaCha20-Poly1305 and XChaCha20-Poly1305 never run on `crypto.subtle`, so
+ * passing them is a type error.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromCryptoKey = (algorithm, cryptoKey) => algorithm.implementation !== undefined ? internal.invalidKey("Aead", "fromCryptoKey", `${algorithm.name} keys cannot be CryptoKeys`) : KeyModel.fromCryptoKey("Aead", "fromCryptoKey", KeyProto, algorithm, cryptoKey, {
+  type: "secret",
+  name: "AES-GCM",
+  usages: ["encrypt", "decrypt"],
+  usagePolicy: "all",
+  check: KeyModel.checkAesLength("AES-GCM", algorithm.keyLength)
+});
+/**
+ * Exports a key's bytes.
+ *
+ * **Details**
+ *
+ * Returns a fresh `Uint8Array` that shares no memory with the key. 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 const toBytes = key => KeyModel.toBytes("Aead", key, KeyModel.exportRaw);
+//# sourceMappingURL=Aead.js.map

package/dist/crypto/Aead.js.map

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