@homeflare/alchemy 0.5.0 → 0.7.0

package/dist/openbao/role-reconcile.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The read / plan / reconcile loop the newer role families share (Bao.JwtRole, Bao.KubernetesRole,
+ * Bao.JwtAuthConfig): one path, one body, one comparison. Each family supplies its own form; this
+ * owns the order of operations, which is where the estate's providers have gone wrong before.
+ *
+ * ★ THE ORDER, AND WHY EACH STEP IS THERE:
+ *   1. Refuse a declaration the family knows is wrong, before any call (`problems`).
+ *   2. Read live. Write only when it differs — an identical write is still an audit line.
+ *   3. Before writing over a live object, refuse if the write would silently destroy something
+ *      this resource does not model (`wouldErase`, the ssh-role.ts pattern).
+ *   4. Re-read, and refuse unless live now MATCHES. A 2xx is not proof: the server can accept a
+ *      field and store something else (pki-role.ts has the history).
+ * ⛔ A DECLARATION reconcile WOULD REFUSE NEVER PLANS `noop` — `planRole` routes it to `update`,
+ *   so the refusal is seen at the next deploy instead of hiding behind a clean plan.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoError } from './bao-status.ts';
+export interface RoleSpec<A> {
+    /** `Bao.JwtRole` etc., for messages. */
+    readonly family: string;
+    /** The API path, e.g. `auth/jwt/role/humans`. */
+    readonly path: string;
+    readonly problems: readonly string[];
+    readonly attributesOf: (live: Record<string, unknown>) => A;
+    readonly matches: (attributes: A) => boolean;
+    readonly body: Readonly<Record<string, unknown>>;
+    /** Live fields a write would reset that the declaration does not model. */
+    readonly wouldErase?: (live: Record<string, unknown>) => readonly string[];
+}
+type Found<A> = {
+    readonly attributes: A;
+    readonly live: Record<string, unknown>;
+};
+export declare const readRoleAt: <A>(spec: RoleSpec<A>) => Effect.Effect<Found<A> | undefined, BaoError, HttpClient.HttpClient>;
+/** `update` or `noop` — the part of a diff after the identity checks. */
+export declare const planRole: <A>(spec: RoleSpec<A>) => Effect.Effect<'noop' | 'update', BaoError, HttpClient.HttpClient>;
+export declare const reconcileRole: <A>(spec: RoleSpec<A>) => Effect.Effect<A, BaoError, HttpClient.HttpClient>;
+export {};
+//# sourceMappingURL=role-reconcile.d.ts.map

package/dist/openbao/role-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-reconcile.d.ts","sourceRoot":"","sources":["../../src/openbao/role-reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAEnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,CAAC,KAAK,OAAO,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC;CAC5E;AAED,KAAK,KAAK,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAEnF,eAAO,MAAM,UAAU,GAAI,CAAC,QACpB,QAAQ,CAAC,CAAC,CAAC,KAChB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,UAAU,CAGnE,CAAC;AAEJ,yEAAyE;AACzE,eAAO,MAAM,QAAQ,GAAI,CAAC,QAClB,QAAQ,CAAC,CAAC,CAAC,KAChB,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,UAAU,CAK/D,CAAC;AAKL,eAAO,MAAM,aAAa,GAAI,CAAC,QACvB,QAAQ,CAAC,CAAC,CAAC,KAChB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,UAAU,CA0B/C,CAAC"}

package/docs/caddy.md

@@ -0,0 +1,180 @@
+# 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',
+    // --envfile: a file a secret renderer (openbao-agent) writes; {env.CF_API_TOKEN} reads it.
+    programArguments: [
+      '/usr/local/bin/caddy',
+      'run',
+      '--config',
+      file.path,
+      '--adapter',
+      'caddyfile',
+      '--envfile',
+      '/usr/local/etc/caddy.env',
+    ],
+    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, a running Caddy is **adopted** (its live config becomes the baseline)                      |
+| 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 — but a **restart before the fix loads
+  the refused file**. Fix and redeploy, or run Caddy with `--resume` (below).
+- ⛔ 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.
+
+## Autosave and `--resume`
+
+After every successful load (ours included) Caddy writes the config JSON to `autosave.json`
+(`$XDG_CONFIG_HOME/caddy/`, else `~/Library/Application Support/Caddy/` on macOS, `~/.config/caddy/`
+on Linux), unless the Caddyfile says `persist_config off`. ⚠️ A daemon started with no `HOME` and no
+`XDG_CONFIG_HOME` falls back to `./caddy/` under its working directory (storage.go AppConfigDir):
+set `XDG_CONFIG_HOME` in the launchd job so autosave lands where you expect.
+
+- **Without `--resume`** (the mini's Caddy today): a restart loads `--config`. The file and the
+  running config agree after every successful deploy; see the ⚠️ above for a failed one.
+- **With `caddy run --resume --config <file>`**: a restart loads `autosave.json` — the last config
+  Caddy **accepted** — and `--config` only when no autosave exists. A refused file on disk can then
+  never take sites down. The trade: a hand change through the API also survives a restart; the next
+  plan reports it as drift and the deploy puts the declaration back.
+- `--watch` reloads the file on change; our `/load` right after is then a no-op ("config is
+  unchanged").
+- `sourceFile` rides as `Caddy-Config-Source-File`, as `caddy reload` sends it. Without it a load
+  makes Caddy forget its source file, and SIGUSR1 stops reloading from it. The header only KEEPS the
+  file Caddy started with (caddy.go ClearLastConfigIfDifferent); it never sets a new one. ⚠️ Under
+  `--resume` with an autosave, Caddy records no source file at all, so SIGUSR1 has nothing to reload.
+
+## 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
+(`127.0.0.0/8`, `localhost`, `[::1]`) or `unix:///path`; the default is `http://127.0.0.1:2019`.
+
+- **Host and Origin.** Caddy refuses a request whose `Host` is not an allowed origin (DNS-rebinding
+  guard; measured on Caddy 2.11.4: `403 host not allowed`), and checks `Origin` when one is sent or
+  `enforce_origin` is on. The transport sends both as the Caddy CLI does. A unix socket skips the
+  Host check entirely.
+- **`admin { origins … }`** narrowed, or **an SSH-forwarded port** (Caddy checks the Host against
+  ITS port): pass `hostHeader: 'localhost:2019'`.
+- **Another host's Caddy** (SSH later): forward its socket or port to loopback here and point a
+  `localCaddyAdmin()` at it, or implement `CaddyAdmin` over your own route. Never expose :2019.
+- **A Caddyfile cannot strand the provider.** Before loading, the adapted `admin` block is refused
+  if it turns the API off, listens off loopback or somewhere the transport does not reach (another
+  port, socket or loopback address: `[::1]` is not `127.0.0.1`, and `localhost` binds IPv4), allows
+  no Host the transport sends (its `origins`, or Caddy's loopback defaults when there are none), sets
+  `enforce_origin` over a unix socket (no Origin is sent there), enables `remote`, or pulls config.
+- ⛔ **No `admin` address means Caddy's default** (`localhost:2019`, or `$CADDY_ADMIN`) after the
+  load. That is refused unless the transport is at that default: a Caddy reached on a socket or
+  another port declares `admin <address>` in its Caddyfile.
+
+## Adoption
+
+With no state, `read` reports the running Caddy's live config as plain (owned) attributes, so the
+first deploy adopts it silently and its forced update loads the declared Caddyfile — a full replace
+of whatever ran before. ⚠️ Review the plan: the Caddy on this loopback admin API is the one you get.
+
+## 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 that loads there; the old one keeps what it had.

package/docs/launchd.md

@@ -0,0 +1,167 @@
+# launchd — `@homeflare/alchemy/launchd`
+
+Declare a Mac host with Alchemy: its launchd jobs (`LaunchdJob`) and the config files they read
+(`HostFile`). launchd has no SDK, so the provider renders the plist itself and drives
+`launchctl`. Every file read, file write and `launchctl` call goes through one injectable
+`HostRunner`.
+
+```ts
+import * as Effect from 'effect/Effect';
+import { HostFile, LaunchdJob, launchdProviders } from '@homeflare/alchemy/launchd';
+
+export const exporter = Effect.gen(function* () {
+  const config = yield* HostFile('exporter-config', {
+    path: '/usr/local/etc/example-exporter.yml',
+    content: 'listen: 127.0.0.1:9100\n',
+    mode: 0o644,
+    owner: 'root',
+    group: 'wheel',
+  });
+  yield* LaunchdJob('exporter', {
+    label: 'com.example.exporter',
+    domain: 'system', // or 'gui/<uid>' for a LaunchAgent
+    // ★ config.path, not the literal: the Output orders the job after its file is written.
+    programArguments: ['/usr/local/bin/example-exporter', '--config', config.path],
+    environment: { TZ: 'UTC' }, // ⛔ non-secret values only
+    runAtLoad: true,
+    keepAlive: { successfulExit: false },
+    throttleInterval: 30,
+    standardOutPath: '/var/log/example-exporter.log',
+    standardErrorPath: '/var/log/example-exporter.log',
+  });
+});
+// Provide launchdProviders() alongside the stack's other provider layers.
+```
+
+## LaunchdJob
+
+| prop                          | plist key                        | notes                                                  |
+| ----------------------------- | -------------------------------- | ------------------------------------------------------ |
+| `label`                       | `Label`                          | also the file name; `[A-Za-z0-9._-]`, no `/`           |
+| `domain`                      | —                                | `system` (LaunchDaemons) or `gui/<uid>` (LaunchAgents) |
+| `programArguments`            | `ProgramArguments`               | first element must be an absolute path                 |
+| `environment`                 | `EnvironmentVariables`           | ⛔ non-secret only (see below)                         |
+| `runAtLoad`                   | `RunAtLoad`                      |                                                        |
+| `keepAlive`                   | `KeepAlive`                      | `true`/`false` or `{ successfulExit, crashed }`        |
+| `startInterval`               | `StartInterval`                  | seconds, > 0                                           |
+| `startCalendarInterval`       | `StartCalendarInterval`          | one entry or a list; fields are range-checked          |
+| `throttleInterval`            | `ThrottleInterval`               | seconds, ≥ 0                                           |
+| `standardOutPath` / `…Error…` | `StandardOutPath` / `…ErrorPath` | absolute                                               |
+| `workingDirectory`            | `WorkingDirectory`               | absolute                                               |
+| `userName` / `groupName`      | `UserName` / `GroupName`         | system domain only — launchd ignores them for agents   |
+| `extraKeys`                   | anything else, verbatim          | may not repeat a key a typed prop owns                 |
+
+The plist path is derived, never declared: `/Library/LaunchDaemons/<label>.plist` for `system`,
+`<home of uid>/Library/LaunchAgents/<label>.plist` for `gui/<uid>`.
+
+| step    | what happens                                                                                        |
+| ------- | --------------------------------------------------------------------------------------------------- |
+| create  | write the plist atomically (system: `root:wheel 0644`), then `launchctl bootstrap`                  |
+| update  | write, `bootout` the running job (and wait until launchd lets go), `bootstrap` — **a restart**      |
+| read    | `launchctl print` (loaded? state, pid, last exit) plus the SHA-256 of the plist on disk             |
+| diff    | the rendered plist's SHA-256 against the stored digest **and** the on-disk one, plus "is it loaded" |
+| replace | only when `label` or `domain` changes — **delete first**, so two copies never run at once           |
+| delete  | `bootout` if loaded, remove the plist; idempotent                                                   |
+
+- A converged job is not restarted: a retried deploy that finds the right plist loaded does nothing.
+- ⛔ **A rename is checked at plan time.** Alchemy deletes the old job before it creates the new
+  one, so everything the new one would be refused for (an invalid or reserved label, a domain you
+  may not write, a disabled label, a label another job already holds) fails the **plan**, with the
+  old job still running. A rename is seen even while other props are unresolved Outputs.
+- ⚠️ A failed `bootstrap` leaves the job **down**. On an update the new plist stays on disk, the
+  state keeps the old digest, and the next deploy retries. On a first create the plist is removed
+  again, so the next plan does not find its own file and call it someone else's.
+  There is no rollback to an older plist.
+- ⛔ A label disabled with `launchctl disable` is refused, not re-enabled: that was someone's
+  decision. The error names the `launchctl enable` command to run if it is stale.
+- ⚠️ A `gui/<uid>` job needs that user logged in: without a login session the domain does not
+  exist (`launchctl print` exits 112, "Could not find domain"; measured). Deploying refuses before
+  it writes anything. Deleting still removes the plist, which stops launchd loading it at login.
+- ⚠️ The digest covers the rendered bytes, so a kit upgrade that changes the renderer's output
+  restarts every declared job on the next deploy. Such a release says so in its changelog.
+
+## HostFile
+
+`path` (absolute, normalised), `content` (UTF-8 text), `mode` (default `0o644`), `owner` and
+`group` (names or ids). Written as a temp file in the same directory — mode and owner set before
+it becomes visible — then renamed over the path. Read back after every write. Diffed by SHA-256,
+mode and owner. A new `path` is a create-before-delete replace. Delete removes the file.
+
+- ⛔ A different file already at a new `path` is refused, not overwritten: the adoption probe
+  never looks at a replace's new path, so a typo there would otherwise overwrite a system file.
+
+- ⛔ A symlink or directory at the path is refused, never replaced: rename over a symlink replaces
+  the link, which takes the path from whatever tool owns it (nix-darwin's `/etc` entries point
+  into `/nix/store`).
+- ⚠️ The parent directory must exist. Creating it would invent an owner and mode nobody declared.
+
+## ⛔ No secrets in props
+
+Alchemy stores props and attributes **unencrypted** in its state store. A job's `environment`,
+`programArguments` and `extraKeys`, and a file's `content`, land there, in every plan diff, and on
+disk.
+
+**Keep secret files rendered by a secret renderer** — `openbao-agent` templates on a HomeFlare
+host — and declare only the path: `FOO_TOKEN_FILE=/path`, `--token-file /path`. A tripwire refuses
+the obvious mistakes (a `*_TOKEN`/`*_PASSWORD`-style variable, `--token=…`, a PEM private key); it
+is not a scanner, and passing it does not make a value safe to declare.
+
+## ⛔ No silent sudo
+
+The `system` domain, and another user's `gui/<uid>`, need root. The provider refuses up front
+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).
+- **your own agents** (`gui/<your uid>`): no root needed.
+
+Reading (`launchctl print`, `print-disabled`) needs no root. ⚠️ A `HostFile` whose mode hides it
+from the planning user (a root-owned `0600`, say) fails the plan with `EACCES`: plan as the user
+you deploy as.
+
+## Adoption: nothing is taken over silently
+
+`read` with no prior state reports anything it finds — a loaded label, a plist, a file — as
+`Unowned`, so Alchemy refuses to take it over without `--adopt`.
+
+Labels under `org.nixos.`, `com.apple.` and `homebrew.mxcl.` are **refused outright**. nix-darwin
+rewrites its plists on every activation and unloads any it no longer lists, macOS owns
+`com.apple.*`, and `brew services` owns `homebrew.mxcl.*`. Adopting one would give a file two
+owners. Move the job instead.
+
+## Cutover from nix-darwin
+
+Nix-managed `org.nixos.*` jobs are **not adopted**. The host stack declares a **new** label, and the
+Nix job is booted out first. Per job:
+
+1. **Declare** the replacement in the host stack under a new label (`com.example.<job>`), with its
+   config as `HostFile`s. ⚠️ Nothing it references may live in `/nix/store` — the next garbage
+   collection deletes it. Plan it: expect creates only.
+2. **Remove the job from the nix-darwin config and activate.** Activation unloads and deletes every
+   daemon it no longer lists — checked 2026-09-21 in a nix-darwin activation script: it prints
+   `removing service <label>`, runs `launchctl unload`, then removes the plist. Confirm with
+   `launchctl print system/org.nixos.<job>` → exit 113 ("Could not find service").
+3. **Deploy** the host stack. The new label bootstraps.
+4. **Verify** `launchctl print system/com.example.<job>` shows `state = running`, then check the
+   service itself (port, metrics, logs).
+
+- ★ **Why this order.** Both jobs usually bind the same port and write the same files; the old one
+  must be gone before the new one starts. Downtime is one deploy.
+- ⚠️ **`sudo launchctl bootout system/org.nixos.<job>` is not a cutover.** The plist stays in
+  `/Library/LaunchDaemons`, so launchd loads it again at the next boot; and activation (checked in
+  the same script) copies back and `load -w`s any Nix plist that is missing or differs from the
+  store. Either way two copies end up fighting over the port.
+- ⚠️ **Check the host's own activation for labels it removes.** An activation script can boot out,
+  `disable` and delete jobs by name on every run; a new label that collides with one is disabled
+  under you. `grep -n 'bootout\|disable' /run/current-system/activate` before choosing labels.
+- **Rolling back** is the same three steps reversed: destroy (or remove) the resource, restore the
+  job in the Nix config, activate.
+
+## The runner
+
+`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.

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.5.0",
-  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo and Talos.",
+  "version": "0.7.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",
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "src",
     "README.md",
     "LICENSE"
@@ -44,12 +45,21 @@
       "types": "./dist/proxmox/index.d.ts",
       "default": "./dist/proxmox/index.js"
     },
+    "./launchd": {
+      "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",