@homeflare/alchemy 0.50.0 → 0.51.0

package/src/unifi/wire-guard-round2.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Red team round 2 on PR 377, against the wire guard: an OUTER `RequestInit` that tries to turn
+ * redirects back on (F2), a consumer transform that replaces `manual` (F3, the response-URL
+ * backstop) and a query parameter added with `setUrlParam` (F5). Real `Bun.serve` + real fetch.
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { networkAllowedWrite } from './network.ts';
+import { UnifiRefusedRequest, guardedHttpClient } from './wire-guard.ts';
+
+const hits: Array<{ method: string; path: string }> = [];
+const server = Bun.serve({
+  port: 0,
+  hostname: '127.0.0.1',
+  fetch(req) {
+    const u = new URL(req.url);
+    hits.push({ method: req.method, path: u.pathname + u.search });
+    return u.pathname.endsWith('/networks/n')
+      ? new Response(null, {
+          status: 307,
+          headers: { location: '/elsewhere/v1/sites/s/networks/O' },
+        })
+      : Response.json({ ok: true });
+  },
+});
+afterAll(() => server.stop(true));
+
+const BASE = `http://127.0.0.1:${server.port}/proxy/network/integration`;
+const ALLOW = [networkAllowedWrite({ siteId: 's', networkId: 'n' } as never)];
+const PUT = () =>
+  HttpClientRequest.put(`${BASE}/v1/sites/s/networks/n`).pipe(
+    HttpClientRequest.bodyText('{"x":1}', 'application/json'),
+  );
+
+const defectOf = (exit: Exit.Exit<unknown, unknown>) => {
+  expect(Exit.isFailure(exit)).toBe(true);
+  if (!Exit.isFailure(exit)) throw new Error('unreachable');
+  expect(Cause.hasDies(exit.cause)).toBe(true);
+  const defect = Cause.squash(exit.cause);
+  expect(defect).toBeInstanceOf(UnifiRefusedRequest);
+  return defect as UnifiRefusedRequest;
+};
+
+describe('an OUTER RequestInit that asks to follow redirects (F2)', () => {
+  test('redirect stays manual, and keepalive plus a tls option still reach fetch', async () => {
+    hits.length = 0;
+    const inits: Array<RequestInit & { tls?: unknown }> = [];
+    const spy = ((url: string | URL | Request, init?: RequestInit) => {
+      inits.push((init ?? {}) as RequestInit);
+      return fetch(url, init);
+    }) as typeof fetch;
+    const exit = await Effect.runPromiseExit(
+      HttpClient.HttpClient.pipe(
+        Effect.flatMap((client) => client.execute(PUT())),
+        Effect.provide(guardedHttpClient(ALLOW, BASE)),
+        Effect.provideService(FetchHttpClient.RequestInit, {
+          redirect: 'follow',
+          keepalive: true,
+          tls: { rejectUnauthorized: false },
+        } as never),
+        Effect.provideService(FetchHttpClient.Fetch, spy),
+        Effect.provide(FetchHttpClient.layer),
+      ),
+    );
+    expect(defectOf(exit).message).toContain('307 redirect');
+    expect(hits).toHaveLength(1);
+    expect(inits).toHaveLength(1);
+    expect(inits[0]?.redirect).toBe('manual');
+    expect(inits[0]?.keepalive).toBe(true);
+    expect(inits[0]?.tls).toEqual({ rejectUnauthorized: false });
+  });
+});
+
+describe('a consumer transform that replaces RequestInit without merging (F3 backstop)', () => {
+  test('a followed redirect dies on the response URL, even though manual was lost', async () => {
+    hits.length = 0;
+    const consumer = Layer.effect(
+      HttpClient.HttpClient,
+      Effect.map(HttpClient.HttpClient, (client) =>
+        HttpClient.transform(client, (effect) =>
+          Effect.provideService(effect, FetchHttpClient.RequestInit, { redirect: 'follow' }),
+        ),
+      ),
+    ).pipe(Layer.provide(FetchHttpClient.layer));
+    const exit = await Effect.runPromiseExit(
+      HttpClient.HttpClient.pipe(
+        Effect.flatMap((client) => client.execute(PUT())),
+        Effect.provide(guardedHttpClient(ALLOW, BASE)),
+        Effect.provide(consumer),
+      ),
+    );
+    // The redirect WAS followed (the consumer's transform won), so a second request hit the server...
+    expect(hits.map((h) => h.path)).toContain('/elsewhere/v1/sites/s/networks/O');
+    // ...but the guard refuses to hand the answer back as a success.
+    expect(defectOf(exit).message).toContain('response URL differs');
+  });
+});
+
+describe('query parameters added with setUrlParam (F5)', () => {
+  test('a PUT with ?force=true built by setUrlParam is refused before the transport', async () => {
+    hits.length = 0;
+    const exit = await Effect.runPromiseExit(
+      HttpClient.HttpClient.pipe(
+        Effect.flatMap((client) =>
+          client.execute(PUT().pipe(HttpClientRequest.setUrlParam('force', 'true'))),
+        ),
+        Effect.provide(guardedHttpClient(ALLOW, BASE)),
+        Effect.provide(FetchHttpClient.layer),
+      ),
+    );
+    defectOf(exit);
+    expect(hits).toEqual([]);
+  });
+});

package/src/unifi/wire-guard.test.ts

@@ -0,0 +1,218 @@
+/**
+ * `guardedHttpClient` (`wire-guard.ts`, B0a/T12) in isolation — against a bare `HttpClient`
+ * service, no `CredentialsFromEnv`, no real SDK operation — plus its installation in
+ * `unifiHandlers`. A `GET` reaches the wrapped transport; any other method dies with
+ * `UnifiRefusedRequest` BEFORE the fake server sees it (`fake.seen` stays empty) unless the row's
+ * allow entry names exactly that `(method, path)`.
+ *
+ * ⚠️ HISTORY (2026-09-26, red team, IMPORTANT-1): deleting `Effect.provide(GetOnlyHttpClient)` from
+ *   `withCredentials` once left every test green, because the family tests call `unifiOperations`
+ *   directly and bypass `unifiHandlers`. The `unifiHandlers` block below drives the real handler
+ *   entry points through a `ConfigProvider` override (the pattern `opnsense/write-refusal.test.ts`
+ *   uses for `CredentialsFromEnv`), so it fails if a guard is ever removed from `withCredentials`.
+ * ★ `fakeUnifi` records `seen` BEFORE calling `route`, so even a route that would throw still proves
+ *   whether the guard let a request through — the assertions are on `seen`, never on a caught throw.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/http/HttpClient';
+import type * as HttpClientError from 'effect/http/HttpClientError';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { FAKE_BASE, FAKE_KEY, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { networkAllowedWrite } from './network.ts';
+import { type UnifiSpec, unifiHandlers } from './resource.ts';
+import { GetOnlyHttpClient, UnifiRefusedRequest, guardedHttpClient } from './wire-guard.ts';
+
+const ROOT = '/proxy/network/integration';
+const NET_PATH = `${ROOT}/v1/sites/s/networks/n`;
+const ALLOW = [networkAllowedWrite({ siteId: 's', networkId: 'n' } as never)];
+const url = (path: string) => `https://unifi.example.com${path}`;
+
+const send = (
+  method: string,
+  path: string,
+  fetchFn: typeof globalThis.fetch,
+  guard: Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient>,
+) =>
+  Effect.runPromiseExit(
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      return yield* client.execute(HttpClientRequest.make(method as never)(url(path)));
+    }).pipe(Effect.provide(guard), Effect.provide(fakeUnifiLayer(fetchFn))),
+  );
+
+const expectRefused = (exit: Exit.Exit<unknown, unknown>, method?: string) => {
+  expect(Exit.isFailure(exit)).toBe(true);
+  if (!Exit.isFailure(exit)) return;
+  expect(Cause.hasDies(exit.cause)).toBe(true);
+  expect(Cause.hasFails(exit.cause)).toBe(false);
+  const defect = Cause.squash(exit.cause);
+  expect(defect).toBeInstanceOf(UnifiRefusedRequest);
+  if (method) expect((defect as UnifiRefusedRequest).method).toBe(method);
+};
+
+const neverReached = (what: string) =>
+  fakeUnifi(() => {
+    throw new Error(`wire-guard.test.ts: unexpected ${what} reached the fake transport`);
+  });
+
+describe('GetOnlyHttpClient (empty allow list)', () => {
+  test("a GET passes through and reaches the transport under redirect: 'manual' (LOW-7)", async () => {
+    const fake = fakeUnifi(() => Response.json({ ok: true }));
+    const exit = await send('GET', `${ROOT}/v1/sites/s/networks`, fake.fetch, GetOnlyHttpClient);
+    expect(Exit.isSuccess(exit)).toBe(true);
+    // 'manual' on GETs is DELIBERATE since 2026-10-10: the response guard refuses a GET's 3xx too,
+    // and under the default 'follow' the guard would never see it (the redirect would be followed).
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: `${ROOT}/v1/sites/s/networks`, redirect: 'manual' },
+    ]);
+  });
+
+  test.each(['POST', 'PUT', 'PATCH', 'DELETE'])('%s dies before the transport', async (method) => {
+    const fake = neverReached(method);
+    expectRefused(await send(method, NET_PATH, fake.fetch, GetOnlyHttpClient), method);
+    // ⛔ THE PROOF: the transport never recorded the call -- refused in `mapRequestEffect`.
+    expect(fake.seen).toEqual([]);
+  });
+});
+
+describe('guardedHttpClient with the row allow entry', () => {
+  test('the one PUT to this row reaches the transport, with fetch redirect: manual', async () => {
+    const fake = fakeUnifi(() => Response.json({ ok: true }));
+    const exit = await send('PUT', NET_PATH, fake.fetch, guardedHttpClient(ALLOW, FAKE_BASE));
+    expect(Exit.isSuccess(exit)).toBe(true);
+    expect(fake.seen).toEqual([{ method: 'PUT', path: NET_PATH, redirect: 'manual' }]);
+  });
+
+  test.each([
+    ['the list route', 'PUT', `${ROOT}/v1/sites/s/networks`],
+    ['another network id', 'PUT', `${ROOT}/v1/sites/s/networks/other`],
+    ['an id this one is a prefix of', 'PUT', `${ROOT}/v1/sites/s/networks/n2`],
+    ['a sub-route of this network', 'PUT', `${NET_PATH}/extra`],
+    ['an id this one is a suffix of', 'PUT', `${ROOT}/v1/sites/s/networks/xn`],
+    ['another site', 'PUT', `${ROOT}/v1/sites/t/networks/n`],
+    ['another family', 'PUT', `${ROOT}/v1/sites/s/firewall/zones/z`],
+    ['POST on the row path', 'POST', NET_PATH],
+    ['PATCH on the row path', 'PATCH', NET_PATH],
+    ['DELETE on the row path', 'DELETE', NET_PATH],
+  ])('%s dies before the transport', async (_name, method, path) => {
+    const fake = neverReached(`${method} ${path}`);
+    expectRefused(
+      await send(method, path, fake.fetch, guardedHttpClient(ALLOW, FAKE_BASE)),
+      method,
+    );
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('a 307 answer to the allowed PUT dies after exactly one request, never followed', async () => {
+    const fake = fakeUnifi(
+      () => new Response(null, { status: 307, headers: { location: 'https://evil.example/x' } }),
+    );
+    expectRefused(
+      await send('PUT', NET_PATH, fake.fetch, guardedHttpClient(ALLOW, FAKE_BASE)),
+      'PUT',
+    );
+    expect(fake.seen).toHaveLength(1);
+    expect(fake.seen[0]?.redirect).toBe('manual');
+  });
+});
+
+interface ProbeProps {
+  id: string;
+}
+
+/** A `fetchLive` that sends one raw request of the given method (not a real SDK operation). */
+const probeSpec = (
+  method: string,
+  withUpdate = false,
+): UnifiSpec<ProbeProps, ProbeProps, ProbeProps, HttpClientError.HttpClientError> => ({
+  type: 'Test.Probe',
+  describe: (props) => `probe/${props.id}`,
+  fetchLive: (props) =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      yield* client.execute(HttpClientRequest.make(method as never)(`${FAKE_BASE}/probe`));
+      return props;
+    }),
+  attributes: (live) => live,
+  matches: () => true,
+  ...(withUpdate
+    ? {
+        update: {
+          allowedWrite: () => ({ method: 'PUT' as const, tail: '/probe' }),
+          patchKeys: [],
+          driftOf: () => [],
+          checkScope: () => Effect.void,
+          write: (live: ProbeProps) => Effect.succeed(live),
+        },
+      }
+    : {}),
+});
+
+const configProvider = ConfigProvider.layer(
+  ConfigProvider.fromUnknown({
+    UNIFI_NETWORK_API_BASE_URL: FAKE_BASE,
+    UNIFI_NETWORK_API_KEY: FAKE_KEY,
+  }),
+);
+const session = { note: () => Effect.void };
+const args = { news: { id: 'w1' }, olds: undefined, output: undefined, session };
+
+const runHandler = <A, E>(
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+  fetchFn: typeof globalThis.fetch,
+): Promise<Exit.Exit<A, E>> =>
+  Effect.runPromiseExit(
+    effect.pipe(Effect.provide(Layer.mergeAll(fakeUnifiLayer(fetchFn), configProvider))) as never,
+  ) as never;
+
+describe('guards are installed in unifiHandlers (IMPORTANT-1, red team 2026-09-26)', () => {
+  test('a GET through the real read entry point reaches the transport', async () => {
+    const fake = fakeUnifi(() => Response.json({ id: 'w1' }));
+    const exit = await runHandler(
+      unifiHandlers(probeSpec('GET')).read({ olds: { id: 'w1' }, output: undefined }),
+      fake.fetch,
+    );
+    expect(Exit.isSuccess(exit)).toBe(true);
+    expect(fake.seen).toEqual([{ method: 'GET', path: `${ROOT}/probe`, redirect: 'manual' }]);
+  });
+
+  test('read dies on a PUT even when the spec declares update (guard scope is reconcile only)', async () => {
+    const fake = neverReached('PUT');
+    const exit = await runHandler(
+      unifiHandlers(probeSpec('PUT', true)).read({ olds: { id: 'w1' }, output: undefined }),
+      fake.fetch,
+    );
+    expectRefused(exit, 'PUT');
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('reconcile dies on a PUT when the spec has no update (firewall-zone style)', async () => {
+    const fake = neverReached('PUT');
+    expectRefused(await runHandler(unifiHandlers(probeSpec('PUT')).reconcile(args), fake.fetch));
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('reconcile lets the allowed PUT through when the spec declares update', async () => {
+    const fake = fakeUnifi(() => Response.json({ id: 'w1' }));
+    const exit = await runHandler(
+      unifiHandlers(probeSpec('PUT', true)).reconcile(args),
+      fake.fetch,
+    );
+    expect(Exit.isSuccess(exit)).toBe(true);
+    expect(fake.seen.map((s) => s.method)).toEqual(['PUT']);
+  });
+
+  test('reconcile still dies on a POST even when the spec declares update', async () => {
+    const fake = neverReached('POST');
+    expectRefused(
+      await runHandler(unifiHandlers(probeSpec('POST', true)).reconcile(args), fake.fetch),
+      'POST',
+    );
+    expect(fake.seen).toEqual([]);
+  });
+});

package/src/unifi/wire-guard.ts

@@ -0,0 +1,192 @@
+/**
+ * B0a / T12 DEFENSE IN DEPTH, AT THE WIRE. `policy.ts`'s `UnifiWriteRefused` stops write INTENT at
+ * `reconcile`/`destroy`; this guard stops the same thing one layer lower. It wraps whatever
+ * `HttpClient` the caller already provides (the stack's `FetchHttpClient.layer` in production,
+ * `fakeUnifiLayer` in tests — `openbao/bao-http.ts`'s header names this same "wrap, don't
+ * replace" seam), so an SDK write operation called by mistake, bypassing `unifiOperations`, still
+ * never reaches the vendor API. `write-op-reference.test.ts` proves no such call exists outside
+ * `network-update.ts`; this is what stops one from ever taking effect.
+ *
+ * ★ A GET ALWAYS PASSES THE REQUEST GUARD; ANY OTHER METHOD PASSES ONLY WHEN `(method, pathname)`
+ *   MATCHES AN ENTRY OF THE `allow` LIST. `unifiHandlers` builds that list PER ROW
+ *   (`spec.update.allowedWrite(news)`): the one PUT that can pass is to this row's own
+ *   `/v1/sites/<siteId>/networks/<networkId>` under the CONFIGURED base URL (local and
+ *   cloud-connector base paths differ, so the base is passed in and compared exactly, `isAllowed`).
+ *   A PUT to another network id, the list route, or another family dies here.
+ *
+ * ⚠️ `Effect.die`, NOT A TYPED FAILURE — every generated SDK operation declares its OWN closed
+ *   error union from the pinned OpenAPI spec and generated files are never hand-edited, so a typed
+ *   `Effect.fail` here would be a failure absent from every op's declared type. A defect is the
+ *   sound way to add a "structurally impossible" failure underneath types this package does not
+ *   own, like `openbao`'s `refuse()` helpers.
+ *
+ * ⛔ REDIRECTS (LOW-7), REFUSED FOR EVERY METHOD — GETs included, 2026-10-10. The layer sets fetch
+ *   `redirect: 'manual'` on EVERY guarded request and the guard dies on any 3xx answer. Default
+ *   fetch follows a redirect and re-sends the request to a `Location` this guard never saw — a PUT
+ *   with its body on 307/308, a GET still carrying the API-key header — so following is never
+ *   safe. Scoping `manual` to a non-empty allow list (the pre-2026-10-10 shape) also made the two
+ *   postures DIVERGE by accident: reconcile's own GETs ran manual, so a 3xx surfaced raw and failed
+ *   the SDK decode, while read/diff under `GetOnlyHttpClient` followed the redirect silently. One
+ *   rule for both postures now: a redirect is refused everywhere, fail closed.
+ */
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import type * as HttpClientResponse from 'effect/http/HttpClientResponse';
+import { UNIFI_WRITE_POLICY } from './policy.ts';
+
+/**
+ * One non-GET request the guard may let through. `tail` is the exact route below the configured
+ * base URL (`/v1/sites/<site>/networks/<id>`): the guard compares the request's origin and path to
+ * `baseUrl + tail` and requires an empty query and fragment (`isAllowed`).
+ */
+export type AllowedWrite = { readonly method: 'PUT'; readonly tail: string };
+
+export class UnifiRefusedRequest extends Error {
+  constructor(
+    readonly method: string,
+    /** PATH ONLY, never the full URL — see `requestPath` below. */
+    readonly path: string,
+    detail = "not on this row's allow list",
+  ) {
+    super(
+      `UniFi HttpClient guard: refused ${method} ${path} (${detail}) -- ${UNIFI_WRITE_POLICY}. ` +
+        'This is a defect, not a recoverable condition: something under src/unifi sent a request ' +
+        "policy.ts's per-operation refusal should already have made impossible. Fix the kit " +
+        'code that produced this request.',
+    );
+    this.name = 'UnifiRefusedRequest';
+  }
+}
+
+/** @deprecated renamed `UnifiRefusedRequest`; kept so existing consumer imports do not break. */
+export const UnifiNonGetRequest = UnifiRefusedRequest;
+export type UnifiNonGetRequest = UnifiRefusedRequest;
+
+/**
+ * ⛔ PATH ONLY, NEVER THE HOST. A cloud connector's base URL embeds the account's Console ID
+ *   (`docs/unifi.md`'s Credentials section, T3) — a defect message can still reach a log or a CI
+ *   failure body. Falls back to a fixed placeholder on a parse failure so a malformed URL can
+ *   never leak through unredacted.
+ */
+const requestPath = (url: string): string => {
+  try {
+    // ⛔ The cloud connector path is `/v1/connector/consoles/<consoleId>/...`: the id is dropped too.
+    return new URL(url).pathname.replace(/(\/consoles\/)[^/]*/g, '$1<redacted>');
+  } catch {
+    return '<unparseable request url>';
+  }
+};
+
+/**
+ * ⛔ ANCHORED TO THE CONFIGURED BASE URL, NOT A SUFFIX. The request must share the base's origin,
+ *   its path must be exactly `<base path><tail>` (so `//v1/...`, another base path or a nested
+ *   `/v1/sites/X/v1/sites/s/...` all miss), and it must carry no query or fragment (`?force=true`).
+ *   Without a base URL nothing is allowed: fail closed.
+ */
+const isAllowed = (
+  allow: ReadonlyArray<AllowedWrite>,
+  baseUrl: string | undefined,
+  method: string,
+  request: HttpClientRequest.HttpClientRequest,
+) => {
+  if (baseUrl === undefined) return false;
+  try {
+    const base = new URL(baseUrl);
+    // ⛔ `toUrl`, NOT `request.url`: `setUrlParam` keeps its parameters OUTSIDE `request.url`, so
+    //   the bare string looked query-free while the wire request carried `?force=true` (round 2, F5).
+    const resolved = HttpClientRequest.toUrl(request);
+    if (Option.isNone(resolved)) return false;
+    const target = resolved.value;
+    if (target.origin !== base.origin || target.search !== '' || target.hash !== '') return false;
+    const basePath = base.pathname.replace(/\/+$/, '');
+    return allow.some(
+      (entry) => entry.method === method && target.pathname === `${basePath}${entry.tail}`,
+    );
+  } catch {
+    return false;
+  }
+};
+
+/** True when the response says it came from a different URL than the request named. */
+const followedElsewhere = (res: HttpClientResponse.HttpClientResponse): boolean => {
+  const sent = HttpClientRequest.toUrl(res.request);
+  return res.url !== '' && Option.isSome(sent) && res.url !== sent.value.href.split('#')[0];
+};
+
+const guard = (
+  client: HttpClient.HttpClient,
+  allow: ReadonlyArray<AllowedWrite>,
+  baseUrl: string | undefined,
+) =>
+  client.pipe(
+    HttpClient.mapRequestEffect((request) =>
+      request.method === 'GET' || isAllowed(allow, baseUrl, request.method, request)
+        ? Effect.succeed(request)
+        : Effect.die(new UnifiRefusedRequest(request.method, requestPath(request.url))),
+    ),
+    HttpClient.transformResponse((response) =>
+      Effect.flatMap(response, (res) =>
+        // ⛔ ANY METHOD: a GET's 3xx is refused exactly like a PUT's — see REDIRECTS in the header.
+        res.status >= 300 && res.status < 400
+          ? Effect.die(
+              new UnifiRefusedRequest(
+                res.request.method,
+                requestPath(res.request.url),
+                `answered a ${res.status} redirect`,
+              ),
+            )
+          : // ⛔ BACKSTOP (round 2, F3): if a consumer's own transform replaced `manual` and fetch
+            //   followed a redirect, the response URL is no longer the request's. Die on that.
+            followedElsewhere(res)
+            ? Effect.die(
+                new UnifiRefusedRequest(
+                  res.request.method,
+                  requestPath(res.request.url),
+                  'the response URL differs from the request URL (a redirect was followed)',
+                ),
+              )
+            : Effect.succeed(res),
+      ),
+    ),
+  );
+
+/**
+ * A `Layer` that reads whatever `HttpClient` is already in the calling context and replaces it,
+ * for everything downstream, with the guarded version. Exported so `wire-guard.test.ts` can prove
+ * the mechanism against a bare `HttpClient`, without `CredentialsFromEnv` or any env var.
+ */
+export const guardedHttpClient = (allow: ReadonlyArray<AllowedWrite>, baseUrl?: string) => {
+  return HttpClient.layerMergedContext(
+    Effect.map(HttpClient.HttpClient, (client) =>
+      // ⛔ MANUAL REDIRECT ON BOTH POSTURES, not just an allow list: the response guard refuses a
+      //   3xx for GETs too, and under the default 'follow' a GET redirect is silently followed —
+      //   the guard would never see it, and read/diff would diverge from reconcile again.
+      HttpClient.transform(guard(client, allow, baseUrl), manualRedirect),
+    ),
+  );
+};
+
+/**
+ * ⛔ `redirect: 'manual'` IS SET PER REQUEST, ON THE CALLING FIBER'S `RequestInit`. A layer-provided
+ *   `RequestInit` is silently REPLACED by an outer one (Effect 4.0.1 `layerMergedContext` merges the
+ *   caller's context over the layer's), which would turn redirects back on. Same read-merge-provide
+ *   pattern as `openbao/bao-http.ts`'s `overSocket`; outer fetch options are kept.
+ */
+const manualRedirect = <E, R>(
+  effect: Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>,
+): Effect.Effect<HttpClientResponse.HttpClientResponse, E, R> =>
+  Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), (existing) =>
+    Effect.provideService(effect, FetchHttpClient.RequestInit, {
+      ...Option.getOrElse(existing, () => ({})),
+      redirect: 'manual',
+    }),
+  );
+
+/**
+ * No write may pass; the posture of `read`/`diff`/`delete` and of every non-updatable family. A 3xx
+ * answer to a GET is refused here exactly as under the allow-list posture — see REDIRECTS above.
+ */
+export const GetOnlyHttpClient = guardedHttpClient([]);

package/src/unifi/write-op-reference.test.ts

@@ -25,7 +25,7 @@
  */
 import { describe, expect, test } from 'bun:test';
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stripComments, walk } from './scan-source.ts';
 
@@ -54,17 +54,34 @@ const sdkWriteOpNames = (): ReadonlySet<string> => {
 
 const REAL_WRITE_OP_NAMES = sdkWriteOpNames();
 
+/**
+ * ⛔ THE ONE FILE ALLOWED TO NAME ONE WRITE OP (Tim 2026-10-10: `Unifi.Network` update). Keyed by
+ * path relative to `src/unifi`. Widening this object is a policy change — `policy.ts` — and a
+ * test below pins it to exactly this entry so it cannot grow unnoticed. Everything else the SDK
+ * exports (`createNetwork`, `deleteNetwork`, `patchFirewallPolicy`, …) stays an offense even
+ * inside the allowlisted file.
+ */
+const WRITE_OP_ALLOWLIST: Record<string, ReadonlyArray<string>> = {
+  'network-update.ts': ['updateNetwork'],
+};
+
 /** Recursive by construction (IMPORTANT-2): a future `src/unifi/<subdir>/*.ts` is walked too. */
 const sourceFiles = () => walk(DIR).filter((path) => path !== SELF);
 
 /** Every offense in one file: any real SDK write-op name appearing as a token anywhere in its
  *  comment-stripped text, GATED on the file mentioning the SDK's package specifier at all (a file
  *  that never imports it — by any syntax — cannot meaningfully reference one of its exports). */
-const offensesIn = (path: string, rawSrc: string): string[] => {
+const offensesIn = (
+  path: string,
+  rawSrc: string,
+  allowlist: Record<string, ReadonlyArray<string>> = WRITE_OP_ALLOWLIST,
+): string[] => {
   if (!rawSrc.includes(SDK_MARKER)) return [];
   const codeSrc = stripComments(rawSrc);
+  const allowed = allowlist[relative(DIR, path)] ?? [];
   const offenses: string[] = [];
   for (const name of REAL_WRITE_OP_NAMES) {
+    if (allowed.includes(name)) continue;
     if (new RegExp(`\\b${name}\\b`).test(codeSrc)) {
       offenses.push(`${path}: references SDK write op '${name}'`);
     }
@@ -169,6 +186,25 @@ describe('src/unifi never references an SDK write operation (T12)', () => {
     }
   });
 
+  test('the allowlist is exactly network-update.ts -> updateNetwork, nothing else', () => {
+    expect(WRITE_OP_ALLOWLIST).toEqual({ 'network-update.ts': ['updateNetwork'] });
+  });
+
+  test('network-update.ts may name updateNetwork but still not create/delete/patch ops', () => {
+    const path = join(DIR, 'network-update.ts');
+    const src = (op: string) => `import * as n from '${SDK_MARKER}/networks';\nn.${op}({});\n`;
+    expect(offensesIn(path, src('updateNetwork'))).toEqual([]);
+    for (const op of ['createNetwork', 'deleteNetwork', 'patchFirewallPolicy']) {
+      expect(offensesIn(path, src(op))).toEqual([`${path}: references SDK write op '${op}'`]);
+    }
+  });
+
+  test('any other file naming updateNetwork is an offense', () => {
+    const path = join(DIR, 'network.ts');
+    const src = `import * as n from '${SDK_MARKER}/networks';\nn.updateNetwork({});\n`;
+    expect(offensesIn(path, src)).toEqual([`${path}: references SDK write op 'updateNetwork'`]);
+  });
+
   test('the walk is recursive -- a future src/unifi/<subdir>/*.ts is not silently unscanned', () => {
     const probeDir = join(DIR, '.write-op-reference-recursion-probe');
     const probeFile = join(probeDir, 'nested.ts');