@homeflare/alchemy 0.39.0 → 0.41.0

package/src/unifi/providers.ts

@@ -9,7 +9,25 @@
  * mirroring `../discord/providers.ts`.
  */
 import * as Layer from 'effect/Layer';
+import { UnifiAclRuleProvider } from './acl-rule.ts';
+import { UnifiAclRuleOrderingProvider } from './acl-rule-ordering.ts';
+import { UnifiDnsPolicyProvider } from './dns-policy.ts';
+import { UnifiFirewallPolicyProvider } from './firewall-policy.ts';
+import { UnifiFirewallPolicyOrderingProvider } from './firewall-policy-ordering.ts';
 import { UnifiFirewallZoneProvider } from './firewall-zone.ts';
 import { UnifiNetworkProvider } from './network.ts';
+import { UnifiTrafficMatchingListProvider } from './traffic-matching-list.ts';
+import { UnifiWifiBroadcastProvider } from './wifi-broadcast.ts';
 
-export const providers = () => Layer.mergeAll(UnifiNetworkProvider(), UnifiFirewallZoneProvider());
+export const providers = () =>
+  Layer.mergeAll(
+    UnifiNetworkProvider(),
+    UnifiFirewallZoneProvider(),
+    UnifiDnsPolicyProvider(),
+    UnifiAclRuleProvider(),
+    UnifiAclRuleOrderingProvider(),
+    UnifiWifiBroadcastProvider(),
+    UnifiFirewallPolicyProvider(),
+    UnifiFirewallPolicyOrderingProvider(),
+    UnifiTrafficMatchingListProvider(),
+  );

package/src/unifi/scan-source.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared comment/string-aware source scanner for `src/unifi`'s static banned-token tests:
+ * `write-op-reference.test.ts` (T12 — no SDK write-op reference anywhere in this directory) and
+ * `wifi-broadcast-details-call.test.ts` (T23 — no reference to the passphrase-bearing
+ * `getWifiBroadcastDetails` GET). Extracted (red team, IMPORTANT-2, 2026-09-26) so both share the
+ * ONE left-to-right, single-state comment stripper instead of each maintaining its own — see the
+ * history below for why a naive or duplicated implementation is a real trap here, not a
+ * hypothetical one.
+ *
+ * ⚠️ COMMENTS ARE STRIPPED WITH A SINGLE LEFT-TO-RIGHT SCAN, NOT TWO INDEPENDENT REGEXES. An
+ *   earlier "mask strings, then regex the comments" attempt had its own bug: an apostrophe in
+ *   ordinary prose ("doesn't", "it's") reads as an unterminated string open to any regex that does
+ *   not already know it is inside a comment, and can swallow real code up to the next quote
+ *   anywhere later in the file. `stripComments` tracks ONE state (code / line comment / block
+ *   comment / string) char by char left to right, so a comment can't be misread as a string and a
+ *   string's contents (a banned token hidden in one, e.g. `alias['deleteNetwork']`, is still an
+ *   offense) are never mistaken for a comment either.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * One left-to-right scan tracking a single state (code / `//` / `/* *\/` / string). Comments are
+ * blanked to spaces (newlines kept, so a caller's own line-number diagnostics still line up);
+ * string and template literal CONTENTS are left untouched, because a banned token hidden inside
+ * one is still an offense a caller needs to see.
+ */
+export const stripComments = (src: string): string => {
+  let out = '';
+  for (let i = 0; i < src.length;) {
+    const two = src.slice(i, i + 2);
+    if (two === '//') {
+      const end = src.indexOf('\n', i);
+      const stop = end === -1 ? src.length : end;
+      out += ' '.repeat(stop - i);
+      i = stop;
+    } else if (two === '/*') {
+      const end = src.indexOf('*/', i + 2);
+      const stop = end === -1 ? src.length : end + 2;
+      out += src.slice(i, stop).replace(/[^\n]/g, ' ');
+      i = stop;
+    } else if (src[i] === '"' || src[i] === "'" || src[i] === '`') {
+      const quote = src[i];
+      let j = i + 1;
+      while (j < src.length && src[j] !== quote) j += src[j] === '\\' ? 2 : 1;
+      const stop = Math.min(j + 1, src.length);
+      out += src.slice(i, stop);
+      i = stop;
+    } else {
+      out += src[i];
+      i += 1;
+    }
+  }
+  return out;
+};
+
+/** Every `.ts` file under `dir`, recursively — a future `src/unifi/<subdir>/*.ts` is walked too. */
+export const walk = (dir: string): string[] =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = join(dir, entry.name);
+    return entry.isDirectory() ? walk(full) : entry.name.endsWith('.ts') ? [full] : [];
+  });
+
+export const readSource = (path: string): string => readFileSync(path, 'utf8');

package/src/unifi/traffic-matching-list-drift.ts

@@ -0,0 +1,40 @@
+/**
+ * `Unifi.TrafficMatchingList`'s `matches` AND `driftOf` (B6) — both built on the ONE field list
+ * below, the same `fieldDrift`-is-the-only-comparison shape `network-drift.ts`'s header explains
+ * (MEDIUM-4, red team, 2026-09-26): `matches(attrs, props) === (driftOf(live, props).length === 0)`
+ * is true BY CONSTRUCTION, never two hand-kept-in-sync comparisons.
+ *
+ * ⚠️ `stripNullish: true` ON EVERY FIELD BY DEFAULT (`drift.ts`'s `defaultEqual`) — same "UniFi's
+ *   JSON answers `null`, a declaration omits" tolerance every other family here relies on.
+ * ★ `items` compares with the plain default `equal` (whole-value `deepEqual`) — see
+ *   `traffic-matching-list-form.ts`'s header for the accepted known gap this leaves for a
+ *   membership-preserving reorder.
+ */
+import type * as trafficMatchingLists from '@distilled.cloud/unifi-network/traffic_matching_lists';
+import { makeDriftOf } from './drift.ts';
+import {
+  type TrafficMatchingListAttributes,
+  type TrafficMatchingListProps,
+  attributesOf,
+} from './traffic-matching-list-form.ts';
+
+const fieldDrift = makeDriftOf<TrafficMatchingListAttributes, TrafficMatchingListProps>([
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'type', live: (a) => a.type, declared: (p) => p.type },
+  { field: 'items', live: (a) => a.items, declared: (p) => p.items },
+]);
+
+export const matches = (
+  attributes: TrafficMatchingListAttributes,
+  props: TrafficMatchingListProps,
+): boolean => fieldDrift(attributes, props).length === 0;
+
+/**
+ * Per-field live-vs-declared drift straight from one live read — the task's own API
+ * (`driftOf(live, props)`), so `homeflare-network`'s pre-import drift check never has to derive
+ * `attributesOf` itself just to call this.
+ */
+export const driftOf = (
+  live: trafficMatchingLists.TrafficMatchingList,
+  props: TrafficMatchingListProps,
+) => fieldDrift(attributesOf(live, props), props);

package/src/unifi/traffic-matching-list-form.ts

@@ -0,0 +1,77 @@
+/**
+ * `Unifi.TrafficMatchingList`'s wire shape — the declarable subset of `TrafficMatchingList`
+ * (`getTrafficMatchingList`'s own decode target), and how a live read becomes both plan attributes
+ * and a rendered declaration.
+ *
+ * ★ NO `metadata` FIELD AT ALL — the simplest object shape in this directory. Unlike every other
+ *   family here (`FirewallZone`/`DNSPolicy`/`ACLRule`/`FirewallPolicy` all carry a server-derived
+ *   `metadata.origin`), `TrafficMatchingList` is just `{id, name, type, items?}` — nothing here is
+ *   attributes-only the way `metadataOrigin`/`index` are elsewhere.
+ *
+ * ★ `items` IS A REAL TS UNION POST-A3, COMPARED WHOLESALE — `Array<IPv4Matching> |
+ *   Array<IPv6Matching> | Array<PortMatching>`, keyed by the sibling `type` field
+ *   (`traffic_matching_lists.ts`'s own comment: "Shape depends on the sibling discriminator value").
+ *   The runtime schema is still a passthrough `S.Unknown` (A3's own changeset: narrower for a reader
+ *   at the type level only, so decode keeps every key including one this pinned spec doesn't yet
+ *   declare — same proof `discriminated-filter-decode.test.ts` runs for `FirewallPolicy`/`AclRule`).
+ *
+ * ⚠️ KNOWN GAP (T15, same shape `acl-rule-form.ts`/`firewall-policy-form.ts` both carry): a traffic
+ *   matching list's `items` is semantically a SET of match entries (matching is "is this traffic
+ *   covered by ANY entry," not order-dependent, unlike `firewall-policy-ordering-form.ts`'s own
+ *   sequences), but each entry is an OBJECT (`{type, value?, start?, stop?}`), not a bare string --
+ *   there is no cheap canonical sort key the way `sortedSet` gives a `string[]`. `deepEqual` compares
+ *   `items` order-sensitively, so a console-side reorder with no membership change would report a
+ *   spurious drift this read-only family's `reconcile` then refuses forever. Accepted, not fixed,
+ *   same proportion as ACL rule's own nested-filter gap: a generic object-set normalizer is bigger,
+ *   separate modelling work, not a mechanical extension of typing `items` per-discriminator (A3).
+ */
+import type * as trafficMatchingLists from '@distilled.cloud/unifi-network/traffic_matching_lists';
+
+export interface TrafficMatchingListProps {
+  siteId: string;
+  trafficMatchingListId: string;
+  name: string;
+  /** Discriminator for `items`' own shape (e.g. an IPv4/IPv6/port list) — the spec enumerates no
+   *  fixed value set for it (also accepts a future vendor value it did not enumerate). */
+  type: string;
+  /** Match entries — a SET semantically, compared wholesale; see the header's known gap. */
+  items?: trafficMatchingLists.TrafficMatchingListItems | undefined;
+}
+
+export interface TrafficMatchingListAttributes {
+  siteId: string;
+  trafficMatchingListId: string;
+  name: string;
+  type: string;
+  items: trafficMatchingLists.TrafficMatchingListItems | undefined;
+}
+
+export const attributesOf = (
+  live: trafficMatchingLists.TrafficMatchingList,
+  props: TrafficMatchingListProps,
+): TrafficMatchingListAttributes => ({
+  siteId: props.siteId,
+  trafficMatchingListId: live.id,
+  name: live.name,
+  type: live.type,
+  items: live.items,
+});
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). A later import script feeds `getTrafficMatchingList`'s own response
+ * straight in and writes the result as `trafficMatchingList('<id>',
+ * declareTrafficMatchingList(live, siteId))` — no field is invented or defaulted beyond what
+ * `attributesOf` already reports, so `matches(attributesOf(live, props), declareTrafficMatchingList(
+ * live, siteId))` is `true` by construction (`traffic-matching-list.test.ts` proves it).
+ */
+export const declareTrafficMatchingList = (
+  live: trafficMatchingLists.TrafficMatchingList,
+  siteId: string,
+): TrafficMatchingListProps => ({
+  siteId,
+  trafficMatchingListId: live.id,
+  name: live.name,
+  type: live.type,
+  items: live.items,
+});

package/src/unifi/traffic-matching-list.test.ts

@@ -0,0 +1,202 @@
+/**
+ * `Unifi.TrafficMatchingList`'s `spec` against a fake UniFi Network API — mirrors
+ * `dns-policy.test.ts`. `driftOf`/`matches` coverage lives here too, same reasoning as that file's
+ * own header (a short field list, no separate need to split under the house cap).
+ *
+ * ⛔ I2 (red team, 2026-09-26, PR 309 LAND): `traffic-matching-list-drift.ts`'s field list is
+ *   untyped strings (`makeDriftOf`'s own contract) — dropping `type` from it left every test above
+ *   green. The last `describe` below closes that the same way `firewall-policy-drift.test.ts` does:
+ *   `DECLARABLE_FIELDS` is a `Record<..., true>` keyed by `Exclude<keyof TrafficMatchingListProps,
+ *   'siteId' | 'trafficMatchingListId'>` — a field added to or removed from
+ *   `TrafficMatchingListProps` without a matching edit there is a TYPE ERROR, so the list is
+ *   complete BY CONSTRUCTION; the per-field test then proves each one is actually wired into
+ *   `fieldDrift`, not merely present in the type.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as trafficMatchingLists from '@distilled.cloud/unifi-network/traffic_matching_lists';
+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 './traffic-matching-list-form.ts';
+import { driftOf, matches } from './traffic-matching-list-drift.ts';
+import {
+  type TrafficMatchingListProps,
+  declareTrafficMatchingList,
+  spec,
+} from './traffic-matching-list.ts';
+import { unifiOperations } from './resource.ts';
+
+const LIST_PATH = '/proxy/network/integration/v1/sites/site-1/traffic-matching-lists/tml-1';
+
+const liveTrafficMatchingList = (
+  overrides: Partial<trafficMatchingLists.TrafficMatchingList> = {},
+): trafficMatchingLists.TrafficMatchingList => ({
+  id: 'tml-1',
+  name: 'Office subnets',
+  type: 'IPV4',
+  items: [{ type: 'SUBNET', value: '192.0.2.0/24' }],
+  ...overrides,
+});
+
+const PROPS: TrafficMatchingListProps = {
+  siteId: 'site-1',
+  trafficMatchingListId: 'tml-1',
+  name: 'Office subnets',
+  type: 'IPV4',
+  items: [{ type: 'SUBNET', value: '192.0.2.0/24' }],
+};
+
+describe('Unifi.TrafficMatchingList spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json(liveTrafficMatchingList())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('tml-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: LIST_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 () => {
+    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('declareTrafficMatchingList -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    // A different discriminator case than the default fixture (`PortMatching[]`, not
+    // `IPv4Matching[]`) -- a fresh literal, not the SUBNET fixture's overrides.
+    const live: trafficMatchingLists.TrafficMatchingList = {
+      id: 'tml-2',
+      name: 'Management ports',
+      type: 'PORT',
+      items: [{ type: 'RANGE', start: 8000, stop: 8100 }],
+    };
+    const declared = declareTrafficMatchingList(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+    expect(driftOf(live, declared)).toEqual([]);
+  });
+});
+
+describe('driftOf -- B6 field-level drift, straight from one live read', () => {
+  test('a real name change reports its own field, live and declared', () => {
+    const live = liveTrafficMatchingList({ name: 'Office /24s' });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'name', live: 'Office /24s', declared: 'Office subnets' },
+    ]);
+  });
+
+  test('items compares wholesale -- a real membership change is caught', () => {
+    const live = liveTrafficMatchingList({ items: [{ type: 'SUBNET', value: '203.0.113.0/24' }] });
+    expect(driftOf(live, PROPS)).toEqual([
+      {
+        field: 'items',
+        live: [{ type: 'SUBNET', value: '203.0.113.0/24' }],
+        declared: [{ type: 'SUBNET', value: '192.0.2.0/24' }],
+      },
+    ]);
+  });
+
+  test('a live object with no items key at all is a noop against declared undefined', () => {
+    // `exactOptionalPropertyTypes`: the SDK's own `items?` type has no explicit `| undefined`, so
+    // this omits the key entirely rather than setting it to `undefined` -- the real wire shape for
+    // a list with no match entries yet.
+    const live: trafficMatchingLists.TrafficMatchingList = {
+      id: 'tml-1',
+      name: 'Office subnets',
+      type: 'IPV4',
+    };
+    const props: TrafficMatchingListProps = { ...PROPS, items: undefined };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+});
+
+describe('Unifi.TrafficMatchingList 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 === LIST_PATH
+        ? Response.json(liveTrafficMatchingList())
+        : 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 PUTting a merged body', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json(liveTrafficMatchingList({ name: 'Renamed elsewhere' }))
+        : 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 === LIST_PATH
+        ? Response.json(liveTrafficMatchingList())
+        : 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([]);
+  });
+});
+
+type DeclarableField = Exclude<keyof TrafficMatchingListProps, 'siteId' | 'trafficMatchingListId'>;
+
+const DECLARABLE_FIELDS: Record<DeclarableField, true> = {
+  name: true,
+  type: true,
+  items: true,
+};
+
+/** One changed value per field -- distinct enough from PROPS' own that `deepEqual` calls it drift. */
+const CHANGED_VALUE: { [K in DeclarableField]: TrafficMatchingListProps[K] } = {
+  name: 'a different name',
+  type: 'PORT',
+  items: [{ type: 'RANGE', start: 8000, stop: 8100 }],
+};
+
+describe('I2 -- every declarable field is wired into the drift field list', () => {
+  // `liveTrafficMatchingList()` (no overrides) matches PROPS field-for-field, so changing exactly
+  // one PROPS field per case isolates that field's own wire-up.
+  test.each(Object.keys(DECLARABLE_FIELDS) as DeclarableField[])(
+    'changing only %s reports exactly that field',
+    (field) => {
+      const live = liveTrafficMatchingList();
+      const changedProps: TrafficMatchingListProps = { ...PROPS, [field]: CHANGED_VALUE[field] };
+      expect(driftOf(live, changedProps).map((d) => d.field)).toEqual([field]);
+    },
+  );
+});

package/src/unifi/traffic-matching-list.ts

@@ -0,0 +1,78 @@
+/**
+ * `Unifi.TrafficMatchingList` — one traffic matching list (IPv4/IPv6/port match entries) on a UniFi
+ * Network site, READ-ONLY (`policy.ts`).
+ *
+ * ★ T11 GATE, CHECKED 2026-09-26: `Traffic Matching Lists`' 5 operations are byte-identical between
+ *   10.4.57 and 10.6.97, full raw operation objects; the 19-schema closure reachable from all 5
+ *   (`$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-traffic-matching-list.md`.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as trafficMatchingLists from '@distilled.cloud/unifi-network/traffic_matching_lists';
+import * as Effect from 'effect/Effect';
+import {
+  type TrafficMatchingListAttributes,
+  type TrafficMatchingListProps,
+  attributesOf,
+} from './traffic-matching-list-form.ts';
+import { matches } from './traffic-matching-list-drift.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type {
+  TrafficMatchingListAttributes,
+  TrafficMatchingListProps,
+} from './traffic-matching-list-form.ts';
+export { declareTrafficMatchingList } from './traffic-matching-list-form.ts';
+export { driftOf } from './traffic-matching-list-drift.ts';
+
+export interface UnifiTrafficMatchingList extends Resource<
+  'Unifi.TrafficMatchingList',
+  TrafficMatchingListProps,
+  TrafficMatchingListAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiTrafficMatchingList = Resource<UnifiTrafficMatchingList>(
+  'Unifi.TrafficMatchingList',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+/** `trafficMatchingList('office-subnets', props)` — `adopt(true)` piped on by default (H5); see
+ *  `network.ts`. */
+export const trafficMatchingList = (id: string, props: TrafficMatchingListProps) =>
+  UnifiTrafficMatchingList(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  TrafficMatchingListProps,
+  trafficMatchingLists.TrafficMatchingList,
+  TrafficMatchingListAttributes,
+  trafficMatchingLists.GetTrafficMatchingListError
+> = {
+  type: 'Unifi.TrafficMatchingList',
+  describe: (props) =>
+    `sites/${props.siteId}/traffic-matching-lists/${props.trafficMatchingListId}`,
+  fetchLive: (props) =>
+    trafficMatchingLists
+      .getTrafficMatchingList({
+        siteId: props.siteId,
+        trafficMatchingListId: props.trafficMatchingListId,
+      })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiTrafficMatchingListProvider = () =>
+  Provider.effect(
+    UnifiTrafficMatchingList,
+    Effect.succeed(UnifiTrafficMatchingList.Provider.of(handlers)),
+  );

package/src/unifi/wifi-broadcast-details-call.test.ts

@@ -0,0 +1,92 @@
+/**
+ * T23 static guard (red team, IMPORTANT-2, 2026-09-26): no file under `src/unifi` may reference
+ * `getWifiBroadcastDetails` — the single-object WiFi Broadcast GET whose `securityConfiguration`
+ * carries the WPA passphrase and every PPSK entry's own passphrase (`wifi-broadcast.ts`'s header;
+ * SDK `wifi_broadcasts.ts`). Confirmed missing before this file existed: `write-op-reference.test.ts`
+ * only bans WRITE verbs (create/update/delete/patch/execute/remove/adopt) — nothing stopped a
+ * future edit from calling this GET, even though it is exactly as forbidden here as a write op is.
+ *
+ * ⛔ NOT MERGED INTO `write-op-reference.test.ts`'s OWN SCAN. That scan's `WRITE_OP_NAME` regex and
+ *   its `sdkWriteOpNames` harvest are BOTH scoped to `BANNED_VERBS` — `getWifiBroadcastDetails`
+ *   starts with `get`, so it can never match there, and widening that regex to catch it would also
+ *   start matching ordinary read helpers this family and every other one legitimately call
+ *   (`getNetworkDetails`, `getWifiBroadcastPage`, …). This is a single hand-named token, not a verb
+ *   class, so it gets its own small scan built on the SAME comment/string-aware scanner
+ *   (`scan-source.ts`) rather than a real design bent to fit inside the other one.
+ *
+ * ⚠️ NO `SDK_MARKER` GATE, UNLIKE `write-op-reference.test.ts`. That gate exists there because
+ *   `create`/`delete`/… are common English words that need the "and this file imports the SDK" ANDed
+ *   check to avoid false positives; `getWifiBroadcastDetails` is specific enough that its bare
+ *   appearance anywhere in code (not a comment) already IS the offense, with no plausible unrelated
+ *   source for that exact identifier.
+ *
+ * ⛔ ONE NAMED EXCEPTION, NOT A PATTERN. `errors-and-secrets.test.ts` (pre-dates this file — A2,
+ *   kit PR #300) calls `getWifiBroadcastDetails` directly ON PURPOSE: it is the runtime proof that
+ *   the SDK's OWN regen redacts the WPA/PPSK passphrase to `Redacted.Redacted<string>` at the wire
+ *   (T23's `sensitivePatterns` fix), which is impossible to prove without actually calling the
+ *   details endpoint at the SDK layer. That is a DIFFERENT claim from this ban's actual target —
+ *   "no `Unifi.WifiBroadcast` RESOURCE/family file ever calls it" — so it is named here explicitly,
+ *   not folded into a looser rule that would also excuse a future family file. A new exception
+ *   needs the same caliber of justification (proving a lower-layer guarantee that cannot be proven
+ *   without the call) and its own line here, not a widened pattern.
+ */
+import { describe, expect, test } from 'bun:test';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readSource, stripComments, walk } from './scan-source.ts';
+
+const SELF = fileURLToPath(import.meta.url);
+const DIR = dirname(SELF);
+const BANNED_TOKEN = 'getWifiBroadcastDetails';
+const TOKEN_PATTERN = new RegExp(`\\b${BANNED_TOKEN}\\b`);
+
+/** The one file allowed to reference the banned token, and why — see this file's header. */
+const ALLOWED_REFERENCES: ReadonlySet<string> = new Set([join(DIR, 'errors-and-secrets.test.ts')]);
+
+const sourceFiles = () =>
+  walk(DIR).filter((path) => path !== SELF && !ALLOWED_REFERENCES.has(path));
+
+const referencesBannedToken = (rawSrc: string): boolean =>
+  TOKEN_PATTERN.test(stripComments(rawSrc));
+
+describe('src/unifi never calls getWifiBroadcastDetails (T23, IMPORTANT-2)', () => {
+  test('every source file, except the one named exception, is clean of the details call', () => {
+    const offenders = sourceFiles().filter((path) => referencesBannedToken(readSource(path)));
+    expect(offenders).toEqual([]);
+  });
+
+  test('the named exception still exists and still is the one making the call (guards a silent rename)', () => {
+    const [exceptionPath] = [...ALLOWED_REFERENCES];
+    if (exceptionPath === undefined) throw new Error('ALLOWED_REFERENCES must not be empty');
+    expect(referencesBannedToken(readSource(exceptionPath))).toBe(true);
+  });
+
+  test('a comment or prose mention of the banned name never trips the scan', () => {
+    // This file's own header, and wifi-broadcast.ts's, both name the token in prose -- proving the
+    // scan is comment-aware IS the point: a naive substring scan would flag the very files that
+    // document why the call is forbidden.
+    const documented = `
+      /** Never call getWifiBroadcastDetails directly -- see T23. */
+      // getWifiBroadcastDetails is refused by policy.ts too.
+      export const read = () => 1;
+    `;
+    expect(referencesBannedToken(documented)).toBe(false);
+  });
+
+  test('a real reference to the banned call is caught regardless of syntax shape', () => {
+    const marker = '@distilled.cloud/unifi-network/wifi_broadcasts';
+    const cases = [
+      `import { getWifiBroadcastDetails } from '${marker}';`,
+      `import { getWifiBroadcastDetails as readOne } from '${marker}'; readOne;`,
+      `export { getWifiBroadcastDetails } from '${marker}';`,
+      `const fn = (m: Record<string, unknown>) => m['getWifiBroadcastDetails'];`,
+      `const fn = async () => (await import('${marker}')).getWifiBroadcastDetails;`,
+    ];
+    for (const src of cases) expect(referencesBannedToken(src)).toBe(true);
+  });
+
+  test('the walk is recursive, matching write-op-reference.test.ts', () => {
+    expect(sourceFiles().length).toBeGreaterThan(0);
+    expect(sourceFiles()).not.toContain(SELF);
+  });
+});

package/src/unifi/wifi-broadcast-drift.ts

@@ -0,0 +1,69 @@
+/**
+ * `Unifi.WifiBroadcast`'s `matches` AND `driftOf` (B6) — built on the ONE field list below, the
+ * same `fieldDrift`-is-the-only-comparison shape `dns-policy-drift.ts`'s header explains
+ * (MEDIUM-4): `matches(attrs, props) === (driftOf(live, props).length === 0)` is true BY
+ * CONSTRUCTION, never two hand-kept-in-sync comparisons.
+ *
+ * ★ THREE FIELDS REUSE `wifi-broadcast-form.ts`'s OWN NORMALIZERS ON THE `declared` SIDE TOO, not
+ *   just the `live` side — `firewall-zone-form.ts`'s `networkIds` gives the same reason: comparing
+ *   a freshly-normalized live value against an un-normalized declared value would report spurious
+ *   drift the moment a committed declaration's array happens to be in a different (still valid)
+ *   order than what `declareWifiBroadcast` would itself produce today.
+ */
+import type * as wifiBroadcasts from '@distilled.cloud/unifi-network/wifi_broadcasts';
+import { makeDriftOf } from './drift.ts';
+import {
+  type WifiBroadcastAttributes,
+  type WifiBroadcastProps,
+  attributesOf,
+  normalizeDeviceFilter,
+  normalizeFrequencies,
+  normalizeHotspot,
+  normalizeRef,
+  normalizeSecurityConfiguration,
+} from './wifi-broadcast-form.ts';
+
+const fieldDrift = makeDriftOf<WifiBroadcastAttributes, WifiBroadcastProps>([
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
+  { field: 'type', live: (a) => a.type, declared: (p) => p.type },
+  {
+    // IMPORTANT-1: `a.network` is already rebuilt field-by-field inside `attributesOf`; the
+    // declared side gets the same treatment so a hand-written declaration carrying a stray key
+    // cannot report phantom drift against a live side that never could.
+    field: 'network',
+    live: (a) => a.network,
+    declared: (p) => normalizeRef(p.network),
+  },
+  {
+    field: 'broadcastingDeviceFilter',
+    live: (a) => a.broadcastingDeviceFilter,
+    declared: (p) => normalizeDeviceFilter(p.broadcastingDeviceFilter),
+  },
+  {
+    field: 'broadcastingFrequenciesGHz',
+    live: (a) => a.broadcastingFrequenciesGHz,
+    declared: (p) => normalizeFrequencies(p.broadcastingFrequenciesGHz),
+  },
+  {
+    field: 'hotspotConfiguration',
+    live: (a) => a.hotspotConfiguration,
+    declared: (p) => normalizeHotspot(p.hotspotConfiguration),
+  },
+  {
+    field: 'securityConfiguration',
+    live: (a) => a.securityConfiguration,
+    declared: (p) => normalizeSecurityConfiguration(p.securityConfiguration),
+  },
+]);
+
+export const matches = (attributes: WifiBroadcastAttributes, props: WifiBroadcastProps): boolean =>
+  fieldDrift(attributes, props).length === 0;
+
+/**
+ * Per-field live-vs-declared drift straight from one live read — the task's own API
+ * (`driftOf(live, props)`), so `homeflare-network`'s pre-import drift check never has to derive
+ * `attributesOf` itself just to call this.
+ */
+export const driftOf = (live: wifiBroadcasts.WifiBroadcastOverview, props: WifiBroadcastProps) =>
+  fieldDrift(attributesOf(live, props), props);