@homeflare/alchemy 0.6.0 → 0.7.0

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

@@ -0,0 +1,125 @@
+/**
+ * `fetchMeshNodeToken` — a Mesh node's enrolment token, fetched on demand for a one-off Bun
+ * `mesh-enroll` step. ⛔ Not a Resource, and never an attribute: see mesh-node-form.ts for why
+ * the token must stay out of Alchemy state.
+ *
+ * ⛔ WHERE THE VALUE MAY GO. Straight into a root-owned `0600` file on the node's host, which the
+ *   enrolment reads (`warp-cli --accept-tos connector new <token>`, per the Mesh get-started page,
+ *   read 2026-09-21). Nowhere else: not Alchemy state, not a secrets store (a runtime credential
+ *   belongs to the host that runs it), not a log line, not a CI variable. It is returned
+ *   `Redacted`, so an accidental `console.log` or `Effect.log` prints `<redacted>`; call
+ *   `Redacted.value` only at the write.
+ * ⚠️ `warp-cli` takes the token as an ARGUMENT, so it is visible in the host's process list for
+ *   the life of that command. Run the enrolment as root on the node itself, never over a shell
+ *   whose history is kept.
+ * ⚠️ THE ENDPOINT NEEDS A WRITE PERMISSION. Its API reference (read 2026-09-21) accepts
+ *   "Cloudflare One Connectors Write", "Cloudflare One Connector: cloudflared Write" or
+ *   "Cloudflare Tunnel Write"; the Mesh get-started guide also names "Cloudflare One Connector:
+ *   WARP Write". Connectors Write is in both lists. Mint a short-lived token for this step alone;
+ *   a read-only plan token gets a 403 here.
+ *
+ * ★ Requires distilled `Credentials` and an `HttpClient`, not Alchemy's CloudflareEnvironment: a
+ *   Bun script has no Alchemy profile, so the account id is an argument. Provide
+ *   `Credentials.fromApiToken({ apiToken })` (from `@distilled.cloud/cloudflare/Credentials`) and
+ *   `FetchHttpClient.layer`. ⛔ Not `Credentials.fromEnv()`: it falls back to the Global API Key
+ *   (`CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`) when no token is set — and `refuseUnsafe` below
+ *   refuses that key rather than trusting the caller to have read this.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { MeshNodeError, findNodeByName } from './mesh-node-api.ts';
+
+/** Which node: by id (the `MeshNode` attribute) or by its exact name. */
+export type MeshNodeRef = { readonly accountId: string } & (
+  | { readonly id: string; readonly name?: undefined }
+  | { readonly name: string; readonly id?: undefined }
+);
+
+/**
+ * ⛔ REFUSED BEFORE ANY REQUEST IS SENT:
+ * - `DISTILLED_DEBUG_HTTP` set. distilled's Cloudflare protocol then `console.error`s the first
+ *   400 characters of EVERY response body (protocol.ts, measured in 1.0.0-rc.12) — the token
+ *   response is `{"success":true,…,"result":"<token>"}`, so the whole token lands on stderr and in
+ *   whatever captures it. The check reads `process.env` because that is what distilled reads.
+ * - The Global API Key (`apiKey` credentials). Account-wide and long-lived: the one credential a
+ *   one-off enrolment must never use.
+ * - An EMPTY API token. A denied secrets-store grant renders empty, and Cloudflare then answers
+ *   like a bad permission — which would send the operator to widen a grant that was fine
+ *   (client.ts says the same for `CLOUDFLARE_API_TOKEN`).
+ */
+const refuseUnsafe = Effect.gen(function* () {
+  if ((globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') !== '') {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'Refusing to fetch a Mesh node token while DISTILLED_DEBUG_HTTP is set: the SDK would print the token to stderr. Unset it and run again.',
+      }),
+    );
+  }
+  const credentials = yield* yield* Credentials;
+  if (credentials.type === 'apiKey') {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'Refusing the Global API Key for a Mesh node token. Mint a short-lived API token with "Cloudflare One Connectors Write" and pass it with fromApiToken.',
+      }),
+    );
+  }
+  if (credentials.type === 'apiToken' && Redacted.value(credentials.apiToken).length === 0) {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'The Cloudflare API token is EMPTY. That is a missing or denied secrets grant, not a Cloudflare permission: re-mint the token before changing any grant.',
+      }),
+    );
+  }
+});
+
+const resolveId = (ref: MeshNodeRef) => {
+  if (ref.id !== undefined) return Effect.succeed(ref.id);
+  const name = ref.name;
+  return Effect.flatMap(findNodeByName(ref.accountId, name), (node) =>
+    node === undefined
+      ? Effect.fail(new MeshNodeError({ message: `No live Mesh node named "${name}".` }))
+      : Effect.succeed(node.id),
+  );
+};
+
+/**
+ * ⛔ An EMPTY token fails closed: `warp-cli connector new ""` would not enrol, and a script that
+ *   wrote an empty file would report success over a host that never joined.
+ * ⛔ The failures made here name the node and account and quote no response body, because the
+ *   success body IS the token. Other SDK errors pass through; they come only from non-2xx
+ *   responses, which carry an error envelope, not a token.
+ */
+export const fetchMeshNodeToken = (ref: MeshNodeRef) =>
+  Effect.gen(function* () {
+    yield* refuseUnsafe;
+    const nodeId = yield* resolveId(ref);
+    const token = yield* zeroTrust
+      .getTunnelWarpConnectorToken({ accountId: ref.accountId, tunnelId: nodeId })
+      .pipe(
+        Effect.catchTag('TunnelNotFound', () =>
+          Effect.fail(
+            new MeshNodeError({
+              message: `Mesh node ${nodeId} does not exist in account ${ref.accountId}.`,
+            }),
+          ),
+        ),
+        Effect.catchTag('Forbidden', () =>
+          Effect.fail(
+            new MeshNodeError({
+              message: `Reading Mesh node ${nodeId}'s token was refused (403). The endpoint needs a Write permission such as "Cloudflare One Connectors Write", on a token scoped to account ${ref.accountId}.`,
+            }),
+          ),
+        ),
+      );
+    if (typeof token !== 'string' || token.length === 0) {
+      return yield* Effect.fail(
+        new MeshNodeError({ message: `Mesh node ${nodeId} returned an empty token.` }),
+      );
+    }
+    return Redacted.make(token);
+  });

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

@@ -0,0 +1,172 @@
+/**
+ * MeshNodeProvider against a fake Cloudflare (fake-mesh.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 node token — even though the fake's create response carries
+ *   one, as Cloudflare's HA page says the real one does.
+ */
+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 { FAKE_ACCOUNT, FAKE_API_TOKEN, fakeMesh } from './fake-mesh.ts';
+import { diff, extra, ids, read, reconcile, run, stored, tokenReads } from './mesh-node-harness.ts';
+import { providers } from './providers.ts';
+
+// ⛔ Compile-time: a stack's `providers` must be `Layer<…, never, StackServices>`. Adding MeshNode
+//   first leaked Alchemy's auth errors into the error channel; `bun run types` now catches that.
+type Built = Layer.Success<ReturnType<typeof providers>>;
+const _stackShaped: Layer.Layer<Built, never, StackServices> = providers();
+void _stackShaped;
+
+describe('MeshNodeProvider', () => {
+  test('create sends ha, and the attributes carry no token', async () => {
+    const fake = fakeMesh();
+    const out = await run(fake, (p) => reconcile(p, { name: 'door-a', ha: true }));
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(post?.body).toEqual({ name: 'door-a', ha: true });
+    expect(out).toMatchObject({
+      name: 'door-a',
+      ha: true,
+      accountId: FAKE_ACCOUNT,
+      status: 'inactive',
+    });
+    expect(Object.keys(out).sort()).toEqual(['accountId', 'ha', 'id', 'name', 'status']);
+    expect(JSON.stringify(out)).not.toContain('fake-node-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 = fakeMesh();
+    fake.seed({ name: 'door-a-old' });
+    fake.seed({ name: 'door-a-older' });
+    const node = fake.seed({ name: 'door-a', status: 'healthy' });
+    const props = { name: 'door-a', ha: false };
+    const [owned, probe] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = stored(FAKE_ACCOUNT, { id: node.id });
+        return [yield* read(p, props, output), yield* read(p, props)] as const;
+      }),
+    );
+    expect(Unowned.is(owned)).toBe(false);
+    expect(owned).toMatchObject({ id: node.id, status: 'healthy' });
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ id: node.id, name: 'door-a', ha: false });
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('a prefix-only match or a deleted node is not adopted', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-2' });
+    fake.seed({ name: 'door-a', deleted_at: '2026-09-20T00:00:00Z' });
+    const probe = await run(fake, (p) => read(p, { name: 'door-a', ha: false }));
+    expect(probe).toBeUndefined();
+  });
+
+  test('a rename is a PATCH on the same id', async () => {
+    const fake = fakeMesh();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, { name: 'door-a', ha: false });
+        return [first, yield* reconcile(p, { name: 'door-b', ha: false }, first)] as const;
+      }),
+    );
+    expect(second.id).toBe(first.id);
+    expect(second.name).toBe('door-b');
+    expect(fake.seen.filter((s) => s.method === 'POST')).toHaveLength(1);
+    expect(fake.seen.find((s) => s.method === 'PATCH')?.body).toEqual({ name: 'door-b' });
+  });
+
+  test('an unchanged node costs no write', async () => {
+    const fake = fakeMesh();
+    await run(fake, (p) =>
+      Effect.flatMap(reconcile(p, { name: 'door-a', ha: false }), (out) =>
+        reconcile(p, { name: 'door-a', ha: false }, out),
+      ),
+    );
+    expect(fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method)).toEqual(['POST']);
+  });
+
+  test('reconcile refuses an ha change that reached it as an update', async () => {
+    const fake = fakeMesh();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        Effect.flatMap(reconcile(p, { name: 'door-a', ha: false }), (out) =>
+          reconcile(p, { name: 'door-a', ha: true }, out),
+        ),
+      ),
+    );
+    expect(String(failure)).toContain('create-only');
+  });
+
+  test('create never converges on a node it did not create (a retained old generation)', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a', ha: false });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, { name: 'door-a', ha: true })));
+    expect(String(failure)).toContain('already exists');
+    expect(fake.seen.some((s) => s.method === 'POST')).toBe(false);
+  });
+
+  test('a node deleted out of band is created again', async () => {
+    const fake = fakeMesh();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, { name: 'door-a', ha: false });
+        const node = fake.nodes.get(first.id);
+        if (node !== undefined) node.deleted_at = '2026-09-21T02:00:00Z';
+        return [first, yield* reconcile(p, { name: 'door-a', ha: false }, first)] as const;
+      }),
+    );
+    expect(second.id).not.toBe(first.id);
+    expect(fake.live()).toHaveLength(1);
+  });
+
+  test('delete removes the node, and deleting it again succeeds', async () => {
+    const fake = fakeMesh();
+    await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = yield* reconcile(p, { name: 'door-a', ha: false });
+        const olds = { name: 'door-a', ha: false };
+        yield* p.delete({ ...ids, ...extra, olds, output });
+        yield* p.delete({ ...ids, ...extra, olds, output });
+      }),
+    );
+    expect(fake.live()).toHaveLength(0);
+    expect(fake.seen.filter((s) => s.method === 'DELETE')).toHaveLength(2);
+  });
+
+  test('diff reads the account from the provider environment', async () => {
+    const fake = fakeMesh();
+    const props = { name: 'door-a', ha: false };
+    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',
+    });
+  });
+
+  test('an invalid declaration fails the PLAN, before a delete-first replace tears anything down', async () => {
+    const fake = fakeMesh();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        diff(p, { name: 'door-a ', ha: true }, { name: 'door-a', ha: false }, stored(FAKE_ACCOUNT)),
+      ),
+    );
+    expect(String(failure)).toContain('whitespace');
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('list is empty and nuke skips it: Alchemy WarpConnector already enumerates these', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a' });
+    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/mesh-node.ts

@@ -0,0 +1,120 @@
+/**
+ * `Cloudflare.MeshNode` — a Cloudflare Mesh node (a `warp_connector` object), declared without
+ * its token ever touching Alchemy state. Usage and the enrolment step: docs/mesh-node.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Tunnel.WarpConnector`. A Mesh node that fronts a
+ *   private service needs a node record in the graph, so the Gateway rules and DNS records that
+ *   name it deploy together. Alchemy beta.79's WarpConnector would put the node token — the
+ *   credential that lets any Linux host join the account's Mesh as that node — into plaintext
+ *   state on every read, and it cannot create an HA node. See mesh-node-form.ts.
+ *
+ * ★ REMOVAL POLICY: `retain` BY DEFAULT — see the ★ on `MeshNode` below, and what it does to an
+ *   `ha` replace in mesh-node-lifecycle.ts.
+ */
+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/unstable/http/HttpClient';
+import {
+  type MeshNodeAttributes,
+  type MeshNodeProps,
+  diffMeshNode,
+  validateMeshNode,
+} from './mesh-node-form.ts';
+import { deleteMeshNode, readMeshNode, reconcileMeshNode } from './mesh-node-lifecycle.ts';
+import type { Providers } from './providers.ts';
+
+export interface MeshNode extends Resource<
+  'Cloudflare.MeshNode',
+  MeshNodeProps,
+  MeshNodeAttributes,
+  never,
+  Providers
+> {}
+
+/**
+ * ★ `defaultRemovalPolicy: 'retain'`, LIKE EVERY KIT RESOURCE WHOSE DELETION BREAKS ITS CONSUMERS
+ *   (the `Bao.*` families, `R2BucketLock`, the Proxmox storage families; the reasoning is written
+ *   once in proxmox/resource.ts). Deleting a node cuts every enrolled replica off the Mesh, and
+ *   nothing brings it back: a new node has a new id, a new token and a new Mesh IP per replica, so
+ *   each host must be re-enrolled by hand and every Gateway rule or allow-list that pins the old
+ *   Mesh IP breaks. So dropping the declaration, or `alchemy destroy`, leaves the node live.
+ * ⚠️ IT ALSO SKIPS THE OLD NODE'S DELETE IN A REPLACE (Apply.ts, `deleteOldGenerations` and the
+ *   GC's `retainOldGeneration`, beta.79). A same-name `ha` change therefore REFUSES, deleting
+ *   nothing, until that deploy opts in with `.pipe(RemovalPolicy.destroy())`; a create-first
+ *   replace leaves the old node live and unmanaged. Both measured in mesh-node-policy.test.ts.
+ * ⛔ `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 MeshNode: ResourceClass<MeshNode> = Resource<MeshNode>('Cloudflare.MeshNode', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** What every call below needs: the account, credentials and HTTP — Alchemy's own trio. */
+export type MeshNodeServices =
+  | 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. `Provider.succeed` (what Alchemy's
+ *   own providers use) leaves each handler to find CloudflareEnvironment and Credentials in the
+ *   engine's context at call time — which works for `Cloudflare.providers()` only because it
+ *   `provideMerge`s them into the stack. Capturing them here keeps this provider correct whether
+ *   or not the stack also merges `Cloudflare.providers()`.
+ */
+export const MeshNodeProvider = () =>
+  Provider.effect(
+    MeshNode,
+    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, MeshNodeServices>) =>
+        Effect.provideContext(effect, services);
+
+      return MeshNode.Provider.of({
+        stables: ['id', 'accountId', 'ha'],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Tunnel.WarpConnector` already lists
+         *   every `warp_connector` in the account for `alchemy unsafe nuke`; a second listing here
+         *   would make nuke delete each node twice. `read` does not depend on this.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        /**
+         * ⛔ VALIDATE AT PLAN TIME, NOT ONLY IN `reconcile`. An `ha` replace is delete-first: the
+         *   engine deletes the old node BEFORE the new generation's reconcile runs, so a
+         *   declaration refused there would leave no node at all. launchd's job-preflight.ts
+         *   refuses at plan time for the same reason.
+         */
+        diff: ({ news, output }) =>
+          run(
+            Effect.gen(function* () {
+              const invalid = isResolved(news) ? validateMeshNode(news) : undefined;
+              if (invalid !== undefined) return yield* Effect.fail(invalid);
+              return diffMeshNode(news, output, yield* accountId);
+            }),
+          ),
+        read: ({ olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readMeshNode(account, olds, output))),
+        reconcile: ({ news, output }) =>
+          run(Effect.flatMap(accountId, (account) => reconcileMeshNode(account, news, output))),
+        delete: ({ output }) => run(deleteMeshNode(output)),
+      });
+    }),
+  );

package/src/cloudflare/providers.ts

@@ -8,16 +8,34 @@
  *   both a `Cloudflare.R2.Bucket` and this lock merges the two:
  *   `Layer.mergeAll(Cloudflare.providers(), HomeflareCloudflare.providers())` — the shape
  *   a consuming stack names for one talking to more than one account.
+ *
+ * ★ TWO CREDENTIAL PATHS, ONE PER SDK. `R2BucketLock` uses the `cloudflare` SDK through
+ *   `CloudflareApiLive` (`CLOUDFLARE_API_TOKEN`, fail-closed). `MeshNode` uses Alchemy's own SDK
+ *   and resolves credentials and the account through `Cloudflare.CloudflareApiLive()` — the same
+ *   source `Cloudflare.providers()` uses (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
+ *   `CLOUDFLARE_ACCOUNT_ID` in CI), so a node lands in the account its Gateway rules do.
+ * ⚠️ That second layer is built again here even when the stack also merges
+ *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: it feeds MeshNode only and adds
+ *   nothing to the stack's context.
  */
+import * as Cloudflare from 'alchemy/Cloudflare';
 import * as Provider from 'alchemy/Provider';
 import * as Layer from 'effect/Layer';
 import { CloudflareApiLive } from './client.ts';
+import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
 import { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';
 
 export class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}
 
 export const providers = () =>
-  Layer.effect(Providers, Provider.collection([R2BucketLock])).pipe(
-    Layer.provide(R2BucketLockProvider()),
+  Layer.effect(Providers, Provider.collection([R2BucketLock, MeshNode])).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        R2BucketLockProvider(),
+        // ⛔ `orDie`, as `Cloudflare.providers()` ends with: a stack's providers layer must not
+        //   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
+        MeshNodeProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
+      ),
+    ),
     Layer.provideMerge(CloudflareApiLive),
   );

package/src/index.ts

@@ -10,6 +10,7 @@
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
  *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
+ *     import { CaddyConfig } from '@homeflare/alchemy/caddy';
  *
  * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative
  *   is a runbook step a human runs once — and a plan can never show a missing runbook

package/src/launchd/secret-tripwire.ts

@@ -28,7 +28,7 @@ const INLINE_FLAG = /^--?[a-z0-9-]*(?:token|password|passwd|passphrase|secret|ap
 /** A flag whose NEXT argv element is the secret: `--token abc`. */
 const BARE_FLAG = /^--?(?:[a-z0-9]+-)*(?:token|password|passwd|passphrase|secret|api-?key)$/i;
 
-const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
+export const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
 
 /** Paths of every string leaf in a plist value holding a private key. */
 const keyLeaves = (value: PlistValue, path: string): string[] => {

package/src/openbao/REPLACE.md

@@ -1,7 +1,12 @@
 # Replace semantics: the `Bao.*` providers
 
-Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source. Every kit
-provider must answer `replace` correctly (vault consolidation plan, "Replace freely").
+Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source, in two batches.
+Every kit provider must answer `replace` correctly (vault consolidation plan, "Replace freely").
+
+★ **Measured, not only read.** `fake-stack.ts` runs beta.79's own `Plan.make` and `apply` over an
+in-memory state store against the fake engines in `fake-engines.ts`. `policy-rename.test.ts`,
+`role-rename.test.ts` and `rename-occupied.test.ts` deploy, rename, and deploy again, then check
+the plan and every call that reached the fake.
 
 ## What Alchemy does with each answer
 
@@ -9,6 +14,12 @@ provider must answer `replace` correctly (vault consolidation plan, "Replace fre
   (its path) is unchanged.
 - **`replace`**: create-first by default. The new generation is created, dependents are updated in
   the same graph, then the old generation is deleted (`Apply.ts`, delete-first comment near :1180).
+  ★ That delete gets the **old** generation's attributes (`output: old.attr`), so a provider that
+  deletes by `output` deletes the old path. Measured: `PUT` of the new path, then `DELETE` of the
+  old one.
+- **No answer** (`undefined`, which every diff returns while `news` holds a pending Output): the
+  engine plans `update` if any prop changed (`Plan.ts`, `havePropsChanged`). ⚠️ That is the bug
+  class below whenever the identity changed too.
 - **`deleteFirst: true`**: tears the old one down first. It is only for identities that cannot
   coexist, such as a unique physical name. No `Bao.*` provider uses it. A rename is a new API
   path, which never collides with the old one. ⚠️ A mount or auth method whose `type` changes
@@ -27,25 +38,88 @@ state record, so no later plan would mention it. For a mount this meant an **emp
 beside the retained one that held every secret. For an AppRole it meant the old role's secret_ids
 kept working for their whole TTL.
 
-## Touched in this batch
-
-| Resource                  | Identity change | Answer now                                                                                                                               | Other changes                                                                               |
-| ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `Bao.Mount`               | `path`          | ⛔ **fails the plan**, unless `remountFrom` names the old path. Then it is an in-place `update` that moves the mount with `sys/remount`. | `type` → `replace` that **fails at apply** (below). Description and TTLs → `update` (tune). |
-| `Bao.AuthMethod`          | `path`          | Same as `Bao.Mount` (`auth/` prefix). The accessor survives the move.                                                                    | `type` → `replace` that **fails at apply** (below)                                          |
-| `Bao.AuthRole`            | `name`          | `replace`. Before 2026-09-21 it was `update`, and the old role was orphaned.                                                             | `update`                                                                                    |
-| `Bao.PkiRole`             | `mount`, `name` | `replace`. Before, only a `mount` change was caught; a `name` change orphaned the old role.                                              | `update` (full-replace write)                                                               |
-| `Bao.JwtRole`             | `mount`, `name` | `replace`                                                                                                                                | `update` (merge write; every managed field is sent)                                         |
-| `Bao.KubernetesRole`      | `mount`, `name` | `replace`                                                                                                                                | `update`                                                                                    |
-| `Bao.JwtAuthConfig`       | `mount`         | `replace`. The old delete is a no-op because there is no delete endpoint.                                                                | `update` (full-replace write)                                                               |
-| `Bao.MfaTotpMethod`       | `name`          | ⛔ **fails the plan**: a new id would strand every enrolled secret                                                                       | `update` (the upsert keeps the id)                                                          |
-| `Bao.MfaLoginEnforcement` | `name`          | `replace`. Its delete is **refused** (openbao#4030)                                                                                      | `update`                                                                                    |
+🔴 Reproduced through the engine on 2026-09-21 for `Bao.Policy` under `RemovalPolicy.destroy()`:
+deploy `app-old`, redeclare it as `app-new`, deploy. The plan said `update`, and both policies
+stayed live. `destroy` could not help, because nothing recorded the old one.
+
+## Answers, by resource
+
+| Resource                  | Identity change | Answer now                                                                                                                                                                         | Other changes                                                                               |
+| ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `Bao.Mount`               | `path`          | ⛔ **fails the plan**, unless `remountFrom` names the old path. Then it is an in-place `update` that moves the mount with `sys/remount`.                                           | `type` → `replace` that **fails at apply** (below). Description and TTLs → `update` (tune). |
+| `Bao.AuthMethod`          | `path`          | Same as `Bao.Mount` (`auth/` prefix). The accessor survives the move.                                                                                                              | `type` → `replace` that **fails at apply** (below)                                          |
+| `Bao.AuthRole`            | `name`          | `replace`. Before 2026-09-21 it was `update`, and the old role was orphaned.                                                                                                       | `update`                                                                                    |
+| `Bao.PkiRole`             | `mount`, `name` | `replace`. Before, only a `mount` change was caught; a `name` change orphaned the old role.                                                                                        | `update` (full-replace write)                                                               |
+| `Bao.JwtRole`             | `mount`, `name` | `replace`                                                                                                                                                                          | `update` (merge write; every managed field is sent)                                         |
+| `Bao.KubernetesRole`      | `mount`, `name` | `replace`                                                                                                                                                                          | `update`                                                                                    |
+| `Bao.JwtAuthConfig`       | `mount`         | `replace`. The old delete is a no-op because there is no delete endpoint.                                                                                                          | `update` (full-replace write)                                                               |
+| `Bao.MfaTotpMethod`       | `name`          | ⛔ **fails the plan**: a new id would strand every enrolled secret                                                                                                                 | `update` (the upsert keeps the id)                                                          |
+| `Bao.MfaLoginEnforcement` | `name`          | `replace`. Its delete is **refused** (openbao#4030)                                                                                                                                | `update`                                                                                    |
+| `Bao.Policy`              | `name`          | `replace` (batch 3A). Compared as OpenBao keys it, trimmed and lowercased, so `Admin` → `admin` is the same policy: `noop`. ⛔ **Fails the plan** onto a name that exists (below). | `update` (fragments digest)                                                                 |
+| `Bao.CloudflareRole`      | `mount`, `name` | `replace` (batch 3A). Exact; a trailing `/` on the mount is the same path. ⛔ **Fails the plan** onto a role that exists (below).                                                  | `update`                                                                                    |
+| `Bao.ProxmoxRole`         | `mount`, `name` | `replace` (batch 3A). ⛔ **Fails the plan** onto a role that exists, or if the rename also changes `mintUser` unless `allowMintUserChange` names the old one.                      | `update`. A `mintUser` change at the same path is refused at apply, never replaced.         |
 
 `hostAppRoles` makes no resources, but its names are identities: renaming a host or a class
 renames the role. With the logical id taken from the role name, as the README does, the old id
 leaves the stack: that is an orphan delete, not a `replace`. With a stable logical id,
 `Bao.AuthRole` plans a `replace`. Under the default `retain`, both leave the old role live.
 
+## When the new identity is not known at plan
+
+- **Only another prop is pending** (say `fragments` is an Output of an upstream that is also
+  changing). `Bao.Policy`, `Bao.CloudflareRole` and `Bao.ProxmoxRole` judge the identity props
+  before `isResolved(news)` (`rename.ts`), so the rename still plans `replace`. Measured.
+- **The identity itself is pending.** Then the diff defers: it never answers `replace` on an
+  unknown identity, because under `destroy` a replace onto the same path deletes what it just
+  wrote. The engine plans `update`, and reconcile, seeing the old attributes name another
+  object, **refuses before any write**. The row is left `updating`, with the new props and the
+  old attributes. The next deploy sees both names and plans `replace`. Measured, for all three.
+- `Bao.ProxmoxRole` defers the same way while `mintUser` or `allowMintUserChange` is pending on a
+  rename, because the re-scope guard cannot be checked. Measured for `allowMintUserChange`.
+
+## A move onto an object that already exists fails the plan
+
+⛔ All three read the new path at plan (`judgeMove`, `rename.ts`) and refuse the move if anything
+is there. 🔴 Measured before the guard: two policies that swapped names under
+`RemovalPolicy.destroy()` both planned `replace`. Each new generation wrote over the other's live
+policy, and each old generation's delete then removed the name the other had just written. The
+deploy was green, and both policies were gone, every grant revoked. Measured the same way:
+
+- a shift (`a → b` while `b → c`) deleted `b`, and a move onto the name of a resource leaving the
+  stack deleted the name it moved onto;
+- reverting a move whose new generation failed. The old generation still holds the name, and its
+  delete runs after the revert rewrites it. So the diff compares against the props of an
+  unfinished create or replacement when there are no attributes yet. Declaring the new name again
+  finishes the move instead.
+
+⚠️ The diff cannot see the removal policy, so this refuses under `retain` too, where a swap would
+have been harmless. So would a move back onto a retained old generation. Move in two deploys
+through a name nothing holds, or remove the target by hand first. A change of policy-name case, or
+a trailing `/` on a mount, is the same object, so it is not a move and is never refused.
+
+## What `retain` means for these three
+
+Under the default `retain` the old generation is kept, and the apply says so ("Replaced resource
+retained."). It is live and unmanaged from then on:
+
+- **`Bao.Policy`**: the old policy keeps every grant, for every token, role and group that still
+  names it. Under `destroy` they lose those grants at the delete. ⚠️ Only a role that takes the
+  policy's `name` Output follows the rename in the same graph. A role that names the policy as a
+  literal string (`tokenPolicies: ['deploy']`) keeps the old name, so change it in the same PR.
+- **`Bao.CloudflareRole`**: the old role still mints, for any token whose ACL reaches its
+  `creds/<name>`. Under `destroy` every consumer still minting from the old path fails. Tokens
+  already minted are leases and live to their own expiry either way.
+- **`Bao.ProxmoxRole`**: the same, and the old role keeps minting under its old `mint_user`. The
+  plugin's delete leaves outstanding leases revocable (its own
+  `TestDeletingARoleLeavesItsOutstandingLeasesRevocable`).
+
+★ A stack that puts `mount` and `name` in the logical id, as homeflare-openbao's
+`declareCloudflareRoles` does, never reaches the `replace`: the old id leaves the stack as an
+orphan delete, which `retain` also keeps live.
+
+⚠️ A NEW declaration (a new logical id) of a name that already exists still takes that object over
+and rewrites it: these families' `read` never answers `Unowned`, so Alchemy adopts it.
+
 ## Why the moves fail instead of replacing
 
 - **Mount and auth path.** A `replace` would create an empty mount. Deleting the old one would
@@ -78,10 +152,12 @@ take every secret with it. (Corrected 2026-09-21: the first audit listed this as
 3. **Unique names need `deleteFirst`.** Only a mount's `type` change keeps its unique path, and
    it fails on purpose instead (above).
 
-## Audited, not touched in this batch (open)
+## Open
 
-- ⚠️ `Bao.Policy`, `Bao.CloudflareRole` and `Bao.ProxmoxRole` still compare only the live object
-  at the declared `name` (and `mount`). A rename plans `update` and orphans the old object, which
-  is the same bug class as above. `Bao.ProxmoxRole` deliberately never answers `replace` for a
-  `mint_user` change (its own comment), and that choice is sound. The rename case is separate.
-- `Bao.SshRole` and `Bao.Plugin` already answer `replace` on an identity change.
+- ⚠️ **Nine families still check the identity after `isResolved(news)`**: `Bao.AuthRole`,
+  `Bao.PkiRole`, `Bao.JwtRole`, `Bao.KubernetesRole`, `Bao.JwtAuthConfig`, `Bao.MfaTotpMethod`,
+  `Bao.MfaLoginEnforcement`, `Bao.SshRole` and `Bao.Plugin`. A rename that lands in the same
+  deploy as any pending Output plans `update`, and none of their reconciles has the moved-update
+  guard. For `Bao.MfaTotpMethod` that writes a second method and strands every enrolment. The
+  helpers in `rename.ts` close it the same way. (`Bao.Mount` and `Bao.AuthMethod` are safe: their
+  reconcile re-plans the move from the stated path.)