sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ MagicTransit/ SiteAcl.ts

import * as magicTransit from "@distilled.cloud/cloudflare/magic-transit";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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.MagicTransit.SiteAcl" as const;
type TypeId = typeof TypeId;

/**
 * Protocols a Magic WAN site ACL can match.
 */
export type MagicSiteAclProtocol = "tcp" | "udp" | "icmp";

/**
 * One side of a Magic WAN site ACL — selects a LAN and optionally narrows
 * the match to specific ports, port ranges, and subnets.
 */
export interface MagicSiteAclLan {
  /** The LAN identifier this side of the ACL applies to. */
  lanId: string;
  /** Display name of the LAN (informational). */
  lanName?: string;
  /** Specific ports to match. */
  ports?: number[];
  /** Port ranges to match, e.g. `"8080-8090"`. */
  portRanges?: string[];
  /** Subnets to match (IPv4 CIDR or address). */
  subnets?: string[];
}

export interface MagicSiteAclProps {
  /**
   * The site this ACL belongs to. Changing it triggers a replacement.
   */
  siteId: string;
  /**
   * The name of the ACL.
   */
  name: string;
  /**
   * The first LAN of the ACL pair.
   */
  lan1: MagicSiteAclLan;
  /**
   * The second LAN of the ACL pair.
   */
  lan2: MagicSiteAclLan;
  /**
   * Description for the ACL.
   */
  description?: string;
  /**
   * If `true`, traffic is forwarded locally on the Magic Connector; if
   * `false`, traffic is forwarded to Cloudflare.
   * @default false
   */
  forwardLocally?: boolean;
  /**
   * Protocols the ACL matches. Omit to match all protocols.
   */
  protocols?: MagicSiteAclProtocol[];
  /**
   * If `true`, the policy allows traffic in one direction only
   * (lan1 → lan2); if `false`, traffic is bidirectional.
   * @default false
   */
  unidirectional?: boolean;
}

export interface MagicSiteAclAttributes {
  /** Cloudflare-assigned identifier of the ACL. */
  aclId: string;
  /** The site the ACL belongs to. */
  siteId: string;
  /** The Cloudflare account the ACL belongs to. */
  accountId: string;
  /** The name of the ACL. */
  name: string;
  /** The ACL description, if set. */
  description: string | undefined;
  /** Whether traffic is forwarded locally on the connector. */
  forwardLocally: boolean | undefined;
  /** Protocols the ACL matches, if narrowed. */
  protocols: MagicSiteAclProtocol[] | undefined;
  /** Whether the ACL is unidirectional. */
  unidirectional: boolean | undefined;
}

export type MagicSiteAcl = Resource<
  TypeId,
  MagicSiteAclProps,
  MagicSiteAclAttributes,
  never,
  Providers
>;

/**
 * An ACL between two LANs of a Magic WAN site — allows traffic between
 * LAN segments behind a Magic WAN Connector (all inter-LAN traffic is
 * denied by default).
 *
 * Requires a Magic WAN subscription — accounts without it receive a typed
 * `MagicWanUnauthorized` error (Cloudflare code 1025) or `MagicWanNotEnabled`
 * (code 1101, "forbidden: feature not enabled").
 *
 * `siteId` is create-only — changing it triggers a replacement. Everything
 * else is updated in place.
 * ### Creating an ACL
 * **Example:** Allow TCP between two LANs
 * ```typescript
 * yield* Cloudflare.MagicTransit.MagicSiteAcl("lan-to-lan", {
 *   siteId: site.siteId,
 *   name: "office-to-lab",
 *   lan1: { lanId: officeLan.lanId, ports: [443] },
 *   lan2: { lanId: labLan.lanId },
 *   protocols: ["tcp"],
 * });
 * ```
 *
 * **Example:** Unidirectional ACL forwarded locally
 * ```typescript
 * yield* Cloudflare.MagicTransit.MagicSiteAcl("one-way", {
 *   siteId: site.siteId,
 *   name: "sensors-to-collector",
 *   lan1: { lanId: sensorsLan.lanId },
 *   lan2: { lanId: collectorLan.lanId, ports: [9000] },
 *   unidirectional: true,
 *   forwardLocally: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-wan/configuration/connector/network-options/site-acls/
 *
 * @resource
 * @product Magic Transit
 * @category Network
 */
export const MagicSiteAcl = Resource<MagicSiteAcl>(TypeId);

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

export const MagicSiteAclProvider = () =>
  Provider.succeed(MagicSiteAcl, {
    stables: ["aclId", "siteId", "accountId"],

    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return undefined;
      if (olds === undefined) return undefined;
      // ACLs cannot move between sites.
      if (
        typeof olds.siteId === "string" &&
        typeof news.siteId === "string" &&
        olds.siteId !== news.siteId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const siteId = output?.siteId ?? (typeof olds?.siteId === "string" ? olds.siteId : undefined);
      if (!siteId) return undefined;

      if (output?.aclId) {
        const observed = yield* getAcl(acct, siteId, output.aclId);
        if (observed) return toAttributes(observed, siteId, acct);
      }
      // Cold read — match by name within the site. ACLs carry no
      // ownership markers; report as Unowned so takeover is gated behind
      // the adopt policy.
      const name = output?.name ?? olds?.name;
      if (name) {
        const observed = yield* findByName(acct, siteId, name);
        if (observed) return Unowned(toAttributes(observed, siteId, acct));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Inputs have been resolved to concrete strings by Plan.
      const siteId = news.siteId as string;
      const lan1 = toLanRequest(news.lan1);
      const lan2 = toLanRequest(news.lan2);

      // Observe — the id on `output` is a hint; fall back to a name scan.
      let observed = output?.aclId ? yield* getAcl(accountId, siteId, output.aclId) : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, siteId, news.name);
      }

      // Ensure — create when missing.
      if (!observed) {
        const created = yield* magicTransit.createSiteAcl({
          accountId,
          siteId,
          name: news.name,
          lan_1: lan1,
          lan_2: lan2,
          description: news.description,
          forwardLocally: news.forwardLocally,
          protocols: news.protocols,
          unidirectional: news.unidirectional,
        });
        return toAttributes(created, siteId, accountId);
      }

      // Sync — the update API is a PUT; send the full desired state, but
      // skip the call entirely on a no-op.
      const dirty =
        (observed.name ?? undefined) !== news.name ||
        (news.description !== undefined &&
          (observed.description ?? undefined) !== news.description) ||
        (news.forwardLocally !== undefined &&
          (observed.forwardLocally ?? false) !== news.forwardLocally) ||
        (news.unidirectional !== undefined &&
          (observed.unidirectional ?? false) !== news.unidirectional) ||
        (news.protocols !== undefined && !sameList(observed.protocols, news.protocols)) ||
        lanDirty(observed.lan_1, lan1) ||
        lanDirty(observed.lan_2, lan2);
      if (dirty) {
        const updated = yield* magicTransit.updateSiteAcl({
          accountId,
          siteId,
          aclId: observed.id!,
          name: news.name,
          lan_1: lan1,
          lan_2: lan2,
          description: news.description,
          forwardLocally: news.forwardLocally,
          protocols: news.protocols,
          unidirectional: news.unidirectional,
        });
        observed = { ...updated, id: updated.id ?? observed.id };
      }

      return toAttributes(observed, siteId, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* magicTransit
        .deleteSiteAcl({
          accountId: output.accountId,
          siteId: output.siteId,
          aclId: output.aclId,
        })
        .pipe(Effect.catchTag("SiteAclNotFound", () => Effect.void));
    }),

    // Parent fan-out: ACLs are sub-resources keyed by site, and there is no
    // account-wide ACL enumeration API. Enumerate every Magic site (account
    // scope), then list ACLs per site with bounded concurrency, paginating
    // each list exhaustively. Magic WAN-gated accounts (and partial-scope
    // tokens) reject these routes with the typed `MagicWanUnauthorized`
    // (code 1025) / `Forbidden` tags — treat those as "nothing to list".
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;

      const siteIds = yield* magicTransit.listSites.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).flatMap((site) => (site.id ? [site.id] : [])),
          ),
        ),
        Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled", "Forbidden"], () =>
          Effect.succeed([] as string[]),
        ),
      );

      const rows = yield* Effect.forEach(
        siteIds,
        (siteId) =>
          magicTransit.listSiteAcls.pages({ accountId, siteId }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((acl) => toAttributes(acl, siteId, accountId)),
              ),
            ),
            // Site vanished or became inaccessible mid-enumeration — skip it.
            Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled", "Forbidden"], () =>
              Effect.succeed([] as MagicSiteAclAttributes[]),
            ),
          ),
        { concurrency: 10 },
      );

      return rows.flat();
    }),
  });

interface ObservedAclLan {
  lanId: string;
  lanName?: string | null;
  ports?: number[] | null;
  portRanges?: string[] | null;
  subnets?: string[] | null;
}

interface ObservedAcl {
  id?: string | null;
  name?: string | null;
  description?: string | null;
  forwardLocally?: boolean | null;
  protocols?: string[] | null;
  unidirectional?: boolean | null;
  lan_1?: ObservedAclLan | null;
  lan_2?: ObservedAclLan | null;
}

interface AclLanRequest {
  lanId: string;
  lanName?: string;
  ports?: number[];
  portRanges?: string[];
  subnets?: string[];
}

/**
 * Read an ACL by id, mapping "gone" (`SiteAclNotFound`, HTTP 404) to
 * `undefined`.
 */
const getAcl = (accountId: string, siteId: string, aclId: string) =>
  magicTransit.getSiteAcl({ accountId, siteId, aclId }).pipe(
    Effect.map((acl): ObservedAcl | undefined => acl),
    Effect.catchTag("SiteAclNotFound", () => Effect.undefined),
  );

/**
 * Find an ACL by exact name within a site. Names are not enforced unique;
 * pick the first match deterministically by id.
 */
const findByName = (accountId: string, siteId: string, name: string) =>
  magicTransit.listSiteAcls({ accountId, siteId }).pipe(
    Effect.map((r): ObservedAcl | undefined =>
      r.result
        .filter((acl) => acl.name === name)
        .sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))
        .at(0),
    ),
  );

const toLanRequest = (lan: MagicSiteAclLan): AclLanRequest => ({
  // Inputs have been resolved to concrete strings by Plan.
  lanId: lan.lanId as string,
  lanName: lan.lanName,
  ports: lan.ports,
  portRanges: lan.portRanges,
  subnets: lan.subnets,
});

const byString = (x: string | number, y: string | number) => {
  const a = String(x);
  const b = String(y);
  return a < b ? -1 : a > b ? 1 : 0;
};

const sameList = (
  a: readonly (string | number)[] | null | undefined,
  b: readonly (string | number)[] | undefined,
): boolean => [...(a ?? [])].sort(byString).join(",") === [...(b ?? [])].sort(byString).join(",");

const lanDirty = (observed: ObservedAclLan | null | undefined, desired: AclLanRequest): boolean =>
  (observed?.lanId ?? undefined) !== desired.lanId ||
  (desired.ports !== undefined && !sameList(observed?.ports, desired.ports)) ||
  (desired.portRanges !== undefined && !sameList(observed?.portRanges, desired.portRanges)) ||
  (desired.subnets !== undefined && !sameList(observed?.subnets, desired.subnets));

const toAttributes = (
  acl: ObservedAcl,
  siteId: string,
  accountId: string,
): MagicSiteAclAttributes => ({
  aclId: acl.id ?? "",
  siteId,
  accountId,
  name: acl.name ?? "",
  description: acl.description ?? undefined,
  forwardLocally: acl.forwardLocally ?? undefined,
  protocols: acl.protocols ? acl.protocols.map((p) => p as MagicSiteAclProtocol) : undefined,
  unidirectional: acl.unidirectional ?? undefined,
});