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

main
ts 421 lines 17.3 KB
Raw
1 import {
2 Credentials,
3 fromServiceAccountKey,
4 fromWorkloadIdentity,
5 } from "@distilled.cloud/gcp/Credentials";
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 * as Config from "effect/Config";
12 import * as Context from "effect/Context";
13 import * as Effect from "effect/Effect";
14 import * as FetchHttpClient from "effect/http/FetchHttpClient";
15 import * as Layer from "effect/Layer";
16 import * as Redacted from "effect/Redacted";
17 import type * as rolldown from "rolldown";
18 import type { GcpIamGrant } from "./Host.ts";
19 import { Member } from "./IAM/Member.ts";
20 import { ServiceAccount } from "./IAM/ServiceAccount.ts";
21 import { ServiceAccountKey } from "./IAM/ServiceAccountKey.ts";
22 import { WorkloadIdentityPool } from "./IAM/WorkloadIdentityPool.ts";
23 import { WorkloadIdentityProvider } from "./IAM/WorkloadIdentityProvider.ts";
24
25 /**
26 * How a GCP binding reaches GCP from its host:
27 *
28 * - the host runs as a service account (Cloud Run, Cloud Functions, a GKE
29 * pod): roles are granted to that account, and calls use its
30 * metadata-server credentials;
31 * - the host runs as an AWS IAM role (Lambda, ECS, EC2, App Runner): Alchemy
32 * creates a service account, grants the roles to it, and lets the role
33 * impersonate it through a workload identity pool that trusts the AWS
34 * account. The host exchanges a signed `GetCallerIdentity` request for the
35 * account's token; no key is created;
36 * - any other host (a Cloudflare Worker, an EKS pod): Alchemy creates a
37 * service account and key for it, grants the roles to that account, and
38 * binds the key into the host's env;
39 * - no host (a script or deploy-time Action): nothing is bound and calls use
40 * the deployer's credentials.
41 *
42 * Import it as a namespace. A binding resolves its operations with
43 * {@link withCredentials} and gets its `bind` from {@link Bind} when its layer
44 * is built, then binds behind its own `__ALCHEMY_RUNTIME__` guard:
45 *
46 * ```ts
47 * Effect.gen(function* () {
48 * const publish = yield* GCPBindings.withCredentials(pubsub.publishProjectsTopics);
49 * const bind = yield* GCPBindings.Bind;
50 * return Effect.fn(function* (topic: Topic) {
51 * if (!globalThis.__ALCHEMY_RUNTIME__) {
52 * yield* bind`GCP.PubSub.WriteTopic(${topic})`({
53 * iam: [{ role: "roles/pubsub.publisher", resource: { kind: "pubsub.topic", name: topic.name } }],
54 * });
55 * }
56 * return (message) => publish({ topic: …, body: … });
57 * });
58 * })
59 * ```
60 */
61
62 /** What a GCP binding attaches to its host. */
63 export interface HostBinding {
64 /** The IAM roles the binding needs. */
65 readonly iam?: Input<GcpIamGrant>[];
66 /** Env vars the binding reads at runtime. */
67 readonly env?: Record<string, unknown>;
68 }
69
70 /**
71 * Build options for a bundle that runs on a host running as a GCP service account (Cloud Run, Cloud Functions, GKE): defines
72 * `__ALCHEMY_HOST_IDENTITY__` as `"GCP.IAM.ServiceAccount"` so the bundler drops the created-key credentials path.
73 */
74 export const serviceAccountHostBundle = (input: rolldown.InputOptions): rolldown.InputOptions => ({
75 ...input,
76 transform: {
77 ...input.transform,
78 define: {
79 ...input.transform?.define,
80 "globalThis.__ALCHEMY_HOST_IDENTITY__": JSON.stringify("GCP.IAM.ServiceAccount"),
81 },
82 },
83 });
84
85 /**
86 * Env vars holding the key Alchemy creates for a host that doesn't run as a
87 * service account. Only {@link Bind} sets them, and only on that path, so
88 * at runtime their presence is the whole decision.
89 */
90 const KEY_ENV = {
91 email: "ALCHEMY_GCP_SERVICE_ACCOUNT_EMAIL",
92 project: "ALCHEMY_GCP_SERVICE_ACCOUNT_PROJECT",
93 privateKeyId: "ALCHEMY_GCP_SERVICE_ACCOUNT_KEY_ID",
94 privateKey: "ALCHEMY_GCP_SERVICE_ACCOUNT_KEY",
95 } as const;
96
97 /**
98 * Env vars for a host that runs as an AWS IAM role: the workload identity
99 * provider it exchanges its AWS identity at, and the service account it
100 * impersonates. Only {@link Bind} sets them, on that path only.
101 */
102 const FEDERATION_ENV = {
103 audience: "ALCHEMY_GCP_WORKLOAD_IDENTITY_AUDIENCE",
104 email: "ALCHEMY_GCP_WORKLOAD_IDENTITY_SERVICE_ACCOUNT",
105 project: "ALCHEMY_GCP_WORKLOAD_IDENTITY_PROJECT",
106 } as const;
107
108 /**
109 * The attribute holding the IAM role ARN each AWS host type runs as.
110 *
111 * TODO: don't hard-code AWS host types in the GCP package. The AWS package
112 * owns them; find a way for it to provide this, e.g. as a Layer the GCP
113 * binding reads at deploy time.
114 */
115 const AWS_ROLE_ARN_ATTRIBUTE: Record<string, string> = {
116 "AWS.Lambda.Function": "roleArn",
117 "AWS.Lambda.WebFunction": "roleArn",
118 "AWS.ECS.Task": "taskRoleArn",
119 "AWS.ECS.Service": "taskRoleArn",
120 "AWS.EC2.Instance": "roleArn",
121 "AWS.AutoScaling.LaunchTemplate": "roleArn",
122 "AWS.AppRunner.Service": "instanceRoleArn",
123 };
124
125 /**
126 * Whether a host runs its code as an AWS IAM role GCP can federate with:
127 * Lambda, ECS, EC2, an EC2 launch template, or App Runner. Not an EKS pod or
128 * a Batch job, which keep a key. Deploy-time only.
129 */
130 export const runsAsAwsRole = (host: ResourceLike): boolean =>
131 Object.hasOwn(AWS_ROLE_ARN_ATTRIBUTE, host.Type);
132
133 /**
134 * Id of the AWS provider in the stack's pool. Fixed so a host's env can name
135 * the provider by the pool alone: the provider reads the host's role (for
136 * the AWS account), so naming it by its own output would be a cycle.
137 */
138 const AWS_PROVIDER_ID = "alchemy-aws";
139
140 /** `arn:aws:iam::123:role/path/name` → `arn:aws:sts::123:assumed-role/name`. */
141 const assumedRoleArn = (roleArn: string) => {
142 const [, partition, , , account, resource] = roleArn.split(":");
143 const name = resource?.split("/").pop();
144 return `arn:${partition}:sts::${account}:assumed-role/${name}`;
145 };
146
147 /**
148 * Maps an AWS caller to the role it assumed, so a grant to
149 * `attribute.aws_role/arn:aws:sts::<account>:assumed-role/<role>` matches
150 * every session of that role. `google.subject` is the bounded `userid`
151 * (`<role id>:<session>`): a full assumed-role ARN can exceed its 127 bytes.
152 */
153 const AWS_ATTRIBUTE_MAPPING = {
154 "google.subject": "assertion.userid",
155 "attribute.aws_role":
156 "assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn",
157 };
158
159 /**
160 * Whether a host runs its code as a GCP service account: Cloud Run, Cloud
161 * Functions, or a Kubernetes workload on a GKE cluster (Workload Identity).
162 * Deploy-time only: it reads the host's props.
163 */
164 export const runsAsServiceAccount = (host: ResourceLike): boolean => {
165 switch (host.Type) {
166 case "GCP.Run.Service":
167 case "GCP.Run.Container":
168 case "GCP.Run.Job":
169 case "GCP.Run.WorkerPool":
170 case "GCP.CloudFunctions.Function":
171 return true;
172 case "Kubernetes.Deployment":
173 case "Kubernetes.Job":
174 return isGkeCluster(host.Props?.cluster);
175 default:
176 return false;
177 }
178 };
179
180 /** A `GCP.Container.Cluster`, or a cluster connection authenticating as `gcp-gke`. */
181 const isGkeCluster = (cluster: unknown): boolean => {
182 if (isResourceOfType(cluster, "GCP.Container.Cluster")) return true;
183 const value = cluster as { auth?: { kind?: string }; connection?: { auth?: { kind?: string } } };
184 return value?.auth?.kind === "gcp-gke" || value?.connection?.auth?.kind === "gcp-gke";
185 };
186
187 /** Label a grant `Allow(<host>, <label>)`, as `host.bind` records it. */
188 const allow = (label: TemplateStringsArray): TemplateStringsArray => {
189 const strings = ["Allow(", `, ${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 /**
199 * The `bind` for a binding's layer: yield it while the layer is built, then
200 * call it from the returned function, behind a literal
201 * `if (!globalThis.__ALCHEMY_RUNTIME__)` so the bundler drops it. It attaches
202 * the binding to its host labelled `Allow(<host>, <label>)`:
203 *
204 * - a host that runs as a service account takes the roles on that account;
205 * - a host that runs as an AWS IAM role gets a service account the role may
206 * impersonate through a workload identity pool; the account takes the roles;
207 * - any other host gets a service account and key; the account takes the
208 * roles and the key is bound into the host's env.
209 *
210 * ```ts
211 * Effect.gen(function* () {
212 * const bind = yield* GCPBindings.Bind;
213 * return Effect.fn(function* (topic: Topic) {
214 * if (!globalThis.__ALCHEMY_RUNTIME__) {
215 * yield* bind`GCP.PubSub.WriteTopic(${topic})`({ iam: [ … ] });
216 * }
217 * });
218 * })
219 * ```
220 */
221 /** The signature {@link Bind} yields. */
222 export type BindHost = (
223 label: TemplateStringsArray,
224 ...args: unknown[]
225 ) => (data: HostBinding) => Effect.Effect<void>;
226
227 export const Bind: Effect.Effect<BindHost> = Effect.gen(function* () {
228 // Bindings only bind at deploy, so a host bundle captures nothing here
229 // and drops the identity resources.
230 if (globalThis.__ALCHEMY_RUNTIME__) return () => () => Effect.void;
231 const GcpServiceAccount = yield* ServiceAccount;
232 const GcpServiceAccountKey = yield* ServiceAccountKey;
233 const GcpWorkloadIdentityPool = yield* WorkloadIdentityPool;
234 const GcpWorkloadIdentityProvider = yield* WorkloadIdentityProvider;
235 const GcpMember = yield* Member;
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 (runsAsServiceAccount(host)) {
243 return yield* (host as unknown as BindTarget).bind(allow(label), host, ...args)(data);
244 }
245
246 const account = yield* GcpServiceAccount(`${host.LogicalId}ServiceAccount`, {
247 displayName: `Alchemy: GCP access for ${host.LogicalId}`.slice(0, 100),
248 });
249 if (data.iam !== undefined && data.iam.length > 0) {
250 yield* (account as unknown as BindTarget).bind(
251 allow(label),
252 host,
253 ...args,
254 )({
255 iam: data.iam,
256 });
257 }
258 const runtime = (yield* CurrentRuntimeContext)!;
259
260 if (runsAsAwsRole(host)) {
261 const roleArn = (host as unknown as Record<string, Output.Output<string>>)[
262 AWS_ROLE_ARN_ATTRIBUTE[host.Type]!
263 ]!;
264 // One pool and provider serve every AWS host in the stack: a second
265 // declaration of the same id resolves to the first.
266 const pool = yield* GcpWorkloadIdentityPool("AwsWorkloadIdentityPool", {
267 displayName: "Alchemy AWS hosts",
268 });
269 yield* GcpWorkloadIdentityProvider("AwsWorkloadIdentityProvider", {
270 workloadIdentityPoolId: pool.workloadIdentityPoolId,
271 workloadIdentityPoolProviderId: AWS_PROVIDER_ID,
272 displayName: "Alchemy AWS hosts",
273 aws: { accountId: Output.map(roleArn, (arn) => arn.split(":")[4]!) },
274 attributeMapping: AWS_ATTRIBUTE_MAPPING,
275 });
276 yield* GcpMember(`${host.LogicalId}WorkloadIdentityUser`, {
277 kind: "iam.serviceAccount",
278 name: Output.interpolate`projects/${account.project}/serviceAccounts/${account.email}`,
279 role: "roles/iam.workloadIdentityUser",
280 member: Output.interpolate`principalSet://iam.googleapis.com/${pool.name}/attribute.aws_role/${Output.map(roleArn, assumedRoleArn)}`,
281 });
282 yield* runtime.set(
283 FEDERATION_ENV.audience,
284 Output.interpolate`//iam.googleapis.com/${pool.name}/providers/${AWS_PROVIDER_ID}`,
285 );
286 yield* runtime.set(FEDERATION_ENV.email, account.email);
287 yield* runtime.set(FEDERATION_ENV.project, account.project);
288 for (const [name, value] of Object.entries(data.env ?? {})) {
289 yield* runtime.set(name, Output.isOutput(value) ? value : Output.literal(value));
290 }
291 return;
292 }
293
294 const key = yield* GcpServiceAccountKey(`${host.LogicalId}ServiceAccountKey`, {
295 serviceAccount: account.email,
296 });
297 yield* runtime.set(KEY_ENV.email, account.email);
298 yield* runtime.set(KEY_ENV.project, account.project);
299 yield* runtime.set(KEY_ENV.privateKeyId, key.privateKeyId);
300 yield* runtime.set(KEY_ENV.privateKey, key.privateKey);
301 for (const [name, value] of Object.entries(data.env ?? {})) {
302 yield* runtime.set(name, Output.isOutput(value) ? value : Output.literal(value));
303 }
304 });
305 });
306
307 /**
308 * The subject token an AWS host exchanges at Google STS: a `GetCallerIdentity`
309 * request signed with the host's own role credentials (env, container or
310 * instance metadata), bound to `audience` by the signed
311 * `x-goog-cloud-target-resource` header. Google replays it against AWS STS to
312 * learn the caller. Built again on every token refresh.
313 */
314 const awsSubjectToken = (audience: string) =>
315 Effect.gen(function* () {
316 // Loaded on AWS hosts only: the Node credential chain has no browser build.
317 const aws = yield* Effect.promise(() => import("@distilled.cloud/aws/Credentials"));
318 const { sign } = yield* Effect.promise(() => import("@distilled.cloud/aws4signer"));
319 const creds = yield* Effect.gen(function* () {
320 const resolve = yield* aws.Credentials;
321 return yield* resolve;
322 }).pipe(Effect.provide(aws.fromNodeProviderChain()));
323 const region = yield* Config.String("AWS_REGION").pipe(
324 Config.withDefault(creds.region ?? "us-east-1"),
325 );
326 const signed = yield* sign({
327 method: "POST",
328 url: `https://sts.${region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15`,
329 headers: { "x-goog-cloud-target-resource": audience },
330 accessKeyId: Redacted.value(creds.accessKeyId),
331 secretAccessKey: creds.secretAccessKey,
332 sessionToken: creds.sessionToken,
333 service: "sts",
334 region,
335 });
336 const headers = { host: new URL(signed.url).host, ...signed.headers };
337 return Redacted.make(
338 encodeURIComponent(
339 JSON.stringify({
340 url: signed.url,
341 method: signed.method,
342 headers: Object.entries(headers).map(([key, value]) => ({ key, value })),
343 }),
344 ),
345 );
346 }).pipe(Effect.provide(FetchHttpClient.layer));
347
348 /**
349 * Resolve a distilled operation with the host's GCP credentials, once when
350 * the binding's layer is built: with the key {@link Bind} created for this
351 * host if there is one, as-is otherwise (the host's own service account, or
352 * the deployer).
353 */
354 export const withCredentials: <Op>(operation: Effect.Effect<Op, never, any>) => Effect.Effect<Op> =
355 Effect.fn(function* <Op>(operation: Effect.Effect<Op, never, any>) {
356 // A host running as a service account signs with its own credentials.
357 if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "GCP.IAM.ServiceAccount")
358 return yield* operation as Effect.Effect<Op>;
359 const runtime = yield* CurrentRuntimeContext;
360 // A host running as an AWS IAM role federates; it never has a key.
361 if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "AWS.IAM.Role") {
362 const audience =
363 globalThis.__ALCHEMY_RUNTIME__ && runtime !== undefined
364 ? yield* runtime.get<string>(FEDERATION_ENV.audience)
365 : undefined;
366 if (runtime === undefined || audience === undefined) {
367 return yield* operation as Effect.Effect<Op>;
368 }
369 const federated = fromWorkloadIdentity({
370 audience,
371 serviceAccountEmail: (yield* runtime.get<string>(FEDERATION_ENV.email))!,
372 project: yield* runtime.get<string>(FEDERATION_ENV.project),
373 subjectToken: awsSubjectToken(audience),
374 subjectTokenType: "urn:ietf:params:aws:token-type:aws4_request",
375 });
376 const credentials = Context.get(
377 yield* Layer.build(federated).pipe(Effect.scoped),
378 Credentials,
379 );
380 return yield* (operation as Effect.Effect<Op>).pipe(
381 Effect.provide(
382 Layer.mergeAll(Layer.succeed(Credentials, credentials), FetchHttpClient.layer),
383 ),
384 );
385 }
386 const email =
387 globalThis.__ALCHEMY_RUNTIME__ && runtime !== undefined
388 ? yield* runtime.get<string>(KEY_ENV.email)
389 : undefined;
390 if (runtime === undefined || email === undefined) {
391 return yield* operation as Effect.Effect<Op>;
392 }
393 const privateKey = yield* runtime.get<string | Redacted.Redacted<string>>(KEY_ENV.privateKey);
394 const key = fromServiceAccountKey({
395 clientEmail: email,
396 project: (yield* runtime.get<string>(KEY_ENV.project))!,
397 privateKeyId: (yield* runtime.get<string>(KEY_ENV.privateKeyId))!,
398 privateKey: Redacted.isRedacted(privateKey) ? privateKey : Redacted.make(privateKey ?? ""),
399 });
400 const credentials = Context.get(yield* Layer.build(key).pipe(Effect.scoped), Credentials);
401 return yield* (operation as Effect.Effect<Op>).pipe(
402 Effect.provide(
403 Layer.mergeAll(Layer.succeed(Credentials, credentials), FetchHttpClient.layer),
404 ),
405 );
406 });
407
408 /**
409 * Fail at deploy for a binding that needs its host to run as a service
410 * account, e.g. one that reads ID tokens from the metadata server.
411 */
412 export const requireServiceAccountHost = Effect.fn(function* (tag: string) {
413 if (globalThis.__ALCHEMY_RUNTIME__) return;
414 const host = yield* Binding.Host;
415 if (host === undefined || runsAsServiceAccount(host)) return;
416 return yield* Effect.die(
417 new Error(
418 `${tag} needs a host that runs as a GCP service account (Cloud Run, Cloud Functions or GKE), not ${host.Type} ${host.LogicalId}.`,
419 ),
420 );
421 });