effect 4.0.6 → 4.1.0

package/dist/crypto/Cipher.js

@@ -0,0 +1,233 @@
+/**
+ * Unauthenticated encryption with no integrity: compose with `Mac`.
+ *
+ * AES-CTR and AES-CBC with PKCS#7 padding, for protocols that pair them with a
+ * MAC, such as SSH, SRTP, JWE, CMS, and Matrix. Anyone can change the
+ * ciphertext without being detected, so authenticate it with `Mac`
+ * (encrypt-then-MAC), or use `Aead` instead.
+ *
+ * The {@link Cipher} service generates keys, encrypts, and decrypts. The
+ * top-level {@link key}, {@link fromCryptoKey}, and {@link toBytes} functions
+ * build and export keys without a service. Both modes run on `crypto.subtle`.
+ *
+ * Keys are opaque. They hold either key bytes or a `CryptoKey`, display only
+ * their algorithm, and compare by reference.
+ *
+ * **Gotchas**
+ *
+ * - Never reuse an IV with the same key. For AES-CTR a repeated counter block
+ *   reveals the XOR of two plaintexts. For AES-CBC the IV must also be
+ *   unpredictable.
+ * - AES-CTR decryption never fails, whatever the ciphertext. AES-CBC
+ *   decryption fails with one `DecryptionFailed` reason for both bad padding
+ *   and a bad length, so callers cannot tell them apart. Verify a MAC before
+ *   decrypting, or the error itself becomes a padding oracle.
+ *
+ * @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 KeyModel from "./internal/key.js";
+import * as internal from "./internal/webCrypto.js";
+import * as SecureRandom from "./SecureRandom.js";
+import { WebCrypto } from "./WebCrypto.js";
+const TypeId = "~effect/crypto/Cipher/Key";
+/**
+ * AES-128-CTR, with a 16-byte key.
+ *
+ * **Details**
+ *
+ * The 16-byte `iv` is the initial counter block, and the whole 128-bit block
+ * is the counter, as in OpenSSL, Node.js, Go's `cipher.NewCTR`, and noble.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const aes128Ctr = {
+  name: "aes128Ctr",
+  mode: "AES-CTR",
+  keyLength: 16
+};
+/**
+ * AES-256-CTR, with a 32-byte key.
+ *
+ * **Details**
+ *
+ * The 16-byte `iv` is the initial counter block, and the whole 128-bit block
+ * is the counter, as in OpenSSL, Node.js, Go's `cipher.NewCTR`, and noble.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const aes256Ctr = {
+  name: "aes256Ctr",
+  mode: "AES-CTR",
+  keyLength: 32
+};
+/**
+ * AES-128-CBC with PKCS#7 padding, with a 16-byte key.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const aes128Cbc = {
+  name: "aes128Cbc",
+  mode: "AES-CBC",
+  keyLength: 16
+};
+/**
+ * AES-256-CBC with PKCS#7 padding, with a 32-byte key.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const aes256Cbc = {
+  name: "aes256Cbc",
+  mode: "AES-CBC",
+  keyLength: 32
+};
+const KeyProto = /*#__PURE__*/KeyModel.redactedProto(TypeId, "Cipher.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 without
+ * authentication.
+ *
+ * **Example** (Encrypting with AES-CBC)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { Cipher, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const cipher = yield* Cipher.Cipher
+ *   const random = yield* SecureRandom.SecureRandom
+ *   const key = yield* cipher.generateKey(Cipher.aes256Cbc)
+ *   const iv = yield* random.randomBytes(16)
+ *   const ciphertext = yield* cipher.encrypt(key, new TextEncoder().encode("secret"), { iv })
+ *   const plaintext = yield* cipher.decrypt(key, ciphertext, { iv })
+ *   return [ciphertext.length, new TextDecoder().decode(plaintext)]
+ * })
+ *
+ * const layer = Cipher.layerWebCrypto.pipe(Layer.provideMerge(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => [16, "secret"]
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class Cipher extends /*#__PURE__*/Context.Service()("effect/crypto/Cipher") {}
+const fail = (method, reason) => internal.fail("Cipher", method, reason);
+const blockLength = 16;
+const params = (algorithm, iv) => algorithm.mode === "AES-CTR" ? {
+  name: "AES-CTR",
+  counter: iv,
+  length: 128
+} : {
+  name: "AES-CBC",
+  iv: iv
+};
+/**
+ * Layer that provides `Cipher` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * Encryption and decryption run on `crypto.subtle`. The layer imports a
+ * byte-backed key on first use and caches the `CryptoKey`. AES-CTR uses the
+ * whole 128-bit block as the counter (`length: 128`), which every runtime
+ * supports. Generated keys come from `SecureRandom`, so a seeded
+ * `SecureRandom` gives reproducible keys.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCrypto = /*#__PURE__*/Layer.effect(Cipher, /*#__PURE__*/Effect.gen(function* () {
+  const random = yield* SecureRandom.SecureRandom;
+  const crypto = yield* WebCrypto;
+  const cryptoKeyFor = KeyModel.makeCache((subtle, bytes, algorithm) => subtle.importKey("raw", bytes, algorithm.mode, false, ["encrypt", "decrypt"]));
+  const run = method => (key, data, options) => Effect.suspend(() => {
+    if (options.iv.length !== blockLength) {
+      return fail(method, new CryptoError.InvalidArgument({
+        description: "IVs must contain exactly 16 bytes"
+      }));
+    }
+    // Checked here so a bad length is not reported differently from bad padding.
+    const cbc = key.algorithm.mode === "AES-CBC";
+    if (method === "decrypt" && cbc && (data.length === 0 || data.length % blockLength !== 0)) {
+      return fail(method, new CryptoError.DecryptionFailed());
+    }
+    return internal.run("Cipher", method, key.algorithm.name, crypto, async subtle => new Uint8Array(await subtle[method](params(key.algorithm, options.iv), await cryptoKeyFor(subtle, key), data)), cause => internal.webCryptoError("Cipher", method, key.algorithm.name, cause, method === "decrypt" && cbc ? () => new CryptoError.DecryptionFailed() : undefined));
+  });
+  return Cipher.of({
+    generateKey: algorithm => Effect.map(random.randomBytes(algorithm.keyLength), bytes => KeyModel.makeBytes(KeyProto, algorithm, bytes)),
+    encrypt: run("encrypt"),
+    decrypt: run("decrypt")
+  });
+}));
+/**
+ * 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("Cipher", "key", KeyProto, algorithm, bytes, KeyModel.checkKeyLength(algorithm));
+/**
+ * Builds a key from an existing `CryptoKey`, such as a non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a secret key for the algorithm's mode (`AES-CTR` or
+ * `AES-CBC`) and 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.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromCryptoKey = (algorithm, cryptoKey) => KeyModel.fromCryptoKey("Cipher", "fromCryptoKey", KeyProto, algorithm, cryptoKey, {
+  type: "secret",
+  name: algorithm.mode,
+  usages: ["encrypt", "decrypt"],
+  usagePolicy: "all",
+  check: KeyModel.checkAesLength(algorithm.mode, 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("Cipher", key, KeyModel.exportRaw);
+//# sourceMappingURL=Cipher.js.map

package/dist/crypto/Cipher.js.map

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

package/dist/crypto/CryptoError.d.ts

@@ -0,0 +1,212 @@
+declare const TypeId: "~effect/crypto/CryptoError";
+declare const ReasonTypeId: "~effect/crypto/CryptoError/Reason";
+declare const InvalidArgument_base: new <A extends Record<string, any> = {}>(args: import("../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../Cause.ts").YieldableError & {
+    readonly _tag: "InvalidArgument";
+} & Readonly<A>;
+/**
+ * Reason for an argument that the operation rejects before using the key or
+ * data, such as a wrong nonce length, an out-of-range iteration count, or
+ * `info` passed to a key derivation other than HKDF.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class InvalidArgument extends InvalidArgument_base<{
+    readonly description: string;
+    readonly cause?: unknown;
+}> {
+    /**
+     * Marks this value as a `CryptoError` reason for runtime guards.
+     *
+     * @since 4.0.0
+     */
+    readonly [ReasonTypeId]: "~effect/crypto/CryptoError/Reason";
+    get message(): string;
+}
+declare const InvalidKey_base: new <A extends Record<string, any> = {}>(args: import("../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../Cause.ts").YieldableError & {
+    readonly _tag: "InvalidKey";
+} & Readonly<A>;
+/**
+ * Reason for key material that is rejected, such as a wrong raw key length,
+ * malformed DER, PEM, or JWK data, a `CryptoKey` that does not match the typed
+ * key, or a peer public key that produces an all-zero shared secret.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class InvalidKey extends InvalidKey_base<{
+    readonly description: string;
+    readonly cause?: unknown;
+}> {
+    /**
+     * Marks this value as a `CryptoError` reason for runtime guards.
+     *
+     * @since 4.0.0
+     */
+    readonly [ReasonTypeId]: "~effect/crypto/CryptoError/Reason";
+    get message(): string;
+}
+declare const DecryptionFailed_base: new <A extends Record<string, any> = {}>(args: import("../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../Cause.ts").YieldableError & {
+    readonly _tag: "DecryptionFailed";
+} & Readonly<A>;
+/**
+ * Reason for a decryption or unwrap that failed its integrity check, or a CBC
+ * ciphertext with bad padding or length.
+ *
+ * **Details**
+ *
+ * The reason is identical for every cause and carries no `cause` or runtime
+ * message, so callers cannot tell a tampered tag from bad padding. Keeping
+ * either would create a padding oracle.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class DecryptionFailed extends DecryptionFailed_base<{}> {
+    /**
+     * Marks this value as a `CryptoError` reason for runtime guards.
+     *
+     * @since 4.0.0
+     */
+    readonly [ReasonTypeId]: "~effect/crypto/CryptoError/Reason";
+    get message(): string;
+}
+declare const Unsupported_base: new <A extends Record<string, any> = {}>(args: import("../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../Cause.ts").YieldableError & {
+    readonly _tag: "Unsupported";
+} & Readonly<A>;
+/**
+ * Reason for an algorithm or key that a layer does not provide, such as
+ * Argon2id under `Kdf.layerWebCrypto`, or a `CryptoKey`-backed key passed to a
+ * layer that cannot use it.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class Unsupported extends Unsupported_base<{
+    readonly description: string;
+    readonly cause?: unknown;
+}> {
+    /**
+     * Marks this value as a `CryptoError` reason for runtime guards.
+     *
+     * @since 4.0.0
+     */
+    readonly [ReasonTypeId]: "~effect/crypto/CryptoError/Reason";
+    get message(): string;
+}
+declare const NotExtractable_base: new <A extends Record<string, any> = {}>(args: import("../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../Cause.ts").YieldableError & {
+    readonly _tag: "NotExtractable";
+} & Readonly<A>;
+/**
+ * Reason for exporting or wrapping a `CryptoKey` that was created as
+ * non-extractable.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class NotExtractable extends NotExtractable_base<{
+    readonly description: string;
+    readonly cause?: unknown;
+}> {
+    /**
+     * Marks this value as a `CryptoError` reason for runtime guards.
+     *
+     * @since 4.0.0
+     */
+    readonly [ReasonTypeId]: "~effect/crypto/CryptoError/Reason";
+    get message(): string;
+}
+/**
+ * Union of the reasons carried by `CryptoError`.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export type CryptoErrorReason = InvalidArgument | InvalidKey | DecryptionFailed | Unsupported | NotExtractable;
+declare const CryptoError_base: new <A extends Record<string, any> = {}>(args: import("../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../Cause.ts").YieldableError & {
+    readonly _tag: "CryptoError";
+} & Readonly<A>;
+/**
+ * Error returned by the `effect/crypto` modules.
+ *
+ * **When to use**
+ *
+ * Use to handle failures from any `effect/crypto` operation, matching on
+ * `reason` to separate caller mistakes from failed decryption.
+ *
+ * **Details**
+ *
+ * `module` and `method` name the operation, such as `"Aead"` and `"decrypt"`.
+ * The message reads `"Aead.decrypt: <reason message>"`. The error's `cause`
+ * is the reason's `cause`, when it has one.
+ *
+ * **Example** (Recovering from failed decryption)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { CryptoError } from "effect/crypto"
+ *
+ * const decrypt = Effect.fail(
+ *   new CryptoError.CryptoError({
+ *     module: "Aead",
+ *     method: "decrypt",
+ *     reason: new CryptoError.DecryptionFailed()
+ *   })
+ * )
+ *
+ * const program = decrypt.pipe(
+ *   Effect.catchReason("CryptoError", "DecryptionFailed", () => Effect.succeed("rejected"))
+ * )
+ *
+ * await Effect.runPromise(program) // => "rejected"
+ * ```
+ *
+ * @see {@link isCryptoError} for narrowing unknown values
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class CryptoError extends CryptoError_base<{
+    readonly module: string;
+    readonly method: string;
+    readonly reason: CryptoErrorReason;
+}> {
+    /**
+     * Marks this value as a `CryptoError` for runtime guards.
+     *
+     * @since 4.0.0
+     */
+    readonly [TypeId]: "~effect/crypto/CryptoError";
+    /**
+     * The reason's cause, when it has one.
+     *
+     * @since 4.0.0
+     */
+    readonly cause: unknown;
+    get message(): string;
+}
+/**
+ * Checks whether a value is a `CryptoError`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isCryptoError: (u: unknown) => u is CryptoError;
+/**
+ * Checks whether a value is one of the reasons carried by `CryptoError`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isCryptoErrorReason: (u: unknown) => u is CryptoErrorReason;
+export {};
+//# sourceMappingURL=CryptoError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CryptoError.d.ts","sourceRoot":"","sources":["../../src/crypto/CryptoError.ts"],"names":[],"mappings":"AAsBA,QAAA,MAAM,MAAM,EAAG,4BAAqC,CAAA;AACpD,QAAA,MAAM,YAAY,EAAG,mCAA4C,CAAA;;;;AAEjE;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,qBAAoC;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,sCAAe;IAEtC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,sCAAe;IAEtC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAiB,SAAQ,sBAAqC,EAAE,CAAC;IAC5E;;;;OAIG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,sCAAe;IAEtC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,iBAAgC;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,sCAAe;IAEtC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,oBAAmC;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,sCAAe;IAEtC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,UAAU,GAAG,gBAAgB,GAAG,WAAW,GAAG,cAAc,CAAA;;;;AAE9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,WAAY,SAAQ,iBAAgC;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CACnC,CAAC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,+BAAS;IAE1B;;;;OAIG;IACH,SAAkB,KAAK,EAAE,OAAO,CAAyD;IAEzF,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,MAAO,OAAO,KAAG,CAAC,IAAI,WAA+C,CAAA;AAE/F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,MAAO,OAAO,KAAG,CAAC,IAAI,iBAA2D,CAAA"}

package/dist/crypto/CryptoError.js

@@ -0,0 +1,202 @@
+/**
+ * The `CryptoError` returned by the `effect/crypto` modules, and the reasons it
+ * carries.
+ *
+ * Every failure is one `CryptoError` whose `module` and `method` name the
+ * operation, such as `"Aead"` and `"decrypt"`, and whose `reason` says what
+ * went wrong: `InvalidArgument`, `InvalidKey`, `DecryptionFailed`,
+ * `Unsupported`, or `NotExtractable`.
+ *
+ * **Gotchas**
+ *
+ * The error is not serializable, so it cannot be a typed failure in an Rpc or
+ * HttpApi schema. Map it before it reaches a client, for example
+ * `DecryptionFailed` to a 401. Sending crypto failure detail to clients is how
+ * oracles leak.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Data from "../Data.js";
+import * as Predicate from "../Predicate.js";
+const TypeId = "~effect/crypto/CryptoError";
+const ReasonTypeId = "~effect/crypto/CryptoError/Reason";
+/**
+ * Reason for an argument that the operation rejects before using the key or
+ * data, such as a wrong nonce length, an out-of-range iteration count, or
+ * `info` passed to a key derivation other than HKDF.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class InvalidArgument extends /*#__PURE__*/Data.TaggedError("InvalidArgument") {
+  /**
+   * Marks this value as a `CryptoError` reason for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  [ReasonTypeId] = ReasonTypeId;
+  get message() {
+    return this.description;
+  }
+}
+/**
+ * Reason for key material that is rejected, such as a wrong raw key length,
+ * malformed DER, PEM, or JWK data, a `CryptoKey` that does not match the typed
+ * key, or a peer public key that produces an all-zero shared secret.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class InvalidKey extends /*#__PURE__*/Data.TaggedError("InvalidKey") {
+  /**
+   * Marks this value as a `CryptoError` reason for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  [ReasonTypeId] = ReasonTypeId;
+  get message() {
+    return this.description;
+  }
+}
+/**
+ * Reason for a decryption or unwrap that failed its integrity check, or a CBC
+ * ciphertext with bad padding or length.
+ *
+ * **Details**
+ *
+ * The reason is identical for every cause and carries no `cause` or runtime
+ * message, so callers cannot tell a tampered tag from bad padding. Keeping
+ * either would create a padding oracle.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class DecryptionFailed extends /*#__PURE__*/Data.TaggedError("DecryptionFailed") {
+  /**
+   * Marks this value as a `CryptoError` reason for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  [ReasonTypeId] = ReasonTypeId;
+  get message() {
+    return "Could not decrypt the data";
+  }
+}
+/**
+ * Reason for an algorithm or key that a layer does not provide, such as
+ * Argon2id under `Kdf.layerWebCrypto`, or a `CryptoKey`-backed key passed to a
+ * layer that cannot use it.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class Unsupported extends /*#__PURE__*/Data.TaggedError("Unsupported") {
+  /**
+   * Marks this value as a `CryptoError` reason for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  [ReasonTypeId] = ReasonTypeId;
+  get message() {
+    return this.description;
+  }
+}
+/**
+ * Reason for exporting or wrapping a `CryptoKey` that was created as
+ * non-extractable.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class NotExtractable extends /*#__PURE__*/Data.TaggedError("NotExtractable") {
+  /**
+   * Marks this value as a `CryptoError` reason for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  [ReasonTypeId] = ReasonTypeId;
+  get message() {
+    return this.description;
+  }
+}
+/**
+ * Error returned by the `effect/crypto` modules.
+ *
+ * **When to use**
+ *
+ * Use to handle failures from any `effect/crypto` operation, matching on
+ * `reason` to separate caller mistakes from failed decryption.
+ *
+ * **Details**
+ *
+ * `module` and `method` name the operation, such as `"Aead"` and `"decrypt"`.
+ * The message reads `"Aead.decrypt: <reason message>"`. The error's `cause`
+ * is the reason's `cause`, when it has one.
+ *
+ * **Example** (Recovering from failed decryption)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { CryptoError } from "effect/crypto"
+ *
+ * const decrypt = Effect.fail(
+ *   new CryptoError.CryptoError({
+ *     module: "Aead",
+ *     method: "decrypt",
+ *     reason: new CryptoError.DecryptionFailed()
+ *   })
+ * )
+ *
+ * const program = decrypt.pipe(
+ *   Effect.catchReason("CryptoError", "DecryptionFailed", () => Effect.succeed("rejected"))
+ * )
+ *
+ * await Effect.runPromise(program) // => "rejected"
+ * ```
+ *
+ * @see {@link isCryptoError} for narrowing unknown values
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class CryptoError extends /*#__PURE__*/Data.TaggedError("CryptoError") {
+  /**
+   * Marks this value as a `CryptoError` for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  [TypeId] = TypeId;
+  /**
+   * The reason's cause, when it has one.
+   *
+   * @since 4.0.0
+   */
+  cause = "cause" in this.reason ? this.reason.cause : undefined;
+  get message() {
+    return `${this.module}.${this.method}: ${this.reason.message}`;
+  }
+}
+/**
+ * Checks whether a value is a `CryptoError`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export const isCryptoError = u => Predicate.hasProperty(u, TypeId);
+/**
+ * Checks whether a value is one of the reasons carried by `CryptoError`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export const isCryptoErrorReason = u => Predicate.hasProperty(u, ReasonTypeId);
+//# sourceMappingURL=CryptoError.js.map

package/dist/crypto/CryptoError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CryptoError.js","names":[],"sources":["../../src/crypto/CryptoError.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAK,IAAI,MAAM,YAAY;AAClC,OAAO,KAAK,SAAS,MAAM,iBAAiB;AAE5C,MAAM,MAAM,GAAG,4BAAqC;AACpD,MAAM,YAAY,GAAG,mCAA4C;AAEjE;;;;;;;;;AASA,OAAM,MAAO,eAAgB,sBAAQ,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAGrE;EACA;;;;;EAKS,CAAC,YAAY,IAAI,YAAY;EAEtC,IAAa,OAAO;IAClB,OAAO,IAAI,CAAC,WAAW;EACzB;;AAGF;;;;;;;;;AASA,OAAM,MAAO,UAAW,sBAAQ,IAAI,CAAC,WAAW,CAAC,YAAY,CAG3D;EACA;;;;;EAKS,CAAC,YAAY,IAAI,YAAY;EAEtC,IAAa,OAAO;IAClB,OAAO,IAAI,CAAC,WAAW;EACzB;;AAGF;;;;;;;;;;;;;;AAcA,OAAM,MAAO,gBAAiB,sBAAQ,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAAK;EAC5E;;;;;EAKS,CAAC,YAAY,IAAI,YAAY;EAEtC,IAAa,OAAO;IAClB,OAAO,4BAA4B;EACrC;;AAGF;;;;;;;;;AASA,OAAM,MAAO,WAAY,sBAAQ,IAAI,CAAC,WAAW,CAAC,aAAa,CAG7D;EACA;;;;;EAKS,CAAC,YAAY,IAAI,YAAY;EAEtC,IAAa,OAAO;IAClB,OAAO,IAAI,CAAC,WAAW;EACzB;;AAGF;;;;;;;;AAQA,OAAM,MAAO,cAAe,sBAAQ,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAGnE;EACA;;;;;EAKS,CAAC,YAAY,IAAI,YAAY;EAEtC,IAAa,OAAO;IAClB,OAAO,IAAI,CAAC,WAAW;EACzB;;AAYF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,OAAM,MAAO,WAAY,sBAAQ,IAAI,CAAC,WAAW,CAAC,aAAa,CAI7D;EACA;;;;;EAKS,CAAC,MAAM,IAAI,MAAM;EAE1B;;;;;EAKkB,KAAK,GAAY,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS;EAEzF,IAAa,OAAO;IAClB,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;EAChE;;AAGF;;;;;;;AAOA,OAAO,MAAM,aAAa,GAAI,CAAU,IAAuB,SAAS,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC;AAE/F;;;;;;;AAOA,OAAO,MAAM,mBAAmB,GAAI,CAAU,IAA6B,SAAS,CAAC,WAAW,CAAC,CAAC,EAAE,YAAY,CAAC","ignoreList":[]}