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

main
ts 495 lines 19.4 KB
Raw
1 import { createHash } from "node:crypto";
2 import { fromWebToken, type ResolvedCredentials } from "@distilled.cloud/aws/Credentials";
3 import * as Endpoint from "@distilled.cloud/aws/Endpoint";
4 import { Region, type RegionName } from "@distilled.cloud/aws/Region";
5 import { AlchemyContext } from "alchemy/AlchemyContext";
6 import * as Binding from "alchemy/Binding";
7 import type { Input } from "alchemy/Input";
8 import * as Output from "alchemy/Output";
9 import { isResourceOfType, type ResourceLike } from "alchemy/Resource";
10 import { CurrentRuntimeContext } from "alchemy/RuntimeContext";
11 import { Stack } from "alchemy/Stack";
12 import * as Effect from "effect/Effect";
13 import * as FetchHttpClient from "effect/http/FetchHttpClient";
14 import * as HttpClient from "effect/http/HttpClient";
15 import * as HttpClientRequest from "effect/http/HttpClientRequest";
16 import * as Layer from "effect/Layer";
17 import * as Option from "effect/Option";
18 import * as Redacted from "effect/Redacted";
19 import type * as rolldown from "rolldown";
20 import { DEFAULT_LOCAL_ENDPOINT } from "./AuthProvider.ts";
21 import { Credentials, makeAssumeRoleResolver } from "./Credentials.ts";
22 import { AWSEnvironment } from "./Environment.ts";
23 import { AccessKey } from "./IAM/AccessKey.ts";
24 import type { PolicyStatement } from "./IAM/Policy.ts";
25 import { Role } from "./IAM/Role.ts";
26 import { User } from "./IAM/User.ts";
27 import { CurrentRegion } from "./Region.ts";
28
29 /**
30 * How an AWS binding reaches AWS from its host:
31 *
32 * - the host runs as an IAM role (Lambda, ECS, EC2, …): statements go on that
33 * role, and calls use its ambient credentials;
34 * - the host runs as a Google service account (Cloud Run, Cloud Functions):
35 * Alchemy creates a Role that trusts that account's Google ID tokens, puts
36 * the statements on the Role, and the host assumes it with
37 * `AssumeRoleWithWebIdentity`. No key is created;
38 * - any other host (a Cloudflare Worker, Cloud Run, a GKE pod): Alchemy
39 * creates an IAM User and AccessKey that may assume a Role, puts the
40 * statements on the Role, and binds the key into the host's env;
41 * - no host (a script or deploy-time Action): nothing is bound and calls use
42 * the deployer's credentials.
43 *
44 * Import it as a namespace. A binding resolves its operations with
45 * {@link withCredentials} and gets its `bind` from {@link Bind} when its layer
46 * is built, then binds behind its own `__ALCHEMY_RUNTIME__` guard:
47 *
48 * ```ts
49 * Effect.gen(function* () {
50 * const sendMessage = yield* AWSBindings.withCredentials(sqs.sendMessage);
51 * const bind = yield* AWSBindings.Bind;
52 * return Effect.fn(function* (queue: Queue) {
53 * if (!globalThis.__ALCHEMY_RUNTIME__) {
54 * yield* bind`AWS.SQS.SendMessage(${queue})`({
55 * policyStatements: [
56 * { Effect: "Allow", Action: ["sqs:SendMessage"], Resource: [queue.queueArn] },
57 * ],
58 * });
59 * }
60 * return (request) => sendMessage({ ...request, QueueUrl: … });
61 * });
62 * })
63 * ```
64 */
65
66 /** What a binding attaches to its host. */
67 export interface HostBinding {
68 /** The IAM statements the binding needs. */
69 readonly policyStatements?: Input<PolicyStatement>[];
70 /** Env vars the binding reads at runtime. */
71 readonly env?: Record<string, unknown>;
72 }
73
74 /** The VPC a host must attach to, e.g. to reach a VPC-only database. */
75 export interface HostVpc {
76 readonly subnetIds: Input<string[]>;
77 readonly securityGroupIds: Input<string[]>;
78 }
79
80 /**
81 * Build options for a bundle that runs on a host running as an IAM role (Lambda, ECS, EC2, AppRunner, Batch, EKS): defines
82 * `__ALCHEMY_HOST_IDENTITY__` as `"AWS.IAM.Role"` so the bundler drops the created-key credentials path.
83 */
84 export const roleHostBundle = (input: rolldown.InputOptions): rolldown.InputOptions => ({
85 ...input,
86 transform: {
87 ...input.transform,
88 define: {
89 ...input.transform?.define,
90 "globalThis.__ALCHEMY_HOST_IDENTITY__": JSON.stringify("AWS.IAM.Role"),
91 },
92 },
93 });
94
95 /**
96 * Env vars holding the key Alchemy creates for a host that doesn't run as an
97 * IAM role. Only {@link Bind} sets them, and only on that path, so at
98 * runtime their presence is the whole decision.
99 */
100 const KEY_ENV = {
101 accessKeyId: "ALCHEMY_AWS_ACCESS_KEY_ID",
102 secretAccessKey: "ALCHEMY_AWS_SECRET_ACCESS_KEY",
103 roleArn: "ALCHEMY_AWS_ROLE_ARN",
104 region: "ALCHEMY_AWS_REGION",
105 } as const;
106
107 /**
108 * Env var holding the Role a Google-service-account host assumes with its
109 * ID token. Only {@link Bind} sets it, on that path only.
110 */
111 const WEB_IDENTITY_ROLE_ENV = "ALCHEMY_AWS_WEB_IDENTITY_ROLE_ARN";
112
113 /** The `aud` a host requests on the Google ID tokens it exchanges with STS. */
114 const GOOGLE_ID_TOKEN_AUDIENCE = "sts.amazonaws.com";
115
116 /**
117 * Whether a host runs its code as an IAM role: Lambda, ECS, EC2,
118 * AutoScaling, AppRunner, Batch, or a Kubernetes workload on an EKS cluster
119 * (Pod Identity). Not a Lambda `MicrovmImage`: an image has no role of its
120 * own (`RunMicrovm` takes one per launch). Deploy-time only: it reads the
121 * host's props.
122 */
123 export const runsAsRole = (host: ResourceLike): boolean => {
124 switch (host.Type) {
125 case "AWS.Lambda.Function":
126 case "AWS.Lambda.WebFunction":
127 case "AWS.ECS.Task":
128 case "AWS.ECS.Service":
129 case "AWS.EC2.Instance":
130 case "AWS.AutoScaling.LaunchTemplate":
131 case "AWS.AppRunner.Service":
132 case "AWS.Batch.JobDefinition":
133 return true;
134 case "Kubernetes.Deployment":
135 case "Kubernetes.Job":
136 return isEksCluster(host.Props?.cluster);
137 default:
138 return false;
139 }
140 };
141
142 /**
143 * Whether a host runs its code as a Google service account that can fetch ID
144 * tokens from the metadata server: Cloud Run and Cloud Functions. Not a GKE
145 * pod: its Workload Identity principal has no ID tokens. Deploy-time only.
146 *
147 * TODO: don't hard-code GCP host types in the AWS package. The GCP package
148 * owns them (and their `serviceAccountUniqueId`); find a way for it to
149 * provide this, e.g. as a Layer the AWS binding reads at deploy time.
150 */
151 export const runsAsGoogleServiceAccount = (host: ResourceLike): boolean => {
152 switch (host.Type) {
153 case "GCP.Run.Service":
154 case "GCP.Run.Job":
155 case "GCP.Run.WorkerPool":
156 case "GCP.CloudFunctions.Function":
157 return true;
158 default:
159 return false;
160 }
161 };
162
163 /**
164 * The name of the Role a Google-service-account host assumes:
165 * `{stack}-{host}-{stage}-` plus a hash of the host's FQN, at most 64
166 * characters. Derived from the host alone so the host's env can name the
167 * Role without depending on it.
168 */
169 const federatedRoleName = Effect.fn(function* (host: ResourceLike) {
170 const stack = yield* Effect.serviceOption(Stack);
171 const prefix = Option.isSome(stack)
172 ? `${stack.value.name}-${host.LogicalId}-${stack.value.stage}-`
173 : `${host.LogicalId}-`;
174 const hash = yield* Effect.sync(() =>
175 createHash("sha256").update(host.FQN).digest("hex").slice(0, 12),
176 );
177 return `${prefix.replaceAll(/[^a-zA-Z0-9-]/g, "-").slice(0, 64 - hash.length)}${hash}`;
178 });
179
180 /** An `AWS.EKS.Cluster`, or a cluster connection authenticating as `aws-eks`. */
181 const isEksCluster = (cluster: unknown): boolean => {
182 if (isResourceOfType(cluster, "AWS.EKS.Cluster")) return true;
183 const value = cluster as { auth?: { kind?: string }; connection?: { auth?: { kind?: string } } };
184 return value?.auth?.kind === "aws-eks" || value?.connection?.auth?.kind === "aws-eks";
185 };
186
187 /** Label a binding `<verb>(<host>, <label>)`, as `host.bind` records it. */
188 const labelled = (verb: string, label: TemplateStringsArray): TemplateStringsArray => {
189 const strings = [`${verb}(`, `, ${label[0]}`, ...label.slice(1)];
190 strings[strings.length - 1] += ")";
191 return Object.assign(strings, { raw: strings }) as unknown as TemplateStringsArray;
192 };
193
194 type BindTarget = {
195 bind: (...args: unknown[]) => (data: unknown) => Effect.Effect<void>;
196 };
197
198 const toOutput = (value: unknown) => (Output.isOutput(value) ? value : Output.literal(value));
199
200 /**
201 * The `bind` for a binding's layer: yield it while the layer is built, then
202 * call it from the returned function, behind a literal
203 * `if (!globalThis.__ALCHEMY_RUNTIME__)` so the bundler drops it. It attaches
204 * the binding to its host labelled `Allow(<host>, <label>)`:
205 *
206 * - a host that runs as an IAM role takes the statements on that role;
207 * - a host that runs as a Google service account gets a Role that trusts
208 * its ID tokens; the Role takes the statements;
209 * - any other host gets an IAM User and AccessKey that may assume a Role;
210 * the Role takes the statements and the key is bound into the host's env.
211 *
212 * ```ts
213 * Effect.gen(function* () {
214 * const bind = yield* AWSBindings.Bind;
215 * return Effect.fn(function* (queue: Queue) {
216 * if (!globalThis.__ALCHEMY_RUNTIME__) {
217 * yield* bind`AWS.SQS.SendMessage(${queue})`({ policyStatements: [ … ] });
218 * }
219 * });
220 * })
221 * ```
222 */
223 /** The signature {@link Bind} yields. */
224 export type BindHost = (
225 label: TemplateStringsArray,
226 ...args: unknown[]
227 ) => (data: HostBinding) => Effect.Effect<void>;
228
229 export const Bind: Effect.Effect<BindHost> = Effect.gen(function* () {
230 // Bindings only bind at deploy, so a host bundle captures nothing here
231 // and drops the identity resources.
232 if (globalThis.__ALCHEMY_RUNTIME__) return () => () => Effect.void;
233 const IamUser = yield* User;
234 const IamAccessKey = yield* AccessKey;
235 const IamRole = yield* Role;
236
237 return (label: TemplateStringsArray, ...args: unknown[]) =>
238 Effect.fn(function* (data: HostBinding) {
239 const host = yield* Binding.Host;
240 if (host === undefined) return;
241
242 if (runsAsRole(host)) {
243 return yield* (host as unknown as BindTarget).bind(
244 labelled("Allow", label),
245 host,
246 ...args,
247 )(data);
248 }
249
250 const id = host.LogicalId;
251 const runtime = (yield* CurrentRuntimeContext)!;
252
253 if (runsAsGoogleServiceAccount(host)) {
254 // The host's env names the Role by a name derived from the host, not
255 // by the Role's output: the Role's trust reads the host's service
256 // account, so an env reference back to the Role would be a cycle.
257 const roleName = yield* federatedRoleName(host);
258 const uniqueId = (host as unknown as { serviceAccountUniqueId: Output.Output<string> })
259 .serviceAccountUniqueId;
260 const role = yield* IamRole(`${id}Role`, {
261 roleName,
262 assumeRolePolicyDocument: {
263 Version: "2012-10-17",
264 Statement: [
265 {
266 Effect: "Allow",
267 Principal: { Federated: "accounts.google.com" },
268 Action: ["sts:AssumeRoleWithWebIdentity"],
269 Condition: {
270 StringEquals: {
271 // Google ID tokens carry the account's unique ID as
272 // `sub` and `azp`; IAM reads `azp` as `aud` and the
273 // requested audience as `oaud`.
274 "accounts.google.com:sub": uniqueId,
275 "accounts.google.com:aud": uniqueId,
276 "accounts.google.com:oaud": GOOGLE_ID_TOKEN_AUDIENCE,
277 },
278 },
279 },
280 ],
281 },
282 });
283 if (data.policyStatements !== undefined && data.policyStatements.length > 0) {
284 yield* (role as unknown as BindTarget).bind(
285 labelled("Allow", label),
286 host,
287 ...args,
288 )({ policyStatements: data.policyStatements });
289 }
290 yield* runtime.set(
291 WEB_IDENTITY_ROLE_ENV,
292 Output.fromEffect(
293 AWSEnvironment.use((env) =>
294 Effect.map(env, ({ accountId }) => `arn:aws:iam::${accountId}:role/${roleName}`),
295 ).pipe(Effect.orDie),
296 ) as Output.Output<string>,
297 );
298 yield* runtime.set(
299 KEY_ENV.region,
300 Output.fromEffect(CurrentRegion.pipe(Effect.orDie)) as Output.Output<string>,
301 );
302 for (const [key, value] of Object.entries(data.env ?? {})) {
303 yield* runtime.set(key, toOutput(value));
304 }
305 return;
306 }
307
308 // The user may assume any role that trusts it; the role's trust policy
309 // restricts assumption to this user, which avoids a User↔Role ARN cycle.
310 const user = yield* IamUser(`${id}User`, {
311 inlinePolicies: {
312 AssumeRole: {
313 Version: "2012-10-17",
314 Statement: [{ Effect: "Allow", Action: ["sts:AssumeRole"], Resource: ["*"] }],
315 },
316 },
317 });
318 const accessKey = yield* IamAccessKey(`${id}AccessKey`, { userName: user.userName });
319 const role = yield* IamRole(`${id}Role`, {
320 assumeRolePolicyDocument: {
321 Version: "2012-10-17",
322 Statement: [
323 { Effect: "Allow", Principal: { AWS: user.userArn }, Action: ["sts:AssumeRole"] },
324 ],
325 },
326 });
327 if (data.policyStatements !== undefined && data.policyStatements.length > 0) {
328 yield* (role as unknown as BindTarget).bind(
329 labelled("Allow", label),
330 host,
331 ...args,
332 )({ policyStatements: data.policyStatements });
333 }
334
335 yield* runtime.set(KEY_ENV.accessKeyId, accessKey.accessKeyId);
336 yield* runtime.set(KEY_ENV.secretAccessKey, accessKey.secretAccessKey);
337 yield* runtime.set(KEY_ENV.roleArn, role.roleArn);
338 yield* runtime.set(
339 KEY_ENV.region,
340 Output.fromEffect(CurrentRegion.pipe(Effect.orDie)) as Output.Output<string>,
341 );
342 // Local dev: STS and the bound operations run on the emulator, reached
343 // via the same `AWS_ENDPOINT_URL` the emulator injects into Lambdas.
344 const context = yield* Effect.serviceOption(AlchemyContext);
345 if (Option.isSome(context) && context.value.dev) {
346 yield* runtime.set("AWS_ENDPOINT_URL", Output.literal(DEFAULT_LOCAL_ENDPOINT));
347 }
348 for (const [key, value] of Object.entries(data.env ?? {})) {
349 yield* runtime.set(key, toOutput(value));
350 }
351 });
352 });
353
354 /**
355 * Attach the host to a VPC, labelled `Vpc(<host>, <label>)`. Only a host that
356 * runs as an IAM role has a VPC to attach; any other host reaches AWS over
357 * the internet, so this skips it. Call it behind a literal
358 * `if (!globalThis.__ALCHEMY_RUNTIME__)`.
359 */
360 export const bindVpc = (label: TemplateStringsArray, ...args: unknown[]) =>
361 Effect.fn(function* (vpc: HostVpc) {
362 const host = yield* Binding.Host;
363 if (host === undefined || !runsAsRole(host)) return;
364 yield* (host as unknown as BindTarget).bind(labelled("Vpc", label), host, ...args)({ vpc });
365 });
366
367 /**
368 * A Google ID token for {@link GOOGLE_ID_TOKEN_AUDIENCE}, fetched from the
369 * metadata server as the host's runtime service account. Tokens live an
370 * hour; a fresh one is fetched on every credential refresh.
371 */
372 const googleIdToken = Effect.gen(function* () {
373 const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
374 const response = yield* client.execute(
375 HttpClientRequest.get(
376 "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity",
377 ).pipe(
378 HttpClientRequest.setHeader("Metadata-Flavor", "Google"),
379 HttpClientRequest.setUrlParams({ audience: GOOGLE_ID_TOKEN_AUDIENCE, format: "full" }),
380 ),
381 );
382 return Redacted.make((yield* response.text).trim());
383 }).pipe(Effect.provide(FetchHttpClient.layer));
384
385 /**
386 * Resolve an operation on a host that runs as a Google service account: the
387 * Role {@link Bind} created for it is assumed with the host's Google ID token
388 * (`AssumeRoleWithWebIdentity`). Credentials are cached and re-assumed with a
389 * fresh token shortly before they expire.
390 */
391 const withWebIdentity = Effect.fn(function* <Op>(
392 operation: Effect.Effect<Op, never, any>,
393 region?: Effect.Effect<Effect.Effect<string>, never, any>,
394 ) {
395 const runtime = yield* CurrentRuntimeContext;
396 const roleArn = runtime ? yield* runtime.get<string>(WEB_IDENTITY_ROLE_ENV) : undefined;
397 if (runtime === undefined || roleArn === undefined) {
398 return yield* operation as Effect.Effect<Op>;
399 }
400 const credentials = fromWebToken({
401 roleArn,
402 webIdentityToken: googleIdToken,
403 roleSessionName: "alchemy",
404 // STS is global; operations provide their own Region.
405 region: "us-east-1",
406 });
407 const callRegion =
408 region !== undefined
409 ? yield* region as Effect.Effect<Effect.Effect<string>>
410 : Effect.map(runtime.get<string>(KEY_ENV.region), (value) => value ?? "us-east-1");
411 return yield* (operation as Effect.Effect<Op>).pipe(
412 Effect.provide([
413 credentials,
414 Layer.succeed(Region, callRegion as Effect.Effect<RegionName>),
415 Endpoint.fromEnv(),
416 FetchHttpClient.layer,
417 ]),
418 );
419 });
420
421 /**
422 * Resolve a distilled operation (or several, with `Effect.all`) with the
423 * host's AWS credentials, once when the binding's layer is built: by
424 * assuming the Role {@link Bind} created for this host if there is one,
425 * as-is otherwise (the host's own role, or the deployer).
426 *
427 * @param region the region a host with a created key signs in, e.g. a
428 * bucket's own. Its outer Effect may read resource attributes onto the
429 * host, so it also runs at deploy for those hosts.
430 * @default the stack's region
431 */
432 export const withCredentials: <Op>(
433 operation: Effect.Effect<Op, never, any>,
434 region?: Effect.Effect<Effect.Effect<string>, never, any>,
435 ) => Effect.Effect<Op> = Effect.fn(function* <Op>(
436 operation: Effect.Effect<Op, never, any>,
437 region?: Effect.Effect<Effect.Effect<string>, never, any>,
438 ) {
439 // A host running as an IAM role signs with its own credentials.
440 if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "AWS.IAM.Role")
441 return yield* operation as Effect.Effect<Op>;
442 // A host running as a Google service account assumes its Role with an ID
443 // token; it never has a key, so the bundler drops that path.
444 if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "GCP.IAM.ServiceAccount") {
445 return yield* withWebIdentity(operation, region);
446 }
447 if (!globalThis.__ALCHEMY_RUNTIME__) {
448 const host = yield* Binding.Host;
449 if (region !== undefined && host !== undefined && !runsAsRole(host)) {
450 // Only the outer Effect: it binds attributes onto the host at deploy.
451 yield* Effect.asVoid(region as Effect.Effect<Effect.Effect<string>>);
452 }
453 return yield* operation as Effect.Effect<Op>;
454 }
455
456 const runtime = yield* CurrentRuntimeContext;
457 const roleArn = runtime ? yield* runtime.get<string>(KEY_ENV.roleArn) : undefined;
458 if (runtime === undefined || roleArn === undefined) {
459 return yield* operation as Effect.Effect<Op>;
460 }
461
462 // The created user's key signs `AssumeRole`; read on each refresh.
463 const base = Layer.succeed(
464 Credentials,
465 Effect.gen(function* () {
466 const secret = yield* runtime.get<string | Redacted.Redacted<string>>(
467 KEY_ENV.secretAccessKey,
468 );
469 return {
470 accessKeyId: Redacted.make((yield* runtime.get<string>(KEY_ENV.accessKeyId)) ?? ""),
471 secretAccessKey: Redacted.isRedacted(secret) ? secret : Redacted.make(secret ?? ""),
472 sessionToken: undefined,
473 // STS is global; operations provide their own Region.
474 region: "us-east-1",
475 } satisfies ResolvedCredentials;
476 }),
477 );
478 const credentials = yield* makeAssumeRoleResolver({
479 roleArn: Effect.succeed(roleArn),
480 base,
481 region: "us-east-1",
482 });
483 const callRegion =
484 region !== undefined
485 ? yield* region as Effect.Effect<Effect.Effect<string>>
486 : Effect.map(runtime.get<string>(KEY_ENV.region), (value) => value ?? "us-east-1");
487 return yield* (operation as Effect.Effect<Op>).pipe(
488 Effect.provide([
489 Layer.succeed(Credentials, credentials),
490 Layer.succeed(Region, callRegion as Effect.Effect<RegionName>),
491 Endpoint.fromEnv(),
492 FetchHttpClient.layer,
493 ]),
494 );
495 });