@homeflare/alchemy 0.1.0

package/src/openbao/policy.ts

@@ -0,0 +1,212 @@
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Path from 'effect/Path';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { sha256 } from './digest.ts';
+import { isEmptyAssembly } from './policy-assembly.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+
+/**
+ * An OpenBao ACL policy, assembled from the HCL fragments that declare it.
+ *
+ * ★ WHY THIS EXISTS. The estate already hand-rolled both halves of what Alchemy provides:
+ *   five `apply-*.sh`/`apply-*.py` scripts converge OpenBao, and separate `check-*.sh`
+ *   gates compare live to repo and refuse on drift. That is `reconcile` and `diff` written
+ *   twice, in two languages, with nothing recording what was applied — and one of those
+ *   gates blocked a deploy today because its own path had rotted.
+ *
+ * ⛔ THERE IS NO `Bao.Secret`, AND THERE MUST NEVER BE ONE. Alchemy persists attributes to
+ *   its state store and does NOT encrypt them: StateEncoding.ts unwraps `Redacted` to
+ *   plaintext under a marker key, and nothing under alchemy/src/State encrypts. This
+ *   estate's state store is the `alchemy` Postgres database, which pg-backup.sh dumps
+ *   nightly (it enumerates EVERY non-template database), copies to CT100, and PBS backs up
+ *   from there. A KV value here would exist in four places, none of them OpenBao.
+ *
+ *   So this declares the SHAPE AROUND secrets. Every attribute it stores is a name, a
+ *   count, or a hash.
+ *
+ * ⛔ EVERY PRIMITIVE IS ALCHEMY'S OR EFFECT'S, NOT NODE'S. An earlier cut of this file used
+ *   `node:child_process` + `promisify(execFile)` and `node:fs/promises`, which is
+ *   hand-rolling inside a bun + Effect codebase: it loses the Scope, the typed
+ *   PlatformError, and the Layer that makes the provider testable without a real vault.
+ *   ★ `CommandExecutor.run` was tried first and blocked read/diff: Alchemy passes a session
+ *   to reconcile/delete but NOT to read/diff (Provider.ts:258-289), so the fix was Alchemy's
+ *   OWN Docker pattern — `ChildProcessSpawner` + `ChildProcess.make`, which needs only a
+ *   Scope (Docker.ts:476-553). ★ SINCE 2026-09-14 THE CALLS ARE OpenBao's HTTP API through
+ *   Effect's `HttpClient` (bao-http.ts), which needs no session either, so read/diff still work.
+ *   FileSystem and Path come from `effect/*` directly — in Effect 4 they moved into core.
+ */
+export interface BaoPolicyProps {
+  /** Policy name, as `sys/policies/acl/<name>` takes it. */
+  name: string;
+  /**
+   * Directory of `*.hcl` fragments.
+   *
+   * ⚠️ CONCATENATED IN SORTED ORDER, EACH FOLLOWED BY A NEWLINE — byte-identical to
+   *   apply-agent-policy.sh, which is what wrote the live policy. Any other joining makes
+   *   the first plan report an update on a policy nobody changed.
+   */
+  fragments: string;
+}
+
+export interface BaoPolicyAttributes {
+  /** Policy name. */
+  name: string;
+  /** SHA-256 of the assembled HCL. The whole diff, and safe to persist. */
+  digest: string;
+  /** `path "..."` grants — the number apply-agent-policy.sh prints. */
+  grants: number;
+  /** Fragment files that produced it, so a plan reads like the directory. */
+  parts: number;
+}
+
+export interface BaoPolicy extends Resource<
+  'Bao.Policy',
+  BaoPolicyProps,
+  BaoPolicyAttributes,
+  never,
+  HttpClient.HttpClient | FileSystem.FileSystem | Path.Path
+> {}
+
+/**
+ * ⛔ `retain` — DELETING A POLICY REVOKES EVERY GRANT IT CARRIES, and this is the ONLY family in
+ *   this package with live instances, so it is the only one where the default could ever fire.
+ *
+ * 🔴 IT WAS THE ONLY FAMILY WITHOUT IT. Every sibling passes `{ defaultRemovalPolicy: 'retain' }`
+ *   — auth-role.ts:37, mount.ts:40, pki-role.ts, proxmox-role.ts, ssh-role.ts — each with a ★
+ *   explaining what deletion destroys. This file has the same warning on its own `delete` handler
+ *   and did not carry the option, which is the worst possible combination: the danger is
+ *   documented and the guard is missing.
+ *   ⛔ WHAT THAT MEANT IN PRACTICE, on 2026-09-13: ten live policies are named in a `const` array
+ *     in alchemy.run.ts. Removing a name from that array orphans the resource, and without
+ *     `retain` the next deploy calls `bao policy delete` on it — including the 86-line policy that
+ *     decides what the agent working in this repo can reach. A one-word edit, no plan line saying
+ *     "revoke", and the grants are gone. The array grew from four names to ten that same day,
+ *     which multiplied the blast radius of a mistake nobody had guarded against.
+ *
+ * ⚠️ `retain` DOES NOT WEAKEN `delete`, WHICH STAYS FULLY IMPLEMENTED. The engine skips it for an
+ *   orphaned resource; a caller that means it opts in with `.pipe(RemovalPolicy.destroy())`. This
+ *   is Terraform's `prevent_destroy`, not a stubbed operation — a delete that silently did nothing
+ *   would lie to whoever read the plan.
+ */
+export const BaoPolicy = Resource<BaoPolicy>('Bao.Policy', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `path "..."` grant count — the same number the apply script prints. */
+const grantsOf = (hcl: string) => (hcl.match(/^path /gm) ?? []).length;
+
+const attributesOf = (name: string, hcl: string, parts: number): BaoPolicyAttributes => ({
+  name,
+  digest: sha256(hcl),
+  grants: grantsOf(hcl),
+  parts,
+});
+
+export const BaoPolicyProvider = () =>
+  Provider.effect(
+    BaoPolicy,
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+
+      /** Assemble fragments exactly as apply-agent-policy.sh does. */
+      const assemble = (dir: string) =>
+        Effect.gen(function* () {
+          const entries = (yield* fs.readDirectory(dir)).filter((f) => f.endsWith('.hcl')).sort();
+          let joined = '';
+          for (const f of entries) joined += `${yield* fs.readFileString(path.join(dir, f))}\n`;
+          return { joined, parts: entries.length };
+        });
+
+      return BaoPolicy.Provider.of({
+        /**
+         * ⛔ `bao policy list` IS NOT A LIST OF THINGS THIS OWNS. Every policy in the
+         *   namespace answers, including ones written by hand years ago. Returning them
+         *   would invite Alchemy to adopt — and then delete — policies it never created.
+         */
+        list: () => Effect.succeed([]),
+
+        // ★ '' means genuinely absent (a 404); a refusal fails. policy-wire.ts has the history.
+        read: Effect.fn(function* ({ olds }) {
+          const live = yield* readPolicy(olds.name);
+          return live.length === 0 ? undefined : attributesOf(olds.name, live, 0);
+        }),
+
+        /**
+         * ⛔ IT COMPARES THE LIVE POLICY, NOT THE STORED DIGEST. A policy edited in the
+         *   OpenBao UI is exactly the drift the check-* gates exist to catch, and a
+         *   provider that trusted its own state would report `noop` straight through it.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          // ⚠️ A prop can still be an unresolved Output or Config at plan time. Docker's
+          //   own providers guard with isResolved and skip rather than guess; a diff that
+          //   read a Config as a string would compare a placeholder to real HCL.
+          if (output === undefined || !isResolved(news)) return undefined;
+          const { joined } = yield* assemble(news.fragments);
+          const live = yield* readPolicy(news.name);
+          return live.length > 0 && sha256(live) === sha256(joined)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          const name = news.name;
+          const { joined, parts } = yield* assemble(news.fragments);
+          /**
+           * ⛔ AN EMPTY ASSEMBLY IS A REFUSAL, NOT AN EMPTY POLICY. `bao policy write` with
+           *   no paths SILENTLY REVOKES every grant the policy carries, for every token
+           *   bound to it — and a mistyped or moved fragments directory reads exactly like
+           *   a policy with nothing in it. This estate lost a deploy today to a directory
+           *   that moved; it must not lose a vault to one.
+           */
+          // ⛔ No FILES was the first guard; no GRANT is the real one — see policy-assembly.ts.
+          if (isEmptyAssembly(parts, joined))
+            return yield* Effect.die(
+              new Error(
+                `Bao.Policy ${name}: the fragments under ${news.fragments} carry no path grant ` +
+                  `(${String(parts)} file(s)). Writing it would revoke every grant the policy carries.`,
+              ),
+            );
+          /**
+           * ⛔ ADOPTING A POLICY THAT ALREADY MATCHES MUST NOT REWRITE IT. Alchemy's `adopted`
+           *   action is NOT a read — Apply.ts routes it down the same branch as `update` and calls
+           *   reconcile — so the first deploy after declaring the four policies this estate
+           *   already has would have run `bao policy write` over all four. Byte-identical in the
+           *   happy case, and a SILENT REWRITE OF LIVE GRANTS the moment the repo fragments have
+           *   drifted from what is deployed.
+           *
+           * ★ THE GUARD IS THE SAME EXPRESSION `diff` USES, deliberately: one definition of
+           *   "settled" for this resource, so the plan and the write can never disagree. The
+           *   sibling PVE provider does exactly this in pveOperations.reconcile.
+           */
+          const current = yield* readPolicy(name);
+          if (current.length > 0 && sha256(current) === sha256(joined)) {
+            return attributesOf(name, joined, parts);
+          }
+          // ⚠️ In the request body, never on argv — see `writePolicy` for why the temp file went.
+          yield* writePolicy(name, joined);
+          return attributesOf(name, joined, parts);
+        }),
+
+        /**
+         * ⛔ DELETING A POLICY REVOKES EVERY GRANT IT CARRIES. Idempotent as Alchemy
+         *   requires — already gone is success — but this is the one operation with teeth.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          /**
+           * ⛔ A REFUSED DELETE FAILS. This is "the one operation with teeth" the note above
+           *   names, and it used to run through the read helper, which discarded the exit code —
+           *   so a REFUSED policy delete reported success and the row left Alchemy's state while
+           *   every grant it carried stayed live. Idempotence is preserved: a 404 is still
+           *   success, and a 403 is not (bao-status.ts).
+           */
+          yield* deletePolicy(output.name);
+          return undefined;
+        }),
+      });
+    }),
+  );

package/src/openbao/proxmox-role-form.ts

@@ -0,0 +1,174 @@
+/**
+ * Wire and comparison half of Bao.ProxmoxRole — the resource itself is proxmox-role.ts.
+ *
+ * MEASURED 2026-09-13, read-only, against the live server (BAO_ADDR=http://127.0.0.1:8200,
+ * BAO_NAMESPACE=homeflare). No write of any kind was issued to a role or a mount:
+ *
+ *   bao read -format=json proxmox-tb4/roles/read
+ *     → { max_ttl: 21600, mint_user: "hf-read@pve",      name: "read",      ttl: 3600 }
+ *   bao read -format=json proxmox-tb4/roles/provision
+ *     → { max_ttl: 1800,  mint_user: "hf-provision@pve", name: "provision", ttl: 300 }
+ *   GET /v1/proxmox-tb4/?help=1 → components.schemas.WriteRolesNameRequest:
+ *     mint_user  string  — the ONLY required field, described as "The `user@realm` whose
+ *                          standing ACL is the minted token's entire privilege set. Created
+ *                          out-of-band; this engine never grants ACLs."
+ *     ttl        integer — "format": "seconds"
+ *     max_ttl    integer — "format": "seconds", "Narrows the mount's; can never widen it."
+ *
+ * ★ name + mint_user + ttl + max_ttl IS THE WHOLE ROLE. The plugin stores nothing else, so
+ *   `matches` below covers 100% of the server-side state: there is no unmanaged field left to
+ *   drift behind a green plan. That completeness is bought by making the TTLs REQUIRED props
+ *   rather than the optional-means-unmanaged shape Bao.Mount uses — see the ⛔ on writeBody.
+ */
+import { sha256 } from './digest.ts';
+import { mountPath, parseDuration, ttlSeconds } from './mount-form.ts';
+
+export interface BaoProxmoxRoleProps {
+  /** Mount path of the proxmox secrets engine, e.g. `proxmox-tb4`. A trailing slash is fine. */
+  mount: string;
+  /**
+   * Role name, as `<mount>/roles/<name>` takes it.
+   *
+   * ⚠️ The plugin's own schema says the name "Appears in the minted token's id, so keep it
+   *   short." Both live roles are one word (`read`, `provision`). A long name here becomes a
+   *   long PVE token id on every mint.
+   */
+  name: string;
+  /**
+   * ⛔ THE ENTIRE SECURITY BOUNDARY OF THIS RESOURCE. A minted token inherits this PVE user's
+   *   standing ACL and nothing else — the engine never grants ACLs, it only borrows one. Change
+   *   this string and every credential the role issues from then on carries a different
+   *   privilege set, with no other field in the declaration changing to hint at it. That is why
+   *   it is compared in `matches` below, and why reconcile refuses to move it without
+   *   `allowMintUserChange`.
+   */
+  mintUser: string;
+  /** Default lease TTL for minted tokens, e.g. `1h`. REQUIRED — see the ⛔ on writeBody. */
+  ttl: string;
+  /**
+   * Maximum lease TTL, e.g. `6h`. REQUIRED — see the ⛔ on writeBody.
+   *
+   * ⚠️ "Narrows the mount's; can never widen it." A role declaring `6h` under a mount whose
+   *   max_lease_ttl is `1h` still READS BACK as 21600, so this resource reports noop and the
+   *   plan is green — while every actual mint is capped at 3600 by the mount. The role is not
+   *   lying and neither is the plan; the ceiling simply lives one level up. If a consumer gets
+   *   a shorter lease than declared here, check `bao read sys/mounts/<mount>` before touching
+   *   the role.
+   */
+  maxTtl: string;
+  /**
+   * Permission to re-scope `mintUser` on an EXISTING role: set it to the CURRENT live mint_user
+   * that this change is allowed to replace.
+   *
+   * ★ IT IS A STRING AND NOT A BOOLEAN, AND THAT IS THE WHOLE POINT. A `true` left behind after
+   *   one legitimate rename would wave through every future re-scope of that role forever —
+   *   including one pasted in by whoever copies this block as a template. Naming the value being
+   *   replaced makes the permission SELF-EXPIRING: the moment the change lands, live equals
+   *   `mintUser`, the guard stops consulting it, and the next re-scope finds a stale string that
+   *   does not match live and is refused on its own merits.
+   *
+   * Not persisted, not in attributes, not in `matches` — it describes the operator's intent, not
+   * the server, so changing it alone is correctly a noop. See the ⛔ in proxmox-role.ts reconcile.
+   */
+  allowMintUserChange?: string;
+}
+
+export interface BaoProxmoxRoleAttributes {
+  /** Mount path, trailing slash stripped. */
+  mount: string;
+  /** Role name. */
+  name: string;
+  /** The PVE `user@realm` live tokens are minted under. A name, never a credential. */
+  mintUser: string;
+  /** Live default lease TTL, rendered back into the duration shape props use. */
+  ttl: string;
+  /** Live maximum lease TTL, same shape. */
+  maxTtl: string;
+  /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
+  digest: string;
+}
+
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+
+/**
+ * Seconds back into the duration shape the props use.
+ *
+ * ⚠️ Third private copy of this function in the package (mount-form.ts and auth-role-form.ts
+ *   each keep one). Exporting a single copy means editing a file this change does not own, so
+ *   it is duplicated deliberately rather than silently. Worth collapsing in a follow-up.
+ */
+const ttlText = (seconds: number | undefined, fallback = '0') => {
+  if (seconds === undefined) return fallback;
+  if (seconds % 86400 === 0) return `${String(seconds / 86400)}d`;
+  if (seconds % 3600 === 0) return `${String(seconds / 3600)}h`;
+  if (seconds % 60 === 0) return `${String(seconds / 60)}m`;
+  return `${String(seconds)}s`;
+};
+
+/** `proxmox-tb4/roles/read` — read, write and delete all address the role here. */
+export const rolePath = (mount: string, name: string) => `${mountPath(mount)}/roles/${name}`;
+
+export const attributesOf = (
+  props: BaoProxmoxRoleProps,
+  live: Record<string, unknown>,
+): BaoProxmoxRoleAttributes => {
+  const attrs = {
+    mount: mountPath(props.mount),
+    // ⚠️ The plugin echoes `name` in a role read, so it is taken from `live` with the prop only
+    //   as a fallback. Every other value below is live-only: the same split the sibling
+    //   resources use, so a read never launders a declaration back into itself as "current".
+    name: text(live['name']) || props.name,
+    mintUser: text(live['mint_user']),
+    ttl: ttlText(ttlSeconds(live['ttl'])),
+    maxTtl: ttlText(ttlSeconds(live['max_ttl'])),
+  };
+  return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
+};
+
+/**
+ * The body for `PUT <mount>/roles/<name>` — all strings, the `k=v` pairs `bao write` sent — or
+ * the prop names whose duration would not parse.
+ *
+ * ⛔ A WRITE TO roles/{name} REPLACES THE ROLE, IT DOES NOT MERGE. An omitted `ttl` is written
+ *   as the field's zero value, so a resource that treated undeclared TTLs as "unmanaged" — the
+ *   Bao.Mount shape — would silently reset a lease ceiling every time it rewrote the role for an
+ *   unrelated reason. Both TTLs are therefore required props and EVERY write carries all three
+ *   fields. REASONED from the Vault secrets-framework write semantics plus this plugin's schema
+ *   marking only `mint_user` required; NOT measured, because this session was read-only and
+ *   proving it would have meant writing to the live engine.
+ *
+ * ⚠️ Seconds go on the wire as integers, not as `1h`. The schema declares both TTLs
+ *   `"format": "seconds"`, and an integer is accepted unambiguously by every path that reads
+ *   them back — which is what keeps the round-trip through `matches` stable.
+ */
+export const writeBody = (
+  props: BaoProxmoxRoleProps,
+): { ok: true; body: Record<string, string> } | { ok: false; bad: string[] } => {
+  const ttl = parseDuration(props.ttl);
+  const maxTtl = parseDuration(props.maxTtl);
+  const bad: string[] = [];
+  if (ttl === undefined) bad.push(`ttl=${props.ttl}`);
+  if (maxTtl === undefined) bad.push(`maxTtl=${props.maxTtl}`);
+  if (ttl === undefined || maxTtl === undefined) return { ok: false, bad };
+  return {
+    ok: true,
+    body: { mint_user: props.mintUser, ttl: String(ttl), max_ttl: String(maxTtl) },
+  };
+};
+
+/**
+ * ⚠️ An unparseable declaration never equals anything, so it surfaces as an update that will
+ *   never settle rather than as a false noop. reconcile turns that loop into one named error;
+ *   see the `writeBody` refusal there.
+ */
+const sameTtl = (want: string, have: string) => {
+  const wantSeconds = parseDuration(want);
+  const haveSeconds = ttlSeconds(have);
+  return wantSeconds !== undefined && wantSeconds === haveSeconds;
+};
+
+/** True when the live role already matches the declaration on every field the plugin stores. */
+export const matches = (attributes: BaoProxmoxRoleAttributes, props: BaoProxmoxRoleProps) =>
+  attributes.mintUser === props.mintUser &&
+  sameTtl(props.ttl, attributes.ttl) &&
+  sameTtl(props.maxTtl, attributes.maxTtl);

package/src/openbao/proxmox-role.ts

@@ -0,0 +1,214 @@
+/**
+ * A role on the estate's proxmox secrets plugin — the mapping from one consumer to one PVE
+ * mint user, plus the lease ceilings that consumer's tokens get. METADATA ONLY.
+ *
+ * ★ WHY THIS FAMILY MATTERS MORE THAN IT LOOKS. Declaring these roles is how the estate
+ *   replaces HAND-MADE PERMANENT PVE TOKENS with short-lived minted ones. On TB4, SEVEN tokens
+ *   carry expire=0 and privsep=0 — root@pam!proxbox-sync, mcp@pve!executor,
+ *   monitoring@pve!exporter, sablier@pve!sablier, tofu@pve!ro, tofu@pve!apply and
+ *   vaultmint@pve!engine. Six of those are one Bao.ProxmoxRole plus a scoped PVE user away from
+ *   being a 5-minute lease instead of a forever key.
+ *
+ *   The seventh cannot be. vaultmint@pve!engine is the credential the ENGINE ITSELF
+ *   authenticates with in order to mint anything at all: the thing that issues short-lived
+ *   tokens needs a standing one, and no role can resolve that chicken-and-egg. It stays
+ *   permanent, which makes it the single most valuable token on the cluster and the one whose
+ *   rotation must be a deliberate, hand-run procedure rather than a plan.
+ *
+ *   MEASURED here: `bao read proxmox-tb4/config` returns parent_token_id
+ *   `vaultmint@pve!engine`, parent_secret_set true, parent_secret_tail `…eb01` — the engine's
+ *   own key, present and, by the schema's own "Write-only: never returned by a read", not
+ *   retrievable. The seven-token inventory was handed to this change and NOT re-counted against
+ *   the PVE API in this session.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts for the full reasoning. Every attribute
+ *   here is a mount path, a role name, a PVE username or a TTL. Nothing this resource stores
+ *   would help anyone authenticate to anything.
+ *
+ * ⛔ ISSUANCE IS NOT THIS RESOURCE, AND MUST NEVER BECOME ONE. `<mount>/creds/<name>` returns a
+ *   LIVE PVE TOKEN. Alchemy persists attributes unencrypted (StateEncoding.ts tags Redacted
+ *   values rather than encrypting them) into the `alchemy` Postgres, which pg-backup.sh dumps
+ *   nightly to CT100, from where PBS backs it up. A minted token declared as a resource would
+ *   outlive its own lease in at least four places, none of them OpenBao. This resource declares
+ *   the DOOR; walking through it is a runtime call, not a plan.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a role breaks every consumer that mints from
+ *   it. Opt in with `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import {
+  type BaoProxmoxRoleAttributes,
+  type BaoProxmoxRoleProps,
+  attributesOf,
+  matches,
+  rolePath,
+  writeBody,
+} from './proxmox-role-form.ts';
+
+export type { BaoProxmoxRoleAttributes, BaoProxmoxRoleProps };
+
+export interface BaoProxmoxRole extends Resource<
+  'Bao.ProxmoxRole',
+  BaoProxmoxRoleProps,
+  BaoProxmoxRoleAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoProxmoxRole = Resource<BaoProxmoxRole>('Bao.ProxmoxRole', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * ⚠️ A missing MOUNT and a missing ROLE both read as undefined here, because both answer 404:
+ *   an absent role is a read that found nothing, and a path under no mount is OpenBao's
+ *   unsupported-path error, which is also a 404 (sdk/logical/response_util.go). They are not the
+ *   same failure — one is a typo in `mount`, the other is a role that has yet to be created — so
+ *   reconcile lets OpenBao's own `errors` through on the write rather than inventing a message.
+ *   A bad mount says "no handler for route".
+ */
+const readRole = (props: BaoProxmoxRoleProps) =>
+  Effect.gen(function* () {
+    const live = yield* baoRead(rolePath(props.mount, props.name));
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+export const BaoProxmoxRoleProvider = () =>
+  Provider.effect(
+    BaoProxmoxRole,
+    Effect.succeed(
+      BaoProxmoxRole.Provider.of({
+        /**
+         * ⛔ `bao list <mount>/roles` IS NOT A LIST OF THINGS THIS OWNS. MEASURED today:
+         *   proxmox-tb4/roles answers `provision, read` and proxmox-ops/roles answers `read` —
+         *   four roles created by hand at bringup, none of them declared anywhere yet.
+         *   Returning them would invite Alchemy to adopt, and then delete, roles it never
+         *   created, and deleting a role is how every consumer of it stops being able to mint.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readRole(olds);
+        }),
+
+        /**
+         * ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST. A mint_user edited in the
+         *   OpenBao UI re-scopes every future credential while the digest in Postgres still
+         *   says everything is fine — exactly the drift the hand-written check-* gates exist to
+         *   catch, and exactly what a provider that trusted its own state would walk past.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          const live = yield* readRole(news);
+          if (live === undefined) return { action: 'update' } as const;
+          if (matches(live, news)) return { action: 'noop' } as const;
+          /**
+           * ⛔ NEVER `replace`, NOT EVEN FOR A mint_user CHANGE. A replace deletes the role and
+           *   writes it back; between those steps `<mount>/creds/<name>` 404s, so anything
+           *   minting in that window fails. The end state is byte-identical to the in-place
+           *   write, because the plugin stores name, mint_user, ttl and max_ttl and nothing
+           *   else — there is no immutable identity a recreate could reset. So a replace here
+           *   buys an outage window in exchange for a louder-looking plan. The loudness a
+           *   re-scope deserves comes from reconcile REFUSING it below, which blocks rather
+           *   than destroys.
+           *
+           * ⚠️ CONSEQUENCE FOR THE READER OF A PLAN: a mint_user re-scope shows up here as a
+           *   plain `update`, indistinguishable from a TTL tweak. The refusal lands at DEPLOY,
+           *   not at plan. That is the safe ordering — nothing is written before the refusal —
+           *   but do not read a green plan as evidence that a mint_user change is approved.
+           */
+          return { action: 'update' } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* readRole(news);
+          /**
+           * ⛔ A mint_user CHANGE RE-SCOPES EVERY CREDENTIAL THE ROLE WILL EVER MINT, SILENTLY.
+           *   The minted token inherits that PVE user's standing ACL and nothing else, so
+           *   swapping `hf-read@pve` for `hf-provision@pve` turns a read-only consumer into a
+           *   provisioning one with no other line of the declaration changing. A plan diff of
+           *   one string is not proportionate warning for that, so an existing role refuses the
+           *   move unless the declaration NAMES THE VALUE IT IS REPLACING. Creating a role never
+           *   trips this — there is nothing to re-scope — and the permission expires by itself
+           *   once the change lands, because live then equals the declaration.
+           */
+          if (
+            live !== undefined &&
+            live.mintUser !== news.mintUser &&
+            news.allowMintUserChange !== live.mintUser
+          ) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.ProxmoxRole ${rolePath(news.mount, news.name)}: live mint_user ` +
+                  `${live.mintUser} != declared ${news.mintUser}. Every token this role mints ` +
+                  'inherits the ACL of that PVE user. To re-scope deliberately, declare ' +
+                  `allowMintUserChange: '${live.mintUser}'.`,
+              ),
+            );
+          }
+          if (live === undefined || !matches(live, news)) {
+            const write = writeBody(news);
+            /**
+             * ⛔ AN UNPARSEABLE TTL IS A REFUSAL, NOT A ZERO. parseDuration accepts `3600s`,
+             *   `1h`, `6h`, `1d` and bare `0`, and NOTHING ELSE — a bare `3600` or a compound
+             *   `1h30m` returns undefined. Left alone that never equals the live value, so the
+             *   plan would report an update forever and each deploy would write a zero TTL.
+             *   Die with the offending props named instead.
+             */
+            if (!write.ok) {
+              return yield* Effect.die(
+                new Error(
+                  `Bao.ProxmoxRole ${rolePath(news.mount, news.name)}: unparseable duration ` +
+                    `${write.bad.join(', ')}. Use 30s / 5m / 1h / 1d, or 0.`,
+                ),
+              );
+            }
+            yield* baoWrite('PUT', rolePath(news.mount, news.name), write.body);
+          }
+          const after = yield* readRole(news);
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.ProxmoxRole ${rolePath(news.mount, news.name)}: write returned no error ` +
+                  'but the role is still absent.',
+              ),
+            );
+          }
+          /**
+           * ⚠️ A GREEN RECONCILE DOES NOT MEAN THE ROLE CAN MINT. The engine never grants ACLs
+           *   — it borrows the mint user's — so declaring `mint_user: hf-read@pve` neither
+           *   creates that PVE user nor gives it a single permission. If the user does not
+           *   exist, or exists with no ACL, the role writes and reads back perfectly and the
+           *   failure surfaces at `creds/<name>` time, in whatever consumer is unlucky. Verify
+           *   the PVE side out-of-band; this resource cannot and does not.
+           */
+          return after;
+        }),
+
+        /**
+         * ⛔ DELETING A ROLE DOES NOT REVOKE THE TOKENS IT ALREADY MINTED — it only stops the
+         *   next mint. Outstanding leases run to their own expiry against the PVE user's ACL.
+         *   So this is an availability change for every consumer of `creds/<name>` and NOT a
+         *   containment action: to contain a leaked credential, revoke the lease (which deletes
+         *   the PVE token) or delete the token in PVE. Deleting the role only hides the door it
+         *   came through. REASONED from Vault lease semantics; not exercised here.
+         *
+         * ⚠️ IDEMPOTENT AS ALCHEMY REQUIRES — already gone is success. It used to get that by
+         *   going through `baoReadText`, which discarded the exit code entirely, so a REFUSED
+         *   delete was reported as a successful one and the resource left Alchemy's state while
+         *   the role stayed live. `baoDelete` keeps the idempotence — a 404 is success — and
+         *   fails on everything else, 403 and 503 included.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* baoDelete(rolePath(output.mount, output.name));
+          return undefined;
+        }),
+      }),
+    ),
+  );