1import type * as kms from "@distilled.cloud/aws/kms";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { AliasName } from "./Alias.ts";
5import type { Key } from "./Key.ts";
6
7export interface DecryptRequest extends Omit<kms.DecryptRequest, "KeyId"> {}
8
9/**
10 * Runtime binding for `kms:Decrypt`.
11 *
12 * Bind this operation to a KMS {@link Key} (or the `alias/...` name of a
13 * pre-existing key) inside a function runtime to get a callable that
14 * automatically injects the `KeyId`. Passing the key explicitly (rather than
15 * relying on the metadata KMS embeds in symmetric ciphertext) pins decryption
16 * to the intended key, per AWS best practice.
17 *
18 * The decrypted `Plaintext` in the response is wrapped in `Redacted` so it
19 * never leaks into logs — unwrap with `Redacted.value(...)` at the point of
20 * use.
21 *
22 * ### Decrypting Data
23 * **Example:** Decrypt a Ciphertext
24 * ```typescript
25 * import * as Redacted from "effect/Redacted";
26 *
27 * const decrypt = yield* AWS.KMS.Decrypt(key);
28 *
29 * const response = yield* decrypt({ CiphertextBlob: ciphertext });
30 * const plaintext = Redacted.isRedacted(response.Plaintext)
31 * ? Redacted.value(response.Plaintext)
32 * : response.Plaintext; // Uint8Array
33 * ```
34 *
35 * **Example:** Decrypt with an Encryption Context
36 * ```typescript
37 * // Must match the context used at encryption time exactly, otherwise the
38 * // call fails with a typed InvalidCiphertextException.
39 * const response = yield* decrypt({
40 * CiphertextBlob: ciphertext,
41 * EncryptionContext: { tenant: "acme" },
42 * });
43 * ```
44 *
45 * ### Pre-Existing Keys
46 * **Example:** Bind by Alias Name
47 * ```typescript
48 * const decrypt = yield* AWS.KMS.Decrypt("alias/app-key");
49 * ```
50 *
51 * ### Wiring
52 * **Example:** Provide the Implementation on a Lambda Function
53 * ```typescript
54 * // Provide the DecryptHttp layer on the Function's init Effect,
55 * // merged with the other KMS layers the function binds.
56 * export default CryptoFunction.make(
57 * { main: import.meta.url, functionUrl: true },
58 * Effect.gen(function* () {
59 * const key = yield* AWS.KMS.Key("AppKey");
60 * const encrypt = yield* AWS.KMS.Encrypt(key);
61 * const decrypt = yield* AWS.KMS.Decrypt(key);
62 * // ... use encrypt/decrypt in the fetch handler
63 * return { fetch: handler };
64 * }).pipe(
65 * Effect.provide(Layer.mergeAll(AWS.KMS.EncryptHttp, AWS.KMS.DecryptHttp)),
66 * ),
67 * );
68 * ```
69 *
70 * @binding
71 */
72export interface Decrypt extends Binding.Service<
73 Decrypt,
74 "AWS.KMS.Decrypt",
75 (
76 key: Key | AliasName,
77 ) => Effect.Effect<
78 (
79 request: DecryptRequest,
80 ) => Effect.Effect<kms.DecryptResponse, kms.DecryptError>
81 >
82> {}
83
84export const Decrypt = Binding.Service<Decrypt>("AWS.KMS.Decrypt");