@homeflare/alchemy 0.48.0 → 0.49.0

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

@@ -0,0 +1,190 @@
+/**
+ * `HomeFlare.Access.SaasOidcApplication` — the pure helpers the lifecycle uses: validation, the
+ * issuer URLs, drift, the write body and the attribute mapping. The props and attributes types are
+ * declared in saas-oidc-props.ts and re-exported here.
+ *
+ * ⛔ THE ATTRIBUTES NEVER HOLD THE CLIENT SECRET, and nothing here can: `ObservedApp`
+ *   (saas-oidc-api.ts) has no field for it. A client that authenticates with PKCE alone declares
+ *   `allowPkceWithoutClientSecret: true`, and then no secret exists to keep.
+ * ★ THE ISSUER IS `https://<teamDomain>/cdn-cgi/access/sso/oidc/<clientId>`. The team domain is a
+ *   prop; the openbao copy this came from hardcoded one account's. Cloudflare also reports the
+ *   same host in the app's own `domain` field (Alchemy's `Access.Application` doc: for `saas`
+ *   "Cloudflare uses the OIDC issuer"), and `checkTeam` refuses a declaration that disagrees with it.
+ */
+import { SaasOidcError } from './saas-oidc-error.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-props.ts';
+import type { AppWrite, ObservedApp } from './saas-oidc-wire.ts';
+
+// The declared shape lives in saas-oidc-props.ts (every field documented there); re-exported so
+// the module that always held it keeps answering to its old name.
+export type {
+  OidcGrantType,
+  OidcScope,
+  SaasOidcApplicationAttributes,
+  SaasOidcApplicationProps,
+} from './saas-oidc-props.ts';
+
+const HOSTNAME = /^[a-z0-9]+(?:[.-][a-z0-9]+)+$/;
+
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export const validateSaasOidc = (props: SaasOidcApplicationProps): SaasOidcError | undefined => {
+  const fail = (message: string) => new SaasOidcError({ message });
+  if (typeof props.teamDomain !== 'string' || !HOSTNAME.test(props.teamDomain)) {
+    return fail(
+      `SaasOidcApplication \`teamDomain\` must be a bare lowercase hostname such as "example.cloudflareaccess.com" (no scheme, no path); got ${JSON.stringify(props.teamDomain)}.`,
+    );
+  }
+  if (props.name !== undefined && props.name.trim() === '') {
+    return fail('SaasOidcApplication `name`, when set, must not be empty.');
+  }
+  if (
+    props.saasApp.allowPkceWithoutClientSecret === true &&
+    !props.saasApp.grantTypes.includes('authorization_code_with_pkce')
+  ) {
+    return fail(
+      '`allowPkceWithoutClientSecret: true` only applies to the `authorization_code_with_pkce` grant; add it to `grantTypes` or drop the flag.',
+    );
+  }
+  return undefined;
+};
+
+export const issuerFor = (teamDomain: string, clientId: string): string =>
+  `https://${teamDomain}/cdn-cgi/access/sso/oidc/${clientId}`;
+
+const hostOf = (domain: string): string => domain.split('/')[0]?.toLowerCase() ?? '';
+
+/**
+ * ⛔ A DECLARED TEAM DOMAIN THAT DISAGREES WITH THE APP'S OWN `domain` is refused: the issuer in
+ *   the attributes would point at a different team than the one that holds the app.
+ * ⛔ WHEN CLOUDFLARE REPORTS NO `domain` there is nothing to compare, so the team the row already
+ *   recorded (`knownTeam`, from state) stands in: a declaration that moves it is refused, because
+ *   `issuer` is a declared stable and must not move under the row. With no `knownTeam` either
+ *   (a first create or a cold adoption) there is nothing to compare against and the declaration
+ *   stands.
+ */
+export const checkTeam = (
+  teamDomain: string,
+  app: ObservedApp,
+  knownTeam?: string,
+): SaasOidcError | undefined => {
+  if (app.domain === undefined) {
+    return knownTeam === undefined || knownTeam.toLowerCase() === teamDomain.toLowerCase()
+      ? undefined
+      : new SaasOidcError({
+          message: `SaasOidcApplication declares teamDomain "${teamDomain}" but the row recorded "${knownTeam}" and Cloudflare reports no domain for the app to confirm the change. The issuer cannot move; revert the declaration.`,
+        });
+  }
+  return hostOf(app.domain) === teamDomain.toLowerCase()
+    ? undefined
+    : new SaasOidcError({
+        message: `SaasOidcApplication declares teamDomain "${teamDomain}" but Cloudflare reports the app on "${hostOf(app.domain)}".`,
+      });
+};
+
+const refreshLifetime = (props: SaasOidcApplicationProps): string =>
+  props.saasApp.refreshTokenLifetime ?? '';
+
+/** The request body for a create or an update. */
+export const writeBody = (news: SaasOidcApplicationProps, name: string): AppWrite => ({
+  name,
+  sessionDuration: news.sessionDuration ?? '24h',
+  allowedIdps: news.allowedIdps,
+  autoRedirectToIdentity: news.autoRedirectToIdentity,
+  appLauncherVisible: news.appLauncherVisible ?? false,
+  policies: news.policies,
+  saasApp: {
+    authType: 'oidc',
+    redirectUris: news.saasApp.redirectUris,
+    scopes: news.saasApp.scopes,
+    grantTypes: news.saasApp.grantTypes,
+    accessTokenLifetime: news.saasApp.accessTokenLifetime,
+    ...(news.saasApp.refreshTokenLifetime === undefined
+      ? {}
+      : { refreshTokenOptions: { lifetime: news.saasApp.refreshTokenLifetime } }),
+    allowPkceWithoutClientSecret: news.saasApp.allowPkceWithoutClientSecret ?? false,
+    appLauncherUrl: news.saasApp.appLauncherUrl,
+  },
+});
+
+const sameSet = (a: ReadonlyArray<string>, b: ReadonlyArray<string> | undefined): boolean =>
+  JSON.stringify([...a].sort()) === JSON.stringify([...(b ?? [])].sort());
+
+/**
+ * ⛔ ORDER MATTERS FOR POLICIES: `policies` is "in ascending order of precedence" (the SDK's own
+ *   field doc, zero_trust.ts:9774), so `[a, b]` and `[b, a]` are different declarations. A set
+ *   compare here would let a reorder go unnoticed and leave the live precedence unchanged.
+ *   `parseApp` hands the observed ids over already ordered by the API's `precedence`.
+ */
+const sameList = (a: ReadonlyArray<string>, b: ReadonlyArray<string> | undefined): boolean => {
+  const other = b ?? [];
+  return a.length === other.length && a.every((item, index) => item === other[index]);
+};
+
+/**
+ * Does the live app differ from the declaration? Compared: name, auth type, redirect URIs, scopes,
+ * grant types (each as a set), both lifetimes, the PKCE flag and the policies IN ORDER — the
+ * openbao copy's set plus the policy order, kept so adopting a live app is not newly a write.
+ * ⚠️ NOT COMPARED: `sessionDuration`, `allowedIdps`, `autoRedirectToIdentity`, `appLauncherVisible`,
+ *   `appLauncherUrl`. They are written on create and on any sync, but a change to only those does
+ *   not trigger one. Carried over unchanged; see saas-oidc.md.
+ */
+export const needsSync = (
+  news: SaasOidcApplicationProps,
+  observed: ObservedApp,
+  name: string,
+): boolean => {
+  const saas = observed.saasApp;
+  return (
+    (observed.name ?? '') !== name ||
+    (saas?.authType ?? '') !== 'oidc' ||
+    !sameSet(news.saasApp.redirectUris, saas?.redirectUris) ||
+    !sameSet(news.saasApp.scopes, saas?.scopes) ||
+    !sameSet(news.saasApp.grantTypes, saas?.grantTypes) ||
+    (saas?.accessTokenLifetime ?? '') !== news.saasApp.accessTokenLifetime ||
+    refreshLifetime(news) !== (saas?.refreshTokenLifetime ?? '') ||
+    (saas?.allowPkceWithoutClientSecret ?? false) !==
+      (news.saasApp.allowPkceWithoutClientSecret ?? false) ||
+    !sameList(news.policies, observed.policyIds)
+  );
+};
+
+/**
+ * The attributes of a live app, or `undefined` when it lacks an id, an `aud` or a client id (so it
+ * is not a SaaS OIDC app this package can describe). `teamDomain` is the declared one, or, for a
+ * read that has no declaration (state written before the prop existed), the host Cloudflare reports.
+ */
+export const toAttributes = (
+  app: ObservedApp,
+  accountId: string,
+  fallbackName: string,
+  declaredTeam: string | undefined,
+): SaasOidcApplicationAttributes | undefined => {
+  const clientId = app.saasApp?.clientId;
+  const teamDomain = declaredTeam ?? (app.domain === undefined ? undefined : hostOf(app.domain));
+  if (app.id === undefined || app.aud === undefined || clientId === undefined) return undefined;
+  if (teamDomain === undefined || teamDomain === '') return undefined;
+  const issuer = issuerFor(teamDomain, clientId);
+  const saas = app.saasApp;
+  return {
+    applicationId: app.id,
+    aud: app.aud,
+    domain: app.domain ?? issuer.replace('https://', ''),
+    name: app.name ?? fallbackName,
+    accountId,
+    teamDomain,
+    clientId,
+    issuer,
+    authorizationEndpoint: `${issuer}/authorization`,
+    tokenEndpoint: `${issuer}/token`,
+    jwksEndpoint: `${issuer}/jwks`,
+    userinfoEndpoint: `${issuer}/userinfo`,
+    configurationEndpoint: `${issuer}/.well-known/openid-configuration`,
+    redirectUris: saas?.redirectUris ?? [],
+    scopes: saas?.scopes ?? [],
+    grantTypes: saas?.grantTypes ?? [],
+    accessTokenLifetime: saas?.accessTokenLifetime ?? '',
+    refreshTokenLifetime: saas?.refreshTokenLifetime ?? '',
+    createdAt: app.createdAt,
+    updatedAt: app.updatedAt,
+  };
+};

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

@@ -0,0 +1,140 @@
+/**
+ * SaasOidcApplicationProvider's handlers, called the way the engine calls them, over the fake
+ * Access API in fake-access.ts — and `engine`, which runs Alchemy's real plan/apply over the same
+ * fake and exposes the in-memory state rows. Shared by saas-oidc.test.ts and
+ * saas-oidc-state.test.ts. ⛔ TEST-ONLY, like fake-access.ts.
+ */
+import { apply } from 'alchemy/Apply';
+import * as Plan from 'alchemy/Plan';
+import { type CompiledStack, make as makeStack } from 'alchemy/Stack';
+import { Stage } from 'alchemy/Stage';
+import * as State from 'alchemy/State';
+import * as Cause from 'effect/Cause';
+import * as Context from 'effect/Context';
+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 { type FakeAccess, TEAM } from './fake-access.ts';
+import { fakeProviderLayer } from './fake-mesh.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-form.ts';
+import { SaasOidcApplication, SaasOidcApplicationProvider } from './saas-oidc.ts';
+
+/**
+ * ⚠️ THE SDK'S STRICT VALIDATION SWITCH, REBUILT BY KEY. A `CloudflareParseError` exists only under
+ *   `ResponseValidation.strict` (`@distilled.cloud/core` response-validation.ts:43-52, :104-116);
+ *   the default is lenient. `@distilled.cloud/core` is not a dependency of this package, so this
+ *   declares a reference with the SAME string key and provides `'strict'` for it: the SDK reads the
+ *   mode from the fiber's context by that key. saas-oidc-parse-error.test.ts first proves the raw
+ *   SDK really fails under it, so a renamed key fails that test instead of passing vacuously.
+ */
+const ResponseValidation = Context.Reference<'lenient' | 'strict'>(
+  '@distilled.cloud/core/ResponseValidation',
+  { defaultValue: () => 'lenient' },
+);
+export const strict = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  effect.pipe(Effect.provideService(ResponseValidation, 'strict'));
+
+export const ids = { fqn: 'stack/headlamp', id: 'headlamp', instanceId: 'i-1' };
+export const extra = { bindings: [] as never, session: undefined as never };
+
+export type P = Effect.Success<typeof SaasOidcApplication.Provider>;
+
+/** A public PKCE client, the shape Headlamp declares (Q6). */
+export const publicClient = (
+  over: Partial<SaasOidcApplicationProps> = {},
+): SaasOidcApplicationProps => ({
+  name: 'Headlamp',
+  teamDomain: TEAM,
+  policies: ['policy-admin'],
+  saasApp: {
+    authType: 'oidc',
+    redirectUris: ['https://headlamp.example.test/oidc-callback'],
+    scopes: ['openid', 'email', 'groups'],
+    grantTypes: ['authorization_code_with_pkce'],
+    accessTokenLifetime: '15m',
+    allowPkceWithoutClientSecret: true,
+  },
+  ...over,
+});
+
+/** The wire `saas_app` of a live app that matches `publicClient()` exactly (no drift to sync). */
+export const LIVE_OIDC = {
+  auth_type: 'oidc',
+  redirect_uris: ['https://headlamp.example.test/oidc-callback'],
+  scopes: ['openid', 'email', 'groups'],
+  grant_types: ['authorization_code_with_pkce'],
+  access_token_lifetime: '15m',
+  allow_pkce_without_client_secret: true,
+};
+
+/** Build the provider over the fake and hand it to `use`. */
+export const run = <A, E>(fake: FakeAccess, use: (p: P) => Effect.Effect<A, E, never>) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* SaasOidcApplication.Provider);
+    }).pipe(
+      Effect.provide(
+        SaasOidcApplicationProvider().pipe(Layer.provideMerge(fakeProviderLayer(fake))),
+      ),
+      // `createPhysicalName` reads these from the engine's context; a named app never calls it.
+      Effect.provideService(FetchHttpClient.Fetch, fake.fetch),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+export const reconcile = (
+  p: P,
+  news: SaasOidcApplicationProps,
+  output?: SaasOidcApplicationAttributes,
+) => p.reconcile({ ...ids, ...extra, news, olds: undefined, output });
+
+export const read = (
+  p: P,
+  olds: SaasOidcApplicationProps,
+  output?: SaasOidcApplicationAttributes,
+) => {
+  const handler = p.read;
+  if (handler === undefined) throw new Error('provider has no read handler');
+  return handler({ ...ids, olds, output });
+};
+
+/** The writes the fake saw, in order: `['POST', 'PUT', …]`. */
+export const writes = (fake: FakeAccess) =>
+  fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method);
+
+type Rows = Record<string, Record<string, Record<string, State.ResourceState>>>;
+
+/**
+ * ★ THE REAL ENGINE, NOT A MODEL OF IT: `Plan.make` + `apply` over an in-memory state store, as
+ *   mesh-node-harness.ts does. `rows` is that store, so a test can serialise exactly what Alchemy
+ *   would persist.
+ */
+export const engine = (fake: FakeAccess, extra: Layer.Layer<never, never, never> = Layer.empty) => {
+  const rows: Rows = {};
+  const state = Layer.succeed(State.State, State.InMemoryService(rows));
+  const providers = Layer.mergeAll(
+    SaasOidcApplicationProvider().pipe(Layer.provide(fakeProviderLayer(fake))),
+    extra,
+  );
+  const deploy = <A, E, R>(declare: Effect.Effect<A, E, R>) =>
+    Effect.runPromiseExit(
+      declare.pipe(
+        makeStack({ name: 'oidc', providers, state }) as never,
+        Effect.flatMap((compiled: CompiledStack) =>
+          Plan.make(compiled).pipe(Effect.flatMap(apply), Effect.provide(compiled.services)),
+        ),
+        Effect.provide(Layer.succeed(Stage, 'test')),
+        Effect.scoped,
+        Effect.provideService(FetchHttpClient.Fetch, fake.fetch),
+      ) as Effect.Effect<unknown, unknown>,
+    );
+  return {
+    deploy,
+    rows,
+    status: (fqn: string) => rows['oidc']?.['test']?.[fqn]?.status,
+  };
+};
+
+/** The failure sentence of a deploy, or `''` when it succeeded. */
+export const failureOf = (exit: Exit.Exit<unknown, unknown>) =>
+  Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : '';

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

@@ -0,0 +1,150 @@
+/**
+ * read / reconcile / delete for `HomeFlare.Access.SaasOidcApplication`, as plain Effects over the
+ * calls in saas-oidc-api.ts. saas-oidc.ts only wires them into Alchemy.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { createPhysicalName } from 'alchemy/PhysicalName';
+import * as Effect from 'effect/Effect';
+import { createApp, deleteApp, findSaasByName, getApp, updateApp } from './saas-oidc-api.ts';
+import { SaasOidcError } from './saas-oidc-error.ts';
+import {
+  type SaasOidcApplicationAttributes,
+  type SaasOidcApplicationProps,
+  checkTeam,
+  needsSync,
+  toAttributes,
+  validateSaasOidc,
+  writeBody,
+} from './saas-oidc-form.ts';
+import { checkTeamBeforeCreate } from './saas-oidc-team.ts';
+import type { ObservedApp } from './saas-oidc-wire.ts';
+
+const resolveName = (id: string, name: string | undefined) =>
+  name !== undefined && name !== '' ? Effect.succeed(name) : createPhysicalName({ id });
+
+/**
+ * The live app: by the known id when there is one, else by exact name. A saas app found by id that
+ * is NOT type `saas` is refused, never rewritten: `applicationId` pointing at a self-hosted app
+ * would otherwise have its type overwritten by the update.
+ */
+const observe = (
+  accountId: string,
+  knownId: string | undefined,
+  name: string,
+  options: { readonly byIdOnly?: boolean } = {},
+) =>
+  Effect.gen(function* () {
+    const byId = knownId === undefined ? undefined : yield* getApp(accountId, knownId);
+    if (byId !== undefined) {
+      if (byId.type !== 'saas') {
+        return yield* Effect.fail(
+          new SaasOidcError({
+            message: `Access application ${knownId} is type "${byId.type ?? 'unknown'}", not "saas". Refusing to rewrite it as a SaaS OIDC app.`,
+          }),
+        );
+      }
+      return byId;
+    }
+    // ★ An OWNED row's app that is gone stays gone: another saas app with the same name is not it,
+    //   and its applicationId and clientId (declared stables) must not change under the row.
+    if (options.byIdOnly === true) return undefined;
+    const foundId = yield* findSaasByName(accountId, name);
+    return foundId === undefined ? undefined : yield* getApp(accountId, foundId);
+  });
+
+/**
+ * Owned: refresh by the stored id ONLY (gone is `undefined`, never a same-named app). Cold: find the app by `applicationId` or exact name and hand it
+ * back `Unowned`, so Alchemy refuses to take it over until the stack says `adopt(true)`.
+ * ★ `olds` MAY PREDATE `teamDomain` (state written by the openbao copy of this resource): the host
+ *   Cloudflare reports for the app stands in, so the first plan after the move can still read.
+ */
+export const readSaasOidc = (
+  accountId: string,
+  id: string,
+  olds: SaasOidcApplicationProps | undefined,
+  output: SaasOidcApplicationAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const name = yield* resolveName(id, output?.name ?? olds?.name);
+    const owned = output?.applicationId;
+    const observed = yield* observe(accountId, owned ?? olds?.applicationId, name, {
+      byIdOnly: owned !== undefined,
+    });
+    if (observed === undefined) return undefined;
+    const attributes = toAttributes(
+      observed,
+      output?.accountId ?? accountId,
+      name,
+      output?.teamDomain ?? olds?.teamDomain,
+    );
+    if (attributes === undefined) return undefined;
+    return owned !== undefined ? attributes : Unowned(attributes);
+  });
+
+const missing = (what: string) =>
+  Effect.fail(
+    new SaasOidcError({
+      message: `SaaS OIDC ${what} succeeded but the GET did not return the app.`,
+    }),
+  );
+
+/** observe, ensure (create or sync), read back. A no-op when nothing drifted. */
+export const reconcileSaasOidc = (
+  accountId: string,
+  id: string,
+  news: SaasOidcApplicationProps,
+  output: SaasOidcApplicationAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const invalid = validateSaasOidc(news);
+    if (invalid !== undefined) return yield* Effect.fail(invalid);
+    const name = yield* resolveName(id, news.name);
+    // ★ A stored applicationId means the row owns THAT app: if it is gone, create (or refuse),
+    //   never adopt whatever app now carries the name. Only a cold run may look up by name.
+    const ownedId = output?.applicationId;
+    let observed: ObservedApp | undefined = yield* observe(
+      accountId,
+      ownedId ?? news.applicationId,
+      name,
+      { byIdOnly: ownedId !== undefined },
+    );
+    // ⛔ BEFORE ANY WRITE TO AN EXISTING APP: a wrong team domain must not cost it an update.
+    //   A FIRST CREATE has no app to compare with, so it is checked against the account's Zero
+    //   Trust organization instead (`checkTeamBeforeCreate`, below). ⚠️ That read needs a token
+    //   permission the app write does not (saas-oidc-team.ts): where it cannot be read, a wrong
+    //   `teamDomain` still writes the app and then fails the post-write check, leaving a live app
+    //   with no state row. docs/saas-oidc.md says what to do.
+    const wrongTeam =
+      observed === undefined ? undefined : checkTeam(news.teamDomain, observed, output?.teamDomain);
+    if (wrongTeam !== undefined) return yield* Effect.fail(wrongTeam);
+    const write = writeBody(news, name);
+    if (observed === undefined) {
+      const wrongOrganization = yield* checkTeamBeforeCreate(accountId, news.teamDomain);
+      if (wrongOrganization !== undefined) return yield* Effect.fail(wrongOrganization);
+      const createdId = yield* createApp(accountId, write);
+      observed = yield* getApp(accountId, createdId);
+      if (observed === undefined) return yield* missing('create');
+    } else if (needsSync(news, observed, name)) {
+      const appId = observed.id;
+      if (appId === undefined) {
+        return yield* Effect.fail(new SaasOidcError({ message: 'SaaS OIDC app has no id.' }));
+      }
+      yield* updateApp(accountId, appId, write);
+      observed = yield* getApp(accountId, appId);
+      if (observed === undefined) return yield* missing('update');
+    }
+    const teamAfterWrite = checkTeam(news.teamDomain, observed, output?.teamDomain);
+    if (teamAfterWrite !== undefined) return yield* Effect.fail(teamAfterWrite);
+    const attributes = toAttributes(observed, accountId, name, news.teamDomain);
+    if (attributes === undefined) {
+      return yield* Effect.fail(
+        new SaasOidcError({
+          message: 'Cloudflare returned a SaaS OIDC application without an id, aud or client id.',
+        }),
+      );
+    }
+    return attributes;
+  });
+
+export const deleteSaasOidc = (output: SaasOidcApplicationAttributes) =>
+  deleteApp(output.accountId, output.applicationId);

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

@@ -0,0 +1,180 @@
+/**
+ * A response the SDK cannot validate must not carry the client secret out of this package.
+ *
+ * ⛔ THE LEAK THIS PINS. Under STRICT response validation, `@distilled.cloud/cloudflare@1.0.0-rc.13`
+ *   fails a 2xx response it cannot decode with `CloudflareParseError({ body, cause })`, `body` being
+ *   the WHOLE parsed response (protocol.ts:452-457). For a confidential client a create response
+ *   carries `client_secret`, so a raw SDK error that reached a log or a trace would print it.
+ *   `fake-access.ts` plants `FAKE_CLIENT_SECRET` in a body the decoder rejects, for each call.
+ * ★ THE FIRST TEST IS THE PREMISE: the raw SDK error really does carry the secret under the strict
+ *   switch `strict` provides, so a renamed key or a lenient default fails there, not silently below.
+ */
+import { describe, expect, spyOn, test } from 'bun:test';
+import { CloudflareParseError } from '@distilled.cloud/cloudflare/Errors';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { FAKE_CLIENT_SECRET, fakeAccess } from './fake-access.ts';
+import { FAKE_ACCOUNT, fakeClientLayer } from './fake-mesh.ts';
+import { deleteSaasOidc } from './saas-oidc-lifecycle.ts';
+import { sdkWrites } from './saas-oidc-api.ts';
+import { LIVE_OIDC, publicClient, reconcile, run, strict } from './saas-oidc-harness.ts';
+
+/** Run `go` with the console watched; the second member is everything it logged. */
+const watched = async <T>(go: () => Promise<T>): Promise<readonly [T, string]> => {
+  const spies = [spyOn(console, 'log'), spyOn(console, 'error'), spyOn(console, 'warn')];
+  try {
+    const result = await go();
+    return [result, JSON.stringify(spies.map((spy) => spy.mock.calls))];
+  } finally {
+    for (const spy of spies) spy.mockRestore();
+  }
+};
+
+/** Everything a caller or a log could render from a failure: nothing may hold the secret. */
+const surfaces = (exit: Exit.Exit<unknown, unknown>, logged: string): string[] => {
+  if (!Exit.isFailure(exit)) throw new Error('expected a failure');
+  const error = Cause.squash(exit.cause);
+  const fields = (error instanceof Error ? Object.getOwnPropertyNames(error) : []).map(
+    (key) => (error as unknown as Record<string, unknown>)[key],
+  );
+  return [
+    String(error),
+    JSON.stringify(error),
+    JSON.stringify(fields),
+    error instanceof Error ? error.message : '',
+    Cause.pretty(exit.cause),
+    logged,
+  ];
+};
+
+const failureOf = (exit: Exit.Exit<unknown, unknown>): { _tag: string; message: string } => {
+  if (!Exit.isFailure(exit)) throw new Error('expected a failure');
+  return Cause.squash(exit.cause) as { _tag: string; message: string };
+};
+
+type Outcome = Promise<Exit.Exit<unknown, unknown>>;
+
+/**
+ * The error rc.13 builds (protocol.ts:452-457) for a create that answered with a secret: the whole
+ * envelope as `body`, a SchemaError-like `cause` quoting the offending value.
+ */
+const rawParseError = () =>
+  new CloudflareParseError({
+    body: { success: true, result: { id: 'app', saas_app: { client_secret: FAKE_CLIENT_SECRET } } },
+    cause: `Expected string, actual ${FAKE_CLIENT_SECRET}`,
+  });
+
+/** Stand in for one SDK write that fails with the raw parse error, then put the real ones back. */
+const withRawWrite = async (which: 'create' | 'update', go: () => Outcome): Outcome => {
+  const real = { ...sdkWrites };
+  Object.assign(sdkWrites, { [which]: () => Effect.fail(rawParseError()) });
+  try {
+    return await go();
+  } finally {
+    Object.assign(sdkWrites, real);
+  }
+};
+
+/**
+ * One way to make each call fail with CloudflareParseError, and what the sanitized error names.
+ * ⚠️ create and update go through `sdkWrites` because rc.13 cannot be made to fail them (their
+ *   response decodes against `S.Unknown`, see saas-oidc-error.ts); the other three are the REAL SDK
+ *   under strict validation, fed a body its typed schema rejects.
+ */
+const scenarios: ReadonlyArray<readonly [string, string, () => Outcome]> = [
+  [
+    'create',
+    'application create',
+    () =>
+      withRawWrite('create', () =>
+        run(fakeAccess(), (p) => Effect.exit(reconcile(p, publicClient()))),
+      ),
+  ],
+  [
+    'update',
+    'application update',
+    () => {
+      const fake = fakeAccess();
+      const live = fake.seed({ name: 'Headlamp', policies: ['policy-old'], saas_app: LIVE_OIDC });
+      return withRawWrite('update', () =>
+        run(fake, (p) => Effect.exit(reconcile(p, publicClient({ applicationId: live.id })))),
+      );
+    },
+  ],
+  [
+    'list',
+    'application list',
+    () =>
+      run(fakeAccess({ malformed: ['list'] }), (p) =>
+        Effect.exit(strict(reconcile(p, publicClient()))),
+      ),
+  ],
+  [
+    'org',
+    'organization read',
+    () =>
+      run(fakeAccess({ malformed: ['org'] }), (p) =>
+        Effect.exit(strict(reconcile(p, publicClient()))),
+      ),
+  ],
+  [
+    'delete',
+    'application delete',
+    async () => {
+      const fake = fakeAccess({ malformed: ['delete'] });
+      const made = await run(fake, (p) => reconcile(p, publicClient()));
+      return Effect.runPromiseExit(
+        strict(deleteSaasOidc(made)).pipe(Effect.provide(fakeClientLayer(fake))),
+      );
+    },
+  ],
+];
+
+describe('a response the SDK cannot validate', () => {
+  test('premise: the real SDK raises CloudflareParseError carrying the whole response', async () => {
+    const fake = fakeAccess({ malformed: ['delete'] });
+    const made = await run(fake, (p) => reconcile(p, publicClient()));
+    const raw = await Effect.runPromise(
+      strict(
+        zeroTrust.deleteAccessApplicationForAccount({
+          accountId: FAKE_ACCOUNT,
+          appId: made.applicationId,
+        }),
+      ).pipe(Effect.flip, Effect.provide(fakeClientLayer(fake))),
+    );
+    expect(raw).toMatchObject({
+      _tag: 'CloudflareParseError',
+      body: { result: { client_secret: FAKE_CLIENT_SECRET } },
+    });
+  });
+
+  test.each(scenarios)(
+    '%s: only the operation is named, never a body or a field',
+    async (_op, name, go) => {
+      const [exit, logged] = await watched(go);
+      const error = failureOf(exit);
+      expect(error._tag).toBe('SaasOidcError');
+      expect(error.message).toContain(name);
+      expect(error.message).toContain('withheld');
+      for (const surface of surfaces(exit, logged)) {
+        expect(surface).not.toContain(FAKE_CLIENT_SECRET);
+        expect(surface).not.toContain('client_secret');
+      }
+    },
+  );
+
+  test('the seam leaves the real SDK in place afterwards', () => {
+    expect(sdkWrites.create).toBe(zeroTrust.createAccessApplicationForAccount);
+    expect(sdkWrites.update).toBe(zeroTrust.updateAccessApplicationForAccount);
+  });
+
+  test('the raw read (not an SDK call) fails on a non-JSON body without echoing it', async () => {
+    const [exit, logged] = await watched(() =>
+      run(fakeAccess({ malformed: ['get'] }), (p) => Effect.exit(reconcile(p, publicClient()))),
+    );
+    expect(failureOf(exit).message).toContain('was not JSON');
+    for (const surface of surfaces(exit, logged)) expect(surface).not.toContain(FAKE_CLIENT_SECRET);
+  });
+});