@homeflare/alchemy 0.49.0 → 0.51.0

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');

package/src/unifi/get-only-guard.test.ts

@@ -1,165 +0,0 @@
-/**
- * `GetOnlyHttpClient` (`resource.ts`, B0a/T12) in isolation — against a bare `HttpClient` service,
- * no `CredentialsFromEnv`, no real SDK operation. Proves the guard's own mechanism: a `GET`
- * reaches the wrapped transport unchanged, and any other method dies with `UnifiNonGetRequest`
- * BEFORE the fake server ever sees it (`fake.seen` stays empty for the refused call).
- *
- * ⚠️ NOT ROUTED THROUGH `unifiHandlers`/`CredentialsFromEnv` ON PURPOSE — see `fake-unifi.ts`'s
- *   own warning: `CredentialsFromEnv` resolves `UNIFI_NETWORK_*` through Effect's `Config`, which
- *   this directory's existing tests all avoid depending on for the same reason. Since the guard
- *   only touches the `HttpClient` service, testing it directly here is both simpler and a more
- *   precise proof of the mechanism than routing real credentials through it would be.
- * ⚠️ CORRECTION (2026-09-26, red team): the line this replaces claimed `network.test.ts`/
- *   `firewall-zone.test.ts` prove `withCredentials` lets a real GET through. They don't —
- *   both call `unifiOperations(spec)` directly, which bypasses `unifiHandlers`/`withCredentials`
- *   (and therefore this guard) entirely. Proof: deleting `Effect.provide(GetOnlyHttpClient)` from
- *   `withCredentials` (`resource.ts`) left all 56 tests green before this file's own
- *   `describe('GetOnlyHttpClient installed in unifiHandlers', …)` block below existed. THAT block
- *   is what closes the gap: it drives `unifiHandlers(...).read`/`.reconcile` — the actual exported
- *   entry points a real deploy calls — through a `ConfigProvider` override (the same pattern
- *   `opnsense/write-refusal.test.ts` uses for `CredentialsFromEnv`), so it fails if the guard is
- *   ever removed from `withCredentials` again.
- * ★ REUSES `fakeUnifi` (`fake-unifi.ts`), NOT AN AD HOC MOCK. `fakeUnifi`'s wrapper records
- *   `seen` BEFORE calling `route`, so even a `route` that would throw still proves whether the
- *   guard let a request through — the assertion is on `seen`, never on catching that 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 {
-  GetOnlyHttpClient,
-  UnifiNonGetRequest,
-  type UnifiSpec,
-  unifiHandlers,
-} from './resource.ts';
-
-const FAKE_PATH = '/proxy/network/integration/v1/sites/site-1/networks';
-const FAKE_URL = `https://unifi.example.com${FAKE_PATH}`;
-
-/** One request through `GetOnlyHttpClient`, over a fake transport built by `fakeUnifi`. */
-const sendGuarded = (method: string, fetchFn: typeof globalThis.fetch) =>
-  Effect.runPromiseExit(
-    Effect.gen(function* () {
-      const client = yield* HttpClient.HttpClient;
-      return yield* client.execute(HttpClientRequest.make(method as never)(FAKE_URL));
-    }).pipe(Effect.provide(GetOnlyHttpClient), Effect.provide(fakeUnifiLayer(fetchFn))),
-  );
-
-describe('GetOnlyHttpClient', () => {
-  test('a GET request passes through unchanged and reaches the transport', async () => {
-    const fake = fakeUnifi(() => Response.json({ ok: true }));
-
-    const exit = await sendGuarded('GET', fake.fetch);
-
-    expect(Exit.isSuccess(exit)).toBe(true);
-    expect(fake.seen).toEqual([{ method: 'GET', path: FAKE_PATH }]);
-  });
-
-  test.each(['POST', 'PUT', 'PATCH', 'DELETE'])(
-    '%s dies with UnifiNonGetRequest and never reaches the transport',
-    async (method) => {
-      const fake = fakeUnifi(() => {
-        throw new Error(`get-only-guard.test.ts: unexpected ${method} reached the fake transport`);
-      });
-
-      const exit = await sendGuarded(method, fake.fetch);
-
-      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(UnifiNonGetRequest);
-      expect((defect as UnifiNonGetRequest).method).toBe(method);
-      // ⛔ THE PROOF: the fake transport never even recorded the call -- the guard refused the
-      //   request in `mapRequestEffect`, before dispatch, not after a failed response.
-      expect(fake.seen).toEqual([]);
-    },
-  );
-});
-
-interface ProbeProps {
-  id: string;
-}
-
-/**
- * A `fetchLive` that sends exactly one raw request over whatever `method` the test wants to
- * probe — not a real SDK operation, on purpose: this block proves the GUARD'S INSTALLATION in
- * `unifiHandlers`, not any one family's own all-GET behavior (`network.test.ts`/
- * `firewall-zone.test.ts` already prove that, for calls that bypass `unifiHandlers` entirely).
- */
-const probeSpec = (
-  method: string,
-): 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,
-});
-
-/**
- * Overrides the `ConfigProvider` `CredentialsFromEnv` resolves `UNIFI_NETWORK_*` against — the
- * SAME pattern `opnsense/write-refusal.test.ts` uses for its own `CredentialsFromEnv` — WITHOUT
- * touching real `process.env` (a parallel test file could race on that). `unifiHandlers`'s
- * `withCredentials` bakes in `CredentialsFromEnv` itself, so providing a `Credentials` layer from
- * OUTSIDE (the way `fake-unifi.ts`'s own `fakeUnifiLayer` does for tests that call `spec.fetchLive`
- * directly) would be shadowed and do nothing here — this ConfigProvider override is what actually
- * reaches it.
- */
-const fakeCredentialsConfigProvider = ConfigProvider.layer(
-  ConfigProvider.fromUnknown({
-    UNIFI_NETWORK_API_BASE_URL: FAKE_BASE,
-    UNIFI_NETWORK_API_KEY: FAKE_KEY,
-  }),
-);
-
-describe('GetOnlyHttpClient is installed in unifiHandlers (IMPORTANT-1, red team 2026-09-26)', () => {
-  test('a GET through the real handler entry point still reaches the transport', async () => {
-    const fake = fakeUnifi(() => Response.json({ id: 'w1' }));
-    const attrs = await Effect.runPromise(
-      unifiHandlers(probeSpec('GET'))
-        .read({ olds: { id: 'w1' }, output: undefined })
-        .pipe(
-          Effect.provide(Layer.mergeAll(fakeUnifiLayer(fake.fetch), fakeCredentialsConfigProvider)),
-        ),
-    );
-    expect(attrs).toEqual({ id: 'w1' });
-    expect(fake.seen).toEqual([{ method: 'GET', path: '/proxy/network/integration/probe' }]);
-  });
-
-  test('a non-GET through the real handler entry point dies, never reaching the transport', async () => {
-    const fake = fakeUnifi(() => {
-      throw new Error('get-only-guard.test.ts: unexpected POST reached the fake transport');
-    });
-    const exit = await Effect.runPromiseExit(
-      unifiHandlers(probeSpec('POST'))
-        .read({ olds: { id: 'w1' }, output: undefined })
-        .pipe(
-          Effect.provide(Layer.mergeAll(fakeUnifiLayer(fake.fetch), fakeCredentialsConfigProvider)),
-        ),
-    );
-    expect(Exit.isFailure(exit)).toBe(true);
-    if (!Exit.isFailure(exit)) return;
-    expect(Cause.hasDies(exit.cause)).toBe(true);
-    expect(Cause.squash(exit.cause)).toBeInstanceOf(UnifiNonGetRequest);
-    // ⛔ THIS IS THE PROOF THE FILE HEADER PROMISES. Verified by hand (2026-09-26): deleting
-    //   `Effect.provide(GetOnlyHttpClient)` from `withCredentials` (`resource.ts`) turns this
-    //   exact test into a passing `Response.json` round-trip with a non-empty `fake.seen` --
-    //   i.e. it FAILS the instant the guard installation regresses, which no test in this
-    //   directory could do before this block existed (IMPORTANT-1).
-    expect(fake.seen).toEqual([]);
-  });
-});