@homeflare/alchemy 0.48.1 → 0.49.0

package/src/cloudflare/cloudflared-tunnel-harness.ts

@@ -0,0 +1,126 @@
+/**
+ * CloudflaredTunnelProvider's handlers, called the way the engine calls them, over the fake
+ * Cloudflare in fake-tunnel.ts — and `engine`, which runs Alchemy's real plan/apply over the same
+ * fake and exposes the state rows it wrote. Shared by cloudflared-tunnel.test.ts,
+ * cloudflared-tunnel-edges.test.ts and cloudflared-tunnel-state.test.ts.
+ *
+ * ⛔ TEST-ONLY, like fake-tunnel.ts: no provider imports this file and it is not on the barrel.
+ */
+import { apply } from 'alchemy/Apply';
+import * as Plan from 'alchemy/Plan';
+import { type CompiledStack, make as makeStack } from 'alchemy/Stack';
+import { Stage } from 'alchemy/Stage';
+import * as State from 'alchemy/State';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import { CloudflaredTunnel, CloudflaredTunnelProvider } from './cloudflared-tunnel.ts';
+import type {
+  CloudflaredTunnelAttributes,
+  CloudflaredTunnelProps,
+} from './cloudflared-tunnel-form.ts';
+import { fakeProviderLayer } from './fake-mesh.ts';
+import type { FakeTunnels } from './fake-tunnel.ts';
+
+export const ids = { fqn: 'stack/admin', id: 'admin', instanceId: 'i-1' };
+export const extra = { bindings: [] as never, session: undefined as never };
+
+export type P = Effect.Success<typeof CloudflaredTunnel.Provider>;
+
+export const handler = <F>(name: string, fn: F | undefined): F => {
+  if (fn === undefined) throw new Error(`provider has no ${name} handler`);
+  return fn;
+};
+
+/** Build the provider over the fake (as `accountId`'s environment) and hand it to `use`. */
+export const run = <A, E>(
+  fake: FakeTunnels,
+  use: (p: P) => Effect.Effect<A, E>,
+  accountId?: string,
+) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* CloudflaredTunnel.Provider);
+    }).pipe(
+      Effect.provide(
+        CloudflaredTunnelProvider().pipe(Layer.provideMerge(fakeProviderLayer(fake, accountId))),
+      ),
+    ),
+  );
+
+export const reconcile = (
+  p: P,
+  news: CloudflaredTunnelProps,
+  output?: CloudflaredTunnelAttributes,
+) => p.reconcile({ ...ids, ...extra, news, olds: undefined, output });
+
+export const read = (p: P, olds: CloudflaredTunnelProps, output?: CloudflaredTunnelAttributes) =>
+  handler('read', p.read)({ ...ids, olds, output });
+
+export const diff = (
+  p: P,
+  news: CloudflaredTunnelProps,
+  olds: CloudflaredTunnelProps,
+  output: CloudflaredTunnelAttributes,
+) =>
+  handler(
+    'diff',
+    p.diff,
+  )({ ...ids, news, olds, newBindings: [] as never, oldBindings: [] as never, output });
+
+/** A stored attribute set for a tunnel that may or may not exist in the fake. */
+export const stored = (
+  accountId: string,
+  over: Partial<CloudflaredTunnelAttributes> = {},
+): CloudflaredTunnelAttributes => ({
+  id: 'x',
+  accountId,
+  name: 'k8s-admin',
+  ...over,
+});
+
+/** Requests the fake saw for any `/token` path. The provider must never make one. */
+export const tokenReads = (fake: FakeTunnels) =>
+  fake.seen.filter((s) => s.path.includes('/token')).length;
+
+/** The writes the fake saw, in order: `['POST', 'DELETE', …]`. */
+export const writes = (fake: FakeTunnels) =>
+  fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method);
+
+type Rows = Record<string, Record<string, Record<string, State.ResourceState>>>;
+
+/**
+ * ★ THE REAL ENGINE, NOT A MODEL OF IT: Alchemy's own `Plan.make` + `apply` over an in-memory
+ *   state store (the same construction as mesh-node-harness.ts, which says why
+ *   `FetchHttpClient.Fetch` is provided around the whole deploy). `rows` is the store itself, so a
+ *   test can serialize exactly what Alchemy would persist.
+ */
+export const engine = (fake: FakeTunnels) => {
+  const rows: Rows = {};
+  const state = Layer.succeed(State.State, State.InMemoryService(rows));
+  const providers = CloudflaredTunnelProvider().pipe(Layer.provide(fakeProviderLayer(fake)));
+  const deploy = <A, E, R>(declare: Effect.Effect<A, E, R>) =>
+    Effect.runPromiseExit(
+      declare.pipe(
+        makeStack({ name: 'tunnel', providers, state }) as never,
+        Effect.flatMap((compiled: CompiledStack) =>
+          Plan.make(compiled).pipe(Effect.flatMap(apply), Effect.provide(compiled.services)),
+        ),
+        Effect.provide(Layer.succeed(Stage, 'test')),
+        Effect.scoped,
+        Effect.provideService(FetchHttpClient.Fetch, fake.fetch),
+      ) as Effect.Effect<unknown, unknown>,
+    );
+  return {
+    deploy,
+    rows,
+    /** The stored row's status (`created`, `replacing`, …), or `undefined` when there is none. */
+    status: (fqn: string) => rows['tunnel']?.['test']?.[fqn]?.status,
+  };
+};
+
+/** The failure sentence of a deploy, or `''` when it succeeded. */
+export const failureOf = (exit: Exit.Exit<unknown, unknown>) =>
+  Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : '';

package/src/cloudflare/cloudflared-tunnel-lifecycle.ts

@@ -0,0 +1,146 @@
+/**
+ * read / reconcile / delete for `Cloudflare.CloudflaredTunnel`, as plain Effects over the SDK calls
+ * in cloudflared-tunnel-api.ts. cloudflared-tunnel.ts only wires them into Alchemy.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import {
+  CloudflaredTunnelError,
+  type ObservedTunnel,
+  createTunnel,
+  deleteTunnel,
+  findTunnelByName,
+  getTunnel,
+  renameTunnel,
+} from './cloudflared-tunnel-api.ts';
+import {
+  type CloudflaredTunnelAttributes,
+  type CloudflaredTunnelProps,
+  validateCloudflaredTunnel,
+} from './cloudflared-tunnel-form.ts';
+
+const attributesOf = (tunnel: ObservedTunnel, accountId: string): CloudflaredTunnelAttributes => ({
+  id: tunnel.id,
+  accountId,
+  name: tunnel.name,
+});
+
+/**
+ * Owned: refresh by the stored id. Cold (no stored row): find the live tunnel by exact name and
+ * hand it back `Unowned`, so Alchemy refuses to take it over until the stack says `adopt(true)` —
+ * a `cfd_tunnel` carries no ownership marker to prove it was ours. Adoption is idempotent: the
+ * adopted row holds the id, so every later `read` takes the owned path and writes nothing.
+ *
+ * ⛔ A STORED ID THAT NO LONGER RESOLVES IS "MISSING", NEVER A NAME PROBE. Drift (alchemy beta.81
+ *   src/Drift.ts) passes the row's output and treats whatever `read` returns as already ours
+ *   (`stripUnowned`), then repairs by reconciling onto it. A by-name fallback there would write a
+ *   same-named tunnel somebody else made into this row, bypassing `adopt(true)`; a later rename
+ *   would PATCH it and `RemovalPolicy.destroy` would DELETE it. Returning `undefined` makes Drift
+ *   report "missing" and recreate through `reconcile`, where `createFresh` names the holder.
+ */
+export const readCloudflaredTunnel = (
+  accountId: string,
+  olds: CloudflaredTunnelProps | undefined,
+  output: CloudflaredTunnelAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const account = output?.accountId ?? accountId;
+    if (output !== undefined) {
+      const tunnel = yield* getTunnel(account, output.id);
+      return tunnel === undefined ? undefined : attributesOf(tunnel, account);
+    }
+    const name = olds?.name;
+    if (name === undefined) return undefined;
+    const match = yield* findTunnelByName(account, name);
+    return match === undefined ? undefined : Unowned(attributesOf(match, account));
+  });
+
+/**
+ * ⛔ NEVER CONVERGE ON A TUNNEL THIS RESOURCE DID NOT FIND BY ITS OWN ID. Alchemy's own Tunnel
+ *   answers a duplicate-name failure by re-reading the holder and returning it (when its `adopt`
+ *   prop is set). Here adoption belongs to `read` and `adopt(true)` alone, where it is visible in
+ *   the plan. The holder is named, never deleted: it may be a live tunnel that serves traffic.
+ */
+const nameHeld = (name: string, holder: string) =>
+  new CloudflaredTunnelError({
+    message:
+      `A tunnel named "${name}" already exists (${holder}) and is not the tunnel this resource ` +
+      'tracks, so it is left alone: names are unique per account. If it is meant to be this ' +
+      'one, deploy under adopt(true). Otherwise choose another name; do not delete it.',
+  });
+
+/**
+ * 🔴 A 1013 AFTER A CLEAN LOOKUP IS USUALLY THIS DEPLOY'S OWN TUNNEL. distilled retries a POST on a
+ *   transport error or a 5xx, so a create that succeeded but lost its response is sent again and
+ *   answered 1013 by the tunnel the first attempt made. The lookup is repeated so the sentence
+ *   names that tunnel; it is still not adopted here, because a concurrent creator looks the same.
+ */
+const raced = (accountId: string, name: string) =>
+  findTunnelByName(accountId, name).pipe(
+    Effect.flatMap((holder) =>
+      Effect.fail(
+        holder === undefined
+          ? nameHeld(
+              name,
+              'not a live cloudflared tunnel: another tunnel type, or one just deleted',
+            )
+          : new CloudflaredTunnelError({
+              message:
+                `Tunnel "${name}" (${holder.id}) appeared between this deploy's lookup and its ` +
+                'create. The likeliest cause is this deploy itself: the SDK retries a create ' +
+                'whose response was lost. If so, deploy again under adopt(true). Otherwise ' +
+                'another creator raced this one.',
+            }),
+      ),
+    ),
+  );
+
+const createFresh = (accountId: string, name: string) =>
+  Effect.gen(function* () {
+    const existing = yield* findTunnelByName(accountId, name);
+    if (existing !== undefined) return yield* Effect.fail(nameHeld(name, existing.id));
+    const tunnel = yield* createTunnel(accountId, name).pipe(
+      Effect.catchTag('DuplicateTunnelName', () => raced(accountId, name)),
+    );
+    return attributesOf(tunnel, accountId);
+  });
+
+/**
+ * ⛔ `local` IS REFUSED. A tunnel's `config_src` is create-only, and adoption by name could land on
+ *   a locally configured tunnel, whose ingress is a YAML file on its origin: a consumer's remote
+ *   rules would be accepted by the API and never applied. The tunnel is left untouched.
+ */
+const requireRemote = (tunnel: ObservedTunnel) =>
+  tunnel.configSrc === 'local'
+    ? Effect.fail(
+        new CloudflaredTunnelError({
+          message: `Tunnel "${tunnel.name}" (${tunnel.id}) is locally configured (config_src local), which cannot be changed after creation. CloudflaredTunnel manages remotely configured tunnels only; create a new tunnel under another name.`,
+        }),
+      )
+    : Effect.void;
+
+export const reconcileCloudflaredTunnel = (
+  accountId: string,
+  news: CloudflaredTunnelProps,
+  output: CloudflaredTunnelAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const invalid = validateCloudflaredTunnel(news);
+    if (invalid !== undefined) return yield* Effect.fail(invalid);
+    const owned = output !== undefined && output.accountId === accountId ? output : undefined;
+    const live = owned === undefined ? undefined : yield* getTunnel(accountId, owned.id);
+    // ★ Gone out of band (or a replace's new generation): create, under the same refusals.
+    if (owned === undefined || live === undefined) return yield* createFresh(accountId, news.name);
+    yield* requireRemote(live);
+    if (live.name === news.name) return attributesOf(live, accountId);
+    const renamed = yield* renameTunnel(accountId, live.id, news.name).pipe(
+      Effect.catchTag('DuplicateTunnelName', () =>
+        Effect.fail(nameHeld(news.name, 'held by another tunnel')),
+      ),
+    );
+    return attributesOf(renamed, accountId);
+  });
+
+/** By the stored id and account only (cloudflared-tunnel-api.ts, `deleteTunnel`). */
+export const deleteCloudflaredTunnel = (output: CloudflaredTunnelAttributes) =>
+  deleteTunnel(output.accountId, output.id);

package/src/cloudflare/cloudflared-tunnel-state.test.ts

@@ -0,0 +1,104 @@
+/**
+ * What Alchemy WRITES for a CloudflaredTunnel, through the real engine (`engine` in
+ * cloudflared-tunnel-harness.ts) over the fake Cloudflare: the serialization proof the resource
+ * exists for, plus the removal policy and adoption, which live in the engine, not the provider.
+ *
+ * ⛔ THE PROOF: the rows in the state store, encoded by Alchemy's own `encodeState` (the function
+ *   LocalState, HttpStateStore and PostgresState all call before writing), contain no `__redacted__`
+ *   marker, no `token` key and no token value — and the fake handed out a token on the create
+ *   response, every wire object and its `/token` endpoint. A negative control shows the same
+ *   encoder DOES write a `Redacted` token as plaintext, so the absence above means something.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as State from 'alchemy/State';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { CloudflaredTunnel } from './cloudflared-tunnel.ts';
+import { engine, failureOf, tokenReads, writes } from './cloudflared-tunnel-harness.ts';
+import { fakeTunnels } from './fake-tunnel.ts';
+
+const ADMIN = 'admin';
+const admin = (name = 'k8s-admin') => CloudflaredTunnel(ADMIN, { name });
+
+const persisted = (rows: object) => JSON.stringify(State.encodeState(rows));
+
+describe('CloudflaredTunnel state serialization', () => {
+  test('the persisted state holds no token, no __redacted__ marker and no secret field', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(admin()))).toBe('');
+    // A second deploy re-reads and re-reconciles: the paths Alchemy's own Tunnel reads the token on.
+    expect(failureOf(await stack.deploy(admin('k8s-admin-2')))).toBe('');
+    const [tunnel] = fake.live();
+    const json = persisted(stack.rows);
+    expect(json).toContain(tunnel?.id ?? 'no tunnel');
+    expect(json).not.toContain(State.REDACTED_MARKER);
+    expect(json).not.toContain(tunnel?.token ?? 'no tunnel');
+    expect(json).not.toContain('fake-tunnel-token');
+    expect(json.toLowerCase()).not.toContain('token');
+    expect(json.toLowerCase()).not.toContain('secret');
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('the attributes in the row are exactly id, accountId and name', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin());
+    const row = stack.rows['tunnel']?.['test']?.[ADMIN] as { attr?: object } | undefined;
+    expect(Object.keys(row?.attr ?? {}).sort()).toEqual(['accountId', 'id', 'name']);
+  });
+
+  test('negative control: the same encoder writes a Redacted token as a plaintext marker', () => {
+    const json = persisted({ attr: { token: Redacted.make('t0ken') } });
+    expect(json).toContain(State.REDACTED_MARKER);
+    expect(json).toContain('t0ken');
+  });
+});
+
+describe('CloudflaredTunnel through the real engine', () => {
+  test('retain is the default: dropping the declaration leaves the tunnel and sends no DELETE', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin());
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(stack.status(ADMIN)).toBeUndefined();
+    expect(fake.live()).toHaveLength(1);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('RemovalPolicy.destroy() still reaches the implemented delete', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin().pipe(RemovalPolicy.destroy()));
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(fake.live()).toHaveLength(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE']);
+  });
+
+  test('a rename deploys as a PATCH on the same tunnel', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin());
+    const [before] = fake.live();
+    expect(failureOf(await stack.deploy(admin('k8s-admin-2')))).toBe('');
+    expect(fake.live().map((t) => [t.id, t.name])).toEqual([[before?.id ?? '', 'k8s-admin-2']]);
+    expect(writes(fake)).toEqual(['POST', 'PATCH']);
+  });
+
+  test('an existing tunnel is refused without adopt(true), adopted with it, and a repeat writes nothing', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', status: 'healthy' });
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(admin()))).not.toBe('');
+    expect(writes(fake)).toEqual([]);
+    expect(failureOf(await stack.deploy(admin().pipe(adopt(true))))).toBe('');
+    expect(failureOf(await stack.deploy(admin().pipe(adopt(true))))).toBe('');
+    expect(writes(fake)).toEqual([]);
+    expect(fake.live().map((t) => t.id)).toEqual([tunnel.id]);
+    expect(tokenReads(fake)).toBe(0);
+    const row = stack.rows['tunnel']?.['test']?.[ADMIN] as { attr?: { id?: string } } | undefined;
+    expect(row?.attr?.id).toBe(tunnel.id);
+  });
+});

package/src/cloudflare/cloudflared-tunnel.test.ts

@@ -0,0 +1,164 @@
+/**
+ * CloudflaredTunnelProvider against a fake Cloudflare (fake-tunnel.ts), its handlers called the way
+ * the engine calls them.
+ *
+ * ⛔ THE ASSERTION THAT MATTERS MOST: no lifecycle handler ever requests `/token`, and nothing the
+ *   provider returns contains the tunnel token — even though the fake puts one on every wire object.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { StackServices } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import {
+  diff,
+  extra,
+  ids,
+  read,
+  reconcile,
+  run,
+  stored,
+  tokenReads,
+  writes,
+} from './cloudflared-tunnel-harness.ts';
+import { FAKE_ACCOUNT, FAKE_API_TOKEN } from './fake-mesh.ts';
+import { fakeTunnels } from './fake-tunnel.ts';
+import { providers } from './providers.ts';
+
+// ⛔ Compile-time: a stack's `providers` must be `Layer<…, never, StackServices>`.
+type Built = Layer.Success<ReturnType<typeof providers>>;
+const _stackShaped: Layer.Layer<Built, never, StackServices> = providers();
+void _stackShaped;
+
+const props = { name: 'k8s-admin' };
+
+describe('CloudflaredTunnelProvider', () => {
+  test('create sends config_src cloudflare and no secret, and the attributes carry no token', async () => {
+    const fake = fakeTunnels();
+    const out = await run(fake, (p) => reconcile(p, props));
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(post?.body).toEqual({ name: 'k8s-admin', config_src: 'cloudflare' });
+    expect(out).toMatchObject({ name: 'k8s-admin', accountId: FAKE_ACCOUNT });
+    expect(Object.keys(out).sort()).toEqual(['accountId', 'id', 'name']);
+    expect(JSON.stringify(out)).not.toContain('fake-tunnel-token');
+    expect(tokenReads(fake)).toBe(0);
+    expect(new Set(fake.auth)).toEqual(new Set([`Bearer ${FAKE_API_TOKEN}`]));
+  });
+
+  test('read with state refreshes by id; without state it adopts by exact name, Unowned', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-admin-old' });
+    fake.seed({ name: 'k8s-admin-older' });
+    const tunnel = fake.seed({ name: 'k8s-admin', status: 'healthy' });
+    const [owned, probe] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = stored(FAKE_ACCOUNT, { id: tunnel.id });
+        return [yield* read(p, props, output), yield* read(p, props)] as const;
+      }),
+    );
+    expect(Unowned.is(owned)).toBe(false);
+    expect(owned).toMatchObject({ id: tunnel.id, name: 'k8s-admin' });
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ id: tunnel.id, name: 'k8s-admin' });
+    expect(tokenReads(fake)).toBe(0);
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('adopting twice is idempotent: the second reconcile over the adopted row writes nothing', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', status: 'healthy' });
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const adopted = yield* read(p, props);
+        expect(Unowned.is(adopted)).toBe(true);
+        const first = yield* reconcile(p, props, adopted);
+        return [first, yield* reconcile(p, props, first)] as const;
+      }),
+    );
+    expect(first).toEqual(second);
+    expect(first.id).toBe(tunnel.id);
+    expect(writes(fake)).toEqual([]);
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('a rename is a PATCH on the same id', async () => {
+    const fake = fakeTunnels();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, props);
+        return [first, yield* reconcile(p, { name: 'k8s-admin-2' }, first)] as const;
+      }),
+    );
+    expect(second.id).toBe(first.id);
+    expect(second.name).toBe('k8s-admin-2');
+    expect(writes(fake)).toEqual(['POST', 'PATCH']);
+    expect(fake.seen.find((s) => s.method === 'PATCH')?.body).toEqual({ name: 'k8s-admin-2' });
+  });
+
+  test('an unchanged tunnel costs no write', async () => {
+    const fake = fakeTunnels();
+    await run(fake, (p) => Effect.flatMap(reconcile(p, props), (out) => reconcile(p, props, out)));
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('a tunnel deleted out of band is created again', async () => {
+    const fake = fakeTunnels();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, props);
+        const tunnel = fake.tunnels.get(first.id);
+        if (tunnel !== undefined) tunnel.deleted_at = '2026-10-09T02:00:00Z';
+        return [first, yield* reconcile(p, props, first)] as const;
+      }),
+    );
+    expect(second.id).not.toBe(first.id);
+    expect(fake.live()).toHaveLength(1);
+  });
+
+  test('delete removes the tunnel by id, and deleting it again sends nothing', async () => {
+    const fake = fakeTunnels();
+    await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = yield* reconcile(p, props);
+        yield* p.delete({ ...ids, ...extra, olds: props, output });
+        yield* p.delete({ ...ids, ...extra, olds: props, output });
+      }),
+    );
+    expect(fake.live()).toHaveLength(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE']);
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('diff reads the account from the provider environment', async () => {
+    const fake = fakeTunnels();
+    const plan = (p: Parameters<typeof diff>[0]) => diff(p, props, props, stored(FAKE_ACCOUNT));
+    expect(await run(fake, plan)).toBeUndefined();
+    expect(await run(fake, plan, '00000000000000000000000000000002')).toEqual({
+      action: 'replace',
+    });
+    const renamed = await run(fake, (p) =>
+      diff(p, { name: 'k8s-admin-2' }, props, stored(FAKE_ACCOUNT)),
+    );
+    expect(renamed).toEqual({ action: 'update' });
+  });
+
+  test('an invalid declaration fails the PLAN', async () => {
+    const fake = fakeTunnels();
+    const failure = await run(fake, (p) =>
+      Effect.flip(diff(p, { name: 'k8s-admin ' }, props, stored(FAKE_ACCOUNT))),
+    );
+    expect(String(failure)).toContain('whitespace');
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('list is empty and nuke skips it: Alchemy Tunnel already enumerates these', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-admin' });
+    const [listed, nuke] = await run(fake, (p) =>
+      Effect.map(p.list(), (rows) => [rows, p.nuke] as const),
+    );
+    expect(listed).toEqual([]);
+    expect(nuke).toEqual({ skip: true });
+    expect(fake.seen).toHaveLength(0);
+  });
+});

package/src/cloudflare/cloudflared-tunnel.ts

@@ -0,0 +1,116 @@
+/**
+ * `Cloudflare.CloudflaredTunnel` — a Cloudflare Tunnel (the cloudflared kind, `cfd_tunnel`),
+ * declared without its connector token ever touching Alchemy state. Usage: docs/cloudflared-tunnel.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Tunnel.Tunnel`. Alchemy beta.81's resource stores the
+ *   token as a `Redacted` attribute, and the state encoder writes it out in plaintext. See
+ *   cloudflared-tunnel-form.ts, which also says what this resource leaves to other declarations.
+ *
+ * ★ REMOVAL POLICY: `retain` BY DEFAULT — see the ★ on `CloudflaredTunnel` below.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/http/HttpClient';
+import {
+  type CloudflaredTunnelAttributes,
+  type CloudflaredTunnelProps,
+  diffCloudflaredTunnel,
+  validateCloudflaredTunnel,
+} from './cloudflared-tunnel-form.ts';
+import {
+  deleteCloudflaredTunnel,
+  readCloudflaredTunnel,
+  reconcileCloudflaredTunnel,
+} from './cloudflared-tunnel-lifecycle.ts';
+import type { Providers } from './providers.ts';
+
+export interface CloudflaredTunnel extends Resource<
+  'Cloudflare.CloudflaredTunnel',
+  CloudflaredTunnelProps,
+  CloudflaredTunnelAttributes,
+  never,
+  Providers
+> {}
+
+/**
+ * ★ `defaultRemovalPolicy: 'retain'`, LIKE EVERY KIT RESOURCE WHOSE DELETION BREAKS ITS CONSUMERS
+ *   (MeshNode, the `Bao.*` families, `R2BucketLock`; the reasoning is written once in
+ *   proxmox/resource.ts). Deleting a tunnel drops its remote configuration (ingress rules) and
+ *   orphans every DNS record that targets `<id>.cfargotunnel.com`, and a new tunnel has a new id
+ *   and a new token. So dropping the declaration, or `alchemy destroy`, leaves the tunnel live.
+ * ⚠️ IT ALSO SKIPS THE OLD TUNNEL'S DELETE IN AN ACCOUNT-CHANGE REPLACE (create-first), which
+ *   leaves the old tunnel live and unmanaged (Apply.ts, `deleteOldGenerations`, beta.81).
+ * ⛔ `delete` STAYS FULLY IMPLEMENTED. Retain is Terraform's `prevent_destroy`, not a stub: it runs
+ *   the moment a declaration opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+export const CloudflaredTunnel: ResourceClass<CloudflaredTunnel> = Resource<CloudflaredTunnel>(
+  'Cloudflare.CloudflaredTunnel',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+/** What every call below needs: the account, credentials and HTTP — Alchemy's own trio. */
+export type CloudflaredTunnelServices =
+  | Cloudflare.CloudflareEnvironment
+  | Credentials
+  | HttpClient.HttpClient;
+
+/** The account id, resolved the way every `alchemy/Cloudflare` provider resolves it. */
+const accountId = Effect.gen(function* () {
+  const resolved = yield* yield* Cloudflare.CloudflareEnvironment;
+  return resolved.accountId;
+});
+
+/**
+ * ★ `Provider.effect`, CAPTURING THE THREE SERVICES AT BUILD, exactly as `MeshNodeProvider` does
+ *   (mesh-node.ts says why): correct whether or not the stack also merges `Cloudflare.providers()`.
+ */
+export const CloudflaredTunnelProvider = () =>
+  Provider.effect(
+    CloudflaredTunnel,
+    Effect.gen(function* () {
+      const services = Context.make(
+        Cloudflare.CloudflareEnvironment,
+        yield* Cloudflare.CloudflareEnvironment,
+      ).pipe(
+        Context.add(Credentials, yield* Credentials),
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      const run = <A, E>(effect: Effect.Effect<A, E, CloudflaredTunnelServices>) =>
+        Effect.provideContext(effect, services);
+
+      return CloudflaredTunnel.Provider.of({
+        stables: ['id', 'accountId'],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Tunnel.Tunnel` already lists every
+         *   `cfd_tunnel` in the account for `alchemy unsafe nuke` (and fetches each token to do
+         *   it); a second listing here would make nuke delete each tunnel twice. `read` does not
+         *   depend on this.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        /** ⛔ Validate at plan time too, so a bad declaration never reaches a replace. */
+        diff: ({ news, output }) =>
+          run(
+            Effect.gen(function* () {
+              const invalid = isResolved(news) ? validateCloudflaredTunnel(news) : undefined;
+              if (invalid !== undefined) return yield* Effect.fail(invalid);
+              return diffCloudflaredTunnel(news, output, yield* accountId);
+            }),
+          ),
+        read: ({ olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readCloudflaredTunnel(account, olds, output))),
+        reconcile: ({ news, output }) =>
+          run(
+            Effect.flatMap(accountId, (account) =>
+              reconcileCloudflaredTunnel(account, news, output),
+            ),
+          ),
+        delete: ({ output }) => run(deleteCloudflaredTunnel(output)),
+      });
+    }),
+  );