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

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
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 Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import type { DeviceDefaultProfile } from "./DefaultProfile.ts";

export class CustomProfileUnexpectedResponse extends Data.TaggedError(
  "CustomProfileUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

const TypeId = "Cloudflare.Devices.CustomProfile" as const;
type TypeId = typeof TypeId;

/**
 * Configuration for a WARP custom device profile.
 *
 * A custom profile applies its settings to the subset of devices matched
 * by the `match` wirefilter expression, evaluated in ascending
 * `precedence` order. Devices not matched by any custom profile fall back
 * to the account's default profile.
 */
export interface DeviceCustomProfileProps {
  /**
   * Name of the device settings profile. If omitted, a unique name is
   * generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The wirefilter expression to match devices, e.g.
   * `identity.email == "user@example.com"` or `os.name == "windows"`.
   * Mutable — patched in place.
   */
  match: string;
  /**
   * The precedence of the profile. Lower values indicate higher
   * precedence; profiles are evaluated in ascending order. Must be
   * unique within the account.
   */
  precedence: number;
  /**
   * Whether the profile is applied to matching devices.
   * @default true
   */
  enabled?: boolean;
  /**
   * A human-readable description of the profile.
   */
  description?: string;
  /**
   * Routes that WARP will tunnel for matched devices. Mutually exclusive
   * with {@link exclude}. Pushed to the per-profile include list endpoint.
   */
  include?: DeviceDefaultProfile.SplitTunnelEntry[];
  /**
   * Routes that WARP will bypass for matched devices. Mutually exclusive
   * with {@link include}. Pushed to the per-profile exclude list endpoint.
   */
  exclude?: DeviceDefaultProfile.SplitTunnelEntry[];
  /**
   * Local-fallback DNS suffixes for matched devices. For each suffix,
   * WARP resolves matching names via the given DNS servers.
   */
  fallbackDomains?: DeviceDefaultProfile.FallbackDomain[];
  /**
   * Seconds to wait before activating the captive-portal bypass. A value
   * of `0` disables the bypass.
   */
  captivePortal?: number;
  /**
   * Seconds to wait before WARP reconnects after the user disables it.
   * `0` keeps WARP disabled until the user re-enables it.
   */
  autoConnect?: number;
  /**
   * Whether the user is allowed to remove the device from the team.
   */
  allowedToLeave?: boolean;
  /**
   * Whether the user is allowed to switch WARP between Gateway-with-WARP
   * and other modes.
   */
  allowModeSwitch?: boolean;
  /**
   * Whether WARP should surface available client updates to the user.
   */
  allowUpdates?: boolean;
  /**
   * When `true`, fallback domains without an explicit `dnsServer` are NOT
   * resolved via the system resolver — WARP refuses to resolve them.
   */
  disableAutoFallback?: boolean;
  /**
   * When `true`, Microsoft 365 service IP ranges are added to the
   * split-tunnel exclude list automatically.
   */
  excludeOfficeIps?: boolean;
  /**
   * When `true`, the user cannot turn the WARP switch off.
   */
  switchLocked?: boolean;
  /**
   * Selects WARP's tunneling behavior: `"warp"` for the full WireGuard
   * tunnel, `"proxy"` for a local SOCKS proxy on the chosen `port`.
   */
  serviceModeV2?: DeviceDefaultProfile.ServiceModeV2;
  /**
   * Minutes of LAN access permitted after a WARP reconnect. `0` means
   * unrestricted until the next WARP cycle.
   */
  lanAllowMinutes?: number;
  /**
   * Prefix length of the LAN subnet that {@link lanAllowMinutes} applies
   * to (e.g. `24` for a `/24`).
   */
  lanAllowSubnetSize?: number;
  /**
   * When `true`, the OS registers WARP's local interface IP with the
   * on-premises DNS server.
   */
  registerInterfaceIpWithDns?: boolean;
  /**
   * When `true`, WARP signals SCCM that the device is inside a VPN
   * boundary. Windows only.
   */
  sccmVpnBoundarySupport?: boolean;
  /**
   * URL launched when the user clicks "Send Feedback" in the client.
   */
  supportUrl?: string;
  /**
   * Which underlying tunnel protocol WARP should use (e.g. `"wireguard"`,
   * `"masque"`).
   */
  tunnelProtocol?: string;
}

export type DeviceCustomProfileAttributes = {
  /** API UUID of the profile. */
  policyId: string;
  /** Account that owns the profile. */
  accountId: string;
  /** Observed profile name. */
  name: string;
  /** Observed wirefilter match expression. */
  match: string | undefined;
  /** Observed precedence. */
  precedence: number | undefined;
  /** Whether the profile is applied to matching devices. */
  enabled: boolean | undefined;
  /** Observed description. */
  description: string | undefined;
  /** Always `false` — custom profiles are never the default profile. */
  default: boolean;
  /** Observed per-profile split-tunnel include list. */
  include: DeviceDefaultProfile.SplitTunnelEntry[];
  /** Observed per-profile split-tunnel exclude list. */
  exclude: DeviceDefaultProfile.SplitTunnelEntry[];
  /** Observed per-profile fallback domains. */
  fallbackDomains: DeviceDefaultProfile.FallbackDomain[];
  /** Observed captive-portal timeout (seconds). */
  captivePortal: number | undefined;
  /** Observed auto-connect timeout (seconds). */
  autoConnect: number | undefined;
  /** Whether devices are allowed to leave the organization. */
  allowedToLeave: boolean | undefined;
  /** Whether the user may switch WARP modes. */
  allowModeSwitch: boolean | undefined;
  /** Whether update notifications are shown. */
  allowUpdates: boolean | undefined;
  /** Whether auto-fallback to system DNS is disabled. */
  disableAutoFallback: boolean | undefined;
  /** Whether Microsoft IPs are auto-excluded. */
  excludeOfficeIps: boolean | undefined;
  /** Whether the WARP switch is locked on. */
  switchLocked: boolean | undefined;
  /** Tunneling mode configuration. */
  serviceModeV2: DeviceDefaultProfile.ServiceModeV2 | undefined;
  /** Whether the WARP IP is registered with the on-prem DNS server. */
  registerInterfaceIpWithDns: boolean | undefined;
  /** Whether SCCM VPN-boundary support is enabled. */
  sccmVpnBoundarySupport: boolean | undefined;
  /** Send-Feedback URL. */
  supportUrl: string | undefined;
  /** Tunnel protocol selection. */
  tunnelProtocol: string | undefined;
};

export type DeviceCustomProfile = Resource<
  TypeId,
  DeviceCustomProfileProps,
  DeviceCustomProfileAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare WARP **custom device profile** — a settings profile applied
 * to the subset of devices matched by a wirefilter `match` expression at a
 * given `precedence`.
 *
 * All properties are mutable in place: the profile itself is patched, and
 * the per-profile split-tunnel include/exclude and fallback-domain lists
 * are replaced via their dedicated endpoints. Deleting the resource
 * deletes the profile; matched devices fall back to the account's default
 * profile.
 * ### Creating a profile
 * **Example:** Profile for a user group
 * ```typescript
 * const profile = yield* Cloudflare.Devices.DeviceCustomProfile("Contractors", {
 *   match: 'identity.groups.name == "contractors"',
 *   precedence: 100,
 *   description: "Locked-down profile for contractors",
 *   switchLocked: true,
 * });
 * ```
 *
 * ### Split tunneling
 * **Example:** Exclude internal ranges from the tunnel
 * ```typescript
 * yield* Cloudflare.Devices.DeviceCustomProfile("Engineering", {
 *   match: 'identity.groups.name == "engineering"',
 *   precedence: 50,
 *   exclude: [
 *     { address: "10.0.0.0/8", description: "RFC1918" },
 *   ],
 * });
 * ```
 *
 * ### Fallback domains
 * **Example:** Resolve a private suffix via an on-prem DNS server
 * ```typescript
 * yield* Cloudflare.Devices.DeviceCustomProfile("CorpDns", {
 *   match: 'identity.email matches ".*@corp.example.com"',
 *   precedence: 10,
 *   fallbackDomains: [
 *     { suffix: "corp.example.com", dnsServer: ["10.0.0.53"] },
 *   ],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/configure-warp/device-profiles/
 *
 * @resource
 * @product Devices
 * @category Cloudflare One (Zero Trust)
 */
export const DeviceCustomProfile = Resource<DeviceCustomProfile>(TypeId);

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

export const DeviceCustomProfileProvider = () =>
  Provider.succeed(DeviceCustomProfile, {
    stables: ["policyId", "accountId", "default"],

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

      // Owned path: refresh by our persisted policy id.
      if (output?.policyId) {
        const observed = yield* observeProfile(acct, output.policyId);
        return observed ? yield* buildAttrs(acct, observed) : undefined;
      }

      // Cold lookup: recover from lost state by exact name. Profile names
      // carry no ownership markers, so brand the match `Unowned` and let
      // the engine gate takeover behind the adopt policy.
      const name = yield* createProfileName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match?.policyId) {
        const observed = yield* observeProfile(acct, match.policyId);
        if (observed) return Unowned(yield* buildAttrs(acct, observed));
      }
      return undefined;
    }),

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

      // 1. Observe — the policy id cached on `output` is a hint, not a
      //    guarantee: a missing profile falls through to create.
      let observed = output?.policyId
        ? yield* observeProfile(accountId, output.policyId)
        : undefined;

      // 2. Ensure — create when missing. Names are not unique on
      //    Cloudflare's side, so there is no AlreadyExists race; a
      //    precedence collision is a real validation error and propagates.
      if (!observed) {
        const created = yield* zeroTrust.createDevicePolicyCustom({
          accountId,
          name,
          match: news.match,
          precedence: news.precedence,
          enabled: news.enabled,
          description: news.description,
          include: news.include?.map(encodeSplit),
          exclude: news.exclude?.map(encodeSplit),
          captivePortal: news.captivePortal,
          autoConnect: news.autoConnect,
          allowedToLeave: news.allowedToLeave,
          allowModeSwitch: news.allowModeSwitch,
          allowUpdates: news.allowUpdates,
          disableAutoFallback: news.disableAutoFallback,
          excludeOfficeIps: news.excludeOfficeIps,
          switchLocked: news.switchLocked,
          serviceModeV2: news.serviceModeV2,
          lanAllowMinutes: news.lanAllowMinutes,
          lanAllowSubnetSize: news.lanAllowSubnetSize,
          registerInterfaceIpWithDns: news.registerInterfaceIpWithDns,
          sccmVpnBoundarySupport: news.sccmVpnBoundarySupport,
          supportUrl: news.supportUrl,
          tunnelProtocol: news.tunnelProtocol,
        });
        const policyId = created?.policyId;
        if (!policyId) {
          return yield* new CustomProfileUnexpectedResponse({
            message: "Cloudflare did not return a policy id for the created custom device profile",
          });
        }
        observed = yield* observeProfile(accountId, policyId);
        if (!observed) {
          return yield* new CustomProfileUnexpectedResponse({
            message: `custom device profile ${policyId} disappeared right after create`,
          });
        }
      }
      const policyId = observed.policyId!;

      // 3. Sync (a) — patch the profile body with only the changed fields.
      const patch: zeroTrust.PatchDevicePolicyCustomRequest = {
        accountId,
        policyId,
      };
      let dirty = false;
      const setIf = <
        K extends Exclude<keyof zeroTrust.PatchDevicePolicyCustomRequest, "accountId" | "policyId">,
      >(
        key: K,
        desired: zeroTrust.PatchDevicePolicyCustomRequest[K],
        observedValue: unknown,
      ) => {
        if (desired === undefined) return;
        if (!sameJSON(desired, observedValue)) {
          patch[key] = desired;
          dirty = true;
        }
      };
      setIf("name", name, observed.name ?? undefined);
      setIf("match", news.match, denull(observed.match));
      setIf("precedence", news.precedence, denull(observed.precedence));
      setIf("enabled", news.enabled, denull(observed.enabled));
      setIf("description", news.description, denull(observed.description));
      setIf("captivePortal", news.captivePortal, denull(observed.captivePortal));
      setIf("autoConnect", news.autoConnect, denull(observed.autoConnect));
      setIf("allowedToLeave", news.allowedToLeave, denull(observed.allowedToLeave));
      setIf("allowModeSwitch", news.allowModeSwitch, denull(observed.allowModeSwitch));
      setIf("allowUpdates", news.allowUpdates, denull(observed.allowUpdates));
      setIf("disableAutoFallback", news.disableAutoFallback, denull(observed.disableAutoFallback));
      setIf("excludeOfficeIps", news.excludeOfficeIps, denull(observed.excludeOfficeIps));
      setIf("switchLocked", news.switchLocked, denull(observed.switchLocked));
      setIf(
        "registerInterfaceIpWithDns",
        news.registerInterfaceIpWithDns,
        denull(observed.registerInterfaceIpWithDns),
      );
      setIf(
        "sccmVpnBoundarySupport",
        news.sccmVpnBoundarySupport,
        denull(observed.sccmVpnBoundarySupport),
      );
      setIf("supportUrl", news.supportUrl, denull(observed.supportUrl));
      setIf("tunnelProtocol", news.tunnelProtocol, denull(observed.tunnelProtocol));
      if (
        news.serviceModeV2 !== undefined &&
        !sameJSON(news.serviceModeV2, normalizeServiceMode(observed.serviceModeV2))
      ) {
        patch.serviceModeV2 = news.serviceModeV2;
        dirty = true;
      }
      // lanAllow* are accepted by PATCH but not reliably echoed on GET,
      // so push them whenever the user sets them — the API is idempotent.
      if (news.lanAllowMinutes !== undefined) {
        patch.lanAllowMinutes = news.lanAllowMinutes;
        dirty = true;
      }
      if (news.lanAllowSubnetSize !== undefined) {
        patch.lanAllowSubnetSize = news.lanAllowSubnetSize;
        dirty = true;
      }
      if (dirty) {
        yield* zeroTrust.patchDevicePolicyCustom(patch);
      }

      // 3. Sync (b) — replace the per-profile lists when they differ from
      //    the observed cloud state.
      const lists = yield* observeLists(accountId, policyId);
      if (news.include !== undefined && !sameJSON(news.include, lists.include)) {
        yield* zeroTrust.putDevicePolicyCustomInclude({
          accountId,
          policyId,
          body: news.include.map(encodeSplit),
        });
      }
      if (news.exclude !== undefined && !sameJSON(news.exclude, lists.exclude)) {
        yield* zeroTrust.putDevicePolicyCustomExclude({
          accountId,
          policyId,
          body: news.exclude.map(encodeSplit),
        });
      }
      if (
        news.fallbackDomains !== undefined &&
        !sameJSON(news.fallbackDomains, lists.fallbackDomains)
      ) {
        yield* zeroTrust.putDevicePolicyCustomFallbackDomain({
          accountId,
          policyId,
          domains: news.fallbackDomains.map(encodeFallback),
        });
      }

      // 4. Return — re-read so attrs reflect post-sync truth.
      const final = yield* observeProfile(accountId, policyId);
      if (!final) {
        return yield* new CustomProfileUnexpectedResponse({
          message: `custom device profile ${policyId} disappeared during reconcile`,
        });
      }
      return yield* buildAttrs(accountId, final);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteDevicePolicyCustom({
          accountId: output.accountId,
          policyId: output.policyId,
        })
        .pipe(Effect.catchTag("DevicePolicyNotFound", () => Effect.void));
    }),

    // Account collection: enumerate every custom device profile in the
    // ambient account, then hydrate each into the exact `read` Attributes
    // shape (same `observeProfile` + `buildAttrs` path read uses, so the
    // per-profile split-tunnel/fallback lists are fetched too). Bounded
    // concurrency keeps the fan-out polite; a profile that vanishes
    // mid-enumeration is dropped via the typed `DevicePolicyNotFound` map.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const items = yield* zeroTrust.listDevicePolicyCustoms.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.result ?? [])),
      );
      const rows = yield* Effect.forEach(
        items.filter((p) => p.policyId != null),
        (p) =>
          Effect.gen(function* () {
            const observed = yield* observeProfile(accountId, p.policyId!);
            return observed ? yield* buildAttrs(accountId, observed) : undefined;
          }),
        { concurrency: 10 },
      );
      return rows.filter((row): row is DeviceCustomProfileAttributes => row !== undefined);
    }),
  });

type ObservedProfile = NonNullable<zeroTrust.GetDevicePolicyCustomResponse>;

/**
 * Read a custom profile by id, mapping "gone" (`DevicePolicyNotFound`,
 * Cloudflare error code 2052) to `undefined`.
 */
const observeProfile = (accountId: string, policyId: string) =>
  zeroTrust.getDevicePolicyCustom({ accountId, policyId }).pipe(
    Effect.map((p): ObservedProfile | undefined => p ?? undefined),
    Effect.catchTag("DevicePolicyNotFound", () => Effect.undefined),
  );

/**
 * Read the three per-profile list endpoints.
 */
const observeLists = Effect.fn(function* (accountId: string, policyId: string) {
  const [include, exclude, fallback] = yield* Effect.all(
    [
      zeroTrust.getDevicePolicyCustomInclude({ accountId, policyId }),
      zeroTrust.getDevicePolicyCustomExclude({ accountId, policyId }),
      zeroTrust.getDevicePolicyCustomFallbackDomain({ accountId, policyId }),
    ],
    { concurrency: "unbounded" },
  );
  return {
    include: (include.result ?? []).map(normalizeSplit),
    exclude: (exclude.result ?? []).map(normalizeSplit),
    fallbackDomains: (fallback.result ?? []).map(normalizeFallback),
  };
});

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

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

const buildAttrs = Effect.fn(function* (accountId: string, profile: ObservedProfile) {
  const policyId = profile.policyId!;
  const lists = yield* observeLists(accountId, policyId);
  const attrs: DeviceCustomProfileAttributes = {
    policyId,
    accountId,
    name: profile.name ?? "",
    match: denull(profile.match),
    precedence: denull(profile.precedence),
    enabled: denull(profile.enabled),
    description: denull(profile.description),
    default: profile.default ?? false,
    include: lists.include,
    exclude: lists.exclude,
    fallbackDomains: lists.fallbackDomains,
    captivePortal: denull(profile.captivePortal),
    autoConnect: denull(profile.autoConnect),
    allowedToLeave: denull(profile.allowedToLeave),
    allowModeSwitch: denull(profile.allowModeSwitch),
    allowUpdates: denull(profile.allowUpdates),
    disableAutoFallback: denull(profile.disableAutoFallback),
    excludeOfficeIps: denull(profile.excludeOfficeIps),
    switchLocked: denull(profile.switchLocked),
    serviceModeV2: normalizeServiceMode(profile.serviceModeV2),
    registerInterfaceIpWithDns: denull(profile.registerInterfaceIpWithDns),
    sccmVpnBoundarySupport: denull(profile.sccmVpnBoundarySupport),
    supportUrl: denull(profile.supportUrl),
    tunnelProtocol: denull(profile.tunnelProtocol),
  };
  return attrs;
});

/**
 * 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);

const normalizeServiceMode = (
  sm: { mode?: string | null; port?: number | null } | null | undefined,
): DeviceDefaultProfile.ServiceModeV2 | undefined =>
  sm && sm.mode != null
    ? {
        mode: (sm.mode === "proxy" ? "proxy" : "warp") as "warp" | "proxy",
        port: denull(sm.port),
      }
    : undefined;

const normalizeSplit = (
  entry:
    | { address: string; description?: string | null }
    | { host: string; description?: string | null },
): DeviceDefaultProfile.SplitTunnelEntry => ({
  address: "address" in entry ? entry.address : "",
  host: "host" in entry ? entry.host : undefined,
  description: denull(entry.description),
});

const normalizeFallback = (entry: {
  suffix: string;
  description?: string | null;
  dnsServer?: string[] | null;
}): DeviceDefaultProfile.FallbackDomain => ({
  suffix: entry.suffix,
  description: denull(entry.description),
  dnsServer: denull(entry.dnsServer),
});

/**
 * Encode a SplitTunnelEntry for the API's union shape (`address` OR `host`).
 * Prefers `host` when set since the address would otherwise be empty.
 */
const encodeSplit = (
  e: DeviceDefaultProfile.SplitTunnelEntry,
): { address: string; description?: string } | { host: string; description?: string } => {
  if (e.host && !e.address) {
    return e.description !== undefined
      ? { host: e.host, description: e.description }
      : { host: e.host };
  }
  return e.description !== undefined
    ? { address: e.address, description: e.description }
    : { address: e.address };
};

const encodeFallback = (
  d: DeviceDefaultProfile.FallbackDomain,
): { suffix: string; description?: string; dnsServer?: string[] } => {
  const out: { suffix: string; description?: string; dnsServer?: string[] } = {
    suffix: d.suffix,
  };
  if (d.description !== undefined) out.description = d.description;
  if (d.dnsServer !== undefined) out.dnsServer = d.dnsServer;
  return out;
};

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