@homeflare/alchemy 0.12.0 → 0.14.0

package/src/github/repo-policy.ts

@@ -0,0 +1,65 @@
+/**
+ * `declareRepoPolicy` — the policy from repo-policy-form.ts, as resources.
+ *
+ *     const policy = yield* declareRepoPolicy('api', {
+ *       owner: 'my-org',
+ *       repository: 'api',
+ *       checks: ['ci', 'secret scan'],
+ *     });
+ *
+ * Provide `GitHub.providers()`; this subpath adds no provider of its own.
+ *
+ * ⛔ THE RULESET CANNOT BE ADOPTED, AND A FIRST DEPLOY ONTO A REPO THAT ALREADY HAS ONE
+ *   MAKES A SECOND. Read out of alchemy@2.0.0-beta.79's own source on 2026-09-22
+ *   (`node_modules/alchemy/lib/github/Ruleset.js`): `read` returns `undefined` whenever
+ *   there is no prior output, and `reconcile` looks the live ruleset up only BY THE ID IN
+ *   THAT OUTPUT — with none, it calls `createRepoRuleset` unconditionally. GitHub permits
+ *   several rulesets with the same name on one repository, so nothing errors; the repo
+ *   quietly ends up with two, both enforcing.
+ *   ★ SO, BEFORE THE FIRST DEPLOY: `gh api repos/<owner>/<repo>/rulesets` and delete a
+ *     hand-made ruleset of the same name, or give this one a `rulesetName` of its own.
+ *     Afterwards the state carries the id and every later deploy converges that one.
+ *   ⚠️ `GitHub.Repository` does NOT share the problem — its `reconcile` probes by name
+ *     and converges onto whatever is live — so only half of this helper is adopt-safe,
+ *     and the halves fail differently. See docs/repo-policy.md.
+ *
+ * ⛔ BOTH RESOURCES RETAIN. `retain` is already the vendor default for each of them; it
+ *   is piped anyway so that a vendor change cannot quietly turn "drop this call from the
+ *   stack" into "delete the repository" or "unprotect the default branch".
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as GitHub from 'alchemy/GitHub';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { type RepoPolicyOptions, repoPolicy } from './repo-policy-form.ts';
+
+export interface DeclareRepoPolicyOptions extends RepoPolicyOptions {
+  /**
+   * `true`/`false` pipe `adopt(…)` onto both resources; omitted, the deploy's own policy
+   * decides. ⚠️ It changes nothing about the ruleset hazard above: adoption routes on
+   * what a provider's `read` reports, and this one reports nothing without prior state.
+   */
+  readonly adopt?: boolean;
+}
+
+/**
+ * Declares the repository and its ruleset under `<id>` and `<id>-ruleset`. Fails, before
+ * declaring either, on any policy the form refuses.
+ */
+export const declareRepoPolicy = (id: string, options: DeclareRepoPolicyOptions) =>
+  Effect.gen(function* () {
+    const policy = yield* Effect.try({
+      catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+      try: () => repoPolicy(options),
+    });
+    // ⚠️ `never` in the error channel, not a generic `E`: `AdoptPolicy.adopt` is typed
+    //   `Effect<A, never, R> => Effect<A, never, R>`, so a wider error type fails to
+    //   compile here rather than at the call site. Alchemy's resources declare `never`.
+    const owned = <A, R>(resource: Effect.Effect<A, never, R>) => {
+      const kept = resource.pipe(RemovalPolicy.retain());
+      return options.adopt === undefined ? kept : kept.pipe(adopt(options.adopt));
+    };
+    const repository = yield* owned(GitHub.Repository(id, policy.repository));
+    const ruleset = yield* owned(GitHub.Ruleset(`${id}-ruleset`, policy.ruleset));
+    return { policy, repository, ruleset };
+  });

package/src/index.ts

@@ -6,6 +6,7 @@
  *
  *     import { R2BucketLock } from '@homeflare/alchemy/cloudflare';
  *     import { BranchProtection } from '@homeflare/alchemy/forgejo';
+ *     import { declareRepoPolicy } from '@homeflare/alchemy/github';
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';

package/src/proxmox/alertmanager-body.ts

@@ -0,0 +1,125 @@
+/**
+ * A PBS webhook body that posts one Alertmanager v2 alert — `POST /api/v2/alerts` takes a JSON
+ * ARRAY of `postableAlert`, each with a required `labels` map and an optional `annotations` map,
+ * every value a string (Alertmanager's api/v2/openapi.yaml, read at main 2026-09-22).
+ *
+ * ★ PURE TEXT, NOT A RENDERER. PBS renders it, with Handlebars, at send time: `{{ severity }}`,
+ *   `{{ title }}`, `{{ message }}`, `{{ timestamp }}` and `{{ fields.<name> }}` are the
+ *   notification, and `json`, `escape` and `url-encode` are the only helpers
+ *   (proxmox-notify endpoints/webhook.rs `setup_handlebars`, read at HEAD 2026-09-22).
+ *
+ * ⛔ THERE IS NO ESCAPING UNLESS THE TEMPLATE ASKS FOR IT. The webhook's Handlebars registers
+ *   `no_escape` ("There is no escape."), so `"{{ message }}"` breaks the JSON the first time a
+ *   task log holds a quote or a newline — and a failed job's message is exactly a task log. Every
+ *   value below goes through `json`, which emits a complete, quoted JSON string.
+ * ⛔ A FIELD THE NOTIFICATION DOES NOT CARRY MUST NOT BE REACHED FOR BARE. `escape` on a missing
+ *   field fails the whole render, and the notification is then lost — not degraded. MEASURED
+ *   (2026-09-22) with handlebars-rust 5.1.2 and the webhook's three helpers restated from source:
+ *   `{{ escape fields.job-id }}` over no fields errors "param at index 0 required but not found";
+ *   `{{ json fields.job-id }}` renders `null`, valid JSON but not a label value. Garbage
+ *   collection has no `job-id`, and the UI's "Test" button sends a notification with NO fields at
+ *   all (lib.rs `test_target`). So every field-derived label sits inside
+ *   `{{#if}}`, ends with its own comma, and the labels after them are always there: whichever
+ *   fields are present, the object stays valid JSON.
+ *
+ * ⚠️ ALERTMANAGER RESOLVES IT BY ITSELF. With no `endsAt` it sets `now + resolve_timeout` (5m by
+ *   default, api/v2/api.go `postAlertsHandler`), and PBS never sends a resolve — so a receiver
+ *   with `send_resolved: true` reports "resolved" five minutes after a failure that nobody fixed.
+ *   Page on the firing notification; do not read the resolve as a recovery.
+ * ⚠️ `severity` IS PBS'S WORD, not Alertmanager convention: `info`, `notice`, `warning`, `error`,
+ *   `unknown`. Route on `severity="error"`, or relabel it in the Alertmanager config.
+ */
+
+export interface AlertmanagerBodyOptions {
+  /** The `alertname` label. Default `PbsNotification`; `job_type` says which job it was. */
+  readonly alertname?: string;
+  /** The `source` label. Default `pbs`. */
+  readonly source?: string;
+  /** Optional `generatorURL` — an absolute link back to the PBS UI. */
+  readonly generatorURL?: string;
+}
+
+/**
+ * ⛔ AN OPTION IS PASTED INTO THE TEMPLATE, SO IT MAY NOT CARRY TEMPLATE SYNTAX. A `{{` in an
+ *   alert name would be rendered by PBS as an expression; a brace or backslash is refused here
+ *   rather than escaped, because Handlebars' escape rules are the renderer's, not this file's.
+ */
+const literal = (label: string, value: string): string => {
+  if (/[{}\\]/.test(value) || value === '') {
+    throw new Error(
+      `alertmanagerAlertBody: ${label} must be non-empty and hold no '{', '}' or '\\'`,
+    );
+  }
+  return JSON.stringify(value);
+};
+
+/**
+ * ⛔ AN ABSOLUTE http(s) URL OR NOTHING. Alertmanager validates `generatorURL` as `format: uri`
+ *   (api/v2/openapi.yaml) and answers 422 for the WHOLE post — so a typo here would not degrade
+ *   one field, it would lose every notification, and only at send time.
+ */
+const absoluteUrl = (value: string): string => {
+  const text = literal('generatorURL', value);
+  let protocol = '';
+  try {
+    protocol = new URL(value).protocol;
+  } catch {
+    // not a URL at all: refused below, like a relative one
+  }
+  if (protocol !== 'https:' && protocol !== 'http:') {
+    throw new Error('alertmanagerAlertBody: generatorURL must be an absolute http(s) URL');
+  }
+  return text;
+};
+
+/** Label name → notification field. ⚠️ Label names must match `[a-zA-Z_][a-zA-Z0-9_]*`. */
+const FIELD_LABELS: readonly (readonly [label: string, field: string])[] = [
+  ['job_type', 'type'],
+  ['job_id', 'job-id'],
+  ['datastore', 'datastore'],
+  ['hostname', 'hostname'],
+];
+
+/**
+ * The body template. Declare it on a webhook target together with `Content-Type:
+ * application/json`, method `post`, and the URL `<alertmanager>/api/v2/alerts`.
+ *
+ * ★ `fields.job-id` IS A VALID PATH: Handlebars-rust 5 (the version proxmox-notify pins) allows
+ *   `-` in an identifier (grammar.pest `symbol_char`), as handlebars.js does. The same scratch
+ *   build rendered this template for a GC failure, a verify failure and a field-less test
+ *   notification, and each parsed as JSON with string-only labels. The adversarial review re-ran
+ *   it over the test file's whole matrix — every PBS event's fields x five severities x hostile
+ *   text, 840 renders with and without `generatorURL` — and every one parsed (2026-09-22).
+ * ⚠️ THAT BUILD IS NOT PBS. The first real notification is the measurement that counts: send one
+ *   with the target's "Test" button and read what Alertmanager received.
+ */
+export const alertmanagerAlertBody = (options: AlertmanagerBodyOptions = {}): string => {
+  const alertname = literal('alertname', options.alertname ?? 'PbsNotification');
+  const source = literal('source', options.source ?? 'pbs');
+  const labels = FIELD_LABELS.map(
+    ([label, field]) =>
+      `      {{#if fields.${field}}}"${label}": {{ json fields.${field} }},{{/if}}`,
+  );
+  const link =
+    options.generatorURL === undefined
+      ? ''
+      : `,\n    "generatorURL": ${absoluteUrl(options.generatorURL)}`;
+  return [
+    '[',
+    '  {',
+    '    "labels": {',
+    ...labels,
+    '      "severity": {{ json severity }},',
+    `      "alertname": ${alertname},`,
+    `      "source": ${source}`,
+    '    },',
+    '    "annotations": {',
+    '      "summary": {{ json title }},',
+    '      "description": {{ json message }},',
+    '      "timestamp": "{{ timestamp }}"',
+    `    }${link}`,
+    '  }',
+    ']',
+    '',
+  ].join('\n');
+};

package/src/proxmox/credential-literals.test.ts

@@ -0,0 +1,148 @@
+/**
+ * A literal credential in a plain `Pbs.NotificationTarget` prop is refused — and refused BEFORE
+ * Alchemy writes the props to the state store, which is the whole point.
+ *
+ * ★ THE END-TO-END CASES RUN ALCHEMY'S OWN PLAN AND APPLY (verify/fake-engine.ts) and dump the
+ *   store, because the failure being pinned is not "a refusal exists" but "the token never
+ *   reached the row": before the fix a refused create had already committed its props.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import type { PbsTarget } from './credentials.ts';
+import {
+  isCredentialName,
+  literalCredentialHeaders,
+  literalCredentialsInUrl,
+} from './credential-literals.ts';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { withoutBao } from './fake-pve.ts';
+import {
+  PbsNotificationTarget,
+  type PbsNotificationTargetProps,
+  PbsNotificationTargetProvider,
+} from './pbs-notification-target.ts';
+import { refusals } from './pbs-notification-target-form.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const LITERAL = 'lit-7a1c-not-real';
+const AM = 'https://alertmanager.example.com/api/v2/alerts';
+
+const hook = (over: Partial<PbsNotificationTargetProps> = {}): PbsNotificationTargetProps => ({
+  method: 'post',
+  name: 'alertmanager',
+  target: PBS,
+  type: 'webhook',
+  url: AM,
+  ...over,
+});
+
+describe('which names are credentials', () => {
+  test('authorization, cookie and credential words — whole names or dash/underscore words', () => {
+    for (const name of ['Authorization', 'proxy-authorization', 'Cookie', 'X-Api-Key', 'api_key']) {
+      expect(isCredentialName(name)).toBe(true);
+    }
+    for (const name of ['X-Auth-Token', 'Private-Token', 'X-Gotify-Key', 'token', 'sig', 'code']) {
+      expect(isCredentialName(name)).toBe(true);
+    }
+    for (const name of ['Content-Type', 'X-Scope-OrgID', 'Author', 'Keyword', 'Passthrough']) {
+      expect(isCredentialName(name)).toBe(false);
+    }
+  });
+});
+
+describe('literal credentials are found by where they sit', () => {
+  test('headers: a literal is refused; a secrets template, `{ fromEnv }` and `""` are not', () => {
+    expect(
+      literalCredentialHeaders({
+        'Content-Type': 'application/json',
+        Cookie: `session=${LITERAL}`,
+        'X-Api-Key': { fromEnv: 'HOOK_KEY' },
+        Authorization: `Bearer ${LITERAL}`,
+        'X-Auth-Token': '{{secrets.token}}',
+        'X-Empty-Token': '',
+      }),
+    ).toEqual(['Authorization', 'Cookie']);
+    expect(literalCredentialHeaders({ Authorization: 'Bearer {{ secrets.token }}' })).toEqual([]);
+    expect(literalCredentialHeaders(undefined)).toEqual([]);
+  });
+
+  test('a URL: a userinfo password and credential-named query parameters, by name', () => {
+    expect(literalCredentialsInUrl(`https://pbs:${LITERAL}@am.example.com/x`)).toEqual([
+      'userinfo',
+    ]);
+    expect(literalCredentialsInUrl(`${AM}?token=${LITERAL}&team=ops&api_key=${LITERAL}`)).toEqual([
+      '?token',
+      '?api_key',
+    ]);
+    expect(literalCredentialsInUrl(`${AM}?code=${LITERAL}#token=${LITERAL}`)).toEqual([
+      '?code',
+      '?token',
+    ]);
+    expect(literalCredentialsInUrl(`${AM}#team=ops&sig=${LITERAL}`)).toEqual(['?sig']);
+  });
+
+  test('a URL that references its secrets, or has no password, is clean', () => {
+    for (const url of [
+      AM,
+      `${AM}?team=ops`,
+      `${AM}?token={{ url-encode secrets.token }}`,
+      'https://pbs:{{ secrets.pw }}@am.example.com/',
+      'https://pbs@am.example.com/',
+      `${AM}?token=`,
+      undefined,
+    ]) {
+      expect(literalCredentialsInUrl(url)).toEqual([]);
+    }
+  });
+
+  test('refusals name the header or the URL part — never the value', () => {
+    const reasons = refusals(
+      hook({ header: { Authorization: `Bearer ${LITERAL}` }, url: `${AM}?token=${LITERAL}` }),
+    );
+    expect(reasons).toHaveLength(2);
+    expect(reasons[0]).toStartWith("header 'Authorization' holds a literal credential");
+    expect(reasons[1]).toStartWith("'url' ?token holds a literal credential");
+    expect(reasons.join(' ')).not.toContain(LITERAL);
+  });
+});
+
+describe('through Alchemy: refused at plan, before anything is stored or sent', () => {
+  const run = async (props: PbsNotificationTargetProps) => {
+    const fake = fakeNotify();
+    let failure = '';
+    let stored = '';
+    await withoutBao(async () => {
+      const engine = engineOver(
+        PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      await engine.deploy(PbsNotificationTarget('alertmanager', props)).catch((error: unknown) => {
+        failure = String(error);
+      });
+      stored = engine.stored();
+    });
+    return { failure, stored, writes: fake.writes() };
+  };
+
+  test('a literal Authorization header on a NEW target never reaches the store', async () => {
+    const { failure, stored, writes } = await run(
+      hook({ header: { Authorization: `Bearer ${LITERAL}` } }),
+    );
+    expect(failure).toContain("header 'Authorization' holds a literal credential");
+    expect(stored).not.toContain(LITERAL);
+    expect(writes).toEqual([]);
+  });
+
+  test('a literal query token on a NEW target never reaches the store', async () => {
+    const { failure, stored, writes } = await run(hook({ url: `${AM}?token=${LITERAL}` }));
+    expect(failure).toContain("'url' ?token holds a literal credential");
+    expect(stored).not.toContain(LITERAL);
+    expect(writes).toEqual([]);
+  });
+
+  test('any other refusal on a new target also fails before the row is written', async () => {
+    const { failure, stored } = await run(hook({ comment: LITERAL, mailto: ['x@example.com'] }));
+    expect(failure).toContain("'mailto' belongs to sendmail/smtp targets, not webhook");
+    expect(stored).not.toContain(LITERAL);
+  });
+});

package/src/proxmox/credential-literals.ts

@@ -0,0 +1,74 @@
+/**
+ * A credential written as a LITERAL in a plain prop — refused, because a plain prop is a value in
+ * the state store.
+ *
+ * ⛔ THE HOLE THIS CLOSES, MEASURED 2026-09-22 (adversarial review of PR 95). write-only.ts keeps
+ *   every `{ fromEnv }` value out of state, and the doc WARNED that a plain header value is a prop.
+ *   A warning is not a guard: `header: { Authorization: 'Bearer <token>' }` planned, deployed, and
+ *   left the token in the dumped state store — and so did `url: 'https://…?token=<token>'`. Alchemy
+ *   stores props unencrypted (write-only.ts has the StateEncoding reading), so the only safe
+ *   literal is one that is not a credential.
+ *
+ * ★ WHAT COUNTS AS A CREDENTIAL IS A NAME, NOT A VALUE. A value cannot be recognised — a token is
+ *   any string — but where it sits can: an `Authorization`/`Cookie` header, a header or query
+ *   parameter whose name has a word like `token`, `key`, `secret`, `password` or `signature`, and a
+ *   password in the URL's userinfo. A false positive costs one edit (declare it `{ fromEnv }`, or
+ *   hold it in `secret` and write `{{ secrets.<name> }}`); a false negative costs a leaked token.
+ * ★ A TEMPLATE THAT READS A SECRET IS NOT A LITERAL. `Bearer {{ secrets.token }}`, and
+ *   `{{ url-encode secrets.token }}` in a query, render on PBS from the root-only secret store —
+ *   the prop holds the reference, not the value.
+ *
+ * ⚠️ WHAT THIS CANNOT SEE: a token in a URL PATH (a Slack-style `/services/T…/B…/<token>`), in the
+ *   `body`, or in a `comment`. Those are plain props too; put the token in `secret` and reference
+ *   it from the template. docs/pbs-notifications.md says the same to the reader.
+ * ⛔ A REFUSAL NAMES THE FIELD, NEVER THE VALUE — the message lands in a terminal and a CI log.
+ */
+import type { FromEnv } from './write-only.ts';
+
+/** `{{ secrets.x }}`, `{{secrets.x}}`, `{{ url-encode secrets.x }}` — a reference, not a value. */
+const READS_SECRET = /\{\{[^}]*\bsecrets\./;
+
+/** A whole-name match, or one dash/underscore-separated word of the name. */
+const CREDENTIAL_WORD =
+  /(^|[-_])(api[-_]?key|apikey|key|token|secret|password|passwd|pwd|pass|auth|signature|sig|code)($|[-_])/i;
+const CREDENTIAL_HEADER = /^(proxy-authorization|authorization|cookie)$/i;
+
+export const isCredentialName = (name: string): boolean =>
+  CREDENTIAL_HEADER.test(name) || CREDENTIAL_WORD.test(name);
+
+const literal = (value: string): boolean => value !== '' && !READS_SECRET.test(value);
+
+/** Plain header values that are credentials by their header's name. `{ fromEnv }` is never one. */
+export const literalCredentialHeaders = (
+  header: Readonly<Record<string, FromEnv | string>> | undefined,
+): string[] =>
+  Object.entries(header ?? {})
+    .filter(([name, value]) => typeof value === 'string' && isCredentialName(name))
+    .filter(([, value]) => literal(value as string))
+    .map(([name]) => name)
+    .sort();
+
+/**
+ * Where a URL carries a literal credential: `userinfo` (a password before the `@`), or the names
+ * of credential-shaped query (or fragment) parameters. Parsed by hand, not with `new URL`: a URL here is a
+ * TEMPLATE, and `{{ … }}` in the host or the userinfo is not a URL `new URL` will accept.
+ */
+export const literalCredentialsInUrl = (url: string | undefined): string[] => {
+  if (url === undefined) return [];
+  const out: string[] = [];
+  const authority = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i.exec(url)?.[1] ?? '';
+  const at = authority.lastIndexOf('@');
+  if (at >= 0) {
+    const userinfo = authority.slice(0, at);
+    const colon = userinfo.indexOf(':');
+    if (colon >= 0 && literal(userinfo.slice(colon + 1))) out.push('userinfo');
+  }
+  // ⚠️ THE FRAGMENT TOO: it is never sent, but it is still a prop — and so still in state.
+  const params = url.replace(/^[^?#]*/, '');
+  for (const pair of params.split(/[?&#]/)) {
+    const eq = pair.indexOf('=');
+    const name = eq < 0 ? pair : pair.slice(0, eq);
+    if (eq >= 0 && isCredentialName(name) && literal(pair.slice(eq + 1))) out.push(`?${name}`);
+  }
+  return out;
+};

package/src/proxmox/fake-pbs-notify.ts

@@ -0,0 +1,108 @@
+/**
+ * A PBS (or PVE) notification config that remembers writes — enough of proxmox-notify's CRUD for
+ * a family's REAL provider to create, drift, rotate and adopt through Alchemy's engine.
+ *
+ * ★ STATEFUL, UNLIKE `fakePve`'s bare answer function, because the questions here are about the
+ *   SECOND deploy: whether a rotated secret is written, whether an unchanged one is not. That needs
+ *   a server that holds what the first deploy wrote.
+ * ★ IT KEEPS proxmox-notify's TWO RULES THAT MATTER HERE (api/webhook.rs, read at HEAD 2026-09-22):
+ *     1. a read returns secret NAMES only; values live in a separate private store;
+ *     2. a PUT that carries `secret` REPLACES the list, a name without a value keeping the old
+ *        one; a PUT without `secret` leaves the list alone. `delete` entries clear a field.
+ *   Repeated form keys arrive as arrays, as the real urlencoded decoder builds them.
+ * ⛔ TEST-ONLY. No provider imports this file.
+ */
+import { type FakePve, type PveCall, fakePve } from './fake-pve.ts';
+import { keyAndValue } from './pbs-notification-target-wire.ts';
+
+/** Keys the servers take as `type: array`. Everything else is a scalar. */
+const LISTS = new Set([
+  'header',
+  'mailto',
+  'mailto-user',
+  'match-calendar',
+  'match-field',
+  'match-severity',
+  'secret',
+  'target',
+]);
+
+export interface FakeNotify extends FakePve {
+  /** Public config by path, as a GET would see it apart from secrets. Mutable, for drift. */
+  readonly objects: Map<string, Record<string, unknown>>;
+  /** Secret items with values (`name=…,value=<base64>`), by path — the root-only file. */
+  readonly secrets: Map<string, string[]>;
+}
+
+const body = (call: PveCall) => {
+  const fields: Record<string, unknown> = {};
+  const deletes: string[] = [];
+  for (const [key, value] of call.pairs) {
+    if (key === 'delete') deletes.push(value);
+    else if (LISTS.has(key))
+      fields[key] = [...((fields[key] as string[] | undefined) ?? []), value];
+    // ⚠️ Scalars as the server's JSON reads them back: a flag as a boolean, a port as a number.
+    else if (key === 'disable' || key === 'invert-match') fields[key] = value === '1';
+    else if (key === 'port') fields[key] = Number(value);
+    else fields[key] = value;
+  }
+  return { deletes, fields };
+};
+
+const withSecretsBlanked = (
+  path: string,
+  object: Record<string, unknown>,
+  secrets: FakeNotify['secrets'],
+) => {
+  const held = secrets.get(path);
+  return held === undefined || held.length === 0
+    ? object
+    : { ...object, secret: held.map((item) => `name=${keyAndValue(item).name}`) };
+};
+
+export const fakeNotify = (
+  seed: Readonly<Record<string, Record<string, unknown>>> = {},
+): FakeNotify => {
+  const objects = new Map(Object.entries(seed).map(([path, object]) => [path, { ...object }]));
+  const secrets = new Map<string, string[]>();
+
+  const putSecrets = (path: string, items: readonly string[]) => {
+    const old = secrets.get(path) ?? [];
+    const next = items.map((item) => {
+      const { name, value } = keyAndValue(item);
+      if (value !== undefined) return item;
+      const kept = old.find((existing) => keyAndValue(existing).name === name);
+      if (kept === undefined) throw new Error(`secret '${name}' not known`);
+      return kept;
+    });
+    secrets.set(path, next);
+  };
+
+  const fake = fakePve((call) => {
+    const path = call.path.split('?')[0] ?? call.path;
+    const { deletes, fields } = body(call);
+    if (call.method === 'GET') {
+      const object = objects.get(path);
+      return object === undefined ? undefined : withSecretsBlanked(path, object, secrets);
+    }
+    if (call.method === 'DELETE') {
+      objects.delete(path);
+      secrets.delete(path);
+      return undefined;
+    }
+    const target = call.method === 'POST' ? `${path}/${String(fields['name'])}` : path;
+    const { secret, ...rest } = fields as { secret?: string[] } & Record<string, unknown>;
+    const next: Record<string, unknown> = {
+      ...(call.method === 'PUT' ? objects.get(target) : {}),
+      ...rest,
+    };
+    for (const key of deletes) {
+      if (key === 'secret') secrets.delete(target);
+      else delete next[key];
+    }
+    objects.set(target, next);
+    if (secret !== undefined) putSecrets(target, secret);
+    return undefined;
+  });
+  return { ...fake, objects, secrets };
+};

package/src/proxmox/fake-pve.ts

@@ -28,6 +28,11 @@ export interface PveCall {
   /** Relative to `/api2/json/`, query included — the string a family passes to `pve()`. */
   readonly path: string;
   readonly form: Readonly<Record<string, string>>;
+  /**
+   * Every key/value pair in wire order. ⚠️ `form` keeps only the LAST value of a repeated key, and
+   * a PBS list IS a repeated key (client.ts `encode`) — assert a list on `pairs`, never `form`.
+   */
+  readonly pairs: readonly (readonly [string, string])[];
 }
 
 /** Answers one call with its `data`; `undefined` is PVE's `{"data": null}`. */
@@ -56,8 +61,13 @@ export const fakePve = (answer: PveAnswer): FakePve => {
       return Response.json({ data, lease_duration: 0 });
     }
     const path = `${url.pathname.replace(/^\/api2\/json\//, '')}${url.search}`;
-    const form = Object.fromEntries(new URLSearchParams(await request.text()));
-    const call = { form, method: request.method, path };
+    const params = new URLSearchParams(await request.text());
+    const call = {
+      form: Object.fromEntries(params),
+      method: request.method,
+      pairs: [...params],
+      path,
+    };
     calls.push(call);
     return Response.json({ data: answer(call) ?? null });
   };