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

import * as iam from "@distilled.cloud/gcp/unstable/iam_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import { revokeHostIam, syncHostIam, type AppliedIamGrant, type GcpIamGrant } from "../Host.ts";
import { createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import { encodeOwnedDescription, hasOwnedDescription, parseOwnedDescription } from "./internal.ts";

const ACCOUNT_ID_MAX = 30;

export type ServiceAccountProps = {
  /** Project that owns the account. Defaults to the current GCP project. */
  project?: string;
  /**
   * Account id used as the email prefix: 6-30 lowercase letters, digits,
   * or hyphens. If omitted, a unique id is generated. Changing it
   * replaces the account.
   */
  accountId?: string;
  /** Human-readable display name (maximum 100 UTF-8 bytes). */
  displayName?: string;
  /**
   * Human-readable description. Service accounts have no labels, so
   * Alchemy stamps ownership into a `[alchemy …]` prefix and strips it
   * from the `description` attribute. The marker and this text share the
   * API's 256-byte limit; overflow is truncated.
   */
  description?: string;
};

export type ServiceAccount = Resource<
  "GCP.IAM.ServiceAccount",
  ServiceAccountProps,
  {
    /** Full resource name `projects/{project}/serviceAccounts/{email}`. */
    name: string;
    /** Project that owns the account. */
    project: string;
    /** Account id (the email prefix). */
    accountId: string;
    /** Service-account email address. */
    email: string;
    /** Globally unique numeric id. */
    uniqueId: string | undefined;
    /** OAuth 2 client id. */
    oauth2ClientId: string | undefined;
    /** Human-readable display name. */
    displayName: string | undefined;
    /** User description (Alchemy ownership marker stripped). */
    description: string | undefined;
    /** Whether the account is disabled. */
    disabled: boolean | undefined;
    /** Roles granted through bindings, revoked once no binding asks for them. */
    iamGrants?: AppliedIamGrant[];
  },
  ServiceAccountBinding,
  Providers
>;

/** What a binding grants a {@link ServiceAccount}. */
export type ServiceAccountBinding = {
  /** Roles to grant the account, each on one resource (or the project). */
  iam?: GcpIamGrant[];
};

/**
 * A user-managed Google Cloud IAM service account.
 *
 * Grant it roles with `GCP.IAM.Member` (`kind: "project"` for project-wide
 * roles), and pass its `email` to resources that run as an identity, such
 * as GKE node pools or Compute instances.
 *
 * ### Creating a Service Account
 * **Example:** Service account with a generated id
 * ```typescript
 * const account = yield* GCP.IAM.ServiceAccount("Worker", {
 *   displayName: "Background worker",
 * });
 * ```
 *
 * **Example:** Service account with an explicit id
 * ```typescript
 * const account = yield* GCP.IAM.ServiceAccount("GkeNodes", {
 *   accountId: "prod-gke-nodes",
 *   displayName: "Production GKE nodes",
 * });
 * ```
 *
 * ### Granting Roles
 * **Example:** Let the account write logs in the project
 * ```typescript
 * const account = yield* GCP.IAM.ServiceAccount("Worker", {});
 * yield* GCP.IAM.Member("WorkerLogs", {
 *   kind: "project",
 *   name: account.project,
 *   role: "roles/logging.logWriter",
 *   member: Output.interpolate`serviceAccount:${account.email}`,
 * });
 * ```
 *
 * @resource
 * @category IAM
 */
export const ServiceAccount = Resource<ServiceAccount>("GCP.IAM.ServiceAccount");

export class ServiceAccountNotResolved extends Data.TaggedError(
  "GCP.IAM.ServiceAccountNotResolved",
)<{ resourceName: string }> {}

const accountIdFromEmail = (email: string) => email.split("@")[0] ?? email;
const emailOf = (project: string, accountId: string) =>
  `${accountId}@${project}.iam.gserviceaccount.com`;
const nameOf = (project: string, accountId: string) =>
  `projects/${project}/serviceAccounts/${emailOf(project, accountId)}`;

const toAttrs = (account: iam.ServiceAccount, project: string): ServiceAccount["Attributes"] => {
  const email = account.email ?? "";
  const accountId = accountIdFromEmail(email);
  return {
    name: account.name ?? nameOf(project, accountId),
    project: account.projectId ?? project,
    accountId,
    email,
    uniqueId: account.uniqueId,
    oauth2ClientId: account.oauth2ClientId,
    displayName: account.displayName,
    description: parseOwnedDescription(account.description).description,
    disabled: account.disabled,
  };
};

const getByName = (name: string) =>
  iam
    .getProjectsServiceAccounts({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const toAccountId = (id: string, explicit: string | undefined, existing: string | undefined) =>
  Effect.gen(function* () {
    if (explicit !== undefined) return explicit;
    if (existing !== undefined) return existing;
    return yield* createPhysicalName({
      id,
      prefix: `alchemy-${id}-`,
      maxLength: ACCOUNT_ID_MAX,
      lowercase: true,
    });
  });

export const ServiceAccountProvider = () =>
  Provider.succeed(ServiceAccount, {
    stables: ["name", "project", "accountId", "email", "uniqueId"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;
      const previousProject = olds?.project ?? output?.project ?? env.project;
      const previousAccountId = olds?.accountId ?? output?.accountId;
      if (
        (news.project !== undefined && news.project !== previousProject) ||
        (news.accountId !== undefined && news.accountId !== previousAccountId)
      ) {
        return { action: "replace" as const, deleteFirst: false };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const project = olds?.project ?? output?.project ?? env.project;
      const accountId = yield* toAccountId(id, olds?.accountId, output?.accountId);
      const existing = yield* getByName(output?.name ?? nameOf(project, accountId));
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, project);
      const { labels } = parseOwnedDescription(existing.description);
      return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* iam.listProjectsServiceAccounts
          .pages({
            name: `projects/${env.project}`,
            pageSize: 100,
          })
          .pipe(
            Stream.flatMap((page) => Stream.fromIterable(page.accounts ?? [])),
            Stream.filter((account) => hasOwnedDescription(account.description)),
            Stream.map((account) => toAttrs(account, env.project)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag("NotFound", () => Effect.succeed([] as ServiceAccount["Attributes"][])),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, output, bindings }) {
      const env = yield* GcpEnvironment.current;
      const project = news.project ?? output?.project ?? env.project;
      const accountId = yield* toAccountId(id, news.accountId, output?.accountId);
      const name = output?.name ?? nameOf(project, accountId);
      const internal = yield* createInternalLabels(id);
      const desiredDescription = encodeOwnedDescription(internal, news.description);

      // Observe
      let current = yield* getByName(name);

      // Ensure — `Conflict` is a create race; adopt the winner.
      if (current === undefined) {
        current = yield* iam
          .createProjectsServiceAccounts({
            name: `projects/${project}`,
            body: {
              accountId,
              serviceAccount: {
                displayName: news.displayName,
                description: desiredDescription,
              },
            },
          })
          .pipe(
            Effect.retry({
              while: (error) => error._tag === "ServiceAccountQuotaExceeded",
              times: 6,
              schedule: Schedule.exponential("2 seconds"),
            }),
            Effect.catchTag("Conflict", () => getByName(name)),
          );
      }
      if (current === undefined) {
        return yield* new ServiceAccountNotResolved({ resourceName: name });
      }
      // A new account is eventually consistent: reads (and IAM bindings that
      // name it) fail with NotFound for a few seconds after create.
      current = yield* getByName(current.name ?? name).pipe(
        Effect.flatMap((account) =>
          account === undefined
            ? Effect.fail(new ServiceAccountNotResolved({ resourceName: name }))
            : Effect.succeed(account),
        ),
        Effect.retry({
          while: (error) => error._tag === "GCP.IAM.ServiceAccountNotResolved",
          schedule: Schedule.exponential("500 millis"),
          times: 8,
        }),
      );

      // Sync display name and description against observed state.
      const updateMask = [
        (current.displayName ?? "") !== (news.displayName ?? "") ? "displayName" : undefined,
        (current.description ?? "") !== desiredDescription ? "description" : undefined,
      ].filter((field): field is string => field !== undefined);
      if (updateMask.length > 0) {
        const patched = yield* iam.patchProjectsServiceAccounts({
          name: current.name ?? name,
          body: {
            updateMask: updateMask.join(","),
            serviceAccount: {
              displayName: news.displayName ?? "",
              description: desiredDescription,
            },
          },
        });
        // The patch response only echoes the masked fields, and a re-read can
        // still return the previous values, so the patched fields win.
        current = {
          ...current,
          displayName: patched.displayName ?? news.displayName,
          description: patched.description ?? desiredDescription,
        };
      }

      // Sync the roles bindings grant the account. Roles it holds for other
      // reasons (e.g. a `GCP.IAM.Member`) are used but never revoked.
      const attrs = toAttrs(current, project);
      if (bindings.length === 0 && (output?.iamGrants ?? []).length === 0) return attrs;
      const { grants } = yield* syncHostIam({
        project: attrs.project,
        serviceAccount: attrs.email,
        managed: false,
        bindings,
        previous: output?.iamGrants,
      });
      return { ...attrs, iamGrants: grants };
    }),

    delete: Effect.fn(function* ({ output }) {
      // Revoke first, so no `deleted:serviceAccount:` members linger.
      yield* revokeHostIam({ serviceAccount: output.email, grants: output.iamGrants ?? [] });
      yield* iam
        .deleteProjectsServiceAccounts({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });