sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ TokenValidation/ Configuration.ts

import * as tokenValidation from "@distilled.cloud/cloudflare/token-validation";
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";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.TokenValidation.Configuration" as const;
type TypeId = typeof TypeId;

/**
 * A JSON Web Key (JWK) in a token configuration's key set. These are public
 * keys (the public half of a JWKS), not secrets.
 */
export type JwkKey =
  | {
      /** Key type — RSA. */
      kty: "RSA";
      /** RSA signing algorithm the key is used with. */
      alg: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512";
      /** Key ID — must match the `kid` header of incoming JWTs. */
      kid: string;
      /** RSA modulus (base64url). */
      n: string;
      /** RSA public exponent (base64url). */
      e: string;
    }
  | {
      /** Key type — elliptic curve. */
      kty: "EC";
      /** ECDSA P-256 signing algorithm. */
      alg: "ES256";
      /** Curve — P-256. */
      crv: "P-256";
      /** Key ID — must match the `kid` header of incoming JWTs. */
      kid: string;
      /** EC x coordinate (base64url). */
      x: string;
      /** EC y coordinate (base64url). */
      y: string;
    }
  | {
      /** Key type — elliptic curve. */
      kty: "EC";
      /** ECDSA P-384 signing algorithm. */
      alg: "ES384";
      /** Curve — P-384. */
      crv: "P-384";
      /** Key ID — must match the `kid` header of incoming JWTs. */
      kid: string;
      /** EC x coordinate (base64url). */
      x: string;
      /** EC y coordinate (base64url). */
      y: string;
    };

export interface TokenConfigurationProps {
  /**
   * Zone the token configuration belongs to.
   *
   * Stable — moving a configuration between zones triggers a replacement.
   */
  zoneId: string;
  /**
   * Human-readable name for the configuration. If omitted, a unique name is
   * generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  title?: string;
  /**
   * A description that gives more details than `title`.
   * @default ""
   */
  description?: string;
  /**
   * Where to look for the token on incoming requests, as firewall fields —
   * e.g. `http.request.headers["authorization"][0]`.
   */
  tokenSources: string[];
  /**
   * The JWKS key set used to validate token signatures. Replacing entries
   * rotates the key set in place via the credentials endpoint.
   */
  keys: JwkKey[];
  /**
   * The token format. Only JWT is supported today. Cannot be changed after
   * creation — updating this property triggers a replacement.
   * @default "JWT"
   */
  tokenType?: "JWT";
}

export interface TokenConfigurationAttributes {
  /** Cloudflare-assigned UUID of the token configuration. */
  configId: string;
  /** Zone the configuration belongs to. */
  zoneId: string;
  /** Human-readable name of the configuration. */
  title: string;
  /** Description of the configuration. */
  description: string;
  /** Where the token is looked for on incoming requests. */
  tokenSources: string[];
  /** The token format. */
  tokenType: "JWT" | (string & {});
  /** The JWKS key set currently active on the configuration. */
  keys: JwkKey[];
  /** ISO8601 creation timestamp. */
  createdAt: string;
  /** ISO8601 last-modified timestamp. */
  lastUpdated: string;
}

export type TokenConfiguration = Resource<
  TypeId,
  TokenConfigurationProps,
  TokenConfigurationAttributes,
  never,
  Providers
>;

/**
 * An API Shield JWT validation token configuration — the JWKS key material
 * and token source locations used to validate JSON Web Tokens on a zone.
 *
 * A configuration holds a set of public JWKs (`keys`) plus the request
 * fields where the token is found (`tokenSources`). Rules
 * ({@link Rule}) then reference the configuration by UUID in
 * their expression (e.g. `is_jwt_valid("<configId>")`) to enforce
 * validation on selected hosts/operations.
 *
 * JWT validation is an API Shield feature (Enterprise add-on) — accounts
 * without the entitlement receive the typed `TokenValidationNotEntitled`
 * error (Cloudflare code 10403) on every call.
 *
 * Title, description, and token sources are patched in place; the key set
 * is rotated in place via the credentials endpoint. Only `zoneId` and
 * `tokenType` force a replacement.
 * ### Creating a Configuration
 * **Example:** JWT configuration with an RSA key
 * ```typescript
 * const config = yield* Cloudflare.TokenValidation.TokenConfiguration("ApiJwt", {
 *   zoneId: zone.zoneId,
 *   tokenSources: ['http.request.headers["authorization"][0]'],
 *   keys: [
 *     {
 *       kty: "RSA",
 *       alg: "RS256",
 *       kid: "key-2026-01",
 *       n: "<base64url modulus>",
 *       e: "AQAB",
 *     },
 *   ],
 * });
 * ```
 *
 * ### Rotating Keys
 * **Example:** Replace the key set in place
 * ```typescript
 * // Changing `keys` PUTs the full key set to the credentials endpoint —
 * // the configuration (and its UUID) stays in place.
 * const config = yield* Cloudflare.TokenValidation.TokenConfiguration("ApiJwt", {
 *   zoneId: zone.zoneId,
 *   tokenSources: ['http.request.headers["authorization"][0]'],
 *   keys: [oldKey, newKey],
 * });
 * ```
 *
 * ### Enforcing Validation
 * **Example:** Reference the configuration from a rule
 * ```typescript
 * yield* Cloudflare.TokenValidation.Rule("RequireJwt", {
 *   zoneId: zone.zoneId,
 *   action: "block",
 *   expression: Output.interpolate`is_jwt_valid("${config.configId}")`,
 *   selector: { include: [{ host: ["api.example.com"] }] },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/api-shield/security/jwt-validation/
 *
 * @resource
 * @product Token Validation
 * @category Application Security
 */
export const TokenConfiguration = Resource<TokenConfiguration>(TypeId);

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

export const TokenConfigurationProvider = () =>
  Provider.succeed(TokenConfiguration, {
    stables: ["configId", "zoneId", "tokenType", "createdAt"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Configurations are zone-scoped; the list op is keyed per zone.
      // Enumerate every zone, fan out the per-zone list, and flatten.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          tokenValidation.listConfigurations.items({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk).map((c) => toAttributes(c, zone.id))),
            // JWT validation is entitlement-gated and freshly minted tokens
            // can briefly 403 — skip zones we can't enumerate.
            Effect.catchTag(["TokenValidationNotEntitled", "Forbidden"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // Moving between zones replaces the configuration.
      const oldZoneId = output?.zoneId ?? olds?.zoneId;
      if (typeof oldZoneId === "string" && oldZoneId !== news.zoneId) {
        return { action: "replace" } as const;
      }
      // tokenType is not patchable (and "JWT" is the only value today).
      const oldType = output?.tokenType ?? olds?.tokenType ?? "JWT";
      if ((news.tokenType ?? "JWT") !== oldType) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      // Owned path: refresh by our persisted UUID.
      if (output?.configId) {
        const observed = yield* getConfiguration(zoneId, output.configId);
        if (observed) return toAttributes(observed, zoneId);
      }

      // Cold read — recover from lost state by matching the deterministic
      // physical title. Configurations carry no ownership markers, so an
      // existing match is reported as `Unowned` and the engine gates
      // takeover behind the adopt policy.
      const title = yield* createConfigurationTitle(id, olds?.title);
      const match = yield* findByTitle(zoneId, title);
      if (match) return Unowned(toAttributes(match, zoneId));
      return undefined;
    }),

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

      // 1. Observe — the UUID cached on `output` is a hint, not a
      //    guarantee: a 404 falls through to "missing" and we recreate.
      let observed = output?.configId
        ? yield* getConfiguration(zoneId, output.configId)
        : undefined;

      // 2. Ensure — greenfield (or out-of-band delete): create with the
      //    full desired body. Titles are not unique on Cloudflare's side,
      //    so there is no AlreadyExists race to tolerate.
      if (!observed) {
        observed = yield* tokenValidation.createConfiguration({
          zoneId,
          title,
          description: news.description ?? "",
          tokenSources: news.tokenSources,
          tokenType: news.tokenType ?? "JWT",
          credentials: { keys: news.keys },
        });
        return toAttributes(observed, zoneId);
      }

      // 3. Sync metadata — diff observed title/description/tokenSources
      //    against desired; PATCH only the delta, skip on no-op.
      const desiredDescription = news.description ?? "";
      const metadataDirty =
        observed.title !== title ||
        observed.description !== desiredDescription ||
        !sameStrings(observed.tokenSources, news.tokenSources);
      if (metadataDirty) {
        yield* tokenValidation.patchConfiguration({
          zoneId,
          configId: observed.id,
          title,
          description: desiredDescription,
          tokenSources: news.tokenSources,
        });
      }

      // 4. Sync key set — compare the observed JWKS against the desired
      //    one by full key material; PUT the full set on any difference
      //    (the credentials endpoint replaces the whole key set).
      if (!sameKeys(observed.credentials.keys, news.keys)) {
        yield* tokenValidation.putConfigurationCredential({
          zoneId,
          configId: observed.id,
          keys: news.keys,
        });
      }

      // 5. Return — re-read so attributes reflect the final cloud state.
      const final = yield* getConfiguration(zoneId, observed.id);
      return toAttributes(final ?? observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare may answer DELETE for an already-gone configuration with
      // `result: null`, which the typed response decode rejects — observe
      // first and treat missing as done.
      const observed = yield* getConfiguration(output.zoneId, output.configId);
      if (!observed) return;
      yield* tokenValidation
        .deleteConfiguration({
          zoneId: output.zoneId,
          configId: output.configId,
        })
        .pipe(Effect.catchTag("TokenConfigurationNotFound", () => Effect.void));
    }),
  });

type ObservedConfiguration = tokenValidation.GetConfigurationResponse;

/**
 * Read a configuration by UUID, mapping "gone"
 * (`TokenConfigurationNotFound`, HTTP 404) to `undefined`.
 */
const getConfiguration = (zoneId: string, configId: string) =>
  tokenValidation.getConfiguration({ zoneId, configId }).pipe(
    Effect.map((c): ObservedConfiguration | undefined => c),
    Effect.catchTag("TokenConfigurationNotFound", () => Effect.undefined),
  );

/**
 * Find a configuration by exact title. Titles are not unique on
 * Cloudflare's side; if several match, pick the oldest for determinism.
 */
const findByTitle = (zoneId: string, title: string) =>
  tokenValidation.listConfigurations.items({ zoneId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .filter((c) => c.title === title)
        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
        .at(0),
    ),
  );

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

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

const keyIdentity = (key: JwkKey) =>
  key.kty === "RSA"
    ? `RSA:${key.alg}:${key.kid}:${key.n}:${key.e}`
    : `EC:${key.alg}:${key.crv}:${key.kid}:${key.x}:${key.y}`;

const sameKeys = (
  observed: ObservedConfiguration["credentials"]["keys"],
  desired: readonly JwkKey[],
) => {
  const observedIds = observed.map((key) => keyIdentity(key as JwkKey)).sort();
  const desiredIds = desired.map(keyIdentity).sort();
  return observedIds.length === desiredIds.length && observedIds.join("") === desiredIds.join("");
};

const toAttributes = (
  configuration: ObservedConfiguration,
  zoneId: string,
): TokenConfigurationAttributes => ({
  configId: configuration.id,
  zoneId,
  title: configuration.title,
  description: configuration.description,
  tokenSources: [...configuration.tokenSources],
  tokenType: configuration.tokenType,
  // Distilled widens the RSA `alg` enum to an open union (`string & {}`).
  keys: configuration.credentials.keys.map((key) => ({ ...key }) as JwkKey),
  createdAt: configuration.createdAt,
  lastUpdated: configuration.lastUpdated,
});