@homeflare/alchemy 0.1.0

package/src/proxmox/credentials.test.ts

@@ -0,0 +1,144 @@
+/**
+ * `mint` against a fake OpenBao on Bun.serve — lease parsing, the headers, agent mode, the
+ * failures that must never become a credential, and the unix-socket path.
+ *
+ * ⛔ NO REAL VAULT AND NO REAL ENVIRONMENT. Every call passes an explicit environment, so a
+ *   BAO_ADDR or BAO_TOKEN in the shell running the tests is never read.
+ */
+import assert from 'node:assert/strict';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { type BaoEnvironment, type PveTarget, mint } from './credentials.ts';
+
+/**
+ * ⚠️ THIS PACKAGE'S tsconfig CARRIES NO BUN TYPES, and its package.json is out of bounds for this
+ *   change, so the one Bun API the fake needs is typed here, minimally. The tests run under
+ *   `bun test`, where `Bun.serve` exists.
+ */
+type ServeOptions = { fetch(request: Request): Promise<Response> } & (
+  | { hostname: string; port: number }
+  | { unix: string }
+);
+const { Bun } = globalThis as unknown as {
+  Bun: { serve(options: ServeOptions): { url: URL; stop(closeActive: boolean): void } };
+};
+
+const TOKEN = 'hvs.FAKE-sentinel-never-a-real-token';
+const SECRET = 'fake-pve-secret-0000';
+const TB4: PveTarget = {
+  members: ['pve.example'],
+  mount: 'proxmox-tb4',
+  scheme: 'pve',
+};
+
+type Seen = { path: string; headers: Headers };
+type Reply = { status: number; json: unknown };
+
+const withFake = async (
+  reply: Reply,
+  body: (address: string, seen: Seen[]) => Promise<void>,
+  unix?: string,
+) => {
+  const seen: Seen[] = [];
+  const fetch = async (request: Request) => {
+    seen.push({ headers: request.headers, path: new URL(request.url).pathname });
+    return Response.json(reply.json, { status: reply.status });
+  };
+  const server = Bun.serve(
+    unix === undefined ? { fetch, hostname: '127.0.0.1', port: 0 } : { fetch, unix },
+  );
+  try {
+    await body(unix === undefined ? server.url.origin : `unix://${unix}`, seen);
+  } finally {
+    server.stop(true);
+  }
+};
+
+const minted = (env: BaoEnvironment) =>
+  Effect.runPromise(mint(TB4, 'read', env).pipe(Effect.provide(FetchHttpClient.layer)));
+const refused = (env: BaoEnvironment) =>
+  Effect.runPromise(
+    mint(TB4, 'read', env).pipe(Effect.flip, Effect.provide(FetchHttpClient.layer)),
+  );
+
+const CREDENTIAL = {
+  json: { data: { secret: SECRET, token_id: 'hf-read@pve!hf-read-1' }, lease_duration: 3600 },
+  status: 200,
+};
+
+describe('mint', () => {
+  it('parses the lease and sends the token, the namespace and X-Vault-Request', async () => {
+    await withFake(CREDENTIAL, async (address, seen) => {
+      const env = { BAO_ADDR: address, BAO_NAMESPACE: 'homeflare', BAO_TOKEN: TOKEN };
+      assert.deepEqual(await minted(env), {
+        leaseSeconds: 3600,
+        secret: SECRET,
+        tokenId: 'hf-read@pve!hf-read-1',
+      });
+      assert.equal(seen[0]?.path, '/v1/proxmox-tb4/creds/read');
+      assert.equal(seen[0]?.headers.get('x-vault-token'), TOKEN);
+      assert.equal(seen[0]?.headers.get('x-vault-namespace'), 'homeflare');
+      assert.equal(seen[0]?.headers.get('x-vault-request'), 'true');
+    });
+  });
+
+  // ⛔ An unknown lifetime is 0, and lease-cache.ts never keeps a 0-second lease.
+  it('reads a missing lease_duration as 0', async () => {
+    const reply = { json: { data: { secret: SECRET, token_id: 'hf-read@pve!x' } }, status: 200 };
+    await withFake(reply, async (address) => {
+      assert.equal((await minted({ BAO_ADDR: address, BAO_TOKEN: TOKEN })).leaseSeconds, 0);
+    });
+  });
+
+  // ★ AGENT MODE: no BAO_TOKEN, no token header — the listener supplies its auto-auth token.
+  it('sends no token header when BAO_TOKEN is unset', async () => {
+    await withFake(CREDENTIAL, async (address, seen) => {
+      await minted({ BAO_ADDR: address });
+      assert.equal(seen[0]?.headers.has('x-vault-token'), false);
+    });
+  });
+
+  it('fails 403, 404 and 503 with OpenBao errors, never the token', async () => {
+    for (const status of [403, 404, 503]) {
+      await withFake(
+        { json: { errors: [`status ${String(status)}`] }, status },
+        async (address) => {
+          const error = await refused({ BAO_ADDR: address, BAO_TOKEN: TOKEN });
+          assert.ok(error instanceof Error);
+          assert.match(
+            error.message,
+            new RegExp(`-> ${String(status)}: status ${String(status)}$`),
+          );
+          assert.ok(!error.message.includes(TOKEN));
+        },
+      );
+    }
+  });
+
+  it('refuses a 200 with no token_id, without quoting the secret', async () => {
+    await withFake({ json: { data: { secret: SECRET } }, status: 200 }, async (address) => {
+      const error = await refused({ BAO_ADDR: address, BAO_TOKEN: TOKEN });
+      assert.ok(error instanceof Error);
+      assert.match(error.message, /returned no token_id\/secret/);
+      assert.ok(!error.message.includes(SECRET));
+    });
+  });
+
+  it('mints over a unix socket', async () => {
+    const socket = join(tmpdir(), `fake-bao-mint-${String(process.pid)}.sock`);
+    rmSync(socket, { force: true });
+    await withFake(
+      CREDENTIAL,
+      async (address, seen) => {
+        assert.equal((await minted({ BAO_ADDR: address })).leaseSeconds, 3600);
+        assert.equal(seen[0]?.path, '/v1/proxmox-tb4/creds/read');
+      },
+      socket,
+    );
+    rmSync(socket, { force: true });
+  });
+});

package/src/proxmox/credentials.ts

@@ -0,0 +1,254 @@
+/**
+ * The PVE credential a reconcile runs with: minted from OpenBao, alive for five minutes.
+ *
+ * ⛔ THERE IS NO STATIC WRITE TOKEN IN THIS ESTATE, AND THAT IS DELIBERATE. Every PVE token stored
+ *   in `kv/infra/proxmox/*` is read-only — PVEAuditor on media/ops/tb4, Audit on pbs, all as
+ *   `monitoring@pve`. The MCP proxmox client says why in its own header: the auditor token bounds
+ *   what a BUG can do, independently of what the code bounds. Adding a long-lived write token to
+ *   that shelf would delete the outer lock for every reader of the shelf, not just for this
+ *   provider.
+ *
+ * ★ SO WRITES COME FROM A DYNAMIC MOUNT INSTEAD, which the estate already built: `proxmox-tb4/`
+ *   exposes two roles — `read` (ttl 3600s) and `provision` (ttl 300s, max 1800s, NOT renewable).
+ *   A mint returns a PVE API token of its own, `hf-provision@pve!hf-provision-…-<timestamp>-<id>`,
+ *   which expires on its own whether or not anything cleans up. Same shape as
+ *   `cloudflare-<account>-<surface>/creds/<role>`, same reason.
+ *   ⚠️ THAT PATH IS WRITTEN WITH `<surface>` RATHER THAN A GLOB ON PURPOSE: a `*` followed by
+ *     a slash CLOSES THIS BLOCK COMMENT, and everything below it then parses as code. It cost
+ *     six TS1005/TS1443 errors pointing at innocent lines twenty rows further down.
+ *
+ * ⚠️ FIVE MINUTES IS THE DESIGN, NOT AN OBSTACLE. A reconcile that cannot finish inside the lease
+ *   should mint again rather than ask for a longer one: the short lease is what makes a leaked
+ *   token uninteresting. `provision` is explicitly non-renewable, so there is no renew path to
+ *   reach for.
+ *
+ * ⛔ THE SECRET NEVER TOUCHES DISK, A LOG, OR ALCHEMY STATE. Alchemy persists resource attributes
+ *   WITHOUT encryption — StateEncoding.ts writes `Redacted` as `{"@redacted": <plaintext>}` — and
+ *   this estate's state store is the `alchemy` Postgres, which pg-backup.sh dumps nightly. A PVE
+ *   secret that reached an attribute would outlive its 300s lease by months, in four places.
+ *   Nothing here returns it to a resource; it is used to build a header and then dropped.
+ */
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import * as Headers from 'effect/unstable/http/Headers';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+
+/**
+ * ★ NO SESSION, ON PURPOSE, AND THIS IS WHAT UNBLOCKED `wip/bao-policy`.
+ *   `CommandExecutor.run` requires a `ScopedPlanStatusSession`, and Alchemy gives one to
+ *   `reconcile` and `delete` but NOT to `read` or `diff` — so a provider built on `run` can only
+ *   ever write. Alchemy's OWN Docker provider does not use `CommandExecutor` for this at all: it
+ *   takes `ChildProcessSpawner` and pipes `ChildProcess.make(...)` through `spawner.spawn`, which
+ *   needs a `Scope` and nothing else (Docker.ts:476-553). That was the pattern here until
+ *   2026-09-14, when `mint` moved to `HttpClient` — which needs no session either, so `mint` is
+ *   still callable from all four operations.
+ *
+ * ⛔ DO NOT SATISFY THE OLD SIGNATURE BY FAKING A SESSION. A session carries plan status Alchemy
+ *   uses to report progress; inventing one would make read and diff report work they are not doing.
+ */
+/** Which role a call needs. `read` for read/diff, `provision` for reconcile/delete. */
+export type PveRole = 'read' | 'provision';
+
+/**
+ * Where credentials come from, and which cluster they are for.
+ *
+ * ⚠️ A PARAMETER, NOT A CONSTANT, SO THIS PACKAGE CAN LEAVE THE ESTATE. Everything
+ *   HomeFlare-specific — the mount name, the API host — belongs in the stack that declares
+ *   resources, not in the provider. Anyone with an OpenBao mount that vends Proxmox API tokens can
+ *   use this file unchanged; that is the whole difference between a provider and a script.
+ */
+export type PveTarget = {
+  /** OpenBao mount that vends API tokens for this host, e.g. `proxmox-tb4`. */
+  readonly mount: string;
+  /**
+   * mgmt hostnames for cluster members, e.g. `n2.mgmt.example.com`. Any member's :8006 API
+   * manages the whole cluster; `client.ts` failovers across them.
+   */
+  readonly members: readonly string[];
+  /**
+   * Which product answers at `api`. Defaults to `pve`.
+   *
+   * ★ PBS IS THE SAME CLIENT WITH A DIFFERENT AUTHORIZATION HEADER, AND THAT IS WHY THERE IS NO
+   *   SECOND CLIENT HERE. Proxmox Backup Server speaks the same `/api2/json` paths, wraps every
+   *   answer in the same `{"data": …}` envelope, and its OpenBao mount vends the same
+   *   `{token_id, secret}` shape — so `mint`, `pve()` and `pveOperations` all work against it
+   *   unchanged. The ONE difference is the header scheme: PVE spells it
+   *   `PVEAPIToken=<id>=<secret>` and PBS spells it `PBSAPIToken=<id>:<secret>` — a different
+   *   prefix AND a different separator.
+   *
+   * ⛔ IT IS REQUIRED, NOT OPTIONAL, AND THAT IS THE WHOLE TYPE-SAFETY ARGUMENT. A PBS target and
+   *   a PVE target are the same two strings, so with an OPTIONAL discriminant TypeScript's
+   *   structural typing would accept a PBS host wherever a PVE one belongs — and `pve()` would
+   *   then build `PVEAPIToken=<id>=<secret>` against a server wanting
+   *   `PBSAPIToken=<id>:<secret>`. Every call 401s, `pveOperations.read` folds that into "absent",
+   *   the plan says CREATE for an object that is plainly there, the POST is refused, and not one
+   *   symptom points at the header. Required, the mistake is a compile error instead.
+   *
+   * ⚠️ REASONED FROM PBS'S DOCUMENTED SCHEME, NOT MEASURED. The estate has no PBS credential yet
+   *   (there is no PBS mount in OpenBao), and an unauthenticated probe cannot tell the schemes
+   *   apart — `https://pbs.example.com:8007/api2/json/nodes` answers 401 to a missing header, a
+   *   PVE-shaped one and a PBS-shaped one alike. The first real token will confirm or correct it,
+   *   and a wrong guess fails closed with a 401 rather than doing something odd.
+   */
+  readonly scheme: 'pve';
+};
+
+/** The same client against a Proxmox Backup Server. See the ⛔ on `scheme` above. */
+export type PbsTarget = {
+  readonly mount: string;
+  readonly api: string;
+  readonly scheme: 'pbs';
+};
+
+/** Either product. What `pve()` and `pveOperations` accept; what a RESOURCE accepts is narrower. */
+export type ApiTarget = PbsTarget | PveTarget;
+
+/**
+ * What a mint returns.
+ *
+ * ⚠️ `secret` IS PRESENT AND MUST NOT BE PERSISTED. It is typed as a plain string rather than
+ *   `Redacted` on purpose: Alchemy's Redacted is a STATE-ENCODING marker, not encryption, so
+ *   wrapping it would imply a protection that does not exist. The protection here is that this
+ *   value never leaves the function that builds the Authorization header.
+ */
+export type PveCredential = {
+  /** `hf-provision@pve!hf-provision-…` — an identifier, safe to log. */
+  readonly tokenId: string;
+  /** ⛔ NEVER LOG, NEVER PERSIST, NEVER RETURN FROM A RESOURCE. */
+  readonly secret: string;
+  /** Seconds the lease was granted for, as reported by OpenBao. */
+  readonly leaseSeconds: number;
+};
+
+/** The environment `mint` resolves OpenBao from — `process.env` unless a test passes its own. */
+export type BaoEnvironment = Readonly<Record<string, string | undefined>>;
+
+/** openbao v2.6.2 api/env.go:22-34 — a present BAO_* wins, even empty; else its VAULT_* twin. */
+const baoVariable = (env: BaoEnvironment, name: string) =>
+  env[`BAO_${name}`] ?? env[`VAULT_${name}`] ?? '';
+
+/**
+ * Mint one credential for `role`: `GET /v1/<mount>/creds/<role>` on OpenBao's HTTP API.
+ *
+ * 🔴 IT SHELLED OUT TO `bao read -format=json` UNTIL 2026-09-14. The case for the CLI was that one
+ *   client could not disagree with `bao kv get` about what this machine may do. house/openbao then
+ *   learned twice what deciding by stderr costs — every failure read as absent, and two commands
+ *   said "absent" in different words — so this reads STATUS CODES: 2xx is a credential, and 403
+ *   (denied), 404 (no such role or mount — a mint has no "absent"), 503 (sealed) all fail.
+ * ★ THE ENVIRONMENT CONTRACT IS STILL THE CLI's, READ THE CLI's WAY, which keeps the case above
+ *   true (openbao v2.6.2 api/client.go:34-66, 370, 503-507, 761-762, 776-785): BAO_AGENT_ADDR over
+ *   BAO_ADDR over https://127.0.0.1:8200; BAO_NAMESPACE as X-Vault-Namespace; BAO_TOKEN as
+ *   X-Vault-Token; X-Vault-Request always. house/openbao/src/bao-address.ts has the long form.
+ * ★ AGENT MODE IS NO BAO_TOKEN AND NO TOKEN HEADER. An Agent or Proxy listener with
+ *   `api_proxy { use_auto_auth_token = true }` (or the older `cache { … }`) substitutes its
+ *   auto-auth token exactly when a request carries none — command/agentproxyshared/cache/handler.go
+ *   :29-38, command/agent.go:517-541, command/agent/config/config.go:288-292, and
+ *   website/content/docs/agent-and-proxy/agent/apiproxy.mdx:57-62. The CLI's token-file fallback
+ *   is deliberately not read. ⚠️ So an unset BAO_TOKEN aimed at a SERVER rather than an agent is a
+ *   403, which reads like a missing grant rather than a missing variable.
+ * ★ UNIX SOCKETS: `unix:///path` is plain HTTP to `localhost` over that socket, as the CLI does it
+ *   (api/client.go:654-667). Bun's fetch takes a `unix` option; `FetchHttpClient.RequestInit` is
+ *   Effect's documented way to pass fetch options, read from the calling fiber (effect
+ *   FetchHttpClient.ts:59-72). Off Bun it REFUSES, rather than reach http://localhost:80.
+ */
+export const mint = (target: ApiTarget, role: PveRole, env: BaoEnvironment = process.env) =>
+  Effect.gen(function* () {
+    const path = `${target.mount}/creds/${role}`;
+    // ⛔ METHOD, PATH AND OpenBao's `errors` ONLY — never a header (the token), never a success
+    //   body (the credential is IN it, so echoing it would print the secret into a log).
+    const refuse = (status: number, detail: string) =>
+      new Error(`OpenBao GET /v1/${path} -> ${status === 0 ? 'no response' : status}: ${detail}`);
+    const address =
+      baoVariable(env, 'AGENT_ADDR') || baoVariable(env, 'ADDR') || 'https://127.0.0.1:8200';
+    const socket = address.startsWith('unix://') ? address.slice('unix://'.length) : undefined;
+    const base = socket === undefined ? address.replace(/\/+$/, '') : 'http://localhost';
+    const headers: Record<string, string> = { 'X-Vault-Request': 'true' };
+    const namespace = baoVariable(env, 'NAMESPACE');
+    if (namespace !== '') headers['X-Vault-Namespace'] = namespace;
+    const token = baoVariable(env, 'TOKEN');
+    if (token !== '') headers['X-Vault-Token'] = token;
+    if (socket !== undefined && !('Bun' in globalThis)) {
+      return yield* Effect.fail(refuse(0, 'a unix:// address needs Bun fetch; this is not Bun'));
+    }
+
+    const client = yield* HttpClient.HttpClient;
+    // ⛔ Effect records request headers on the client span, and its default redaction list does
+    //   not name x-vault-token (effect Headers.ts:753-762). It is added for this call.
+    const redacted = yield* Headers.CurrentRedactedNames;
+    const defaults = Option.getOrElse(
+      yield* Effect.serviceOption(FetchHttpClient.RequestInit),
+      () => ({}),
+    );
+    const request = HttpClientRequest.get(`${base}/v1/${path}`).pipe(
+      HttpClientRequest.setHeaders(headers),
+    );
+    const exchange = client.execute(request).pipe(
+      Effect.flatMap((response) =>
+        Effect.map(response.text, (text) => ({ status: response.status, text })),
+      ),
+      // ⚠️ The CLI's default client timeout (api/client.go:324) — a hung agent must not hang a plan.
+      Effect.timeout('60 seconds'),
+      Effect.provideService(Headers.CurrentRedactedNames, [...redacted, 'x-vault-token']),
+    );
+    // ⚠️ `| undefined` under exactOptionalPropertyTypes: `socket` is narrowed to a string
+    //   only on the branch below, so the object literal genuinely carries
+    //   `unix: string | undefined` and the type must say so. The alternative — building
+    //   the key conditionally — hides that this request is the unix-socket path.
+    const init: RequestInit & { unix?: string | undefined } = { ...defaults, unix: socket };
+    const { status, text } = yield* (
+      socket === undefined
+        ? exchange
+        : Effect.provideService(exchange, FetchHttpClient.RequestInit, init)
+    ).pipe(
+      // ⛔ `.message` only — the error object holds the request, and the request holds the token.
+      Effect.mapError((cause) => refuse(0, cause.message)),
+    );
+
+    let parsed:
+      | {
+          lease_duration?: unknown;
+          data?: { token_id?: unknown; secret?: unknown };
+          errors?: unknown;
+        }
+      | undefined;
+    try {
+      parsed = JSON.parse(text) as typeof parsed;
+    } catch {
+      parsed = undefined;
+    }
+    if (status < 200 || status >= 300) {
+      const errors = parsed?.errors;
+      const detail = Array.isArray(errors)
+        ? errors.map(String).join('; ')
+        : 'not an OpenBao error body';
+      return yield* Effect.fail(refuse(status, detail || '(no errors given)'));
+    }
+    const tokenId = parsed?.data?.token_id;
+    const secret = parsed?.data?.secret;
+    if (typeof tokenId !== 'string' || typeof secret !== 'string') {
+      // ⛔ REFUSE RATHER THAN RETURN A HALF CREDENTIAL, and again WITHOUT quoting the body.
+      return yield* Effect.fail(
+        new Error(
+          `${target.mount}/creds/${role} returned no token_id/secret. Either this approle lacks ` +
+            `the grant, or the mount is not ${target.mount}. Say which mount and role you needed ` +
+            `than falling back to a stored credential -- every stored PVE token is read-only.`,
+        ),
+      );
+    }
+    const lease = parsed?.lease_duration;
+    const leaseSeconds = typeof lease === 'number' ? lease : 0;
+    return { leaseSeconds, secret, tokenId } satisfies PveCredential;
+  });
+
+/**
+ * The header PVE wants. `PVEAPIToken=<tokenid>=<secret>`.
+ *
+ * ⚠️ THE SEPARATOR IS `=`, NOT `:`. Proxmox rejects the colon form with a 401 that says only
+ *   "authentication failure", which reads as a bad credential rather than as a malformed header.
+ */
+export const authorization = (credential: PveCredential, target: ApiTarget): string =>
+  target.scheme === 'pbs'
+    ? `PBSAPIToken=${credential.tokenId}:${credential.secret}`
+    : `PVEAPIToken=${credential.tokenId}=${credential.secret}`;

package/src/proxmox/firewall-alias-form.ts

@@ -0,0 +1,112 @@
+/**
+ * A firewall alias on the wire: what PVE stores, and what it quietly changes on the way.
+ *
+ * ★ SPLIT OUT OF firewall-alias.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is the
+ *   same one metric-server.ts and node-network.ts cut: this file answers "what does the cluster do
+ *   to a value", firewall-alias.ts answers "what is an alias and when has it changed". Nothing here
+ *   reads the cluster and nothing here decides a diff.
+ *
+ * ⛔ THE PUT IS A FULL REPLACE, WHICH IS THE EXACT INVERSE OF metric-server.ts — DO NOT COPY THAT
+ *   FILE'S RULE OVER HERE. A metric server is a SectionConfig section and a PUT merges into it, so
+ *   an omitted field SURVIVES and a managed optional needs a matching `delete=` or it can never be
+ *   cleared. An alias is not: `update_alias` builds `$data = { name, cidr }`, adds `comment` only
+ *   when it is truthy, and assigns the whole hash over the old one. So an omitted `comment` is
+ *   CLEARED here, there is no `delete` parameter on this endpoint at all, and sending
+ *   `comment=''` would be a second spelling of the same thing.
+ *
+ * ⚠️ THE SAME REPLACE MAKES `cidr` REQUIRED ON EVERY UPDATE. PVE's PUT schema does not mark it
+ *   optional, and the Perl would build an entry with an undefined cidr if it could — so `body`
+ *   below sends it on update as well as on create, rather than treating it as "only send what
+ *   changed".
+ */
+import type { FirewallAliasProps } from './firewall-alias.ts';
+import { text } from './values.ts';
+
+/**
+ * The alias key, as PVE computes it.
+ *
+ * ⚠️ EVERY ENTRY POINT LOWERS THE NAME AND NOTHING LOWERS THE STORED ONE: create, read, update and
+ *   delete all start `my $name = lc($param->{name})`, while the entry keeps `name => $param->{name}`
+ *   as written. So this is identity, and the stored spelling is decoration. Used by `diff` to tell
+ *   an edit from a different alias — a comparison of the raw names would call a re-capitalisation a
+ *   replace, and delete an alias to put back the same one.
+ */
+export const fold = (name: string) => name.trim().toLowerCase();
+
+/**
+ * A CIDR reduced to the one form PVE will hand back.
+ *
+ * ⛔ MEASURED by running the cluster's own `PVE::Firewall::parse_alias` on n2 (pve-manager 9.2.11,
+ *   2026-09-13) — a pure function over a string, no config read and none written:
+ *     `10.1.1.5/32`     -> `10.1.1.5`        a /32 host suffix is STRIPPED
+ *     `2001:0DB8::1/128`-> `2001:0DB8::1`    a /128 is stripped, and the case is NOT folded
+ *     `2001:db8::/32`   -> `2001:db8::/32`   a /32 on IPv6 is a real prefix and SURVIVES
+ *   `parse_ip_or_cidr` is where it happens: `s|/32$||` under the IPv4 branch and `s|/128$||` under
+ *   the IPv6 one. Unmatched, a declared `10.1.1.5/32` reads back as `10.1.1.5` and reports an
+ *   update on every plan for the rest of time, each deploy writing back a value it already holds.
+ *
+ * ⛔ SO THE STRIP IS VERSION-AWARE, AND AN UNCONDITIONAL `/32` WOULD CORRUPT THE COMPARISON. A
+ *   colon cannot appear in an IPv4 address and must appear in an IPv6 one, which is the whole
+ *   discriminator PVE's own two regexes come down to here. Reading `2001:db8::/32` as
+ *   `2001:db8::` would make a /32 prefix compare equal to a single host.
+ *
+ * ⚠️ AND IT STOPS THERE, ON PURPOSE. PVE does not lowercase, zero-pad or compress an IPv6 literal,
+ *   so neither may this: it stores what it was handed and gives that back, which means any spelling
+ *   is stable once written. Canonicalising further would make `matches` call two DIFFERENT stored
+ *   strings equal and report noop over real drift — the same lie as missing a rewrite, pointed the
+ *   other way.
+ */
+export const cidr = (value: unknown) => {
+  const raw = text(value).trim();
+  const host = raw.includes(':') ? '/128' : '/32';
+  return raw.endsWith(host) ? raw.slice(0, -host.length) : raw;
+};
+
+/**
+ * A comment reduced to the one form PVE will hand back.
+ *
+ * ⚠️ AN ALIAS COMMENT IS A TRAILING `#` ON ITS LINE IN `cluster.fw`, AND THE ROUND TRIP TRIMS IT.
+ *   MEASURED with the same parser run: `Cmt 10.2.0.0/16 #   spaced comment   ` comes back as
+ *   `spaced comment`. `parse_alias` strips the surrounding whitespace (`s/\s*#\s*(.*?)\s*$//`) and
+ *   `format_aliases` refuses to write a blank one at all, so an untrimmed declaration would diff
+ *   against its own stored form forever.
+ *
+ * ⛔ A COMMENT OF EXACTLY `0` CANNOT BE STORED, AND READING THAT AS DRIFT WOULD LOOP FOREVER.
+ *   MEASURED: `Zero 10.3.0.0/16 # 0` parses to an entry with NO comment key. Both the create and
+ *   the update guard with Perl's `if $param->{comment}`, and `'0'` is false in Perl — so the string
+ *   is dropped before it ever reaches the file, on write as well as on read. Folded to `''` here
+ *   because that is what the cluster will do with it: a declaration asking for something PVE will
+ *   not keep should plan as noop and be documented, not diff on every plan and be unfixable by the
+ *   very PUT the diff asks for.
+ *
+ * ⚠️ A LINE FEED IS A 400, NOT A TRUNCATION. `pve_fw_verify_comment_spec` dies with "comment must
+ *   not contain a line feed", which is the honest answer and is left to PVE rather than silently
+ *   flattened here — flattening would store something the declaration did not say.
+ */
+export const comment = (value: unknown) => {
+  const trimmed = text(value).trim();
+  return trimmed === '0' ? '' : trimmed;
+};
+
+/**
+ * Everything mutable, in the form PVE wants. Create adds `name`; update sends exactly this.
+ *
+ * ⚠️ `name` IS NOT SENT ON UPDATE BECAUSE IT IS ALREADY THE LAST SEGMENT OF THE PATH BEING PUT TO,
+ *   and a second copy can only disagree with it — the same reasoning metric-server.ts gives for
+ *   omitting its `id`. PVE takes the path segment as `$param->{name}` and writes it back as the
+ *   stored spelling, so a PUT for any other reason also re-capitalises the entry to match the
+ *   declaration. That is a side effect worth knowing about and not worth causing on its own.
+ *
+ * ⚠️ THE NORMALISED CIDR IS WHAT GETS WRITTEN, NOT THE DECLARED SPELLING. PVE stores the parameter
+ *   verbatim into `cluster.fw` and only strips the host suffix when it reads the file back, so
+ *   sending `10.1.1.5` rather than `10.1.1.5/32` leaves the file saying exactly what the next read
+ *   will answer. Both settle; this one leaves no pair of values that merely happen to agree.
+ *
+ * ⚠️ `rename` IS DELIBERATELY ABSENT — see the ⚠️ on renames in firewall-alias.ts. A `rename` in
+ *   this form would be a second, invisible identity for the object, set from a field the resource
+ *   does not have.
+ */
+export const body = (props: FirewallAliasProps): Record<string, string> => {
+  const note = comment(props.comment);
+  return { cidr: cidr(props.cidr), ...(note === '' ? {} : { comment: note }) };
+};