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 EncryptRequest extends Omit<kms.EncryptRequest, "KeyId"> {}
8
9/**
10 * Runtime binding for `kms:Encrypt`.
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`. Payloads are raw `Uint8Array`s — the
15 * distilled client handles base64 wire encoding transparently.
16 *
17 * IAM is scoped to least privilege: the exact key ARN for a `Key` resource,
18 * or the `kms:RequestAlias` condition for an alias name.
19 *
20 * ### Encrypting Data
21 * **Example:** Encrypt a Payload
22 * ```typescript
23 * const encrypt = yield* AWS.KMS.Encrypt(key);
24 *
25 * const response = yield* encrypt({
26 * Plaintext: new TextEncoder().encode("attack at dawn"),
27 * });
28 * // response.CiphertextBlob is a Uint8Array
29 * ```
30 *
31 * **Example:** Encrypt with an Encryption Context
32 * ```typescript
33 * const response = yield* encrypt({
34 * Plaintext: payload,
35 * EncryptionContext: { tenant: "acme" },
36 * });
37 * ```
38 *
39 * ### Pre-Existing Keys
40 * **Example:** Bind by Alias Name
41 * ```typescript
42 * // Uses a key managed outside this stack; IAM is scoped via kms:RequestAlias.
43 * const encrypt = yield* AWS.KMS.Encrypt("alias/app-key");
44 * ```
45 *
46 * ### Wiring
47 * **Example:** Provide the Implementation on a Lambda Function
48 * ```typescript
49 * // Bind in the init phase, call in the handler, and provide the
50 * // EncryptHttp layer on the Function's init Effect (merge the other
51 * // KMS layers with Layer.mergeAll when using several bindings).
52 * export default CryptoFunction.make(
53 * { main: import.meta.url, functionUrl: true },
54 * Effect.gen(function* () {
55 * const key = yield* AWS.KMS.Key("AppKey");
56 * const encrypt = yield* AWS.KMS.Encrypt(key);
57 * return {
58 * fetch: Effect.gen(function* () {
59 * const request = yield* HttpServerRequest;
60 * const body = yield* request.text;
61 * const { CiphertextBlob } = yield* encrypt({
62 * Plaintext: new TextEncoder().encode(body),
63 * });
64 * return HttpServerResponse.json({
65 * ciphertext: Buffer.from(CiphertextBlob!).toString("base64"),
66 * });
67 * }),
68 * };
69 * }).pipe(Effect.provide(AWS.KMS.EncryptHttp)),
70 * );
71 * ```
72 *
73 * @binding
74 */
75export interface Encrypt extends Binding.Service<
76 Encrypt,
77 "AWS.KMS.Encrypt",
78 (
79 key: Key | AliasName,
80 ) => Effect.Effect<
81 (
82 request: EncryptRequest,
83 ) => Effect.Effect<kms.EncryptResponse, kms.EncryptError>
84 >
85> {}
86
87export const Encrypt = Binding.Service<Encrypt>("AWS.KMS.Encrypt");