sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ AWSBindings.ts

import { createHash } from "node:crypto";
import { fromWebToken, type ResolvedCredentials } from "@distilled.cloud/aws/Credentials";
import * as Endpoint from "@distilled.cloud/aws/Endpoint";
import { Region, type RegionName } from "@distilled.cloud/aws/Region";
import { AlchemyContext } from "alchemy/AlchemyContext";
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 { Stack } from "alchemy/Stack";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import type * as rolldown from "rolldown";
import { DEFAULT_LOCAL_ENDPOINT } from "./AuthProvider.ts";
import { Credentials, makeAssumeRoleResolver } from "./Credentials.ts";
import { AWSEnvironment } from "./Environment.ts";
import { AccessKey } from "./IAM/AccessKey.ts";
import type { PolicyStatement } from "./IAM/Policy.ts";
import { Role } from "./IAM/Role.ts";
import { User } from "./IAM/User.ts";
import { CurrentRegion } from "./Region.ts";

/**
 * How an AWS binding reaches AWS from its host:
 *
 * - the host runs as an IAM role (Lambda, ECS, EC2, …): statements go on that
 *   role, and calls use its ambient credentials;
 * - the host runs as a Google service account (Cloud Run, Cloud Functions):
 *   Alchemy creates a Role that trusts that account's Google ID tokens, puts
 *   the statements on the Role, and the host assumes it with
 *   `AssumeRoleWithWebIdentity`. No key is created;
 * - any other host (a Cloudflare Worker, Cloud Run, a GKE pod): Alchemy
 *   creates an IAM User and AccessKey that may assume a Role, puts the
 *   statements on the Role, 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 sendMessage = yield* AWSBindings.withCredentials(sqs.sendMessage);
 *   const bind = yield* AWSBindings.Bind;
 *   return Effect.fn(function* (queue: Queue) {
 *     if (!globalThis.__ALCHEMY_RUNTIME__) {
 *       yield* bind`AWS.SQS.SendMessage(${queue})`({
 *         policyStatements: [
 *           { Effect: "Allow", Action: ["sqs:SendMessage"], Resource: [queue.queueArn] },
 *         ],
 *       });
 *     }
 *     return (request) => sendMessage({ ...request, QueueUrl: … });
 *   });
 * })
 * ```
 */

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

/** The VPC a host must attach to, e.g. to reach a VPC-only database. */
export interface HostVpc {
  readonly subnetIds: Input<string[]>;
  readonly securityGroupIds: Input<string[]>;
}

/**
 * Build options for a bundle that runs on a host running as an IAM role (Lambda, ECS, EC2, AppRunner, Batch, EKS): defines
 * `__ALCHEMY_HOST_IDENTITY__` as `"AWS.IAM.Role"` so the bundler drops the created-key credentials path.
 */
export const roleHostBundle = (input: rolldown.InputOptions): rolldown.InputOptions => ({
  ...input,
  transform: {
    ...input.transform,
    define: {
      ...input.transform?.define,
      "globalThis.__ALCHEMY_HOST_IDENTITY__": JSON.stringify("AWS.IAM.Role"),
    },
  },
});

/**
 * Env vars holding the key Alchemy creates for a host that doesn't run as an
 * IAM role. Only {@link Bind} sets them, and only on that path, so at
 * runtime their presence is the whole decision.
 */
const KEY_ENV = {
  accessKeyId: "ALCHEMY_AWS_ACCESS_KEY_ID",
  secretAccessKey: "ALCHEMY_AWS_SECRET_ACCESS_KEY",
  roleArn: "ALCHEMY_AWS_ROLE_ARN",
  region: "ALCHEMY_AWS_REGION",
} as const;

/**
 * Env var holding the Role a Google-service-account host assumes with its
 * ID token. Only {@link Bind} sets it, on that path only.
 */
const WEB_IDENTITY_ROLE_ENV = "ALCHEMY_AWS_WEB_IDENTITY_ROLE_ARN";

/** The `aud` a host requests on the Google ID tokens it exchanges with STS. */
const GOOGLE_ID_TOKEN_AUDIENCE = "sts.amazonaws.com";

/**
 * Whether a host runs its code as an IAM role: Lambda, ECS, EC2,
 * AutoScaling, AppRunner, Batch, or a Kubernetes workload on an EKS cluster
 * (Pod Identity). Not a Lambda `MicrovmImage`: an image has no role of its
 * own (`RunMicrovm` takes one per launch). Deploy-time only: it reads the
 * host's props.
 */
export const runsAsRole = (host: ResourceLike): boolean => {
  switch (host.Type) {
    case "AWS.Lambda.Function":
    case "AWS.Lambda.WebFunction":
    case "AWS.ECS.Task":
    case "AWS.ECS.Service":
    case "AWS.EC2.Instance":
    case "AWS.AutoScaling.LaunchTemplate":
    case "AWS.AppRunner.Service":
    case "AWS.Batch.JobDefinition":
      return true;
    case "Kubernetes.Deployment":
    case "Kubernetes.Job":
      return isEksCluster(host.Props?.cluster);
    default:
      return false;
  }
};

/**
 * Whether a host runs its code as a Google service account that can fetch ID
 * tokens from the metadata server: Cloud Run and Cloud Functions. Not a GKE
 * pod: its Workload Identity principal has no ID tokens. Deploy-time only.
 *
 * TODO: don't hard-code GCP host types in the AWS package. The GCP package
 * owns them (and their `serviceAccountUniqueId`); find a way for it to
 * provide this, e.g. as a Layer the AWS binding reads at deploy time.
 */
export const runsAsGoogleServiceAccount = (host: ResourceLike): boolean => {
  switch (host.Type) {
    case "GCP.Run.Service":
    case "GCP.Run.Job":
    case "GCP.Run.WorkerPool":
    case "GCP.CloudFunctions.Function":
      return true;
    default:
      return false;
  }
};

/**
 * The name of the Role a Google-service-account host assumes:
 * `{stack}-{host}-{stage}-` plus a hash of the host's FQN, at most 64
 * characters. Derived from the host alone so the host's env can name the
 * Role without depending on it.
 */
const federatedRoleName = Effect.fn(function* (host: ResourceLike) {
  const stack = yield* Effect.serviceOption(Stack);
  const prefix = Option.isSome(stack)
    ? `${stack.value.name}-${host.LogicalId}-${stack.value.stage}-`
    : `${host.LogicalId}-`;
  const hash = yield* Effect.sync(() =>
    createHash("sha256").update(host.FQN).digest("hex").slice(0, 12),
  );
  return `${prefix.replaceAll(/[^a-zA-Z0-9-]/g, "-").slice(0, 64 - hash.length)}${hash}`;
});

/** An `AWS.EKS.Cluster`, or a cluster connection authenticating as `aws-eks`. */
const isEksCluster = (cluster: unknown): boolean => {
  if (isResourceOfType(cluster, "AWS.EKS.Cluster")) return true;
  const value = cluster as { auth?: { kind?: string }; connection?: { auth?: { kind?: string } } };
  return value?.auth?.kind === "aws-eks" || value?.connection?.auth?.kind === "aws-eks";
};

/** Label a binding `<verb>(<host>, <label>)`, as `host.bind` records it. */
const labelled = (verb: string, label: TemplateStringsArray): TemplateStringsArray => {
  const strings = [`${verb}(`, `, ${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>;
};

const toOutput = (value: unknown) => (Output.isOutput(value) ? value : Output.literal(value));

/**
 * 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 an IAM role takes the statements on that role;
 * - a host that runs as a Google service account gets a Role that trusts
 *   its ID tokens; the Role takes the statements;
 * - any other host gets an IAM User and AccessKey that may assume a Role;
 *   the Role takes the statements and the key is bound into the host's env.
 *
 * ```ts
 * Effect.gen(function* () {
 *   const bind = yield* AWSBindings.Bind;
 *   return Effect.fn(function* (queue: Queue) {
 *     if (!globalThis.__ALCHEMY_RUNTIME__) {
 *       yield* bind`AWS.SQS.SendMessage(${queue})`({ policyStatements: [ … ] });
 *     }
 *   });
 * })
 * ```
 */
/** 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 IamUser = yield* User;
  const IamAccessKey = yield* AccessKey;
  const IamRole = yield* Role;

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

      if (runsAsRole(host)) {
        return yield* (host as unknown as BindTarget).bind(
          labelled("Allow", label),
          host,
          ...args,
        )(data);
      }

      const id = host.LogicalId;
      const runtime = (yield* CurrentRuntimeContext)!;

      if (runsAsGoogleServiceAccount(host)) {
        // The host's env names the Role by a name derived from the host, not
        // by the Role's output: the Role's trust reads the host's service
        // account, so an env reference back to the Role would be a cycle.
        const roleName = yield* federatedRoleName(host);
        const uniqueId = (host as unknown as { serviceAccountUniqueId: Output.Output<string> })
          .serviceAccountUniqueId;
        const role = yield* IamRole(`${id}Role`, {
          roleName,
          assumeRolePolicyDocument: {
            Version: "2012-10-17",
            Statement: [
              {
                Effect: "Allow",
                Principal: { Federated: "accounts.google.com" },
                Action: ["sts:AssumeRoleWithWebIdentity"],
                Condition: {
                  StringEquals: {
                    // Google ID tokens carry the account's unique ID as
                    // `sub` and `azp`; IAM reads `azp` as `aud` and the
                    // requested audience as `oaud`.
                    "accounts.google.com:sub": uniqueId,
                    "accounts.google.com:aud": uniqueId,
                    "accounts.google.com:oaud": GOOGLE_ID_TOKEN_AUDIENCE,
                  },
                },
              },
            ],
          },
        });
        if (data.policyStatements !== undefined && data.policyStatements.length > 0) {
          yield* (role as unknown as BindTarget).bind(
            labelled("Allow", label),
            host,
            ...args,
          )({ policyStatements: data.policyStatements });
        }
        yield* runtime.set(
          WEB_IDENTITY_ROLE_ENV,
          Output.fromEffect(
            AWSEnvironment.use((env) =>
              Effect.map(env, ({ accountId }) => `arn:aws:iam::${accountId}:role/${roleName}`),
            ).pipe(Effect.orDie),
          ) as Output.Output<string>,
        );
        yield* runtime.set(
          KEY_ENV.region,
          Output.fromEffect(CurrentRegion.pipe(Effect.orDie)) as Output.Output<string>,
        );
        for (const [key, value] of Object.entries(data.env ?? {})) {
          yield* runtime.set(key, toOutput(value));
        }
        return;
      }

      // The user may assume any role that trusts it; the role's trust policy
      // restricts assumption to this user, which avoids a User↔Role ARN cycle.
      const user = yield* IamUser(`${id}User`, {
        inlinePolicies: {
          AssumeRole: {
            Version: "2012-10-17",
            Statement: [{ Effect: "Allow", Action: ["sts:AssumeRole"], Resource: ["*"] }],
          },
        },
      });
      const accessKey = yield* IamAccessKey(`${id}AccessKey`, { userName: user.userName });
      const role = yield* IamRole(`${id}Role`, {
        assumeRolePolicyDocument: {
          Version: "2012-10-17",
          Statement: [
            { Effect: "Allow", Principal: { AWS: user.userArn }, Action: ["sts:AssumeRole"] },
          ],
        },
      });
      if (data.policyStatements !== undefined && data.policyStatements.length > 0) {
        yield* (role as unknown as BindTarget).bind(
          labelled("Allow", label),
          host,
          ...args,
        )({ policyStatements: data.policyStatements });
      }

      yield* runtime.set(KEY_ENV.accessKeyId, accessKey.accessKeyId);
      yield* runtime.set(KEY_ENV.secretAccessKey, accessKey.secretAccessKey);
      yield* runtime.set(KEY_ENV.roleArn, role.roleArn);
      yield* runtime.set(
        KEY_ENV.region,
        Output.fromEffect(CurrentRegion.pipe(Effect.orDie)) as Output.Output<string>,
      );
      // Local dev: STS and the bound operations run on the emulator, reached
      // via the same `AWS_ENDPOINT_URL` the emulator injects into Lambdas.
      const context = yield* Effect.serviceOption(AlchemyContext);
      if (Option.isSome(context) && context.value.dev) {
        yield* runtime.set("AWS_ENDPOINT_URL", Output.literal(DEFAULT_LOCAL_ENDPOINT));
      }
      for (const [key, value] of Object.entries(data.env ?? {})) {
        yield* runtime.set(key, toOutput(value));
      }
    });
});

/**
 * Attach the host to a VPC, labelled `Vpc(<host>, <label>)`. Only a host that
 * runs as an IAM role has a VPC to attach; any other host reaches AWS over
 * the internet, so this skips it. Call it behind a literal
 * `if (!globalThis.__ALCHEMY_RUNTIME__)`.
 */
export const bindVpc = (label: TemplateStringsArray, ...args: unknown[]) =>
  Effect.fn(function* (vpc: HostVpc) {
    const host = yield* Binding.Host;
    if (host === undefined || !runsAsRole(host)) return;
    yield* (host as unknown as BindTarget).bind(labelled("Vpc", label), host, ...args)({ vpc });
  });

/**
 * A Google ID token for {@link GOOGLE_ID_TOKEN_AUDIENCE}, fetched from the
 * metadata server as the host's runtime service account. Tokens live an
 * hour; a fresh one is fetched on every credential refresh.
 */
const googleIdToken = Effect.gen(function* () {
  const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
  const response = yield* client.execute(
    HttpClientRequest.get(
      "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity",
    ).pipe(
      HttpClientRequest.setHeader("Metadata-Flavor", "Google"),
      HttpClientRequest.setUrlParams({ audience: GOOGLE_ID_TOKEN_AUDIENCE, format: "full" }),
    ),
  );
  return Redacted.make((yield* response.text).trim());
}).pipe(Effect.provide(FetchHttpClient.layer));

/**
 * Resolve an operation on a host that runs as a Google service account: the
 * Role {@link Bind} created for it is assumed with the host's Google ID token
 * (`AssumeRoleWithWebIdentity`). Credentials are cached and re-assumed with a
 * fresh token shortly before they expire.
 */
const withWebIdentity = Effect.fn(function* <Op>(
  operation: Effect.Effect<Op, never, any>,
  region?: Effect.Effect<Effect.Effect<string>, never, any>,
) {
  const runtime = yield* CurrentRuntimeContext;
  const roleArn = runtime ? yield* runtime.get<string>(WEB_IDENTITY_ROLE_ENV) : undefined;
  if (runtime === undefined || roleArn === undefined) {
    return yield* operation as Effect.Effect<Op>;
  }
  const credentials = fromWebToken({
    roleArn,
    webIdentityToken: googleIdToken,
    roleSessionName: "alchemy",
    // STS is global; operations provide their own Region.
    region: "us-east-1",
  });
  const callRegion =
    region !== undefined
      ? yield* region as Effect.Effect<Effect.Effect<string>>
      : Effect.map(runtime.get<string>(KEY_ENV.region), (value) => value ?? "us-east-1");
  return yield* (operation as Effect.Effect<Op>).pipe(
    Effect.provide([
      credentials,
      Layer.succeed(Region, callRegion as Effect.Effect<RegionName>),
      Endpoint.fromEnv(),
      FetchHttpClient.layer,
    ]),
  );
});

/**
 * Resolve a distilled operation (or several, with `Effect.all`) with the
 * host's AWS credentials, once when the binding's layer is built: by
 * assuming the Role {@link Bind} created for this host if there is one,
 * as-is otherwise (the host's own role, or the deployer).
 *
 * @param region the region a host with a created key signs in, e.g. a
 *   bucket's own. Its outer Effect may read resource attributes onto the
 *   host, so it also runs at deploy for those hosts.
 *   @default the stack's region
 */
export const withCredentials: <Op>(
  operation: Effect.Effect<Op, never, any>,
  region?: Effect.Effect<Effect.Effect<string>, never, any>,
) => Effect.Effect<Op> = Effect.fn(function* <Op>(
  operation: Effect.Effect<Op, never, any>,
  region?: Effect.Effect<Effect.Effect<string>, never, any>,
) {
  // A host running as an IAM role signs with its own credentials.
  if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "AWS.IAM.Role")
    return yield* operation as Effect.Effect<Op>;
  // A host running as a Google service account assumes its Role with an ID
  // token; it never has a key, so the bundler drops that path.
  if (globalThis.__ALCHEMY_HOST_IDENTITY__ === "GCP.IAM.ServiceAccount") {
    return yield* withWebIdentity(operation, region);
  }
  if (!globalThis.__ALCHEMY_RUNTIME__) {
    const host = yield* Binding.Host;
    if (region !== undefined && host !== undefined && !runsAsRole(host)) {
      // Only the outer Effect: it binds attributes onto the host at deploy.
      yield* Effect.asVoid(region as Effect.Effect<Effect.Effect<string>>);
    }
    return yield* operation as Effect.Effect<Op>;
  }

  const runtime = yield* CurrentRuntimeContext;
  const roleArn = runtime ? yield* runtime.get<string>(KEY_ENV.roleArn) : undefined;
  if (runtime === undefined || roleArn === undefined) {
    return yield* operation as Effect.Effect<Op>;
  }

  // The created user's key signs `AssumeRole`; read on each refresh.
  const base = Layer.succeed(
    Credentials,
    Effect.gen(function* () {
      const secret = yield* runtime.get<string | Redacted.Redacted<string>>(
        KEY_ENV.secretAccessKey,
      );
      return {
        accessKeyId: Redacted.make((yield* runtime.get<string>(KEY_ENV.accessKeyId)) ?? ""),
        secretAccessKey: Redacted.isRedacted(secret) ? secret : Redacted.make(secret ?? ""),
        sessionToken: undefined,
        // STS is global; operations provide their own Region.
        region: "us-east-1",
      } satisfies ResolvedCredentials;
    }),
  );
  const credentials = yield* makeAssumeRoleResolver({
    roleArn: Effect.succeed(roleArn),
    base,
    region: "us-east-1",
  });
  const callRegion =
    region !== undefined
      ? yield* region as Effect.Effect<Effect.Effect<string>>
      : Effect.map(runtime.get<string>(KEY_ENV.region), (value) => value ?? "us-east-1");
  return yield* (operation as Effect.Effect<Op>).pipe(
    Effect.provide([
      Layer.succeed(Credentials, credentials),
      Layer.succeed(Region, callRegion as Effect.Effect<RegionName>),
      Endpoint.fromEnv(),
      FetchHttpClient.layer,
    ]),
  );
});