@homeflare/alchemy 0.1.0

package/src/proxmox/acl.ts

@@ -0,0 +1,267 @@
+/**
+ * `Proxmox.Acl` — one grant: a role bound to a subject at a path. The line that makes a role real.
+ *
+ * ★ USERS, GROUPS, ROLES AND TOKENS ARE ALL INERT UNTIL AN ACL BINDS THEM. A role is a named list
+ *   of privileges that grants nothing by itself; a user can do nothing until
+ *   {path, user|group|token, role} exists. That is what makes those four families worth declaring,
+ *   and why the grants that let OpenBao mint a PVE token today are only clicks somebody made once.
+ *
+ * ⛔ THE ONE FAMILY THAT DOES NOT FIT `pveOperations` AS WRITTEN, AND THE MISFIT IS MEASURED. The
+ *   cluster's own schema — `/pve-docs/api-viewer/apidoc.js`, read unauthenticated 2026-09-13 —
+ *   lists exactly TWO methods on `/access/acl`: GET and PUT. There is no DELETE (it answers
+ *   "Method 'DELETE /access/acl' not implemented") and, less famously, NO POST either. So create
+ *   and update are the SAME call, `PUT /access/acl`, and removal is that PUT with `delete=1` —
+ *   which is why `delete` below does not use `ops.destroy`.
+ *   ⚠️ THE REAL FIX BELONGS IN `resource.ts`: give `PveSpec` a `deleteForm` and the method to go
+ *     with it, and this override disappears. Until then it is local and loud — do not "restore
+ *     symmetry" by pointing `delete` at `ops.destroy`, which reports every removal as a 501 while
+ *     the grant stays exactly where it was.
+ *
+ * ⛔ A SINGLE GRANT HAS NO URL OF ITS OWN. `GET /access/acl` answers ONE FLAT LIST for the whole
+ *   cluster, so identity is the tuple (path, type, ugid, roleid), matched client-side in
+ *   `attributes` below. Two resources declaring the SAME tuple are the SAME grant — Alchemy sees
+ *   two resource ids, not one collision — and deleting either takes the access away from both,
+ *   the same hazard as two guests declaring one vmid.
+ *
+ * ⛔ AND THAT LIST IS FILTERED BY WHO IS ASKING. The schema's own words for GET: "The returned list
+ *   is restricted to objects where you have rights to modify permissions." A credential that can
+ *   read the cluster but not modify permissions is answered `[]` — not a 403, not an error — so
+ *   the mount's `read` role needs permission-modify rights on the declared path exactly as
+ *   `provision` does. Work reported on a grant that is plainly there means that role is too narrow.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { pve } from './client.ts';
+import { type PveRequirements, type WithTarget, pveOperations } from './resource.ts';
+
+/** PVE's three kinds of subject. The read answers this word; the write wants its plural. */
+export type AclSubjectType = 'user' | 'group' | 'token';
+
+export interface AclProps extends WithTarget {
+  /**
+   * The PVE object path the grant is ON — `/`, `/pool/house`, `/vms/101`, `/storage/local-zfs`.
+   * ⚠️ NOT THE API PATH: `spec.path` below is the endpoint (`access/acl`). PVE's API overloads the
+   *   word, so this file does too rather than renaming a field the cluster calls `path`.
+   */
+  path: string;
+  /** Which kind of subject `ugid` names. Identity: changing it is a different grant. */
+  type: AclSubjectType;
+  /** `tim@pve`, `admins`, `hf-provision@pve!hf-provision-…`. Identity. */
+  ugid: string;
+  /** The role bound here, e.g. `PVEAuditor`. ⚠️ It must exist — PVE refuses an unknown roleid. */
+  roleid: string;
+  /** Inherit down the path. PVE's default is ON, and this is the grant's ONLY mutable field. */
+  propagate?: boolean;
+}
+
+export interface AclAttributes {
+  path: string;
+  type: AclSubjectType;
+  ugid: string;
+  roleid: string;
+  propagate: boolean;
+  /**
+   * ⛔ PRESENCE AS AN ATTRIBUTE, AND IT IS WHAT MAKES THE FACTORY WORK HERE. `attributes` never
+   *   returns undefined: if it did, `reconcile` would take the create branch and POST to
+   *   `access/acl`, which PVE does not implement. Present-but-unbound sends every write down the
+   *   PUT branch instead, the only branch PVE has. The cost: the factory's read-back guard cannot
+   *   fire, so `reconcile` below re-checks this field itself and dies with the same honesty.
+   */
+  bound: boolean;
+}
+
+export interface ProxmoxAcl extends Resource<
+  'Proxmox.Acl',
+  AclProps,
+  AclAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxAcl = Resource<ProxmoxAcl>('Proxmox.Acl');
+
+/**
+ * ⚠️ PVE NORMALISES ACL PATHS AND RETURNS THE NORMALISED FORM, a forever-update trap when only one
+ *   side of the comparison is normalised. `PVE::AccessControl::normalize_path` collapses repeated
+ *   slashes and strips the trailing one, so a declared `/pool/house/` reads back as `/pool/house`
+ *   and a naive match never fires again. It also refuses a path with no leading slash, so one is
+ *   added here rather than letting `pool/house` 400.
+ */
+const normalize = (raw: string) => `/${raw.split('/').filter(Boolean).join('/')}`;
+
+/**
+ * ⚠️ THE WRITE NAMES THE SUBJECT WITH A PLURAL KEY THAT DIFFERS PER KIND — `users`, `groups`,
+ *   `tokens` — while the READ answers a singular `type`/`ugid` pair. The PUT declares
+ *   `additionalProperties: 0`, so `user=` fails with a 400 rather than being ignored. The bad case
+ *   is the WRONG plural: a valid parameter naming a subject kind you did not mean.
+ */
+const SUBJECT_FIELD = { group: 'groups', token: 'tokens', user: 'users' } as const;
+
+/** The tuple PVE keys a grant by, as the form it takes. Every write to this family starts here. */
+const tuple = (props: AclProps): Record<string, string> => ({
+  path: normalize(props.path),
+  roles: props.roleid,
+  [SUBJECT_FIELD[props.type]]: props.ugid,
+});
+
+/** Create and update are one call: the tuple plus the single mutable field. */
+const bind = (props: AclProps): Record<string, string> => ({
+  propagate: props.propagate === false ? '0' : '1',
+  ...tuple(props),
+});
+
+/** What a change of this string means: not an edit, a different grant. Used by `diff` below. */
+const identity = (grant: Pick<AclAttributes, 'path' | 'roleid' | 'type' | 'ugid'>) =>
+  [normalize(grant.path), grant.type, grant.ugid, grant.roleid].join(' ');
+
+/**
+ * ⚠️ `GET /access/acl` ANSWERS AN ARRAY, while the factory hands `attributes` the
+ *   `Record<string, unknown>` every other PVE read is shaped like. Rows are narrowed, not trusted,
+ *   and an empty result is not evidence of an empty cluster — see the last ⛔ in the header.
+ */
+const find = (live: unknown, props: AclProps) =>
+  (Array.isArray(live) ? live : [])
+    .filter((row): row is Record<string, unknown> => typeof row === 'object' && row !== null)
+    .find(
+      (row) =>
+        row['path'] === normalize(props.path) &&
+        row['type'] === props.type &&
+        row['ugid'] === props.ugid &&
+        row['roleid'] === props.roleid,
+    );
+
+/**
+ * ⚠️ PVE ANSWERS `propagate` AS 1/0 RATHER THAN true/false, AND OMITS IT WHEN IT CARRIES THE API
+ *   DEFAULT, WHICH IS ON. Reading an absent field as `false` would report drift on every plan,
+ *   forever, for every grant this provider did not create itself.
+ */
+const propagates = (row: Record<string, unknown>) => {
+  const value = row['propagate'];
+  return value === undefined || value === 1 || value === true || value === '1';
+};
+
+const ops = pveOperations<AclProps, AclAttributes>({
+  attributes: (live, props) => {
+    const row = find(live, props);
+    return {
+      // ⚠️ `propagate` reads false when nothing is bound, because there is no grant to inherit.
+      //   `bound` is the field that carries presence; this one means something only once it is set.
+      bound: row !== undefined,
+      path: normalize(props.path),
+      propagate: row !== undefined && propagates(row),
+      roleid: props.roleid,
+      type: props.type,
+      ugid: props.ugid,
+    };
+  },
+  /**
+   * ⛔ THE CREATE PATH IS UNREACHABLE ON A HEALTHY CLUSTER, AND ITS ERROR WILL MISLEAD YOU. The
+   *   factory POSTs `collection` only when the read came back undefined, and `attributes` never
+   *   does — so a POST means the GET itself failed (an expired 300s lease, a node down), not that
+   *   the grant is missing. PVE answers "Method 'POST /access/acl' not implemented": read that 501
+   *   as "the read failed" and go and look at the credential, not at the ACL.
+   */
+  /**
+   * ⛔ `provision`, AND WITHOUT IT EVERY GRANT READS BACK AS ABSENT. `GET /access/acl` is
+   *   FILTERED, NOT GATED — the schema's own words are "The returned list is restricted to objects
+   *   where you have rights to modify permissions". A credential without Permissions.Modify gets
+   *   HTTP 200 and an EMPTY ARRAY, never a 403, so there is no error for `read` to fold; it simply
+   *   sees nothing.
+   *   ⛔ THE READ LEASE IS EXACTLY SUCH A CREDENTIAL. `hf-read@pve` is PVEAuditor on `/`, whose
+   *     privilege set is Datastore.Audit, Mapping.Audit, Pool.Audit, SDN.Audit, Sys.Audit,
+   *     VM.Audit, VM.GuestAgent.Audit — MEASURED in the 2026-09-13 cluster read. No
+   *     Permissions.Modify. So on the default lease all fourteen live grants read back unbound,
+   *     `matches` is false for every one, the plan reports fourteen updates for grants that
+   *     plainly exist, and the deploy PUTs each one before acl.ts's own read-back guard dies.
+   *   ★ THIS IS THE SAME CLASS AS storage.ts, sdn-zone.ts, sdn-vnet.ts AND api-token.ts, and it is
+   *     the worst instance of it: those three are gated and answer 403, which is at least an
+   *     error. A filtered endpoint answers success with less data, which is indistinguishable from
+   *     the object not being there.
+   */
+  readRole: 'provision',
+  collection: () => 'access/acl',
+  createForm: bind,
+  /**
+   * ⚠️ ONLY `propagate` IS COMPARED, AND ONLY ONCE THE GRANT IS THERE. path/type/ugid/roleid are
+   *   the FILTER that produced these attributes, not a reading of the cluster: comparing them with
+   *   the props they came from is true by construction. An identity change is a DIFFERENT grant,
+   *   which `diff` in the provider handles.
+   */
+  matches: (attributes, props) =>
+    attributes.bound && attributes.propagate === (props.propagate !== false),
+  path: () => 'access/acl',
+  updateForm: bind,
+});
+
+export const ProxmoxAclProvider = () =>
+  Provider.effect(
+    ProxmoxAcl,
+    Effect.succeed(
+      ProxmoxAcl.Provider.of({
+        /**
+         * ⛔ EMPTY LIKE EVERY OTHER RESOURCE HERE, AND MOST OF ALL THIS ONE. `GET /access/acl`
+         *   hands back every grant a human ever clicked; adopting them would let a later plan
+         *   DELETE somebody's access as tidy-up. Adoption is an explicit act.
+         */
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds }) {
+          return yield* ops.read(olds);
+        }),
+        /**
+         * ⛔ AN IDENTITY CHANGE IS A REPLACE, AND THE FACTORY CANNOT SAY SO ALONE — it answers
+         *   `replace` only for objects with no update path, and this one has PUT. Left to delegate,
+         *   editing `roleid` (or the subject, or the path) would PUT the NEW grant and LEAVE THE
+         *   OLD ONE BOUND: access nobody declared, held indefinitely, invisible in the plan because
+         *   the provider believes it converged. Replace makes Alchemy call `delete` with the OLD
+         *   props, which is the only thing that removes it.
+         *   ⚠️ CREATE-FIRST, DELIBERATELY (Alchemy's default; `deleteFirst: true` would invert it).
+         *     Delete-first could remove the very grant the provision credential mints against and
+         *     leave nothing able to put it back. The cost is that a NARROWING change leaves the
+         *     wider grant bound until Phase 2 collects the old generation.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output !== undefined && isResolved(news) && identity(news) !== identity(output)) {
+            return { action: 'replace' } as const;
+          }
+          return yield* ops.diff(news, output);
+        }),
+        /**
+         * ⚠️ THE READ-BACK GUARD, RESTORED FOR A FAMILY WHOSE "ABSENT" IS NOT `undefined`.
+         *   `ops.reconcile` refuses when the object is still missing after a write, but missing
+         *   here is `bound: false`, which that check cannot see. PVE answers 200 with
+         *   `{"data":null}` on calls that did nothing: without this, a PUT that silently no-oped
+         *   is recorded as a landed grant and the next plan reads noop over the gap.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          const after = yield* ops.reconcile(news);
+          if (!after.bound) {
+            return yield* Effect.die(
+              new Error(
+                `access/acl: the write returned no error but ${identity(news)} is still not ` +
+                  'bound. Either the PUT did nothing, or the read credential cannot see the ' +
+                  'grant -- GET /access/acl is filtered to paths you may MODIFY permissions on, ' +
+                  'so a read-only role is answered [] rather than 403.',
+              ),
+            );
+          }
+          return after;
+        }),
+        /**
+         * ⛔ NOT `ops.destroy`, AND NOT AN OVERSIGHT. `DELETE /access/acl` is not implemented, so a
+         *   factory delete would fail every destroy — while looking like a permissions problem —
+         *   and leave the grant bound. Removal is the create call with `delete=1` and the identity
+         *   tuple, no `propagate`, because removal is keyed on the tuple and nothing else.
+         *
+         * ⚠️ IDEMPOTENT, AND SHARED: removing a grant that is already gone is a no-op, but the
+         *   tuple is cluster-global — re-read the second ⛔ in the header before assuming this
+         *   only takes away what this stack declared.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          const removal = { delete: '1', ...tuple(olds) };
+          yield* pve(olds.target, 'provision', 'PUT', 'access/acl', removal);
+        }),
+      }),
+    ),
+  );

package/src/proxmox/api-token-form.ts

@@ -0,0 +1,122 @@
+import type { ApiTokenAttributes, ApiTokenProps } from './api-token.ts';
+/**
+ * What a write to a PVE API token actually does, and the form that does it.
+ *
+ * ★ SPLIT OUT OF api-token.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is the one
+ *   metric-server-form.ts draws: this file answers "what does PVE store when this form arrives",
+ *   api-token.ts answers "what a token is and when it has changed". Nothing here reads the
+ *   cluster and nothing here decides a diff.
+ *
+ * ⚠️ THE `import type` BACK TO api-token.ts IS A CYCLE ON PAPER ONLY. It is type-only, so it is
+ *   erased before anything runs and `ApiTokenProps` stays in the file that declares the resource.
+ *
+ * ⛔ THE WRITE SEMANTICS BELOW ARE READ FROM THE CLUSTER'S OWN PERL RATHER THAN INFERRED FROM THE
+ *   API SCHEMA — `/usr/share/perl5/PVE/API2/User.pm`, subs `generate_token` and
+ *   `update_token_info`, read over SSH on n2 on 2026-09-13. The two disagree in exactly the place
+ *   that costs a forever-diff: the schema gives `expire` the default "same as user", and the code
+ *   never implements it. api-token.ts records what that means.
+ */
+import type { PveSpec } from './resource.ts';
+import { bool, int, text } from './values.ts';
+
+/**
+ * `<userid>!<tokenid>` — the name the rest of PVE calls this object by.
+ *
+ * ★ IT IS WHAT AN ACL BINDS. `Proxmox.Acl` with `type: 'token'` wants exactly this string as its
+ *   `ugid`, so reporting it as an attribute is what lets a privilege-separated token be granted
+ *   anything at all without somebody retyping the join by hand.
+ *
+ * ⚠️ DERIVED, NOT READ. MEASURED: `GET /access/users/monitoring@pve/token/exporter` answers
+ *   `{"expire":0,"privsep":0}` and echoes back neither half of its own identity. So this is built
+ *   from props, cannot disagree with the path the read used, and is therefore true by
+ *   construction — which is why it is reported and never compared.
+ */
+export const fullTokenid = (props: ApiTokenProps) => `${props.userid}!${props.tokenid}`;
+
+/**
+ * Everything a token has, in the form PVE wants. Create and update send exactly this.
+ *
+ * ⛔ `userid` AND `tokenid` ARE NOT IN IT, and that is not an omission. Both are path segments of
+ *   `access/users/{userid}/token/{tokenid}` — which is the path the POST goes to as well as the
+ *   PUT — so a second copy in the body can only ever disagree with the path it was sent to.
+ *   metric-server.ts omits its `id` for the same reason and says so there.
+ *
+ * ⚠️ EVERY FIELD IS SENT ON EVERY WRITE, THE EMPTY COMMENT INCLUDED, BECAUSE A PUT MERGES.
+ *   MEASURED in `update_token_info`: `$token->{comment} = $param->{comment} if defined(...)`
+ *   followed by `delete $token->{comment} if (!length $token->{comment})`. So `comment=` is how a
+ *   comment is CLEARED; omitting it leaves the old text in place while `matches` goes on asking
+ *   for an update the update cannot make. user.ts writes the same reasoning out for `groups`.
+ *   ⚠️ THE `delete=` PARAMETER IS NOT USED AND WOULD NOT HELP. Its whitelist in that sub is
+ *     literally `my $deletable = { comment => 1 };`, and anything else answers
+ *     "unknown option '<k>'" — so `expire` and `privsep` have no clear path at all, which is the
+ *     other half of why both are required props rather than optional ones.
+ *
+ * ⚠️ `flag()` FROM values.ts IS DELIBERATELY NOT USED FOR `privsep`. Its entire job is turning an
+ *   UNDECLARED boolean into `undefined` so the field is omitted from the form; `privsep` is a
+ *   required prop precisely so that it is never undeclared, so there is nothing for it to do and
+ *   its `string | undefined` return would have to be asserted away to fit `Record<string,string>`.
+ *   An assertion here would be a claim about the prop that the type already makes properly.
+ */
+export const shape = (props: ApiTokenProps): Record<string, string> => ({
+  comment: props.comment ?? '',
+  expire: String(props.expire),
+  privsep: props.privsep ? '1' : '0',
+});
+
+export const apiTokenSpec: PveSpec<ApiTokenProps, ApiTokenAttributes> = {
+  // ⛔ THE ITEM READ NEEDS `User.Modify`, WHICH THE AUDITOR-SHAPED READ LEASE DOES NOT HAVE. The
+  //   measurement and the consequence are in the header's last ⚠️; the mechanism — a silent
+  //   "absent" rather than a 403 — is the ⛔ on `readRole` in resource.ts.
+  readRole: 'provision',
+  /**
+   * ★ NOTHING PVE REPORTS HERE IS UNWRITABLE, WHICH IS UNUSUAL IN THIS PACKAGE AND IS WHY
+   *   `matches` can compare everything it reads. The GET returns exactly `comment`, `expire` and
+   *   `privsep`; PUT accepts exactly those three. There is no autoscaled field, no server-assigned
+   *   id, no set whose order PVE reshuffles — the three killers the neighbouring files carry
+   *   ⚠️s about do not arise. The two identity fields and `fullTokenid` come from props and are
+   *   true by construction, so comparing them would be theatre.
+   * ⚠️ `undefined` WHEN NEITHER FLAG IS THERE, BECAUSE BOTH ARE ALWAYS THERE. `user.cfg`
+   *   materialises `expire` and `privsep` for every token it stores, so an answer carrying neither
+   *   is not a token — and without this guard `bool`/`int` would invent one out of their fallbacks
+   *   and the read-back guard in `reconcile` could never fire.
+   */
+  attributes: (live, props) => {
+    const expire = live['expire'];
+    const privsep = live['privsep'];
+    if (expire === undefined && privsep === undefined) return undefined;
+    return {
+      comment: text(live['comment']),
+      expire: int(expire, 0),
+      fullTokenid: fullTokenid(props),
+      /** ⚠️ FALLBACK `true`, MATCHING PVE'S API DEFAULT — unreachable given the guard above, but
+       *   wrong in the safe direction if a future release stops emitting the field. */
+      privsep: bool(privsep, true),
+      tokenid: props.tokenid,
+      userid: props.userid,
+    };
+  },
+  /**
+   * ⛔ THE SAME STRING AS `path`, AND NOT A TYPO. A token is POSTed to its OWN url, not to the
+   *   collection: MEASURED, `/access/users/{userid}/token` carries a GET and nothing else, while
+   *   POST lives on `{tokenid}`. metric-server.ts has the identical shape for the identical
+   *   reason and records the experiment there.
+   */
+  collection: (props) => `access/users/${props.userid}/token/${props.tokenid}`,
+  createForm: shape,
+  /**
+   * ⚠️ EXACTLY THE THREE FIELDS A PUT CAN PUT BACK, WHICH IS ALSO EXACTLY WHAT THE GET REPORTS.
+   *   MEASURED, by replaying these two functions over the live GET bodies of all four token
+   *   shapes this cluster has: `monitoring@pve!exporter` (no comment), `tofu@pve!apply` and
+   *   `sablier@pve!sablier` (commented), and a live OpenBao lease under `hf-read@pve` (a real
+   *   non-zero `expire`, offered as both `1789327175` and `"1789327175"` since `int` must not care
+   *   which). All four answer noop; flipping `privsep` answers update; an empty body answers
+   *   absent. ⚠️ THAT IS THE COMPARISON, NOT THE ENGINE — no `alchemy plan` was run against this
+   *   family, and nothing here was written to the cluster.
+   */
+  matches: (attributes, props) =>
+    attributes.comment === (props.comment ?? '') &&
+    attributes.expire === props.expire &&
+    attributes.privsep === props.privsep,
+  path: (props) => `access/users/${props.userid}/token/${props.tokenid}`,
+  updateForm: shape,
+};

package/src/proxmox/api-token.ts

@@ -0,0 +1,222 @@
+/**
+ * `Proxmox.ApiToken` — a PVE API token: the thing a service actually authenticates as.
+ *
+ * ⛔ THE SECRET EXISTS FOR ONE HTTP RESPONSE AND THEN NOWHERE. MEASURED from the cluster's own
+ *   schema (`/usr/share/pve-docs/api-viewer/apidoc.js` on n2, 2026-09-13): POST returns
+ *   `["full-tokenid","info","value"]`; PUT returns `["comment","expire","full-tokenid","privsep",
+ *   "value"]` with `value` present ONLY when `regenerate` was set; GET returns
+ *   `["comment","expire","privsep"]` and never the secret. A live token agrees —
+ *   `GET /access/users/monitoring@pve/token/exporter` answers `{"expire":0,"privsep":0}`. PVE says
+ *   it plainly on the POST: the value "needs to be stored as it cannot be retrieved afterwards".
+ *
+ * ⛔ SO A TOKEN THIS RESOURCE CREATES IS UNUSABLE, AND SAYING SO IS THE POINT OF THIS BLOCK. The
+ *   secret may not become an attribute: Alchemy persists attributes UNENCRYPTED, and this estate's
+ *   state store is a Postgres dumped nightly (the ⛔ in credentials.ts). So `reconcile` drops the
+ *   value on the floor, and what lands is a live credential in `/etc/pve/user.cfg` whose secret
+ *   nobody holds. No `regenerate` rescues it, because a regenerated value is discarded the same
+ *   way. The only escape is an operator who captured the value out of band — which this provider
+ *   gives them no way to do.
+ *   ★ SO POINT THIS FAMILY AT TOKENS THAT ALREADY EXIST. `comment`, `expire` and `privsep` are the
+ *     whole of a token's policy, and declaring them is real work: it is how `expire` stops being
+ *     whatever somebody typed in 2024. Mint NEW tokens where the secret can be caught — OpenBao's
+ *     `proxmox-tb4` mount, or a human at `pveum user token add`.
+ *   ⚠️ THE CREATE PATH IS LEFT REACHABLE RATHER THAN STUBBED. A create that silently did nothing
+ *     would be the same lie as the stubbed delete resource.ts's ★ refuses; the honest arrangement
+ *     is a create that works and a header that says what it produces.
+ *
+ * ⛔ THERE IS NO `regenerate` PROP, AND IT IS NOT AN OVERSIGHT. PVE's own description: "All users
+ *   of the previous secret will lose access after this operation." A prop for it would revoke a
+ *   live credential during a deploy whose plan said `update`, and hand back a replacement this
+ *   provider is obliged to throw away — breakage with no recovery. Rotation belongs to the mount
+ *   that owns the lease, or to a human who is watching.
+ *
+ * ⚠️ THERE IS A SECOND WRITER TO THESE OBJECTS AND IT IS THE ONE THIS PROVIDER RUNS ON. OpenBao's
+ *   `proxmox-tb4` engine mints PVE tokens under `hf-read@pve` and `hf-provision@pve` — read from
+ *   `house/platform/secrets/vault/plugin-proxmox/proxmox/`: `privsep=0` (client.go), `expire` set
+ *   to the lease deadline, and an id the plugin CHOOSES,
+ *   `hf-<role>-<actor>-<entity6>-<stamp>-<nonce>` (tokenname.go). Revocation and WAL rollback look
+ *   up that one exact id (wal.go); neither sweeps a prefix. So the two systems cannot collide on
+ *   one object by accident — but they share the USER: `hf-read@pve` held three live leases when
+ *   this was written, and `Proxmox.User` deleting that account takes every one of them with it.
+ *   ⛔ DO NOT DECLARE A TOKEN UNDER A MINT USER. `expire` is what makes that dangerous rather than
+ *     untidy: point this resource at a lease token with the wrong expire and a 300-second
+ *     credential becomes a permanent one — and on `hf-provision@pve` that credential carries
+ *     `Permissions.Modify` at `/`. docs/privileges.md records what those 27 privileges buy.
+ *
+ * ⚠️ PRIVILEGES, AND THE READ LANE CANNOT DO IT. MEASURED: all four methods on this path check
+ *   `['or', ['userid-param','self'], ['userid-group', ['User.Modify']]]` — with no `Sys.Audit`
+ *   alternative, unlike `GET /access/users/{userid}`, which has one. And
+ *   `pvesh get /access/permissions --userid hf-read@pve --path /access/groups` answers the seven
+ *   PVEAuditor audit privileges and no `User.Modify`, while `hf-provision@pve` has it. So the
+ *   3600s read lease reaches at most its OWN account's tokens and is refused for every other
+ *   userid — which `read` in resource.ts folds into "absent", so the plan says create and the POST
+ *   then fails with "Token already exists". Hence `readRole: 'provision'` below, for the same
+ *   reason storage.ts, sdn-zone.ts and sdn-vnet.ts set it, at the same cost: every plan mints a
+ *   300s non-renewable provision lease just to read.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { apiTokenSpec } from './api-token-form.ts';
+import { type PveRequirements, type WithTarget, pveHandlers, pveOperations } from './resource.ts';
+
+export interface ApiTokenProps extends WithTarget {
+  /**
+   * The account that owns the token, realm-qualified: `tofu@pve`, `root@pam`. Identity.
+   *
+   * ⚠️ THE ACCOUNT MUST ALREADY EXIST. Every method here runs `check_user_exist` first, so a
+   *   token named under a missing user fails the READ (folded to "absent") and then fails the
+   *   create with "no such user" — the honest error, arriving one step after the misleading plan.
+   *   Sequence a `Proxmox.User` ahead of it and the ordering takes care of itself.
+   */
+  userid: string;
+  /**
+   * The token's own name, unique within the account. Identity.
+   *
+   * ⚠️ PVE HAS NO RENAME, AND HERE THAT COSTS MORE THAN IT DOES FOR A USER. Editing this prop (or
+   *   `userid`) points `path` at a DIFFERENT token, which reads as absent and is then created —
+   *   leaving the old token LIVE, with its secret still working, invisible to the plan, while the
+   *   new one is the unusable kind described at the top. Rename by declaring a delete and a
+   *   create, the way user.ts says for an account.
+   *   ⛔ `diff` IS NOT OVERRIDDEN TO SAY `replace` THE WAY acl.ts DOES, AND THE DIFFERENCE IS THE
+   *     OBJECT. There, replace removes a grant that can be rebuilt from its own tuple; here it
+   *     would DELETE a live token — destroying an irrecoverable secret, and everything using it —
+   *     to tidy up a name. Leaving the old token standing is the lesser harm, and saying so here
+   *     is what keeps it from looking like an omission.
+   * ⚠️ PATTERN `[A-Za-z][A-Za-z0-9.\-_]+`: a letter first, two characters minimum. The schema
+   *   declares no maxLength; the OpenBao plugin assumes a conservative 64 rather than finding the
+   *   real limit in production, and so should anything else.
+   */
+  tokenid: string;
+  /**
+   * Free text in `pveum user token list` and the UI. Empty is how it is cleared — see `shape`.
+   * ⚠️ ANY CHARACTER IS SAFE HERE, MEASURED, and it was worth checking: `user.cfg` is a
+   *   colon-delimited line, so a comment holding a colon or a newline is the obvious place for a
+   *   round-trip to lose a character and diff forever. PVE escapes it — `encode_text` turns
+   *   `a:b\nc%d` into `a%3Ab%0Ac%25d` and `decode_text` gives it back byte for byte.
+   */
+  comment?: string;
+  /**
+   * Seconds since the epoch, or 0 for "never expires".
+   *
+   * ⛔ REQUIRED, AND THE SCHEMA WILL TELL YOU IT NEED NOT BE. It declares the default "same as
+   *   user", and the code never implements it: `generate_token` writes `expire` only when the
+   *   parameter is defined, `user.cfg` stores a token as `token:<id>:<expire>:<privsep>:<comment>:`
+   *   with no absent state, and the parser does `$expire = 0 if !$expire` (AccessControl.pm:1624).
+   *   MEASURED end to end: every token on this cluster that was created without an expire reads
+   *   back `"expire":0`. So "same as user" is documentation of an intention, not behaviour.
+   * ⛔ WHICH IS WHY IT IS NOT OPTIONAL-DEFAULTING-TO-0. That spelling reads identically and is far
+   *   worse: an omitted `expire` would then quietly WRITE 0 over a live deadline, turning an
+   *   expiring credential into a permanent one, and the plan would call it an update. Requiring
+   *   the field makes "this token never expires" a sentence somebody had to type.
+   */
+  expire: number;
+  /**
+   * True keeps the token's privileges separate from its owner's — it gets NOTHING until an ACL
+   *   names `fullTokenid`. False gives it the owner's privileges entire.
+   *
+   * ⛔ REQUIRED FOR THE SAME REASON AS `expire`, AND THE BLAST RADIUS IS LARGER. PVE's API default
+   *   is 1, every token on this cluster is 0 (measured), and `user.cfg` materialises it either way
+   *   — `$privsep = $privsep ? 1 : 0` (AccessControl.pm:1622), so there is no unset state to
+   *   preserve. Were this optional, adopting a live token without mentioning `privsep` would plan
+   *   an update to 1 and STRIP a working credential of every privilege it has, silently: PVE
+   *   returns 401/403 to the service, nothing errors here, and `tofu@pve!apply` simply stops
+   *   working. Required, so adopting a token is a sentence that states what it is.
+   * ⚠️ AND `false` IS NOT A SHRUG. It is a token with its owner's whole privilege set; under a
+   *   provisioning account that is the account's full authority with a separate secret.
+   */
+  privsep: boolean;
+}
+
+export interface ApiTokenAttributes {
+  userid: string;
+  tokenid: string;
+  /** `<userid>!<tokenid>` — what `Proxmox.Acl` binds as its `ugid`. Derived; never compared. */
+  fullTokenid: string;
+  comment: string;
+  expire: number;
+  privsep: boolean;
+  /**
+   * ⛔ THERE IS NO `value` FIELD HERE AND THERE NEVER MAY BE. Adding one would write a working PVE
+   *   credential, in clear, into the state Postgres and into every nightly dump of it — the exact
+   *   leak metric-server.ts types its `token` as `never` to prevent. The read cannot supply one
+   *   anyway; only create and regenerate can, and both of those responses are dropped.
+   */
+}
+
+export interface ProxmoxApiToken extends Resource<
+  'Proxmox.ApiToken',
+  ApiTokenProps,
+  ApiTokenAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ★ `retain` BY DEFAULT, AND THIS IS THE PLAINEST CASE FOR IT IN THE PACKAGE. A token's contents
+ *   are one irreplaceable secret: delete it and the value is gone, a replacement is a DIFFERENT
+ *   value, and every holder loses access the instant `cfs_write_file` returns — with no error
+ *   raised anywhere near them. The live cluster's tokens are `monitoring@pve!exporter` (the PVE
+ *   exporter feeding VictoriaMetrics), `mcp@pve!executor`, `tofu@pve!apply`, `tofu@pve!ro`,
+ *   `sablier@pve!sablier` and `vaultmint@pve!engine` — the last being the parent credential the
+ *   OpenBao mount itself authenticates with, so orphaning that one would stop every plan in this
+ *   package, this resource included. `delete` is FULLY IMPLEMENTED (DELETE is a real method on
+ *   this path, measured) and runs the moment a caller opts in with `.pipe(RemovalPolicy.destroy())`.
+ *   See the ★ in resource.ts, which explains the convention once.
+ */
+export const ProxmoxApiToken = Resource<ProxmoxApiToken>('Proxmox.ApiToken', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const ops = pveOperations(apiTokenSpec);
+
+/**
+ * ⛔ THIS FAMILY ADOPTS AND MANAGES TOKENS; IT REFUSES TO MINT ONE, AND THAT IS A DECISION RATHER
+ *   THAN A GAP. The secret exists ONLY in the create response — MEASURED from the schema: `POST`
+ *   returns `["full-tokenid","info","value"]`, where `value` is "API token value used for
+ *   authentication", while `GET` returns `["comment","expire","privsep"]` and never the secret.
+ *   It may not become an attribute, because Alchemy writes attributes to its state store
+ *   UNENCRYPTED into a Postgres that is dumped nightly.
+ *
+ *   So a token created here would be A LIVE CREDENTIAL ON THE CLUSTER THAT NOBODY HOLDS: valid,
+ *   privileged, unusable, and indistinguishable from one somebody meant to keep. Regenerating does
+ *   not rescue it — a `regenerate` PUT returns the new value down the same discarded path. So
+ *   `reconcile` refuses by name and says what to do instead.
+ *
+ * ★ EVERYTHING ELSE STILL WORKS, AND IT IS THE HALF WORTH HAVING. Adopting an existing token and
+ *   converging its `comment`, `expire` and `privsep` are real operations: TB4 carries SEVEN tokens
+ *   with `expire=0` and `privsep=0` made by clicks nobody recorded. Declaring those freezes the
+ *   set, and an eighth appearing shows up as drift.
+ *
+ * ⚠️ IF DECLARATIVE MINTING IS EVER WANTED, the missing piece is a secret SINK — write the value
+ *   straight into an OpenBao kv path and return only its address. That is a different resource
+ *   with a different contract; it must not be bolted onto this one.
+ */
+const handlers = {
+  ...pveHandlers(apiTokenSpec),
+  reconcile: Effect.fn(function* ({ news }: { news: ApiTokenProps }) {
+    const live = yield* ops.read(news);
+    if (live === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `${news.userid}!${news.tokenid}: this resource does not create API tokens. PVE returns ` +
+            'the secret only in the create response and it cannot be stored, so a token made here ' +
+            'would be a live credential nobody holds. Create it with `pveum user token add` and ' +
+            'capture the value, or mint a short-lived one from the OpenBao proxmox mount ' +
+            '(`bao read proxmox-tb4/creds/<role>`) -- then declare it here to manage it.',
+        ),
+      );
+    }
+    return yield* ops.reconcile(news);
+  }),
+};
+
+/**
+ * ⛔ `list` IS EMPTY, AND FOR THIS FAMILY THAT MATTERS MORE THAN THE GENERIC ARGUMENT IN
+ *   resource.ts. A token index handed to Alchemy would offer up `vaultmint@pve!engine` and every
+ *   live OpenBao lease for adoption — and adoption is what makes a later plan willing to delete.
+ *   The mount's leases in particular appear and vanish on their own; anything that adopted one
+ *   would report drift against a credential that was never its to hold.
+ */
+export const ProxmoxApiTokenProvider = () =>
+  Provider.effect(ProxmoxApiToken, Effect.succeed(ProxmoxApiToken.Provider.of(handlers)));