sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ GCPBindings.ts

import {
  Credentials,
  fromServiceAccountKey,
  fromWorkloadIdentity,
} from "@distilled.cloud/gcp/Credentials";
import * as Binding from "alchemy/Binding";
import type { Input } from "alchemy/Input";
import * as Output from "alchemy/Output";
import { isResourceOfType, type ResourceLike } from "alchemy/Resource";
import { CurrentRuntimeContext } from "alchemy/RuntimeContext";
import * as Config from "effect/Config";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
import type * as rolldown from "rolldown";
import type { GcpIamGrant } from "./Host.ts";
import { Member } from "./IAM/Member.ts";
import { ServiceAccount } from "./IAM/ServiceAccount.ts";
import { ServiceAccountKey } from "./IAM/ServiceAccountKey.ts";
import { WorkloadIdentityPool } from "./IAM/WorkloadIdentityPool.ts";
import { WorkloadIdentityProvider } from "./IAM/WorkloadIdentityProvider.ts";

/**
 * How a GCP binding reaches GCP from its host:
 *
 * - the host runs as a service account (Cloud Run, Cloud Functions, a GKE
 *   pod): roles are granted to that account, and calls use its
 *   metadata-server credentials;
 * - the host runs as an AWS IAM role (Lambda, ECS, EC2, App Runner): Alchemy
 *   creates a service account, grants the roles to it, and lets the role
 *   impersonate it through a workload identity pool that trusts the AWS
 *   account. The host exchanges a signed `GetCallerIdentity` request for the
 *   account's token; no key is created;
 * - any other host (a Cloudflare Worker, an EKS pod): Alchemy creates a
 *   service account and key for it, grants the roles to that account, and
 *   binds the key into the host's env;
 * - no host (a script or deploy-time Action): nothing is bound and calls use
 *   the deployer's credentials.
 *
 * Import it as a namespace. A binding resolves its operations with
 * {@link withCredentials} and gets its `bind` from {@link Bind} when its layer
 * is built, then binds behind its own `__ALCHEMY_RUNTIME__` guard:
 *
 * ```ts
 * Effect.gen(function* () {
 *   const publish = yield* GCPBindings.withCredentials(pubsub.publishProjectsTopics);
 *   const bind = yield* GCPBindings.Bind;
 *   return Effect.fn(function* (topic: Topic) {
 *     if (!globalThis.__ALCHEMY_RUNTIME__) {
 *       yield* bind`GCP.PubSub.WriteTopic(${topic})`({
 *         iam: [{ role: "roles/pubsub.publisher", resource: { kind: "pubsub.topic", name: topic.name } }],
 *       });
 *     }
 *     return (message) => publish({ topic: …, body: … });
 *   });
 * })
 * ```
 */

/** What a GCP binding attaches to its host. */
export interface HostBinding {
  /** The IAM roles the binding needs. */
  readonly iam?: Input<GcpIamGrant>[];
  /** Env vars the binding reads at runtime. */
  readonly env?: Record<string, unknown>;
}

/**
 * Build options for a bundle that runs on a host running as a GCP service account (Cloud Run, Cloud Functions, GKE): defines
 * `__ALCHEMY_HOST_IDENTITY__` as `"GCP.IAM.ServiceAccount"` so the bundler drops the created-key credentials path.
 */
export const serviceAccountHostBundle = (input: rolldown.InputOptions): rolldown.InputOptions => ({
  ...input,
  transform: {
    ...input.transform,
    define: {
      ...input.transform?.define,
      "globalThis.__ALCHEMY_HOST_IDENTITY__": JSON.stringify("GCP.IAM.ServiceAccount"),
    },
  },
});

/**
 * Env vars holding the key Alchemy creates for a host that doesn't run as a
 * service account. Only {@link Bind} sets them, and only on that path, so
 * at runtime their presence is the whole decision.
 */
const KEY_ENV = {
  email: "ALCHEMY_GCP_SERVICE_ACCOUNT_EMAIL",
  project: "ALCHEMY_GCP_SERVICE_ACCOUNT_PROJECT",
  privateKeyId: "ALCHEMY_GCP_SERVICE_ACCOUNT_KEY_ID",
  privateKey: "ALCHEMY_GCP_SERVICE_ACCOUNT_KEY",
} as const;

/**
 * Env vars for a host that runs as an AWS IAM role: the workload identity
 * provider it exchanges its AWS identity at, and the service account it
 * impersonates. Only {@link Bind} sets them, on that path only.
 */
const FEDERATION_ENV = {
  audience: "ALCHEMY_GCP_WORKLOAD_IDENTITY_AUDIENCE",
  email: "ALCHEMY_GCP_WORKLOAD_IDENTITY_SERVICE_ACCOUNT",
  project: "ALCHEMY_GCP_WORKLOAD_IDENTITY_PROJECT",
} as const;

/**
 * The attribute holding the IAM role ARN each AWS host type runs as.
 *
 * TODO: don't hard-code AWS host types in the GCP package. The AWS package
 * owns them; find a way for it to provide this, e.g. as a Layer the GCP
 * binding reads at deploy time.
 */
const AWS_ROLE_ARN_ATTRIBUTE: Record<string, string> = {
  "AWS.Lambda.Function": "roleArn",
  "AWS.Lambda.WebFunction": "roleArn",
  "AWS.ECS.Task": "taskRoleArn",
  "AWS.ECS.Service": "taskRoleArn",
  "AWS.EC2.Instance": "roleArn",
  "AWS.AutoScaling.LaunchTemplate": "roleArn",
  "AWS.AppRunner.Service": "instanceRoleArn",
};

/**
 * Whether a host runs its code as an AWS IAM role GCP can federate with:
 * Lambda, ECS, EC2, an EC2 launch template, or App Runner. Not an EKS pod or
 * a Batch job, which keep a key. Deploy-time only.
 */
export const runsAsAwsRole = (host: ResourceLike): boolean =>
  Object.hasOwn(AWS_ROLE_ARN_ATTRIBUTE, host.Type);

/**
 * Id of the AWS provider in the stack's pool. Fixed so a host's env can name
 * the provider by the pool alone: the provider reads the host's role (for
 * the AWS account), so naming it by its own output would be a cycle.
 */
const AWS_PROVIDER_ID = "alchemy-aws";

/** `arn:aws:iam::123:role/path/name` → `arn:aws:sts::123:assumed-role/name`. */
const assumedRoleArn = (roleArn: string) => {
  const [, partition, , , account, resource] = roleArn.split(":");
  const name = resource?.split("/").pop();
  return `arn:${partition}:sts::${account}:assumed-role/${name}`;
};

/**
 * Maps an AWS caller to the role it assumed, so a grant to
 * `attribute.aws_role/arn:aws:sts::<account>:assumed-role/<role>` matches
 * every session of that role. `google.subject` is the bounded `userid`
 * (`<role id>:<session>`): a full assumed-role ARN can exceed its 127 bytes.
 */
const AWS_ATTRIBUTE_MAPPING = {
  "google.subject": "assertion.userid",
  "attribute.aws_role":
    "assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn",
};

/**
 * Whether a host runs its code as a GCP service account: Cloud Run, Cloud
 * Functions, or a Kubernetes workload on a GKE cluster (Workload Identity).
 * Deploy-time only: it reads the host's props.
 */
export const runsAsServiceAccount = (host: ResourceLike): boolean => {
  switch (host.Type) {
    case "GCP.Run.Service":
    case "GCP.Run.Container":
    case "GCP.Run.Job":
    case "GCP.Run.WorkerPool":
    case "GCP.CloudFunctions.Function":
      return true;
    case "Kubernetes.Deployment":
    case "Kubernetes.Job":
      return isGkeCluster(host.Props?.cluster);
    default:
      return false;
  }
};

/** A `GCP.Container.Cluster`, or a cluster connection authenticating as `gcp-gke`. */
const isGkeCluster = (cluster: unknown): boolean => {
  if (isResourceOfType(cluster, "GCP.Container.Cluster")) return true;
  const value = cluster as { auth?: { kind?: string }; connection?: { auth?: { kind?: string } } };
  return value?.auth?.kind === "gcp-gke" || value?.connection?.auth?.kind === "gcp-gke";
};

/** Label a grant `Allow(<host>, <label>)`, as `host.bind` records it. */
const allow = (label: TemplateStringsArray): TemplateStringsArray => {
  const strings = ["Allow(", `, ${label[0]}`, ...label.slice(1)];
  strings[strings.length - 1] += ")";
  return Object.assign(strings, { raw: strings }) as unknown as TemplateStringsArray;
};

type BindTarget = {
  bind: (...args: unknown[]) => (data: unknown) => Effect.Effect<void>;
};

/**
 * The `bind` for a binding's layer: yield it while the layer is built, then
 * call it from the returned function, behind a literal
 * `if (!globalThis.__ALCHEMY_RUNTIME__)` so the bundler drops it. It attaches
 * the binding to its host labelled `Allow(<host>, <label>)`:
 *
 * - a host that runs as a service account takes the roles on that account;
 * - a host that runs as an AWS IAM role gets a service account the role may
 *   impersonate through a workload identity pool; the account takes the roles;
 * - any other host gets a service account and key; the account takes the
 *   roles and the key is bound into the host's env.
 *
 * ```ts
 * Effect.gen(function* () {
 *   const bind = yield* GCPBindings.Bind;
 *   return Effect.fn(function* (topic: Topic) {
 *     if (!globalThis.__ALCHEMY_RUNTIME__) {
 *       yield* bind`GCP.PubSub.WriteTopic(${topic})`({ iam: [ … ] });
 *     }
 *   });
 * })
 * ```
 */
/** The signature {@link Bind} yields. */
export type BindHost = (
  label: TemplateStringsArray,
  ...args: unknown[]
) => (data: HostBinding) => Effect.Effect<void>;

export const Bind: Effect.Effect<BindHost> = Effect.gen(function* () {
  // Bindings only bind at deploy, so a host bundle captures nothing here
  // and drops the identity resources.
  if (globalThis.__ALCHEMY_RUNTIME__) return () => () => Effect.void;
  const GcpServiceAccount = yield* ServiceAccount;
  const GcpServiceAccountKey = yield* ServiceAccountKey;
  const GcpWorkloadIdentityPool = yield* WorkloadIdentityPool;
  const GcpWorkloadIdentityProvider = yield* WorkloadIdentityProvider;
  const GcpMember = yield* Member;

  return (label: TemplateStringsArray, ...args: unknown[]) =>
    Effect.fn(function* (data: HostBinding) {
      const host = yield* Binding.Host;
      if (host === undefined) return;

      if (runsAsServiceAccount(host)) {
        return yield* (host as unknown as BindTarget).bind(allow(label), host, ...args)(data);
      }

      const account = yield* GcpServiceAccount(`${host.LogicalId}ServiceAccount`, {
        displayName: `Alchemy: GCP access for ${host.LogicalId}`.slice(0, 100),
      });
      if (data.iam !== undefined && data.iam.length > 0) {
        yield* (account as unknown as BindTarget).bind(
          allow(label),
          host,
          ...args,
        )({
          iam: data.iam,
        });
      }
      const runtime = (yield* CurrentRuntimeContext)!;

      if (runsAsAwsRole(host)) {
        const roleArn = (host as unknown as Record<string, Output.Output<string>>)[
          AWS_ROLE_ARN_ATTRIBUTE[host.Type]!
        ]!;
        // One pool and provider serve every AWS host in the stack: a second
        // declaration of the same id resolves to the first.
        const pool = yield* GcpWorkloadIdentityPool("AwsWorkloadIdentityPool", {
          displayName: "Alchemy AWS hosts",
        });
        yield* GcpWorkloadIdentityProvider("AwsWorkloadIdentityProvider", {
          workloadIdentityPoolId: pool.workloadIdentityPoolId,
          workloadIdentityPoolProviderId: AWS_PROVIDER_ID,
          displayName: "Alchemy AWS hosts",
          aws: { accountId: Output.map(roleArn, (arn) => arn.split(":")[4]!) },
          attributeMapping: AWS_ATTRIBUTE_MAPPING,
        });
        yield* GcpMember(`${host.LogicalId}WorkloadIdentityUser`, {
          kind: "iam.serviceAccount",
          name: Output.interpolate`projects/${account.project}/serviceAccounts/${account.email}`,
          role: "roles/iam.workloadIdentityUser",
          member: Output.interpolate`principalSet://iam.googleapis.com/${pool.name}/attribute.aws_role/${Output.map(roleArn, assumedRoleArn)}`,
        });
        yield* runtime.set(
          FEDERATION_ENV.audience,
          Output.interpolate`//iam.googleapis.com/${pool.name}/providers/${AWS_PROVIDER_ID}`,
        );
        yield* runtime.set(FEDERATION_ENV.email, account.email);
        yield* runtime.set(FEDERATION_ENV.project, account.project);
        for (const [name, value] of Object.entries(data.env ?? {})) {
          yield* runtime.set(name, Output.isOutput(value) ? value : Output.literal(value));
        }
        return;
      }

      const key = yield* GcpServiceAccountKey(`${host.LogicalId}ServiceAccountKey`, {
        serviceAccount: account.email,
      });
      yield* runtime.set(KEY_ENV.email, account.email);
      yield* runtime.set(KEY_ENV.project, account.project);
      yield* runtime.set(KEY_ENV.privateKeyId, key.privateKeyId);
      yield* runtime.set(KEY_ENV.privateKey, key.privateKey);
      for (const [name, value] of Object.entries(data.env ?? {})) {
        yield* runtime.set(name, Output.isOutput(value) ? value : Output.literal(value));
      }
    });
});

/**
 * The subject token an AWS host exchanges at Google STS: a `GetCallerIdentity`
 * request signed with the host's own role credentials (env, container or
 * instance metadata), bound to `audience` by the signed
 * `x-goog-cloud-target-resource` header. Google replays it against AWS STS to
 * learn the caller. Built again on every token refresh.
 */
const awsSubjectToken = (audience: string) =>
  Effect.gen(function* () {
    // Loaded on AWS hosts only: the Node credential chain has no browser build.
    const aws = yield* Effect.promise(() => import("@distilled.cloud/aws/Credentials"));
    const { sign } = yield* Effect.promise(() => import("@distilled.cloud/aws4signer"));
    const creds = yield* Effect.gen(function* () {
      const resolve = yield* aws.Credentials;
      return yield* resolve;
    }).pipe(Effect.provide(aws.fromNodeProviderChain()));
    const region = yield* Config.String("AWS_REGION").pipe(
      Config.withDefault(creds.region ?? "us-east-1"),
    );
    const signed = yield* sign({
      method: "POST",
      url: `https://sts.${region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15`,
      headers: { "x-goog-cloud-target-resource": audience },
      accessKeyId: Redacted.value(creds.accessKeyId),
      secretAccessKey: creds.secretAccessKey,
      sessionToken: creds.sessionToken,
      service: "sts",
      region,
    });
    const headers = { host: new URL(signed.url).host, ...signed.headers };
    return Redacted.make(
      encodeURIComponent(
        JSON.stringify({
          url: signed.url,
          method: signed.method,
          headers: Object.entries(headers).map(([key, value]) => ({ key, value })),
        }),
      ),
    );
  }).pipe(Effect.provide(FetchHttpClient.layer));

/**
 * Resolve a distilled operation with the host's GCP credentials, once when
 * the binding's layer is built: with the key {@link Bind} created for this
 * host if there is one, as-is otherwise (the host's own service account, or
 * the deployer).
 */
export const withCredentials: <Op>(operation: Effect.Effect<Op, never, any>) => Effect.Effect<Op> =
  Effect.fn(function* <Op>(operation: Effect.Effect<Op, never, any>) {
    // A host running as a service account signs with its own credentials.
    if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "GCP.IAM.ServiceAccount")
      return yield* operation as Effect.Effect<Op>;
    const runtime = yield* CurrentRuntimeContext;
    // A host running as an AWS IAM role federates; it never has a key.
    if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "AWS.IAM.Role") {
      const audience =
        globalThis.__ALCHEMY_RUNTIME__ && runtime !== undefined
          ? yield* runtime.get<string>(FEDERATION_ENV.audience)
          : undefined;
      if (runtime === undefined || audience === undefined) {
        return yield* operation as Effect.Effect<Op>;
      }
      const federated = fromWorkloadIdentity({
        audience,
        serviceAccountEmail: (yield* runtime.get<string>(FEDERATION_ENV.email))!,
        project: yield* runtime.get<string>(FEDERATION_ENV.project),
        subjectToken: awsSubjectToken(audience),
        subjectTokenType: "urn:ietf:params:aws:token-type:aws4_request",
      });
      const credentials = Context.get(
        yield* Layer.build(federated).pipe(Effect.scoped),
        Credentials,
      );
      return yield* (operation as Effect.Effect<Op>).pipe(
        Effect.provide(
          Layer.mergeAll(Layer.succeed(Credentials, credentials), FetchHttpClient.layer),
        ),
      );
    }
    const email =
      globalThis.__ALCHEMY_RUNTIME__ && runtime !== undefined
        ? yield* runtime.get<string>(KEY_ENV.email)
        : undefined;
    if (runtime === undefined || email === undefined) {
      return yield* operation as Effect.Effect<Op>;
    }
    const privateKey = yield* runtime.get<string | Redacted.Redacted<string>>(KEY_ENV.privateKey);
    const key = fromServiceAccountKey({
      clientEmail: email,
      project: (yield* runtime.get<string>(KEY_ENV.project))!,
      privateKeyId: (yield* runtime.get<string>(KEY_ENV.privateKeyId))!,
      privateKey: Redacted.isRedacted(privateKey) ? privateKey : Redacted.make(privateKey ?? ""),
    });
    const credentials = Context.get(yield* Layer.build(key).pipe(Effect.scoped), Credentials);
    return yield* (operation as Effect.Effect<Op>).pipe(
      Effect.provide(
        Layer.mergeAll(Layer.succeed(Credentials, credentials), FetchHttpClient.layer),
      ),
    );
  });

/**
 * Fail at deploy for a binding that needs its host to run as a service
 * account, e.g. one that reads ID tokens from the metadata server.
 */
export const requireServiceAccountHost = Effect.fn(function* (tag: string) {
  if (globalThis.__ALCHEMY_RUNTIME__) return;
  const host = yield* Binding.Host;
  if (host === undefined || runsAsServiceAccount(host)) return;
  return yield* Effect.die(
    new Error(
      `${tag} needs a host that runs as a GCP service account (Cloud Run, Cloud Functions or GKE), not ${host.Type} ${host.LogicalId}.`,
    ),
  );
});