@homeflare/alchemy 0.39.0 → 0.40.0

package/src/unifi/firewall-policy-ordering.test.ts

@@ -0,0 +1,185 @@
+/**
+ * `Unifi.FirewallPolicyOrdering`'s `spec` against a fake UniFi Network API — mirrors
+ * `acl-rule-ordering.test.ts`. The two things this file exists to prove that no other family test
+ * does: the zone-pair QUERY identity actually reaches the wire (unlike `acl-rule-ordering.ts`'s
+ * one-per-site path with no query at all), and T5's "order IS the value, never `sortedSet`" rule
+ * holds independently for BOTH `beforeSystemDefined` and `afterSystemDefined`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Retry from '@distilled.cloud/unifi-network/Retry';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { attributesOf, driftOf, matches } from './firewall-policy-ordering-form.ts';
+import {
+  type FirewallPolicyOrderingProps,
+  declareFirewallPolicyOrdering,
+  spec,
+} from './firewall-policy-ordering.ts';
+import { unifiOperations } from './resource.ts';
+
+const ORDERING_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies/ordering';
+
+const liveOrdering = (
+  overrides: Partial<firewall.IntegrationFirewallPolicyOrderingDto> = {},
+): firewall.IntegrationFirewallPolicyOrderingDto => ({
+  orderedFirewallPolicyIds: {
+    beforeSystemDefined: ['fp-1', 'fp-2'],
+    afterSystemDefined: ['fp-9'],
+  },
+  ...overrides,
+});
+
+const PROPS: FirewallPolicyOrderingProps = {
+  siteId: 'site-1',
+  sourceFirewallZoneId: 'zone-iot',
+  destinationFirewallZoneId: 'zone-external',
+  beforeSystemDefined: ['fp-1', 'fp-2'],
+  afterSystemDefined: ['fp-9'],
+};
+
+describe('Unifi.FirewallPolicyOrdering spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object, with the zone pair as a query', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(liveOrdering())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.orderedFirewallPolicyIds.beforeSystemDefined).toEqual(['fp-1', 'fp-2']);
+    expect(fake.seen).toHaveLength(1);
+    const sentUrl = new URL(`http://x${fake.seen[0]?.path}`);
+    expect(sentUrl.pathname).toBe(ORDERING_PATH);
+    expect(sentUrl.searchParams.get('sourceFirewallZoneId')).toBe('zone-iot');
+    expect(sentUrl.searchParams.get('destinationFirewallZoneId')).toBe('zone-external');
+  });
+
+  test('a genuine 404 folds to undefined', async () => {
+    const fake = fakeUnifi(() => fakeFailure(404, 'not found'));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 500 fails loudly -- only a genuine not-found may mean absent (T14)', async () => {
+    const fake = fakeUnifi(() => fakeFailure(500, 'boom'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive(PROPS).pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('InternalServerError');
+  });
+});
+
+describe('declareFirewallPolicyOrdering -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: { beforeSystemDefined: ['fp-5'], afterSystemDefined: [] },
+    });
+    const declared = declareFirewallPolicyOrdering(live, 'site-1', 'zone-iot', 'zone-external');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+describe('T5 -- order IS the value, never sortedSet, independently on each half', () => {
+  test('an identical pair of lists is a noop', () => {
+    expect(driftOf(liveOrdering(), PROPS)).toEqual([]);
+    expect(matches(attributesOf(liveOrdering(), PROPS), PROPS)).toBe(true);
+  });
+
+  test('the SAME ids in a DIFFERENT order within beforeSystemDefined is real drift', () => {
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: {
+        beforeSystemDefined: ['fp-2', 'fp-1'],
+        afterSystemDefined: ['fp-9'],
+      },
+    });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(false);
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'beforeSystemDefined', live: ['fp-2', 'fp-1'], declared: ['fp-1', 'fp-2'] },
+    ]);
+  });
+
+  test('a reorder within afterSystemDefined alone is caught, beforeSystemDefined untouched', () => {
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: {
+        beforeSystemDefined: ['fp-1', 'fp-2'],
+        afterSystemDefined: ['fp-9', 'fp-10'],
+      },
+    });
+    const props: FirewallPolicyOrderingProps = { ...PROPS, afterSystemDefined: ['fp-10', 'fp-9'] };
+    expect(driftOf(live, props)).toEqual([
+      { field: 'afterSystemDefined', live: ['fp-9', 'fp-10'], declared: ['fp-10', 'fp-9'] },
+    ]);
+  });
+
+  test('a policy moving from beforeSystemDefined to afterSystemDefined drifts on both fields', () => {
+    // The two halves can never swap through this endpoint by "reordering" alone -- membership moving
+    // across them is a genuine drift on each side independently, not one combined-list reorder.
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: {
+        beforeSystemDefined: ['fp-1'],
+        afterSystemDefined: ['fp-2', 'fp-9'],
+      },
+    });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'beforeSystemDefined', live: ['fp-1'], declared: ['fp-1', 'fp-2'] },
+      { field: 'afterSystemDefined', live: ['fp-2', 'fp-9'], declared: ['fp-9'] },
+    ]);
+  });
+});
+
+describe('Unifi.FirewallPolicyOrdering write paths never reach the vendor API', () => {
+  const ops = unifiOperations(spec);
+
+  test('reconcile on an exact-match adoption (H6) makes no request but the one read', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(liveOrdering())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Success');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('reconcile on drift (a reorder) refuses instead of PUTting the whole pair', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(
+            liveOrdering({
+              orderedFirewallPolicyIds: {
+                beforeSystemDefined: ['fp-2', 'fp-1'],
+                afterSystemDefined: [],
+              },
+            }),
+          )
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(liveOrdering())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.destroy(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen).toEqual([]);
+  });
+});

package/src/unifi/firewall-policy-ordering.ts

@@ -0,0 +1,87 @@
+/**
+ * `Unifi.FirewallPolicyOrdering` — the ordered `before`/`afterSystemDefined` policy-id lists for
+ * ONE `(sourceFirewallZoneId, destinationFirewallZoneId)` zone pair (`getFirewallPolicyOrdering`,
+ * `GET /v1/sites/{siteId}/firewall/policies/ordering`), READ-ONLY (`policy.ts`). T5/I4's per-family
+ * variant: `docs/unifi.md`'s own header named this "a future `Unifi.FirewallPolicyOrdering`" as a
+ * separate, bigger PR (see `acl-rule-ordering.ts`'s header for the same forward reference, now
+ * resolved) — this is that resource.
+ *
+ * ⚠️ NOT ONE OBJECT PER SITE, UNLIKE `acl-rule-ordering.ts` — the identity is the TRIPLE
+ *   `(siteId, sourceFirewallZoneId, destinationFirewallZoneId)`, both zone ids passed as QUERY
+ *   parameters on the same path every time (`firewall.ts`'s `GetFirewallPolicyOrderingRequest`).
+ *   There is no "list every zone pair with an ordering" endpoint — a caller (a future Lane C import)
+ *   has to already know which pairs exist, typically by walking `firewall.getFirewallPolicies`
+ *   (T9's own 424-live-policy scale — B0b's `pageAll`, see `firewall-policy.test.ts`'s own decode
+ *   proof) and grouping by each policy's `source.zoneId`/`destination.zoneId`. Nothing here performs
+ *   that discovery — this resource is one already-known pair's ordering, same as
+ *   `firewall-policy.ts`/`acl-rule.ts` are one already-known object's own fields.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Effect from 'effect/Effect';
+import {
+  type FirewallPolicyOrderingAttributes,
+  type FirewallPolicyOrderingProps,
+  attributesOf,
+  matches,
+} from './firewall-policy-ordering-form.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type {
+  FirewallPolicyOrderingAttributes,
+  FirewallPolicyOrderingProps,
+} from './firewall-policy-ordering-form.ts';
+export { declareFirewallPolicyOrdering, driftOf } from './firewall-policy-ordering-form.ts';
+
+export interface UnifiFirewallPolicyOrdering extends Resource<
+  'Unifi.FirewallPolicyOrdering',
+  FirewallPolicyOrderingProps,
+  FirewallPolicyOrderingAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiFirewallPolicyOrdering = Resource<UnifiFirewallPolicyOrdering>(
+  'Unifi.FirewallPolicyOrdering',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+/** `firewallPolicyOrdering('iot-to-external', props)` — `adopt(true)` piped on by default (H5); see
+ *  `network.ts`. */
+export const firewallPolicyOrdering = (id: string, props: FirewallPolicyOrderingProps) =>
+  UnifiFirewallPolicyOrdering(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  FirewallPolicyOrderingProps,
+  firewall.IntegrationFirewallPolicyOrderingDto,
+  FirewallPolicyOrderingAttributes,
+  firewall.GetFirewallPolicyOrderingError
+> = {
+  type: 'Unifi.FirewallPolicyOrdering',
+  describe: (props) =>
+    `sites/${props.siteId}/firewall/policies/ordering` +
+    `?sourceFirewallZoneId=${props.sourceFirewallZoneId}` +
+    `&destinationFirewallZoneId=${props.destinationFirewallZoneId}`,
+  fetchLive: (props) =>
+    firewall
+      .getFirewallPolicyOrdering({
+        siteId: props.siteId,
+        sourceFirewallZoneId: props.sourceFirewallZoneId,
+        destinationFirewallZoneId: props.destinationFirewallZoneId,
+      })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiFirewallPolicyOrderingProvider = () =>
+  Provider.effect(
+    UnifiFirewallPolicyOrdering,
+    Effect.succeed(UnifiFirewallPolicyOrdering.Provider.of(handlers)),
+  );

package/src/unifi/firewall-policy.test.ts

@@ -0,0 +1,183 @@
+/**
+ * `Unifi.FirewallPolicy`'s `spec` against a fake UniFi Network API — mirrors `acl-rule.test.ts`/
+ * `dns-policy.test.ts`.
+ *
+ * ⚠️ `driftOf`/`matches` coverage lives in `firewall-policy-drift.test.ts` (the field-level table
+ *   plus I2's per-field completeness check) and `firewall-policy-filter-roundtrip.test.ts` (I1's
+ *   filter-bearing round trip) — both split out to keep this file under the house 250-line cap once
+ *   that coverage grew, same split `network-drift.test.ts` is from `network.test.ts`, not a
+ *   different family. Red team, 2026-09-26.
+ *
+ * The last `describe` block is this family's own decode-proof of B0b's `pageAll` (T9) — not used by
+ * `spec.fetchLive` itself (`getFirewallPolicy` reads one policy by id directly, same as
+ * `acl-rule.ts`), but a real console's FirewallPolicy list is the one T9 names by scale (424 live
+ * policies, `alchemy-ledger-network.md:13`) — `paginate.test.ts`'s own "against the real SDK" section
+ * proves the pager's decode path against `networks.getNetworksOverviewPage`; this proves it against
+ * `firewall.getFirewallPolicies`'s own page shape too, so a future Lane C import walking this
+ * family's full list is walking a shape this suite has already exercised end to end.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Retry from '@distilled.cloud/unifi-network/Retry';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { attributesOf } from './firewall-policy-form.ts';
+import { driftOf, matches } from './firewall-policy-drift.ts';
+import { type FirewallPolicyProps, declareFirewallPolicy, spec } from './firewall-policy.ts';
+import { pageAll } from './paginate.ts';
+import { unifiOperations } from './resource.ts';
+
+const POLICY_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies/fp-1';
+
+const liveFirewallPolicy = (
+  overrides: Partial<firewall.FirewallPolicy> = {},
+): firewall.FirewallPolicy => ({
+  action: { type: 'ALLOW' },
+  connectionStateFilter: ['ESTABLISHED', 'RELATED'],
+  description: 'Allow IoT devices outbound to the internet',
+  destination: { zoneId: 'zone-external' },
+  enabled: true,
+  id: 'fp-1',
+  index: 3,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: false,
+  metadata: { origin: 'USER' },
+  name: 'Allow IoT to Internet',
+  source: { zoneId: 'zone-iot' },
+  ...overrides,
+});
+
+const PROPS: FirewallPolicyProps = {
+  siteId: 'site-1',
+  firewallPolicyId: 'fp-1',
+  action: { type: 'ALLOW' },
+  connectionStateFilter: ['ESTABLISHED', 'RELATED'],
+  description: 'Allow IoT devices outbound to the internet',
+  destination: { zoneId: 'zone-external' },
+  enabled: true,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: false,
+  name: 'Allow IoT to Internet',
+  source: { zoneId: 'zone-iot' },
+};
+
+describe('Unifi.FirewallPolicy spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveFirewallPolicy())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('fp-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: POLICY_PATH }]);
+  });
+
+  test('a genuine 404 folds to undefined -- never a false "unreadable" on anything else', async () => {
+    const fake = fakeUnifi(() => fakeFailure(404, 'not found'));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 500 fails loudly -- only a genuine not-found may mean absent (T14)', async () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 indefinitely with backoff -- this test
+    //   asserts the FAILURE, not the retry schedule.
+    const fake = fakeUnifi(() => fakeFailure(500, 'boom'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive(PROPS).pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('InternalServerError');
+  });
+});
+
+describe('declareFirewallPolicy -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveFirewallPolicy({
+      connectionStateFilter: ['RELATED', 'ESTABLISHED'],
+      index: 9,
+    });
+    const declared = declareFirewallPolicy(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+    expect(driftOf(live, declared)).toEqual([]);
+  });
+});
+
+describe('Unifi.FirewallPolicy write paths never reach the vendor API', () => {
+  const ops = unifiOperations(spec);
+
+  test('reconcile on an exact-match adoption (H6) makes no request but the one read', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveFirewallPolicy())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Success');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('reconcile on drift refuses instead of PATCHing/PUTting a merged body', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveFirewallPolicy({ enabled: false }))
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveFirewallPolicy())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.destroy(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen).toEqual([]);
+  });
+});
+
+describe("T9/B0b -- pageAll walks this family's own page shape (decode proof)", () => {
+  test('every row across several pages of getFirewallPolicies decodes, in order', async () => {
+    const rows = Array.from({ length: 7 }, (_, i) =>
+      liveFirewallPolicy({ id: `fp-${i}`, index: i }),
+    );
+    const fake = fakeUnifi((method, url) => {
+      if (
+        method !== 'GET' ||
+        url.pathname !== '/proxy/network/integration/v1/sites/site-1/firewall/policies'
+      ) {
+        return fakeFailure(400, 'unexpected request');
+      }
+      const offset = Number(url.searchParams.get('offset') ?? '0');
+      const limit = Number(url.searchParams.get('limit') ?? '3');
+      const data = rows.slice(offset, offset + limit);
+      return Response.json({ count: data.length, data, limit, offset, totalCount: rows.length });
+    });
+
+    const result = await Effect.runPromise(
+      pageAll(firewall.getFirewallPolicies, { siteId: 'site-1', limit: 3 }).pipe(
+        Effect.provide(fakeUnifiLayer(fake.fetch)),
+      ),
+    );
+
+    expect(result.map((p) => p.id)).toEqual(rows.map((r) => r.id));
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen).toHaveLength(3);
+  });
+});

package/src/unifi/firewall-policy.ts

@@ -0,0 +1,73 @@
+/**
+ * `Unifi.FirewallPolicy` — one firewall policy on a UniFi Network site, READ-ONLY (`policy.ts`).
+ * `Unifi.FirewallPolicyOrdering` (`firewall-policy-ordering.ts`) is the sibling resource for policy
+ * ORDER within a zone pair (T5) — one per `(sourceFirewallZoneId, destinationFirewallZoneId)`, never
+ * this file's concern. `docs/unifi.md`'s own header names this pair as "a bigger, separate PR";
+ * this is that PR — see `docs/unifi-firewall-policy.md` for the full breakdown.
+ *
+ * ★ T11 GATE, CHECKED 2026-09-26: the `Firewall` tag's 13 operations (5 already covered for
+ *   `Unifi.FirewallZone` in `docs/unifi.md`, 8 new here for `FirewallPolicy` — `getFirewallPolicies`,
+ *   `createFirewallPolicy`, `getFirewallPolicyOrdering`, `updateFirewallPolicyOrdering`,
+ *   `deleteFirewallPolicy`, `getFirewallPolicy`, `patchFirewallPolicy`, `updateFirewallPolicy`) are
+ *   byte-identical between 10.4.57 and 10.6.97, full raw operation objects; the 106-schema closure
+ *   reachable from all 13 (`$ref` + `discriminator.mapping`) shares zero names with the 14 schemas
+ *   that DID change elsewhere in the document. Corroborated independently by the A3 changeset's own
+ *   broader 25-operation/139-schema re-check (`.changeset/unifi-network-a3-typed-discriminator-filters.md`).
+ *   Full breakdown: `docs/unifi-firewall-policy.md`.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Effect from 'effect/Effect';
+import {
+  type FirewallPolicyAttributes,
+  type FirewallPolicyProps,
+  attributesOf,
+} from './firewall-policy-form.ts';
+import { matches } from './firewall-policy-drift.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { FirewallPolicyAttributes, FirewallPolicyProps } from './firewall-policy-form.ts';
+export { declareFirewallPolicy } from './firewall-policy-form.ts';
+export { driftOf } from './firewall-policy-drift.ts';
+
+export interface UnifiFirewallPolicy extends Resource<
+  'Unifi.FirewallPolicy',
+  FirewallPolicyProps,
+  FirewallPolicyAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiFirewallPolicy = Resource<UnifiFirewallPolicy>('Unifi.FirewallPolicy', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `firewallPolicy('block-iot-wan', props)` — `adopt(true)` piped on by default (H5); see
+ *  `network.ts`. */
+export const firewallPolicy = (id: string, props: FirewallPolicyProps) =>
+  UnifiFirewallPolicy(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  FirewallPolicyProps,
+  firewall.FirewallPolicy,
+  FirewallPolicyAttributes,
+  firewall.GetFirewallPolicyError
+> = {
+  type: 'Unifi.FirewallPolicy',
+  describe: (props) => `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
+  fetchLive: (props) =>
+    firewall
+      .getFirewallPolicy({ siteId: props.siteId, firewallPolicyId: props.firewallPolicyId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiFirewallPolicyProvider = () =>
+  Provider.effect(UnifiFirewallPolicy, Effect.succeed(UnifiFirewallPolicy.Provider.of(handlers)));

package/src/unifi/index.ts

@@ -37,4 +37,67 @@ export {
   type FirewallZoneProps,
   driftOf as firewallZoneDriftOf,
 } from './firewall-zone.ts';
+export {
+  UnifiDnsPolicy,
+  UnifiDnsPolicyProvider,
+  declareDnsPolicy,
+  dnsPolicy,
+  type DnsPolicyAttributes,
+  type DnsPolicyProps,
+  driftOf as dnsPolicyDriftOf,
+} from './dns-policy.ts';
+export {
+  UnifiAclRule,
+  UnifiAclRuleProvider,
+  aclRule,
+  declareAclRule,
+  type AclRuleAttributes,
+  type AclRuleProps,
+  driftOf as aclRuleDriftOf,
+} from './acl-rule.ts';
+export {
+  UnifiAclRuleOrdering,
+  UnifiAclRuleOrderingProvider,
+  aclRuleOrdering,
+  declareAclRuleOrdering,
+  type AclRuleOrderingAttributes,
+  type AclRuleOrderingProps,
+  driftOf as aclRuleOrderingDriftOf,
+} from './acl-rule-ordering.ts';
+export {
+  UnifiWifiBroadcast,
+  UnifiWifiBroadcastProvider,
+  declareWifiBroadcast,
+  wifiBroadcast,
+  type WifiBroadcastAttributes,
+  type WifiBroadcastProps,
+  driftOf as wifiBroadcastDriftOf,
+} from './wifi-broadcast.ts';
+export {
+  UnifiFirewallPolicy,
+  UnifiFirewallPolicyProvider,
+  declareFirewallPolicy,
+  firewallPolicy,
+  type FirewallPolicyAttributes,
+  type FirewallPolicyProps,
+  driftOf as firewallPolicyDriftOf,
+} from './firewall-policy.ts';
+export {
+  UnifiFirewallPolicyOrdering,
+  UnifiFirewallPolicyOrderingProvider,
+  declareFirewallPolicyOrdering,
+  firewallPolicyOrdering,
+  type FirewallPolicyOrderingAttributes,
+  type FirewallPolicyOrderingProps,
+  driftOf as firewallPolicyOrderingDriftOf,
+} from './firewall-policy-ordering.ts';
+export {
+  UnifiTrafficMatchingList,
+  UnifiTrafficMatchingListProvider,
+  declareTrafficMatchingList,
+  trafficMatchingList,
+  type TrafficMatchingListAttributes,
+  type TrafficMatchingListProps,
+  driftOf as trafficMatchingListDriftOf,
+} from './traffic-matching-list.ts';
 export { providers } from './providers.ts';

package/src/unifi/paginate.test.ts

@@ -5,6 +5,12 @@
  * list operation (`getNetworksOverviewPage`) through the fake UniFi server. `M2`: this file does
  * not repeat the 404/500 decode tests `network.test.ts` already covers — those are about ONE
  * page's failure, not the walk this file exists to prove.
+ *
+ * ⛔ MINOR-3 (red team, 2026-09-26): `page.offset`/`page.totalCount` are wire-controlled values
+ *   `@distilled.cloud/core` never validates (`wifi-broadcast.ts`'s header documents why), so the
+ *   "malformed response" test below plants a non-numeric value in each and proves `paginate.ts`'s
+ *   `numOrPlaceholder` keeps it out of the error text, instead of assuming a vendor response is
+ *   always well-typed just because the SDK's TS types say so.
  */
 import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
@@ -176,6 +182,24 @@ describe('pageAll -- IMPORTANT-3: typed failures on a self-contradicting respons
     expect(failure.reason).toBe('page-ceiling');
   });
 
+  test('a non-numeric offset/totalCount from a malformed response never appears in the error text (MINOR-3)', async () => {
+    const SENTINEL = 'sentinel-do-not-log-me';
+    // Cast, not a typo: the SDK's TS types say `offset`/`totalCount` are numbers, but nothing
+    // validates that at runtime -- this is exactly the shape a genuinely malformed page could take.
+    const fetchPage = () =>
+      Effect.succeed({
+        data: [],
+        offset: SENTINEL,
+        totalCount: SENTINEL,
+      } as unknown as OffsetPage<Row>);
+
+    const failure = await flip(pageAll(fetchPage, {}));
+
+    expect(failure.reason).toBe('offset-mismatch');
+    expect(failure.detail).not.toContain(SENTINEL);
+    expect(failure.message).not.toContain(SENTINEL);
+  });
+
   test('an honest, well-behaved server never trips any of the three checks', async () => {
     const rows = Array.from({ length: 9 }, (_, id) => ({ id }));
     const { fetchPage } = fakePages(rows, 4);

package/src/unifi/paginate.ts

@@ -78,7 +78,19 @@ export class UnifiPaginationInconsistent extends Data.TaggedError('UnifiPaginati
  * a `totalCount` and final row count that agree by coincidence. What this closes is the SILENT
  * version of every case actually observed in review: an ignored `offset`, a `totalCount` that
  * drifts between calls, and an undercounted `totalCount` that truncates the walk early.
+ *
+ * ⛔ `numOrPlaceholder` (red team, MINOR-3, 2026-09-26): nothing in `@distilled.cloud/core` decodes
+ *   or validates a page response's shape (this file's own `wifi-broadcast.ts` neighbor documents
+ *   why), so `page.offset`/`page.totalCount` can be ANY JSON value, not just a number, if the wire
+ *   ever sends something malformed. Every `detail` string below prints these through
+ *   `numOrPlaceholder` rather than raw template interpolation, so a non-numeric value — however it
+ *   got there — can never inject arbitrary response text into an error message a caller might log.
  */
+/** A finite number renders as itself; anything else (a malformed wire value) renders as a fixed
+ *  placeholder, never as the value itself — see this file's header (MINOR-3). */
+const numOrPlaceholder = (value: unknown): string =>
+  typeof value === 'number' && Number.isFinite(value) ? String(value) : '<non-numeric>';
+
 export const pageAll = <Req extends OffsetPageRequest, T, E, R>(
   fetchPage: (request: Req) => Effect.Effect<OffsetPage<T>, E, R>,
   request: Req,
@@ -103,13 +115,13 @@ export const pageAll = <Req extends OffsetPageRequest, T, E, R>(
       if (page.offset !== offset) {
         return yield* new UnifiPaginationInconsistent({
           reason: 'offset-mismatch',
-          detail: `requested offset ${offset}, page echoed ${page.offset} -- rows may be duplicated or skipped`,
+          detail: `requested offset ${offset}, page echoed ${numOrPlaceholder(page.offset)} -- rows may be duplicated or skipped`,
         });
       }
       if (totalCount !== undefined && page.totalCount !== totalCount) {
         return yield* new UnifiPaginationInconsistent({
           reason: 'total-count-changed',
-          detail: `totalCount changed from ${totalCount} to ${page.totalCount} between page calls`,
+          detail: `totalCount changed from ${numOrPlaceholder(totalCount)} to ${numOrPlaceholder(page.totalCount)} between page calls`,
         });
       }
       totalCount = page.totalCount;
@@ -122,7 +134,7 @@ export const pageAll = <Req extends OffsetPageRequest, T, E, R>(
     if (rows.length !== expected) {
       return yield* new UnifiPaginationInconsistent({
         reason: 'row-count-mismatch',
-        detail: `collected ${rows.length} rows but totalCount(${totalCount}) - startOffset(${startOffset}) = ${expected}`,
+        detail: `collected ${rows.length} rows but totalCount(${numOrPlaceholder(totalCount)}) - startOffset(${startOffset}) = ${numOrPlaceholder(expected)}`,
       });
     }
     return rows;