sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Devices/ PostureRule.ts

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
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.Devices.PostureRule" as const;
type TypeId = typeof TypeId;

/**
 * The type of device posture rule, e.g. `os_version`, `firewall`,
 * `disk_encryption`, or a third-party service-to-service integration type
 * like `crowdstrike_s2s` (which requires a posture integration's
 * `connectionId` in {@link DevicePostureRuleProps.input}).
 */
export type DevicePostureRuleType = zeroTrust.CreateDevicePostureRequest["type"];

/**
 * The per-type check definition for a posture rule. The accepted shape
 * depends on {@link DevicePostureRuleProps.type} — e.g. `os_version` takes
 * `{ operatingSystem, operator, version }`, `firewall` takes
 * `{ enabled, operatingSystem }`, `disk_encryption` takes
 * `{ checkDisks?, requireAll? }`.
 */
export type DevicePostureRuleInput = zeroTrust.CreateDevicePostureRequest["input"];

/**
 * Platform conditions that scope which devices run the rule.
 */
export type DevicePostureRuleMatch = zeroTrust.CreateDevicePostureRequest["match"];

export interface DevicePostureRuleProps {
  /**
   * Name of the device posture rule. If omitted, a unique name is
   * generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The type of posture check (e.g. `os_version`, `firewall`,
   * `disk_encryption`, `crowdstrike_s2s`). Immutable — changing the type
   * triggers a replacement.
   */
  type: DevicePostureRuleType;
  /**
   * A description of the posture rule.
   */
  description?: string;
  /**
   * Polling frequency for the WARP client posture check (e.g. `"5m"`,
   * `"1h"`). Minimum `1m`.
   * @default "5m"
   */
  schedule?: string;
  /**
   * Expiration time for a posture check result (e.g. `"1h"`). If empty,
   * the result remains valid until overwritten by new data from the WARP
   * client.
   */
  expiration?: string;
  /**
   * The conditions (platforms) that a device must match for the rule to
   * run, e.g. `[{ platform: "mac" }]`.
   */
  match?: DevicePostureRuleMatch;
  /**
   * The per-type value to check against. Shape depends on {@link type}.
   */
  input?: DevicePostureRuleInput;
}

export type DevicePostureRuleAttributes = {
  /** API UUID of the posture rule. */
  postureRuleId: string;
  /** Account that owns the rule. */
  accountId: string;
  /** Observed rule name. */
  name: string;
  /** Observed rule type. */
  type: string;
  /** Observed description. */
  description: string | undefined;
  /** Observed polling schedule. */
  schedule: string | undefined;
  /** Observed result expiration. */
  expiration: string | undefined;
  /** Observed platform conditions. */
  match: { platform: string | undefined }[] | undefined;
  /** Observed per-type check definition. */
  input: unknown;
};

export type DevicePostureRule = Resource<
  TypeId,
  DevicePostureRuleProps,
  DevicePostureRuleAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust **device posture rule** — a periodic check the
 * WARP client runs on enrolled devices (OS version, firewall status, disk
 * encryption, file presence, or a third-party security provider's
 * verdict). Posture results can then gate Access policies and Gateway
 * rules.
 *
 * Everything except `type` is mutable in place (full PUT). Changing
 * `type` replaces the rule.
 * ### Infrastructure-free checks
 * **Example:** Require a minimum Windows version
 * ```typescript
 * const rule = yield* Cloudflare.Devices.DevicePostureRule("WindowsOsVersion", {
 *   type: "os_version",
 *   description: "Require Windows 10.0.19045+",
 *   match: [{ platform: "windows" }],
 *   schedule: "5m",
 *   input: {
 *     operatingSystem: "windows",
 *     operator: ">=",
 *     version: "10.0.19045",
 *   },
 * });
 * ```
 *
 * **Example:** Require the OS firewall to be enabled
 * ```typescript
 * yield* Cloudflare.Devices.DevicePostureRule("Firewall", {
 *   type: "firewall",
 *   match: [{ platform: "windows" }, { platform: "mac" }],
 *   input: { enabled: true, operatingSystem: "windows" },
 * });
 * ```
 *
 * **Example:** Require disk encryption on all drives
 * ```typescript
 * yield* Cloudflare.Devices.DevicePostureRule("DiskEncryption", {
 *   type: "disk_encryption",
 *   match: [{ platform: "mac" }],
 *   input: { requireAll: true },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/identity/devices/
 *
 * @resource
 * @product Devices
 * @category Cloudflare One (Zero Trust)
 */
export const DevicePostureRule = Resource<DevicePostureRule>(TypeId);

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

export const DevicePostureRuleProvider = () =>
  Provider.succeed(DevicePostureRule, {
    stables: ["postureRuleId", "accountId", "type"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection: exhaustively paginate the device
      // posture rules list and hydrate each into the `read` shape.
      return yield* zeroTrust.listDevicePostures.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((rule) => toAttributes(rule, accountId)),
          ),
        ),
        // Account lacks the Zero Trust / device posture entitlement.
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // `type` is immutable on Cloudflare's side — replace on change.
      const oldType = output?.type ?? olds?.type;
      if (oldType !== undefined && oldType !== news.type) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      // Owned path: refresh by our persisted rule id.
      if (output?.postureRuleId) {
        const observed = yield* observeRule(acct, output.postureRuleId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

      // Cold lookup: recover from lost state by exact name. Posture rules
      // carry no ownership markers, so brand the match `Unowned`.
      const name = yield* createRuleName(id, olds?.name);
      const match = yield* findByName(acct, name);
      // A create-first replacement reuses the name: the generation it is
      // replacing is not the replacement, so report nothing there yet.
      if (match && match.id === previous?.postureRuleId) return undefined;
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createRuleName(id, news.name);

      // 1. Observe — the rule id cached on `output` is a hint, not a
      //    guarantee: a missing rule falls through to create.
      const observed = output?.postureRuleId
        ? yield* observeRule(accountId, output.postureRuleId)
        : undefined;

      // 2. Ensure — create when missing. Names are not unique on
      //    Cloudflare's side, so there is no AlreadyExists race.
      if (!observed) {
        const created = yield* zeroTrust.createDevicePosture({
          accountId,
          name,
          type: news.type,
          description: news.description,
          schedule: news.schedule,
          expiration: news.expiration,
          match: news.match,
          input: news.input,
        });
        return toAttributes(created, accountId);
      }

      // 3. Sync — the update API is a PUT that requires the full body;
      //    send everything, but skip the call entirely on a no-op.
      const dirty =
        (observed.name ?? "") !== name ||
        (news.description !== undefined &&
          !sameJSON(denull(observed.description), news.description)) ||
        (news.schedule !== undefined && denull(observed.schedule) !== news.schedule) ||
        (news.expiration !== undefined && denull(observed.expiration) !== news.expiration) ||
        (news.match !== undefined && !sameJSON(normalizeMatch(observed.match), news.match)) ||
        (news.input !== undefined && !sameJSON(observed.input, news.input));
      if (!dirty) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* zeroTrust.updateDevicePosture({
        accountId,
        ruleId: observed.id!,
        name,
        type: news.type,
        description: news.description,
        schedule: news.schedule,
        expiration: news.expiration,
        match: news.match,
        input: news.input,
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare's delete is already idempotent (200 on a missing
      // rule); the typed catch covers the documented 404 path too.
      yield* zeroTrust
        .deleteDevicePosture({
          accountId: output.accountId,
          ruleId: output.postureRuleId,
        })
        .pipe(Effect.catchTag("PostureRuleNotFound", () => Effect.void));
    }),
  });

type ObservedRule =
  | zeroTrust.GetDevicePostureResponse
  | zeroTrust.CreateDevicePostureResponse
  | zeroTrust.UpdateDevicePostureResponse
  | zeroTrust.ListDevicePosturesResponse["result"][number];

/**
 * Read a posture rule by id, mapping "gone" (`PostureRuleNotFound`,
 * Cloudflare error code 6024) to `undefined`.
 */
const observeRule = (accountId: string, ruleId: string) =>
  zeroTrust
    .getDevicePosture({ accountId, ruleId })
    .pipe(Effect.catchTag("PostureRuleNotFound", () => Effect.undefined));

/**
 * Find a posture rule by exact name (oldest-id-first for determinism when
 * names collide).
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust.listDevicePostures.items({ accountId }).pipe(
    Stream.filter((r) => r.name === name && r.id != null),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))
        .at(0),
    ),
  );

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

const toAttributes = (rule: ObservedRule, accountId: string): DevicePostureRuleAttributes => ({
  postureRuleId: rule.id ?? "",
  accountId,
  name: rule.name ?? "",
  type: rule.type ?? "",
  description: denull(rule.description),
  schedule: denull(rule.schedule),
  expiration: denull(rule.expiration),
  match: normalizeMatch(rule.match),
  input: denull(rule.input),
});

const normalizeMatch = (
  match: ObservedRule["match"],
): { platform: string | undefined }[] | undefined =>
  match == null ? undefined : match.map((m) => ({ platform: denull(m.platform) }));

/**
 * Strip Cloudflare's `null` echoes to `undefined` so structural equality
 * (`JSON.stringify`) works.
 */
const denull = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);

/** Structural deep-equality via canonical JSON. */
const sameJSON = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);