@homeflare/alchemy 0.1.0

package/dist/proxmox/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * One authenticated call to the Proxmox VE API.
+ *
+ * ★ PLAIN `fetch`, NO TLS ESCAPE HATCH, AND THAT IS A MEASURED CHOICE RATHER THAN AN OMISSION.
+ *   Proxmox is usually met with `curl -k` because a fresh install serves its own self-signed
+ *   certificate — I reached for `-k` myself before checking. This cluster serves a real Let's
+ *   Encrypt certificate (`CN=cluster-tb4.example.com`), and strict TLS answers 401, i.e. the
+ *   handshake succeeds and only the credential is missing. So there is no `rejectUnauthorized`
+ *   option here to be left switched on by accident in somebody else's estate.
+ *
+ * ⚠️ EVERY PVE ANSWER IS WRAPPED IN `{"data": ...}`, errors included — a failed call can still be
+ *   HTTP 200 with `{"data": null}`. Unwrapping is not cosmetic; a caller that reads the envelope
+ *   as the payload sees `undefined` and calls it "absent".
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { type ApiTarget, type PveCredential, type PveRole, type PveTarget } from './credentials.ts';
+export declare class PveError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(status: number, method: string, path: string, detail: string);
+}
+/**
+ * A form body, where a value may be a LIST.
+ *
+ * ⛔ PVE AND PBS SPELL A MULTI-VALUED FIELD DIFFERENTLY, AND THE LIST FORM IS FOR PBS. PBS is Rust:
+ *   its schemas use `type: array` — `delete` on every update endpoint is one — and its urlencoded
+ *   decoder builds that array from REPEATED KEYS (`delete=a&delete=b`). PVE's Perl takes a comma
+ *   string for the same idea, which is what `withClears` in values.ts produces, and for the one
+ *   PVE field that genuinely needs repetition it wants a NUL-joined value instead (see
+ *   notification-target.ts). So: PVE callers pass strings and are unaffected; a PBS caller that
+ *   needs an array passes one and gets repeated keys rather than reaching for PVE's encoding.
+ */
+export type PveForm = Record<string, readonly string[] | string>;
+/** A call that already holds a credential. Used when one mint serves several calls. */
+export declare const pveWith: <T>(target: ApiTarget, credential: PveCredential, method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, form?: PveForm) => Effect.Effect<T | undefined, PveError, HttpClient.HttpClient>;
+/**
+ * Like `pveWith`, but returns the full JSON body — for endpoints whose answer lives beside `data`.
+ *
+ * ⚠️ `network-apply-read.ts` is the caller today; the local fetch there should fold into this once
+ *   the envelope shape is stable across both paths.
+ */
+export declare const pveEnvelopeWith: (target: PveTarget, credential: PveCredential, method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string) => Effect.Effect<Record<string, unknown>, PveError, HttpClient.HttpClient>;
+/**
+ * Make one call on a credential for `role`, REUSING a still-valid lease rather than minting one.
+ *
+ * 🔴 IT USED TO MINT PER CALL, AND AT 98 RESOURCES THAT STOPPED BEING FREE. One plan plus deploy
+ *   of the TB4 stack left 760 token entries in `/etc/pve/user.cfg` — read, diff, reconcile and the
+ *   read-back each minted their own, and `/etc/pve` is a replicated cluster filesystem every node
+ *   has to agree on. src/lease-cache.ts carries the measurement and the safety argument.
+ *
+ * ⚠️ `pveWith` IS STILL THERE AND STILL TAKES AN EXPLICIT CREDENTIAL. network-apply.ts needs ONE
+ *   identity across its apply and its task poll — PVE only skips the task-status privilege check
+ *   for the task's OWNER — and it threads a lease through by hand for that. Caching makes that
+ *   property easier to hold, never weaker, but the explicit path stays because that caller is
+ *   reasoning about identity rather than about cost.
+ *
+ * ★ TASK POLL ON A DIFFERENT MEMBER THAN THE APPLY STILL HOLDS: the owner is the token id, not the
+ *   node that received the PUT. Any member serves any task path; the privilege skip is keyed on
+ *   whether the caller IS the task's owner.
+ */
+export declare const pve: <T>(target: ApiTarget, role: PveRole, method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, form?: PveForm) => Effect.Effect<T | undefined, Error, HttpClient.HttpClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/proxmox/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/proxmox/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAE9D,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAC;AAI1B,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAHvB,YACW,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EAIf;CACF;AAcD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;AA8FjE,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,CAAC,UACf,SAAS,cACL,aAAa,UACjB,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,QACnC,MAAM,SACL,OAAO,kEAgBZ,CAAC;AAEL;;;;;GAKG;AACH,eAAO,MAAM,eAAe,WAClB,SAAS,cACL,aAAa,UACjB,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,QACnC,MAAM,4EAmBV,CAAC;AAEL;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,UACX,SAAS,QACX,OAAO,UACL,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,QACnC,MAAM,SACL,OAAO,+DAKZ,CAAC"}

package/dist/proxmox/credentials.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 HttpClient from 'effect/unstable/http/HttpClient';
+/**
+ * ★ 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>>;
+/**
+ * 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 declare const mint: (target: ApiTarget, role: PveRole, env?: BaoEnvironment) => Effect.Effect<{
+    leaseSeconds: number;
+    secret: string;
+    tokenId: string;
+}, Error, HttpClient.HttpClient>;
+/**
+ * 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 declare const authorization: (credential: PveCredential, target: ApiTarget) => string;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/proxmox/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/proxmox/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAG9D;;;;;;;;;;;;GAYG;AACH,uFAAuF;AACvF,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;CACxB,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;CACxB,CAAC;AAEF,oGAAoG;AACpG,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAM1E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,WAAY,SAAS,QAAQ,OAAO,QAAO,cAAc;;;;gCAuFtE,CAAC;AAEL;;;;;GAKG;AACH,eAAO,MAAM,aAAa,eAAgB,aAAa,UAAU,SAAS,KAAG,MAGf,CAAC"}

package/dist/proxmox/firewall-alias-form.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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';
+/**
+ * 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 declare const fold: (name: string) => string;
+/**
+ * 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 declare const cidr: (value: unknown) => string;
+/**
+ * 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 declare const comment: (value: unknown) => string;
+/**
+ * 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 declare const body: (props: FirewallAliasProps) => Record<string, string>;
+//# sourceMappingURL=firewall-alias-form.d.ts.map

package/dist/proxmox/firewall-alias-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firewall-alias-form.d.ts","sourceRoot":"","sources":["../../src/proxmox/firewall-alias-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,SAAU,MAAM,WAA8B,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,IAAI,UAAW,OAAO,WAIlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,OAAO,UAAW,OAAO,WAGrC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,IAAI,UAAW,kBAAkB,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAGrE,CAAC"}

package/dist/proxmox/firewall-alias.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `Proxmox.FirewallAlias` — a named network the cluster firewall can be written in terms of.
+ *
+ * ★ WHY THIS FAMILY AND NOT FIREWALL RULES, WHICH IS THE ONE EVERYONE REACHES FOR FIRST. A rule is
+ *   addressed BY POSITION — `/cluster/firewall/rules/{pos}` — so inserting a rule renumbers every
+ *   rule below it. A position-keyed resource therefore RETARGETS ITSELF at somebody else's rule the
+ *   moment anything is inserted above it, and it does so while the plan looks clean: the path still
+ *   resolves, the read still succeeds, the diff is simply computed against the wrong object.
+ *   Aliases, ipsets and security groups are the firewall objects with STABLE IDENTITY — a name, not
+ *   an index — and they are the ones worth declaring. Rules belong in this package only once
+ *   somebody models the whole ordered list as ONE resource, which is a different shape from
+ *   `PveSpec` and should look different.
+ *
+ * ★ AND THE ALIAS IS THE PIECE THAT EARNS THE MOST BY BEING DECLARED. `10.1.0.0/16` spelled into
+ *   nine rules is nine places to edit and one to forget; `HomeLan` spelled into nine rules is one
+ *   place, resolved by PVE at compile time. The alias is the object that has to be right.
+ *
+ * ⛔ PVE REWRITES THE CIDR ON READ, AND THAT IS THE FOREVER-DIFF THIS RESOURCE IS SHAPED AROUND.
+ *   A declared `10.1.1.5/32` reads back as `10.1.1.5`. `cidr()` in `firewall-alias-form.ts` applies
+ *   exactly the cluster's own transformation to BOTH sides and carries the measurements; read that
+ *   comment before touching either side of `matches` below.
+ *
+ * ⛔ `ipversion` IS RETURNED BY THE READ AND REFUSED BY EVERY WRITE. `parse_alias` derives it from
+ *   the address and `read_alias` hands the parsed entry straight back, while POST and PUT declare
+ *   `additionalProperties: 0` with no such parameter — sending it is a 400, not an ignored hint. It
+ *   is REPORTED as an attribute so a plan can say whether an alias is v4 or v6, and kept OUT of
+ *   `matches`, exactly like `pool.members` and `user.tokens`.
+ *
+ * ⚠️ `digest` NEVER REACHES THIS PROVIDER, which is a better answer than keeping it out of
+ *   `matches`. The LIST read runs its entries through `copy_list_with_digest` and stamps one — and
+ *   it changes whenever ANYTHING else in the firewall config changes, so a resource that stored it
+ *   would diff on a rule somebody else edited. The SINGLE-OBJECT read this resource uses returns
+ *   `$aliases->{$name}` raw, with no digest in it at all. None is sent on write either:
+ *   `PVE::Tools::assert_if_modified` skips the comparison when either side is undef, and the API
+ *   handler already holds `lock_clusterfw_conf(10, ...)` for the whole read-modify-write. So
+ *   declining optimistic locking buys last-writer-wins between two concurrent editors, not a torn
+ *   file — and the alternative, storing a cluster-wide digest per alias, buys a permanent diff.
+ *
+ * ⚠️ THE NAME IS CASE-FOLDED FOR IDENTITY AND PRESERVED FOR DISPLAY, which reads as a bug until you
+ *   see both halves. The config is keyed `$aliases->{lc($data->{name})}` while the entry stores the
+ *   name as written, and the item GET lowers its path segment too — so `homelan` and `HomeLan` are
+ *   ONE alias, reachable by either spelling. `name` is therefore reported from the live config and
+ *   kept OUT of `matches`: rewriting an alias to change its capitalisation is a cosmetic write to
+ *   the file every node recompiles its firewall from.
+ *   ⛔ AND TWO DECLARATIONS DIFFERING ONLY IN CASE ARE THE SAME OBJECT, which is the `acl.ts`
+ *     hazard again. Alchemy sees two resource ids, the cluster sees one alias, and deleting either
+ *     takes it away from both.
+ *
+ * ⚠️ A RENAME IS MODELLED AS A REPLACE, NOT AS AN UPDATE, AND THE REJECTED OPTION WAS REAL. PVE's
+ *   PUT does take a `rename` parameter and Alchemy's `reconcile` does receive `olds`, so an
+ *   in-place rename was available. It was rejected because using it means hand-writing `reconcile`
+ *   as well as `diff` and branching on four states — old present or absent, new present or absent —
+ *   each branch a fresh way to write the wrong object, and all of it to buy only the gap between
+ *   the create and the delete. What a rename must NOT be is silent, which is what the factory alone
+ *   would make it: the read at the NEW path answers absent, `diff` says update, reconcile POSTs a
+ *   SECOND alias, and the old one stays in `cluster.fw` with its old CIDR — still resolving in
+ *   every rule that names it, and invisible to every later plan. `diff` below says `replace`.
+ *   ⚠️ CREATE-FIRST, as Alchemy defaults and as `acl.ts` argues: the new alias exists before the
+ *     old one goes, so a rules change can be sequenced between the two generations.
+ *
+ * ⚠️ PRIVILEGES, AND FOR ONCE NOTHING NEEDS WIDENING. MEASURED 2026-09-13 from the cluster's own
+ *   schema and its live ACL: the item GET checks `["perm","/",["Sys.Audit"]]`, POST/PUT/DELETE
+ *   check `["perm","/",["Sys.Modify"]]`, `hf-read@pve` holds `PVEAuditor` at `/` with propagate and
+ *   `hf-provision@pve` holds `LXCProvisioner` at `/` with propagate. Both privileges are already
+ *   held, so `readRole` stays the default `read` lane — unlike storage/sdn-zone/sdn-vnet, whose
+ *   ITEM reads are gated on an allocate privilege the auditor cannot have.
+ *   ⚠️ `Sys.Modify` ON `/` IS STILL A BIG HAMMER — it is the same grant `metric-server.ts` warns
+ *     about, and there is no `/firewall` object to scope a narrower role to.
+ *
+ * ⚠️ DELETION IS FULLY IMPLEMENTED AND THE DEFAULT POLICY IS DELIBERATELY NOT `retain`. The ★ in
+ *   `resource.ts` reserves `retain` for objects whose CONTENTS cannot be rebuilt from a line of
+ *   TypeScript; an alias is a name, a CIDR and a comment, all three of them in the declaration, so
+ *   recreating one is exact and free. The real hazard is referential — PVE checks nothing before
+ *   removing an alias, and a rule naming a removed one fails to compile — and `retain` would not
+ *   fix that, it would only leave an undeclared alias on the cluster forever. Sequence the rules,
+ *   or pipe `RemovalPolicy.retain()` at the declaration site where the reason is visible.
+ *
+ * ⚠️ `local_network` IS THE ONE ALIAS NAME WITH CLUSTER-WIDE MEANING. `compile_ipsets` reads
+ *   `aliases->{local_network}` to decide what the `management` ipset covers, and SYNTHESISES one
+ *   from the node's own subnet when it is missing — in memory, never written back to the file.
+ *   Declaring it is stable, because PVE leaves a present one alone. DELETING it hands that decision
+ *   silently back to autodetection, which is drift no plan will ever show.
+ *
+ * ⚠️ NO SECRET LIVES IN THIS FAMILY, so nothing here has to be typed `never` to keep it out of
+ *   Alchemy's unencrypted state the way `metric-server.ts` does with its `token`. A name, a CIDR and
+ *   a free-text comment are the whole object, and all three are the declaration's own values read
+ *   back — not a credential held by the cluster.
+ *
+ * ⚠️ ACCEPTANCE, STATED HONESTLY: `GET /cluster/firewall/aliases` ANSWERS `[]` ON THIS CLUSTER and
+ *   the cluster firewall is disabled, so there was no live alias to declare and NO create/plan/noop
+ *   round trip was run. What is measured is the published schema, the API module's Perl, and the
+ *   cluster's own `parse_alias` exercised on sample lines. Whoever declares the first alias should
+ *   confirm the SECOND plan says noop before trusting this file.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { type PveRequirements, type WithTarget } from './resource.ts';
+export interface FirewallAliasProps extends WithTarget {
+    /**
+     * PVE's `pve-fw-alias`: a letter, then at least one more of letter/digit/`-`/`_`, to 64 chars.
+     * ⚠️ IDENTITY, CASE-INSENSITIVELY — see the ⚠️ on folding in the header. A two-character minimum
+     *   is real: a one-letter name is refused by the pattern, not silently accepted.
+     */
+    name: string;
+    /**
+     * An IP or a network, e.g. `10.1.0.0/16`, `10.1.1.5`, `2001:db8::/32`.
+     * ⚠️ A `/32` (or `/128`) SUFFIX IS DROPPED BY PVE AND BY `cidr()` ALIKE, so declaring one is
+     *   harmless — it simply is not what comes back. Anything `parse_ip_or_cidr` refuses is a 400.
+     */
+    cidr: string;
+    /**
+     * Free text, stored as a trailing `#` comment on the alias's line in `cluster.fw`.
+     * ⚠️ TRIMMED, AND A LINE FEED IS REFUSED. A comment of exactly `0` cannot be stored at all — the
+     *   ⛔ in `firewall-alias-form.ts` measures why, and why declaring one plans as noop.
+     */
+    comment?: string;
+}
+export interface FirewallAliasAttributes {
+    /** The spelling held in `cluster.fw`, which need not be the declared one. Never compared. */
+    name: string;
+    /** Normalised the way PVE normalises it, so it is comparable with a declaration. */
+    cidr: string;
+    comment: string;
+    /**
+     * 4 or 6, derived by PVE from the address. Reported so a plan can show which stack an alias
+     * covers; never compared, because no write accepts it.
+     */
+    ipversion: number;
+}
+export interface ProxmoxFirewallAlias extends Resource<'Proxmox.FirewallAlias', FirewallAliasProps, FirewallAliasAttributes, never, PveRequirements> {
+}
+export declare const ProxmoxFirewallAlias: import("alchemy").ResourceClass<ProxmoxFirewallAlias>;
+/**
+ * ⛔ ONE HANDLER IS OVERRIDDEN AND THE REST COME FROM THE FACTORY, for the reason `acl.ts` spells
+ *   out at length: the factory answers `replace` only for an object with no update path, and this
+ *   one has a PUT. Left to delegate, a changed `name` would read absent at the new path, plan as an
+ *   update, and quietly leave the old alias behind. Everything else — the empty `list`, the read,
+ *   the read-back-guarded reconcile, the delete — is the factory's, unchanged.
+ */
+export declare const ProxmoxFirewallAliasProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxFirewallAlias>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=firewall-alias.d.ts.map

package/dist/proxmox/firewall-alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firewall-alias.d.ts","sourceRoot":"","sources":["../../src/proxmox/firewall-alias.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAe,MAAM,eAAe,CAAC;AAGnF,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAqB,SAAQ,QAAQ,CACpD,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,eAAO,MAAM,oBAAoB,uDAA0D,CAAC;AAuC5F;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,0IAiBtC,CAAC"}