sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Devices/ ManagedNetwork.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 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.ManagedNetwork" as const;
type TypeId = typeof TypeId;

/**
 * Detection configuration for a managed network: the WARP client opens a
 * TLS connection to `tlsSockaddr` and (optionally) verifies the
 * certificate's SHA-256 fingerprint to decide whether the device is on
 * the network.
 */
export interface DeviceManagedNetworkConfig {
  /**
   * A network address of the form `host:port` that the WARP client will
   * probe over TLS to detect the network (e.g. `"192.0.2.1:443"`).
   */
  tlsSockaddr: string;
  /**
   * The SHA-256 fingerprint (64 hexadecimal characters) of the TLS
   * certificate served at {@link tlsSockaddr}. When set, the client only
   * considers the network detected if the certificate matches.
   */
  sha256?: string;
}

export interface DeviceManagedNetworkProps {
  /**
   * Name of the managed network. Must be unique within the account. If
   * omitted, a unique name is generated from the app, stage, and logical
   * ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * TLS detection endpoint for the network. Mutable — updated in place.
   */
  config: DeviceManagedNetworkConfig;
}

export type DeviceManagedNetworkAttributes = {
  /** API UUID of the managed network. */
  networkId: string;
  /** Account that owns the managed network. */
  accountId: string;
  /** Observed network name. */
  name: string;
  /** The type of managed network — always `tls`. */
  type: "tls";
  /** Observed TLS detection configuration. */
  config: DeviceManagedNetworkConfig;
};

export type DeviceManagedNetwork = Resource<
  TypeId,
  DeviceManagedNetworkProps,
  DeviceManagedNetworkAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust **device managed network** — a TLS endpoint the
 * WARP client probes to detect whether the device is on a known network.
 * Device profiles can then `match` on `network` to apply different WARP
 * settings on trusted networks.
 *
 * Name and config are mutable in place (PUT). `tls` is the only network
 * type Cloudflare supports.
 * ### Creating a managed network
 * **Example:** Detect the office network by TLS fingerprint
 * ```typescript
 * const network = yield* Cloudflare.Devices.DeviceManagedNetwork("Office", {
 *   config: {
 *     tlsSockaddr: "192.0.2.1:443",
 *     sha256:
 *       "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
 *   },
 * });
 * ```
 *
 * **Example:** Use the network in a custom device profile
 * ```typescript
 * yield* Cloudflare.Devices.DeviceCustomProfile("OnPrem", {
 *   match: `network == "${network.name}"`,
 *   precedence: 100,
 *   serviceModeV2: { mode: "proxy", port: 3000 },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/configure-warp/managed-networks/
 *
 * @resource
 * @product Devices
 * @category Cloudflare One (Zero Trust)
 */
export const DeviceManagedNetwork = Resource<DeviceManagedNetwork>(TypeId);

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

export const DeviceManagedNetworkProvider = () =>
  Provider.succeed(DeviceManagedNetwork, {
    stables: ["networkId", "accountId", "type"],

    // Account collection: managed networks are account-scoped and the
    // distilled list op paginates (items: "result"). Enumerate every page
    // and hydrate into the exact `read` Attributes shape via `toAttributes`.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listDeviceNetworks.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((n) => n.networkId != null)
              .map((n) => toAttributes(n, accountId)),
          ),
        ),
      );
    }),

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

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

      // Cold lookup: names are unique per account, so an exact match
      // identifies the network — but it carries no ownership markers, so
      // brand it `Unowned` and let the engine gate takeover behind the
      // adopt policy.
      const name = yield* createNetworkName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),

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

      // 1. Observe — the network id cached on `output` is a hint, not a
      //    guarantee. Names are unique per account, so also scan by name
      //    to converge on a network created by a crashed prior run.
      let observed = output?.networkId
        ? yield* observeNetwork(accountId, output.networkId)
        : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // 2. Ensure — create when missing.
      if (!observed) {
        const created = yield* zeroTrust.createDeviceNetwork({
          accountId,
          name,
          type: "tls",
          config: encodeConfig(news.config),
        });
        return toAttributes(created, accountId);
      }

      // 3. Sync — PUT name/config when the observed state differs; skip
      //    the call entirely on a no-op.
      const dirty = (observed.name ?? "") !== name || !sameConfig(observed.config, news.config);
      if (!dirty) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* zeroTrust.updateDeviceNetwork({
        accountId,
        networkId: observed.networkId!,
        name,
        type: "tls",
        config: encodeConfig(news.config),
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare's delete is already idempotent (200 on a missing
      // network); the typed catch covers the documented error path too.
      yield* zeroTrust
        .deleteDeviceNetwork({
          accountId: output.accountId,
          networkId: output.networkId,
        })
        .pipe(Effect.catchTag("DeviceNetworkNotFound", () => Effect.void));
    }),
  });

/**
 * Structural shape shared by get/list/create/update responses.
 */
type ObservedNetwork = {
  config?: { tlsSockaddr: string; sha256?: string | null } | null;
  name?: string | null;
  networkId?: string | null;
  type?: "tls" | (string & {}) | null;
};

/**
 * Read a managed network by id, mapping "gone" (`DeviceNetworkNotFound`,
 * Cloudflare error code 2053) to `undefined`.
 */
const observeNetwork = (accountId: string, networkId: string) =>
  zeroTrust
    .getDeviceNetwork({ accountId, networkId })
    .pipe(Effect.catchTag("DeviceNetworkNotFound", () => Effect.undefined));

/**
 * Find a managed network by exact name. Names are unique per account.
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust
    .listDeviceNetworks({ accountId })
    .pipe(Effect.map((list) => list.result.find((n) => n.name === name && n.networkId != null)));

const createNetworkName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    // Cloudflare caps managed network names at 50 characters.
    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 50 }));
  });

const encodeConfig = (
  config: DeviceManagedNetworkConfig,
): { tlsSockaddr: string; sha256?: string } => {
  const out: { tlsSockaddr: string; sha256?: string } = {
    tlsSockaddr: config.tlsSockaddr,
  };
  if (config.sha256 !== undefined) out.sha256 = config.sha256;
  return out;
};

const sameConfig = (
  observed: ObservedNetwork["config"],
  desired: DeviceManagedNetworkConfig,
): boolean =>
  observed != null &&
  observed.tlsSockaddr === desired.tlsSockaddr &&
  (observed.sha256 ?? undefined) === desired.sha256;

const toAttributes = (
  network: ObservedNetwork,
  accountId: string,
): DeviceManagedNetworkAttributes => ({
  networkId: network.networkId ?? "",
  accountId,
  name: network.name ?? "",
  type: "tls",
  config: {
    tlsSockaddr: network.config?.tlsSockaddr ?? "",
    sha256: network.config?.sha256 ?? undefined,
  },
});