@homeflare/alchemy 0.11.0 → 0.13.0

package/src/proxmox/pbs-notification-target-state.test.ts

@@ -0,0 +1,191 @@
+/**
+ * `Pbs.NotificationTarget` through Alchemy's own Plan and Apply, over a PBS that remembers writes
+ * (fake-pbs-notify.ts) — the write-only contract, end to end.
+ *
+ * ★ WHAT IS PINNED, AND WHERE A REGRESSION WOULD LEAK:
+ *   - the secret, the password and a `fromEnv` header reach the WIRE and never the STATE STORE
+ *     (the store is dumped as JSON and searched, raw and base64);
+ *   - a rotated value is found by the seal and written, and ONLY its group is written;
+ *   - a plan without the variables is presence-only: noop, not a guess;
+ *   - a write that needs a missing variable fails by the variable's NAME, before any request;
+ *   - adopting a webhook that already has secrets writes nothing.
+ */
+import { afterEach, 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 { fakeNotify } from './fake-pbs-notify.ts';
+import { withoutBao } from './fake-pve.ts';
+import {
+  PbsNotificationTarget,
+  type PbsNotificationTargetProps,
+  PbsNotificationTargetProvider,
+} from './pbs-notification-target.ts';
+import { keyAndValue, unbase64 } from './pbs-notification-target-wire.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const PATH = 'config/notifications/endpoints/webhook/alertmanager';
+const FIRST = 'tok-1111-not-real';
+const SECOND = 'tok-2222-not-real';
+const HEADER = 'hdr-3333-not-real';
+
+const hook = (over: Partial<PbsNotificationTargetProps> = {}) =>
+  PbsNotificationTarget('alertmanager', {
+    body: '[{"labels": {"alertname": "x"}}]',
+    header: { 'Content-Type': 'application/json', 'X-Scope': { fromEnv: 'HF_TEST_HEADER' } },
+    method: 'post',
+    name: 'alertmanager',
+    secret: { token: { fromEnv: 'HF_TEST_TOKEN' } },
+    target: PBS,
+    type: 'webhook',
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+    ...over,
+  });
+
+const setEnv = (values: Record<string, string | undefined>) => {
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+};
+
+afterEach(() => setEnv({ HF_TEST_HEADER: undefined, HF_TEST_TOKEN: undefined }));
+
+const engineFor = (fake: ReturnType<typeof fakeNotify>) =>
+  engineOver(PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)));
+
+const leaks = (stored: string, values: readonly string[]) =>
+  values.filter((v) => stored.includes(v) || stored.includes(Buffer.from(v).toString('base64')));
+
+const verifyDiff = async (engine: ReturnType<typeof engineFor>, body = hook()) =>
+  (await engine.verify(body, { all: true })).rows[0]?.diff;
+
+describe('a webhook created with write-only values', () => {
+  test('sends them, stores none of them, and plans noop again', async () => {
+    setEnv({ HF_TEST_HEADER: HEADER, HF_TEST_TOKEN: FIRST });
+    const fake = fakeNotify();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(hook());
+      expect(leaks(engine.stored(), [FIRST, HEADER])).toEqual([]);
+      expect(engine.stored()).toContain('HF_TEST_TOKEN');
+      expect(await verifyDiff(engine)).toBe('noop');
+      await engine.deploy(hook());
+    });
+    expect(fake.writes()).toEqual(['POST config/notifications/endpoints/webhook']);
+    const held = (fake.secrets.get(PATH) ?? []).map(keyAndValue);
+    expect(held.map((s) => [s.name, unbase64(s.value ?? '')])).toEqual([['token', FIRST]]);
+  });
+
+  test('a rotated secret is found by the seal and PUT alone — headers are not resent', async () => {
+    setEnv({ HF_TEST_HEADER: HEADER, HF_TEST_TOKEN: FIRST });
+    const fake = fakeNotify();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(hook());
+      setEnv({ HF_TEST_TOKEN: SECOND });
+      expect(await verifyDiff(engine)).toBe('update');
+      await engine.deploy(hook());
+      expect(leaks(engine.stored(), [FIRST, SECOND, HEADER])).toEqual([]);
+      expect(await verifyDiff(engine)).toBe('noop');
+    });
+    const put = fake.calls.filter((call) => call.method === 'PUT');
+    expect(put).toHaveLength(1);
+    expect(put[0]?.pairs.map(([key]) => key)).toContain('secret');
+    expect(put[0]?.pairs.map(([key]) => key)).not.toContain('header');
+    expect(unbase64(keyAndValue(fake.secrets.get(PATH)?.[0] ?? '').value ?? '')).toBe(SECOND);
+  });
+
+  test('a header changed on the server is drift, found by digest, repaired from the env', async () => {
+    setEnv({ HF_TEST_HEADER: HEADER, HF_TEST_TOKEN: FIRST });
+    const fake = fakeNotify();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(hook());
+      const object = fake.objects.get(PATH) ?? {};
+      const edited = `name=X-Scope,value=${Buffer.from('edited-by-hand').toString('base64')}`;
+      fake.objects.set(PATH, { ...object, header: [(object['header'] as string[])[0], edited] });
+      expect(await verifyDiff(engine)).toBe('update');
+      await engine.deploy(hook());
+      expect(leaks(engine.stored(), [HEADER, 'edited-by-hand'])).toEqual([]);
+    });
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.pairs.map(([key]) => key)).toContain('header');
+    expect(put?.pairs.map(([key]) => key)).not.toContain('secret');
+  });
+});
+
+describe('without the variables', () => {
+  test('a plan is presence-only: noop, and a deploy writes nothing', async () => {
+    setEnv({ HF_TEST_HEADER: HEADER, HF_TEST_TOKEN: FIRST });
+    const fake = fakeNotify();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(hook());
+      setEnv({ HF_TEST_HEADER: undefined, HF_TEST_TOKEN: undefined });
+      expect(await verifyDiff(engine)).toBe('noop');
+      await engine.deploy(hook());
+    });
+    expect(fake.writes()).toEqual(['POST config/notifications/endpoints/webhook']);
+  });
+
+  test('a comment change is still written — without the write-only groups, which the server keeps', async () => {
+    setEnv({ HF_TEST_HEADER: HEADER, HF_TEST_TOKEN: FIRST });
+    const fake = fakeNotify();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(hook());
+      setEnv({ HF_TEST_HEADER: undefined, HF_TEST_TOKEN: undefined });
+      await engine.deploy(hook({ comment: 'pager' }));
+    });
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.pairs.map(([key]) => key).sort()).toEqual([
+      'body',
+      'comment',
+      'disable',
+      'method',
+      'url',
+    ]);
+    expect(unbase64(keyAndValue(fake.secrets.get(PATH)?.[0] ?? '').value ?? '')).toBe(FIRST);
+  });
+
+  test('a write that needs a missing value fails by variable name, before any request', async () => {
+    const fake = fakeNotify();
+    let failure = '';
+    await withoutBao(async () => {
+      await engineFor(fake)
+        .deploy(hook())
+        .catch((error: unknown) => {
+          failure = String(error);
+        });
+    });
+    expect(failure).toContain('HF_TEST_HEADER, HF_TEST_TOKEN');
+    expect(fake.writes()).toEqual([]);
+  });
+});
+
+describe('adopting a webhook that already holds secrets', () => {
+  test('reads only: names match, values are unknown, nothing is written', async () => {
+    setEnv({ HF_TEST_HEADER: HEADER, HF_TEST_TOKEN: FIRST });
+    const fake = fakeNotify({
+      [PATH]: {
+        body: Buffer.from('[{"labels": {"alertname": "x"}}]').toString('base64'),
+        header: [
+          `name=Content-Type,value=${Buffer.from('application/json').toString('base64')}`,
+          `name=X-Scope,value=${Buffer.from(HEADER).toString('base64')}`,
+        ],
+        method: 'post',
+        name: 'alertmanager',
+        url: 'https://alertmanager.example.com/api/v2/alerts',
+      },
+    });
+    fake.secrets.set(PATH, [`name=token,value=${Buffer.from('set-by-hand').toString('base64')}`]);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      expect((await engine.verify(hook())).rows[0]).toMatchObject({ diff: 'noop', ok: true });
+      await engine.deploy(hook());
+      expect(leaks(engine.stored(), [HEADER, 'set-by-hand', FIRST])).toEqual([]);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+});

package/src/proxmox/pbs-notification-target-wire.ts

@@ -0,0 +1,112 @@
+/**
+ * How a PBS notification target looks on the wire, and what of it may be remembered.
+ *
+ * ★ SPLIT OUT OF pbs-notification-target.ts FOR THE 250-LINE CAP, on the seam
+ *   notification-target-form.ts cut for PVE: the resource file says what a target IS and when it
+ *   changed; this file turns a live answer into attributes and a value into a wire item. The
+ *   `import type` back is erased, so the cycle is on paper only.
+ *
+ * ⛔ THE LIVE ANSWER HOLDS HEADER VALUES, AND NONE OF THEM REACHES AN ATTRIBUTE. PBS returns a
+ *   webhook's headers in full — `name=Authorization,value=<base64>` — to anyone with Sys.Audit on
+ *   /system/notifications (proxmox-notify api/webhook.rs `get_endpoint`, read at HEAD 2026-09-22).
+ *   Copying them into attributes would copy whatever a human pasted into a header, a bearer token
+ *   included, into the unencrypted state store. So attributes keep header NAMES and a fixed-salt
+ *   scrypt digest of the pairs (write-only.ts), enough to notice a change and nothing to send.
+ * ⚠️ SECRETS ARE SAFER ON THE SERVER, AND THE READ SHOWS IT: `get_endpoint` blanks every secret's
+ *   value and returns names only, from a root-only `notifications-priv.cfg`. A credential belongs
+ *   in `secret` and is referenced as `{{ secrets.<name> }}` from a header, the URL or the body.
+ */
+import { Buffer } from 'node:buffer';
+import { addressList, portOf } from './notification-target-form.ts';
+import type {
+  PbsNotificationTargetAttributes,
+  PbsNotificationTargetProps,
+} from './pbs-notification-target.ts';
+import { bool, text } from './values.ts';
+import { seal } from './write-only.ts';
+
+export const base64 = (value: string): string => Buffer.from(value, 'utf8').toString('base64');
+
+/** ⚠️ Node's decoder skips characters it does not know rather than throwing, so this never throws. */
+export const unbase64 = (value: string): string => Buffer.from(value, 'base64').toString('utf8');
+
+/**
+ * One `KeyAndBase64Val` property string — `name=<name>,value=<base64>` — split into its halves.
+ * ⚠️ KEYED BY NAME, NOT BY POSITION: the server serialises `name` first today, and a parser that
+ *   relied on that would read a reordered item as a header called `value=…`.
+ * ★ A comma cannot occur inside either half: base64 has none, and `refusals` keeps names clean.
+ */
+export const keyAndValue = (item: string): { name: string; value?: string } => {
+  const parts: Record<string, string> = {};
+  for (const part of item.split(',')) {
+    const at = part.indexOf('=');
+    if (at > 0) parts[part.slice(0, at).trim()] = part.slice(at + 1).trim();
+  }
+  const value = parts['value'];
+  return value === undefined ? { name: parts['name'] ?? '' } : { name: parts['name'] ?? '', value };
+};
+
+/** The wire item for one header or secret. The value is base64 — the server decodes it to use it. */
+export const wireItem = (name: string, value: string): string =>
+  `name=${name},value=${base64(value)}`;
+
+const list = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.map((item: unknown) => String(item)) : [];
+
+/** Sorted, comma-joined names — presence, the only thing the store may know about the values. */
+export const names = (keys: readonly string[]): string =>
+  [...keys]
+    .filter((key) => key !== '')
+    .sort()
+    .join(',');
+
+/**
+ * ★ A FIXED SALT PER TARGET, SO AN UNCHANGED HEADER SET DIGESTS THE SAME ON EVERY READ. A random
+ *   one would rewrite the state row on every plan. The server shows these values to its auditors
+ *   anyway; what the salt and scrypt buy is that the STORE does not become a second, weaker copy.
+ */
+export const headerDigest = (target: string, pairs: Readonly<Record<string, string>>): string =>
+  seal(pairs, `hf:pbs-notification-target:${target}:header`);
+
+/**
+ * Live JSON to attributes. `sealed` is left empty here: it is not the server's to report, and the
+ * handlers in pbs-notification-target.ts carry it forward from the previous state.
+ */
+export const targetAttributes = (
+  live: Record<string, unknown>,
+  props: PbsNotificationTargetProps,
+): PbsNotificationTargetAttributes => {
+  const headers: Record<string, string> = {};
+  for (const item of list(live['header'])) {
+    const { name, value } = keyAndValue(item);
+    if (name !== '') headers[name] = unbase64(value ?? '');
+  }
+  const secrets = list(live['secret']).map((item) => keyAndValue(item).name);
+  return {
+    author: text(live['author']),
+    // ⚠️ DECODED, unlike the PVE family's: the server stores exactly the base64 it was handed and
+    //   decodes it to render (endpoints/webhook.rs `build_request`), so decoding here is a pure
+    //   function of what was written and `matches` compares readable text rather than base64.
+    body: unbase64(text(live['body'])),
+    comment: text(live['comment']),
+    disable: bool(live['disable']),
+    'from-address': text(live['from-address']),
+    header: names(Object.keys(headers)),
+    headerDigest: headerDigest(props.name, headers),
+    mailto: addressList(live['mailto']),
+    'mailto-user': addressList(live['mailto-user']),
+    method: text(live['method']),
+    mode: text(live['mode']),
+    name: props.name,
+    // ★ ON THE PER-OBJECT READ, MEASURED on PBS 4.2 (`notification endpoint sendmail show
+    //   mail-to-root` answers `origin: builtin`). Reported, never compared.
+    origin: text(live['origin']),
+    port: portOf(live['port']),
+    secret: names(secrets),
+    sealed: '',
+    server: text(live['server']),
+    type: props.type,
+    url: text(live['url']),
+    username: text(live['username']),
+  };
+};

package/src/proxmox/pbs-notification-target.test.ts

@@ -0,0 +1,226 @@
+/**
+ * `Pbs.NotificationTarget` — refusals, the wire forms against the generated PBS schema, and the
+ * rule that no header or secret VALUE reaches an attribute.
+ *
+ * ⚠️ THE DRIFT CHECK IS A TYPED KEY LIST PER FAMILY. `targetForm` builds one flat body for three
+ *   families, so it cannot be typed as any one of them; instead each list below `satisfies` the
+ *   generated parameter keys (and each `delete` value the generated enum), and every form this file
+ *   builds is asserted to stay inside its list. A renamed parameter fails `tsc` on the list.
+ */
+import { describe, expect, test } from 'bun:test';
+import type {
+  ConfigNotificationsEndpointsSendmailNamePutParams,
+  ConfigNotificationsEndpointsSmtpPostParams,
+  ConfigNotificationsEndpointsWebhookNamePutParams,
+  ConfigNotificationsEndpointsWebhookPostParams,
+} from './generated/pbs.ts';
+import type { PbsTarget } from './credentials.ts';
+import type { PbsNotificationTargetProps } from './pbs-notification-target.ts';
+import { refusals, resolveGroups, targetForm } from './pbs-notification-target-form.ts';
+import { keyAndValue, targetAttributes, unbase64 } from './pbs-notification-target-wire.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const TOKEN = 'tok-5f0c1d2e-not-real';
+const ENV = { HOOK_TOKEN: TOKEN, SMTP_PASSWORD: 'pw-not-real' };
+
+const WEBHOOK_POST = [
+  'body',
+  'comment',
+  'disable',
+  'header',
+  'method',
+  'name',
+  'secret',
+  'url',
+] as const satisfies readonly (keyof ConfigNotificationsEndpointsWebhookPostParams)[];
+const WEBHOOK_PUT = [
+  'body',
+  'comment',
+  'delete',
+  'disable',
+  'header',
+  'method',
+  'secret',
+  'url',
+] as const satisfies readonly (keyof ConfigNotificationsEndpointsWebhookNamePutParams)[];
+const WEBHOOK_DELETE = [
+  'body',
+  'comment',
+  'header',
+  'secret',
+] as const satisfies readonly NonNullable<
+  ConfigNotificationsEndpointsWebhookNamePutParams['delete']
+>[number][];
+const SMTP_POST = [
+  'author',
+  'comment',
+  'disable',
+  'from-address',
+  'mailto',
+  'mailto-user',
+  'mode',
+  'name',
+  'password',
+  'port',
+  'server',
+  'username',
+] as const satisfies readonly (keyof ConfigNotificationsEndpointsSmtpPostParams)[];
+const SENDMAIL_DELETE = [
+  'author',
+  'comment',
+  'from-address',
+  'mailto',
+  'mailto-user',
+] as const satisfies readonly NonNullable<
+  ConfigNotificationsEndpointsSendmailNamePutParams['delete']
+>[number][];
+
+const webhook = (over: Partial<PbsNotificationTargetProps> = {}): PbsNotificationTargetProps => ({
+  body: '{"text": {{ json title }}}',
+  header: { Authorization: 'Bearer {{ secrets.token }}', 'Content-Type': 'application/json' },
+  method: 'post',
+  name: 'alertmanager',
+  secret: { token: { fromEnv: 'HOOK_TOKEN' } },
+  target: PBS,
+  type: 'webhook',
+  url: 'https://alertmanager.example.com/api/v2/alerts',
+  ...over,
+});
+
+const all = { header: true, sealed: true } as const;
+const keysOf = (form: object) => Object.keys(form).sort();
+
+describe('refusals, at plan, by field name', () => {
+  test('a field outside its family, a missing required field, a name that breaks the wire', () => {
+    expect(refusals(webhook())).toEqual([]);
+    expect(refusals({ name: 'm', target: PBS, type: 'sendmail', url: 'https://x.test' })).toEqual([
+      "'url' belongs to webhook targets, not sendmail",
+    ]);
+    expect(refusals(webhook({ url: undefined as never }))).toContain("webhook needs 'url'");
+    expect(refusals({ name: 's', server: 'mx.test', target: PBS, type: 'smtp' })).toEqual([
+      "smtp needs 'from-address'",
+    ]);
+    expect(refusals(webhook({ header: { 'X-A,b': 'v' } }))).toEqual([
+      "'X-A,b' cannot be a header or secret name",
+    ]);
+  });
+});
+
+describe('webhook forms', () => {
+  const groups = resolveGroups(webhook(), ENV);
+
+  test('a create carries base64 body, header and secret items, and stays inside the schema', () => {
+    const form = targetForm(webhook(), groups, all, 'create');
+    expect(keysOf(form).every((key) => (WEBHOOK_POST as readonly string[]).includes(key))).toBe(
+      true,
+    );
+    expect(unbase64(String(form['body']))).toBe('{"text": {{ json title }}}');
+    const secret = (form['secret'] as readonly string[]).map(keyAndValue);
+    expect(secret).toEqual([{ name: 'token', value: Buffer.from(TOKEN).toString('base64') }]);
+    const headers = (form['header'] as readonly string[]).map(keyAndValue);
+    expect(headers.map((h) => [h.name, unbase64(h.value ?? '')])).toEqual([
+      ['Authorization', 'Bearer {{ secrets.token }}'],
+      ['Content-Type', 'application/json'],
+    ]);
+    expect(form['disable']).toBe('0');
+  });
+
+  test('an update carries only the groups it was told to — omitted means "keep"', () => {
+    const form = targetForm(
+      webhook({ comment: 'x' }),
+      groups,
+      { header: false, sealed: false },
+      'update',
+    );
+    expect(keysOf(form)).toEqual(['body', 'comment', 'disable', 'method', 'url']);
+    expect(keysOf(form).every((key) => (WEBHOOK_PUT as readonly string[]).includes(key))).toBe(
+      true,
+    );
+  });
+
+  test('clearing is a `delete` inside the generated enum', () => {
+    const cleared = webhook({ body: '', comment: '', header: {}, secret: {} });
+    const form = targetForm(cleared, resolveGroups(cleared, ENV), all, 'update');
+    expect(form['delete']).toEqual(['body', 'comment', 'header', 'secret']);
+    expect(
+      (form['delete'] as readonly string[]).every((d) =>
+        (WEBHOOK_DELETE as readonly string[]).includes(d),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('mail forms', () => {
+  test('smtp: recipients sorted, password sent only when its group is carried', () => {
+    const smtp: PbsNotificationTargetProps = {
+      'from-address': 'pbs@example.com',
+      mailto: ['b@example.com', 'a@example.com'],
+      name: 'relay',
+      password: { fromEnv: 'SMTP_PASSWORD' },
+      server: 'mx.example.com',
+      target: PBS,
+      type: 'smtp',
+      username: 'pbs',
+    };
+    const groups = resolveGroups(smtp, ENV);
+    const create = targetForm(smtp, groups, all, 'create');
+    expect(create['mailto']).toEqual(['a@example.com', 'b@example.com']);
+    expect(create['password']).toBe('pw-not-real');
+    expect(keysOf(create).every((key) => (SMTP_POST as readonly string[]).includes(key))).toBe(
+      true,
+    );
+    expect(
+      targetForm(smtp, groups, { header: false, sealed: false }, 'update')['password'],
+    ).toBeUndefined();
+  });
+
+  test('sendmail: an emptied list and an empty from-address clear, inside the enum', () => {
+    const sendmail: PbsNotificationTargetProps = {
+      'from-address': '',
+      mailto: [],
+      name: 'mail-to-root',
+      target: PBS,
+      type: 'sendmail',
+    };
+    const form = targetForm(sendmail, resolveGroups(sendmail, ENV), all, 'update');
+    expect(form['delete']).toEqual(['from-address', 'mailto']);
+    expect(
+      (form['delete'] as readonly string[]).every((d) =>
+        (SENDMAIL_DELETE as readonly string[]).includes(d),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('attributes', () => {
+  const live = {
+    body: Buffer.from('{}').toString('base64'),
+    header: [`name=Authorization,value=${Buffer.from(`Bearer ${TOKEN}`).toString('base64')}`],
+    method: 'post',
+    name: 'alertmanager',
+    origin: 'user-created',
+    secret: ['name=token'],
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+  };
+
+  test('keep header and secret NAMES and a digest — never a value, raw or base64', () => {
+    const attributes = targetAttributes(live, webhook());
+    expect(attributes.header).toBe('Authorization');
+    expect(attributes.secret).toBe('token');
+    expect(attributes.headerDigest).toStartWith('scrypt:');
+    const text = JSON.stringify(attributes);
+    expect(text).not.toContain(TOKEN);
+    expect(text).not.toContain(Buffer.from(`Bearer ${TOKEN}`).toString('base64'));
+    expect(attributes.body).toBe('{}');
+  });
+
+  test('the header digest is stable across reads and moves with the value', () => {
+    const again = targetAttributes(live, webhook());
+    expect(again.headerDigest).toBe(targetAttributes(live, webhook()).headerDigest);
+    const other = {
+      ...live,
+      header: [`name=Authorization,value=${Buffer.from('Bearer other').toString('base64')}`],
+    };
+    expect(targetAttributes(other, webhook()).headerDigest).not.toBe(again.headerDigest);
+  });
+});

package/src/proxmox/pbs-notification-target.ts

@@ -0,0 +1,139 @@
+/**
+ * `Pbs.NotificationTarget` — where a Proxmox Backup Server sends a notification: a `webhook`, or
+ * mail through `sendmail` or `smtp`.
+ *
+ * ★ THE WEBHOOK IS THE POINT. A failed verify, sync or garbage collection reaches a human through a
+ *   target a matcher names (pbs-notification-matcher.ts). Out of the box that is `mail-to-root`,
+ *   one mailbox on one host; a webhook can post an Alertmanager alert instead, and then the failure
+ *   pages like everything else. docs/pbs-alertmanager-body.md has the body template.
+ *
+ * ⛔ SECRETS ARE DECLARED BY THE NAME OF AN ENVIRONMENT VARIABLE, NEVER BY VALUE, and NO VALUE EVER
+ *   REACHES STATE — not as a prop, not as an attribute. write-only.ts has the whole argument; the
+ *   short form: Alchemy stores props and attributes unencrypted, so `secret`, `password` and any
+ *   header holding a credential take `{ fromEnv: 'NAME' }`, read by the deploying process at call
+ *   time. What the store keeps is presence (names) and digests, and the plan diffs on those.
+ *   ★ THIS IS WHERE THE PBS FAMILY PARTS FROM notification-target.ts (PVE), which refuses every
+ *     secret and so cannot create a signed webhook at all.
+ *
+ * ⛔ THE PER-OBJECT PATH CARRIES THE FAMILY: `config/notifications/endpoints/{type}/{name}`. `type`
+ *   is identity, and changing it or `name` plans a REPLACE here — `diff` compares them with the
+ *   recorded props. `/config/notifications/targets` is a read-only union view, as on PVE.
+ *
+ * ⚠️ A BUILT-IN TARGET REVERTS ON DELETE instead of disappearing (`origin: builtin`, measured on
+ *   PBS 4.2 for `mail-to-root`), and PBS reports success either way — notification-target.ts has
+ *   the consequence. Read `origin` before declaring a name you did not create.
+ *
+ * ★ WHAT THIS NEEDS (generated/pbs.ts source): Sys.Audit on /system/notifications to read,
+ *   Sys.Modify there to write. A datastore-scoped credential reads every target as absent.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { handlers } from './pbs-notification-target-lifecycle.ts';
+import type { PveRequirements, WithPbsTarget } from './resource.ts';
+import type { FromEnv } from './write-only.ts';
+
+export type PbsNotificationTargetType = 'sendmail' | 'smtp' | 'webhook';
+
+/**
+ * ⚠️ PBS'S OWN KEY NAMES, DASHES INCLUDED, for the reason backup-job.ts gives. A field outside its
+ *   family (a `url` on a sendmail target) is refused at plan by name, not sent for a 400.
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED; `''` or `[]` (or `{}`) CLEARS ONE.
+ */
+export interface PbsNotificationTargetProps extends WithPbsTarget {
+  /** ⛔ IDENTITY: it picks the family and the URL. Changing it is a replace. */
+  type: PbsNotificationTargetType;
+  /** Unique across ALL families on the host: a webhook cannot be called `mail-to-root`. */
+  name: string;
+  comment?: string;
+  /** Configured but not delivering. Always sent and always compared. */
+  disable?: boolean;
+  /** sendmail, smtp: recipient addresses. Order is not meaning. */
+  mailto?: readonly string[];
+  /** sendmail, smtp: PBS users whose configured address receives the mail. */
+  'mailto-user'?: readonly string[];
+  /** smtp: required. sendmail: optional. */
+  'from-address'?: string;
+  author?: string;
+  /** smtp: the relay host. Required. */
+  server?: string;
+  /** smtp. Unset lets PBS pick from `mode`. */
+  port?: number;
+  /** smtp. PBS's default is `tls`. */
+  mode?: 'insecure' | 'starttls' | 'tls';
+  /** smtp. */
+  username?: string;
+  /** smtp: ⛔ WRITE-ONLY. The server never returns it; the plan compares its seal. */
+  password?: FromEnv;
+  /** webhook: required. Supports templating: `{{ secrets.<name> }}` keeps a token out of it. */
+  url?: string;
+  /** webhook: required. */
+  method?: 'get' | 'post' | 'put';
+  /**
+   * webhook: header name → template text, or `{ fromEnv }` for a value that is itself a secret.
+   * ⚠️ PLAIN VALUES ARE PROPS, AND PROPS ARE STORED: `Content-Type` is fine, a token is not. Put a
+   *   credential in `secret` and write `'Bearer {{ secrets.token }}'` here instead.
+   */
+  header?: Readonly<Record<string, FromEnv | string>>;
+  /**
+   * webhook: the body TEMPLATE, as text. ★ Declared DECODED — the wire is base64, and this family
+   *   encodes on write and decodes on read, so a plan shows a readable diff.
+   */
+  body?: string;
+  /** webhook: ⛔ WRITE-ONLY. Name → variable. Referenced as `{{ secrets.<name> }}`. */
+  secret?: Readonly<Record<string, FromEnv>>;
+}
+
+/** ⛔ NO VALUE OF A SECRET, PASSWORD OR HEADER — names and digests only. */
+export interface PbsNotificationTargetAttributes {
+  name: string;
+  type: PbsNotificationTargetType;
+  /** `builtin`, `modified-builtin`, `user-created` — reported, never compared. */
+  origin: string;
+  comment: string;
+  disable: boolean;
+  mailto: string;
+  'mailto-user': string;
+  'from-address': string;
+  author: string;
+  server: string;
+  /** 0 means PBS holds no port. */
+  port: number;
+  mode: string;
+  username: string;
+  url: string;
+  method: string;
+  /** The decoded body template. */
+  body: string;
+  /** Header NAMES, sorted — presence. */
+  header: string;
+  /** scrypt digest of the live header pairs, fixed salt per target. */
+  headerDigest: string;
+  /** Secret NAMES, sorted — all PBS will say. */
+  secret: string;
+  /**
+   * Seal of the secret values and password THIS PROVIDER LAST WROTE; `''` if it never wrote them
+   * (an adoption). ⚠️ `''` makes those values presence-only until the first write that carries them.
+   */
+  sealed: string;
+}
+
+export interface PbsNotificationTarget extends Resource<
+  'Pbs.NotificationTarget',
+  PbsNotificationTargetProps,
+  PbsNotificationTargetAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const PbsNotificationTarget = Resource<PbsNotificationTarget>('Pbs.NotificationTarget');
+
+/**
+ * ⛔ `Provider.of` STAYS HERE, for resource.ts's reason: it is the one place the handlers are
+ *   checked against the concrete resource types, so the lifecycle file cannot drift from them.
+ */
+export const PbsNotificationTargetProvider = () =>
+  Provider.effect(
+    PbsNotificationTarget,
+    Effect.succeed(PbsNotificationTarget.Provider.of(handlers)),
+  );