@homeflare/alchemy 0.48.0 → 0.49.0

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)),
+      });
+    }),
+  );

package/src/cloudflare/fake-access.ts

@@ -0,0 +1,196 @@
+/**
+ * A fake Cloudflare Access applications API for the SaasOidcApplication tests — an in-memory
+ * `fetch` handed to Effect's real FetchHttpClient (see fake-mesh.ts, which this mirrors), so the
+ * tests exercise distilled's real path assembly, body encoding and envelope decoding AND the raw
+ * read in saas-oidc-api.ts.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. Any request outside
+ *   `/accounts/<FAKE_ACCOUNT>/access/apps` throws, so a mis-wired test fails instead of reaching a
+ *   real API. Every credential-looking value is a placeholder.
+ * ★ THE WIRE IS CLOUDFLARE'S, snake_case: `saas_app`, `client_id`, `redirect_uris`… The create
+ *   response carries `saas_app.client_secret` (the SDK schema's own doc: "only returned on POST
+ *   request"); a GET and a PUT never do. So a test that asserts the secret appears nowhere is
+ *   asserting against a fake that does hand it out once.
+ * ★ THE LIST IS PAGES OF TWO by default, so every name lookup walks more than one page.
+ * ★ THE ORGANIZATION READ (`GET /access/organizations`, the pre-create team check) answers with the
+ *   fake's own team by default; `org` makes it answer a different domain, a 403 in either of the
+ *   two shapes a token without the permission can get (code 10000 and 10001, see
+ *   saas-oidc-team.ts), or a 404.
+ * ★ `malformed` makes the named calls answer a 2xx body the SDK's STRICT validation cannot decode,
+ *   with `FAKE_CLIENT_SECRET` planted in it, so a test can force `CloudflareParseError` and look
+ *   for the secret in what this package throws. ⚠️ ONLY THE CALLS rc.13 TYPES CAN BE MADE TO FAIL:
+ *   a create or update response decodes against `S.Unknown` (zero_trust.ts:35025, :210218), which
+ *   accepts anything, so those two are not offered here (saas-oidc-parse-error.test.ts reaches them
+ *   through the `sdkWrites` seam instead). `list` fails by answering an object where an array is
+ *   expected, `delete` and `org` by answering a number where the schema wants a string.
+ */
+import { FAKE_ACCOUNT, fakeFailure } from './fake-mesh.ts';
+
+export const TEAM = 'example.cloudflareaccess.com';
+/** ⚠️ A placeholder, not a credential. Tests assert it is stored and logged nowhere. */
+export const FAKE_CLIENT_SECRET = 'fake-client-secret-0123456789abcdef';
+
+export type FakeApp = {
+  id: string;
+  aud: string;
+  type: string;
+  name: string;
+  session_duration: string;
+  policies: string[];
+  saas_app?: Record<string, unknown> | undefined;
+};
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+/** The calls `malformed` can corrupt: `get` is the raw read, the rest are SDK calls. */
+export type FakeOp = 'get' | 'list' | 'delete' | 'org';
+/** How the organization read answers; an object names the `auth_domain` it returns. */
+export type FakeOrg =
+  | 'matching'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'not_found'
+  | { authDomain: string };
+
+export type FakeOptions = {
+  readonly perPage?: number;
+  readonly team?: string;
+  readonly org?: FakeOrg;
+  readonly malformed?: ReadonlyArray<FakeOp>;
+};
+
+const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
+  Response.json({ success: true, errors: [], messages: [], result, ...extra });
+
+/** The wire shape of an app: no `client_secret`, and `domain` as Cloudflare derives it. */
+const wire = (app: FakeApp, team: string) => {
+  const clientId = app.saas_app?.['client_id'];
+  const { saas_app: saas, ...rest } = app;
+  const { client_secret: _secret, ...publicSaas } = saas ?? {};
+  return {
+    ...rest,
+    domain: typeof clientId === 'string' ? `${team}/cdn-cgi/access/sso/oidc/${clientId}` : 'x.test',
+    created_at: '2026-10-09T00:00:00Z',
+    updated_at: '2026-10-09T00:00:00Z',
+    policies: app.policies.map((id, i) => ({ id, precedence: i + 1 })),
+    ...(saas === undefined ? {} : { saas_app: publicSaas }),
+  };
+};
+
+/**
+ * A 2xx `result` the typed decoders reject (`id` and `auth_domain` are numbers, and it is not an
+ * array), carrying the secret where a create puts it.
+ */
+const garbage = () => ({
+  id: 12345,
+  auth_domain: 12345,
+  client_secret: FAKE_CLIENT_SECRET,
+  saas_app: { client_secret: FAKE_CLIENT_SECRET },
+});
+
+const orgBody = (org: FakeOrg, team: string): Response => {
+  if (org === 'unauthorized') return fakeFailure(403, 10000, 'Authentication error');
+  if (org === 'forbidden') return fakeFailure(403, 10001, 'Method not allowed for token');
+  if (org === 'not_found') return fakeFailure(404, 12004, 'access.api.error.not_found');
+  const authDomain = org === 'matching' ? team : org.authDomain;
+  return ok({ auth_domain: authDomain, name: 'team', session_duration: '24h' });
+};
+
+export const fakeAccess = (options: FakeOptions = {}) => {
+  const team = options.team ?? TEAM;
+  const broken = (op: FakeOp): boolean => options.malformed?.includes(op) ?? false;
+  const apps = new Map<string, FakeApp>();
+  const seen: Seen[] = [];
+  let next = 1;
+
+  const seed = (app: Partial<FakeApp> & { name: string }): FakeApp => {
+    const n = String(next++).padStart(12, '0');
+    const full: FakeApp = {
+      id: `00000000-0000-4000-8000-${n}`,
+      aud: `aud-${n}`,
+      type: 'saas',
+      session_duration: '24h',
+      policies: [],
+      ...app,
+    };
+    if (full.type === 'saas' && full.saas_app?.['client_id'] === undefined) {
+      full.saas_app = { auth_type: 'oidc', client_id: `client-${n}`, ...full.saas_app };
+    }
+    apps.set(full.id, full);
+    return full;
+  };
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const prefix = `/client/v4/accounts/${FAKE_ACCOUNT}/access/apps`;
+    if (
+      url.host === 'api.example.com' &&
+      url.pathname === prefix.replace(/apps$/, 'organizations')
+    ) {
+      if (method !== 'GET') throw new Error(`fake-access: unexpected ${method} ${url.pathname}`);
+      return broken('org') ? ok(garbage()) : orgBody(options.org ?? 'matching', team);
+    }
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(prefix)) {
+      throw new Error(`fake-access: unexpected request ${method} ${url.href}`);
+    }
+    const id = url.pathname.slice(prefix.length).split('/').filter(Boolean)[0];
+    if (id === undefined && method === 'GET') {
+      if (broken('list')) return ok(garbage());
+      const page = Number(url.searchParams.get('page') ?? '1');
+      const perPage = Number(url.searchParams.get('per_page') ?? options.perPage ?? 2);
+      const all = [...apps.values()];
+      const slice = all.slice((page - 1) * perPage, page * perPage);
+      return ok(
+        slice.map((app) => wire(app, team)),
+        {
+          result_info: { page, per_page: perPage, count: slice.length, total_count: all.length },
+        },
+      );
+    }
+    if (id === undefined && method === 'POST') {
+      const app = seed({
+        name: String(body['name']),
+        type: String(body['type']),
+        policies: (body['policies'] as string[] | undefined) ?? [],
+        saas_app: body['saas_app'] as Record<string, unknown> | undefined,
+      });
+      // ⛔ The one response that hands the secret out, as the API does on POST.
+      const created = wire(app, team) as Record<string, unknown>;
+      created['saas_app'] = {
+        ...(created['saas_app'] as object),
+        client_secret: FAKE_CLIENT_SECRET,
+      };
+      return ok(created);
+    }
+    const app = id === undefined ? undefined : apps.get(id);
+    if (app === undefined) return fakeFailure(404, 12006, 'access.api.error.unknown_application');
+    if (method === 'GET') {
+      return broken('get') ? new Response(`not json ${FAKE_CLIENT_SECRET}`) : ok(wire(app, team));
+    }
+    if (method === 'PUT') {
+      app.name = String(body['name']);
+      app.policies = (body['policies'] as string[] | undefined) ?? [];
+      app.saas_app = { ...app.saas_app, ...(body['saas_app'] as Record<string, unknown>) };
+      return ok(wire(app, team));
+    }
+    if (method === 'DELETE') {
+      if (broken('delete')) return ok(garbage());
+      apps.delete(app.id);
+      return ok({ id: app.id });
+    }
+    throw new Error(`fake-access: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}`, body });
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { apps, fetch, seed, seen, team };
+};
+
+export type FakeAccess = ReturnType<typeof fakeAccess>;

package/src/cloudflare/fake-mesh.ts

@@ -37,7 +37,7 @@ export type FakeNode = {
 
 export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
 
-const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
+export const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
   Response.json({ success: true, errors: [], messages: [], result, ...extra });
 
 export const fakeFailure = (status: number, code: number, message: string) =>
@@ -153,7 +153,7 @@ export type FakeMesh = ReturnType<typeof fakeMesh>;
 
 /** distilled Credentials + the real FetchHttpClient over the fake — what a Bun script provides. */
 export const fakeClientLayer = (
-  fake: FakeMesh,
+  fake: { readonly fetch: typeof globalThis.fetch },
   credentials: Layer.Layer<Credentials> = fromApiToken({
     apiToken: FAKE_API_TOKEN,
     apiBaseUrl: FAKE_BASE,
@@ -166,7 +166,10 @@ export const fakeClientLayer = (
   );
 
 /** …plus the account, as Alchemy's CloudflareEnvironment hands it to a provider. */
-export const fakeProviderLayer = (fake: FakeMesh, accountId: string = FAKE_ACCOUNT) =>
+export const fakeProviderLayer = (
+  fake: { readonly fetch: typeof globalThis.fetch },
+  accountId: string = FAKE_ACCOUNT,
+) =>
   Layer.mergeAll(
     fakeClientLayer(fake),
     Layer.succeed(

package/src/cloudflare/fake-tunnel.ts

@@ -0,0 +1,148 @@
+/**
+ * A fake Cloudflare `cfd_tunnel` API for the CloudflaredTunnel tests — an in-memory `fetch` handed
+ * to Effect's real FetchHttpClient, the same way fake-mesh.ts does it, so the tests exercise
+ * distilled's real path assembly, query and body encoding, envelope decoding and error matching.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. Any request outside
+ *   `/accounts/<FAKE_ACCOUNT>/cfd_tunnel` or `/accounts/<FAKE_ACCOUNT>/tunnels` throws, so a
+ *   mis-wired test fails instead of reaching a real API.
+ * ★ THE FAKE HANDS OUT A TOKEN ON EVERY SURFACE IT CAN: a `token` field on the create response and
+ *   on every wire object (worst case: if Cloudflare ever adds one to the documented shape), and the
+ *   `/token` endpoint. The tests then prove none of it reaches an attribute, a state row or a
+ *   request log. The SDK's decoder drops fields outside its schema; the provider must not depend on
+ *   that alone.
+ * ★ THE NAME FILTER IS A SUBSTRING MATCH, as in fake-mesh.ts, so the client's exact re-check is
+ *   exercised. `/tunnels` honours `tun_types` and `is_deleted` as the SDK documents them, and
+ *   answers pages of two by default.
+ */
+import { FAKE_ACCOUNT, type Seen, fakeFailure, ok } from './fake-mesh.ts';
+
+export type FakeTunnel = {
+  id: string;
+  name: string;
+  tun_type: string;
+  config_src: string;
+  status: string;
+  token: string;
+  deleted_at: string | null;
+  /** The fake refuses a DELETE while this is set, as the SDK doc says it must ("no active connections"). */
+  connected: boolean;
+};
+
+const wire = (tunnel: FakeTunnel) => ({
+  id: tunnel.id,
+  account_tag: FAKE_ACCOUNT,
+  config_src: tunnel.config_src,
+  created_at: '2026-10-09T00:00:00Z',
+  deleted_at: tunnel.deleted_at,
+  name: tunnel.name,
+  status: tunnel.status,
+  tun_type: tunnel.tun_type,
+  token: tunnel.token,
+});
+
+export type FakeTunnelOptions = {
+  readonly perPage?: number;
+  /** Return a Response to answer the POST with it instead (e.g. `fakeFailure(409, 1013, …)`). */
+  readonly onCreate?: (name: string) => Response | void;
+  /** Return a Response to answer the DELETE with it instead (e.g. the tunnel vanishing mid-delete). */
+  readonly onDelete?: (id: string) => Response | void;
+};
+
+export const fakeTunnels = (options: FakeTunnelOptions = {}) => {
+  const tunnels = new Map<string, FakeTunnel>();
+  const seen: Seen[] = [];
+  const auth: string[] = [];
+  let next = 1;
+  const live = () => [...tunnels.values()].filter((t) => t.deleted_at === null);
+
+  const seed = (tunnel: Partial<FakeTunnel> & { name: string }): FakeTunnel => {
+    const id = tunnel.id ?? `00000000-0000-4000-9000-${String(next++).padStart(12, '0')}`;
+    const full: FakeTunnel = {
+      id,
+      tun_type: 'cfd_tunnel',
+      config_src: 'cloudflare',
+      status: 'inactive',
+      token: `fake-tunnel-token-${id}`,
+      deleted_at: null,
+      connected: false,
+      ...tunnel,
+    };
+    tunnels.set(id, full);
+    return full;
+  };
+
+  const list = (url: URL): Response => {
+    const filter = url.searchParams.get('name') ?? '';
+    const types = (url.searchParams.get('tun_types') ?? '').split(',').filter(Boolean);
+    const isDeleted = url.searchParams.get('is_deleted');
+    const page = Number(url.searchParams.get('page') ?? '1');
+    const perPage = Number(url.searchParams.get('per_page') ?? options.perPage ?? 2);
+    const hits = [...tunnels.values()]
+      .filter((t) => types.length === 0 || types.includes(t.tun_type))
+      .filter((t) => isDeleted === null || (t.deleted_at !== null) === (isDeleted === 'true'))
+      .filter((t) => t.name.includes(filter));
+    const slice = hits.slice((page - 1) * perPage, page * perPage);
+    return ok(slice.map(wire), { result_info: { page, per_page: perPage, count: slice.length } });
+  };
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const base = `/client/v4/accounts/${FAKE_ACCOUNT}`;
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(base)) {
+      throw new Error(`fake-tunnel: unexpected request ${method} ${url.href}`);
+    }
+    const rest = url.pathname.slice(base.length);
+    if (rest === '/tunnels' && method === 'GET') return list(url);
+    if (!rest.startsWith('/cfd_tunnel')) {
+      throw new Error(`fake-tunnel: unexpected ${method} ${url.pathname}`);
+    }
+    const [id, sub] = rest.slice('/cfd_tunnel'.length).split('/').filter(Boolean);
+    if (id === undefined && method === 'POST') {
+      const name = String(body['name']);
+      const override = options.onCreate?.(name);
+      if (override !== undefined) return override;
+      if (live().some((t) => t.name === name)) {
+        return fakeFailure(409, 1013, 'tunnel with name already exists');
+      }
+      const tunnel = seed({ name, config_src: String(body['config_src'] ?? 'local') });
+      return ok(wire(tunnel));
+    }
+    const tunnel = id === undefined ? undefined : tunnels.get(id);
+    if (tunnel === undefined) return fakeFailure(404, 1002, 'Tunnel not found');
+    if (sub === 'token' && method === 'GET') return ok(tunnel.token);
+    if (sub !== undefined) throw new Error(`fake-tunnel: unexpected ${method} ${url.pathname}`);
+    if (method === 'GET') return ok(wire(tunnel));
+    if (method === 'PATCH') {
+      const name = String(body['name']);
+      if (live().some((other) => other.name === name && other.id !== tunnel.id)) {
+        return fakeFailure(409, 1013, 'tunnel with name already exists');
+      }
+      tunnel.name = name;
+      return ok(wire(tunnel));
+    }
+    if (method === 'DELETE') {
+      const override = options.onDelete?.(tunnel.id);
+      if (override !== undefined) return override;
+      if (tunnel.deleted_at !== null) return fakeFailure(404, 1002, 'Tunnel not found');
+      if (tunnel.connected) return fakeFailure(400, 1000, 'tunnel has active connections');
+      tunnel.deleted_at = '2026-10-09T01:00:00Z';
+      return ok(wire(tunnel));
+    }
+    throw new Error(`fake-tunnel: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}`, body });
+    auth.push(request.headers.get('authorization') ?? '');
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { auth, fetch, live, tunnels, seed, seen };
+};
+
+export type FakeTunnels = ReturnType<typeof fakeTunnels>;