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

import * as resourcemanager from "@distilled.cloud/gcp/cloudresourcemanager_v3";
import * as iam from "@distilled.cloud/gcp/unstable/iam_v1";
import type { ResourceBinding } from "alchemy/Resource";
import * as Config from "effect/Config";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import {
  hasIamMembership,
  projectRolesOf,
  revokeIamMembership,
  updateIamMembership,
  type GcpIamResourceKind,
  type IamCondition,
} from "./IamPolicy.ts";
import type { BoundContainer } from "./Run/Container.ts";
import { parseServiceAccountKey } from "./Token.ts";

export type { GcpIamResourceKind } from "./IamPolicy.ts";

/**
 * IAM grant a binding attaches to a GCP runtime host (Cloud Run
 * Service/Job/WorkerPool, Cloud Function, or a `Kubernetes.Deployment` /
 * `Kubernetes.Job` on GKE) — the GCP analog of an AWS binding's
 * `policyStatements`. The role is granted to the host's runtime identity:
 * the runtime service account, or on GKE the Kubernetes ServiceAccount's
 * Workload Identity Federation principal.
 */
export type GcpIamGrant = {
  /**
   * Predefined or custom role, e.g. `roles/pubsub.publisher`. Pick the
   * narrowest role that covers the binding's operation.
   */
  role: string;
  /**
   * Grant on this one resource's IAM policy (the analog of an IAM
   * statement's `Resource: [arn]`). Omit only for services with no
   * resource-level IAM, in which case the role is granted on the project.
   */
  resource?: {
    kind: Exclude<GcpIamResourceKind, "project">;
    /**
     * Full resource name, e.g. `projects/p/topics/t` (a bucket name for
     * `storage.bucket`), or {@link HOST_SERVICE_ACCOUNT} with kind
     * `iam.serviceAccount` for the host's own runtime service account.
     */
    name: string;
  };
  /**
   * For a project-level grant on a service with no per-resource IAM
   * policy: an IAM Condition narrowing the role to one resource, e.g.
   * `resource.name == "projects/p/databases/d"`.
   */
  condition?: IamCondition;
};

/**
 * Binding contract for GCP effectful hosts. Capability implementations
 * call `host.bind` with env (packed into the container/function) and IAM
 * grants (applied to the runtime service account).
 */
export type GcpHostBinding = {
  env?: Record<string, any>;
  iam?: GcpIamGrant[];
  /**
   * Cloud SQL connection names (`project:region:instance`) to mount as
   * Unix sockets under `/cloudsql` (Cloud Run services only).
   */
  cloudSqlInstances?: string[];
  /**
   * Sidecar containers to add to the host's revision (Cloud Run services
   * and containers only); see `GCP.Run.bindContainer`.
   */
  containers?: BoundContainer[];
};

/**
 * One role granted to a host's runtime service account on one resource,
 * recorded on the host's attributes so a later deploy can revoke it once
 * the binding that asked for it is gone.
 */
export type AppliedIamGrant = {
  kind: GcpIamResourceKind;
  /** Full resource name, or the project id for `project`. */
  name: string;
  role: string;
  /** IAM Condition the role is bound under, if any. */
  condition?: IamCondition;
};

/** Merge the env and IAM grants of every binding attached to a host. */
export const collectHostBindings = (
  bindings: readonly ResourceBinding<GcpHostBinding>[],
): { env: Record<string, any>; iam: GcpIamGrant[] } => ({
  env: bindings
    .map((binding) => binding.data?.env)
    .reduce<Record<string, any>>((acc, next) => ({ ...acc, ...next }), {}),
  iam: bindings.flatMap((binding) => binding.data?.iam ?? []),
});

const lastSegment = (value: string) => {
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

/**
 * Project number for the default Compute Engine service account
 * (`{number}-compute@developer.gserviceaccount.com`).
 */
export const projectNumber = (project: string) =>
  resourcemanager
    .getProjects({ name: `projects/${project}` })
    .pipe(Effect.map((resource) => lastSegment(resource.name ?? "")));

export const defaultComputeServiceAccount = (project: string) =>
  projectNumber(project).pipe(
    Effect.map((number) => `${number}-compute@developer.gserviceaccount.com`),
  );

/** 64-bit FNV-1a, hex. Deterministic and dependency-free. */
const fnv1a64 = (input: string): string => {
  let hash = 0xcbf29ce484222325n;
  for (let index = 0; index < input.length; index++) {
    hash ^= BigInt(input.charCodeAt(index));
    hash = (hash * 0x100000001b3n) & 0xffffffffffffffffn;
  }
  return hash.toString(16).padStart(16, "0");
};

/**
 * RFC1035 account id (6–30 chars) for the runtime service account Alchemy
 * mints for one physical host. The hash covers the host type and full
 * resource name, so two hosts never share an account — not across
 * stages, not a Service and a Job with the same id, and not the two
 * generations of a create-before-delete replacement.
 */
export const hostServiceAccountId = (hostType: string, resourceName: string): string => {
  const slug = lastSegment(resourceName)
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 12)
    .replace(/-+$/g, "");
  const hash = fnv1a64(`${hostType}:${resourceName}`).slice(0, 10);
  return /^[a-z]/.test(slug) ? `alch-${slug}-${hash}` : `alch-${hash}`;
};

export const hostServiceAccountEmail = (project: string, accountId: string) =>
  `${accountId}@${project}.iam.gserviceaccount.com`;

/** Display name stamped on Alchemy-minted host SAs so nuke can list them. */
export const ALCHEMY_HOST_SA_DISPLAY_NAME = "alchemy-host";

const serviceAccountName = (project: string, email: string) =>
  `projects/${project}/serviceAccounts/${email}`;

/**
 * The numeric unique ID of a host's runtime service account: the `sub` of
 * the Google ID tokens it fetches, which AWS roles trust. A just-created
 * account can read as missing for a few seconds.
 */
export const serviceAccountUniqueId = (email: string) =>
  iam.getProjectsServiceAccounts({ name: `projects/-/serviceAccounts/${email}` }).pipe(
    Effect.retry({
      while: (error) => error._tag === "NotFound",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
    Effect.map((account) => account.uniqueId),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

/**
 * Let the deploying principal and the serverless robots `actAs` the host
 * service account so Cloud Run / Functions accept it as the runtime
 * identity.
 */
const grantActAs = (project: string, email: string) =>
  Effect.gen(function* () {
    const number = yield* projectNumber(project);
    const members = [
      `serviceAccount:service-${number}@serverless-robot-prod.iam.gserviceaccount.com`,
      `serviceAccount:service-${number}@gcf-admin-robot.iam.gserviceaccount.com`,
    ];
    const keyFile = yield* Config.option(Config.String("GOOGLE_APPLICATION_CREDENTIALS"));
    if (Option.isSome(keyFile)) {
      const fs = yield* FileSystem.FileSystem;
      const raw = yield* fs
        .readFileString(keyFile.value)
        .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed("")));
      if (raw.length > 0) {
        const parsed = yield* parseServiceAccountKey(raw).pipe(
          Effect.catchTag("AuthError", () => Effect.undefined),
        );
        if (parsed?.client_email) {
          members.push(`serviceAccount:${parsed.client_email}`);
        }
      }
    }
    for (const member of members) {
      yield* updateIamMembership({
        kind: "iam.serviceAccount",
        name: serviceAccountName(project, email),
        member,
        add: ["roles/iam.serviceAccountUser"],
      });
    }
  });

/**
 * Create (or adopt) the runtime service account for one host and let
 * Cloud Run / Functions `actAs` it. `created` reports whether this call
 * minted it, so a failed first deploy can clean up only what it made.
 */
export const ensureHostServiceAccount = (options: {
  project: string;
  hostType: string;
  resourceName: string;
  /** Let Cloud Run / Functions run as the account. @default true */
  actAs?: boolean;
}) => {
  const accountId = hostServiceAccountId(options.hostType, options.resourceName);
  const email = hostServiceAccountEmail(options.project, accountId);
  return Effect.gen(function* () {
    const existing = yield* iam
      .getProjectsServiceAccounts({
        name: serviceAccountName(options.project, email),
      })
      .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
    let created = false;
    if (existing?.email === undefined || existing.email.length === 0) {
      created = yield* iam
        .createProjectsServiceAccounts({
          name: `projects/${options.project}`,
          body: {
            accountId,
            serviceAccount: { displayName: ALCHEMY_HOST_SA_DISPLAY_NAME },
          },
        })
        .pipe(
          Effect.as(true),
          Effect.retry({
            while: (error) => error._tag === "ServiceAccountQuotaExceeded",
            times: 6,
            schedule: Schedule.exponential("2 seconds"),
          }),
          Effect.catchTag("Conflict", () => Effect.succeed(false)),
        );
    }
    if (options.actAs !== false) {
      yield* grantActAs(options.project, email);
    }
    return { email, created };
  });
};

/** Retry Cloud Run / Functions create while IAM `actAs` is propagating. */
export const retryActAs = <A, E extends { _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
  effect.pipe(
    Effect.retry({
      while: (error) => error._tag === "Forbidden",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

const conditionKey = (condition: IamCondition | undefined) =>
  condition === undefined ? "" : `${condition.title ?? ""}\u0001${condition.expression ?? ""}`;

const grantKey = (grant: AppliedIamGrant) =>
  `${grant.kind}\u0000${grant.name}\u0000${grant.role}\u0000${conditionKey(grant.condition)}`;

const groupByTarget = (grants: readonly AppliedIamGrant[]) => {
  const groups = new Map<
    string,
    {
      kind: GcpIamResourceKind;
      name: string;
      condition: IamCondition | undefined;
      roles: Set<string>;
    }
  >();
  for (const grant of grants) {
    const key = `${grant.kind}\u0000${grant.name}\u0000${conditionKey(grant.condition)}`;
    const group = groups.get(key) ?? {
      kind: grant.kind,
      name: grant.name,
      condition: grant.condition,
      roles: new Set<string>(),
    };
    group.roles.add(grant.role);
    groups.set(key, group);
  }
  return [...groups.values()];
};

/**
 * Placeholder resource name (kind `iam.serviceAccount`) for the host's
 * own runtime service account, e.g. to let it sign blobs as itself.
 * Resolved when the host syncs IAM; dropped for hosts whose identity is
 * not a service account (GKE Workload Identity principals).
 */
export const HOST_SERVICE_ACCOUNT = "@host";

/** Desired grants for a host, deduplicated and resolved to concrete targets. */
export const desiredHostGrants = (
  project: string,
  grants: readonly GcpIamGrant[],
  serviceAccount?: string,
): AppliedIamGrant[] => {
  const ownAccount =
    serviceAccount !== undefined && !serviceAccount.includes(":")
      ? `projects/-/serviceAccounts/${serviceAccount}`
      : undefined;
  const unique = new Map<string, AppliedIamGrant>();
  for (const grant of grants) {
    if (grant.role.length === 0) continue;
    const self = grant.resource?.name === HOST_SERVICE_ACCOUNT;
    if (self && ownAccount === undefined) continue;
    const applied: AppliedIamGrant =
      grant.resource === undefined
        ? {
            kind: "project",
            name: project,
            role: grant.role,
            ...(grant.condition ? { condition: grant.condition } : {}),
          }
        : {
            kind: grant.resource.kind,
            name: self ? ownAccount! : grant.resource.name,
            role: grant.role,
          };
    unique.set(grantKey(applied), applied);
  }
  return [...unique.values()].sort((left, right) => grantKey(left).localeCompare(grantKey(right)));
};

/**
 * Converge the runtime service account's IAM onto the host's bindings.
 *
 * Every desired grant is added on its target resource. Grants recorded
 * on a previous deploy that no binding asks for any more are revoked.
 * For an Alchemy-minted account, the host project policy is additionally
 * synced against the observed policy, so roles granted out of band (or
 * lost from state) are revoked too; a user-supplied account is only ever
 * stripped of grants Alchemy itself recorded.
 */
export const syncHostIam = Effect.fn(function* (options: {
  project: string;
  serviceAccount: string;
  managed: boolean;
  bindings: readonly ResourceBinding<GcpHostBinding>[];
  previous: readonly AppliedIamGrant[] | undefined;
}) {
  const collected = collectHostBindings(options.bindings);
  const desired = desiredHostGrants(options.project, collected.iam, options.serviceAccount);
  const desiredKeys = new Set(desired.map(grantKey));
  const stale = (options.previous ?? []).filter((grant) => !desiredKeys.has(grantKey(grant)));

  // A principal Alchemy doesn't own (user-supplied service account, GKE
  // Workload Identity principal) may already hold a role for other
  // reasons. Such a grant is used but never recorded as ours, so a later
  // deploy or destroy never revokes it.
  const previousKeys = new Set((options.previous ?? []).map(grantKey));
  const preexisting = new Set<string>();
  if (!options.managed) {
    for (const grant of desired) {
      if (previousKeys.has(grantKey(grant)) || grant.condition !== undefined) {
        continue;
      }
      const held = yield* hasIamMembership({
        kind: grant.kind,
        name: grant.name,
        member: options.serviceAccount,
        role: grant.role,
      });
      if (held) preexisting.add(grantKey(grant));
    }
  }

  for (const group of groupByTarget(desired)) {
    yield* updateIamMembership({
      kind: group.kind,
      name: group.name,
      member: options.serviceAccount,
      add: group.roles,
      condition: group.condition,
    });
  }

  // Unconditional project grants of a minted account are synced against
  // the observed policy below; conditional ones only via the record.
  const isHostProject = (grant: { kind: string; name: string; condition?: IamCondition }) =>
    grant.kind === "project" && grant.name === options.project && grant.condition === undefined;

  if (options.managed) {
    const wanted = new Set(desired.filter(isHostProject).map((grant) => grant.role));
    const held = yield* projectRolesOf(options.project, options.serviceAccount);
    const extra = held.filter((role) => !wanted.has(role));
    if (extra.length > 0) {
      yield* revokeIamMembership({
        kind: "project",
        name: options.project,
        member: options.serviceAccount,
        roles: extra,
      });
    }
  }

  for (const group of groupByTarget(stale)) {
    if (options.managed && isHostProject(group)) continue;
    yield* revokeIamMembership({
      kind: group.kind,
      name: group.name,
      member: options.serviceAccount,
      roles: group.roles,
      condition: group.condition,
    });
  }

  return {
    env: collected.env,
    grants: desired.filter((grant) => !preexisting.has(grantKey(grant))),
  };
});

/** Revoke every recorded grant from the host's runtime service account. */
export const revokeHostIam = Effect.fn(function* (options: {
  serviceAccount: string;
  grants: readonly AppliedIamGrant[];
}) {
  for (const group of groupByTarget(options.grants)) {
    yield* revokeIamMembership({
      kind: group.kind,
      name: group.name,
      member: options.serviceAccount,
      roles: group.roles,
      condition: group.condition,
    });
  }
});

/**
 * Delete an Alchemy-minted host service account (no-op if it is already
 * gone) after revoking its project roles and every recorded grant, so no
 * `deleted:serviceAccount:` members linger on other resources.
 */
export const deleteHostServiceAccount = Effect.fn(function* (options: {
  project: string;
  email: string;
  grants?: readonly AppliedIamGrant[];
}) {
  yield* revokeHostIam({
    serviceAccount: options.email,
    grants: options.grants ?? [],
  });
  const held = yield* projectRolesOf(options.project, options.email);
  if (held.length > 0) {
    yield* revokeIamMembership({
      kind: "project",
      name: options.project,
      member: options.email,
      roles: held,
    });
  }
  const name = serviceAccountName(options.project, options.email);
  yield* iam
    .deleteProjectsServiceAccounts({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.void));
  // Block until IAM stops serving the account.
  yield* iam.getProjectsServiceAccounts({ name }).pipe(
    Effect.flatMap(() => Effect.fail(new HostServiceAccountStillExists({ email: options.email }))),
    Effect.catchTag("NotFound", () => Effect.void),
    Effect.retry({
      while: (error) => error._tag === "GCP.HostServiceAccountStillExists",
      times: 30,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );
});

export class HostServiceAccountStillExists extends Data.TaggedError(
  "GCP.HostServiceAccountStillExists",
)<{ email: string }> {}