sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ VulnerabilityScanner/ TargetEnvironment.ts

import * as vulnScanner from "@distilled.cloud/cloudflare/vulnerability-scanner";
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 Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.VulnerabilityScanner.TargetEnvironment" as const;
type TypeId = typeof TypeId;

export interface VulnScannerTargetEnvironmentProps {
  /**
   * Human-readable name for the target environment. If omitted, a unique
   * name is generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The zone the scanner targets (`target.zone_tag`). Scan history is tied
   * to the target, so changing the zone triggers a replacement.
   */
  zoneId: string;
  /**
   * Optional description providing additional context. Mutable; omit to
   * clear an existing description.
   */
  description?: string;
}

export interface VulnScannerTargetEnvironmentAttributes {
  /** Server-assigned target environment identifier (UUID). */
  targetEnvironmentId: string;
  /** The Cloudflare account the target environment belongs to. */
  accountId: string;
  /** Human-readable name. */
  name: string;
  /** The zone being scanned (`target.zone_tag`). */
  zoneId: string;
  /** Description, if set. */
  description: string | undefined;
}

export type VulnScannerTargetEnvironment = Resource<
  TypeId,
  VulnScannerTargetEnvironmentProps,
  VulnScannerTargetEnvironmentAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Vulnerability Scanner target environment — declares which
 * zone the DAST-style web vulnerability scanner (Security Center, beta) is
 * allowed to scan.
 *
 * The environment is identified by a server-assigned UUID. `name` and
 * `description` are mutable in place; changing the target `zoneId` triggers
 * a replacement because scan history is tied to the target.
 * ### Creating a Target Environment
 * **Example:** Scan a zone
 * ```typescript
 * const zone = yield* Cloudflare.Zone.Zone("site", { name: "example.com" });
 *
 * const target = yield* Cloudflare.VulnerabilityScanner.VulnScannerTargetEnvironment("site-scans", {
 *   zoneId: zone.zoneId,
 * });
 * ```
 *
 * **Example:** With an explicit name and description
 * ```typescript
 * const target = yield* Cloudflare.VulnerabilityScanner.VulnScannerTargetEnvironment("site-scans", {
 *   name: "production-site",
 *   zoneId: zone.zoneId,
 *   description: "Weekly DAST scan of the production zone",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/security-center/
 *
 * @resource
 * @product Vulnerability Scanner
 * @category Application Security
 */
export const VulnScannerTargetEnvironment = Resource<VulnScannerTargetEnvironment>(TypeId);

/**
 * Returns true if the given value is a VulnScannerTargetEnvironment resource.
 */
export const isVulnScannerTargetEnvironment = (
  value: unknown,
): value is VulnScannerTargetEnvironment =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const VulnScannerTargetEnvironmentProvider = () =>
  Provider.succeed(VulnScannerTargetEnvironment, {
    stables: ["targetEnvironmentId", "accountId"],

    // Account collection: exhaustively paginate the account-scoped target
    // environments list and hydrate each row into the `read` Attributes shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* vulnScanner.listTargetEnvironments.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((env) => toAttributes(env, accountId)),
          ),
        ),
      );
    }),

    diff: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The scan target is the environment's identity — scan history is
      // tied to it, so a different zone means a different environment.
      if (
        output?.zoneId !== undefined &&
        typeof news.zoneId === "string" &&
        news.zoneId !== output.zoneId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      // Owned path: refresh by the persisted UUID.
      if (output?.targetEnvironmentId) {
        const observed = yield* observeTargetEnvironment(acct, output.targetEnvironmentId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

      // Cold read: recover from lost state by matching the deterministic
      // physical name. Names carry no ownership markers, so report the
      // match `Unowned` and let the engine gate takeover behind --adopt.
      const name = yield* createEnvironmentName(id, olds?.name);
      const match = yield* findTargetEnvironmentByName(acct, name);
      return match ? Unowned(toAttributes(match, acct)) : undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createEnvironmentName(id, news.name);
      // Inputs are resolved to concrete values by the engine.
      const zoneId = news.zoneId as string;

      // 1. Observe — the UUID cached on `output` is a hint, not a
      //    guarantee: a not-found falls through to "missing".
      let observed = output?.targetEnvironmentId
        ? yield* observeTargetEnvironment(output.accountId ?? accountId, output.targetEnvironmentId)
        : undefined;
      // Fall back to the deterministic name (e.g. crash after create but
      // before state persistence). Server UUIDs make duplicate-create the
      // failure mode to defend against here.
      if (!observed) {
        observed = yield* findTargetEnvironmentByName(accountId, name);
      }

      // 2. Ensure — create when missing.
      if (!observed) {
        const created = yield* vulnScanner.createTargetEnvironment({
          accountId,
          name,
          target: { type: "zone", zoneTag: zoneId },
          description: news.description,
        });
        return toAttributes(created, accountId);
      }

      // 3. Sync — PUT the full desired body when anything drifts; skip the
      //    API call entirely on a no-op.
      const desiredDescription = news.description;
      const observedDescription = observed.description ?? undefined;
      const dirty =
        observed.name !== name ||
        observed.target.zoneTag !== zoneId ||
        observedDescription !== desiredDescription;
      if (dirty) {
        const updated = yield* vulnScanner.updateTargetEnvironment({
          accountId,
          targetEnvironmentId: observed.id,
          name,
          target: { type: "zone", zoneTag: zoneId },
          // PUT with explicit null clears a stale description.
          description: desiredDescription ?? null,
        });
        return toAttributes(updated, accountId);
      }

      // 4. Return.
      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* vulnScanner
        .deleteTargetEnvironment({
          accountId: output.accountId,
          targetEnvironmentId: output.targetEnvironmentId,
        })
        .pipe(Effect.catchTag("TargetEnvironmentNotFound", () => Effect.void));
    }),
  });

interface ObservedTargetEnvironment {
  readonly id: string;
  readonly name: string;
  readonly target: { readonly type: "zone"; readonly zoneTag: string };
  readonly description?: string | null;
}

/**
 * Read a target environment by id, mapping "gone" (`TargetEnvironmentNotFound`,
 * Cloudflare error code 11001) to `undefined`.
 */
const observeTargetEnvironment = (accountId: string, targetEnvironmentId: string) =>
  vulnScanner
    .getTargetEnvironment({ accountId, targetEnvironmentId })
    .pipe(Effect.catchTag("TargetEnvironmentNotFound", () => Effect.undefined));

/**
 * Find a target environment by exact name. Names are not unique on
 * Cloudflare's side; if several match, pick the lexicographically smallest
 * id for determinism.
 */
const findTargetEnvironmentByName = (accountId: string, name: string) =>
  vulnScanner.listTargetEnvironments.items({ accountId }).pipe(
    Stream.filter((e) => e.name === name),
    Stream.runCollect,
    Effect.map((chunk): ObservedTargetEnvironment | undefined =>
      Array.from(chunk)
        .sort((a, b) => a.id.localeCompare(b.id))
        .at(0),
    ),
  );

const createEnvironmentName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const toAttributes = (
  env: ObservedTargetEnvironment,
  accountId: string,
): VulnScannerTargetEnvironmentAttributes => ({
  targetEnvironmentId: env.id,
  accountId,
  name: env.name,
  zoneId: env.target.zoneTag,
  description: env.description ?? undefined,
});