@homeflare/alchemy 0.5.0 → 0.7.0

package/src/cloudflare/mesh-node-harness.ts

@@ -0,0 +1,124 @@
+/**
+ * MeshNodeProvider's handlers, called the way the engine calls them, over the fake Cloudflare in
+ * fake-mesh.ts — and `engine`, which runs Alchemy's real plan/apply over the same fake. Shared by
+ * mesh-node.test.ts, mesh-node-edges.test.ts and mesh-node-policy.test.ts.
+ *
+ * ⛔ TEST-ONLY, like fake-mesh.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/unstable/http/FetchHttpClient';
+import { type FakeMesh, fakeProviderLayer } from './fake-mesh.ts';
+import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
+import type { MeshNodeAttributes, MeshNodeProps } from './mesh-node-form.ts';
+
+export const ids = { fqn: 'stack/door', id: 'door', instanceId: 'i-1' };
+export const extra = { bindings: [] as never, session: undefined as never };
+
+export type P = Effect.Success<typeof MeshNode.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: FakeMesh, use: (p: P) => Effect.Effect<A, E>, accountId?: string) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* MeshNode.Provider);
+    }).pipe(
+      Effect.provide(
+        MeshNodeProvider().pipe(Layer.provideMerge(fakeProviderLayer(fake, accountId))),
+      ),
+    ),
+  );
+
+export const reconcile = (p: P, news: MeshNodeProps, output?: MeshNodeAttributes) =>
+  p.reconcile({ ...ids, ...extra, news, olds: undefined, output });
+
+export const read = (p: P, olds: MeshNodeProps, output?: MeshNodeAttributes) =>
+  handler('read', p.read)({ ...ids, olds, output });
+
+export const diff = (p: P, news: MeshNodeProps, olds: MeshNodeProps, output: MeshNodeAttributes) =>
+  handler(
+    'diff',
+    p.diff,
+  )({
+    ...ids,
+    news,
+    olds,
+    newBindings: [] as never,
+    oldBindings: [] as never,
+    output,
+  });
+
+/** A stored attribute set for a node that may or may not exist in the fake. */
+export const stored = (
+  accountId: string,
+  over: Partial<MeshNodeAttributes> = {},
+): MeshNodeAttributes => ({
+  id: 'x',
+  accountId,
+  name: 'door-a',
+  status: undefined,
+  ha: false,
+  ...over,
+});
+
+export const tokenReads = (fake: FakeMesh) =>
+  fake.seen.filter((s) => s.path.endsWith('/token')).length;
+
+/** The writes the fake saw, in order: `['POST', 'DELETE', …]`. */
+export const writes = (fake: FakeMesh) =>
+  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, which is what its Test harness's scratch stacks run (Test/Core.ts
+ *   `scratchStack`), minus the profile, config and telemetry layers a fake Cloudflare does not
+ *   need. Removal policy lives in the engine, so only this can show what it does to a replace.
+ * ⚠️ `FetchHttpClient.Fetch` IS READ PER REQUEST, from the fiber running the engine, so it is
+ *   provided around the whole deploy. Provided only under the provider layer, the requests went
+ *   to the real `fetch` (measured 2026-09-21: ENOTFOUND api.example.com, the RFC 2606 host, so
+ *   no API answered — but a real DNS lookup went out).
+ */
+export const engine = (fake: FakeMesh) => {
+  const rows: Rows = {};
+  const state = Layer.succeed(State.State, State.InMemoryService(rows));
+  const providers = MeshNodeProvider().pipe(Layer.provide(fakeProviderLayer(fake)));
+  const deploy = <A, E, R>(declare: Effect.Effect<A, E, R>) =>
+    Effect.runPromiseExit(
+      declare.pipe(
+        makeStack({ name: 'mesh', 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,
+    /** The stored row's status (`created`, `replacing`, …), or `undefined` when there is none. */
+    status: (fqn: string) => rows['mesh']?.['test']?.[fqn]?.status,
+    /** ★ What `alchemy state rm` does ("Delete state records without deleting cloud resources"). */
+    forget: (fqn: string) => {
+      delete rows['mesh']?.['test']?.[fqn];
+    },
+  };
+};
+
+/** 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/mesh-node-lifecycle.ts

@@ -0,0 +1,187 @@
+/**
+ * read / reconcile / delete for `Cloudflare.MeshNode`, as plain Effects over the SDK calls in
+ * mesh-node-api.ts. mesh-node.ts only wires them into Alchemy.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import {
+  MeshNodeError,
+  type ObservedNode,
+  createNode,
+  deleteNode,
+  findNodeByName,
+  getNode,
+  renameNode,
+} from './mesh-node-api.ts';
+import { type MeshNodeAttributes, type MeshNodeProps, validateMeshNode } from './mesh-node-form.ts';
+
+const attributesOf = (node: ObservedNode, accountId: string, ha: boolean): MeshNodeAttributes => ({
+  id: node.id,
+  accountId,
+  name: node.name,
+  status: node.status,
+  ha,
+});
+
+/**
+ * Owned: refresh by the stored id. Cold: find the live node by exact name and hand it back
+ * `Unowned`, so Alchemy refuses to take it over until the stack says `adopt(true)` — the same
+ * gate `Cloudflare.Tunnel.WarpConnector` uses, because a `warp_connector` carries no ownership
+ * marker to prove it was ours.
+ *
+ * ⚠️ ADOPTION RECORDS THE DECLARED `ha`, BECAUSE NOTHING ELSE CAN. No documented read returns a
+ *   node's HA flag. Adopting an existing node with the wrong `ha` records the wrong value, and no
+ *   later plan can notice. Check the node's HA badge in the dashboard before adopting.
+ */
+export const readMeshNode = (
+  accountId: string,
+  olds: MeshNodeProps | undefined,
+  output: MeshNodeAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const account = output?.accountId ?? accountId;
+    if (output !== undefined) {
+      const node = yield* getNode(account, output.id);
+      if (node !== undefined) return attributesOf(node, account, output.ha);
+    }
+    const name = olds?.name ?? output?.name;
+    const ha = olds?.ha ?? output?.ha;
+    if (name === undefined || ha === undefined) return undefined;
+    const match = yield* findNodeByName(account, name);
+    return match === undefined ? undefined : Unowned(attributesOf(match, account, ha));
+  });
+
+/**
+ * ⛔ NEVER CONVERGE ON A NODE THIS RESOURCE DID NOT FIND BY ITS OWN ID. Alchemy's WarpConnector
+ *   answers `DuplicateTunnelName` by re-reading the node that holds the name and returning it.
+ *   Here that would be wrong in exactly the case that matters: an `ha` replace whose old node is
+ *   still alive (the default `retain` skips the delete-first teardown, mesh-node.ts) would
+ *   "create" by silently re-using the old node and record the new `ha` on it. Adoption belongs to
+ *   `read` and `adopt(true)`. An interrupted create is recovered through `read` too, which returns
+ *   the node `Unowned`, so the engine asks for `adopt(true)` there as well (as for WarpConnector).
+ */
+const nameTaken = (name: string, holder: string) =>
+  new MeshNodeError({
+    message:
+      `A tunnel named "${name}" already exists (${holder}). Names are unique per account, and ` +
+      'this resource never takes over a node it did not create by its own id.',
+  });
+
+/**
+ * ★ HOW TO TAKE A NODE OVER WHILE THIS RESOURCE HAS A STATE ROW, WRITTEN ONCE. The plan asks
+ *   `read` to adopt only for a resource with NO row (Plan.ts, `oldState === undefined`) or for an
+ *   interrupted create's `creating` row. A replace's `replacing` row gets neither, so `adopt(true)`
+ *   alone changes nothing there and the create refuses again (measured in mesh-node-policy.test.ts).
+ *   `alchemy state rm` is Alchemy's "Delete state records without deleting cloud resources".
+ */
+const REOWN =
+  "drop this resource's state row (alchemy state rm, which leaves the node alone), then deploy " +
+  'under adopt(true)';
+
+/**
+ * 🔴 THE REFUSAL AN `ha` CHANGE MEETS UNDER THE DEFAULT, SO IT NAMES EVERY WAY ON. The plan says
+ *   `replace` (delete-first), the engine skips that delete because of `retain`, and the old node
+ *   still holds the name here. A node made outside the stack is caught earlier, by the plan's
+ *   adoption probe in `read`.
+ * ⛔ BUT THE HOLDER IS NOT ALWAYS THE OLD NODE, AND `create` CANNOT TELL: the engine passes it no
+ *   `olds` (Apply.ts, the replace branch). An `ha` + `name` change is a create-first replace, and
+ *   there the holder of the NEW name is some other node, which `RemovalPolicy.destroy()` never
+ *   touches. So the old-node advice is conditional, and the other case says not to delete it: a
+ *   sentence that called any holder "the old node" would send an operator to delete a live node
+ *   and cut its replicas off the Mesh (measured 2026-09-21 in mesh-node-policy.test.ts).
+ * ⚠️ REVERTING `ha` DOES NOT UNDO IT. The failed deploy leaves a `replacing` row, and the next
+ *   plan resumes that replace (Plan.ts, the `replacing` branch), so it refuses again. Dropping the
+ *   row and adopting is the way back. All measured in mesh-node-policy.test.ts.
+ */
+const oldNodeHoldsName = (name: string, holder: string) =>
+  new MeshNodeError({
+    message:
+      `Mesh node "${name}" already exists (${holder}) and is not the node this resource tracks, ` +
+      'so it is left alone: names are unique per account. If this deploy changed `ha` and kept ' +
+      "the name, it is this resource's old node, kept by MeshNode's default " +
+      'RemovalPolicy.retain because HA cannot change in place. To replace it (a new id, token and ' +
+      'Mesh IP per replica), deploy once with .pipe(RemovalPolicy.destroy()), which deletes it ' +
+      `first, or delete it by hand. To keep it, reverting \`ha\` is not enough: ${REOWN}, with ` +
+      'the original `ha`. Otherwise it is another node: do not delete it. Choose another name, ' +
+      `or, if it is meant to be this one, check its HA badge, then ${REOWN}.`,
+  });
+
+/**
+ * 🔴 A 1013 AFTER A CLEAN LOOKUP IS USUALLY THIS DEPLOY'S OWN NODE. distilled retries a POST on
+ *   a transport error or a 5xx (core `isTransientError`, measured in its source 2026-09-21), so a
+ *   create that succeeded but lost its response is sent again and answered 1013 by the node the
+ *   first attempt made. The lookup is repeated so the sentence names that node instead of blaming
+ *   another tunnel type; it is still not adopted here (see above), because a concurrent creator
+ *   looks the same and its `ha` is unknown.
+ * ⚠️ `adopt(true)` ALONE ONLY RECOVERS A FIRST CREATE. Inside a replace (any `ha` change, either
+ *   order) the row is `replacing`, which the plan never probes, so the sentence names `REOWN` for
+ *   that case (measured in mesh-node-policy.test.ts).
+ */
+const raced = (accountId: string, name: string) =>
+  findNodeByName(accountId, name).pipe(
+    Effect.flatMap((holder) =>
+      Effect.fail(
+        holder === undefined
+          ? // ⚠️ No live warp_connector of that name: another tunnel TYPE holds it (a cloudflared
+            //   tunnel), or — UNMEASURED — a node deleted moments ago (a delete-first `ha`
+            //   replace) still reserves it.
+            nameTaken(name, 'not a live Mesh node: another tunnel type, or a just-deleted node')
+          : new MeshNodeError({
+              message:
+                `Mesh node "${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, check its HA badge matches the declared `ha`, then ' +
+                'adopt it: adopt(true) after a first create, but after a replace ' +
+                `${REOWN}, because adopt(true) alone does not act on a replace's row. ` +
+                'Otherwise another creator raced this one.',
+            }),
+      ),
+    ),
+  );
+
+const createFresh = (accountId: string, news: MeshNodeProps) =>
+  Effect.gen(function* () {
+    const existing = yield* findNodeByName(accountId, news.name);
+    if (existing !== undefined) return yield* Effect.fail(oldNodeHoldsName(news.name, existing.id));
+    const node = yield* createNode(accountId, news.name, news.ha).pipe(
+      Effect.catchTag('DuplicateTunnelName', () => raced(accountId, news.name)),
+    );
+    return attributesOf(node, accountId, news.ha);
+  });
+
+export const reconcileMeshNode = (
+  accountId: string,
+  news: MeshNodeProps,
+  output: MeshNodeAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const invalid = validateMeshNode(news);
+    if (invalid !== undefined) return yield* Effect.fail(invalid);
+    const owned = output !== undefined && output.accountId === accountId ? output : undefined;
+    const live = owned === undefined ? undefined : yield* getNode(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);
+    if (owned.ha !== news.ha) {
+      // ⛔ The plan would have said `replace`; it can only reach here with `ha` unresolved then.
+      return yield* Effect.fail(
+        new MeshNodeError({
+          message: `MeshNode "${news.name}": \`ha\` is create-only (stored ${owned.ha}, declared ${news.ha}). Plan again so the change is a replace.`,
+        }),
+      );
+    }
+    if (live.name === news.name) return attributesOf(live, accountId, owned.ha);
+    const renamed = yield* renameNode(accountId, live.id, news.name).pipe(
+      Effect.catchTag('DuplicateTunnelName', () =>
+        Effect.fail(nameTaken(news.name, 'held by another tunnel')),
+      ),
+    );
+    return attributesOf(renamed, accountId, owned.ha);
+  });
+
+/**
+ * ⚠️ Cloudflare may refuse to delete a node while replicas are connected (Alchemy's WarpConnector
+ *   notes "Deleting requires all connector sessions to be down"; unmeasured here). Stop the
+ *   client on every replica first. A node already gone is a successful delete.
+ */
+export const deleteMeshNode = (output: MeshNodeAttributes) =>
+  deleteNode(output.accountId, output.id);

package/src/cloudflare/mesh-node-policy.test.ts

@@ -0,0 +1,151 @@
+/**
+ * MeshNode's removal policy, through Alchemy's real plan/apply (`engine` in mesh-node-harness.ts)
+ * over the fake Cloudflare. The policy lives in the engine, not the provider, so the handler-level
+ * tests beside this one cannot see it.
+ *
+ * ⛔ WHAT THESE PIN: `retain` is the default (a dropped declaration deletes nothing), a same-name
+ *   `ha` change refuses and writes nothing until the deploy opts in with
+ *   `RemovalPolicy.destroy()`, and the sentence's way back (drop the row, adopt) works while a
+ *   plain revert does not. Deleting `defaultRemovalPolicy`, or turning `deleteFirst` off in
+ *   mesh-node-form.ts, fails at least one test here.
+ * ⛔ AND THE SENTENCES NEVER SEND AN OPERATOR THE WRONG WAY: a node holding a create-first
+ *   replace's NEW name is not called the old node, and `adopt(true)` alone, which does nothing to
+ *   a `replacing` row, is never offered as the way back from inside a replace.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeMesh } from './fake-mesh.ts';
+import { engine, failureOf, writes } from './mesh-node-harness.ts';
+import { MeshNode } from './mesh-node.ts';
+
+/** The logical id every test declares; at the stack root it is also the state row's fqn. */
+const DOOR = 'door';
+const door = (ha: boolean, name = 'door-a') => MeshNode(DOOR, { name, ha });
+const liveNodes = (fake: ReturnType<typeof fakeMesh>) =>
+  fake.live().map((node) => ({ id: node.id, name: node.name, ha: node.ha }));
+
+describe('MeshNode removal policy (the real engine)', () => {
+  test('retain is the default: dropping the declaration leaves the node and sends no DELETE', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(door(false)))).toBe('');
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(stack.status(DOOR)).toBeUndefined();
+    expect(liveNodes(fake)).toHaveLength(1);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('RemovalPolicy.destroy() still reaches the implemented delete', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false).pipe(RemovalPolicy.destroy()));
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(liveNodes(fake)).toHaveLength(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE']);
+  });
+
+  test('an `ha` change under the default refuses, writes nothing, and names the opt-in', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    const [before] = liveNodes(fake);
+    const failure = failureOf(await stack.deploy(door(true)));
+    expect(failure).toContain(`"door-a" already exists (${before?.id})`);
+    expect(failure).toContain('RemovalPolicy.retain');
+    expect(failure).toContain('.pipe(RemovalPolicy.destroy())');
+    expect(failure).toContain('reverting `ha` is not enough');
+    expect(liveNodes(fake)).toEqual([{ id: before?.id ?? '', name: 'door-a', ha: false }]);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('opting in with RemovalPolicy.destroy() completes it delete-first, then retain is back', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    await stack.deploy(door(true));
+    const done = await stack.deploy(door(true).pipe(RemovalPolicy.destroy()));
+    expect(failureOf(done)).toBe('');
+    expect(writes(fake)).toEqual(['POST', 'DELETE', 'POST']);
+    expect(liveNodes(fake)).toMatchObject([{ name: 'door-a', ha: true }]);
+    // ★ The opt-in lasts one deploy: without it the row is re-committed as retain.
+    await stack.deploy(door(true));
+    await stack.deploy(Effect.void);
+    expect(liveNodes(fake)).toHaveLength(1);
+  });
+
+  test('reverting `ha` does not undo a refused replace; dropping the row and adopting does', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    const [original] = liveNodes(fake);
+    await stack.deploy(door(true));
+    expect(stack.status(DOOR)).toBe('replacing');
+    expect(failureOf(await stack.deploy(door(false)))).toContain('already exists');
+
+    stack.forget(DOOR);
+    const back = await stack.deploy(door(false).pipe(adopt(true)));
+    expect(failureOf(back)).toBe('');
+    expect(stack.status(DOOR)).not.toBe('replacing');
+    expect(liveNodes(fake)).toEqual([{ id: original?.id ?? '', name: 'door-a', ha: false }]);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('`ha` and `name` together replace create-first, and the old node stays live', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    expect(failureOf(await stack.deploy(door(true, 'door-b')))).toBe('');
+    expect(liveNodes(fake).map((node) => [node.name, node.ha])).toEqual([
+      ['door-a', false],
+      ['door-b', true],
+    ]);
+    expect(writes(fake)).toEqual(['POST', 'POST']);
+  });
+
+  test('`ha` and `name` into a name another node holds: not called the old node, and nothing deletes it', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    const other = fake.seed({ name: 'door-b', ha: false });
+    const refused = failureOf(await stack.deploy(door(true, 'door-b')));
+    expect(refused).toContain(`"door-b" already exists (${other.id})`);
+    expect(refused).toContain('If this deploy changed `ha` and kept the name');
+    expect(refused).toContain('Otherwise it is another node: do not delete it.');
+    // ★ destroy() reaches only the old generation, never the name holder: refused again.
+    const optedIn = door(true, 'door-b').pipe(RemovalPolicy.destroy());
+    expect(failureOf(await stack.deploy(optedIn))).toContain('already exists');
+    // ⚠️ adopt(true) alone does not act on the `replacing` row either.
+    const adopted = door(true, 'door-b').pipe(adopt(true));
+    expect(failureOf(await stack.deploy(adopted))).toContain('already exists');
+    expect(liveNodes(fake).map((node) => node.name)).toEqual(['door-a', 'door-b']);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('a lost-response retry inside an opted-in replace names state rm, which adopt(true) alone is not', async () => {
+    let lose = false;
+    const fake = fakeMesh({
+      onCreate: (name) => {
+        if (!lose) return undefined;
+        lose = false;
+        // What a retried POST meets: the node its first, lost-response attempt created.
+        fake.seed({ name, ha: true });
+        return fakeFailure(409, 1013, 'Tunnel with name already exists');
+      },
+    });
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    lose = true;
+    const raced = failureOf(await stack.deploy(door(true).pipe(RemovalPolicy.destroy())));
+    expect(raced).toContain('appeared between');
+    expect(raced).toContain("after a replace drop this resource's state row (alchemy state rm");
+    expect(stack.status(DOOR)).toBe('replacing');
+    expect(failureOf(await stack.deploy(door(true).pipe(adopt(true))))).toContain('already exists');
+
+    stack.forget(DOOR);
+    expect(failureOf(await stack.deploy(door(true).pipe(adopt(true))))).toBe('');
+    expect(liveNodes(fake)).toMatchObject([{ name: 'door-a', ha: true }]);
+    expect(writes(fake)).toEqual(['POST', 'DELETE', 'POST']);
+  });
+});

package/src/cloudflare/mesh-node-token.test.ts

@@ -0,0 +1,117 @@
+/**
+ * fetchMeshNodeToken against the fake Cloudflare, provided the way a Bun `mesh-enroll` script
+ * provides it: distilled Credentials from an API token, plus FetchHttpClient.
+ *
+ * ⛔ The value comes back `Redacted`: printing it, logging it or serialising it shows
+ *   `<redacted>`. Only `Redacted.value` yields the token, and only the write to the host's 0600
+ *   file should call it.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type Credentials,
+  fromApiKey,
+  fromApiToken,
+} from '@distilled.cloud/cloudflare/Credentials';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import { FAKE_ACCOUNT, FAKE_BASE, type FakeMesh, fakeClientLayer, fakeMesh } from './fake-mesh.ts';
+import { type MeshNodeRef, fetchMeshNodeToken } from './mesh-node-token.ts';
+
+const token = (fake: FakeMesh, ref: MeshNodeRef) =>
+  Effect.runPromise(fetchMeshNodeToken(ref).pipe(Effect.provide(fakeClientLayer(fake))));
+
+const failure = (fake: FakeMesh, ref: MeshNodeRef, credentials?: Layer.Layer<Credentials>) =>
+  Effect.runPromise(
+    Effect.flip(fetchMeshNodeToken(ref)).pipe(Effect.provide(fakeClientLayer(fake, credentials))),
+  );
+
+describe('fetchMeshNodeToken', () => {
+  test('by id: the token, redacted everywhere but Redacted.value', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const value = await token(fake, { accountId: FAKE_ACCOUNT, id: node.id });
+    expect(Redacted.value(value)).toBe(node.token);
+    expect(String(value)).not.toContain(node.token);
+    expect(JSON.stringify({ value })).not.toContain(node.token);
+    expect(fake.seen.map((s) => s.path)).toEqual([
+      `/client/v4/accounts/${FAKE_ACCOUNT}/warp_connector/${node.id}/token`,
+    ]);
+  });
+
+  test('by name: resolved by exact match first', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-2' });
+    const node = fake.seed({ name: 'door-a' });
+    const value = await token(fake, { accountId: FAKE_ACCOUNT, name: 'door-a' });
+    expect(Redacted.value(value)).toBe(node.token);
+  });
+
+  test('an unknown node fails with a sentence naming it', async () => {
+    const fake = fakeMesh();
+    const missing = '00000000-0000-4000-8000-00000000ffff';
+    expect((await failure(fake, { accountId: FAKE_ACCOUNT, id: missing })).message).toContain(
+      missing,
+    );
+    expect((await failure(fake, { accountId: FAKE_ACCOUNT, name: 'nope' })).message).toContain(
+      'No live Mesh node named "nope"',
+    );
+  });
+
+  test('an empty token fails closed rather than enrolling nothing', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a', token: '' });
+    const error = await failure(fake, { accountId: FAKE_ACCOUNT, id: node.id });
+    expect(error.message).toContain('empty token');
+  });
+
+  test('a 403 names the Write permission the endpoint needs', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const denying: FakeMesh = {
+      ...fake,
+      fetch: (async () =>
+        Response.json(
+          {
+            success: false,
+            errors: [{ code: 9109, message: 'Unauthorized to access requested resource' }],
+          },
+          { status: 403 },
+        )) as unknown as typeof globalThis.fetch,
+    };
+    const error = await failure(denying, { accountId: FAKE_ACCOUNT, id: node.id });
+    expect(error.message).toContain('Cloudflare One Connectors Write');
+    expect(error.message).toContain(FAKE_ACCOUNT);
+  });
+
+  test('refused before any request while DISTILLED_DEBUG_HTTP would print the token', async () => {
+    // ⛔ distilled console.errors the first 400 bytes of every response body when this is set.
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const before = process.env['DISTILLED_DEBUG_HTTP'];
+    process.env['DISTILLED_DEBUG_HTTP'] = '1';
+    try {
+      const error = await failure(fake, { accountId: FAKE_ACCOUNT, id: node.id });
+      expect(error.message).toContain('DISTILLED_DEBUG_HTTP');
+    } finally {
+      if (before === undefined) delete process.env['DISTILLED_DEBUG_HTTP'];
+      else process.env['DISTILLED_DEBUG_HTTP'] = before;
+    }
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('the Global API Key and an empty API token are refused before any request', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const ref = { accountId: FAKE_ACCOUNT, id: node.id };
+    const globalKey = fromApiKey({
+      apiKey: 'placeholder-global-key',
+      email: 'ops@example.com',
+      apiBaseUrl: FAKE_BASE,
+    });
+    expect((await failure(fake, ref, globalKey)).message).toContain('Global API Key');
+    const empty = fromApiToken({ apiToken: '', apiBaseUrl: FAKE_BASE });
+    expect((await failure(fake, ref, empty)).message).toContain('EMPTY');
+    expect(fake.seen).toHaveLength(0);
+  });
+});