@homeflare/alchemy 0.39.0 → 0.41.0

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

@@ -0,0 +1,211 @@
+/**
+ * `Unifi.WifiBroadcast`'s wire shape — the declarable subset of `WifiBroadcastOverview`, and how
+ * a live read becomes both plan attributes and a rendered declaration.
+ *
+ * ⛔ T23, THE WHOLE REASON THIS SHAPE DIFFERS FROM EVERY OTHER FAMILY HERE. Every other family's
+ *   `*-form.ts` (`network-form.ts`, `dns-policy-form.ts`, …) types its props against the vendor's
+ *   CREATE/UPDATE request — the fullest declarable shape, even though this stack never calls it.
+ *   `WifiBroadcastProps`/`WifiBroadcastAttributes` do NOT: `securityConfiguration` is typed
+ *   `wifiBroadcasts.WifiSecurityConfigurationOverview` — the PAGE OVERVIEW's own type, `{type,
+ *   presharedKeyNetworkIds}` — never `WifiSecurityConfigurationDetailObject` (the
+ *   `getWifiBroadcastDetails`/create/update shape, which carries `passphrase` and
+ *   `radiusConfiguration`). There is no DECLARED field on `WifiSecurityConfigurationOverview` for
+ *   `attributesOf`/`declareWifiBroadcast` below to name a passphrase into. See `wifi-broadcast.ts`'s
+ *   header for why `fetchLive` can only ever produce a `WifiBroadcastOverview` in the first place
+ *   (no get-by-id call exists for it).
+ *
+ * ⛔ THE TYPE SYSTEM ALONE DOES NOT ENFORCE THIS (red team, IMPORTANT-1, 2026-09-26). `@distilled
+ *   .cloud/core`'s wire decode does not strip a key a schema doesn't declare (this file's next
+ *   header block); the TS types above describe what a CORRECTLY-shaped response looks like, not
+ *   what the decoder actually returns at runtime, so a stray key nested inside `network`,
+ *   `hotspotConfiguration`, `broadcastingDeviceFilter`, or an element of `presharedKeyNetworkIds`
+ *   would ride along through a naive `{...live}`/pass-through copy exactly like the top-level
+ *   `securityConfiguration` object does. `normalizeRef`/`normalizeHotspot`/`normalizeDeviceFilter`
+ *   below rebuild EVERY nested object field-by-field for the same reason
+ *   `normalizeSecurityConfiguration` does — enumeration, not the type annotation, is what actually
+ *   stops it. `wifi-broadcast-secrets.test.ts` plants a sentinel inside each nested shape
+ *   (including one `presharedKeyNetworkIds` element) to prove it, not just the top level.
+ *
+ * ⚠️ EVERY OTHER FIELD REUSES THE SDK'S OWN OVERVIEW TYPES DIRECTLY (`WifiNetworkReference`,
+ *   `BroadcastingDeviceFilter`, `IntegrationWifiHotspotConfigurationOverviewDto`) rather than
+ *   redeclaring them — same reasoning `network-form.ts` gives for reusing `NetworkDHCPGuarding`/
+ *   `NetworkIPv6Configuration` verbatim: one shape to keep in sync with the SDK's own regen.
+ *
+ * ⛔ THREE FIELDS ARE SETS, NOT SEQUENCES, UNCONFIRMED AGAINST A LIVE CONSOLE (same caveat
+ *   `network-form.ts`'s header gives for its own three): `broadcastingDeviceFilter.deviceIds`/
+ *   `.deviceTagIds` and `securityConfiguration.presharedKeyNetworkIds` are membership sets by the
+ *   vendor description's own wording ("Defines the custom scope of devices…"), not ordered
+ *   sequences. `normalizeDeviceFilter`/`normalizeSecurityConfiguration`/`normalizeFrequencies`
+ *   neutralize the same "spurious update, refused by a read-only reconcile" failure mode
+ *   `network-form.ts`'s header describes, exactly like `firewall-zone-form.ts`'s `networkIds`.
+ */
+import type * as wifiBroadcasts from '@distilled.cloud/unifi-network/wifi_broadcasts';
+
+const sortedStrings = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+const sortedFrequencies = (values: readonly number[]): number[] =>
+  [...new Set(values)].sort((a, b) => a - b);
+
+/** Canonical sort key for a `{type, networkId?}` reference — stable regardless of vendor order. */
+const refKey = (ref: wifiBroadcasts.WifiNetworkReference): string =>
+  `${ref.type}:${ref.networkId ?? ''}`;
+
+/**
+ * Rebuilds a reference field-by-field — never returns the object as received. IMPORTANT-1: this
+ * runs on EVERY reference this file handles (`network`, and each `presharedKeyNetworkIds`
+ * element) precisely because a reference is exactly the shape (`{network: WifiNetworkReference,
+ * passphrase}`) the details call uses to carry a PPSK passphrase (`IntegrationWifiPresharedKeyDto`,
+ * SDK `wifi_broadcasts.ts`); it is the most plausible place for a stray passphrase-shaped key to
+ * appear on the wire if the vendor ever leaked one onto the overview response.
+ */
+export const normalizeRef = (
+  ref: wifiBroadcasts.WifiNetworkReference | undefined,
+): wifiBroadcasts.WifiNetworkReference | undefined =>
+  ref === undefined
+    ? undefined
+    : { type: ref.type, ...(ref.networkId !== undefined ? { networkId: ref.networkId } : {}) };
+
+const sortedRefs = (
+  values: readonly wifiBroadcasts.WifiNetworkReference[],
+): wifiBroadcasts.WifiNetworkReference[] => {
+  const byKey = new Map(
+    values.map(
+      (ref) => [refKey(ref), normalizeRef(ref) as wifiBroadcasts.WifiNetworkReference] as const,
+    ),
+  );
+  return [...byKey.values()].sort((a, b) => refKey(a).localeCompare(refKey(b)));
+};
+
+/**
+ * Rebuilds the hotspot configuration field-by-field. `IntegrationWifiHotspotConfigurationOverviewDto`
+ * declares only `type` (SDK `wifi_broadcasts.ts:743-753`) — a PASSPOINT/RADIUS secret would live on
+ * a wire key this type doesn't name, exactly the IMPORTANT-1 risk `normalizeRef` guards against.
+ */
+export const normalizeHotspot = (
+  value: wifiBroadcasts.IntegrationWifiHotspotConfigurationOverviewDto | undefined,
+): wifiBroadcasts.IntegrationWifiHotspotConfigurationOverviewDto | undefined =>
+  value === undefined ? undefined : { type: value.type };
+
+/**
+ * ★ EXPORTED: `wifi-broadcast-drift.ts` reuses these exact normalizers so `matches`/`driftOf` can
+ *   never quietly disagree about what counts as a change (MEDIUM-4, `network-drift.ts`'s header).
+ *
+ * ⛔ NO `{...value}` SPREAD (red team, IMPORTANT-1) — `BroadcastingDeviceFilter` declares exactly
+ *   `type`/`deviceIds`/`deviceTagIds` (SDK `wifi_broadcasts.ts:125-129`); enumerating exactly those
+ *   three is what stops a stray wire key here, the same reason `normalizeSecurityConfiguration`
+ *   (below) never spreads its input.
+ */
+export const normalizeDeviceFilter = (
+  value: wifiBroadcasts.BroadcastingDeviceFilter | undefined,
+): wifiBroadcasts.BroadcastingDeviceFilter | undefined =>
+  value == null
+    ? value
+    : {
+        type: value.type,
+        ...(value.deviceIds !== undefined ? { deviceIds: sortedStrings(value.deviceIds) } : {}),
+        ...(value.deviceTagIds !== undefined
+          ? { deviceTagIds: sortedStrings(value.deviceTagIds) }
+          : {}),
+      };
+
+export const normalizeFrequencies = (value: readonly number[] | undefined): number[] | undefined =>
+  value === undefined ? value : sortedFrequencies(value);
+
+/**
+ * ⛔ NO `{...value}` SPREAD, UNLIKE EVERY OTHER NORMALIZER IN THIS DIRECTORY (`network-form.ts`'s
+ *   `normalizeDhcpGuarding`/`normalizeIpv6Configuration` both spread). This is the one field in
+ *   the whole `Unifi.*` tree with a spec-confirmed passphrase risk (T23): nothing in
+ *   `@distilled.cloud/core`'s wire key-mapping strips an object key the schema doesn't declare —
+ *   it only renames declared ones — so a stray extra key on the WIRE `securityConfiguration`
+ *   object (a vendor bug, or a future console version) survives `getWifiBroadcastPage`'s own
+ *   decode untyped, and `{...value}` would carry it straight through into `Attributes`/`Props`/the
+ *   rendered declaration. Enumerating exactly the two fields
+ *   `WifiSecurityConfigurationOverview` declares is what actually stops that — proved by
+ *   `wifi-broadcast-secrets.test.ts`'s sentinel test, which injects exactly this kind of stray key.
+ */
+export const normalizeSecurityConfiguration = (
+  value: wifiBroadcasts.WifiSecurityConfigurationOverview,
+): wifiBroadcasts.WifiSecurityConfigurationOverview => ({
+  type: value.type,
+  ...(value.presharedKeyNetworkIds !== undefined
+    ? { presharedKeyNetworkIds: sortedRefs(value.presharedKeyNetworkIds) }
+    : {}),
+});
+
+/**
+ * ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` ON PURPOSE — `exactOptionalPropertyTypes`; see
+ *   `network-form.ts`'s own header. `attributesOf`/`declareWifiBroadcast` echo a live optional
+ *   field structurally rather than defaulting it, so the target type must admit an explicit
+ *   `undefined`.
+ */
+export interface WifiBroadcastProps {
+  siteId: string;
+  wifiBroadcastId: string;
+  name: string;
+  enabled: boolean;
+  type: string;
+  network?: wifiBroadcasts.WifiNetworkReference | undefined;
+  broadcastingDeviceFilter?: wifiBroadcasts.BroadcastingDeviceFilter | undefined;
+  broadcastingFrequenciesGHz?: number[] | undefined;
+  hotspotConfiguration?: wifiBroadcasts.IntegrationWifiHotspotConfigurationOverviewDto | undefined;
+  /** ⛔ T23: the PAGE OVERVIEW's security shape ONLY — see this file's header. */
+  securityConfiguration: wifiBroadcasts.WifiSecurityConfigurationOverview;
+}
+
+export interface WifiBroadcastAttributes {
+  siteId: string;
+  wifiBroadcastId: string;
+  name: string;
+  enabled: boolean;
+  type: string;
+  network: wifiBroadcasts.WifiNetworkReference | undefined;
+  broadcastingDeviceFilter: wifiBroadcasts.BroadcastingDeviceFilter | undefined;
+  broadcastingFrequenciesGHz: number[] | undefined;
+  hotspotConfiguration: wifiBroadcasts.IntegrationWifiHotspotConfigurationOverviewDto | undefined;
+  securityConfiguration: wifiBroadcasts.WifiSecurityConfigurationOverview;
+  /** `metadata.origin` — server-derived, never declared; same split as every other family. */
+  metadataOrigin: string;
+}
+
+export const attributesOf = (
+  live: wifiBroadcasts.WifiBroadcastOverview,
+  props: WifiBroadcastProps,
+): WifiBroadcastAttributes => ({
+  siteId: props.siteId,
+  wifiBroadcastId: live.id,
+  name: live.name,
+  enabled: live.enabled,
+  type: live.type,
+  network: normalizeRef(live.network),
+  broadcastingDeviceFilter: normalizeDeviceFilter(live.broadcastingDeviceFilter),
+  broadcastingFrequenciesGHz: normalizeFrequencies(live.broadcastingFrequenciesGHz),
+  hotspotConfiguration: normalizeHotspot(live.hotspotConfiguration),
+  securityConfiguration: normalizeSecurityConfiguration(live.securityConfiguration),
+  metadataOrigin: live.metadata.origin,
+});
+
+/**
+ * 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 `getWifiBroadcastPage`'s own per-row
+ * response straight in and writes the result into `alchemy.run.ts` as `wifiBroadcast('<id>',
+ * declareWifiBroadcast(live, siteId))` — no field is invented or defaulted here beyond what
+ * `attributesOf` already reports, so `matches(attributesOf(live, props), declareWifiBroadcast(live,
+ * siteId))` is `true` by construction (`wifi-broadcast.test.ts` proves it) for any live object
+ * this SDK can decode. Builds ONLY from fields `WifiBroadcastOverview` has — never a passphrase,
+ * which that type cannot express (see this file's header).
+ */
+export const declareWifiBroadcast = (
+  live: wifiBroadcasts.WifiBroadcastOverview,
+  siteId: string,
+): WifiBroadcastProps => ({
+  siteId,
+  wifiBroadcastId: live.id,
+  name: live.name,
+  enabled: live.enabled,
+  type: live.type,
+  network: normalizeRef(live.network),
+  broadcastingDeviceFilter: normalizeDeviceFilter(live.broadcastingDeviceFilter),
+  broadcastingFrequenciesGHz: normalizeFrequencies(live.broadcastingFrequenciesGHz),
+  hotspotConfiguration: normalizeHotspot(live.hotspotConfiguration),
+  securityConfiguration: normalizeSecurityConfiguration(live.securityConfiguration),
+});

package/src/unifi/wifi-broadcast-secrets.test.ts

@@ -0,0 +1,145 @@
+/**
+ * T23 runtime proof for `Unifi.WifiBroadcast`, split from `wifi-broadcast.test.ts` for the same
+ * reason `errors-and-secrets.test.ts` is split from `network.test.ts`: keeps the security-critical
+ * assertions in one file a reviewer can find by name, under the house line cap.
+ *
+ * ★ WHY THE SENTINEL IS INJECTED INTO `securityConfiguration` DIRECTLY ON THE WIRE, NOT VIA A
+ *   `WifiBroadcastOverview` TYPE. `WifiSecurityConfigurationOverview` has no `passphrase` field —
+ *   that is the whole point of `wifi-broadcast-form.ts`'s design (see its header) — so there is no
+ *   TYPED way to construct a fixture that carries one. The raw JSON fixture below simulates the
+ *   one thing the type system CANNOT rule out: a vendor bug or a future console version that puts
+ *   a passphrase-shaped key on the overview response anyway. `errors-and-secrets.test.ts` already
+ *   proves the SDK's OWN details-call schema redacts a real `passphrase` field to `Redacted`; this
+ *   file proves the different, narrower claim the overview path needs: even an UNDECLARED key with
+ *   that name surviving decode never reaches this family's attributes, declaration or a forced
+ *   error path.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { attributesOf } from './wifi-broadcast-form.ts';
+import { type WifiBroadcastProps, declareWifiBroadcast, spec } from './wifi-broadcast.ts';
+
+const PAGE_PATH = '/proxy/network/integration/v1/sites/site-1/wifi/broadcasts';
+
+// A fabricated sentinel, not a real WiFi passphrase (kit is PUBLIC — see fake-unifi.ts).
+const SENTINEL = 'sentinel-wpa-passphrase-do-not-log-me';
+
+const PROPS: WifiBroadcastProps = {
+  siteId: 'site-1',
+  wifiBroadcastId: 'wifi-1',
+  name: 'Guest',
+  enabled: true,
+  type: 'STANDARD',
+  securityConfiguration: { type: 'WPA_PERSONAL' },
+};
+
+/**
+ * One base row per nested location a stray key could hide in — red team, IMPORTANT-1 (2026-09-26):
+ * the original version of this file only planted the sentinel on `securityConfiguration` itself
+ * and missed that `sortedRefs`/`network`/`hotspotConfiguration`/`broadcastingDeviceFilter` all
+ * passed their OWN object through unchanged (`network`/`hotspotConfiguration` assigned directly;
+ * `presharedKeyNetworkIds` elements returned as received; `broadcastingDeviceFilter` spread with
+ * `{...value}`). Each case below plants the SAME sentinel in a different one of those four spots —
+ * `IntegrationWifiPresharedKeyDto`'s own shape (`{network, passphrase}`, SDK `wifi_broadcasts.ts`)
+ * is exactly why a `presharedKeyNetworkIds` element is the most plausible leak site of the four.
+ */
+const baseRow = {
+  enabled: true,
+  id: 'wifi-1',
+  metadata: { origin: 'USER' },
+  name: 'Guest',
+  type: 'STANDARD',
+};
+
+const NESTED_SENTINEL_CASES: Record<string, unknown> = {
+  'top-level securityConfiguration': {
+    ...baseRow,
+    securityConfiguration: {
+      type: 'WPA_PERSONAL',
+      presharedKeyNetworkIds: [{ type: 'VLAN' }],
+      passphrase: SENTINEL,
+    },
+  },
+  'a presharedKeyNetworkIds element (IntegrationWifiPresharedKeyDto shape)': {
+    ...baseRow,
+    securityConfiguration: {
+      type: 'WPA_PERSONAL',
+      presharedKeyNetworkIds: [{ type: 'VLAN', networkId: 'net-1', passphrase: SENTINEL }],
+    },
+  },
+  network: {
+    ...baseRow,
+    network: { type: 'STANDARD', networkId: 'net-1', passphrase: SENTINEL },
+    securityConfiguration: { type: 'WPA_PERSONAL' },
+  },
+  hotspotConfiguration: {
+    ...baseRow,
+    hotspotConfiguration: { type: 'PASSPOINT', radiusSharedSecret: SENTINEL },
+    securityConfiguration: { type: 'WPA_PERSONAL' },
+  },
+  broadcastingDeviceFilter: {
+    ...baseRow,
+    broadcastingDeviceFilter: {
+      type: 'CUSTOM',
+      deviceIds: ['dev-1'],
+      radiusSharedSecret: SENTINEL,
+    },
+    securityConfiguration: { type: 'WPA_PERSONAL' },
+  },
+};
+
+describe('T23 — a stray passphrase-shaped key on the wire never survives fetch -> attrs -> declare -> render', () => {
+  for (const [label, rawRow] of Object.entries(NESTED_SENTINEL_CASES)) {
+    test(`sentinel-passphrase test: ${label}`, async () => {
+      const fake = fakeUnifi((method, url) =>
+        method === 'GET' && url.pathname === PAGE_PATH
+          ? Response.json({ count: 1, data: [rawRow], limit: 1, offset: 0, totalCount: 1 })
+          : new Response('unexpected request', { status: 400 }),
+      );
+      const live = await Effect.runPromise(
+        spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+      );
+
+      // ⚠️ FETCH: documents the real risk, rather than assuming it away — nothing in
+      //   `@distilled.cloud/core`'s wire key-mapping strips a key the schema does not declare (see
+      //   `wifi-broadcast-form.ts`'s header). If this assertion ever starts failing because a future
+      //   core/SDK regen DOES start stripping unknown keys, that is a welcome, stronger guarantee —
+      //   not a reason this test needs to keep asserting the weaker one.
+      expect(JSON.stringify(live)).toContain(SENTINEL);
+      if (live === undefined) throw new Error('expected the fake page to decode a row');
+
+      // ATTRS: `attributesOf` rebuilds every nested object field by field (never `{...live}`,
+      // never assigning a nested object through unchanged).
+      const attrs = attributesOf(live, PROPS);
+      expect(JSON.stringify(attrs)).not.toContain(SENTINEL);
+
+      // DECLARE: `declareWifiBroadcast` is the same discipline, independently.
+      const declared = declareWifiBroadcast(live, 'site-1');
+      expect(JSON.stringify(declared)).not.toContain(SENTINEL);
+
+      // RENDER: the literal text a later import script would write into `alchemy.run.ts`.
+      const rendered = `wifiBroadcast(${JSON.stringify('wifi-1')}, ${JSON.stringify(declared)})`;
+      expect(rendered).not.toContain(SENTINEL);
+    });
+  }
+
+  test('forced decode-failure test: a malformed page body fails typed, without echoing the sentinel', async () => {
+    // A non-JSON 200 body (a genuine decode failure, not a mapped HTTP error) that happens to
+    // CONTAIN a sentinel value, the way a garbled proxy/debug response might. `getWifiBroadcastPage`
+    // has no schema to reject this against (see `wifi-broadcast-form.ts`'s header) — it decodes as
+    // the raw string, which fails `pageAll`'s own OWN consistency check instead (`paginate.ts`):
+    // the fake "page" has no `.offset`, so the walk cannot proceed and refuses to trust it.
+    const fake = fakeUnifi(() => new Response(`malformed body ${SENTINEL}`, { status: 200 }));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+
+    expect(failure._tag).toBe('UnifiPaginationInconsistent');
+    // The error's OWN fields (`reason`/`detail`) are built entirely from offsets and counts
+    // (`paginate.ts`) — never from the raw response body — so neither they nor the `.message`
+    // getter built from them can ever echo the sentinel, regardless of what garbled text arrived.
+    expect(JSON.stringify(failure)).not.toContain(SENTINEL);
+    expect((failure as { message: string }).message).not.toContain(SENTINEL);
+  });
+});

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

@@ -0,0 +1,155 @@
+/**
+ * `Unifi.WifiBroadcast`'s `spec` against a fake UniFi Network API, proving the real distilled wire
+ * path THROUGH `pageAll` (path assembly, JSON decode, `NotFound` folding, the pagination walk this
+ * family is the first resource to actually need), the declaration renderer, and — the task's own
+ * requirement — that no handler this family exposes ever sends a non-`GET` request.
+ *
+ * ⚠️ THE PASSPHRASE-SPECIFIC PROOFS (T23 sentinel + forced-decode-failure) LIVE IN
+ *   `wifi-broadcast-secrets.test.ts`, SPLIT OUT — same reason `errors-and-secrets.test.ts` is its
+ *   own file rather than folded into `network.test.ts`: keeps this file under the house line cap
+ *   and keeps the security-critical assertions in one place a reviewer can find by name.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as wifiBroadcasts from '@distilled.cloud/unifi-network/wifi_broadcasts';
+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 './wifi-broadcast-form.ts';
+import { matches } from './wifi-broadcast-drift.ts';
+import { type WifiBroadcastProps, declareWifiBroadcast, spec } from './wifi-broadcast.ts';
+import { unifiOperations } from './resource.ts';
+
+const PAGE_PATH = '/proxy/network/integration/v1/sites/site-1/wifi/broadcasts';
+
+const liveOverview = (
+  overrides: Partial<wifiBroadcasts.WifiBroadcastOverview> = {},
+): wifiBroadcasts.WifiBroadcastOverview => ({
+  enabled: true,
+  id: 'wifi-1',
+  metadata: { origin: 'USER' },
+  name: 'Guest',
+  type: 'STANDARD',
+  securityConfiguration: { type: 'WPA_PERSONAL', presharedKeyNetworkIds: [{ type: 'VLAN' }] },
+  ...overrides,
+});
+
+const PROPS: WifiBroadcastProps = {
+  siteId: 'site-1',
+  wifiBroadcastId: 'wifi-1',
+  name: 'Guest',
+  enabled: true,
+  type: 'STANDARD',
+  securityConfiguration: { type: 'WPA_PERSONAL', presharedKeyNetworkIds: [{ type: 'VLAN' }] },
+};
+
+/** One page's worth of the shared list envelope every UniFi list op answers. `total` is the
+ *  FULL row count across every page, never just this page's own `rows.length` -- pageAll stops
+ *  once `offset` reaches it (`paginate.ts`), so getting this wrong silently truncates the walk. */
+const pageResponse = (
+  rows: readonly wifiBroadcasts.WifiBroadcastOverview[],
+  offset: number,
+  total = rows.length,
+) =>
+  Response.json({
+    count: rows.length,
+    data: rows,
+    limit: rows.length || 1,
+    offset,
+    totalCount: total,
+  });
+
+describe('Unifi.WifiBroadcast spec.fetchLive', () => {
+  test('a single-page GET response decodes and finds the matching row', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === PAGE_PATH
+        ? pageResponse([liveOverview()], 0)
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('wifi-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: `${PAGE_PATH}?offset=0` }]);
+  });
+
+  test('the row can be on a LATER page -- pageAll actually walks (T9/B0b)', async () => {
+    const rows = [liveOverview({ id: 'wifi-0', name: 'Other' }), liveOverview({ id: 'wifi-1' })];
+    const fake = fakeUnifi((method, url) => {
+      if (method !== 'GET' || url.pathname !== PAGE_PATH) return fakeFailure(400, 'unexpected');
+      const offset = Number(url.searchParams.get('offset') ?? '0');
+      return pageResponse(rows.slice(offset, offset + 1), offset, rows.length);
+    });
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('wifi-1');
+    expect(fake.seen.length).toBeGreaterThan(1);
+  });
+
+  test('present rows but no matching id folds to undefined -- no separate "not found" signal', async () => {
+    const fake = fakeUnifi(() => pageResponse([liveOverview({ id: 'someone-else' })], 0));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a genuine 404 (site not found) 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', async () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 indefinitely with backoff -- this test
+    //   asserts the FAILURE, not the retry schedule (same reason `network.test.ts`'s 500 test needs it).
+    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('declareWifiBroadcast -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveOverview({ name: 'Employees', enabled: false });
+    const declared = declareWifiBroadcast(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+describe('Unifi.WifiBroadcast write paths never reach the vendor API', () => {
+  const ops = unifiOperations(spec);
+
+  test('reconcile on an exact-match adoption (H6) sends only GETs', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === PAGE_PATH
+        ? pageResponse([liveOverview()], 0)
+        : 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('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === PAGE_PATH
+        ? pageResponse([liveOverview()], 0)
+        : 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/wifi-broadcast.ts

@@ -0,0 +1,90 @@
+/**
+ * `Unifi.WifiBroadcast` — one WiFi network (SSID) broadcast on a UniFi Network site, READ-ONLY
+ * (`policy.ts`).
+ *
+ * ⛔ T23, THE REASON THIS FAMILY NEVER CALLS `getWifiBroadcastDetails`. That single-object GET
+ *   returns `WifiBroadcastDetails`, whose `securityConfiguration`
+ *   (`WifiSecurityConfigurationDetailObject`) carries the WPA passphrase AND every PPSK entry's
+ *   passphrase — the pinned spec has NO `writeOnly` flag on either (verified: 4 `passphrase`
+ *   props, 0 `writeOnly`; A2 already redacts them to `Redacted.Redacted<string>` at the SDK layer,
+ *   `errors-and-secrets.test.ts`). This family goes further and never fetches that shape AT ALL:
+ *   the only call below is `getWifiBroadcastPage`, which answers `WifiBroadcastOverview` instead —
+ *   whose own `securityConfiguration` (`WifiSecurityConfigurationOverview`) is `{type,
+ *   presharedKeyNetworkIds}`. No passphrase field exists in that type, so `WifiBroadcastProps`/
+ *   `Attributes` (`wifi-broadcast-form.ts`) cannot carry one even by a future mistake.
+ *
+ * ⚠️ NO GET-BY-ID CALL EXISTS FOR THE OVERVIEW SHAPE — unlike every other family in this
+ *   directory (`getNetworkDetails`, `getFirewallZone`, `getDnsPolicy`, `getAclRule`),
+ *   `wifi_broadcasts.ts` only has `getWifiBroadcastPage` (list) and `getWifiBroadcastDetails`
+ *   (single, passphrase-bearing — forbidden above). `fetchLive` below walks every page with B0b's
+ *   `pageAll` and finds the one row matching `wifiBroadcastId` — the first real resource-level
+ *   consumer of that pager (previously exercised only by `paginate.test.ts` in isolation).
+ *
+ * ⚠️ THE `NotFound` CATCH BELOW IS FOR THE WHOLE WALK, NOT JUST THE FIRST PAGE CALL (red team,
+ *   MINOR-4, 2026-09-26 — corrected from an earlier claim that it only applied to the first call).
+ *   `pageAll` makes its sequential page calls inside one Effect pipeline, and `catchTag` here wraps
+ *   that entire pipeline; a 404 on ANY page of the walk — not only the first — folds to `undefined`
+ *   and discards whatever rows the walk had already collected. In practice this means "the site
+ *   vanished partway through listing its broadcasts" is indistinguishable from "the site was never
+ *   there" and from "the target id just isn't among the collected rows" — none of these three cases
+ *   has a separate vendor signal, and no other family's `fetchLive` distinguishes its own analogous
+ *   cases either. Read-only reporting treats all three the same conservative way (absent, not an
+ *   error); a write path would need to tell them apart.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as wifiBroadcasts from '@distilled.cloud/unifi-network/wifi_broadcasts';
+import * as Effect from 'effect/Effect';
+import {
+  type WifiBroadcastAttributes,
+  type WifiBroadcastProps,
+  attributesOf,
+} from './wifi-broadcast-form.ts';
+import { matches } from './wifi-broadcast-drift.ts';
+import { type UnifiPaginationInconsistent, pageAll } from './paginate.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { WifiBroadcastAttributes, WifiBroadcastProps } from './wifi-broadcast-form.ts';
+export { declareWifiBroadcast } from './wifi-broadcast-form.ts';
+export { driftOf } from './wifi-broadcast-drift.ts';
+
+export interface UnifiWifiBroadcast extends Resource<
+  'Unifi.WifiBroadcast',
+  WifiBroadcastProps,
+  WifiBroadcastAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiWifiBroadcast = Resource<UnifiWifiBroadcast>('Unifi.WifiBroadcast', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `wifiBroadcast('guest', props)` — `adopt(true)` piped on by default (H5); see `network.ts`. */
+export const wifiBroadcast = (id: string, props: WifiBroadcastProps) =>
+  UnifiWifiBroadcast(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  WifiBroadcastProps,
+  wifiBroadcasts.WifiBroadcastOverview,
+  WifiBroadcastAttributes,
+  wifiBroadcasts.GetWifiBroadcastPageError | UnifiPaginationInconsistent
+> = {
+  type: 'Unifi.WifiBroadcast',
+  describe: (props) => `sites/${props.siteId}/wifi/broadcasts/${props.wifiBroadcastId}`,
+  fetchLive: (props) =>
+    pageAll(wifiBroadcasts.getWifiBroadcastPage, { siteId: props.siteId }).pipe(
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+      Effect.map((rows) => rows?.find((row) => row.id === props.wifiBroadcastId)),
+    ),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiWifiBroadcastProvider = () =>
+  Provider.effect(UnifiWifiBroadcast, Effect.succeed(UnifiWifiBroadcast.Provider.of(handlers)));