@homeflare/alchemy 0.48.1 → 0.50.0

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,
+        ),
       ),
     ),
   );

package/src/cloudflare/saas-oidc-api.ts

@@ -0,0 +1,224 @@
+/**
+ * The Access application calls a SaaS OIDC application needs, and nothing else.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare` FOR EVERY WRITE AND FOR THE NAME LOOKUP; ONE RAW READ. Alchemy
+ *   `2.0.0-beta.81`'s `Cloudflare.Access.Application` has no `saas_app` at all (Application.ts:
+ *   `saas` appears only as an app type and in two doc comments), so this resource exists. The SDK
+ *   does carry `saasApp` on the REQUEST (`AccessApplicationsCreateRequestSaasAppOIDCSaaSApp`,
+ *   zero_trust.ts, `@distilled.cloud/cloudflare@1.0.0-rc.13`), so create and update go through it.
+ * ⚠️ BUT ITS RESPONSES DROP IT. Measured 2026-10-09 against rc.13 with a fake API that answered a
+ *   full `saas_app` object: `getAccessApplicationForAccount` and `createAccessApplicationForAccount`
+ *   both decoded to `{ domain, type, id, aud, name, policies }`, with no `saasApp`. The response
+ *   union is discriminated by field names (`T.UnionCases`) and a saas app falls in a variant with
+ *   no `saas_app`. So the OIDC client id, redirect URIs, scopes and grant types can only be read
+ *   from the wire JSON, and `getApp` below does that through the `HttpClient` the SDK itself runs
+ *   on, with the SDK's own credentials and base URL. It invents no path: it is the same
+ *   `GET /accounts/{account_id}/access/apps/{app_id}` the SDK's get verb sends.
+ *
+ * ⛔ THE CLIENT SECRET NEVER REACHES THIS PACKAGE'S MEMORY. The field doc on the SDK schema says
+ *   "The application client secret, only returned on POST request". The create response is
+ *   decoded by the SDK, whose `saasApp`-less variant drops it, and `getApp` copies named fields
+ *   only and never reads `client_secret`. TWO paths remain where the SDK itself holds or prints the
+ *   raw body (`@distilled.cloud/cloudflare@1.0.0-rc.13`, protocol.ts):
+ *   1. `DISTILLED_DEBUG_HTTP` makes it `console.error` the first 400 characters of every response
+ *      (line 334), so `refuseDebugHttp` stops a write while it is set. THIS ONE STAYS AN
+ *      OPERATOR-ONLY SWITCH: the package can refuse to run, it cannot stop the SDK printing.
+ *   2. A response that fails schema validation becomes `CloudflareParseError({ body, cause })`
+ *      (lines 452-457), whose `body` is the whole parsed response, create response included.
+ *      ⛔ SANITISED HERE: every SDK call of this resource (create, update, list, delete, and the
+ *      organization read in saas-oidc-team.ts) catches that tag at the call and fails with a
+ *      `SaasOidcError` that names the operation and nothing from the response. Why, when it can
+ *      happen at all, and what rc.13 will and will not raise: saas-oidc-error.ts (`withheld`).
+ *      The raw `get` below is not an SDK call and never builds that error.
+ *   A PUBLIC PKCE client (`allowPkceWithoutClientSecret: true`) has no secret at all, so neither
+ *   path exposes one for the Headlamp app.
+ */
+import { Credentials, formatHeaders } from '@distilled.cloud/cloudflare/Credentials';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import * as Schedule from 'effect/Schedule';
+import * as Stream from 'effect/Stream';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { SaasOidcError, withheld } from './saas-oidc-error.ts';
+import { type AppWrite, parseApp, record } from './saas-oidc-wire.ts';
+
+/**
+ * The two SDK writes, as properties of an object so saas-oidc-parse-error.test.ts can stand in for
+ * one: rc.13 cannot be made to fail a create or update with `CloudflareParseError` (the ⚠️ in
+ * saas-oidc-error.ts), and the catch on those two calls still has to be proven wired. Nothing
+ * else assigns here.
+ */
+export const sdkWrites = {
+  create: zeroTrust.createAccessApplicationForAccount,
+  update: zeroTrust.updateAccessApplicationForAccount,
+};
+
+const TRANSIENT_STATUS = (status: number): boolean =>
+  status === 403 || status === 429 || status >= 500;
+
+/**
+ * ★ UPSTREAM'S OWN RETRY, EXACTLY (alchemy beta.81 `Cloudflare/Access/Application.ts`, the comment
+ *   and `retryTransientAccessError` above `ApplicationProvider`): `AccessReferenceNotFound` is a
+ *   freshly created policy still propagating, and `Forbidden` is how Cloudflare throttles a valid
+ *   token. Capped exponential, about 45 seconds, then fail. The raw read joins it for the same
+ *   statuses so it is throttled the way the SDK calls are.
+ */
+export const retryTransient = <A, E extends { readonly _tag: string }, R>(
+  effect: Effect.Effect<A, E, R>,
+) =>
+  effect.pipe(
+    Effect.retry({
+      while: (e) =>
+        e._tag === 'AccessReferenceNotFound' ||
+        e._tag === 'Forbidden' ||
+        (e._tag === 'SaasOidcError' &&
+          TRANSIENT_STATUS((e as unknown as SaasOidcError).status ?? 0)),
+      schedule: Schedule.max([
+        Schedule.min([Schedule.exponential('1 second', 1.5), Schedule.spaced('5 seconds')]),
+        Schedule.recurs(12),
+      ]),
+    }),
+  );
+
+/**
+ * ⛔ REFUSED BEFORE ANY WRITE while `DISTILLED_DEBUG_HTTP` is set: the SDK would print the create
+ *   response, which carries the client secret, to stderr (protocol.ts). Read from `process.env`
+ *   because that is what distilled reads, as mesh-node-token.ts does.
+ */
+export const refuseDebugHttp = Effect.suspend(() =>
+  (globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') === ''
+    ? Effect.void
+    : Effect.fail(
+        new SaasOidcError({
+          message:
+            'Refusing to write a SaaS OIDC application while DISTILLED_DEBUG_HTTP is set: the SDK would print the response, which carries the client secret, to stderr. Unset it and run again.',
+        }),
+      ),
+);
+
+/**
+ * The app with this id, from the wire JSON, or `undefined` when it is gone (404).
+ * ⚠️ Error messages carry the reason and the status only: the request holds the bearer token.
+ */
+export const getApp = (accountId: string, appId: string) =>
+  Effect.gen(function* () {
+    const credentials = yield* yield* Credentials;
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.get(
+      `${credentials.apiBaseUrl}/accounts/${accountId}/access/apps/${appId}`,
+    ).pipe(HttpClientRequest.setHeaders(formatHeaders(credentials)), HttpClientRequest.acceptJson);
+    const transport = (cause: { readonly message: string }) =>
+      new SaasOidcError({ message: `Access application GET failed: ${cause.message}`, status: 0 });
+    const response = yield* client.execute(request).pipe(Effect.mapError(transport));
+    if (response.status === 404) return undefined;
+    if (response.status < 200 || response.status >= 300) {
+      return yield* Effect.fail(
+        new SaasOidcError({
+          message: `Access application GET returned ${response.status}`,
+          status: response.status,
+        }),
+      );
+    }
+    const text = yield* response.text.pipe(Effect.mapError(transport));
+    const body = yield* Effect.try({
+      try: () => record(JSON.parse(text) as unknown),
+      catch: () =>
+        new SaasOidcError({ message: 'Access application GET was not JSON', status: 200 }),
+    });
+    const result = record(body?.['result']);
+    return result === undefined ? undefined : parseApp(result);
+  }).pipe(retryTransient);
+
+/**
+ * The live saas app with exactly this name, or `undefined`. The list payload carries no `saas_app`
+ * (see the ⚠️ above), so the caller re-reads the match by id with `getApp`.
+ * ⛔ Two matches are refused rather than resolved: Access does not enforce unique app names, so two
+ *   means this package cannot tell which one is meant.
+ */
+export const findSaasByName = (accountId: string, name: string) =>
+  zeroTrust.listAccessApplicationsForAccount.items({ accountId }).pipe(
+    Stream.filter((app) => app.type === 'saas' && app.name === name),
+    Stream.runCollect,
+    Effect.catchTag('CloudflareParseError', withheld('application list')),
+    retryTransient,
+    Effect.flatMap((chunk) => {
+      const ids = Array.from(chunk).flatMap((app) => (app.id == null ? [] : [app.id]));
+      if (ids.length <= 1) return Effect.succeed(ids[0]);
+      return Effect.fail(
+        new SaasOidcError({
+          message: `SaaS application name "${name}" matches ${ids.length} live apps (${ids.join(', ')}). Refusing to guess which one is meant; set \`applicationId\`.`,
+        }),
+      );
+    }),
+  );
+
+const sdkBody = (write: AppWrite) => ({
+  type: 'saas' as const,
+  name: write.name,
+  sessionDuration: write.sessionDuration,
+  ...(write.allowedIdps === undefined ? {} : { allowedIdps: [...write.allowedIdps] }),
+  ...(write.autoRedirectToIdentity === undefined
+    ? {}
+    : { autoRedirectToIdentity: write.autoRedirectToIdentity }),
+  appLauncherVisible: write.appLauncherVisible,
+  policies: [...write.policies],
+  saasApp: {
+    authType: write.saasApp.authType,
+    redirectUris: [...write.saasApp.redirectUris],
+    scopes: [...write.saasApp.scopes],
+    grantTypes: [...write.saasApp.grantTypes],
+    accessTokenLifetime: write.saasApp.accessTokenLifetime,
+    allowPkceWithoutClientSecret: write.saasApp.allowPkceWithoutClientSecret,
+    ...(write.saasApp.refreshTokenOptions === undefined
+      ? {}
+      : { refreshTokenOptions: write.saasApp.refreshTokenOptions }),
+    ...(write.saasApp.appLauncherUrl === undefined
+      ? {}
+      : { appLauncherUrl: write.saasApp.appLauncherUrl }),
+  } satisfies zeroTrust.AccessApplicationsCreateRequestSaasAppOIDCSaaSApp,
+});
+
+/** Create the app and return its id. The response's other fields are not trusted: re-read it. */
+export const createApp = (accountId: string, write: AppWrite) =>
+  refuseDebugHttp.pipe(
+    Effect.andThen(
+      sdkWrites
+        .create({ accountId, ...sdkBody(write) })
+        .pipe(
+          Effect.catchTag('CloudflareParseError', withheld('application create')),
+          retryTransient,
+        ),
+    ),
+    Effect.flatMap((created) =>
+      created.id == null
+        ? Effect.fail(new SaasOidcError({ message: 'SaaS OIDC create did not return an id.' }))
+        : Effect.succeed(created.id),
+    ),
+  );
+
+export const updateApp = (accountId: string, appId: string, write: AppWrite) =>
+  refuseDebugHttp.pipe(
+    Effect.andThen(
+      sdkWrites
+        .update({ accountId, appId, ...sdkBody(write) })
+        .pipe(
+          Effect.catchTag('CloudflareParseError', withheld('application update')),
+          retryTransient,
+        ),
+    ),
+    Effect.asVoid,
+  );
+
+/**
+ * Idempotent: an app already gone is a successful delete. Any other failure propagates, except
+ * that a response the SDK cannot validate is withheld (see `withheld`).
+ */
+export const deleteApp = (accountId: string, appId: string) =>
+  zeroTrust.deleteAccessApplicationForAccount({ accountId, appId }).pipe(
+    Effect.asVoid,
+    Effect.catchTags({
+      AccessApplicationNotFound: () => Effect.void,
+      CloudflareParseError: withheld('application delete'),
+    }),
+  );

package/src/cloudflare/saas-oidc-consumer.ts

@@ -0,0 +1,35 @@
+/**
+ * A test-only downstream resource for saas-oidc-stable.test.ts: it takes the app's issuer as a prop
+ * and counts how often the engine reconciles it, so a test can tell "planned noop" from "planned
+ * update" for a consumer of `app.issuer`. ⛔ TEST-ONLY. No provider imports this file.
+ */
+import * as Provider from 'alchemy/Provider';
+import { Resource } from 'alchemy/Resource';
+import * as Effect from 'effect/Effect';
+
+export interface IssuerConsumer extends Resource<
+  'Test.IssuerConsumer',
+  { readonly issuer: string; readonly jwks: string },
+  { readonly issuer: string; readonly jwks: string }
+> {}
+export const IssuerConsumer = Resource<IssuerConsumer>('Test.IssuerConsumer');
+
+/** The provider, and the list of props it was reconciled with (one entry per reconcile). */
+export const consumerProvider = () => {
+  const reconciled: string[] = [];
+  const layer = Provider.effect(
+    IssuerConsumer,
+    Effect.succeed(
+      IssuerConsumer.Provider.of({
+        list: () => Effect.succeed([]),
+        reconcile: ({ news }) =>
+          Effect.sync(() => {
+            reconciled.push(news.issuer);
+            return { issuer: news.issuer, jwks: news.jwks };
+          }),
+        delete: () => Effect.void,
+      }),
+    ),
+  );
+  return { layer, reconciled };
+};

package/src/cloudflare/saas-oidc-error.ts

@@ -0,0 +1,52 @@
+/**
+ * The one error type of the SaaS OIDC resource, and the handler that keeps the SDK's raw
+ * `CloudflareParseError` (which can hold the client secret) from leaving this package.
+ *
+ * ⛔ THE LEAK. A response that fails schema validation becomes `CloudflareParseError({ body, cause })`
+ *   (`@distilled.cloud/cloudflare@1.0.0-rc.13` protocol.ts:452-457). `body` is the WHOLE parsed
+ *   response, a create response included, and for a confidential client that carries
+ *   `client_secret`; `cause` is a SchemaError that quotes the values that failed. A raw SDK error
+ *   that reached an engine log or a trace would print both.
+ * ★ THE FIX is at every SDK call of this resource (create, update, list, delete, and the
+ *   organization read in saas-oidc-team.ts): `Effect.catchTag('CloudflareParseError', withheld(…))`,
+ *   applied before the retry or any other combinator sees the error. It is the house's catchTag
+ *   doctrine (a typed tag, no status or message sniffing), and the replacement carries the
+ *   operation name and nothing from the response. The raw `get` in saas-oidc-api.ts is not an SDK
+ *   call and never builds this error.
+ * ⚠️ WHEN IT CAN HAPPEN AT ALL. The error exists only under STRICT response validation (core
+ *   response-validation.ts:29 "without one, every call is lenient", :104-116); neither Alchemy nor
+ *   this kit turns strict on, so a consumer's own `ResponseValidation.strict` is what makes it
+ *   reachable. MEASURED 2026-10-09 against rc.13 under strict validation: a create or update
+ *   response decodes against `S.Unknown` (`AccessApplicationsCreateResult`, zero_trust.ts:35025;
+ *   `AccessApplicationsUpdateResult`, :210218), which accepts anything, so the real SDK cannot
+ *   raise it for those two today (the tests reach them through `sdkWrites` in saas-oidc-api.ts).
+ *   List (a non-array result, :147403-147410), delete (`id` typed, :61601-61607) and the organization
+ *   read (:169193-169253) are typed and can. The catch is on all five so a later SDK that types the
+ *   union cannot start leaking.
+ * ⛔ `DISTILLED_DEBUG_HTTP` is the other raw-body path and stays an operator-only switch: the
+ *   package refuses a write while it is set (`refuseDebugHttp`), it cannot stop the SDK printing.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a secret. */
+export class SaasOidcError extends Data.TaggedError('SaasOidcError')<{
+  readonly message: string;
+  /** The HTTP status when the failure is a response (0 for a transport failure). */
+  readonly status?: number;
+}> {}
+
+/**
+ * ⛔ THE ONLY THING THIS PACKAGE SAYS ABOUT A RESPONSE THE SDK COULD NOT VALIDATE. The handler for
+ *   `Effect.catchTag('CloudflareParseError', …)`: it never touches the error it replaces, because
+ *   that error's `body` is the whole response (a create's carries `client_secret`) and its `cause`
+ *   quotes the values that failed. The message names the operation only. No status is claimed: the
+ *   SDK builds this error after its failure branch (protocol.ts:359, :452), so the response was a
+ *   success as far as HTTP and the envelope go, and nothing more is known.
+ */
+export const withheld = (operation: string) => (): Effect.Effect<never, SaasOidcError> =>
+  Effect.fail(
+    new SaasOidcError({
+      message: `Access ${operation} succeeded at the HTTP level but the SDK could not validate the response. The response is withheld on purpose (a create response carries the client secret). Check the application in the Zero Trust dashboard, then run again.`,
+    }),
+  );