sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Turnstile/ Widget.ts

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

const TypeId = "Cloudflare.Turnstile.Widget" as const;
type TypeId = typeof TypeId;

/**
 * Rendering / interaction mode of a Turnstile widget.
 */
export type WidgetMode = "managed" | "non-interactive" | "invisible";

/**
 * Region a Turnstile widget can be served from. Cannot be changed after
 * creation.
 */
export type WidgetRegion = "world" | "china";

/**
 * Clearance level granted when the widget is embedded on a Cloudflare zone.
 */
export type ClearanceLevel = "no_clearance" | "jschallenge" | "managed" | "interactive";

export type WidgetProps = {
  /**
   * Human readable widget name. Not unique. If omitted, a unique name is
   * generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Hostnames the widget is allowed to run on (e.g. `example.com`).
   * Subdomains are covered automatically.
   */
  domains: string[];
  /**
   * Widget mode: `managed` (Cloudflare decides if an interaction is
   * required), `non-interactive` (never requires interaction), or
   * `invisible` (no visible widget).
   */
  mode: WidgetMode;
  /**
   * Region where this widget can be used. Cannot be changed after creation —
   * updating this property triggers a replacement.
   * @default "world"
   */
  region?: WidgetRegion;
  /**
   * If `true`, Cloudflare issues computationally expensive challenges in
   * response to malicious bots (Enterprise only).
   * @default false
   */
  botFightMode?: boolean;
  /**
   * If Turnstile is embedded on a Cloudflare site and the widget should
   * grant challenge clearance, this setting determines the clearance level.
   * @default "no_clearance"
   */
  clearanceLevel?: ClearanceLevel;
  /**
   * Return the Ephemeral ID in `/siteverify` responses (Enterprise only).
   * @default false
   */
  ephemeralId?: boolean;
  /**
   * Do not show any Cloudflare branding on the widget (Enterprise only).
   * @default false
   */
  offlabel?: boolean;
};

export type WidgetAttributes = {
  /**
   * Widget item identifier tag. This is the public sitekey embedded in HTML.
   */
  sitekey: string;
  /**
   * Secret key for this widget, used server-side with the
   * `/turnstile/v0/siteverify` endpoint.
   */
  secret: Redacted.Redacted<string>;
  /**
   * The Cloudflare account the widget belongs to.
   */
  accountId: string;
  /**
   * Human readable widget name.
   */
  name: string;
  /**
   * Hostnames the widget is allowed to run on.
   */
  domains: string[];
  /**
   * Widget mode.
   */
  mode: WidgetMode;
  /**
   * Region where this widget can be used.
   */
  region: WidgetRegion;
  /**
   * Whether bot fight mode is enabled (Enterprise only).
   */
  botFightMode: boolean;
  /**
   * Clearance level granted on Cloudflare zones.
   */
  clearanceLevel: ClearanceLevel;
  /**
   * Whether the Ephemeral ID is returned in `/siteverify` (Enterprise only).
   */
  ephemeralId: boolean;
  /**
   * Whether Cloudflare branding is hidden (Enterprise only).
   */
  offlabel: boolean;
  /**
   * When the widget was created.
   */
  createdOn: string;
  /**
   * When the widget was last modified.
   */
  modifiedOn: string;
};

export type Widget = Resource<TypeId, WidgetProps, WidgetAttributes, never, Providers>;

/**
 * A Cloudflare Turnstile widget — Cloudflare's CAPTCHA alternative.
 *
 * A widget is identified by its auto-assigned `sitekey` (the public key you
 * embed in HTML) and produces a `secret` used server-side against the
 * `/turnstile/v0/siteverify` endpoint. Name, domains, mode, and clearance
 * settings are all mutable in place; only `region` forces a replacement.
 * ### Creating a Widget
 * **Example:** Managed widget
 * ```typescript
 * const widget = yield* Cloudflare.Turnstile.Widget("signup-form", {
 *   domains: ["example.com"],
 *   mode: "managed",
 * });
 * ```
 *
 * **Example:** Invisible widget with an explicit name
 * ```typescript
 * const widget = yield* Cloudflare.Turnstile.Widget("api-guard", {
 *   name: "api-guard",
 *   domains: ["example.com", "app.example.com"],
 *   mode: "invisible",
 * });
 * ```
 *
 * ### Using the keys
 * **Example:** Embedding the sitekey and verifying tokens
 * ```typescript
 * // The sitekey is public — render it in your HTML:
 * const sitekey = widget.sitekey;
 *
 * // The secret is redacted — pass it to your server-side verifier:
 * const secret = widget.secret; // Redacted<string>
 * ```
 *
 * @see https://developers.cloudflare.com/turnstile/
 *
 * @resource
 * @product Turnstile
 * @category Application Security
 */
export const Widget = Resource<Widget>(TypeId);

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

export const WidgetProvider = () =>
  Provider.succeed(Widget, {
    stables: ["sitekey", "accountId", "region", "createdOn"],
    diff: Effect.fn(function* ({ olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // Region cannot be changed after creation.
      const oldRegion = output?.region ?? olds?.region ?? "world";
      if ((news.region ?? "world") !== oldRegion) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      if (output?.sitekey) {
        const observed = yield* getWidget(acct, output.sitekey);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — recover from lost state by matching the deterministic
      // physical name. Names are not unique on Cloudflare's side; an exact
      // match on our generated/explicit name is the best identity we have.
      const name = yield* createWidgetName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match) {
        const observed = yield* getWidget(acct, match.sitekey);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      return undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createWidgetName(id, news.name);

      // Observe — the sitekey cached on `output` is a hint, not a
      // guarantee: a 404 falls through to "missing" and we recreate.
      const observed = output?.sitekey
        ? yield* getWidget(output.accountId ?? accountId, output.sitekey)
        : undefined;

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete): create with the
        // full desired body. Names are not unique so there is no
        // AlreadyExists race to tolerate.
        const created = yield* turnstile.createWidget({
          accountId,
          name,
          domains: news.domains,
          mode: news.mode,
          region: news.region,
          botFightMode: news.botFightMode,
          clearanceLevel: news.clearanceLevel,
          ephemeralId: news.ephemeralId,
          offlabel: news.offlabel,
        });
        return toAttributes(created, accountId);
      }

      // Sync — diff observed cloud state against desired; the update API
      // is a PUT that requires the full body, so send everything, but
      // skip the call entirely on a no-op.
      const desired = {
        name,
        domains: news.domains,
        mode: news.mode,
        botFightMode: news.botFightMode ?? observedBool(observed.botFightMode),
        clearanceLevel: news.clearanceLevel ?? (observed.clearanceLevel as ClearanceLevel),
        ephemeralId: news.ephemeralId ?? observedBool(observed.ephemeralId),
        offlabel: news.offlabel ?? observedBool(observed.offlabel),
      };
      const dirty =
        observed.name !== desired.name ||
        observed.mode !== desired.mode ||
        !sameDomains(observed.domains, desired.domains) ||
        (news.botFightMode !== undefined && observed.botFightMode !== news.botFightMode) ||
        (news.clearanceLevel !== undefined && observed.clearanceLevel !== news.clearanceLevel) ||
        (news.ephemeralId !== undefined && observed.ephemeralId !== news.ephemeralId) ||
        (news.offlabel !== undefined && observed.offlabel !== news.offlabel);

      if (!dirty) {
        return toAttributes(observed, observed.accountId);
      }

      const updated = yield* turnstile.updateWidget({
        accountId: observed.accountId,
        sitekey: observed.sitekey,
        ...desired,
      });
      return toAttributes(updated, observed.accountId);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* turnstile
        .deleteWidget({
          accountId: output.accountId,
          sitekey: output.sitekey,
        })
        .pipe(Effect.catchTag("WidgetNotFound", () => Effect.void));
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Enumerate every widget in the account, paginating exhaustively.
      const pages = yield* turnstile.listWidgets.pages({ accountId }).pipe(Stream.runCollect);
      const sitekeys = Array.from(pages).flatMap((page) =>
        (page.result ?? []).map((w) => w.sitekey),
      );
      // The list payload omits the write-only `secret`, so hydrate each
      // widget via `getWidget` to produce the exact `read` Attributes
      // shape. A widget deleted between list and get surfaces as
      // `WidgetNotFound` (mapped to `undefined` by `getWidget`).
      const rows = yield* Effect.forEach(
        sitekeys,
        (sitekey) =>
          getWidget(accountId, sitekey).pipe(
            Effect.map((w) => (w ? toAttributes(w, accountId) : undefined)),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is WidgetAttributes => row !== undefined);
    }),
  });

type ObservedWidget = turnstile.GetWidgetResponse & { accountId: string };

/**
 * Read a widget by sitekey, mapping "gone" (`WidgetNotFound`, Cloudflare
 * error code 10404) to `undefined`.
 */
const getWidget = (accountId: string, sitekey: string) =>
  turnstile.getWidget({ accountId, sitekey }).pipe(
    Effect.map((w): ObservedWidget => ({ ...w, accountId })),
    Effect.catchTag("WidgetNotFound", () => Effect.undefined),
  );

/**
 * Find a widget by exact name. Cloudflare's `filter` is a case-insensitive
 * substring match, so re-check exactly client-side. If several widgets carry
 * the same name, pick the oldest for determinism.
 */
const findByName = (accountId: string, name: string) =>
  turnstile.listWidgets.items({ accountId, filter: `name:${name}` }).pipe(
    Stream.filter((w) => w.name === name),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => a.createdOn.localeCompare(b.createdOn))
        .at(0),
    ),
  );

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

const observedBool = (value: boolean | undefined) => value ?? false;

const sameDomains = (observed: readonly string[], desired: readonly string[]) =>
  observed.length === desired.length &&
  [...observed].sort().join(",") === [...desired].sort().join(",");

const toAttributes = (
  widget:
    | turnstile.GetWidgetResponse
    | turnstile.CreateWidgetResponse
    | turnstile.UpdateWidgetResponse,
  accountId: string,
): WidgetAttributes => ({
  sitekey: widget.sitekey,
  secret: Redacted.make(widget.secret),
  accountId,
  name: widget.name,
  // Distilled widens generated string enums to open unions (`string & {}`).
  domains: [...widget.domains],
  mode: widget.mode as WidgetMode,
  region: widget.region as WidgetRegion,
  botFightMode: widget.botFightMode,
  clearanceLevel: widget.clearanceLevel as ClearanceLevel,
  ephemeralId: widget.ephemeralId,
  offlabel: widget.offlabel,
  createdOn: widget.createdOn,
  modifiedOn: widget.modifiedOn,
});