@homeflare/alchemy 0.14.0 → 0.19.0

package/src/netbox/prefix.ts

@@ -0,0 +1,136 @@
+/**
+ * `Netbox.Prefix` — one IP prefix and the decision recorded against it.
+ *
+ * ★ WHY THIS OBJECT CLASS IS THE FIRST ONE, AND NOT `Device`, `VLAN` OR `Site`. Three reasons,
+ *   each measurable rather than aesthetic:
+ *
+ *   1. **It is the only interesting NetBox object with no foreign-key prerequisite.** MEASURED in
+ *      the 4.7.0 schema: `WritablePrefixRequest.required` is exactly `["prefix"]`. A `VLAN` needs
+ *      `vid` AND `name` and belongs to a group or site; a `Device` needs a role, a type, a site
+ *      and usually a manufacturer — four more Resources before the first one can be declared.
+ *      A scaffold that cannot declare anything until five families exist proves nothing.
+ *   2. **It is what the estate's NetBox is FOR.** The house's own IPAM agent describes its job as
+ *      reconciling "what the network IS against what NetBox says it was DECIDED to be". A prefix
+ *      is the atom of that decision. The estate has prefixes whose status is currently recorded
+ *      only in an SSH config comment and a retirement doc — a management VLAN, a Thunderbolt
+ *      point-to-point, and three ranges that are retired and still resolve in people's heads.
+ *   3. **`status: 'deprecated'` makes retirement declarable.** That is the move this unlocks:
+ *      a retired range stops being folklore and becomes a line in a stack file with a reviewable
+ *      diff. No other NetBox class turns an estate decision into one field this cleanly.
+ *
+ * ⚠️ ADOPT-FRIENDLY BY CONSTRUCTION. `locate` filters on the exact `prefix`; `identifies` then
+ *   picks the declared VRF, because NetBox allows the same CIDR in two VRFs and in the global
+ *   table. An instance that already holds `10.0.0.0/24` is BOUND, never duplicated — and ⛔ an
+ *   adopt never clears prose it did not declare (prefix-form.ts).
+ *
+ * ⛔ THIS RESOURCE DOES NOT REMOVE PREFIXES IT DOES NOT DECLARE, and `defaultRemovalPolicy` is
+ *   `retain` (resource.ts). Deleting a prefix in NetBox reparents its children and detaches its
+ *   IP assignments; the record of why it existed survives only in the change log.
+ *
+ * ⛔ NO CREDENTIAL IS A PROP. `NETBOX_URL` and `NETBOX_TOKEN` are read from the environment at
+ *   call time — the house convention, and the only shape that keeps a token out of Alchemy state.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { prefixBody, prefixMatches } from './prefix-form.ts';
+import { type NetboxRequirements, netboxHandlers } from './resource.ts';
+import { choice, fk, text } from './values.ts';
+
+/**
+ * ⚠️ THE FOUR VALUES ARE THE VENDOR'S, NOT OURS — copied from the generated table, which is
+ *   generated from NetBox's own enum. The table is what ENFORCES them; this type is what makes
+ *   the mistake visible in an editor.
+ */
+export type PrefixStatus = 'container' | 'active' | 'reserved' | 'deprecated';
+
+export interface PrefixProps {
+  /** CIDR, exactly as NetBox stores it — `10.0.0.0/24`. The stable key for locate. */
+  prefix: string;
+  /**
+   * VRF id, or omitted for the global table.
+   *
+   * ⛔ PART OF THE IDENTITY, NOT A SETTING. NetBox's uniqueness on a prefix is per-VRF, so a
+   *   locate that ignored it could match two rows — which `soleMatch` refuses rather than
+   *   guessing between.
+   */
+  vrf?: number;
+  status?: PrefixStatus;
+  /** ⚠️ `maxLength: 200` in the schema; the generated table enforces it at plan time. */
+  description?: string;
+  /** Free text. ⚠️ NetBox states no length limit, so nothing here checks one. */
+  comments?: string;
+  tenant?: number;
+  vlan?: number;
+  /** All addresses inside are usable. */
+  isPool?: boolean;
+  markUtilized?: boolean;
+}
+
+export interface PrefixAttributes {
+  prefixId: number;
+  prefix: string;
+  status: string;
+  description: string;
+  comments: string;
+  vrf: number | undefined;
+  tenant: number | undefined;
+  vlan: number | undefined;
+  isPool: boolean;
+  markUtilized: boolean;
+}
+
+export interface NetboxPrefix extends Resource<
+  'Netbox.Prefix',
+  PrefixProps,
+  PrefixAttributes,
+  never,
+  NetboxRequirements
+> {}
+
+export const NetboxPrefix = Resource<NetboxPrefix>('Netbox.Prefix', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = netboxHandlers<PrefixProps, PrefixAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      comments: text(live['comments']),
+      description: text(live['description']),
+      isPool: live['is_pool'] === true,
+      markUtilized: live['mark_utilized'] === true,
+      prefix: text(live['prefix']) || props.prefix,
+      prefixId: id,
+      status: choice(live['status']),
+      tenant: fk(live['tenant']),
+      vlan: fk(live['vlan']),
+      vrf: fk(live['vrf']),
+    };
+  },
+  collection: 'ipam/prefixes',
+  createBody: prefixBody,
+  describe: (props) => `ipam/prefixes ${props.prefix}`,
+  endpoint: {
+    create: 'netbox:POST /api/ipam/prefixes/',
+    update: 'netbox:PATCH /api/ipam/prefixes/{id}/',
+  },
+  /**
+   * 🔴 THE VRF IS **NOT** IN THIS FILTER, AND THE REASON IS A GUESS THAT WAS CAUGHT. This read
+   *   `vrf_id=null` for the global table — NetBox does define `FILTERS_NULL_CHOICE_VALUE = 'null'`
+   *   and does honour it on filters that opt in. ⛔ MEASURED IN THE VENDOR'S OWN SOURCE at
+   *   v4.7.0: `PrefixFilterSet.vrf_id` is a plain `django_filters.ModelMultipleChoiceFilter` with
+   *   no `null_value`, so `'null'` is validated against the VRF queryset, fails, and NetBox
+   *   answers 400 under strict filtering — on EVERY plan for EVERY global prefix.
+   * ★ So the CIDR narrows server-side with a filter the document plainly declares, and `identifies`
+   *   picks the VRF in this process. One extra page of candidates, no vendor semantics guessed.
+   */
+  identifies: (live, props) => fk(live['vrf']) === props.vrf,
+  locate: (props) => [['prefix', props.prefix]],
+  matches: prefixMatches,
+  updateBody: prefixBody,
+});
+
+export const NetboxPrefixProvider = () =>
+  Provider.effect(NetboxPrefix, Effect.succeed(NetboxPrefix.Provider.of(handlers)));

package/src/netbox/resource.ts

@@ -0,0 +1,208 @@
+/**
+ * One shape for every NetBox object — the same four operations, different path and JSON body.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME HANDLERS PER RESOURCE. Prefixes, VLANs, devices, tenants
+ *   and interfaces are all create / read / update / delete over `/api` with JSON bodies and a
+ *   numeric primary key. Hand-rolling the fourth copy is where someone drops the read-back or the
+ *   constraint guard and the plan lies.
+ *
+ * ★ ADOPT IS THE DEFAULT POSTURE, NOT A FLAG. `reconcile` LOCATES before it writes: an object the
+ *   estate already has is bound, not duplicated. NetBox is a record that predates this code by
+ *   years; a provider that created a second `10.20.10.0/24` on first deploy would be worse than
+ *   no provider.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` ON EVERY FAMILY. NetBox holds the estate's record of what
+ *   the network was DECIDED to be, and deleting a row deletes history — child prefixes reparent,
+ *   IP assignments detach, and the change log is the only trace left. `retain` means the engine
+ *   skips `delete` when a resource is orphaned unless the caller opts into
+ *   `.pipe(RemovalPolicy.destroy())`. The `delete` handler is FULLY IMPLEMENTED anyway: a stub
+ *   that silently does nothing lies to whoever reads the plan.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { NetboxError, type NetboxList, type NetboxRow, netbox, soleMatch } from './client.ts';
+import { guardBody } from './constraint-guard.ts';
+import type { EndpointKey, NetboxBody } from './constraints.ts';
+
+/**
+ * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME, AND NOTHING MORE. The token comes from
+ *   `NETBOX_TOKEN` in the environment, so there is no process to spawn and no `bao` to shell out
+ *   to. Declaring a service you never use is not harmless — it makes a stack provide a layer for
+ *   nothing, and it hides the one service you DO need.
+ */
+export type NetboxRequirements = HttpClient.HttpClient;
+
+export interface NetboxSpec<Props extends object, Attributes> {
+  /** `ipam/prefixes` — where a new one is POSTed and where `locate` filters. */
+  readonly collection: string;
+  /**
+   * The query that narrows the candidates, as `URLSearchParams` pairs.
+   *
+   * ⛔ ONLY FILTERS THE VENDOR DOCUMENT DECLARES, AND ONLY IN THE FORM IT DECLARES THEM. A
+   *   filter NetBox rejects answers 400, which `absentOn404` correctly does NOT fold to "absent" —
+   *   so a guessed filter shape is a hard failure on every plan, not a soft one.
+   * ★ IT DOES NOT HAVE TO BE UNIQUE. `identifies` finishes the job in this process, where the
+   *   rule is readable and testable offline.
+   */
+  readonly locate: (props: Props) => readonly (readonly [string, string])[];
+  /**
+   * Which of the returned rows IS this object.
+   *
+   * 🔴 THIS EXISTS BECAUSE THE OBVIOUS ALTERNATIVE WAS A GUESS. `Netbox.Prefix` first narrowed
+   *   server-side with `vrf_id=null`, the sentinel NetBox uses elsewhere for "no foreign key".
+   *   ⛔ MEASURED IN THE VENDOR'S OWN SOURCE at v4.7.0: `PrefixFilterSet.vrf_id` is a plain
+   *   `django_filters.ModelMultipleChoiceFilter` with NO `null_value`, so `'null'` is validated
+   *   against the VRF queryset, fails, and NetBox answers 400 under strict filtering. The
+   *   sentinel is real (`FILTERS_NULL_CHOICE_VALUE = 'null'`) but it is opt-in per filter, and
+   *   this one did not opt in.
+   * ★ SO THE DISCRIMINATOR MOVED INTO THIS PROCESS. It costs one page of candidates and buys a
+   *   rule that can be read, tested without a server, and cannot be wrong about a vendor's
+   *   filter semantics. Omit it when `locate` really is unique on its own.
+   */
+  readonly identifies?: (live: NetboxRow, props: Props) => boolean;
+  readonly attributes: (live: NetboxRow, props: Props) => Attributes | undefined;
+  readonly createBody: (props: Props) => NetboxBody;
+  /** ⚠️ PARTIAL BY DESIGN: NetBox updates are PATCH, so presence is not checked on this body. */
+  readonly updateBody?: (props: Props) => NetboxBody;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /** The generated constraint table to check each body against, by endpoint key. */
+  readonly endpoint: { readonly create: EndpointKey; readonly update?: EndpointKey };
+  /** For the message `soleMatch` raises and for read-back failures. */
+  readonly describe: (props: Props) => string;
+}
+
+/** ⚠️ Only 404 folds to "absent". A 403 or a 502 is a real failure — folding it would plan a create over an existing object. */
+const absentOn404 = <A>(io: Effect.Effect<A, NetboxError, NetboxRequirements>) =>
+  io.pipe(
+    Effect.catchIf(
+      (cause): cause is NetboxError => cause instanceof NetboxError && cause.status === 404,
+      () => Effect.succeed(undefined as A),
+    ),
+  );
+
+/**
+ * ⚠️ NOT `limit=1`, AND NOT `limit=2` EITHER. One row is all a caller wants, but the page has to
+ *   be wide enough for `identifies` to see every candidate `locate` matched — a prefix that
+ *   exists in several VRFs comes back several times, and a page of two would hide the third.
+ * ★ TWENTY, AND THE NUMBER IS AN ASSERTION: a natural key matching more than twenty rows is not
+ *   a natural key. `count` is checked against it, so the failure is "your filter is too broad"
+ *   rather than a silent truncation.
+ */
+const LOCATE_PAGE = 20;
+
+const query = (pairs: readonly (readonly [string, string])[]): string =>
+  new URLSearchParams([
+    ...pairs.map(([k, v]) => [k, v] as [string, string]),
+    ['limit', String(LOCATE_PAGE)],
+  ]).toString();
+
+export const netboxOperations = <Props extends object, Attributes>(
+  spec: NetboxSpec<Props, Attributes>,
+) => {
+  const fetchLive = (props: Props) =>
+    absentOn404(
+      netbox<NetboxList<NetboxRow>>('GET', `${spec.collection}/?${query(spec.locate(props))}`),
+    ).pipe(
+      Effect.map((list) => {
+        if (list !== undefined && list.count > LOCATE_PAGE) {
+          throw new Error(
+            `${spec.describe(props)}: the locate filter matched ${String(list.count)} rows, more ` +
+              `than the ${String(LOCATE_PAGE)}-row page this reads. That is not a natural key — ` +
+              'narrow the filter rather than paging through candidates.',
+          );
+        }
+        const rows = list?.results ?? [];
+        const narrow = spec.identifies;
+        return soleMatch(
+          narrow === undefined ? rows : rows.filter((row) => narrow(row, props)),
+          spec.describe(props),
+        );
+      }),
+    );
+
+  /** ⛔ The numeric `id` is the wire path. NetBox has no update-by-natural-key. */
+  const objectPath = (live: NetboxRow): string => `${spec.collection}/${String(live['id'])}`;
+
+  const read = (props: Props) =>
+    fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+    );
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        if (spec.matches(live, news)) return { action: 'noop' } as const;
+        return spec.updateBody === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* fetchLive(news);
+        if (before === undefined) {
+          const body = spec.createBody(news);
+          // ⛔ GUARD BEFORE THE REQUEST, WITH PRESENCE ON. This is the only place a missing
+          //   required property can still be caught locally.
+          yield* guardBody(spec.endpoint.create, body, true);
+          yield* netbox('POST', `${spec.collection}/`, body);
+        } else if (spec.updateBody !== undefined) {
+          const mapped = spec.attributes(before, news);
+          // ⚠️ ADOPTION IS THE `mapped === undefined` CASE TOO: a row this spec cannot map is not
+          //   a row to PATCH blindly.
+          if (mapped !== undefined && !spec.matches(mapped, news)) {
+            const body = spec.updateBody(news);
+            yield* guardBody(spec.endpoint.update, body, false);
+            if (Object.keys(body).length > 0) {
+              yield* netbox('PATCH', `${objectPath(before)}/`, body);
+            }
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${spec.describe(news)}: the write returned no error but the object is still ` +
+                'absent. NetBox returns the object it wrote — read back rather than trusting the ' +
+                'status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* fetchLive(olds);
+        if (live === undefined) return;
+        yield* netbox('DELETE', `${objectPath(live)}/`);
+      }),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd NetBox object, wired once.
+ *
+ * ⚠️ `list` answers empty. NetBox index endpoints return the whole estate — tens of thousands of
+ *   rows on a real instance — so adoption stays explicit rather than sweeping.
+ */
+export const netboxHandlers = <Props extends object, Attributes extends object>(
+  spec: NetboxSpec<Props, Attributes>,
+) => {
+  const ops = netboxOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
+    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+  };
+};

package/src/netbox/values.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Read-versus-write asymmetry — the bug that makes a resource never converge.
+ *
+ * 🔴 THE SHAPE IS DIFFERENT IN EACH DIRECTION AND NOTHING IN THE TYPES SAYS SO. Measured in the
+ *   NetBox 4.7.0 document: a prefix is WRITTEN with `status: "active"` and READ BACK as
+ *   `status: {value: "active", label: "Active"}`; a foreign key is written as `4` and read back
+ *   as `{id: 4, url: …, display: …}`. A `matches` that compared those directly would report drift
+ *   on every plan, for every object, forever — and each "update" would PATCH the same value back.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bool, choice, fk, text } from './values.ts';
+
+describe('a choice field reads back as an object', () => {
+  test('the object form reduces to the string a declaration writes', () => {
+    expect(choice({ label: 'Active', value: 'active' })).toBe('active');
+  });
+
+  /** ⚠️ Both directions must work: a fixture or a brief serialisation gives the bare string. */
+  test('the bare string passes through unchanged', () => {
+    expect(choice('deprecated')).toBe('deprecated');
+  });
+
+  test('anything else is empty rather than undefined, so a comparison stays total', () => {
+    expect(choice(undefined)).toBe('');
+    expect(choice(null)).toBe('');
+    expect(choice({ label: 'Active' })).toBe('');
+  });
+});
+
+describe('a foreign key reads back as a nested object', () => {
+  test('the nested object reduces to its id', () => {
+    expect(
+      fk({ display: 'HomeFlare', id: 4, url: 'https://example.invalid/api/tenancy/tenants/4/' }),
+    ).toBe(4);
+  });
+
+  test('the bare integer passes through', () => {
+    expect(fk(7)).toBe(7);
+  });
+
+  /**
+   * ⛔ `undefined`, NOT `0`. A cleared foreign key and "tenant 0" are different facts, and zero
+   *   is falsy — a `matches` written against it would treat an unset tenant as a match for every
+   *   declaration that omitted one.
+   */
+  test('an absent or unrecognisable key is undefined', () => {
+    expect(fk(null)).toBeUndefined();
+    expect(fk(undefined)).toBeUndefined();
+    expect(fk({ display: 'no id here' })).toBeUndefined();
+  });
+});
+
+describe('text and booleans', () => {
+  /** ⚠️ NetBox stores an empty string for absent text, never null — so `''` is the settled value. */
+  test('absent text settles to the empty string', () => {
+    expect(text(undefined)).toBe('');
+    expect(text(null)).toBe('');
+    expect(text('a note')).toBe('a note');
+  });
+
+  test('only a real true is true', () => {
+    expect(bool(true)).toBe(true);
+    expect(bool('true')).toBe(false);
+    expect(bool(1)).toBe(false);
+  });
+});

package/src/netbox/values.ts

@@ -0,0 +1,40 @@
+/**
+ * Reading a NetBox row into settled values.
+ *
+ * ⛔ A NETBOX READ AND A NETBOX WRITE ARE NOT THE SAME SHAPE, AND THIS IS WHERE THAT IS HANDLED.
+ *   MEASURED in the 4.7.0 document: `WritablePrefixRequest.status` is a bare string enum
+ *   (`"active"`), while `Prefix.status` on the way back is an OBJECT — `{value, label}`. A `diff`
+ *   that compared the declared string against the live object would see drift on every plan, for
+ *   every prefix, forever, and each "update" would PATCH the same value back.
+ * ⚠️ The same asymmetry holds for every choice field in NetBox (`dcim` device `status`,
+ *   `ipam` IP `role`, …). Anything read through `choice` is safe against it.
+ */
+
+/** ⚠️ `''` for absent, not `undefined` — NetBox stores an empty string, never null, for text. */
+export const text = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+export const bool = (value: unknown): boolean => value === true;
+
+/** A `{value, label}` choice object, reduced to the string a declaration writes. */
+export const choice = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'object' && value !== null && 'value' in value) {
+    return text((value as { value: unknown }).value);
+  }
+  return '';
+};
+
+/**
+ * A foreign key, as the integer a declaration writes.
+ *
+ * ⚠️ IT ARRIVES AS A NESTED OBJECT ON READ AND AN INTEGER ON WRITE — `{id, url, display, …}`
+ *   versus `4`. Comparing the two directly is the same never-converges bug as `choice`.
+ */
+export const fk = (value: unknown): number | undefined => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'object' && value !== null && 'id' in value) {
+    const id = (value as { id: unknown }).id;
+    return typeof id === 'number' ? id : undefined;
+  }
+  return undefined;
+};

package/src/openbao/index-types.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The barrel's TYPE surface, pinned.
+ *
+ * ⛔ THIS IS THE TEST FOR A BUG THAT ONLY A CONSUMER COULD SEE. Every `Bao.*` family already
+ *   re-exported its `…Props` and `…Attributes` from its own module, but `index.ts` forwarded only
+ *   the VALUES for seven of them. A consumer that may not deep-import — which is every consumer,
+ *   by the estate's adoption rules — therefore could not name the props of the very Resource the
+ *   barrel handed it, and had to write the shape out and hope it stayed in step.
+ *   MEASURED 2026-09-22 in homeflare-openbao, which did exactly that for `BaoProxmoxRole`.
+ *
+ * ★ A TYPE-ONLY TEST, ON PURPOSE. Nothing here runs; `tsc --noEmit` is the assertion. If a family's
+ *   props stop being reachable from the package entry, this file stops compiling, which is the
+ *   only moment anyone would otherwise notice — at the next consumer, in another repo.
+ */
+import type {
+  BaoAuthMethodAttributes,
+  BaoAuthMethodProps,
+  BaoAuthRoleAttributes,
+  BaoAuthRoleProps,
+  BaoCloudflareRoleAttributes,
+  BaoCloudflareRoleProps,
+  BaoJwtRoleAttributes,
+  BaoMountAttributes,
+  BaoMountProps,
+  BaoPkiRoleAttributes,
+  BaoPkiRoleProps,
+  BaoPluginAttributes,
+  BaoPluginProps,
+  BaoPolicyAttributes,
+  BaoPolicyProps,
+  BaoProxmoxRoleAttributes,
+  BaoProxmoxRoleProps,
+  BaoSshRoleAttributes,
+  BaoSshRoleProps,
+} from './index.ts';
+import { expect, test } from 'bun:test';
+
+/**
+ * ⛔ The one a consumer was already missing. `mount` + `name` + `mintUser` + `ttl` + `maxTtl` IS the
+ *   whole role, so a consumer that writes this shape out by hand is writing the entire
+ *   server-side state of the family — including `mintUser`, which is its security boundary.
+ */
+const proxmoxRole: BaoProxmoxRoleProps = {
+  maxTtl: '30m',
+  mintUser: 'hf-provision@pve',
+  mount: 'proxmox-ops',
+  name: 'provision',
+  ttl: '5m',
+};
+
+const mount: BaoMountProps = { path: 'proxmox-ops', type: 'openbao-plugin-secrets-proxmox' };
+
+/** ⛔ The plugin catalog key — a consumer needs this to declare a registration at all. */
+const plugin: BaoPluginProps = {
+  command: 'openbao-plugin-secrets-proxmox',
+  name: 'openbao-plugin-secrets-proxmox',
+  sha256: 'a'.repeat(64),
+  type: 'secret',
+  version: 'v0.0.0-dev',
+};
+
+/** ★ Named so the attribute types are reachable too: a consumer reads outputs as well as writing props. */
+type Reachable =
+  | BaoAuthMethodAttributes
+  | BaoAuthMethodProps
+  | BaoAuthRoleAttributes
+  | BaoAuthRoleProps
+  | BaoCloudflareRoleAttributes
+  | BaoCloudflareRoleProps
+  | BaoJwtRoleAttributes
+  | BaoMountAttributes
+  | BaoPkiRoleAttributes
+  | BaoPkiRoleProps
+  | BaoProxmoxRoleAttributes
+  | BaoPluginAttributes
+  | BaoPolicyAttributes
+  | BaoPolicyProps
+  | BaoSshRoleAttributes
+  | BaoSshRoleProps;
+
+test("every openbao family's props are reachable from the package entry", () => {
+  const reachable: Reachable[] = [];
+  expect(reachable).toEqual([]);
+  expect(proxmoxRole.mintUser).toBe('hf-provision@pve');
+  expect(mount.type).toBe('openbao-plugin-secrets-proxmox');
+  expect(plugin.version).toBe('v0.0.0-dev');
+});

package/src/openbao/index.ts

@@ -23,11 +23,13 @@ export {
   revokeSelf,
   revokeSelfEffect,
 } from './approle-login.ts';
+export type { BaoAuthMethodAttributes, BaoAuthMethodProps } from './auth-method.ts';
 export { BaoAuthMethod, BaoAuthMethodProvider } from './auth-method.ts';
-export type { BaoAuthRoleProps } from './auth-role.ts';
+export type { BaoAuthRoleAttributes, BaoAuthRoleProps } from './auth-role.ts';
 export { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
 export type { BaoIdentity, BaoIdentityExpected, BaoIdentityFailure } from './bao-identity.ts';
 export { BaoIdentityError, assertBaoIdentity, assertBaoIdentityEffect } from './bao-identity.ts';
+export type { BaoCloudflareRoleAttributes, BaoCloudflareRoleProps } from './cloudflare-role.ts';
 export { BaoCloudflareRole, BaoCloudflareRoleProvider } from './cloudflare-role.ts';
 export {
   CloudflarePermissionGroups,
@@ -42,7 +44,12 @@ export type { HostAppRolesInput, HostRoleClass, HostRoleHost } from './host-appr
 export { HOST_ROLE_SEPARATOR, hostAppRoles, hostRoleName } from './host-approles.ts';
 export type { BaoJwtAuthConfigProps } from './jwt-config.ts';
 export { BaoJwtAuthConfig, BaoJwtAuthConfigProvider } from './jwt-config.ts';
-export type { BaoJwtRoleProps, BaoJwtRoleType } from './jwt-role.ts';
+export type {
+  BaoJwtCallbackMode,
+  BaoJwtRoleAttributes,
+  BaoJwtRoleProps,
+  BaoJwtRoleType,
+} from './jwt-role.ts';
 export { BaoJwtRole, BaoJwtRoleProvider } from './jwt-role.ts';
 export type { BaoKubernetesAliasSource, BaoKubernetesRoleProps } from './kubernetes-role.ts';
 export { BaoKubernetesRole, BaoKubernetesRoleProvider } from './kubernetes-role.ts';
@@ -50,10 +57,15 @@ export type { BaoMfaLoginEnforcementProps } from './mfa-enforcement.ts';
 export { BaoMfaLoginEnforcement, BaoMfaLoginEnforcementProvider } from './mfa-enforcement.ts';
 export type { BaoMfaTotpMethodProps, BaoTotpAlgorithm } from './mfa-totp.ts';
 export { BaoMfaTotpMethod, BaoMfaTotpMethodProvider } from './mfa-totp.ts';
+export type { BaoMountAttributes, BaoMountProps } from './mount.ts';
 export { BaoMount, BaoMountProvider } from './mount.ts';
+export type { BaoPkiRoleAttributes, BaoPkiRoleProps } from './pki-role.ts';
 export { BaoPkiRole, BaoPkiRoleProvider } from './pki-role.ts';
-export type { BaoPluginProps, BaoPluginType } from './plugin.ts';
+export type { BaoPluginAttributes, BaoPluginProps, BaoPluginType } from './plugin.ts';
 export { BaoPlugin, BaoPluginProvider } from './plugin.ts';
+export type { BaoPolicyAttributes, BaoPolicyProps } from './policy.ts';
 export { BaoPolicy, BaoPolicyProvider } from './policy.ts';
+export type { BaoProxmoxRoleAttributes, BaoProxmoxRoleProps } from './proxmox-role.ts';
 export { BaoProxmoxRole, BaoProxmoxRoleProvider } from './proxmox-role.ts';
+export type { BaoSshRoleAttributes, BaoSshRoleProps } from './ssh-role.ts';
 export { BaoSshRole, BaoSshRoleProvider } from './ssh-role.ts';

package/src/proxmox/acl.ts

@@ -189,6 +189,8 @@ const ops = pveOperations<AclProps, AclAttributes>({
    *   the props they came from is true by construction. An identity change is a DIFFERENT grant,
    *   which `diff` in the provider handles.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:PUT /access/acl', update: 'pve:PUT /access/acl' },
   matches: (attributes, props) =>
     attributes.bound && attributes.propagate === (props.propagate !== false),
   path: () => 'access/acl',

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

@@ -103,6 +103,11 @@ export const apiTokenSpec: PveSpec<ApiTokenProps, ApiTokenAttributes> = {
    */
   collection: (props) => `access/users/${props.userid}/token/${props.tokenid}`,
   createForm: shape,
+  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /access/users/{userid}/token/{tokenid}',
+    update: 'pve:PUT /access/users/{userid}/token/{tokenid}',
+  },
   /**
    * ⚠️ 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

package/src/proxmox/apply-endpoints.ts

@@ -0,0 +1,34 @@
+/**
+ * The two applies, and the vendor endpoints they publish through.
+ *
+ * ★ AN ACTION ENDPOINT IS STILL WIRED, EVEN THOUGH ITS TABLE IS EMPTY, AND THE REASON IS THE
+ *   GENERATOR RATHER THAN THE VALIDATOR. `PUT /nodes/{node}/network` and `PUT /cluster/sdn` take
+ *   no body at all — there is nothing for a length or a range to be wrong about — but
+ *   `codegen/constraints.ts` RESOLVES every key named in this package against the vendor's own
+ *   schema and STOPS when one is absent. So the key buys the thing these two families most need:
+ *   a PVE that moves, renames or withdraws the apply fails `bun run check` instead of failing an
+ *   `ifreload -a` on three nodes at once.
+ * ⚠️ AND THE LOOKUP IS NOT FREE EITHER. `constraintsFor` throws when a key has no table, so a
+ *   checkout whose generated tables were never refreshed refuses the apply with the command to
+ *   run rather than quietly doing nothing — the same defect `constraint-guard.ts` names.
+ *
+ * ⛔ NEITHER OF THESE IS A CREATE, AND NEITHER FAMILY HAS A `PveSpec`. Both write their own five
+ *   handlers (an apply is not an object — see the ⛔ in each file), so they reach the shared check
+ *   through `guardForm` by name, exactly as `pbs-datastore-endpoint.ts` does.
+ */
+import type * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+
+/** ⚠️ `{node}` is a path segment, so this really does take no form keys at all. */
+export const NETWORK_APPLY_ENDPOINT: EndpointKey = 'pve:PUT /nodes/{node}/network';
+
+/**
+ * ⛔ CLUSTER-WIDE. One PUT publishes every staged zone, vnet and subnet on every node; there is no
+ *   per-object apply and no pre-apply veto. `sdn-apply.ts` is the whole argument.
+ */
+export const SDN_APPLY_ENDPOINT: EndpointKey = 'pve:PUT /cluster/sdn';
+
+export const guardNetworkApply: Effect.Effect<void> = guardForm(NETWORK_APPLY_ENDPOINT, {}, true);
+
+export const guardSdnApply: Effect.Effect<void> = guardForm(SDN_APPLY_ENDPOINT, {}, true);

package/src/proxmox/backup-job.ts

@@ -173,6 +173,8 @@ const handlers = pveHandlers<BackupJobProps, BackupJobAttributes>({
   /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
   createForm: (props) => ({ ...shape(props), id: props.id }),
   /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/backup', update: 'pve:PUT /cluster/backup/{id}' },
   matches: (attributes, props) =>
     attributes.schedule === props.schedule &&
     attributes.enabled === (props.enabled !== false) &&