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

import * as artifactregistry from "@distilled.cloud/gcp/artifactregistry_v1";
import * as bigquery from "@distilled.cloud/gcp/bigquery_v2";
import * as bigqueryconnection from "@distilled.cloud/gcp/bigqueryconnection_v1";
import * as bigtableadmin from "@distilled.cloud/gcp/bigtableadmin_v2";
import * as binaryauthorization from "@distilled.cloud/gcp/binaryauthorization_v1";
import * as cloudfunctions from "@distilled.cloud/gcp/cloudfunctions_v2";
import * as kms from "@distilled.cloud/gcp/cloudkms_v1";
import * as resourcemanager from "@distilled.cloud/gcp/cloudresourcemanager_v3";
import * as cloudtasks from "@distilled.cloud/gcp/cloudtasks_v2";
import * as compute from "@distilled.cloud/gcp/compute_v1";
import * as containeranalysis from "@distilled.cloud/gcp/containeranalysis_v1";
import * as dataproc from "@distilled.cloud/gcp/dataproc_v1";
import * as ml from "@distilled.cloud/gcp/ml_v1";
import * as privateca from "@distilled.cloud/gcp/privateca_v1";
import type { GcpOpContext } from "@distilled.cloud/gcp/Protocol";
import * as pubsub from "@distilled.cloud/gcp/pubsub_v1";
import * as run from "@distilled.cloud/gcp/run_v2";
import * as secretmanager from "@distilled.cloud/gcp/secretmanager_v1";
import * as servicedirectory from "@distilled.cloud/gcp/servicedirectory_v1";
import * as spanner from "@distilled.cloud/gcp/spanner_v1";
import * as storage from "@distilled.cloud/gcp/storage_v1";
import * as iam from "@distilled.cloud/gcp/unstable/iam_v1";
import * as workstations from "@distilled.cloud/gcp/workstations_v1";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";

/**
 * The subset of a Google IAM `Policy` Alchemy reads and writes. Every
 * service's generated `Policy` type is structurally compatible.
 */
export interface IamPolicy {
  version?: number;
  etag?: string;
  bindings?: ReadonlyArray<IamPolicyBinding>;
  auditConfigs?: ReadonlyArray<unknown>;
}

export interface IamPolicyBinding {
  role?: string;
  members?: ReadonlyArray<string>;
  condition?: IamCondition;
}

/**
 * An IAM Condition (CEL). Alchemy uses it to narrow a project-level grant
 * to one resource on services with no per-resource IAM policy (Firestore,
 * Cloud SQL, Memorystore, …): `resource.name == "projects/p/…"`.
 */
export interface IamCondition {
  title?: string;
  expression?: string;
  description?: string;
}

/** Condition identity: two conditions are the same binding iff equal. */
const sameCondition = (left: IamCondition | undefined, right: IamCondition | undefined) =>
  (left === undefined && right === undefined) ||
  (left !== undefined &&
    right !== undefined &&
    left.expression === right.expression &&
    (left.title ?? "") === (right.title ?? ""));

/**
 * Resource kinds whose own IAM policy a binding can grant on. Kinds map
 * 1:1 onto a service's `getIamPolicy` / `setIamPolicy` pair, so a grant
 * reaches exactly one resource (the GCP analog of an IAM statement's
 * `Resource: [arn]`).
 */
export type GcpIamResourceKind =
  | "project"
  | "artifactregistry.repository"
  | "bigquery.dataset"
  | "bigquery.table"
  | "bigqueryconnection.connection"
  | "bigtable.instance"
  | "bigtable.table"
  | "binaryauthorization.attestor"
  | "cloudfunctions.function"
  | "cloudtasks.queue"
  | "compute.instance"
  | "containeranalysis.note"
  | "dataproc.cluster"
  | "iam.serviceAccount"
  | "kms.cryptoKey"
  | "ml.model"
  | "privateca.caPool"
  | "pubsub.schema"
  | "pubsub.subscription"
  | "pubsub.topic"
  | "run.job"
  | "run.service"
  | "run.workerPool"
  | "secretmanager.secret"
  | "servicedirectory.namespace"
  | "servicedirectory.service"
  | "spanner.database"
  | "spanner.instance"
  | "storage.bucket"
  | "workstations.workstation"
  | "workstations.workstationConfig";

/** Error from any IAM policy operation, narrowed to the fields Alchemy reads. */
type IamPolicyError = { readonly _tag: string; readonly message?: string };

interface IamPolicyTarget {
  get: Effect.Effect<IamPolicy, IamPolicyError, GcpOpContext>;
  set: (policy: IamPolicy) => Effect.Effect<unknown, IamPolicyError, GcpOpContext>;
}

// The generated per-service `Policy` shapes are structurally identical to
// `IamPolicy`, but each is a distinct nominal type; these adapters bridge
// the two once instead of casting at every call site.
type QueryGet = (input: {
  resource: string;
  "options.requestedPolicyVersion"?: number;
}) => Effect.Effect<any, IamPolicyError, GcpOpContext>;
type BodyGet = (input: {
  resource: string;
  body?: { options?: { requestedPolicyVersion?: number } };
}) => Effect.Effect<any, IamPolicyError, GcpOpContext>;
type Set = (input: {
  resource: string;
  body?: { policy?: any };
}) => Effect.Effect<any, IamPolicyError, GcpOpContext>;

const queryStyle =
  (get: QueryGet, set: Set) =>
  (resource: string): IamPolicyTarget => ({
    get: get({ resource, "options.requestedPolicyVersion": 3 }),
    set: (policy) => set({ resource, body: { policy } }),
  });

const bodyStyle =
  (get: BodyGet, set: Set, policyVersion = 3) =>
  (resource: string): IamPolicyTarget => ({
    get: get({
      resource,
      body: { options: { requestedPolicyVersion: policyVersion } },
    }),
    set: (policy) => set({ resource, body: { policy } }),
  });

const bucketName = (name: string) =>
  name.replace(/^projects\/_\/buckets\//, "").replace(/^buckets\//, "");

const computeInstance = (name: string): IamPolicyTarget => {
  const match = /projects\/([^/]+)\/zones\/([^/]+)\/instances\/([^/]+)/.exec(name);
  const [, project = "", zone = "", resource = ""] = match ?? [];
  return {
    get: compute.getIamPolicyInstances({
      project,
      zone,
      resource,
      optionsRequestedPolicyVersion: 3,
    }),
    set: (policy) =>
      compute.setIamPolicyInstances({
        project,
        zone,
        resource,
        body: { policy: policy as compute.Policy },
      }),
  };
};

type DatasetAccessItem = bigquery.DatasetAccessItem;

/** BigQuery stores the three basic dataset roles under legacy names. */
const LEGACY_DATASET_ROLES: Record<string, string> = {
  READER: "roles/bigquery.dataViewer",
  WRITER: "roles/bigquery.dataEditor",
  OWNER: "roles/bigquery.dataOwner",
};
const datasetRole = (role: string) => LEGACY_DATASET_ROLES[role] ?? role;

const principalOf = (item: DatasetAccessItem): string | undefined =>
  item.iamMember ??
  (item.userByEmail
    ? `${item.userByEmail.endsWith(".gserviceaccount.com") ? "serviceAccount" : "user"}:${item.userByEmail}`
    : item.groupByEmail
      ? `group:${item.groupByEmail}`
      : item.domain
        ? `domain:${item.domain}`
        : undefined);

const accessItemOf = (role: string, member: string): DatasetAccessItem => {
  const [type, id = ""] = member.split(/:(.*)/s);
  switch (type) {
    case "serviceAccount":
    case "user":
      return { role, userByEmail: id };
    case "group":
      return { role, groupByEmail: id };
    case "domain":
      return { role, domain: id };
    default:
      return { role, iamMember: member };
  }
};

/**
 * BigQuery datasets have no `setIamPolicy`; their access list is the
 * policy. Principal entries map to bindings; view, routine, dataset,
 * special-group, and conditional entries are carried through untouched.
 */
const bigqueryDataset = (name: string): IamPolicyTarget => {
  const match = /projects\/([^/]+)\/datasets\/([^/]+)/.exec(name);
  const [, projectId = "", datasetId = ""] = match ?? [];
  const isPrincipal = (item: DatasetAccessItem) =>
    item.condition === undefined && item.role !== undefined && principalOf(item) !== undefined;
  const read = bigquery.getDatasets({ projectId, datasetId });
  return {
    get: read.pipe(
      Effect.map((dataset) => {
        const byRole = new Map<string, string[]>();
        for (const item of dataset.access ?? []) {
          if (!isPrincipal(item)) continue;
          const role = datasetRole(item.role!);
          const members = byRole.get(role) ?? [];
          members.push(principalOf(item)!);
          byRole.set(role, members);
        }
        return {
          etag: dataset.etag,
          bindings: [...byRole].map(([role, members]) => ({ role, members })),
        } satisfies IamPolicy;
      }),
    ),
    set: (policy) =>
      read.pipe(
        Effect.flatMap((dataset) =>
          bigquery.patchDatasets({
            projectId,
            datasetId,
            body: {
              etag: dataset.etag,
              access: [
                ...(dataset.access ?? []).filter((item) => !isPrincipal(item)),
                ...(policy.bindings ?? []).flatMap((binding) =>
                  (binding.members ?? []).map((member) => accessItemOf(binding.role ?? "", member)),
                ),
              ],
            },
          }),
        ),
      ),
  };
};

const secret = (name: string): IamPolicyTarget =>
  /\/locations\//.test(name)
    ? queryStyle(
        secretmanager.getIamPolicyProjectsLocationsSecrets,
        secretmanager.setIamPolicyProjectsLocationsSecrets,
      )(name)
    : queryStyle(
        secretmanager.getIamPolicyProjectsSecrets,
        secretmanager.setIamPolicyProjectsSecrets,
      )(name);

const TARGETS: Record<GcpIamResourceKind, (name: string) => IamPolicyTarget> = {
  project: bodyStyle(resourcemanager.getIamPolicyProjects, resourcemanager.setIamPolicyProjects),
  "artifactregistry.repository": queryStyle(
    artifactregistry.getIamPolicyProjectsLocationsRepositories,
    artifactregistry.setIamPolicyProjectsLocationsRepositories,
  ),
  "bigquery.dataset": bigqueryDataset,
  // BigQuery table policies reject requestedPolicyVersion 3.
  "bigquery.table": bodyStyle(bigquery.getIamPolicyTables, bigquery.setIamPolicyTables, 1),
  "bigqueryconnection.connection": bodyStyle(
    bigqueryconnection.getIamPolicyProjectsLocationsConnections,
    bigqueryconnection.setIamPolicyProjectsLocationsConnections,
  ),
  "bigtable.instance": bodyStyle(
    bigtableadmin.getIamPolicyProjectsInstances,
    bigtableadmin.setIamPolicyProjectsInstances,
  ),
  "bigtable.table": bodyStyle(
    bigtableadmin.getIamPolicyProjectsInstancesTables,
    bigtableadmin.setIamPolicyProjectsInstancesTables,
  ),
  "binaryauthorization.attestor": queryStyle(
    binaryauthorization.getIamPolicyProjectsAttestors,
    binaryauthorization.setIamPolicyProjectsAttestors,
  ),
  "cloudfunctions.function": queryStyle(
    cloudfunctions.getIamPolicyProjectsLocationsFunctions,
    cloudfunctions.setIamPolicyProjectsLocationsFunctions,
  ),
  "cloudtasks.queue": bodyStyle(
    cloudtasks.getIamPolicyProjectsLocationsQueues,
    cloudtasks.setIamPolicyProjectsLocationsQueues,
  ),
  "compute.instance": computeInstance,
  "containeranalysis.note": bodyStyle(
    containeranalysis.getIamPolicyProjectsNotes,
    containeranalysis.setIamPolicyProjectsNotes,
  ),
  "dataproc.cluster": bodyStyle(
    dataproc.getIamPolicyProjectsRegionsClusters,
    dataproc.setIamPolicyProjectsRegionsClusters,
  ),
  "iam.serviceAccount": queryStyle(
    iam.getIamPolicyProjectsServiceAccounts,
    iam.setIamPolicyProjectsServiceAccounts,
  ),
  "kms.cryptoKey": queryStyle(
    kms.getIamPolicyProjectsLocationsKeyRingsCryptoKeys,
    kms.setIamPolicyProjectsLocationsKeyRingsCryptoKeys,
  ),
  "ml.model": queryStyle(ml.getIamPolicyProjectsModels, ml.setIamPolicyProjectsModels),
  "privateca.caPool": queryStyle(
    privateca.getIamPolicyProjectsLocationsCaPools,
    privateca.setIamPolicyProjectsLocationsCaPools,
  ),
  "pubsub.schema": queryStyle(
    pubsub.getIamPolicyProjectsSchemas,
    pubsub.setIamPolicyProjectsSchemas,
  ),
  "pubsub.subscription": queryStyle(
    pubsub.getIamPolicyProjectsSubscriptions,
    pubsub.setIamPolicyProjectsSubscriptions,
  ),
  "pubsub.topic": queryStyle(pubsub.getIamPolicyProjectsTopics, pubsub.setIamPolicyProjectsTopics),
  "run.job": queryStyle(
    run.getIamPolicyProjectsLocationsJobs,
    run.setIamPolicyProjectsLocationsJobs,
  ),
  "run.service": queryStyle(
    run.getIamPolicyProjectsLocationsServices,
    run.setIamPolicyProjectsLocationsServices,
  ),
  "run.workerPool": queryStyle(
    run.getIamPolicyProjectsLocationsWorkerPools,
    run.setIamPolicyProjectsLocationsWorkerPools,
  ),
  "secretmanager.secret": secret,
  "servicedirectory.namespace": bodyStyle(
    servicedirectory.getIamPolicyProjectsLocationsNamespaces,
    servicedirectory.setIamPolicyProjectsLocationsNamespaces,
  ),
  "servicedirectory.service": bodyStyle(
    servicedirectory.getIamPolicyProjectsLocationsNamespacesServices,
    servicedirectory.setIamPolicyProjectsLocationsNamespacesServices,
  ),
  "spanner.database": bodyStyle(
    spanner.getIamPolicyProjectsInstancesDatabases,
    spanner.setIamPolicyProjectsInstancesDatabases,
  ),
  "spanner.instance": bodyStyle(
    spanner.getIamPolicyProjectsInstances,
    spanner.setIamPolicyProjectsInstances,
  ),
  "storage.bucket": (name) => ({
    get: storage.getIamPolicyBuckets({
      bucket: bucketName(name),
      optionsRequestedPolicyVersion: 3,
    }),
    set: (policy) =>
      storage.setIamPolicyBuckets({
        bucket: bucketName(name),
        body: policy as storage.Policy,
      }),
  }),
  "workstations.workstation": queryStyle(
    workstations.getIamPolicyProjectsLocationsWorkstationClustersWorkstationConfigsWorkstations,
    workstations.setIamPolicyProjectsLocationsWorkstationClustersWorkstationConfigsWorkstations,
  ),
  "workstations.workstationConfig": queryStyle(
    workstations.getIamPolicyProjectsLocationsWorkstationClustersWorkstationConfigs,
    workstations.setIamPolicyProjectsLocationsWorkstationClustersWorkstationConfigs,
  ),
};

/** A single `role` → `member` edge on one resource's IAM policy. */
export interface IamMembership {
  kind: GcpIamResourceKind;
  /** Full resource name (`projects/p/topics/t`) or project id for `project`. */
  name: string;
  role: string;
  member: string;
}

const principal = (member: string) =>
  /^(serviceAccount|user|group|domain|principal|principalSet):/.test(member) ||
  member === "allUsers" ||
  member === "allAuthenticatedUsers"
    ? member
    : `serviceAccount:${member}`;

const targetName = (kind: GcpIamResourceKind, name: string) =>
  kind === "project" && !name.startsWith("projects/") ? `projects/${name}` : name;

/**
 * Rewrite `policy` so `member` holds exactly `add` roles out of `managed`
 * (roles in `managed` but not in `add` are revoked from the member).
 * Conditional bindings are never touched — only unconditional
 * role → members edges are Alchemy's to manage. Returns `undefined` when
 * the policy already matches.
 */
const rewrite = (
  policy: IamPolicy,
  member: string,
  add: ReadonlySet<string>,
  remove: ReadonlySet<string>,
  condition?: IamCondition,
): IamPolicy | undefined => {
  const bindings = (policy.bindings ?? []).map((binding) => ({
    ...binding,
    members: [...(binding.members ?? [])],
  }));
  let dirty = false;
  for (const role of add) {
    const existing = bindings.find(
      (binding) => binding.role === role && sameCondition(binding.condition, condition),
    );
    if (existing === undefined) {
      bindings.push(
        condition === undefined
          ? { role, members: [member] }
          : { role, members: [member], condition },
      );
      dirty = true;
    } else if (!existing.members.includes(member)) {
      existing.members.push(member);
      dirty = true;
    }
  }
  for (const binding of bindings) {
    if (!sameCondition(binding.condition, condition)) continue;
    if (binding.role === undefined || !remove.has(binding.role)) continue;
    if (add.has(binding.role)) continue;
    const next = binding.members.filter((item) => item !== member);
    if (next.length !== binding.members.length) {
      binding.members = next;
      dirty = true;
    }
  }
  if (!dirty) return undefined;
  // Keep the version the policy was read at: conditional bindings only
  // come back (and must be written) at v3, and some resources (BigQuery
  // tables) accept nothing above v1.
  return {
    ...policy,
    // Writing a conditional binding requires policy version 3.
    ...(condition !== undefined ? { version: 3 } : {}),
    bindings: bindings.filter((binding) => binding.members.length > 0),
  };
};

/**
 * Read-modify-write one resource's IAM policy under its etag, re-reading
 * on a concurrent-write `Conflict` (Cloud Storage: `IamPolicyEtagMismatch`)
 * so parallel host deploys converge
 * instead of failing. A freshly created service account can take a few
 * seconds to become a valid policy member, surfaced as `BadRequest`.
 */
export const updateIamMembership = (options: {
  kind: GcpIamResourceKind;
  name: string;
  member: string;
  add?: Iterable<string>;
  remove?: Iterable<string>;
  /** Manage the bindings carrying exactly this condition. */
  condition?: IamCondition;
}) => {
  const target = TARGETS[options.kind](targetName(options.kind, options.name));
  const member = principal(options.member);
  const add = new Set(options.add ?? []);
  const remove = new Set(options.remove ?? []);
  const write = Effect.gen(function* () {
    const policy = yield* target.get;
    const next = rewrite(policy, member, add, remove, options.condition);
    if (next === undefined) return;
    yield* target.set(next);
  }).pipe(
    Effect.retry({
      while: (error) =>
        error._tag === "Conflict" ||
        // Cloud Storage reports a stale etag as 412, not 409.
        error._tag === "IamPolicyEtagMismatch" ||
        // A just-created service account the policy service can't see yet.
        error._tag === "IamMemberNotFound" ||
        (error._tag === "BadRequest" && /does not exist/i.test(error.message ?? "")),
      // ~60s total: long enough for a new service account to propagate.
      times: 6,
      schedule: Schedule.exponential("1 second"),
    }),
  );
  // Don't report success until GCP reads the change back: callers (and
  // the resources that depend on them) must never race a write that has
  // not landed. A lost write (read-after-write lag, a concurrent writer
  // without etag) is re-applied.
  const confirmed = target.get.pipe(
    Effect.flatMap((policy) =>
      rewrite(policy, member, add, remove, options.condition) === undefined
        ? Effect.void
        : Effect.fail(new IamPolicyNotConverged({ resourceName: options.name })),
    ),
  );
  return write.pipe(
    Effect.andThen(confirmed),
    Effect.retry({
      while: (error) => error._tag === "GCP.IamPolicyNotConverged",
      times: 10,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );
};

/** A written IAM policy did not read back with the change applied. */
export class IamPolicyNotConverged extends Data.TaggedError("GCP.IamPolicyNotConverged")<{
  resourceName: string;
}> {}

/**
 * Remove `member` from every unconditional binding of `roles` on the
 * resource. A resource that is already gone has nothing to revoke.
 */
export const revokeIamMembership = (options: {
  kind: GcpIamResourceKind;
  name: string;
  member: string;
  roles: Iterable<string>;
  condition?: IamCondition;
}) =>
  updateIamMembership({
    kind: options.kind,
    name: options.name,
    member: options.member,
    remove: options.roles,
    condition: options.condition,
  }).pipe(
    Effect.catchIf(
      (error) => error._tag === "NotFound",
      () => Effect.void,
    ),
  );

/** Roles `member` currently holds unconditionally on the project. */
export const projectRolesOf = (project: string, member: string) =>
  TARGETS.project(targetName("project", project)).get.pipe(
    Effect.map((policy) => {
      const principalId = principal(member);
      return (policy.bindings ?? [])
        .filter(
          (binding) =>
            binding.condition === undefined && (binding.members ?? []).includes(principalId),
        )
        .flatMap((binding) => (binding.role ? [binding.role] : []));
    }),
  );

/** True when `member` holds `role` unconditionally on the resource. */
export const hasIamMembership = (options: {
  kind: GcpIamResourceKind;
  name: string;
  member: string;
  role: string;
}) =>
  TARGETS[options.kind](targetName(options.kind, options.name)).get.pipe(
    Effect.map((policy) =>
      (policy.bindings ?? []).some(
        (binding) =>
          binding.role === options.role &&
          binding.condition === undefined &&
          (binding.members ?? []).includes(principal(options.member)),
      ),
    ),
    Effect.catchIf(
      (error) => error._tag === "NotFound",
      () => Effect.succeed(false),
    ),
  );