@homeflare/alchemy 0.48.1 → 0.49.0

package/src/cloudflare/fake-access.ts

@@ -0,0 +1,196 @@
+/**
+ * A fake Cloudflare Access applications API for the SaasOidcApplication tests — an in-memory
+ * `fetch` handed to Effect's real FetchHttpClient (see fake-mesh.ts, which this mirrors), so the
+ * tests exercise distilled's real path assembly, body encoding and envelope decoding AND the raw
+ * read in saas-oidc-api.ts.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. Any request outside
+ *   `/accounts/<FAKE_ACCOUNT>/access/apps` throws, so a mis-wired test fails instead of reaching a
+ *   real API. Every credential-looking value is a placeholder.
+ * ★ THE WIRE IS CLOUDFLARE'S, snake_case: `saas_app`, `client_id`, `redirect_uris`… The create
+ *   response carries `saas_app.client_secret` (the SDK schema's own doc: "only returned on POST
+ *   request"); a GET and a PUT never do. So a test that asserts the secret appears nowhere is
+ *   asserting against a fake that does hand it out once.
+ * ★ THE LIST IS PAGES OF TWO by default, so every name lookup walks more than one page.
+ * ★ THE ORGANIZATION READ (`GET /access/organizations`, the pre-create team check) answers with the
+ *   fake's own team by default; `org` makes it answer a different domain, a 403 in either of the
+ *   two shapes a token without the permission can get (code 10000 and 10001, see
+ *   saas-oidc-team.ts), or a 404.
+ * ★ `malformed` makes the named calls answer a 2xx body the SDK's STRICT validation cannot decode,
+ *   with `FAKE_CLIENT_SECRET` planted in it, so a test can force `CloudflareParseError` and look
+ *   for the secret in what this package throws. ⚠️ ONLY THE CALLS rc.13 TYPES CAN BE MADE TO FAIL:
+ *   a create or update response decodes against `S.Unknown` (zero_trust.ts:35025, :210218), which
+ *   accepts anything, so those two are not offered here (saas-oidc-parse-error.test.ts reaches them
+ *   through the `sdkWrites` seam instead). `list` fails by answering an object where an array is
+ *   expected, `delete` and `org` by answering a number where the schema wants a string.
+ */
+import { FAKE_ACCOUNT, fakeFailure } from './fake-mesh.ts';
+
+export const TEAM = 'example.cloudflareaccess.com';
+/** ⚠️ A placeholder, not a credential. Tests assert it is stored and logged nowhere. */
+export const FAKE_CLIENT_SECRET = 'fake-client-secret-0123456789abcdef';
+
+export type FakeApp = {
+  id: string;
+  aud: string;
+  type: string;
+  name: string;
+  session_duration: string;
+  policies: string[];
+  saas_app?: Record<string, unknown> | undefined;
+};
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+/** The calls `malformed` can corrupt: `get` is the raw read, the rest are SDK calls. */
+export type FakeOp = 'get' | 'list' | 'delete' | 'org';
+/** How the organization read answers; an object names the `auth_domain` it returns. */
+export type FakeOrg =
+  | 'matching'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'not_found'
+  | { authDomain: string };
+
+export type FakeOptions = {
+  readonly perPage?: number;
+  readonly team?: string;
+  readonly org?: FakeOrg;
+  readonly malformed?: ReadonlyArray<FakeOp>;
+};
+
+const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
+  Response.json({ success: true, errors: [], messages: [], result, ...extra });
+
+/** The wire shape of an app: no `client_secret`, and `domain` as Cloudflare derives it. */
+const wire = (app: FakeApp, team: string) => {
+  const clientId = app.saas_app?.['client_id'];
+  const { saas_app: saas, ...rest } = app;
+  const { client_secret: _secret, ...publicSaas } = saas ?? {};
+  return {
+    ...rest,
+    domain: typeof clientId === 'string' ? `${team}/cdn-cgi/access/sso/oidc/${clientId}` : 'x.test',
+    created_at: '2026-10-09T00:00:00Z',
+    updated_at: '2026-10-09T00:00:00Z',
+    policies: app.policies.map((id, i) => ({ id, precedence: i + 1 })),
+    ...(saas === undefined ? {} : { saas_app: publicSaas }),
+  };
+};
+
+/**
+ * A 2xx `result` the typed decoders reject (`id` and `auth_domain` are numbers, and it is not an
+ * array), carrying the secret where a create puts it.
+ */
+const garbage = () => ({
+  id: 12345,
+  auth_domain: 12345,
+  client_secret: FAKE_CLIENT_SECRET,
+  saas_app: { client_secret: FAKE_CLIENT_SECRET },
+});
+
+const orgBody = (org: FakeOrg, team: string): Response => {
+  if (org === 'unauthorized') return fakeFailure(403, 10000, 'Authentication error');
+  if (org === 'forbidden') return fakeFailure(403, 10001, 'Method not allowed for token');
+  if (org === 'not_found') return fakeFailure(404, 12004, 'access.api.error.not_found');
+  const authDomain = org === 'matching' ? team : org.authDomain;
+  return ok({ auth_domain: authDomain, name: 'team', session_duration: '24h' });
+};
+
+export const fakeAccess = (options: FakeOptions = {}) => {
+  const team = options.team ?? TEAM;
+  const broken = (op: FakeOp): boolean => options.malformed?.includes(op) ?? false;
+  const apps = new Map<string, FakeApp>();
+  const seen: Seen[] = [];
+  let next = 1;
+
+  const seed = (app: Partial<FakeApp> & { name: string }): FakeApp => {
+    const n = String(next++).padStart(12, '0');
+    const full: FakeApp = {
+      id: `00000000-0000-4000-8000-${n}`,
+      aud: `aud-${n}`,
+      type: 'saas',
+      session_duration: '24h',
+      policies: [],
+      ...app,
+    };
+    if (full.type === 'saas' && full.saas_app?.['client_id'] === undefined) {
+      full.saas_app = { auth_type: 'oidc', client_id: `client-${n}`, ...full.saas_app };
+    }
+    apps.set(full.id, full);
+    return full;
+  };
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const prefix = `/client/v4/accounts/${FAKE_ACCOUNT}/access/apps`;
+    if (
+      url.host === 'api.example.com' &&
+      url.pathname === prefix.replace(/apps$/, 'organizations')
+    ) {
+      if (method !== 'GET') throw new Error(`fake-access: unexpected ${method} ${url.pathname}`);
+      return broken('org') ? ok(garbage()) : orgBody(options.org ?? 'matching', team);
+    }
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(prefix)) {
+      throw new Error(`fake-access: unexpected request ${method} ${url.href}`);
+    }
+    const id = url.pathname.slice(prefix.length).split('/').filter(Boolean)[0];
+    if (id === undefined && method === 'GET') {
+      if (broken('list')) return ok(garbage());
+      const page = Number(url.searchParams.get('page') ?? '1');
+      const perPage = Number(url.searchParams.get('per_page') ?? options.perPage ?? 2);
+      const all = [...apps.values()];
+      const slice = all.slice((page - 1) * perPage, page * perPage);
+      return ok(
+        slice.map((app) => wire(app, team)),
+        {
+          result_info: { page, per_page: perPage, count: slice.length, total_count: all.length },
+        },
+      );
+    }
+    if (id === undefined && method === 'POST') {
+      const app = seed({
+        name: String(body['name']),
+        type: String(body['type']),
+        policies: (body['policies'] as string[] | undefined) ?? [],
+        saas_app: body['saas_app'] as Record<string, unknown> | undefined,
+      });
+      // ⛔ The one response that hands the secret out, as the API does on POST.
+      const created = wire(app, team) as Record<string, unknown>;
+      created['saas_app'] = {
+        ...(created['saas_app'] as object),
+        client_secret: FAKE_CLIENT_SECRET,
+      };
+      return ok(created);
+    }
+    const app = id === undefined ? undefined : apps.get(id);
+    if (app === undefined) return fakeFailure(404, 12006, 'access.api.error.unknown_application');
+    if (method === 'GET') {
+      return broken('get') ? new Response(`not json ${FAKE_CLIENT_SECRET}`) : ok(wire(app, team));
+    }
+    if (method === 'PUT') {
+      app.name = String(body['name']);
+      app.policies = (body['policies'] as string[] | undefined) ?? [];
+      app.saas_app = { ...app.saas_app, ...(body['saas_app'] as Record<string, unknown>) };
+      return ok(wire(app, team));
+    }
+    if (method === 'DELETE') {
+      if (broken('delete')) return ok(garbage());
+      apps.delete(app.id);
+      return ok({ id: app.id });
+    }
+    throw new Error(`fake-access: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}`, body });
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { apps, fetch, seed, seen, team };
+};
+
+export type FakeAccess = ReturnType<typeof fakeAccess>;

package/src/cloudflare/fake-mesh.ts

@@ -37,7 +37,7 @@ export type FakeNode = {
 
 export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
 
-const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
+export const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
   Response.json({ success: true, errors: [], messages: [], result, ...extra });
 
 export const fakeFailure = (status: number, code: number, message: string) =>
@@ -153,7 +153,7 @@ export type FakeMesh = ReturnType<typeof fakeMesh>;
 
 /** distilled Credentials + the real FetchHttpClient over the fake — what a Bun script provides. */
 export const fakeClientLayer = (
-  fake: FakeMesh,
+  fake: { readonly fetch: typeof globalThis.fetch },
   credentials: Layer.Layer<Credentials> = fromApiToken({
     apiToken: FAKE_API_TOKEN,
     apiBaseUrl: FAKE_BASE,
@@ -166,7 +166,10 @@ export const fakeClientLayer = (
   );
 
 /** …plus the account, as Alchemy's CloudflareEnvironment hands it to a provider. */
-export const fakeProviderLayer = (fake: FakeMesh, accountId: string = FAKE_ACCOUNT) =>
+export const fakeProviderLayer = (
+  fake: { readonly fetch: typeof globalThis.fetch },
+  accountId: string = FAKE_ACCOUNT,
+) =>
   Layer.mergeAll(
     fakeClientLayer(fake),
     Layer.succeed(

package/src/cloudflare/fake-tunnel.ts

@@ -0,0 +1,148 @@
+/**
+ * A fake Cloudflare `cfd_tunnel` API for the CloudflaredTunnel tests — an in-memory `fetch` handed
+ * to Effect's real FetchHttpClient, the same way fake-mesh.ts does it, so the tests exercise
+ * distilled's real path assembly, query and body encoding, envelope decoding and error matching.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. Any request outside
+ *   `/accounts/<FAKE_ACCOUNT>/cfd_tunnel` or `/accounts/<FAKE_ACCOUNT>/tunnels` throws, so a
+ *   mis-wired test fails instead of reaching a real API.
+ * ★ THE FAKE HANDS OUT A TOKEN ON EVERY SURFACE IT CAN: a `token` field on the create response and
+ *   on every wire object (worst case: if Cloudflare ever adds one to the documented shape), and the
+ *   `/token` endpoint. The tests then prove none of it reaches an attribute, a state row or a
+ *   request log. The SDK's decoder drops fields outside its schema; the provider must not depend on
+ *   that alone.
+ * ★ THE NAME FILTER IS A SUBSTRING MATCH, as in fake-mesh.ts, so the client's exact re-check is
+ *   exercised. `/tunnels` honours `tun_types` and `is_deleted` as the SDK documents them, and
+ *   answers pages of two by default.
+ */
+import { FAKE_ACCOUNT, type Seen, fakeFailure, ok } from './fake-mesh.ts';
+
+export type FakeTunnel = {
+  id: string;
+  name: string;
+  tun_type: string;
+  config_src: string;
+  status: string;
+  token: string;
+  deleted_at: string | null;
+  /** The fake refuses a DELETE while this is set, as the SDK doc says it must ("no active connections"). */
+  connected: boolean;
+};
+
+const wire = (tunnel: FakeTunnel) => ({
+  id: tunnel.id,
+  account_tag: FAKE_ACCOUNT,
+  config_src: tunnel.config_src,
+  created_at: '2026-10-09T00:00:00Z',
+  deleted_at: tunnel.deleted_at,
+  name: tunnel.name,
+  status: tunnel.status,
+  tun_type: tunnel.tun_type,
+  token: tunnel.token,
+});
+
+export type FakeTunnelOptions = {
+  readonly perPage?: number;
+  /** Return a Response to answer the POST with it instead (e.g. `fakeFailure(409, 1013, …)`). */
+  readonly onCreate?: (name: string) => Response | void;
+  /** Return a Response to answer the DELETE with it instead (e.g. the tunnel vanishing mid-delete). */
+  readonly onDelete?: (id: string) => Response | void;
+};
+
+export const fakeTunnels = (options: FakeTunnelOptions = {}) => {
+  const tunnels = new Map<string, FakeTunnel>();
+  const seen: Seen[] = [];
+  const auth: string[] = [];
+  let next = 1;
+  const live = () => [...tunnels.values()].filter((t) => t.deleted_at === null);
+
+  const seed = (tunnel: Partial<FakeTunnel> & { name: string }): FakeTunnel => {
+    const id = tunnel.id ?? `00000000-0000-4000-9000-${String(next++).padStart(12, '0')}`;
+    const full: FakeTunnel = {
+      id,
+      tun_type: 'cfd_tunnel',
+      config_src: 'cloudflare',
+      status: 'inactive',
+      token: `fake-tunnel-token-${id}`,
+      deleted_at: null,
+      connected: false,
+      ...tunnel,
+    };
+    tunnels.set(id, full);
+    return full;
+  };
+
+  const list = (url: URL): Response => {
+    const filter = url.searchParams.get('name') ?? '';
+    const types = (url.searchParams.get('tun_types') ?? '').split(',').filter(Boolean);
+    const isDeleted = url.searchParams.get('is_deleted');
+    const page = Number(url.searchParams.get('page') ?? '1');
+    const perPage = Number(url.searchParams.get('per_page') ?? options.perPage ?? 2);
+    const hits = [...tunnels.values()]
+      .filter((t) => types.length === 0 || types.includes(t.tun_type))
+      .filter((t) => isDeleted === null || (t.deleted_at !== null) === (isDeleted === 'true'))
+      .filter((t) => t.name.includes(filter));
+    const slice = hits.slice((page - 1) * perPage, page * perPage);
+    return ok(slice.map(wire), { result_info: { page, per_page: perPage, count: slice.length } });
+  };
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const base = `/client/v4/accounts/${FAKE_ACCOUNT}`;
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(base)) {
+      throw new Error(`fake-tunnel: unexpected request ${method} ${url.href}`);
+    }
+    const rest = url.pathname.slice(base.length);
+    if (rest === '/tunnels' && method === 'GET') return list(url);
+    if (!rest.startsWith('/cfd_tunnel')) {
+      throw new Error(`fake-tunnel: unexpected ${method} ${url.pathname}`);
+    }
+    const [id, sub] = rest.slice('/cfd_tunnel'.length).split('/').filter(Boolean);
+    if (id === undefined && method === 'POST') {
+      const name = String(body['name']);
+      const override = options.onCreate?.(name);
+      if (override !== undefined) return override;
+      if (live().some((t) => t.name === name)) {
+        return fakeFailure(409, 1013, 'tunnel with name already exists');
+      }
+      const tunnel = seed({ name, config_src: String(body['config_src'] ?? 'local') });
+      return ok(wire(tunnel));
+    }
+    const tunnel = id === undefined ? undefined : tunnels.get(id);
+    if (tunnel === undefined) return fakeFailure(404, 1002, 'Tunnel not found');
+    if (sub === 'token' && method === 'GET') return ok(tunnel.token);
+    if (sub !== undefined) throw new Error(`fake-tunnel: unexpected ${method} ${url.pathname}`);
+    if (method === 'GET') return ok(wire(tunnel));
+    if (method === 'PATCH') {
+      const name = String(body['name']);
+      if (live().some((other) => other.name === name && other.id !== tunnel.id)) {
+        return fakeFailure(409, 1013, 'tunnel with name already exists');
+      }
+      tunnel.name = name;
+      return ok(wire(tunnel));
+    }
+    if (method === 'DELETE') {
+      const override = options.onDelete?.(tunnel.id);
+      if (override !== undefined) return override;
+      if (tunnel.deleted_at !== null) return fakeFailure(404, 1002, 'Tunnel not found');
+      if (tunnel.connected) return fakeFailure(400, 1000, 'tunnel has active connections');
+      tunnel.deleted_at = '2026-10-09T01:00:00Z';
+      return ok(wire(tunnel));
+    }
+    throw new Error(`fake-tunnel: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}`, body });
+    auth.push(request.headers.get('authorization') ?? '');
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { auth, fetch, live, tunnels, seed, seen };
+};
+
+export type FakeTunnels = ReturnType<typeof fakeTunnels>;

package/src/cloudflare/index.ts

@@ -1,10 +1,15 @@
 /**
  * Cloudflare providers for Alchemy — the gaps the vendor SDK leaves.
  *
- * ★ Built on vendor SDKs, not hand-rolled HTTP. Both `R2BucketLock` and `MeshNode` call
- *   `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare providers use — R2BucketLock
- *   over `/r2` (`getBucketLock`/`putBucketLock`), MeshNode over `/zero-trust`, because
- *   `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). Neither invents a path string.
+ * ★ Built on vendor SDKs, not hand-rolled HTTP. `R2BucketLock`, `MeshNode`, `CloudflaredTunnel` and
+ *   `SaasOidcApplication` all call `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare
+ *   providers use — R2BucketLock over `/r2` (`getBucketLock`/`putBucketLock`), MeshNode over
+ *   `/zero-trust`, because `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). None
+ *   invents a path string.
+ * ⚠️ ONE EXCEPTION, A READ: `SaasOidcApplication` writes and looks up names through the SDK, but its
+ *   responses drop `saas_app`, so `getApp` reads that one object from the wire JSON — the same
+ *   `GET /accounts/{account_id}/access/apps/{app_id}` the SDK's get verb sends, over the SDK's own
+ *   `HttpClient`, credentials and base URL (saas-oidc-api.ts).
  */
 export type { R2LockRule } from './lock-rules.ts';
 export { R2BucketLock, type R2BucketLockProps } from './r2-bucket-lock.ts';
@@ -12,6 +17,24 @@ export { MeshNode, MeshNodeProvider, type MeshNodeServices } from './mesh-node.t
 export type { MeshNodeAttributes, MeshNodeProps } from './mesh-node-form.ts';
 export { MeshNodeError, type MeshNodeStatus } from './mesh-node-api.ts';
 export { fetchMeshNodeToken, type MeshNodeRef } from './mesh-node-token.ts';
+export {
+  CloudflaredTunnel,
+  CloudflaredTunnelProvider,
+  type CloudflaredTunnelServices,
+} from './cloudflared-tunnel.ts';
+export type {
+  CloudflaredTunnelAttributes,
+  CloudflaredTunnelProps,
+} from './cloudflared-tunnel-form.ts';
+export { CloudflaredTunnelError } from './cloudflared-tunnel-api.ts';
+export { SaasOidcApplication, SaasOidcApplicationProvider } from './saas-oidc.ts';
+export type {
+  OidcGrantType,
+  OidcScope,
+  SaasOidcApplicationAttributes,
+  SaasOidcApplicationProps,
+} from './saas-oidc-form.ts';
+export { SaasOidcError } from './saas-oidc-error.ts';
 export { providers } from './providers.ts';
 export {
   astroWebsite,

package/src/cloudflare/providers.ts

@@ -13,26 +13,39 @@
  *   `Cloudflare.providers()` does (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
  *   `CLOUDFLARE_ACCOUNT_ID` in CI) — a lock and the Gateway rules that reference the same bucket
  *   land in the same account.
- * ⚠️ THE LAYER IS BUILT TWICE ON PURPOSE, once per provider, even when the stack also merges
+ * ⚠️ THE LAYER IS BUILT ONCE PER PROVIDER ON PURPOSE, even when the stack also merges
  *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: each feeds its own provider
  *   only and adds nothing to the stack's context.
  */
 import * as Cloudflare from 'alchemy/Cloudflare';
 import * as Provider from 'alchemy/Provider';
 import * as Layer from 'effect/Layer';
+import { CloudflaredTunnel, CloudflaredTunnelProvider } from './cloudflared-tunnel.ts';
 import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
 import { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';
+import { SaasOidcApplication, SaasOidcApplicationProvider } from './saas-oidc.ts';
 
 export class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}
 
-// ⛔ `orDie` ON BOTH, as `Cloudflare.providers()` ends with: a stack's providers layer must not
+// ⛔ `orDie` ON EACH of the four, as `Cloudflare.providers()` ends with: a stack's providers layer must not
 //   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
 export const providers = () =>
-  Layer.effect(Providers, Provider.collection([R2BucketLock, MeshNode])).pipe(
+  Layer.effect(
+    Providers,
+    Provider.collection([R2BucketLock, MeshNode, CloudflaredTunnel, SaasOidcApplication]),
+  ).pipe(
     Layer.provide(
       Layer.mergeAll(
         R2BucketLockProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
         MeshNodeProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
+        CloudflaredTunnelProvider().pipe(
+          Layer.provide(Cloudflare.CloudflareApiLive()),
+          Layer.orDie,
+        ),
+        SaasOidcApplicationProvider().pipe(
+          Layer.provide(Cloudflare.CloudflareApiLive()),
+          Layer.orDie,
+        ),
       ),
     ),
   );