sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Devices/ PostureIntegration.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 Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

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

/**
 * The third-party provider behind the posture integration. Determines
 * which {@link DevicePostureIntegrationConfig} fields are required.
 */
export type DevicePostureIntegrationType =
  | "workspace_one"
  | "crowdstrike_s2s"
  | "uptycs"
  | "intune"
  | "kolide"
  | "tanium_s2s"
  | "sentinelone_s2s"
  | "custom_s2s";

/**
 * Connection settings for the third-party posture provider. Which fields
 * are required depends on the integration `type`:
 *
 * - `workspace_one` — `apiUrl`, `authUrl`, `clientId`, `clientSecret`
 * - `crowdstrike_s2s` — `apiUrl`, `clientId`, `clientSecret`, `customerId`
 * - `uptycs` — `apiUrl`, `clientKey`, `clientSecret`, `customerId`
 * - `intune` — `clientId`, `clientSecret`, `customerId`
 * - `kolide` — `clientId`, `clientSecret`
 * - `tanium_s2s` — `apiUrl`, `clientSecret`, optional `accessClientId` /
 *   `accessClientSecret`
 * - `sentinelone_s2s` — `apiUrl`, `clientSecret`
 * - `custom_s2s` — `apiUrl`, `clientSecret`, `accessClientId`,
 *   `accessClientSecret`
 *
 * Secrets are write-only: Cloudflare never returns them on reads, so they
 * are carried forward from the desired state.
 */
export interface DevicePostureIntegrationConfig {
  /** The third-party API URL the integration polls. */
  apiUrl?: string;
  /** The OAuth authorization URL (workspace_one). */
  authUrl?: string;
  /** The OAuth client ID used to authenticate with the provider. */
  clientId?: string;
  /** The client key (uptycs). */
  clientKey?: string;
  /** The customer/tenant identifier (crowdstrike, uptycs, intune). */
  customerId?: string;
  /** The OAuth client secret. Write-only — never returned on reads. */
  clientSecret?: Redacted.Redacted<string>;
  /** Access service-token client ID guarding the custom endpoint. */
  accessClientId?: string;
  /** Access service-token client secret. Write-only. */
  accessClientSecret?: Redacted.Redacted<string>;
}

export interface DevicePostureIntegrationProps {
  /**
   * Name of the posture integration. If omitted, a unique name is
   * generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The third-party provider type. Immutable — changing it triggers a
   * replacement.
   */
  type: DevicePostureIntegrationType;
  /**
   * The interval between each posture check against the third-party API.
   * Use `m` for minutes (e.g. `5m`) and `h` for hours (e.g. `12h`).
   */
  interval: string;
  /**
   * Connection settings for the provider (see
   * {@link DevicePostureIntegrationConfig} for the per-type field
   * requirements). Cloudflare validates the credentials against the live
   * third-party API on create/update.
   */
  config: DevicePostureIntegrationConfig;
}

export type DevicePostureIntegrationAttributes = {
  /** API UUID of the posture integration. */
  integrationId: string;
  /** Account that owns the integration. */
  accountId: string;
  /** Observed integration name. */
  name: string;
  /** The third-party provider type. */
  type: DevicePostureIntegrationType;
  /** Observed polling interval. */
  interval: string;
  /** Non-secret connection details as reported by Cloudflare. */
  config: {
    apiUrl: string | undefined;
    authUrl: string | undefined;
    clientId: string | undefined;
  };
};

export type DevicePostureIntegration = Resource<
  TypeId,
  DevicePostureIntegrationProps,
  DevicePostureIntegrationAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust **device posture integration** — a service-to-
 * service connection to a third-party endpoint security provider
 * (CrowdStrike, Intune, Kolide, Workspace ONE, ...) whose signals power
 * `*_s2s` device posture rules.
 *
 * Cloudflare validates the configured credentials against the live
 * provider API at create/update time, so a reachable third-party tenant
 * is required.
 * ### Creating a posture integration
 * **Example:** CrowdStrike Falcon
 * ```typescript
 * const falcon = yield* Cloudflare.Devices.DevicePostureIntegration("Falcon", {
 *   type: "crowdstrike_s2s",
 *   interval: "10m",
 *   config: {
 *     apiUrl: "https://api.crowdstrike.com",
 *     clientId: Alchemy.env("CROWDSTRIKE_CLIENT_ID"),
 *     clientSecret: Redacted.make(process.env.CROWDSTRIKE_SECRET!),
 *     customerId: "ccid-1234",
 *   },
 * });
 * ```
 *
 * **Example:** Custom service-to-service provider behind Access
 * ```typescript
 * const custom = yield* Cloudflare.Devices.DevicePostureIntegration("Custom", {
 *   type: "custom_s2s",
 *   interval: "30m",
 *   config: {
 *     apiUrl: "https://posture.example.com/check",
 *     clientSecret: Redacted.make(process.env.POSTURE_SECRET!),
 *     accessClientId: serviceToken.clientId,
 *     accessClientSecret: serviceToken.clientSecret,
 *   },
 * });
 * ```
 *
 * **Example:** Reference the integration from a posture rule
 * ```typescript
 * yield* Cloudflare.Devices.DevicePostureRule("FalconScore", {
 *   type: "crowdstrike_s2s",
 *   input: { connectionId: falcon.integrationId, os: "windows" },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/identity/devices/service-providers/
 *
 * @resource
 * @product Devices
 * @category Cloudflare One (Zero Trust)
 */
export const DevicePostureIntegration = Resource<DevicePostureIntegration>(TypeId);

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

export const DevicePostureIntegrationProvider = () =>
  Provider.succeed(DevicePostureIntegration, {
    stables: ["integrationId", "accountId", "type"],

    // Account collection — enumerate every posture integration in the
    // ambient account, exhaustively paginating the distilled list op.
    // Zero Trust is plan-gated; a `Forbidden` rejection means the account
    // lacks the entitlement, so treat it as "nothing to list".
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listDevicePostureIntegrations.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((i) => toAttributes(i, accountId)),
          ),
        ),
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // The provider type is immutable on Cloudflare's side — the config
      // shapes are disjoint, so model a type change as replacement.
      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 }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      if (output?.integrationId) {
        const observed = yield* observeIntegration(acct, output.integrationId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

      // Cold lookup by deterministic name. The list result carries no
      // ownership markers, so brand the match `Unowned` and let the
      // engine gate takeover behind the adopt policy.
      const name = yield* createIntegrationName(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* createIntegrationName(id, news.name);

      // 1. Observe — `output.integrationId` is a cached hint; fall back to
      //    a name scan so a crashed prior run converges.
      let observed = output?.integrationId
        ? yield* observeIntegration(accountId, output.integrationId)
        : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

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

      // 3. Sync — secrets are masked on reads so they cannot be diffed
      //    against observed state; PATCH when any observable field drifts
      //    OR when the desired config carries secrets that may have
      //    rotated. Cloudflare re-validates credentials on PATCH, so only
      //    send config when the non-secret surface differs.
      const sameObservable =
        (observed.name ?? "") === name &&
        (observed.interval ?? "") === news.interval &&
        sameObservedConfig(observed.config, news.config);
      if (sameObservable) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* zeroTrust.patchDevicePostureIntegration({
        accountId,
        integrationId: observed.id!,
        name,
        type: news.type,
        interval: news.interval,
        config: encodeConfig(news.config),
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteDevicePostureIntegration({
          accountId: output.accountId,
          integrationId: output.integrationId,
        })
        .pipe(Effect.catchTag("DevicePostureIntegrationNotFound", () => Effect.void));
    }),
  });

/**
 * Structural shape shared by get/list/create/patch responses.
 */
type ObservedIntegration = {
  id?: string | null;
  config?: { apiUrl: string; authUrl: string; clientId: string } | null;
  interval?: string | null;
  name?: string | null;
  type?: (string & {}) | null;
};

/**
 * Read an integration by id, mapping "gone" to `undefined`.
 */
const observeIntegration = (accountId: string, integrationId: string) =>
  zeroTrust
    .getDevicePostureIntegration({ accountId, integrationId })
    .pipe(Effect.catchTag("DevicePostureIntegrationNotFound", () => Effect.undefined));

/**
 * Find an integration by exact name.
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust
    .listDevicePostureIntegrations({ accountId })
    .pipe(Effect.map((list) => list.result.find((i) => i.name === name && i.id != null)));

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

type EncodedConfig = Parameters<typeof zeroTrust.createDevicePostureIntegration>[0]["config"];

/**
 * Project the alchemy config (flat, secrets `Redacted`) onto the wire
 * shape. The distilled request type is a union of per-provider structs;
 * the API discriminates by the sibling `type` field, so a single
 * present-fields projection is sufficient. The localized cast bridges the
 * flat shape to the union — it never touches error handling.
 */
const encodeConfig = (config: DevicePostureIntegrationConfig): EncodedConfig => {
  const out: Record<string, string> = {};
  if (config.apiUrl !== undefined) out.apiUrl = config.apiUrl;
  if (config.authUrl !== undefined) out.authUrl = config.authUrl;
  if (config.clientId !== undefined) out.clientId = config.clientId;
  if (config.clientKey !== undefined) out.clientKey = config.clientKey;
  if (config.customerId !== undefined) out.customerId = config.customerId;
  if (config.clientSecret !== undefined) {
    out.clientSecret = Redacted.value(config.clientSecret);
  }
  if (config.accessClientId !== undefined) {
    out.accessClientId = config.accessClientId;
  }
  if (config.accessClientSecret !== undefined) {
    out.accessClientSecret = Redacted.value(config.accessClientSecret);
  }
  return out as EncodedConfig;
};

/**
 * Compare only the fields Cloudflare echoes back (secrets are masked).
 */
const sameObservedConfig = (
  observed: ObservedIntegration["config"],
  desired: DevicePostureIntegrationConfig,
): boolean =>
  observed != null &&
  (desired.apiUrl === undefined || observed.apiUrl === desired.apiUrl) &&
  (desired.authUrl === undefined || observed.authUrl === desired.authUrl) &&
  (desired.clientId === undefined || observed.clientId === desired.clientId);

const toAttributes = (
  integration: ObservedIntegration,
  accountId: string,
): DevicePostureIntegrationAttributes => ({
  integrationId: integration.id ?? "",
  accountId,
  name: integration.name ?? "",
  type: (integration.type ?? "custom_s2s") as DevicePostureIntegrationType,
  interval: integration.interval ?? "",
  config: {
    apiUrl: integration.config?.apiUrl ?? undefined,
    authUrl: integration.config?.authUrl ?? undefined,
    clientId: integration.config?.clientId ?? undefined,
  },
});