sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ DNS/ ZoneTransferTsig.ts

import * as dns from "@distilled.cloud/cloudflare/dns";
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 Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.DNS.ZoneTransferTsig" as const;
type TypeId = typeof TypeId;

export interface ZoneTransferTsigProps {
  /**
   * TSIG key name. If omitted, a unique name is generated from the app,
   * stage, and logical ID.
   *
   * Mutable — updated in place (PUT).
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * TSIG algorithm (e.g. `hmac-sha512.`).
   *
   * Mutable — updated in place (PUT).
   */
  algo: string;
  /**
   * TSIG secret (base64-encoded key material). Kept redacted — it is
   * never stored in the resource's attributes.
   *
   * Mutable — updated in place (PUT).
   */
  secret: Redacted.Redacted<string>;
}

export interface ZoneTransferTsigAttributes {
  /** Identifier of the TSIG. */
  tsigId: string;
  /** The Cloudflare account the TSIG belongs to. */
  accountId: string;
  /** TSIG key name. */
  name: string;
  /** TSIG algorithm. */
  algo: string;
}

export type ZoneTransferTsig = Resource<
  TypeId,
  ZoneTransferTsigProps,
  ZoneTransferTsigAttributes,
  never,
  Providers
>;

/**
 * A Secondary DNS TSIG key
 * (`/accounts/{account_id}/secondary_dns/tsigs`) — shared-secret
 * authentication for zone transfers between Cloudflare and external
 * nameservers. Reference it from a {@link ZoneTransferPeer} via
 * `tsigId`.
 *
 * Requires the Secondary DNS (zone transfer) entitlement on the
 * account. All fields are mutable in place; the secret is redacted and
 * never persisted in attributes.
 * ### Creating a TSIG
 * **Example:** HMAC-SHA512 key
 * ```typescript
 * const tsig = yield* Cloudflare.DNS.ZoneTransferTsig("TransferKey", {
 *   algo: "hmac-sha512.",
 *   secret: Redacted.make(process.env.TSIG_SECRET!),
 * });
 * ```
 *
 * ### Using with a Peer
 * **Example:** Authenticate transfers from a primary nameserver
 * ```typescript
 * const peer = yield* Cloudflare.DNS.ZoneTransferPeer("Primary", {
 *   ip: "192.0.2.53",
 *   port: 53,
 *   tsigId: tsig.tsigId,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/dns/zone-setups/zone-transfers/
 *
 * @resource
 * @product DNS
 * @category Domains & DNS
 */
export const ZoneTransferTsig = Resource<ZoneTransferTsig>(TypeId, {
  aliases: ["Cloudflare.Dns.ZoneTransferTsig"],
});

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

export const ZoneTransferTsigProvider = () =>
  Provider.succeed(ZoneTransferTsig, {
    stables: ["tsigId", "accountId"],

    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output !== undefined && output.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?.tsigId) {
        const observed = yield* getTsig(acct, output.tsigId);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — recover from lost state by matching the
      // deterministic physical name. TSIGs carry no ownership markers,
      // so gate takeover behind adoption.
      const name = yield* createTsigName(id, olds?.name);
      const match = yield* findByName(acct, name);
      return match ? Unowned(toAttributes(match, acct)) : undefined;
    }),

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

      // Observe — the id cached on `output` is a hint, not a guarantee.
      const observed = output?.tsigId
        ? yield* getTsig(output.accountId ?? accountId, output.tsigId)
        : undefined;

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete). Names are not
        // unique, so there is no AlreadyExists race to tolerate.
        const created = yield* dns.createZoneTransferTsig({
          accountId,
          name,
          algo: news.algo,
          secret,
        });
        return toAttributes(created, accountId);
      }

      // Sync — PUT with the full body; skip the call on no delta. The
      // observed secret comes back from the GET, so the comparison is
      // exact (not a guess from `olds`).
      if (observed.name === name && observed.algo === news.algo && observed.secret === secret) {
        return toAttributes(observed, output?.accountId ?? accountId);
      }
      const updated = yield* dns.updateZoneTransferTsig({
        accountId: output?.accountId ?? accountId,
        tsigId: observed.id,
        name,
        algo: news.algo,
        secret,
      });
      return toAttributes(updated, output?.accountId ?? accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* dns
        .deleteZoneTransferTsig({
          accountId: output.accountId,
          tsigId: output.tsigId,
        })
        .pipe(Effect.catchTag("TsigNotFound", () => Effect.void));
    }),

    // Account collection — enumerate every TSIG in the account via the
    // account-scoped list API, paginate exhaustively, and hydrate each into
    // the same Attributes shape `read` returns (the secret is write-only and
    // never persisted).
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* dns.listZoneTransferTsigs.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((tsig) => toAttributes(tsig, accountId)),
          ),
        ),
      );
    }),
  });

type ObservedTsig =
  | dns.GetZoneTransferTsigResponse
  | dns.CreateZoneTransferTsigResponse
  | dns.UpdateZoneTransferTsigResponse;

/** Read a TSIG by id, mapping "gone" (404) to `undefined`. */
const getTsig = (accountId: string, tsigId: string) =>
  dns
    .getZoneTransferTsig({ accountId, tsigId })
    .pipe(Effect.catchTag("TsigNotFound", () => Effect.undefined));

/**
 * Find a TSIG by exact name. Names are not unique on Cloudflare's side;
 * pick the lexicographically-first id for determinism.
 */
const findByName = (accountId: string, name: string) =>
  dns.listZoneTransferTsigs.items({ accountId }).pipe(
    Stream.filter((t) => t.name === name),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => a.id.localeCompare(b.id))
        .at(0),
    ),
  );

const createTsigName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    // A TSIG name is a domain name, so a generated one is a single label of at
    // most 63 characters.
    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 63 }));
  });

const toAttributes = (
  tsig: Pick<ObservedTsig, "id" | "name" | "algo">,
  accountId: string,
): ZoneTransferTsigAttributes => ({
  tsigId: tsig.id,
  accountId,
  name: tsig.name,
  algo: tsig.algo,
});