@homeflare/alchemy 0.31.1 → 0.32.0

package/src/opnsense/category.ts

@@ -0,0 +1,82 @@
+/**
+ * `Opnsense.Firewall.Category` — a read-only declaration of one `firewall/category` item (the
+ * tag OPNsense's UI groups aliases, rules etc. by) on the edge. READ-ONLY BY DESIGN — see
+ * policy.ts's header. `reconcile`/`delete` always refuse. Mirrors alias.ts exactly; see that
+ * file's header for why `get()` (whole model) is the read source rather than `getCategory` —
+ * the same generation gap (no `uuid` in `GetCategoryRequest`'s schema) applies here too.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Category from '@distilled.cloud/opnsense/firewall_category';
+import type { OpnsenseOpError } from '@distilled.cloud/opnsense/Protocol';
+import * as Effect from 'effect/Effect';
+import { attributesOf, matches } from './category-form.ts';
+import type { OpnsenseRequirements, OpnsenseSpec } from './resource.ts';
+import { opnsenseHandlers } from './resource.ts';
+
+export interface CategoryProps {
+  readonly uuid: string;
+  /** Pattern `/[^,]+/` on the wire — a comma in the name would collide with the multi-select join. */
+  readonly name: string;
+  /** Whether OPNsense itself created this category (its own subsystems tag things this way); a
+   * category a person made is `false`/absent. */
+  readonly auto?: boolean;
+  /** Six hex digits, no `#`, e.g. `0000FF`. */
+  readonly color?: string;
+}
+
+export interface CategoryAttributes {
+  readonly uuid: string;
+  readonly name: string;
+  readonly auto: boolean;
+  readonly color: string;
+}
+
+export interface OpnsenseFirewallCategory extends Resource<
+  'Opnsense.Firewall.Category',
+  CategoryProps,
+  CategoryAttributes,
+  never,
+  OpnsenseRequirements
+> {}
+
+export const OpnsenseFirewallCategory = Resource<OpnsenseFirewallCategory>(
+  'Opnsense.Firewall.Category',
+  {
+    defaultRemovalPolicy: 'retain',
+  },
+);
+
+export const isOpnsenseFirewallCategory = (value: unknown): value is OpnsenseFirewallCategory =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Opnsense.Firewall.Category';
+
+export const spec: OpnsenseSpec<
+  CategoryProps,
+  Category.CategoryItem,
+  CategoryAttributes,
+  OpnsenseOpError
+> = {
+  attributes: attributesOf,
+  fetchLive: (props) =>
+    Category.get({}).pipe(Effect.map((res) => res.category?.categories?.category?.[props.uuid])),
+  matches,
+  resourceType: 'Opnsense.Firewall.Category',
+};
+
+/** The pure declaration renderer — see alias.ts's `propsFromLive` for the full contract note. */
+export const propsFromLive = attributesOf;
+
+export const handlers = opnsenseHandlers(spec);
+
+export const OpnsenseFirewallCategoryProvider = () =>
+  Provider.effect(
+    OpnsenseFirewallCategory,
+    Effect.succeed(OpnsenseFirewallCategory.Provider.of(handlers)),
+  );
+
+/** `firewallCategory('name', { uuid, name })` — `adopt(true)` piped by default (H5). */
+export const firewallCategory = (id: string, props: CategoryProps) =>
+  OpnsenseFirewallCategory(id, props).pipe(adopt(true));

package/src/opnsense/credentials.ts

@@ -0,0 +1,41 @@
+/**
+ * OPNsense credentials — a key/secret pair REFERENCE, resolved lazily (S24), never a prop.
+ *
+ * ⛔ NO KEY OR SECRET IS EVER A PROP OR AN ATTRIBUTE. Alchemy persists Attributes unencrypted
+ *   (`State/StateEncoding.ts@v2.0.0-beta.79#encodeState`), so nothing a stack file holds may be a
+ *   credential. `@distilled.cloud/opnsense/Credentials` already ships exactly the shape S24 asks
+ *   for: `Credentials` is a lazy `Context.Service<Credentials, Effect.Effect<Config>>`, resolved
+ *   on the calling fiber inside each operation (`OpnsenseProtocol`'s `encode`), never at layer
+ *   build. This file re-exports it rather than re-implementing it — the same choice
+ *   `../discord/credentials.ts` made for its own SDK's `CredentialsFromEnv`.
+ *
+ * ★ `CredentialsFromEnv` READS `OPNSENSE_URL` / `OPNSENSE_API_KEY` / `OPNSENSE_API_SECRET` via
+ *   Effect's `Config` (the SDK's own `credentials.ts` — no vendor-standard env var names exist
+ *   for OPNsense's API, unlike Forgejo's `FORGEJO_URL`). The resource never sees the values,
+ *   only the deploy process's environment does, and the secret is `Redacted` the moment it is
+ *   read — exactly the "reference, never a value" shape S25 asks for.
+ *
+ * ⚠️ NO OpenBao MINT YET, THE SAME GAP `../discord/credentials.ts` DOCUMENTS. H8's target
+ *   (`Alchemy.Stack({ secrets })`) is unreleased (PR 1728, `main` only). Until the estate is on a
+ *   release that carries it, the deploy process's own environment is the credential seam — a
+ *   human or CI job exports the three `OPNSENSE_*` variables from wherever it mints them. This
+ *   package never mints, reads or logs the key/secret itself; it only names the variables.
+ */
+import type { Config } from '@distilled.cloud/opnsense/Credentials';
+import {
+  Credentials,
+  CredentialsFromEnv,
+  credentials,
+} from '@distilled.cloud/opnsense/Credentials';
+
+/** Re-exported so a consumer never has to reach into `@distilled.cloud/opnsense` by hand. */
+export { Credentials, CredentialsFromEnv, credentials };
+export type { Config as OpnsenseCredentialsConfig };
+
+/**
+ * `OpnsenseCredentials.fromEnv()` — the layer `opnsenseHandlers` (resource.ts) provides by
+ * default. A thin, named alias over `CredentialsFromEnv` so a stack's import reads `Opnsense.*`
+ * throughout, the way `../discord/credentials.ts`'s `fromEnv()` keeps `Discord.*` names at the
+ * front door.
+ */
+export const fromEnv = () => CredentialsFromEnv;

package/src/opnsense/fake-opnsense.ts

@@ -0,0 +1,79 @@
+/**
+ * A minimal in-memory OPNsense API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring `../discord/fake-discord.ts`
+ * (itself mirroring `../netbox/fake-netbox.ts`). Tests exercise distilled's REAL path assembly,
+ * JSON encode/decode and Basic-auth header construction — nothing about any of that is
+ * re-implemented here, only the wire responses a scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `opnsense.example.com`, and the key/secret are placeholders — never the edge's real ones,
+ *   which this task has no access to and must not look for (see policy.ts's header).
+ */
+import { type Credentials, credentials } from '@distilled.cloud/opnsense/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://opnsense.example.com';
+export const FAKE_KEY = 'placeholder-opnsense-key';
+export const FAKE_SECRET = 'placeholder-opnsense-secret';
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+export const fakeFailure = (status: number, body: unknown) => Response.json(body, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ */
+export const fakeOpnsense = (
+  route: (method: string, url: URL, body: unknown, callNumber: number) => Response,
+) => {
+  const seen: Seen[] = [];
+  let callNumber = 0;
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const bodyText = await request.clone().text();
+    const body: unknown = bodyText === '' ? undefined : JSON.parse(bodyText);
+    seen.push({ body, method: request.method, path: `${url.pathname}${url.search}` });
+    callNumber += 1;
+    return route(request.method, url, body, callNumber);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen };
+};
+
+/**
+ * ★ FAILS THE TEST ITSELF ON ANY NON-GET REQUEST — the "no SDK write operation is reachable"
+ *   proof `write-refusal.test.ts` and every resource's own test build on. `respond` only ever
+ *   sees a GET, so it never has to branch on method.
+ */
+export const getOnlyOrFail = (respond: (url: URL, callNumber: number) => Response) =>
+  fakeOpnsense((method, url, _body, callNumber) => {
+    if (method !== 'GET') {
+      throw new Error(
+        `fake-opnsense: unexpected ${method} ${url.pathname} — Opnsense.Firewall.* may never ` +
+          'write (policy.ts); this call should not have happened.',
+      );
+    }
+    return respond(url, callNumber);
+  });
+
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `OpnsenseOpContext`, what
+ * every resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `opnsenseHandlers(spec)` export). `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves through Effect's `Config` snapshot of
+ *   `process.env` — untestable against a fake server without setting real env vars a parallel
+ *   test run could race on. So a test calls `spec.fetchLive` (or `opnsenseOperations(spec)`)
+ *   directly, with this explicit layer, exercising exactly the same production code.
+ */
+export const fakeOpnsenseLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({
+    apiKey: FAKE_KEY,
+    apiSecret: FAKE_SECRET,
+    baseUrl: FAKE_BASE,
+  }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/opnsense/group-form.test.ts

@@ -0,0 +1,75 @@
+/**
+ * `group-form.ts`'s pure functions against literal `GroupItem` fixtures — no network.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as group from '@distilled.cloud/opnsense/firewall_group';
+import { attributesOf, matches } from './group-form.ts';
+import type { GroupProps } from './group.ts';
+
+const UUID = '33333333-3333-3333-3333-333333333333';
+
+const liveGroup = (overrides: Partial<group.GroupItem> = {}): group.GroupItem => ({
+  ifname: 'IOT_DEVICES',
+  members: 'opt1,opt2',
+  sequence: '1',
+  ...overrides,
+});
+
+describe('group-form attributesOf', () => {
+  test('settles OPNsense wire spellings to plain values', () => {
+    expect(attributesOf(UUID, liveGroup())).toEqual({
+      description: '',
+      ifname: 'IOT_DEVICES',
+      members: ['opt1', 'opt2'],
+      nogroup: false,
+      sequence: 1,
+      uuid: UUID,
+    });
+  });
+
+  test('members are split, sorted and deduplicated', () => {
+    const live = liveGroup({ members: 'opt2,opt1,opt1' });
+    expect(attributesOf(UUID, live).members).toEqual(['opt1', 'opt2']);
+  });
+
+  test('a non-numeric sequence falls back rather than becoming NaN', () => {
+    expect(attributesOf(UUID, liveGroup({ sequence: 'not-a-number' })).sequence).toBe(0);
+  });
+});
+
+describe('group-form matches', () => {
+  const props: GroupProps = {
+    ifname: 'IOT_DEVICES',
+    members: ['opt1', 'opt2'],
+    sequence: 1,
+    uuid: UUID,
+  };
+
+  test('a live item decoded through attributesOf matches its own declaration', () => {
+    expect(matches(attributesOf(UUID, liveGroup()), props)).toBe(true);
+  });
+
+  test('member-list order alone is not drift', () => {
+    const live = attributesOf(UUID, liveGroup({ members: 'opt2,opt1' }));
+    const declared: GroupProps = { ...props, members: ['opt1', 'opt2'] };
+    expect(matches(live, declared)).toBe(true);
+  });
+
+  test('a removed member is drift', () => {
+    const live = attributesOf(UUID, liveGroup({ members: 'opt1' }));
+    expect(matches(live, props)).toBe(false);
+  });
+});
+
+describe('propsFromLive round-trip', () => {
+  test('the props it returns plan noop against the exact live object they came from', () => {
+    const live = liveGroup({
+      descr: 'IoT VLANs',
+      members: 'opt3,opt1,opt2',
+      nogroup: '1',
+      sequence: '5',
+    });
+    const rendered = attributesOf(UUID, live);
+    expect(matches(attributesOf(UUID, live), rendered)).toBe(true);
+  });
+});

package/src/opnsense/group-form.ts

@@ -0,0 +1,25 @@
+/**
+ * `Opnsense.Firewall.Group`'s wire shape: how a live `GroupItem` (an interface group) becomes
+ * attributes, and the comparison that decides whether a declaration already matches it. Mirrors
+ * alias-form.ts.
+ */
+import type { GroupAttributes, GroupProps } from './group.ts';
+import type * as group from '@distilled.cloud/opnsense/firewall_group';
+import { bool01, csvSet, csvSetOf, numField } from './wire.ts';
+
+/** ★ Attributes and the declaration renderer are one function — see alias-form.ts's header note. */
+export const attributesOf = (uuid: string, live: group.GroupItem): GroupAttributes => ({
+  description: live.descr ?? '',
+  ifname: live.ifname,
+  members: csvSet(live.members),
+  nogroup: bool01(live.nogroup, false),
+  sequence: numField(live.sequence, 0),
+  uuid,
+});
+
+export const matches = (attributes: GroupAttributes, props: GroupProps): boolean =>
+  attributes.ifname === props.ifname &&
+  attributes.nogroup === (props.nogroup ?? false) &&
+  attributes.sequence === (props.sequence ?? 0) &&
+  attributes.description === (props.description ?? '') &&
+  attributes.members.join(',') === csvSetOf(props.members).join(',');

package/src/opnsense/group.test.ts

@@ -0,0 +1,141 @@
+/**
+ * `Opnsense.Firewall.Group`'s `spec` against a fake OPNsense — mirrors `alias.test.ts` for the
+ * interface-group family. See that file's header for what each block proves.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type * as group from '@distilled.cloud/opnsense/firewall_group';
+import * as Effect from 'effect/Effect';
+import { attributesOf } from './group-form.ts';
+import type { GroupProps } from './group.ts';
+import { spec } from './group.ts';
+import { fakeFailure, fakeOpnsense, fakeOpnsenseLayer, getOnlyOrFail } from './fake-opnsense.ts';
+import type { OpnsenseWriteRefused } from './policy.ts';
+import { opnsenseOperations } from './resource.ts';
+
+const asRefusal = (value: unknown) => value as OpnsenseWriteRefused;
+
+const UUID = '33333333-3333-3333-3333-333333333333';
+const GET_PATH = '/api/firewall/group/get';
+const PROPS: GroupProps = {
+  ifname: 'IOT_DEVICES',
+  members: ['opt1', 'opt2'],
+  sequence: 1,
+  uuid: UUID,
+};
+
+const liveItem = (overrides: Partial<group.GroupItem> = {}): group.GroupItem => ({
+  ifname: 'IOT_DEVICES',
+  members: 'opt1,opt2',
+  sequence: '1',
+  ...overrides,
+});
+
+const getResponse = (items: Record<string, group.GroupItem>) =>
+  Response.json({ group: { ifgroupentry: items } });
+
+describe('Opnsense.Firewall.Group spec.fetchLive', () => {
+  test('finds the item whose uuid is the map key, among others', async () => {
+    const fake = getOnlyOrFail((url) =>
+      url.pathname === GET_PATH
+        ? getResponse({ 'other-uuid': liveItem({ ifname: 'OTHER' }), [UUID]: liveItem() })
+        : fakeFailure(400, { errorMessage: 'unexpected request' }),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live?.ifname).toBe('IOT_DEVICES');
+  });
+
+  test('no matching uuid key is absent, not an error', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ 'other-uuid': liveItem() }));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 403 propagates — never folded to absent', async () => {
+    const fake = fakeOpnsense(() => fakeFailure(403, { message: 'Forbidden' }));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('opnsenseOperations(spec).read — S7/S8, marker-less API', () => {
+  test('cold read answers Unowned; warm read answers plain attributes', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const cold = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: undefined })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(Unowned.is(cold)).toBe(true);
+
+    const fakeWarm = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const warm = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: attributesOf(UUID, liveItem()) })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fakeWarm.fetch))),
+    );
+    expect(Unowned.is(warm)).toBe(false);
+  });
+});
+
+describe('opnsenseOperations(spec).diff', () => {
+  test('noop when the declared member set matches live, regardless of order', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt2,opt1' }) }));
+    const result = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .diff(PROPS, attributesOf(UUID, liveItem({ members: 'opt2,opt1' })))
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('update when a member was removed live', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt1' }) }));
+    const result = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .diff(PROPS, attributesOf(UUID, liveItem()))
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'update' });
+  });
+});
+
+describe('opnsenseOperations(spec).reconcile and destroy — the read-only policy', () => {
+  test('reconcile observes with one GET, then refuses — never a write', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt1' }) }));
+    const failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .reconcile(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure._tag).toBe('OpnsenseWriteRefused');
+    expect(failure.action).toBe('update');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen).toHaveLength(1);
+  });
+
+  test('delete refuses unconditionally, with zero requests', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .destroy(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure.action).toBe('delete');
+    expect(fake.seen).toHaveLength(0);
+  });
+});

package/src/opnsense/group.ts

@@ -0,0 +1,78 @@
+/**
+ * `Opnsense.Firewall.Group` — a read-only declaration of one `firewall/group` item (an
+ * "Interface Group", not a permission group) on the edge. READ-ONLY BY DESIGN — see policy.ts's
+ * header. `reconcile`/`delete` always refuse. Mirrors alias.ts exactly; see that file's header
+ * for why `get()` (whole model) is the read source rather than `getGroup` — the same generation
+ * gap (no `uuid` in `GetGroupRequest`'s schema) applies here too.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Group from '@distilled.cloud/opnsense/firewall_group';
+import type { OpnsenseOpError } from '@distilled.cloud/opnsense/Protocol';
+import * as Effect from 'effect/Effect';
+import { attributesOf, matches } from './group-form.ts';
+import type { OpnsenseRequirements, OpnsenseSpec } from './resource.ts';
+import { opnsenseHandlers } from './resource.ts';
+
+export interface GroupProps {
+  readonly uuid: string;
+  /** OPNsense's own `GroupNameField` — the interface group's name. */
+  readonly ifname: string;
+  /** Member interface names (`lan`, `opt1`, …), not their descriptions. */
+  readonly members: readonly string[];
+  /** OPNsense's own "no group" flag — excludes it from certain interface pickers. Default false. */
+  readonly nogroup?: boolean;
+  /** UI list position, `0`..`9999`. Carries no evaluation-order meaning for this object type. */
+  readonly sequence?: number;
+  readonly description?: string;
+}
+
+export interface GroupAttributes {
+  readonly uuid: string;
+  readonly ifname: string;
+  readonly members: readonly string[];
+  readonly nogroup: boolean;
+  readonly sequence: number;
+  readonly description: string;
+}
+
+export interface OpnsenseFirewallGroup extends Resource<
+  'Opnsense.Firewall.Group',
+  GroupProps,
+  GroupAttributes,
+  never,
+  OpnsenseRequirements
+> {}
+
+export const OpnsenseFirewallGroup = Resource<OpnsenseFirewallGroup>('Opnsense.Firewall.Group', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isOpnsenseFirewallGroup = (value: unknown): value is OpnsenseFirewallGroup =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Opnsense.Firewall.Group';
+
+export const spec: OpnsenseSpec<GroupProps, Group.GroupItem, GroupAttributes, OpnsenseOpError> = {
+  attributes: attributesOf,
+  fetchLive: (props) =>
+    Group.get({}).pipe(Effect.map((res) => res.group?.ifgroupentry?.[props.uuid])),
+  matches,
+  resourceType: 'Opnsense.Firewall.Group',
+};
+
+/** The pure declaration renderer — see alias.ts's `propsFromLive` for the full contract note. */
+export const propsFromLive = attributesOf;
+
+export const handlers = opnsenseHandlers(spec);
+
+export const OpnsenseFirewallGroupProvider = () =>
+  Provider.effect(
+    OpnsenseFirewallGroup,
+    Effect.succeed(OpnsenseFirewallGroup.Provider.of(handlers)),
+  );
+
+/** `firewallGroup('name', { uuid, ifname, members })` — `adopt(true)` piped by default (H5). */
+export const firewallGroup = (id: string, props: GroupProps) =>
+  OpnsenseFirewallGroup(id, props).pipe(adopt(true));

package/src/opnsense/index.ts

@@ -0,0 +1,45 @@
+/**
+ * OPNsense providers for Alchemy — READ-ONLY (policy.ts). `reconcile` and `delete` on every
+ * resource here always refuse; this family exists to plan and adopt against the live edge,
+ * never to change it.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY.
+ *   `resource.ts`, `wire.ts`, `policy.ts` and the three `*-form.ts` files are internals every
+ *   resource file shares — a consumer builds against the three resources and `providers()`.
+ */
+export {
+  firewallAlias,
+  isOpnsenseFirewallAlias,
+  OpnsenseFirewallAlias,
+  OpnsenseFirewallAliasProvider,
+  propsFromLive as aliasPropsFromLive,
+  type AliasAttributes,
+  type AliasProps,
+} from './alias.ts';
+export {
+  firewallCategory,
+  isOpnsenseFirewallCategory,
+  OpnsenseFirewallCategory,
+  OpnsenseFirewallCategoryProvider,
+  propsFromLive as categoryPropsFromLive,
+  type CategoryAttributes,
+  type CategoryProps,
+} from './category.ts';
+export {
+  firewallGroup,
+  isOpnsenseFirewallGroup,
+  OpnsenseFirewallGroup,
+  OpnsenseFirewallGroupProvider,
+  propsFromLive as groupPropsFromLive,
+  type GroupAttributes,
+  type GroupProps,
+} from './group.ts';
+export {
+  Credentials,
+  CredentialsFromEnv,
+  type OpnsenseCredentialsConfig,
+  credentials,
+  fromEnv,
+} from './credentials.ts';
+export { OpnsenseWriteRefused, type OpnsenseWriteAction } from './policy.ts';
+export { providers } from './providers.ts';

package/src/opnsense/policy.ts

@@ -0,0 +1,49 @@
+/**
+ * `OpnsenseWriteRefused` — the one error every resource in this family can raise for a write,
+ * and the only thing standing between "read-only for now" and an actual change against the edge.
+ *
+ * ⛔ TIM, 2026-09-24: UniFi AND OPNSENSE ARE READ-ONLY FOR NOW. `Opnsense.Firewall.Alias`,
+ *   `.Category` and `.Group` (alias.ts, category.ts, group.ts) exist to `read`, `diff` and adopt
+ *   against the live edge — never to change it. This is the estate's EDGE firewall: a failed
+ *   probe gets the caller's IP CrowdSec-banned (`edge-crowdsec-bans-lan-ssh-probes` in the shared
+ *   estate memory), and nothing about that risk is worth a resource that can also reconfigure it.
+ *   Every `reconcile` and `delete` in this directory calls `refuseWrite` below and NOTHING ELSE —
+ *   none of them imports an `add`/`set`/`del`/`toggle` operation from `@distilled.cloud/opnsense`
+ *   at all, and `write-refusal.test.ts` proves it with a fake HTTP client that fails the test on
+ *   any request that is not a GET.
+ *
+ * ★ LIFTING THIS IS A KIT CHANGE, NEVER A PROP. There is no `allowWrite` flag on any resource
+ *   here — a flag is one bad `true` (or one bad default) away from a live edit to the box that
+ *   fronts the whole estate. Lifting the policy means editing this file, and writing the
+ *   create/update/delete bodies these resources do not have, a decision Tim makes explicitly by
+ *   changing code and review, not a runtime toggle a stack can set.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+export type OpnsenseWriteAction = 'create' | 'update' | 'delete';
+
+export class OpnsenseWriteRefused extends Data.TaggedError('OpnsenseWriteRefused')<{
+  readonly resourceType: string;
+  readonly id: string;
+  readonly action: OpnsenseWriteAction;
+}> {
+  override get message(): string {
+    return (
+      `${this.resourceType} ${this.id}: refusing to ${this.action} — read-only by Tim's rule, ` +
+      '2026-09-24; lifting it is a kit change, not a prop.'
+    );
+  }
+}
+
+/**
+ * Every `reconcile`/`delete` handler in this family funnels through this one call — see
+ * `resource.ts`'s `opnsenseOperations`. Nothing downstream of this function can reach a write:
+ * it never calls an SDK operation, it only builds and fails with the typed refusal above.
+ */
+export const refuseWrite = (
+  resourceType: string,
+  id: string,
+  action: OpnsenseWriteAction,
+): Effect.Effect<never, OpnsenseWriteRefused> =>
+  Effect.fail(new OpnsenseWriteRefused({ action, id, resourceType }));

package/src/opnsense/providers.ts

@@ -0,0 +1,21 @@
+/**
+ * All three OPNsense firewall providers as one layer for a stack.
+ *
+ *     Layer.mergeAll(opnsenseProviders(), …the stack's other providers)
+ *       .pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * S16: a subpath's `providers()` plays the role upstream's own `Providers.ts` does — one minimal
+ * insertion per family, requirements that never contain `unknown`. `FetchHttpClient.layer` is
+ * the stack's own responsibility to provide, mirroring `../discord/providers.ts`.
+ */
+import * as Layer from 'effect/Layer';
+import { OpnsenseFirewallAliasProvider } from './alias.ts';
+import { OpnsenseFirewallCategoryProvider } from './category.ts';
+import { OpnsenseFirewallGroupProvider } from './group.ts';
+
+export const providers = () =>
+  Layer.mergeAll(
+    OpnsenseFirewallAliasProvider(),
+    OpnsenseFirewallCategoryProvider(),
+    OpnsenseFirewallGroupProvider(),
+  );