@homeflare/alchemy 0.12.0 → 0.13.0

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 });
   };

package/src/proxmox/generated/pbs.ts

@@ -141,6 +141,335 @@ export type ConfigDatastoreNameDeleteParams = {
 /** DELETE /config/datastore/{name} — `data` payload after client unwrap. */
 export type ConfigDatastoreNameDeleteReturn = string;
 
+/** GET /config/notifications/endpoints — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsGetReturn = null;
+
+/** GET /config/notifications/endpoints/gotify — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsGotifyGetReturn = readonly {
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  filter?: string;
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  server: string;
+}[];
+
+/** POST /config/notifications/endpoints/gotify — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsGotifyPostParams = {
+  comment?: string;
+  disable?: '0' | '1';
+  filter?: string;
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  server: string;
+  token: string;
+};
+/** POST /config/notifications/endpoints/gotify — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsGotifyPostReturn = null;
+
+/** GET /config/notifications/endpoints/gotify/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsGotifyNameGetReturn = {
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  filter?: string;
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  server: string;
+};
+
+/** PUT /config/notifications/endpoints/gotify/{name} — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsGotifyNamePutParams = {
+  comment?: string;
+  delete?: readonly ('comment' | 'disable')[];
+  digest?: string;
+  disable?: '0' | '1';
+  server?: string;
+  token?: string;
+};
+/** PUT /config/notifications/endpoints/gotify/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsGotifyNamePutReturn = null;
+
+/** DELETE /config/notifications/endpoints/gotify/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsGotifyNameDeleteReturn = null;
+
+/** GET /config/notifications/endpoints/sendmail — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSendmailGetReturn = readonly {
+  author?: string;
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  filter?: string;
+  'from-address'?: string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+}[];
+
+/** POST /config/notifications/endpoints/sendmail — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsSendmailPostParams = {
+  author?: string;
+  comment?: string;
+  disable?: '0' | '1';
+  filter?: string;
+  'from-address'?: string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+};
+/** POST /config/notifications/endpoints/sendmail — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSendmailPostReturn = null;
+
+/** GET /config/notifications/endpoints/sendmail/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSendmailNameGetReturn = {
+  author?: string;
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  filter?: string;
+  'from-address'?: string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+};
+
+/** PUT /config/notifications/endpoints/sendmail/{name} — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsSendmailNamePutParams = {
+  author?: string;
+  comment?: string;
+  delete?: readonly (
+    | 'author'
+    | 'comment'
+    | 'disable'
+    | 'from-address'
+    | 'mailto'
+    | 'mailto-user'
+  )[];
+  digest?: string;
+  disable?: '0' | '1';
+  'from-address'?: string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+};
+/** PUT /config/notifications/endpoints/sendmail/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSendmailNamePutReturn = null;
+
+/** DELETE /config/notifications/endpoints/sendmail/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSendmailNameDeleteReturn = null;
+
+/** GET /config/notifications/endpoints/smtp — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSmtpGetReturn = readonly {
+  author?: string;
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  'from-address': string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  mode?: 'insecure' | 'starttls' | 'tls';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  port?: number;
+  server: string;
+  username?: string;
+}[];
+
+/** POST /config/notifications/endpoints/smtp — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsSmtpPostParams = {
+  author?: string;
+  comment?: string;
+  disable?: '0' | '1';
+  'from-address': string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  mode?: 'insecure' | 'starttls' | 'tls';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  password?: string;
+  port?: string;
+  server: string;
+  username?: string;
+};
+/** POST /config/notifications/endpoints/smtp — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSmtpPostReturn = null;
+
+/** GET /config/notifications/endpoints/smtp/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSmtpNameGetReturn = {
+  author?: string;
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  'from-address': string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  mode?: 'insecure' | 'starttls' | 'tls';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  port?: number;
+  server: string;
+  username?: string;
+};
+
+/** PUT /config/notifications/endpoints/smtp/{name} — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsSmtpNamePutParams = {
+  author?: string;
+  comment?: string;
+  delete?: readonly (
+    | 'author'
+    | 'comment'
+    | 'disable'
+    | 'mailto'
+    | 'mailto-user'
+    | 'password'
+    | 'port'
+    | 'username'
+  )[];
+  digest?: string;
+  disable?: '0' | '1';
+  'from-address'?: string;
+  mailto?: readonly string[];
+  'mailto-user'?: readonly string[];
+  mode?: 'insecure' | 'starttls' | 'tls';
+  password?: string;
+  port?: string;
+  server?: string;
+  username?: string;
+};
+/** PUT /config/notifications/endpoints/smtp/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSmtpNamePutReturn = null;
+
+/** DELETE /config/notifications/endpoints/smtp/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsSmtpNameDeleteReturn = null;
+
+/** GET /config/notifications/endpoints/webhook — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsWebhookGetReturn = readonly {
+  body?: string;
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  header?: readonly string[];
+  method: 'post' | 'put' | 'get';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  secret?: readonly string[];
+  url: string;
+}[];
+
+/** POST /config/notifications/endpoints/webhook — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsWebhookPostParams = {
+  body?: string;
+  comment?: string;
+  disable?: '0' | '1';
+  header?: readonly string[];
+  method: 'post' | 'put' | 'get';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  secret?: readonly string[];
+  url: string;
+};
+/** POST /config/notifications/endpoints/webhook — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsWebhookPostReturn = null;
+
+/** GET /config/notifications/endpoints/webhook/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsWebhookNameGetReturn = {
+  body?: string;
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  header?: readonly string[];
+  method: 'post' | 'put' | 'get';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  secret?: readonly string[];
+  url: string;
+};
+
+/** PUT /config/notifications/endpoints/webhook/{name} — form/query parameters (path segments omitted). */
+export type ConfigNotificationsEndpointsWebhookNamePutParams = {
+  body?: string;
+  comment?: string;
+  delete?: readonly ('comment' | 'disable' | 'header' | 'body' | 'secret')[];
+  digest?: string;
+  disable?: '0' | '1';
+  header?: readonly string[];
+  method?: 'post' | 'put' | 'get';
+  secret?: readonly string[];
+  url?: string;
+};
+/** PUT /config/notifications/endpoints/webhook/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsWebhookNamePutReturn = null;
+
+/** DELETE /config/notifications/endpoints/webhook/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsEndpointsWebhookNameDeleteReturn = null;
+
+/** GET /config/notifications/matchers — `data` payload after client unwrap. */
+export type ConfigNotificationsMatchersGetReturn = readonly {
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  'invert-match'?: boolean | 0 | 1;
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  target?: readonly string[];
+}[];
+
+/** POST /config/notifications/matchers — form/query parameters (path segments omitted). */
+export type ConfigNotificationsMatchersPostParams = {
+  comment?: string;
+  disable?: '0' | '1';
+  'invert-match'?: '0' | '1';
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  target?: readonly string[];
+};
+/** POST /config/notifications/matchers — `data` payload after client unwrap. */
+export type ConfigNotificationsMatchersPostReturn = null;
+
+/** GET /config/notifications/matchers/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsMatchersNameGetReturn = {
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  'invert-match'?: boolean | 0 | 1;
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  name: string;
+  origin?: 'user-created' | 'builtin' | 'modified-builtin';
+  target?: readonly string[];
+};
+
+/** PUT /config/notifications/matchers/{name} — form/query parameters (path segments omitted). */
+export type ConfigNotificationsMatchersNamePutParams = {
+  comment?: string;
+  delete?: readonly (
+    | 'comment'
+    | 'disable'
+    | 'invert-match'
+    | 'match-calendar'
+    | 'match-field'
+    | 'match-severity'
+    | 'mode'
+    | 'target'
+  )[];
+  digest?: string;
+  disable?: '0' | '1';
+  'invert-match'?: '0' | '1';
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  target?: readonly string[];
+};
+/** PUT /config/notifications/matchers/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsMatchersNamePutReturn = null;
+
+/** DELETE /config/notifications/matchers/{name} — `data` payload after client unwrap. */
+export type ConfigNotificationsMatchersNameDeleteReturn = null;
+
 /** GET /config/prune — `data` payload after client unwrap. */
 export type ConfigPruneGetReturn = readonly {
   comment?: string;

package/src/proxmox/generated/pve.ts

@@ -375,6 +375,68 @@ export type ClusterNotificationsEndpointsWebhookNamePutReturn = null;
 /** DELETE /cluster/notifications/endpoints/webhook/{name} — `data` payload after client unwrap. */
 export type ClusterNotificationsEndpointsWebhookNameDeleteReturn = null;
 
+/** GET /cluster/notifications/matchers — `data` payload after client unwrap. */
+export type ClusterNotificationsMatchersGetReturn = readonly ({
+  comment?: string;
+  disable?: boolean | 0 | 1;
+  'invert-match'?: boolean | 0 | 1;
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  name: string;
+  origin: 'user-created' | 'builtin' | 'modified-builtin';
+  target?: readonly string[];
+} & Record<string, unknown>)[];
+
+/** POST /cluster/notifications/matchers — form/query parameters (path segments omitted). */
+export type ClusterNotificationsMatchersPostParams = {
+  comment?: string;
+  disable?: '0' | '1';
+  'invert-match'?: '0' | '1';
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  name: string;
+  target?: readonly string[];
+};
+/** POST /cluster/notifications/matchers — `data` payload after client unwrap. */
+export type ClusterNotificationsMatchersPostReturn = null;
+
+/** GET /cluster/notifications/matchers/{name} — `data` payload after client unwrap. */
+export type ClusterNotificationsMatchersNameGetReturn = {
+  comment?: string;
+  digest?: string;
+  disable?: boolean | 0 | 1;
+  'invert-match'?: boolean | 0 | 1;
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  name: string;
+  target?: readonly string[];
+} & Record<string, unknown>;
+
+/** PUT /cluster/notifications/matchers/{name} — form/query parameters (path segments omitted). */
+export type ClusterNotificationsMatchersNamePutParams = {
+  comment?: string;
+  delete?: readonly string[];
+  digest?: string;
+  disable?: '0' | '1';
+  'invert-match'?: '0' | '1';
+  'match-calendar'?: readonly string[];
+  'match-field'?: readonly string[];
+  'match-severity'?: readonly string[];
+  mode?: 'all' | 'any';
+  target?: readonly string[];
+};
+/** PUT /cluster/notifications/matchers/{name} — `data` payload after client unwrap. */
+export type ClusterNotificationsMatchersNamePutReturn = null;
+
+/** DELETE /cluster/notifications/matchers/{name} — `data` payload after client unwrap. */
+export type ClusterNotificationsMatchersNameDeleteReturn = null;
+
 /** GET /cluster/firewall/aliases — `data` payload after client unwrap. */
 export type ClusterFirewallAliasesGetReturn = readonly ({
   cidr: string;

package/src/proxmox/index.test.ts

@@ -12,6 +12,8 @@ const src = await Bun.file(new URL('./index.ts', import.meta.url)).text();
 
 const resourceExports = [
   'PbsDatastore',
+  'PbsNotificationMatcher',
+  'PbsNotificationTarget',
   'PbsPruneJob',
   'PbsSyncJob',
   'PbsVerifyJob',
@@ -22,6 +24,7 @@ const resourceExports = [
   'ProxmoxHaRule',
   'ProxmoxLxc',
   'ProxmoxMetricServer',
+  'ProxmoxNotificationMatcher',
   'ProxmoxNotificationTarget',
   'ProxmoxRole',
   'ProxmoxSdnApply',

package/src/proxmox/index.ts

@@ -15,10 +15,14 @@
  * ★ THE PROVISIONING BASELINE JOINED 2026-09-21: one privilege list (`PROVISION_PRIVILEGES`), the
  *   helper that declares it (`declareProvisionBaseline`) and the pure generator of the one-time
  *   root commands that bootstrap it (`provisionBootstrap`) — docs/provision-baseline.md.
+ * ★ THE NOTIFICATION FAMILIES JOINED 2026-09-22: PBS targets and matchers, the PVE matcher, the
+ *   `FromEnv` shape their write-only values take, and the Alertmanager body template
+ *   (docs/pbs-notifications.md; the template alone: docs/pbs-alertmanager-body.md).
  * ★ Anything else unlisted is still reachable by path if you genuinely need
  *   it — that is a deliberate, visible act rather than an accident of barrelling.
  */
 export { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
+export { type AlertmanagerBodyOptions, alertmanagerAlertBody } from './alertmanager-body.ts';
 export { ProxmoxApiTokenProvider } from './api-token.ts';
 export { ProxmoxBackupJob, ProxmoxBackupJobProvider } from './backup-job.ts';
 export { ProxmoxCephDaemonProvider } from './ceph-daemon.ts';
@@ -34,11 +38,24 @@ export { type LxcAttributes, type LxcProps, ProxmoxLxc, ProxmoxLxcProvider } fro
 export { ProxmoxMetricServer, ProxmoxMetricServerProvider } from './metric-server.ts';
 export { ProxmoxNetworkApplyProvider } from './network-apply.ts';
 export { ProxmoxNodeNetworkProvider } from './node-network.ts';
+export {
+  ProxmoxNotificationMatcher,
+  ProxmoxNotificationMatcherProvider,
+} from './notification-matcher.ts';
 export {
   ProxmoxNotificationTarget,
   ProxmoxNotificationTargetProvider,
 } from './notification-target.ts';
 export { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
+export {
+  PbsNotificationMatcher,
+  PbsNotificationMatcherProvider,
+} from './pbs-notification-matcher.ts';
+export {
+  PbsNotificationTarget,
+  PbsNotificationTargetProvider,
+  type PbsNotificationTargetProps,
+} from './pbs-notification-target.ts';
 export { PbsPruneJob, PbsPruneJobProvider } from './pbs-prune-job.ts';
 export { PbsSyncJob, PbsSyncJobProvider } from './pbs-sync-job.ts';
 export { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
@@ -63,4 +80,5 @@ export { ProxmoxSdnVnet, ProxmoxSdnVnetProvider } from './sdn-vnet.ts';
 export { ProxmoxSdnZone, ProxmoxSdnZoneProvider } from './sdn-zone.ts';
 export { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
 export { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
+export { type FromEnv } from './write-only.ts';
 export { ProxmoxZfsPoolProvider } from './zfs-pool.ts';