sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ ContentScanning/ Expression.ts

import * as contentScanning from "@distilled.cloud/cloudflare/content-scanning";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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 Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.ContentScanning.Expression" as const;
type TypeId = typeof TypeId;

export interface ExpressionProps {
  /**
   * Zone the custom scan expression belongs to. Stable — moving an
   * expression between zones triggers a replacement.
   */
  zoneId: string;
  /**
   * Ruleset-language expression that locates the content to scan inside
   * the request — e.g.
   * `lookup_json_string(http.request.body.raw, "file")`.
   *
   * Immutable — the API has no update endpoint for expressions, so
   * changing the payload triggers a replacement (create new, delete old).
   */
  payload: string;
}

export interface ExpressionAttributes {
  /** Cloudflare-assigned identifier of the custom scan expression. */
  expressionId: string;
  /** Zone the expression belongs to. */
  zoneId: string;
  /** The ruleset-language expression locating the content to scan. */
  payload: string;
}

export type Expression = Resource<TypeId, ExpressionProps, ExpressionAttributes, never, Providers>;

/**
 * A custom scan expression ("payload") for WAF Content Scanning — tells the
 * malicious-uploads scanner where to find encoded or nested content in the
 * request body (`/zones/{zone_id}/content-upload-scan/payloads`).
 *
 * An expression's identity is its `payload` text within the zone: the API
 * offers create/list/delete only (no update), so changing `payload`
 * triggers a replacement. The zone must have Content Scanning enabled (see
 * `Cloudflare.ContentScanning.ContentScanning`) — payload calls on a zone where scanning is
 * disabled fail with the typed `ContentScanningNotEnabled` error.
 *
 * Safety: expressions carry no ownership markers. When there is no prior
 * state, `read` scans the zone for an expression with the same payload text
 * and reports it as `Unowned`, so the engine refuses to take it over unless
 * `--adopt` (or `adopt(true)`) is set.
 * ### Creating expressions
 * **Example:** Scan a JSON-embedded file field
 * ```typescript
 * const scanning = yield* Cloudflare.ContentScanning.ContentScanning("UploadScanning", {
 *   zoneId: zone.zoneId,
 * });
 *
 * yield* Cloudflare.ContentScanning.Expression("ScanJsonFile", {
 *   zoneId: scanning.zoneId,
 *   payload: 'lookup_json_string(http.request.body.raw, "file")',
 * });
 * ```
 *
 * **Example:** Scan a base64-encoded form field
 * ```typescript
 * yield* Cloudflare.ContentScanning.Expression("ScanBase64Document", {
 *   zoneId: scanning.zoneId,
 *   payload: 'base64_decode(http.request.body.form["document"][0])',
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/waf/detections/malicious-uploads/#add-custom-scan-expressions
 *
 * @resource
 * @product Content Scanning
 * @category Application Security
 */
export const Expression = Resource<Expression>(TypeId);

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

/**
 * Cloudflare accepted the create call but the expression did not appear in
 * the returned list — an API anomaly that should never happen in practice.
 */
export class ExpressionCreateAnomaly extends Data.TaggedError("ExpressionCreateAnomaly")<{
  readonly zoneId: string;
  readonly payload: string;
}> {}

export const ExpressionProvider = () =>
  Provider.succeed(Expression, {
    stables: ["expressionId", "zoneId", "payload"],

    // Custom scan expressions are a zone-scoped Content Scanning feature. Fan
    // out over every zone in the account, exhaustively paginate each zone's
    // payloads, and hydrate each into the same Attributes shape `read`
    // produces. Zones without Content Scanning enabled (or not entitled) reject
    // payload calls with the typed `ContentScanningNotEnabled`/`Forbidden`
    // tags, and a deleted zone with `InvalidRoute` — skip all three.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones,
        (zone) =>
          contentScanning.listPayloads.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((expression) => toAttributes(zone.id, expression)),
              ),
            ),
            Effect.catchTags({
              ContentScanningNotEnabled: () => Effect.succeed([]),
              Forbidden: () => Effect.succeed([]),
              InvalidRoute: () => Effect.succeed([]),
            }),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      // zoneId is Input<string>; compare only once both sides are concrete.
      if (!isResolved(news)) return undefined;
      const old = olds !== undefined && isResolved(olds) ? olds : undefined;
      // The payload is the expression's identity — no update endpoint.
      const oldPayload = output?.payload ?? old?.payload;
      if (oldPayload !== undefined && oldPayload !== news.payload) {
        return { action: "replace" } as const;
      }
      const oldZoneId = output?.zoneId ?? old?.zoneId;
      if (oldZoneId !== undefined && oldZoneId !== news.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;

      const expressions = yield* listExpressions(zoneId);
      // Scanning disabled or zone gone — no expressions are observable.
      if (expressions === undefined) return undefined;

      // Owned path: refresh by our persisted expression id.
      if (output?.expressionId) {
        const observed = expressions.find((e) => e.id === output.expressionId);
        if (observed) return toAttributes(zoneId, observed);
      }

      // Adoption path: an expression with this payload text may already
      // exist on the zone. Expressions carry no ownership markers, so we
      // cannot prove we created it — brand it `Unowned` so the engine
      // refuses to take over unless `adopt` is set.
      const payload = output?.payload ?? olds?.payload;
      if (payload !== undefined) {
        const observed = expressions.find((e) => e.payload === payload);
        if (observed) return Unowned(toAttributes(zoneId, observed));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;

      // 1. Observe — the expression id cached on `output` is a hint, not
      //    a guarantee: a missing expression falls through to the payload
      //    scan and then to create. (Scanning must be enabled here — a
      //    disabled zone fails with the typed ContentScanningNotEnabled.)
      const expressionId = output?.expressionId;
      let observed: ObservedExpression | undefined = expressionId
        ? yield* findExpression(zoneId, (e) => e.id === expressionId)
        : undefined;

      // 2. Fall back to matching by payload text. Ownership has already
      //    been verified upstream — `read` reports existing expressions as
      //    `Unowned` and the engine gates takeover behind the adopt policy
      //    before reconcile ever runs.
      if (!observed) {
        observed = yield* findExpression(zoneId, (e) => e.payload === news.payload);
      }

      // 3. Ensure — create when missing. The create call returns the full
      //    list of expressions; find ours by payload text.
      if (!observed) {
        const created = yield* contentScanning.createPayload({
          zoneId,
          body: [{ payload: news.payload }],
        });
        observed = created.result.find((e) => e.payload === news.payload);
        if (!observed) {
          return yield* new ExpressionCreateAnomaly({
            zoneId,
            payload: news.payload,
          });
        }
      }

      // 4. No sync step — expressions have nothing mutable beyond identity.
      return toAttributes(zoneId, observed);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, expressionId } = output;
      // Observe first — scanning disabled / zone gone / already deleted
      // all mean there is nothing left to remove.
      const expressions = yield* listExpressions(zoneId);
      if (expressions === undefined) return;
      if (!expressions.some((e) => e.id === expressionId)) return;
      yield* contentScanning.deletePayload({ zoneId, expressionId }).pipe(
        // A concurrent disable between observe and delete is "gone".
        Effect.catchTags({
          ContentScanningNotEnabled: () => Effect.void,
          InvalidRoute: () => Effect.void,
        }),
      );
    }),
  });

type ObservedExpression = { id?: string | null; payload?: string | null };

/**
 * Find the first expression on the zone matching `predicate`, terminating
 * pagination as soon as a match is seen. Unlike {@link listExpressions},
 * "not observable" errors propagate (reconcile requires scanning enabled).
 */
const findExpression = (zoneId: string, predicate: (e: ObservedExpression) => boolean) =>
  contentScanning.listPayloads
    .items({ zoneId })
    .pipe(Stream.filter(predicate), Stream.runHead, Effect.map(Option.getOrUndefined));

/**
 * List the zone's custom scan expressions, mapping "not observable"
 * (scanning disabled on the zone, or the zone itself gone) to `undefined`.
 */
const listExpressions = (zoneId: string) =>
  contentScanning.listPayloads.items({ zoneId }).pipe(
    Stream.runCollect,
    Effect.map((chunk): readonly ObservedExpression[] | undefined => Array.from(chunk)),
    Effect.catchTags({
      ContentScanningNotEnabled: () => Effect.undefined,
      InvalidRoute: () => Effect.undefined,
    }),
  );

const toAttributes = (zoneId: string, expression: ObservedExpression): ExpressionAttributes => ({
  // Cloudflare always echoes both fields for a persisted expression.
  expressionId: expression.id ?? "",
  zoneId,
  payload: expression.payload ?? "",
});