sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Intel/ IndicatorFeed.ts

import crypto from "node:crypto";
import * as intel from "@distilled.cloud/cloudflare/intel";
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.Intel.IndicatorFeed" as const;
type TypeId = typeof TypeId;

export interface IndicatorFeedProps {
  /**
   * The name of the indicator feed. Not unique on Cloudflare's side, but
   * used as the cold-state recovery identity, so keep it unique within the
   * account. If omitted, a unique name is generated from the app, stage,
   * and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Human-readable description of the feed.
   */
  description?: string;
  /**
   * Whether the indicator feed can be attributed to a provider (consumers
   * see who published it).
   * @default false
   */
  isAttributable?: boolean;
  /**
   * Whether the indicator feed data can be downloaded by consumers.
   * @default false
   */
  isDownloadable?: boolean;
  /**
   * Whether the indicator feed is exposed to customers (publicly listed).
   * @default false
   */
  isPublic?: boolean;
  /**
   * Inline STIX 2.x content for the feed's snapshot. When provided, the
   * content is uploaded via the snapshot endpoint whenever it changes
   * (tracked by content hash). Cloudflare processes uploads asynchronously
   * — see the `latestUploadStatus` attribute.
   */
  snapshot?: string;
}

export interface IndicatorFeedAttributes {
  /** The server-assigned numeric identifier for the indicator feed. */
  feedId: number;
  /** The Cloudflare account the feed belongs to. */
  accountId: string;
  /** The name of the indicator feed. */
  name: string;
  /** The description of the indicator feed. */
  description: string | undefined;
  /** Whether the feed can be attributed to a provider. */
  isAttributable: boolean;
  /** Whether the feed data can be downloaded by consumers. */
  isDownloadable: boolean;
  /** Whether the feed is exposed to customers. */
  isPublic: boolean;
  /** When the feed was created. */
  createdOn: string | undefined;
  /** When the feed was last modified. */
  modifiedOn: string | undefined;
  /**
   * Status of the latest snapshot upload (`Mirroring`, `Unifying`,
   * `Loading`, `Provisioning`, `Complete`, or `Error`), if any.
   */
  latestUploadStatus: string | undefined;
  /**
   * SHA-256 hash of the last snapshot content uploaded by this provider.
   * Used to skip re-uploading unchanged content.
   */
  snapshotHash: string | undefined;
}

export type IndicatorFeed = Resource<
  TypeId,
  IndicatorFeedProps,
  IndicatorFeedAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare custom Indicator Feed (Cloudforce One threat intelligence).
 *
 * Indicator feeds let approved accounts publish their own threat-intel
 * indicators (domains, IPs, URLs) that consumer accounts can subscribe to
 * via Gateway or download directly. Creating feeds requires the account to
 * be approved as a feed provider (a Cloudforce One entitlement) — without
 * it, creation fails with the typed `IndicatorFeedsNotEntitled` error.
 *
 * :::warning
 * Cloudflare's API exposes **no delete endpoint** for indicator feeds.
 * Destroying this resource orphans the feed on Cloudflare's side (a warning
 * is logged). To avoid leaking feeds across deployments, the provider
 * adopts an existing feed with the same name instead of creating a
 * duplicate.
 * :::
 * ### Creating a Feed
 * **Example:** Basic feed
 * ```typescript
 * const feed = yield* Cloudflare.Intel.IndicatorFeed("threat-feed", {
 *   description: "Indicators observed by our honeypots",
 * });
 * ```
 *
 * **Example:** Public, downloadable feed
 * ```typescript
 * const feed = yield* Cloudflare.Intel.IndicatorFeed("public-feed", {
 *   name: "acme-public-indicators",
 *   description: "Acme Corp public threat indicators",
 *   isPublic: true,
 *   isDownloadable: true,
 *   isAttributable: true,
 * });
 * ```
 *
 * ### Publishing Indicators
 * **Example:** Upload a STIX 2.x snapshot inline
 * ```typescript
 * const feed = yield* Cloudflare.Intel.IndicatorFeed("threat-feed", {
 *   description: "Indicators observed by our honeypots",
 *   snapshot: JSON.stringify({
 *     type: "bundle",
 *     id: "bundle--0a242344-3c0b-4fdb-9f59-3e8c4a4f6b3a",
 *     objects: [],
 *   }),
 * });
 * ```
 *
 * ### Sharing a Feed
 * **Example:** Grant another account access
 * ```typescript
 * yield* Cloudflare.Intel.IndicatorFeedPermission("partner-access", {
 *   feedId: feed.feedId,
 *   accountTag: "023e105f4ecef8ad9ca31a8372d0c353",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/security-center/indicator-feeds/
 *
 * @resource
 * @product Intel
 * @category Observability & Analytics
 */
export const IndicatorFeed = Resource<IndicatorFeed>(TypeId);

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

export const IndicatorFeedProvider = () =>
  Provider.succeed(IndicatorFeed, {
    stables: ["feedId", "accountId", "createdOn"],

    // Account collection — enumerate every indicator feed owned by the
    // ambient account. The list endpoint returns a thin row (no
    // `latestUploadStatus`), so hydrate each id via `getFeed` to produce the
    // exact `read` Attributes shape. Accounts without the Cloudforce One feed
    // entitlement are rejected with the typed `Forbidden` tag — treat that as
    // an empty collection rather than failing the enumeration.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const ids = yield* intel.listIndicatorFeeds.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((f) => f.id).filter((id): id is number => id != null),
          ),
        ),
        Effect.catchTag("Forbidden", () => Effect.succeed([] as number[])),
      );
      const rows = yield* Effect.forEach(
        ids,
        (feedId) =>
          getFeed(accountId, feedId).pipe(
            Effect.map((observed) =>
              observed ? toAttributes(observed, accountId, undefined) : undefined,
            ),
            // A feed may vanish between list and get, or the account may
            // lack access to an individual feed — skip either case.
            Effect.catchTag("Forbidden", () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is IndicatorFeedAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      // Feeds cannot move between accounts (and cannot be deleted, so a
      // replacement would orphan the old feed) — but a different target
      // account still means a different physical resource.
      if ((output?.accountId ?? accountId) !== accountId) {
        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?.feedId !== undefined) {
        const observed = yield* getFeed(acct, output.feedId);
        return observed ? toAttributes(observed, acct, output.snapshotHash) : undefined;
      }
      // Cold read — recover from lost state by matching the deterministic
      // physical name. Names are not unique on Cloudflare's side; an exact
      // match on our generated/explicit name is the best identity we have.
      const name = yield* createFeedName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match?.id != null) {
        const observed = yield* getFeed(acct, match.id);
        return observed ? toAttributes(observed, acct, undefined) : undefined;
      }
      return undefined;
    }),

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

      // Observe — the feedId cached on `output` is a hint, not a
      // guarantee. Because feeds can never be deleted, a missing cache
      // falls back to a lookup by name so reruns adopt the existing feed
      // instead of leaking a duplicate.
      let observed =
        output?.feedId !== undefined
          ? yield* getFeed(output.accountId ?? accountId, output.feedId)
          : undefined;
      if (!observed) {
        const match = yield* findByName(accountId, name);
        if (match?.id != null) {
          observed = yield* getFeed(accountId, match.id);
        }
      }

      // Ensure — greenfield: create the feed with name + description; the
      // visibility flags are only settable via update, so fall through to
      // the sync step with the freshly observed state.
      if (!observed) {
        const created = yield* intel.createIndicatorFeed({
          accountId,
          name,
          description: news.description,
        });
        if (created.id == null) {
          // The create response is fully optional in the API schema; fall
          // back to the by-name lookup for the id we just created.
          const match = yield* findByName(accountId, name);
          observed = match?.id != null ? yield* getFeed(accountId, match.id) : undefined;
        } else {
          observed = yield* getFeed(accountId, created.id);
        }
      }
      if (!observed || observed.id == null) {
        return yield* intel.IndicatorFeedNotFound.make({
          code: 0,
          message: `Indicator feed "${name}" was not observable after creation`,
        });
      }
      const feedId = observed.id;

      // Sync — diff observed cloud state against desired settings and
      // apply only when dirty.
      const desired = {
        name,
        description: news.description,
        isAttributable: news.isAttributable ?? false,
        isDownloadable: news.isDownloadable ?? false,
        isPublic: news.isPublic ?? false,
      };
      const dirty =
        (observed.name ?? undefined) !== desired.name ||
        (news.description !== undefined &&
          (observed.description ?? undefined) !== desired.description) ||
        (observed.isAttributable ?? false) !== desired.isAttributable ||
        (observed.isDownloadable ?? false) !== desired.isDownloadable ||
        (observed.isPublic ?? false) !== desired.isPublic;
      if (dirty) {
        yield* intel.updateIndicatorFeed({
          accountId,
          feedId,
          ...desired,
        });
      }

      // Sync snapshot — upload inline STIX content whenever its hash
      // differs from what we last uploaded. Uploads are processed
      // asynchronously by Cloudflare (see `latestUploadStatus`).
      let snapshotHash = output?.snapshotHash;
      if (news.snapshot !== undefined) {
        const hash = yield* sha256(news.snapshot);
        if (hash !== output?.snapshotHash) {
          yield* intel.putIndicatorFeedSnapshot({
            accountId,
            feedId,
            source: news.snapshot,
          });
        }
        snapshotHash = hash;
      }

      const final = yield* getFeed(accountId, feedId);
      if (!final) {
        return yield* intel.IndicatorFeedNotFound.make({
          code: 0,
          message: `Indicator feed ${feedId} disappeared during reconcile`,
        });
      }
      return toAttributes(final, accountId, snapshotHash);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare's API has no delete endpoint for indicator feeds — the
      // feed is orphaned on the account. Reconcile adopts same-named feeds,
      // so re-creating this resource later reuses the orphan.
      yield* Effect.logWarning(
        `Cloudflare indicator feeds cannot be deleted via the API — ` +
          `feed ${output.feedId} ("${output.name}") on account ` +
          `${output.accountId} is left in place.`,
      );
    }),
  });

type ObservedFeed = intel.GetIndicatorFeedResponse;

/**
 * Read a feed by id, mapping "gone" — Cloudflare answers HTTP 403 with
 * "Feed N does not exist or this account does not have access", surfaced
 * as the typed `IndicatorFeedNotFound` — to `undefined`.
 */
const getFeed = (accountId: string, feedId: number) =>
  intel.getIndicatorFeed({ accountId, feedId }).pipe(
    Effect.map((f): ObservedFeed | undefined => f),
    Effect.catchTag("IndicatorFeedNotFound", () => Effect.undefined),
  );

/**
 * Find a feed by exact name. The list endpoint has no filter, so match
 * client-side; if several feeds carry the same name, pick the oldest for
 * determinism.
 */
const findByName = (accountId: string, name: string) =>
  intel.listIndicatorFeeds.items({ accountId }).pipe(
    Stream.filter((f) => f.name === name),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => (a.createdOn ?? "").localeCompare(b.createdOn ?? ""))
        .at(0),
    ),
  );

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

const sha256 = (content: string) =>
  Effect.sync(() => crypto.createHash("sha256").update(content).digest("hex"));

const toAttributes = (
  feed: ObservedFeed,
  accountId: string,
  snapshotHash: string | undefined,
): IndicatorFeedAttributes => ({
  feedId: feed.id ?? 0,
  accountId,
  name: feed.name ?? "",
  description: feed.description ?? undefined,
  isAttributable: feed.isAttributable ?? false,
  isDownloadable: feed.isDownloadable ?? false,
  isPublic: feed.isPublic ?? false,
  createdOn: feed.createdOn ?? undefined,
  modifiedOn: feed.modifiedOn ?? undefined,
  latestUploadStatus: feed.latestUploadStatus ?? undefined,
  snapshotHash,
});