The best way to control Claude Code, Codex and more from any computer or phone

main
ts 146 lines 5.17 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import * as Effect from "effect/Effect";
3 import type { RotationRules } from "./RotationSchedule.ts";
4 import type { Secret } from "./Secret.ts";
5
6 /** A step of the Secrets Manager rotation protocol. */
7 export type RotationStep = "createSecret" | "setSecret" | "testSecret" | "finishSecret";
8
9 /**
10 * The payload Secrets Manager sends the rotation function on each step of a
11 * rotation.
12 */
13 export interface SecretRotationEvent {
14 /** Which step of the rotation protocol to perform. */
15 Step: RotationStep;
16 /** ARN of the secret being rotated. */
17 SecretId: string;
18 /**
19 * Request token that becomes the `VersionId` of the new secret version —
20 * pass it as `ClientRequestToken` to `PutSecretValue` and as
21 * `MoveToVersionId` to `UpdateSecretVersionStage`.
22 */
23 ClientRequestToken: string;
24 }
25
26 export interface RotationEventSourceProps {
27 /**
28 * When the rotation runs. Provide `scheduleExpression` or
29 * `automaticallyAfter`.
30 */
31 rotationRules?: RotationRules;
32 /**
33 * Rotate the secret immediately at deploy time. If `false`, Secrets
34 * Manager only validates the configuration by invoking the `testSecret`
35 * step.
36 * @default false
37 */
38 rotateImmediately?: boolean;
39 }
40
41 export type RotationEventSourceService = <Req = never>(
42 secret: Secret,
43 props: RotationEventSourceProps,
44 process: (event: SecretRotationEvent) => Effect.Effect<void, never, Req>,
45 ) => Effect.Effect<void, never, never>;
46
47 /**
48 * Register the current Lambda function as the rotation function for a
49 * Secrets Manager {@link Secret}.
50 *
51 * @param secret The secret to rotate.
52 * @param props Optional rotation schedule configuration.
53 * @param process The handler invoked once per rotation step (last argument).
54 *
55 * @example
56 * ```typescript
57 * yield* SecretsManager.onSecretRotation(secret, (event) =>
58 * Effect.gen(function* () {
59 * switch (event.Step) {
60 * case "createSecret": // stage a new AWSPENDING value
61 * case "setSecret": // apply it to the downstream system
62 * case "testSecret": // verify the new credential works
63 * case "finishSecret": // move AWSCURRENT onto the new version
64 * }
65 * }).pipe(Effect.orDie),
66 * );
67 * ```
68 *
69 * @example With a rotation schedule
70 * ```typescript
71 * yield* SecretsManager.onSecretRotation(
72 * secret,
73 * { rotationRules: { automaticallyAfter: "30 days" } },
74 * handleRotation,
75 * );
76 * ```
77 */
78 export function onSecretRotation<S extends Secret, Req = never>(
79 secret: S,
80 process: (event: SecretRotationEvent) => Effect.Effect<void, never, Req>,
81 ): Effect.Effect<void, never, RotationEventSource>;
82 export function onSecretRotation<S extends Secret, Req = never>(
83 secret: S,
84 props: RotationEventSourceProps,
85 process: (event: SecretRotationEvent) => Effect.Effect<void, never, Req>,
86 ): Effect.Effect<void, never, RotationEventSource>;
87 export function onSecretRotation<S extends Secret, Req = never>(
88 secret: S,
89 propsOrProcess:
90 | RotationEventSourceProps
91 | ((event: SecretRotationEvent) => Effect.Effect<void, never, Req>),
92 maybeProcess?: (event: SecretRotationEvent) => Effect.Effect<void, never, Req>,
93 ): Effect.Effect<void, never, RotationEventSource> {
94 const [props, process] =
95 typeof propsOrProcess === "function"
96 ? [{} as RotationEventSourceProps, propsOrProcess]
97 : [propsOrProcess, maybeProcess!];
98 return RotationEventSource.use((source) => source(secret, props, process));
99 }
100
101 /**
102 * Event source connecting a Secrets Manager {@link Secret}'s rotation to the
103 * hosting Lambda function.
104 *
105 * The contract is a `Binding.Service`; the Lambda implementation layer is
106 * `Lambda.SecretRotationEventSource` — at deploy time it grants Secrets
107 * Manager permission to invoke the function, attaches the rotation-protocol
108 * IAM actions for the secret, and provisions the
109 * {@link RotationSchedule}; at runtime it narrows incoming invocations to
110 * rotation events for the bound secret. Consume it through the
111 * {@link onSecretRotation} helper.
112 * ### Rotating Secrets
113 * **Example:** Rotation Function in a Lambda
114 * ```typescript
115 * export default RotationFunction.make(
116 * { main: import.meta.url },
117 * Effect.gen(function* () {
118 * const secret = yield* SecretsManager.Secret("DbPassword", {
119 * secretString: Redacted.make("initial"),
120 * });
121 * const getValue = yield* SecretsManager.GetSecretValue(secret);
122 * const putValue = yield* SecretsManager.PutSecretValue(secret);
123 * const updateStage = yield* SecretsManager.UpdateSecretVersionStage(secret);
124 * const describe = yield* SecretsManager.DescribeSecret(secret);
125 * const randomPassword = yield* SecretsManager.GetRandomPassword();
126 *
127 * yield* SecretsManager.onSecretRotation(
128 * secret,
129 * { rotationRules: { automaticallyAfter: "30 days" } },
130 * (event) => rotate(event).pipe(Effect.orDie),
131 * );
132 * }).pipe(Effect.provide(Lambda.SecretRotationEventSource)),
133 * );
134 * ```
135 *
136 * @binding
137 */
138 export interface RotationEventSource extends Binding.Service<
139 RotationEventSource,
140 "AWS.SecretsManager.RotationEventSource",
141 RotationEventSourceService
142 > {}
143
144 export const RotationEventSource = Binding.Service<RotationEventSource>(
145 "AWS.SecretsManager.RotationEventSource",
146 );