@homeflare/alchemy 0.6.0 → 0.8.0

package/docs/caddy.md

@@ -0,0 +1,199 @@
+# Caddy — `@homeflare/alchemy/caddy`
+
+Declare a running Caddy's config as Caddyfile text and apply it through Caddy's own admin API:
+`POST /load` to apply (a graceful reload), `GET /config/` to detect drift. `caddyWithFile()` also
+writes the same Caddyfile to the file Caddy starts from, with launchd's `HostFile`, so a restart
+keeps it. Every admin call goes through one injectable `CaddyAdmin` transport.
+
+```ts
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { caddyProviders, caddyWithFile } from '@homeflare/alchemy/caddy';
+import { LaunchdJob, launchdProviders } from '@homeflare/alchemy/launchd';
+
+const caddyfile = `app.example.com {
+\treverse_proxy 127.0.0.1:8080
+\ttls {
+\t\tdns cloudflare {env.CF_API_TOKEN}
+\t}
+}
+`;
+
+export const edge = Effect.gen(function* () {
+  const { file } = yield* caddyWithFile('caddy', { caddyfile, path: '/usr/local/etc/Caddyfile' });
+  yield* LaunchdJob('caddy-daemon', {
+    label: 'com.example.caddy',
+    domain: 'system',
+    // --resume: a restart runs the last config Caddy accepted (see Managed Caddies below).
+    // --envfile: a file a secret renderer (openbao-agent) writes; {env.CF_API_TOKEN} reads it.
+    programArguments: [
+      '/usr/local/bin/caddy',
+      'run',
+      '--resume',
+      '--config',
+      file.path,
+      '--adapter',
+      'caddyfile',
+      '--envfile',
+      '/usr/local/etc/caddy.env',
+    ],
+    // ⛔ Here, not in the envfile: Caddy fixes its autosave path before it reads --envfile.
+    environment: { XDG_CONFIG_HOME: '/usr/local/var/caddy-edge' },
+    runAtLoad: true,
+    keepAlive: true,
+  });
+});
+// ★ launchdProviders() for the HostFile and the job; caddyProviders() for the config.
+export const providers = Layer.mergeAll(caddyProviders(), launchdProviders());
+```
+
+## CaddyConfig
+
+| prop         | notes                                                                        |
+| ------------ | ---------------------------------------------------------------------------- |
+| `caddyfile`  | the whole Caddyfile; it REPLACES the running config. ⛔ never a secret       |
+| `sourceFile` | the file Caddy was started with; `caddyWithFile()` sets it from its HostFile |
+
+| attribute      | what                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `configSha256` | SHA-256 of the adapted JSON Caddy reported after the apply — never the config itself |
+| `endpoint`     | where the admin API was reached                                                      |
+| `sourceFile`   | as applied                                                                           |
+
+| step    | what happens                                                                                                                                       |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| plan    | `POST /adapt` the Caddyfile (side-effect free): a syntax error, a literal secret, no apps or an unsafe `admin` block fails the **plan**            |
+| apply   | `POST /load` with `text/caddyfile`, then `GET /config/` must hash to what `/adapt` produced; skipped when Caddy already runs it                    |
+| refused | Caddy keeps the old config (it rolls back itself); the deploy fails with Caddy's reason and says whether the old config is still running           |
+| read    | the digest of `GET /config/`; with no state, the adoption probe — ⛔ a config that is not the declared one needs `--adopt` ([Adoption](#adoption)) |
+| drift   | live ≠ stored → `update`: a hand `curl` to the API, or a restart that loaded a different file                                                      |
+| replace | never — a new Caddyfile is a reload of the same Caddy                                                                                              |
+| delete  | ⛔ nothing. See [Removing it](#removing-it)                                                                                                        |
+
+The digests compare adapted JSON, not bytes: `/adapt` answers Go struct order, `GET /config/` sorted
+keys with `<>&` escaped and a trailing newline. `digest.ts` erases all three. ★ Measured 2026-09-21
+against a throwaway Caddy 2.11.4: the digests agree after a load and for a Caddy started from the
+same file, and a refused load kept serving the old config and answered **200** with the error after
+the adapter's warnings, which the provider still reports as a refusal.
+
+⚠️ **A stopped Caddy does not fail the plan.** Its launchd job may be the fix in the same stack, so
+`read` and `diff` plan a create/update with a warning (the plan-time `/adapt` did not run). The apply
+still needs Caddy, and fails loudly until it answers.
+
+## Order: file, then `/load`
+
+`caddyWithFile()` passes the HostFile's `path` Output into the CaddyConfig, so Alchemy writes the
+file first. It is the only order that bootstraps: a new host's Caddy job starts from the file,
+before any admin API exists to load into. What bounds the cost:
+
+- ★ **A Caddyfile that does not adapt never reaches disk** once the config has state: the plan-time
+  `/adapt` fails the plan. On the very first deploy the path is still an Output, Alchemy skips the
+  adoption probe, and the check runs at apply instead.
+- ⚠️ **A Caddyfile that adapts but that Caddy refuses** (a port in use, a missing cert file) is on
+  disk when `/load` fails. Caddy keeps serving the old config, and a managed Caddy's restart runs its
+  autosave, not the refused file (below). Without `--resume` a **restart before the fix loads the
+  refused file**: fix and redeploy.
+- ⛔ Secrets are refused at declaration, before the HostFile exists (its `content` is a prop too).
+- ★ Both resources retain: removing them from a stack leaves the file a restart needs.
+
+## Managed Caddies: `--resume` and their own config dir
+
+★ **Decision, 2026-09-21.** A Caddy this package manages runs `caddy run --resume --config <file>`
+with `XDG_CONFIG_HOME` set to a directory of its own, so a restart runs the last config Caddy
+**accepted**. After every successful load (ours included) Caddy writes the config JSON to
+`$XDG_CONFIG_HOME/caddy/autosave.json`; `--resume` starts from it, and from `--config` only when no
+autosave exists (cmd/commandfuncs.go cmdRun). Read in caddyserver/caddy v2.11.4:
+
+- ★ **A refused Caddyfile on disk cannot take sites down.** The file is the first-boot fallback: a
+  new host, or an autosave someone deleted.
+- ★ **Its own directory,** so nothing else (a Homebrew service, a person's `caddy run`) writes the
+  autosave it resumes from. With neither `HOME` nor `XDG_CONFIG_HOME` a daemon would use `./caddy/`
+  under its working directory (storage.go AppConfigDir).
+- ⛔ **Set `XDG_CONFIG_HOME` in the job's `environment`, not the envfile.** The autosave path is
+  fixed when the binary starts (storage.go `var ConfigAutosavePath`), before `--envfile` is read.
+- ⛔ **No `persist_config off`** in a managed Caddyfile. It stops the autosave, so `--resume` starts
+  from a stale one (the last config before it) or, with none, from the file.
+- ⚠️ **A hand change through the API survives a restart.** The next plan reports it as drift, and the
+  deploy puts the declaration back.
+- ⚠️ **SIGUSR1 is not a way to change config.** After a resumed start Caddy records no source file
+  (cmdRun calls `SetLastConfig` only after loading `--config`), so SIGUSR1 is ignored with the log
+  line `last config unknown`. Our `Caddy-Config-Source-File` header keeps a source Caddy already
+  has (caddy.go ClearLastConfigIfDifferent) and never sets one. After a first boot from the file,
+  SIGUSR1 still reloads it: the text the deploy wrote. Change config by deploying. Editing the file
+  and running `caddy reload` is a hand `/load`, which the next plan reports as drift.
+- ⛔ **No `--watch`.** After a resumed start it has no file to watch, and falls back to a `Caddyfile`
+  in the working directory (cmd/main.go watchConfigFile).
+
+A Caddy not yet moved over (no `--resume`) restarts from `--config`: see the ⚠️ in
+[Order](#order-file-then-load).
+
+## Secrets
+
+Alchemy stores props unencrypted, and the Caddyfile is a prop. Use RUNTIME placeholders, which Caddy
+resolves in its own process, so the value never enters the state, the adapted JSON or the autosave:
+
+- `{env.NAME}` — start Caddy with `--envfile <path>`; a secret renderer (openbao-agent) writes that
+  file. A rotated value needs a Caddy restart.
+- `{file./path}` — the file's contents (trailing newline trimmed), read when the placeholder runs.
+- ⚠️ `{$NAME}` is substituted at **adapt** time: the value is in the adapted JSON, readable at
+  `GET /config/` and written to `autosave.json`. Not refused, but worse.
+- ⛔ `{$NAME:default}` puts the default in the prop, and Caddy uses it whenever `NAME` is unset. The
+  tripwire checks the default as a literal.
+- `basic_auth` replaces placeholders in the hash too: `admin {env.ADMIN_HASH}`.
+
+The tripwire refuses a PEM private key, a literal after `dns`/`acme_dns <provider>`, a secret-named
+subdirective (`api_token`, `client_secret`, `password`, …) with a literal value, a literal
+`Authorization`/`Cookie`/`X-Api-Key` header, and token shapes (GitHub, AWS, Slack, `sk-…`, JWT,
+bcrypt/argon2 hashes). It never echoes what it found. It is a tripwire, not a scanner.
+
+## The admin endpoint
+
+⛔ The admin API has no authentication: `localCaddyAdmin()` accepts only `http://` loopback or
+`unix:///path` (default `http://127.0.0.1:2019`), and a Caddyfile whose `admin` block would move,
+expose or lock out the API is refused before it loads. Host/Origin checks, narrowed `origins`, SSH
+forwards and every refusal: [caddy-admin.md](./caddy-admin.md).
+
+## Adoption
+
+★ **Nothing is adopted silently** (decision, 2026-09-21) — the rule `HostFile` and `LaunchdJob` keep.
+With no state, `read` is Alchemy's adoption probe, and what the Caddy runs decides:
+
+| running                             | read      | plan                                                       |
+| ----------------------------------- | --------- | ---------------------------------------------------------- |
+| the declared config (same digest)   | ours      | adopted; the forced update loads nothing                   |
+| nothing (`null`, or no apps)        | absent    | create — nothing to take over, as an empty R2 lock is none |
+| anything else                       | `Unowned` | refused unless the deploy runs with `--adopt`              |
+| a Caddyfile that cannot be compared | `Unowned` | the same, with a warning saying why                        |
+| no Caddy answering                  | absent    | create, with a warning; the apply checks again             |
+
+- ⚠️ **Alchemy skips the probe while the props hold an Output** — always on `caddyWithFile()`'s first
+  deploy, whose `sourceFile` is the HostFile's path. So the apply of a create checks too, and fails
+  before any `/load` unless the deploy runs with `--adopt`. The HostFile is written by then (a file
+  already at the path is the HostFile's own `Unowned`); under `--resume` a restart still runs the
+  autosave.
+- ★ **That apply-time check resolves adoption as the planner does:** a resource-scoped `adopt(…)`,
+  else `--adopt`. So `.pipe(adopt(false))` still refuses under `--adopt`, and `adopt(true)` works.
+- ★ **An uncomparable Caddyfile is `Unowned`, not an error**: the same read recovers an interrupted
+  create with that deploy's props, and a throw would fail every later plan, the fixed one included.
+
+## Removing it
+
+⛔ Delete never touches Caddy, under either removal policy. There is no "less config" to fall back
+to, and an empty config stops every server. `retain` is the default; with `destroy`, delete still
+only forgets. It never calls `/stop` or `DELETE /config/`. An empty Caddyfile, or one that adapts
+to no apps (only comments or global options), is refused for the same reason. To empty a Caddy, do
+it by hand at its admin API.
+
+## Traps
+
+- ⚠️ `import` paths resolve against Caddy's working directory (the API adapts with no file name).
+  Keep them absolute.
+- ⚠️ `/adapt` runs on the **running** binary. A Caddyfile that uses a plugin's directive (Cloudflare
+  DNS, caddy-security, layer4) needs that custom build running before it will validate.
+- ⚠️ **Bootstrap race.** Where Caddy is not running yet, the config can reach the admin API before
+  its launchd job has Caddy listening. The transport retries a refused connection (`retries`,
+  `retryDelayMs`; default 2 × 500 ms) — raise them, or rerun the deploy.
+- ⚠️ One `CaddyAdmin` per stack: the transport picks the Caddy, not a prop. Pointing it at another
+  Caddy plans an update; the old one keeps what it had. ⛔ State vouches only for the Caddy it was
+  applied to, so the apply loads there only if it serves nothing, runs the declared config or the
+  one last stored — anything else needs `--adopt`.

package/docs/launchd-sudo.md

@@ -0,0 +1,122 @@
+# Deploying a Mac host as yourself — `sudoRunner()`
+
+A host stack that declares system daemons needs root for a handful of calls. `sudoRunner()` lets
+the deploy run as you (the operator) and sends **only those calls** through `sudo -n`, in fixed
+argv shapes, logging each one. It is an explicit opt-in: nothing falls back to it, and
+`localRunner()` stays the default and never elevates.
+
+```ts
+import { launchdProviders, sudoRunner } from '@homeflare/alchemy/launchd';
+
+const runner = sudoRunner({
+  // ⛔ Required: the directories root may write. Each must be a real directory that root owns
+  //   and only root may write; that is checked at every privileged call.
+  prefixes: ['/Library/LaunchDaemons', '/opt/example'],
+  // log: (line) => …, // default: one line on stderr per privileged call
+});
+// Provide launchdProviders(runner) alongside the stack's other provider layers.
+```
+
+## What runs as root: the whole list
+
+Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path, never through a shell.
+
+| when                             | argv                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| a system job is bootstrapped     | `/bin/launchctl bootstrap system /Library/LaunchDaemons/<label>.plist` |
+| a system job is booted out       | `/bin/launchctl bootout system/<label>`                                |
+| (your own code, via `exec`)      | `/bin/launchctl kickstart [-k] [-p] system/<label>`                    |
+| a file under a prefix is written | `/usr/bin/install -S -m <0644> [-o <uid>] [-g <gid>] <staged> <path>`  |
+| a file under a prefix is removed | `/bin/rm -f -- <path>`                                                 |
+
+- A file's bytes never reach argv or the log: they are written, as you, to a `0600` file in a
+  fresh `0700` temp directory. `install` copies that file (and only that file) into place, and
+  the temp directory is removed afterwards, whether or not the install succeeded.
+- `install` writes a temp file beside the target and renames it (install(1) on macOS 27.2), so the
+  target is never torn. `-S` adds the fsync.
+- Owner and group are numeric ids, resolved by the provider before the call.
+
+## What stays as you
+
+- `launchctl print` and `print-disabled`. launchctl(1): "Anyone may read or query the system
+  domain"; measured on macOS 27.2, too (see `src/launchd/launchctl.ts`).
+- User and group lookups, `id -G`, every file read and `lstat`.
+- Files outside every prefix, and your own `gui/<uid>` jobs.
+
+★ So **a plan never calls sudo.** `read` and `diff` are reads; only an apply elevates.
+
+## Refused before sudo is asked
+
+- Any other argv. That includes a bare `bootout system` (which removes the whole system domain),
+  `bootstrap system <directory>` (which loads every plist in it), a plist anywhere but
+  `/Library/LaunchDaemons/<label>.plist` (the only place launchd loads daemons from at boot),
+  `rm -r`, `install -d`, a label under `org.nixos.`, `com.apple.` or `homebrew.mxcl.`, and any
+  argv whose program is `sudo`.
+- A system job's `bootstrap` or `bootout` when `/Library/LaunchDaemons` is not a prefix. ⚠️ Without
+  it a delete would boot the job out, then fail to remove its plist, which launchd loads again at
+  the next boot.
+- A prefix that is missing, a symlink, not owned by root, or writable by group or other. ⛔ A
+  symlinked prefix makes root write wherever it points, a path the log never names.
+- A path outside every prefix that needs root: another user as the owner, say.
+- A symlink or missing directory between the prefix and the file, or anything but a regular file
+  at the path. ⚠️ `install src <directory>` copies _into_ the directory, and a symlink to one does
+  the same.
+- A file you could not read back. Both providers read every write back, and read again at every
+  plan, as you. A root-only `0600` would be installed, then fail with `EACCES` and stay on disk
+  with no state. Membership comes from `id -G`, because macOS caps `getgroups()` at 16 (measured
+  2026-09-21: 16 against 18).
+- Another user's `gui/<uid>` or `user/<uid>` domain. Only the system domain is elevated.
+
+Every refusal above throws `SudoRefusedError`: nothing ran as root. A privileged command that ran
+and failed throws a plain `Error` with its exit code.
+
+## When sudo wants a password
+
+`sudo -n` never prompts. It fails at once, and the error says so: `a password is required, and
+this runner never prompts`. The command did not run. You have two options.
+
+1. **`sudo -v` just before the deploy.** This caches a ticket. By default it lasts 5 minutes and
+   is tied to one terminal (sudoers(5): `timestamp_timeout`, `timestamp_type`).
+   ⚠️ A deploy that outlives the ticket fails at its next privileged call. Every step is
+   idempotent (Alchemy requires `delete` to be), so `sudo -v` and deploying again converges. The
+   exception is a `LaunchdJob` label or domain change: it is delete-first, so if it fails between
+   the delete and the create, the job is down until you redeploy.
+2. **A `NOPASSWD` sudoers rule for exactly the shapes above.**
+   - ⛔ **That rule is root-equivalent.** Anyone who may `install` into `/Library/LaunchDaemons`
+     and `launchctl bootstrap system` can run any program as root. The allowlist protects you
+     from mistakes, not from the account that holds the rule.
+   - ⛔ **Never use wildcards in the arguments.** sudoers(5): in arguments, `*` also matches spaces
+     and `/`, so `/bin/rm -f -- /opt/example/*` matches `../../etc/x` and two paths at once. Use
+     `^…$` regular expressions (sudo 1.9.10 and later; macOS 27.2 ships 1.9.17p2) and forbid
+     `..`. Check the file with `visudo -c -f <file>` before you install it.
+   - ⚠️ The kit ships no tested rule. Nothing here has run sudo.
+
+⚠️ The error text sudo prints is **reasoned, not measured**. It comes from sudoers(5) and sudo(8)
+for sudo 1.9.17p2. A sudo refusal the runner does not recognise comes back as a failed command,
+with sudo's own stderr.
+
+## The log
+
+Each privileged call logs one line before it runs:
+
+```text
+homeflare/launchd sudo -n ["/bin/launchctl","bootstrap","system","/Library/LaunchDaemons/com.example.exporter.plist"]
+```
+
+The argv is written as JSON, so a space in a path cannot hide a second argument. The line holds
+the argv only, never file content. ⛔ A custom `log` should keep every line: the log is the only
+record of what ran as root.
+
+## Limits
+
+- ⚠️ **Moving a job from `system` to another user's `gui/<uid>` passes the plan and fails at
+  apply**, after the old job was already removed. The runner reports `privileged: true`, so the
+  plan-time check lets it through, and the refusal only comes at the write. Do that move as a
+  remove, then an add.
+- ⚠️ **Under a prefix, the runner writes as root.** An omitted owner is root, and an omitted group
+  is the directory's group (a new file's group on macOS).
+- ⚠️ **The checks guard against a mistaken declaration, not against a hostile one.** They run as
+  you, just before the call. The prefix itself must be root-only, but a directory _below_ it that
+  another user owns is not checked for that, and that user could swap what lies under it in
+  between. Keep every directory under a prefix root-owned, too. ACLs are not read, only mode bits.
+- ⛔ **macOS hosts.** Every argv shape was checked against macOS 27.2 man pages.

package/docs/launchd.md

@@ -112,8 +112,11 @@ The `system` domain, and another user's `gui/<uid>`, need root. The provider ref
 unless the runner is root (`effectiveUid() === 0`) or was deliberately built with
 `privileged: true`. `localRunner()` — the default — is never privileged and never calls `sudo`, so:
 
-- **system daemons:** start the whole deploy as root; or pass `launchdProviders(yourRunner)` where
-  `yourRunner` is a `HostRunner` you wrote that already holds root (a root helper, say).
+- **system daemons, deployed as yourself:** `launchdProviders(sudoRunner({ prefixes }))` sends only
+  the privileged calls through `sudo -n`, from a fixed allowlist, logging each. It never prompts.
+  See [launchd-sudo.md](./launchd-sudo.md).
+- **system daemons, deployed as root:** start the whole deploy as root; or pass
+  `launchdProviders(yourRunner)` where `yourRunner` is a `HostRunner` that already holds root.
 - **your own agents** (`gui/<your uid>`): no root needed.
 
 Reading (`launchctl print`, `print-disabled`) needs no root. ⚠️ A `HostFile` whose mode hides it
@@ -163,5 +166,5 @@ Nix job is booted out first. Per job:
 `HostRunner` (see `src/launchd/runner.ts`) is `exec(argv)` (never through a shell), `readFile`,
 `stat` (lstat), `writeFileAtomic`, `removeFile`, `lookupUser`, `lookupGroup`, `sleep`, plus
 `privileged` and `effectiveUid()`. `localRunner()` implements it with `node:fs` and
-`node:child_process`; tests use an in-memory fake, so nothing in the test suite runs `launchctl` or
-writes outside a temp directory.
+`node:child_process`; `sudoRunner()` wraps it and elevates the allowlist. Tests use an in-memory
+fake, so nothing in the test suite runs `launchctl` or `sudo`, or writes outside a temp directory.

package/docs/mesh-node.md

@@ -0,0 +1,188 @@
+# MeshNode — a Cloudflare Mesh node without its token in state
+
+`MeshNode` (`Cloudflare.MeshNode`) declares a Cloudflare Mesh node: the `warp_connector` object
+that a Linux host joins with the Cloudflare One Client. `fetchMeshNodeToken` fetches the node's
+enrolment token on demand, for a one-off enrolment step. Read 2026-09-21 against
+`alchemy@2.0.0-beta.79`, `@distilled.cloud/cloudflare@1.0.0-rc.12` and Cloudflare's Mesh docs.
+
+## Why not `Cloudflare.Tunnel.WarpConnector`
+
+- ⛔ **It puts the node token in state.** Its `toAttributes` calls the token endpoint on every
+  `read`, `reconcile` and `list`, and stores the result as an attribute. `Redacted` keeps it out
+  of logs, not out of the state store. The token lets any Linux host join the account's Mesh as
+  that node.
+- **It has no `ha` prop.** High availability can only be chosen when the node is created.
+- **Its plans need a Write token.** The token endpoint requires "Cloudflare One Connectors Write"
+  (or the cloudflared or Tunnel Write groups). `MeshNode` never calls it, so a plan can run on a
+  read token.
+
+## Declaring a node
+
+```ts
+import * as Cloudflare from 'alchemy/Cloudflare';
+import { MeshNode, providers as homeflareCloudflare } from '@homeflare/alchemy/cloudflare';
+
+// providers: Layer.mergeAll(Cloudflare.providers(), homeflareCloudflare()),
+const door = yield * MeshNode('vault-door', { name: 'door-a', ha: false });
+```
+
+| prop   | type      | notes                                                                             |
+| ------ | --------- | --------------------------------------------------------------------------------- |
+| `name` | `string`  | Unique per account. The identity used for adoption. Renames in place.             |
+| `ha`   | `boolean` | **Required, create-only.** The API default is `false`, the dashboard's is `true`. |
+
+Attributes: `id` (the node UUID), `accountId`, `name`, `status` (`inactive`, `degraded`,
+`healthy` or `down`, as of the last read or write) and `ha`. ⛔ There is no token attribute.
+
+The account and credentials come from Alchemy's own Cloudflare environment
+(`Cloudflare.CloudflareApiLive()`): an Alchemy profile, or `CLOUDFLARE_API_TOKEN` and
+`CLOUDFLARE_ACCOUNT_ID` in CI. So the node lands in the same account as the `Gateway.Rule` and
+`DNS.Record` resources that refer to it. `providers()` builds that layer itself, so the provider
+works whether or not the stack also merges `Cloudflare.providers()`.
+
+⛔ **Removal policy: `retain` by default**, like the kit's other resources whose deletion breaks
+their consumers. Dropping the declaration or `alchemy destroy` leaves the node live and only drops
+it from state. Opt a declaration into deletion with `.pipe(RemovalPolicy.destroy())`.
+
+### Choosing `ha`: a door is `ha: false`
+
+HA fails over the CIDR **routes** a node advertises. A node with no routes (a door: callers dial
+its Mesh IP) gains nothing from it, because the Mesh IP belongs to each replica: "Nodes without
+routes do not benefit from HA failover" (Cloudflare's Mesh HA page, read 2026-09-21). After a
+failover the promoted replica answers on its own Mesh IP, so nothing dialling the first one
+follows it.
+
+So a door is `ha: false`, and **a second door is a second `MeshNode`** with its own name, token
+and Mesh IP. Callers list both addresses. Keep `ha: true` for a subnet gateway with routes, on a
+device profile that uses MASQUE.
+
+## What each change does
+
+| change                   | answer                      | what happens on Cloudflare                                                                  |
+| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------- |
+| `name`                   | `update`                    | `PATCH`. The id, token, enrolled replicas and Mesh IPs all survive.                         |
+| `ha`, same `name`        | `replace`, **delete-first** | `retain` (default): **refused**, nothing written. `destroy`: old deleted, then new created. |
+| `ha` and `name` together | `replace`, create-first     | The new node is created. Under `retain` the old one stays live.                             |
+| account (provider env)   | `replace`, create-first     | As above; names are unique per account, so the two cannot collide.                          |
+
+⛔ **An `ha` replace is an outage for that node.** The new node has a new id and a new token, and
+each replica gets a new Mesh IP. Re-enrol every replica with the new token, and update anything
+that pins the old Mesh IP (Gateway rules, listener allow-lists) in the same change.
+
+★ **Why delete-first only when the name stays.** The new node needs the name the old one holds, so
+creating first would fail with code 1013 (`DuplicateTunnelName`). ⚠️ Unmeasured: whether a
+just-deleted node frees its name at once. If it does not, the create fails with code 1013 and a
+sentence; deploy again once the name is free. An invalid declaration is refused at plan time,
+before anything is deleted.
+
+### An `ha` change under `retain`
+
+`retain` also skips the old node's delete inside a replace. So a same-name `ha` change keeps the old
+node, which still holds the name, and the create **refuses** with a sentence and writes nothing. It
+never quietly reuses the old node, because that node still has the old `ha`. Measured through
+Alchemy's own plan/apply in `mesh-node-policy.test.ts`:
+
+| you want             | do                                                                                                                    |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| the replace          | Deploy once with `.pipe(RemovalPolicy.destroy())`: delete, then create. Then drop it.                                 |
+| the replace, by hand | Delete the old node yourself, then deploy again.                                                                      |
+| to keep the old node | `alchemy state rm <stack>/<stage>/<fqn>` (state only, not the node), then deploy the old declaration + `adopt(true)`. |
+
+⚠️ **Reverting `ha` is not enough.** The refused deploy leaves a `replacing` row, and the next
+plan resumes that replace whatever the props say, so it refuses again.
+
+⚠️ **`adopt(true)` alone does nothing to a `replacing` row.** The plan asks `read` to adopt only
+when a resource has no row, or after an interrupted first create. So every way back from inside a
+replace starts with `alchemy state rm`.
+
+⛔ **The old-node advice holds only when the name stayed.** After an `ha` + `name` change (a
+create-first replace), a node already holding the new name is another node, not the old one.
+`RemovalPolicy.destroy()` never touches it, and the refusal says not to delete it: choose another
+name, or check its HA badge, drop the row and adopt it.
+
+⚠️ Never deploy with `DISTILLED_DEBUG_HTTP` set: distilled prints the start of every response,
+and the create response carries the node's `token` field (Cloudflare's HA page says so).
+
+⚠️ Cloudflare may refuse to delete a node while replicas are connected. This is noted in Alchemy's
+WarpConnector and was not measured here. Stop the client on every replica before a destroy or an
+`ha` replace.
+
+## Adoption
+
+An existing node is found by **exact** name and returned `Unowned`. Alchemy refuses to take it
+over until the resource is wrapped in `adopt(true)` (or `--adopt` is passed). A deleted node is
+never matched, and a name that matches two live nodes is refused.
+
+An interrupted create (the node was made, its state was not saved) is found the same way on the
+next plan, so it too needs `adopt(true)`. ⚠️ distilled retries a create after a lost response or a
+5xx, and the retry is answered code 1013 by the node the first attempt made: the error then names
+that node's id. It is never adopted silently, because a concurrent creator looks the same. Inside
+a replace, drop the row before `adopt(true)`, as above.
+
+⚠️ **Adoption records the declared `ha`.** No documented read returns a node's HA flag:
+`GET /warp_connector/{id}` has no such field. Check the node's **HA** badge in the dashboard
+before adopting. A wrong value cannot be detected by any later plan.
+
+## Enrolling a host: `fetchMeshNodeToken`
+
+The token is a runtime credential. It never goes into Alchemy state or the vault; it goes straight
+to the host that runs the node. A one-off Bun `mesh-enroll` step:
+
+```ts
+import { fromApiToken } from '@distilled.cloud/cloudflare/Credentials';
+import { fetchMeshNodeToken } from '@homeflare/alchemy/cloudflare';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { open } from 'node:fs/promises';
+
+const token = await Effect.runPromise(
+  fetchMeshNodeToken({ accountId, id: nodeId }).pipe(
+    Effect.provide(Layer.mergeAll(fromApiToken({ apiToken }), FetchHttpClient.layer)),
+  ),
+);
+// ⛔ Created 0600 from the start, as root: no window where a chmod has not happened yet.
+const file = await open('/root/mesh-node.token', 'wx', 0o600);
+await file.writeFile(Redacted.value(token));
+await file.close();
+```
+
+- `{ accountId, name }` works too; the name is matched exactly.
+- The value comes back `Redacted`: `console.log`, `Effect.log` and `JSON.stringify` show
+  `<redacted>`. Call `Redacted.value` only at the write.
+- ⛔ **`fromApiToken`, not `Credentials.fromEnv()`.** `fromEnv` falls back to the Global API Key
+  (`CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`) when no token is set.
+- ⚠️ **The endpoint needs a Write permission.** Mint a short-lived token for this step alone. A
+  read token gets a 403, and the error names the permission.
+- ⚠️ `warp-cli --accept-tos connector new <token>` (Mesh get-started page) takes the token as an
+  **argument**, so it is visible in the host's process list while that command runs. Run it as
+  root on the node itself, in a shell that does not keep history.
+- An empty token fails closed. An empty file would otherwise "enrol" a host that never joined.
+- ⛔ **Refused before any request:** `DISTILLED_DEBUG_HTTP` set (distilled then prints the first
+  400 characters of every response body to stderr, which is the whole token), the Global API Key
+  (`apiKey` credentials), and an empty API token (a denied secrets grant, not a permission).
+
+## Permissions
+
+| step                    | needs (any one, per the API reference)                                   |
+| ----------------------- | ------------------------------------------------------------------------ |
+| plan / read (get, list) | Cloudflare One Connectors Read, or Cloudflare One Connector: WARP Read   |
+| create, rename, delete  | Cloudflare One Connectors Write, or Cloudflare One Connector: WARP Write |
+| `fetchMeshNodeToken`    | Cloudflare One Connectors Write (see below)                              |
+
+The token endpoint's API reference lists Connectors Write, "Cloudflare One Connector: cloudflared
+Write" and "Cloudflare Tunnel Write"; the Mesh get-started guide lists Connectors Write and
+"Cloudflare One Connector: WARP Write". Connectors Write is the one both name.
+
+## Not covered here
+
+- **Routes, device profiles and Gateway rules:** use Alchemy's `Tunnel.Route`,
+  `Devices.CustomProfile` and `Gateway.Rule`. ⚠️ HA needs MASQUE on the node's device profile.
+- **The HA provider configuration** (`/warp_connector/{id}/configurations`: `ha_mode` of `none`,
+  `disabled`, `aws` or `local` with VIPs) and **manual failover**. Its semantics for a node
+  created without `ha` are undocumented, so this resource neither reads nor writes it.
+- **Mesh IPs.** They belong to each replica (the `/connections` endpoint), not to the node, so
+  they are not attributes. Pin them in site config and check them against the API.
+- **`alchemy unsafe nuke`.** `list` is empty and nuke skips this type, because Alchemy's own
+  WarpConnector provider already lists every `warp_connector` in the account.

package/docs/peers.md

@@ -0,0 +1,39 @@
+# Peers — and why each pin exists
+
+The install line for `@homeflare/alchemy`, and why every peer on it and every entry in the
+`overrides` block is required. The block itself, which every consumer copies, is in the
+[README](../README.md#peers--and-one-override-you-need).
+
+```sh
+bun add @homeflare/alchemy alchemy@2.0.0-beta.79 effect@4.0.0-rc.115 \
+        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0 \
+        @distilled.cloud/cloudflare@1.0.0-rc.12
+```
+
+🔴 **Why, measured 2026-09-16 on 0.1.0 and re-checked 2026-09-17 against Alchemy 78.**
+Effect's `rc` line is not semver-compatible with itself. Alchemy 78's peer is
+`effect >= 4.0.0-rc.115`; an unlocked `@effect/platform-node-shared` still floats to the
+next rc and breaks at import. Pin the whole set.
+
+| what resolves                                                 | what happens                                           |
+| ------------------------------------------------------------- | ------------------------------------------------------ |
+| Alchemy 77 + `effect` → rc.115 (measured 2026-09-16)          | `TypeError: Config.string is not a function` at import |
+| `@effect/platform-node-shared` newer than the pinned `effect` | `Cannot find module 'effect/ByteSize'`                 |
+| `rolldown` → 1.2.9 via vite's `~1.2.6` (measured 2026-09-16)  | `GET …/rolldown-1.2.9.tgz - 404` at `bun add`          |
+| no `mime` (measured 2026-09-17 against Alchemy 78)            | `Cannot find package 'mime'` from cloudflare-runtime   |
+
+Alchemy 78 adapted to rc.115 — that first row is why we used to pin 112, not a reason to
+stay there. The override is still the only thing that holds the set together.
+
+⚠️ `@effect/platform-node` is **required, not optional**: Alchemy's module graph reaches
+`Cloudflare/Workers/WorkerBridge → @effect/platform-node/NodeServices` even when you only
+import the Proxmox subpath.
+
+⚠️ So is `mime`. Alchemy 78's `@alchemy.run/cloudflare-runtime` imported it without
+declaring it (measured 2026-09-17). 79 declares it; the peer stays so a consumer
+that followed the 78 README does not drop a required line.
+
+⚠️ So is `cloudflare`. It was marked optional in 0.1.1, which claimed the `/cloudflare`
+subpath would degrade without it — measured 2026-09-16, the subpath does not load at all:
+`Cannot find package 'cloudflare'`. An optional peer should mean a feature is absent, not
+that an import fails.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.6.0",
-  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos and launchd.",
+  "version": "0.8.0",
+  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
   "license": "MIT",
@@ -49,12 +49,17 @@
       "types": "./dist/launchd/index.d.ts",
       "default": "./dist/launchd/index.js"
     },
+    "./caddy": {
+      "types": "./dist/caddy/index.d.ts",
+      "default": "./dist/caddy/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
+    "@distilled.cloud/cloudflare": "1.0.0-rc.12",
     "@effect/platform-node": "4.0.0-rc.115",
     "alchemy": "2.0.0-beta.79",
     "cloudflare": ">=4.5.0",