@homeflare/distilled-opnsense

This package is not a HomeFlare SDK. It is an unmodified copy of @distilled.cloud/opnsense, generated by the distilled pipeline from OPNsense's own MVC model XML and API controller PHP — OPNsense publishes no OpenAPI/Smithy/GraphQL description of its API at all, so this converter reads opnsense/core's mvc/app/models/OPNsense/<Module>/<Model>.xml and .../controllers/OPNsense/<Module>/Api/*Controller.php directly, not the shared OpenAPI dialect every other distilled package uses. Published here under its own name only because @distilled.cloud/opnsense does not exist on npm yet — the kit builds it in a local clone of alchemy-run/distilled but, per house policy, never pushes to that upstream. See ../alchemy/docs/distilled-interim.md for the full route every distilled-sourced vendor package follows, and why this one exists at all.

⛔ Do not hand-edit anything under src/. The whole point of the route above is that this directory is copied, not written — a fix belongs in the distilled clone's packages/opnsense/, regenerated, then copied back here.

⚠️ License. Apache-2.0, not the kit's usual MIT — this content is a redistribution of alchemy-run/distilled's own Apache-2.0-licensed output, and relicensing a copy would misstate what it is. See LICENSE.

Provenance and version pin

Generated against opnsense/core and opnsense/plugins tag 26.7.2, from a captured package list (os-frr-1.54 matches that one tag's plugin tree exactly) and a runbook stating the box runs "26.7.x" — see the distilled clone's packages/opnsense/README.md for the full evidence chain.

The edge firewall's exact installed version was measured live 2026-09-24 (Probe 14, during PR 236's review — the PR that added @homeflare/alchemy's opnsense/* resources on top of this package), read-only, over the HTTPS API only — no SSH (SSH to the edge is forbidden by house policy; CrowdSec bans the caller's IP on a failed probe): firmware-info returned 200 with product_version=26.7.2_2, and alias-search returned 200 (keys: current, rowCount, rows, total). The edge runs 26.7.2_2, one patch ahead of the 26.7.2 generation tag — the same series, so the reasoning that patch releases essentially never change model/controller shape now rests on a measurement, not an inference. The probe went straight at the vendor's own HTTPS API, not through this package's generated client — see "Not done here" below: this package's own code has still never been pointed at a live instance.

What's in it

8 API controllers, 83 operations — Firewall Alias/Category/Group/Filter (rules), Routing (Gateways), and the os-frr plugin's Quagga/BGP — not OPNsense's full ~80 configured modules; see the distilled clone's packages/opnsense/README.md for the scope table and what was mechanically excluded per controller (decorated get<Item>Actions, bespoke lifecycle actions). catchTag-able errors cover OPNsense's three-shape 200-with-failure vendor pattern ({result:"failed"} validation errors, UserWarningException/UserInformationalException at 200) plus the genuine non-2xx shapes (UserException, DispatchException 404, the 401/403/400 auth gate) — see src/protocol.ts and src/errors.ts for the full mapping with citations back to OPNsense's own PHP source.

import * as Opnsense from '@distilled.cloud/opnsense'; // aliased onto this package — see docs/distilled-interim.md
import * as Effect from 'effect/Effect';

const program = Opnsense.Services.quagga_general.get({}).pipe(
  Effect.provide(
    Opnsense.credentials({
      apiKey: 'key',
      apiSecret: 'secret',
      baseUrl: 'https://edge.example.com',
    }),
  ),
);

Kit code never imports @homeflare/distilled-opnsense directly — always @distilled.cloud/opnsense (the alias in docs/distilled-interim.md's step 5), once that alias exists. This PR does not add that alias and does not declare any Alchemy Resources on top — see "Not done here" below.

Not done here

• No alias, no Alchemy Resources. The alias can only resolve once this package is actually published to npm; adding Firewall Alias/Category/Group/Rule (and later Gateways/BGP) resources on top is a follow-up PR, gated in part on two open intent questions in docs/alchemy-ledger-network.md in the landscape repo.
• No live calls of any kind. This package has never been pointed at a real OPNsense instance; src/protocol.ts's decode logic is grounded in vendor source and docs, not runtime-verified. docs/design.md in the distilled clone's packages/opnsense/ flags a behavioral trap worth reading before building a Resource around setAlias/setCategory/ setGroup: renaming an item through those endpoints triggers a server-side cascade that rewrites the old name everywhere it's referenced elsewhere in config.xml, not just inside the renamed row.

License

Apache-2.0 — see LICENSE. This package is a redistribution of alchemy-run/distilled's own generated output, unmodified.