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

import * as apikeys from "@distilled.cloud/gcp/apikeys_v2";
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 { tagRecord } from "alchemy/Tags";
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 {
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "../Labels.ts";
import { waitForOperation as waitForLongRunning, type LongRunningOperation } from "../Operation.ts";
import type { Providers } from "../Providers.ts";

const LOCATION = "global";
const MAX_NAME_LENGTH = 63;

export type ApiTarget = {
  /**
   * Canonical service name, e.g. `translate.googleapis.com`.
   */
  service?: string;
  /**
   * Allowed methods. Empty means all methods for `service`. A trailing
   * `*` wildcard is allowed (`Get*`).
   */
  methods?: string[];
};

export type BrowserKeyRestrictions = {
  /**
   * Referrer URL regular expressions allowed to call with this key.
   */
  allowedReferrers?: string[];
};

export type AndroidApplication = {
  /**
   * SHA-1 fingerprint of the app signing cert. Colon-separated and
   * compact hex are both accepted; the API stores the compact form.
   */
  sha1Fingerprint?: string;
  /**
   * Android application package name.
   */
  packageName?: string;
};

export type AndroidKeyRestrictions = {
  /**
   * Android apps allowed to call with this key.
   */
  allowedApplications?: AndroidApplication[];
};

export type ServerKeyRestrictions = {
  /**
   * Caller IP addresses (or CIDRs) allowed to call with this key.
   */
  allowedIps?: string[];
};

export type IosKeyRestrictions = {
  /**
   * iOS bundle IDs allowed to call with this key.
   */
  allowedBundleIds?: string[];
};

export type KeyRestrictions = {
  /**
   * Allowed API targets. Empty / omitted allows every enabled service.
   */
  apiTargets?: ApiTarget[];
  /**
   * HTTP referrer restrictions. Mutually exclusive with android, iOS,
   * and server restrictions.
   */
  browserKeyRestrictions?: BrowserKeyRestrictions;
  /**
   * Android app restrictions. Mutually exclusive with browser, iOS, and
   * server restrictions.
   */
  androidKeyRestrictions?: AndroidKeyRestrictions;
  /**
   * Caller IP restrictions. Mutually exclusive with browser, Android,
   * and iOS restrictions.
   */
  serverKeyRestrictions?: ServerKeyRestrictions;
  /**
   * iOS bundle-id restrictions. Mutually exclusive with browser,
   * Android, and server restrictions.
   */
  iosKeyRestrictions?: IosKeyRestrictions;
};

export type KeyProps = {
  /**
   * Key id (the `{key}` segment of
   * `projects/{project}/locations/global/keys/{key}`). If omitted, a
   * unique name is generated from the stack, stage, and logical id.
   * Must match `[a-z]([a-z0-9-]{0,61}[a-z0-9])?`, must not be UUID-like,
   * and is immutable — changing it replaces the key.
   */
  keyId?: string;
  /**
   * Human-readable display name. Max 63 characters.
   */
  displayName?: string;
  /**
   * User annotations. API keys have no labels field — Alchemy ownership
   * (`alchemy-stack` / `alchemy-stage` / `alchemy-id`) is stored here
   * so `list` / `pnpm nuke:gcp` can find owned keys. User keys are
   * preserved; Alchemy keys win on conflict.
   */
  annotations?: Record<string, string>;
  /**
   * Key restrictions (API targets and client-type limits).
   */
  restrictions?: KeyRestrictions;
  /**
   * Service account the key is bound to. Immutable — changing it
   * replaces the key. Binding enables service-account auth on the key.
   */
  serviceAccountEmail?: string;
};

export type Key = Resource<
  "GCP.ApiKeys.Key",
  KeyProps,
  {
    /** Full resource name `projects/{project}/locations/global/keys/{key}`. */
    name: string;
    /** Key id (last path segment). */
    keyId: string;
    /** Project id. */
    project: string;
    /** Always `global` — API keys are a global resource. */
    location: string;
    /** Human-readable display name. */
    displayName: string | undefined;
    /** User annotations (Alchemy ownership keys stripped). */
    annotations: Record<string, string>;
    /** Key restrictions currently configured. */
    restrictions: KeyRestrictions | undefined;
    /** Bound service account email, if any. */
    serviceAccountEmail: string | undefined;
    /**
     * Encrypted key string. Empty on `list` (nuke does not need it).
     * Fetch at runtime with {@link GetKeyString}.
     */
    keyString: string | undefined;
    /** Server-assigned UUID4, stable until delete. */
    uid: string | undefined;
    /** Server checksum of the resource. */
    etag: string | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Google Cloud API key (the API Keys API, `apikeys.googleapis.com`).
 *
 * Keys are global (`locations/global`). They have no labels — Alchemy
 * stamps ownership into `annotations` so `read`, `list`, and
 * `pnpm nuke:gcp` can find them. `keyId` and `serviceAccountEmail` are
 * immutable; changing either replaces the key. Deletes are soft: the key
 * can be undeleted for 30 days, then it is purged.
 *
 * ### Creating a Key
 * **Example:** Generated name
 * ```typescript
 * const maps = yield* GCP.ApiKeys.Key("Maps", {
 *   displayName: "maps browser key",
 * });
 * ```
 *
 * **Example:** Named key with annotations and API-target restrictions
 * ```typescript
 * const maps = yield* GCP.ApiKeys.Key("Maps", {
 *   keyId: "maps-browser",
 *   displayName: "maps browser key",
 *   annotations: { env: "prod" },
 *   restrictions: {
 *     apiTargets: [{ service: "geocoding-backend.googleapis.com" }],
 *     browserKeyRestrictions: {
 *       allowedReferrers: ["https://example.com/*"],
 *     },
 *   },
 * });
 * ```
 *
 * ### Reading the Key String
 * **Example:** Get the encrypted key string at runtime
 * ```typescript
 * const getKeyString = yield* GCP.ApiKeys.GetKeyString(maps);
 * const { keyString } = yield* getKeyString();
 * ```
 *
 * @resource
 * @category ApiKeys
 */
export const Key = Resource<Key>("GCP.ApiKeys.Key");

export class KeyNotResolved extends Data.TaggedError("GCP.ApiKeys.KeyNotResolved")<{
  resourceName: string;
}> {}

export class KeyStillExists extends Data.TaggedError("GCP.ApiKeys.KeyStillExists")<{
  resourceName: string;
}> {}

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

const rfc1035 = (name: string): string => {
  let next = name
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+/, "")
    .replace(/-+$/, "");
  if (!/^[a-z]/.test(next)) {
    next = `k${next}`;
  }
  next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/, "");
  return next.length > 0 ? next : "apikey";
};

const resourceName = (project: string, keyId: string) =>
  `projects/${project}/locations/${LOCATION}/keys/${keyId}`;

const parentOf = (project: string) => `projects/${project}/locations/${LOCATION}`;

const parseName = (name: string) => {
  const parts = name.split("/").filter((part) => part.length > 0);
  const keysAt = parts.lastIndexOf("keys");
  const projectsAt = parts.lastIndexOf("projects");
  return {
    project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
    keyId: keysAt >= 0 && parts[keysAt + 1] ? parts[keysAt + 1]! : lastSegment(name),
  };
};

const userAnnotations = (
  annotations: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(annotations));

const toId = (id: string, keyId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (keyId !== undefined) return keyId;
    if (existing !== undefined) return existing;
    return rfc1035(
      yield* createPhysicalName({
        id,
        maxLength: MAX_NAME_LENGTH,
        lowercase: true,
      }),
    );
  });

const isDeleted = (key: apikeys.V2Key | undefined) => (key?.deleteTime ?? "") !== "";

const toRestrictions = (
  restrictions: apikeys.V2Restrictions | undefined,
): KeyRestrictions | undefined => {
  if (restrictions === undefined) return undefined;
  if (
    (restrictions.apiTargets?.length ?? 0) === 0 &&
    restrictions.browserKeyRestrictions === undefined &&
    restrictions.androidKeyRestrictions === undefined &&
    restrictions.serverKeyRestrictions === undefined &&
    restrictions.iosKeyRestrictions === undefined
  ) {
    return undefined;
  }
  return {
    apiTargets: restrictions.apiTargets,
    browserKeyRestrictions: restrictions.browserKeyRestrictions,
    androidKeyRestrictions: restrictions.androidKeyRestrictions,
    serverKeyRestrictions: restrictions.serverKeyRestrictions,
    iosKeyRestrictions: restrictions.iosKeyRestrictions,
  };
};

const sorted = (values: readonly string[] | undefined) =>
  [...(values ?? [])].slice().sort((a, b) => a.localeCompare(b));

const fingerprintSha1 = (value: string | undefined) =>
  (value ?? "").replace(/:/g, "").toUpperCase();

const restrictionsFingerprint = (restrictions: KeyRestrictions | undefined): string => {
  if (restrictions === undefined) return "";
  const apiTargets = [...(restrictions.apiTargets ?? [])]
    .map((target) => ({
      service: target.service ?? "",
      methods: sorted(target.methods),
    }))
    .sort((a, b) => a.service.localeCompare(b.service));
  const android = [...(restrictions.androidKeyRestrictions?.allowedApplications ?? [])]
    .map((app) => ({
      packageName: app.packageName ?? "",
      sha1Fingerprint: fingerprintSha1(app.sha1Fingerprint),
    }))
    .sort((a, b) => a.packageName.localeCompare(b.packageName));
  return JSON.stringify({
    apiTargets,
    browser: restrictions.browserKeyRestrictions
      ? {
          allowedReferrers: sorted(restrictions.browserKeyRestrictions.allowedReferrers),
        }
      : undefined,
    android: restrictions.androidKeyRestrictions ? { allowedApplications: android } : undefined,
    server: restrictions.serverKeyRestrictions
      ? {
          allowedIps: sorted(restrictions.serverKeyRestrictions.allowedIps),
        }
      : undefined,
    ios: restrictions.iosKeyRestrictions
      ? {
          allowedBundleIds: sorted(restrictions.iosKeyRestrictions.allowedBundleIds),
        }
      : undefined,
  });
};

const toAttrs = (key: apikeys.V2Key, project: string, keyString?: string): Key["Attributes"] => {
  const name = key.name ?? "";
  const parsed = parseName(name);
  return {
    name,
    keyId: parsed.keyId,
    project: parsed.project || project,
    location: LOCATION,
    displayName: key.displayName,
    annotations: userAnnotations(key.annotations),
    restrictions: toRestrictions(key.restrictions),
    serviceAccountEmail: key.serviceAccountEmail,
    keyString,
    uid: key.uid,
    etag: key.etag,
    createTime: key.createTime,
    updateTime: key.updateTime,
  };
};

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

const getKeyStringValue = (name: string) =>
  apikeys.getKeyStringProjectsLocationsKeys({ name }).pipe(
    Effect.map((response) => response.keyString),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

const toAttrsLive = (key: apikeys.V2Key, project: string) =>
  Effect.gen(function* () {
    const name = key.name ?? "";
    const keyString = name.length > 0 ? yield* getKeyStringValue(name) : undefined;
    return toAttrs(key, project, keyString);
  });

const waitUntilActive = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((key) =>
      key && !isDeleted(key)
        ? Effect.succeed(key)
        : Effect.fail(new KeyNotResolved({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.ApiKeys.KeyNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((key) =>
      key === undefined || isDeleted(key)
        ? Effect.void
        : Effect.fail(new KeyStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.ApiKeys.KeyStillExists",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const reviveDeleted = (name: string) =>
  Effect.gen(function* () {
    const operation = yield* apikeys
      .undeleteProjectsLocationsKeys({ name, body: {} })
      .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
    if (operation !== undefined) {
      yield* waitForOperation(operation);
    }
    return yield* getByName(name);
  });

const listOwnedKeys = (project: string) =>
  apikeys.listProjectsLocationsKeys
    .pages({
      parent: parentOf(project),
      pageSize: 1000,
    })
    .pipe(
      Stream.flatMap((page) => Stream.fromIterable(page.keys ?? [])),
      Stream.filter(
        (key) =>
          !isDeleted(key) &&
          Object.keys(key.annotations ?? {}).some((item) => item.startsWith("alchemy-")),
      ),
      Stream.map((key) => toAttrs(key, project)),
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
      Effect.catchTag("NotFound", () => Effect.succeed([])),
    );

const toCreateBody = (news: KeyProps, annotations: Record<string, string>): apikeys.V2Key => ({
  displayName: news.displayName,
  annotations,
  restrictions: news.restrictions,
  serviceAccountEmail: news.serviceAccountEmail,
});

export const KeyProvider = () =>
  Provider.succeed(Key, {
    stables: ["name", "keyId", "project", "location", "uid", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.keyId ?? output?.keyId;
      const nextId = news.keyId ?? previousId;
      const idChanged = previousId !== undefined && nextId !== undefined && nextId !== previousId;
      const previousSa = olds?.serviceAccountEmail ?? output?.serviceAccountEmail ?? "";
      const nextSa = news.serviceAccountEmail ?? previousSa;
      const saChanged = previousSa !== nextSa;

      if (!idChanged && !saChanged) return undefined;
      return {
        action: "replace" as const,
        deleteFirst: !idChanged && previousId !== undefined && nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const keyId = yield* toId(id, olds?.keyId, output?.keyId);
      const name = output?.name ?? resourceName(env.project, keyId);
      const existing = yield* getByName(name);
      if (existing === undefined || isDeleted(existing)) return undefined;
      const attrs = yield* toAttrsLive(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.annotations)))
        ? attrs
        : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* listOwnedKeys(env.project);
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const keyId = yield* toId(id, news.keyId, output?.keyId);
      const name = resourceName(env.project, keyId);
      const parent = parentOf(env.project);
      const desiredAnnotations = {
        ...toLabels(news.annotations),
        ...(yield* createInternalLabels(id)),
      };

      let current = yield* getByName(name);

      if (current !== undefined && isDeleted(current)) {
        current = yield* reviveDeleted(name);
      }

      if (current === undefined || isDeleted(current)) {
        const created = yield* apikeys
          .createProjectsLocationsKeys({
            parent,
            keyId,
            body: toCreateBody(news, desiredAnnotations),
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created);
        }
        current = yield* getByName(name);
        if (current !== undefined && isDeleted(current)) {
          current = yield* reviveDeleted(name);
        }
        if (current === undefined || isDeleted(current)) {
          current = yield* waitUntilActive(name);
        }
      }

      if (current === undefined || isDeleted(current)) {
        return yield* new KeyNotResolved({ resourceName: name });
      }

      const observedAnnotations = tagRecord(current.annotations);
      const { upsert, removed } = diffLabels(observedAnnotations, desiredAnnotations);
      const annotationsChanged = upsert.length > 0 || removed.length > 0;
      const displayNameChanged = (current.displayName ?? "") !== (news.displayName ?? "");
      const restrictionsChanged =
        restrictionsFingerprint(toRestrictions(current.restrictions)) !==
        restrictionsFingerprint(news.restrictions);

      if (annotationsChanged || displayNameChanged || restrictionsChanged) {
        const updateMask = [
          annotationsChanged ? "annotations" : undefined,
          displayNameChanged ? "display_name" : undefined,
          restrictionsChanged ? "restrictions" : undefined,
        ].filter((field): field is string => field !== undefined);

        const operation = yield* apikeys.patchProjectsLocationsKeys({
          name,
          updateMask: updateMask.join(","),
          body: {
            name,
            etag: current.etag,
            annotations: desiredAnnotations,
            displayName: news.displayName,
            restrictions: news.restrictions ?? {},
          },
        });
        yield* waitForOperation(operation);
        current = yield* waitUntilActive(name);
      }

      return yield* toAttrsLive(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      const operation = yield* apikeys
        .deleteProjectsLocationsKeys({
          name: output.name,
          etag: output.etag,
        })
        .pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("1 second"),
          }),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
      if (operation !== undefined) {
        yield* waitForDeleteOperation(operation);
      }
      yield* waitUntilGone(output.name);
    }),
  });

/** API key operations finish within seconds. */
const OPERATION_BUDGET = "5 minutes";

/**
 * Wait for a long-running operation. ALREADY_EXISTS (code 6) means a
 * concurrent create won the race; reconcile observes the resource next.
 */
const waitForOperation = (operation: LongRunningOperation) =>
  waitForLongRunning(operation, (name) => apikeys.getOperations({ name }), {
    budget: OPERATION_BUDGET,
  }).pipe(
    Effect.catchIf(
      (error) => error._tag === "GCP.OperationFailed" && error.code === 6,
      () => Effect.succeed(operation),
    ),
  );

/**
 * Wait for a delete operation. A vanished operation or NOT_FOUND (code 5)
 * means the resource is already gone.
 */
const waitForDeleteOperation = (operation: LongRunningOperation) =>
  waitForOperation(operation).pipe(
    Effect.catchIf(
      (error) =>
        error._tag === "NotFound" || (error._tag === "GCP.OperationFailed" && error.code === 5),
      () => Effect.succeed(operation),
    ),
  );