@homeflare/alchemy 0.48.1 → 0.50.0

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

@@ -0,0 +1,227 @@
+/**
+ * The pure half of SaasOidcApplication: validation, the issuer URLs (the team domain is a prop,
+ * never a constant), drift, the write body and the attribute mapping.
+ */
+import { describe, expect, test } from 'bun:test';
+import { parseApp } from './saas-oidc-wire.ts';
+import {
+  checkTeam,
+  issuerFor,
+  needsSync,
+  toAttributes,
+  validateSaasOidc,
+  writeBody,
+} from './saas-oidc-form.ts';
+import { publicClient } from './saas-oidc-harness.ts';
+
+const live = (over: Record<string, unknown> = {}) =>
+  parseApp({
+    id: 'app-1',
+    aud: 'aud-1',
+    type: 'saas',
+    name: 'Headlamp',
+    domain: 'example.cloudflareaccess.com/cdn-cgi/access/sso/oidc/cid-1',
+    policies: [{ id: 'policy-admin' }],
+    saas_app: {
+      auth_type: 'oidc',
+      client_id: 'cid-1',
+      client_secret: 'must-never-be-read',
+      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,
+    },
+    ...over,
+  });
+
+describe('validateSaasOidc', () => {
+  test('accepts a public PKCE client', () => {
+    expect(validateSaasOidc(publicClient())).toBeUndefined();
+  });
+
+  test.each([
+    '',
+    'https://example.cloudflareaccess.com',
+    'example.cloudflareaccess.com/x',
+    'Team',
+    'nodot',
+  ])('refuses teamDomain %p', (teamDomain) => {
+    expect(validateSaasOidc(publicClient({ teamDomain }))?.message).toContain('teamDomain');
+  });
+
+  test('refuses the public-client flag without the PKCE grant', () => {
+    const props = publicClient();
+    const bad = {
+      ...props,
+      saasApp: { ...props.saasApp, grantTypes: ['authorization_code' as const] },
+    };
+    expect(validateSaasOidc(bad)?.message).toContain('authorization_code_with_pkce');
+  });
+
+  test('refuses an empty name', () => {
+    expect(validateSaasOidc(publicClient({ name: ' ' }))?.message).toContain('name');
+  });
+});
+
+describe('issuer', () => {
+  test('is built from the declared team domain, whatever it is', () => {
+    expect(issuerFor('other.cloudflareaccess.com', 'c')).toBe(
+      'https://other.cloudflareaccess.com/cdn-cgi/access/sso/oidc/c',
+    );
+  });
+
+  test('the attributes expose issuer, clientId and jwksEndpoint for the declared team', () => {
+    const attrs = toAttributes(live(), 'acct', 'x', 'example.cloudflareaccess.com');
+    expect(attrs).toMatchObject({
+      teamDomain: 'example.cloudflareaccess.com',
+      clientId: 'cid-1',
+      issuer: 'https://example.cloudflareaccess.com/cdn-cgi/access/sso/oidc/cid-1',
+      jwksEndpoint: 'https://example.cloudflareaccess.com/cdn-cgi/access/sso/oidc/cid-1/jwks',
+      configurationEndpoint:
+        'https://example.cloudflareaccess.com/cdn-cgi/access/sso/oidc/cid-1/.well-known/openid-configuration',
+    });
+    const other = toAttributes(live(), 'acct', 'x', 'other.cloudflareaccess.com');
+    expect(other?.issuer).toStartWith('https://other.cloudflareaccess.com/');
+    expect(JSON.stringify(attrs)).not.toContain('schenanigans');
+  });
+
+  test('with no declared team (state from before the prop) the live domain host stands in', () => {
+    expect(toAttributes(live(), 'acct', 'x', undefined)?.teamDomain).toBe(
+      'example.cloudflareaccess.com',
+    );
+  });
+
+  test('the client secret the wire carries reaches neither the parse nor the attributes', () => {
+    expect(JSON.stringify(live())).not.toContain('must-never-be-read');
+    expect(
+      JSON.stringify(toAttributes(live(), 'acct', 'x', 'example.cloudflareaccess.com')),
+    ).not.toContain('must-never-be-read');
+  });
+
+  test('an app with no client id is not describable', () => {
+    expect(toAttributes(live({ saas_app: { auth_type: 'oidc' } }), 'a', 'x', 'e.test.com')).toBe(
+      undefined,
+    );
+  });
+
+  test('a declared team that disagrees with the app is refused', () => {
+    expect(checkTeam('other.cloudflareaccess.com', live())?.message).toContain(
+      'example.cloudflareaccess.com',
+    );
+    expect(checkTeam('EXAMPLE.cloudflareaccess.com', live())).toBeUndefined();
+  });
+
+  test('with no domain reported, a declaration that moves the recorded team is refused', () => {
+    const noDomain = live({ domain: undefined });
+    expect(
+      checkTeam('other.cloudflareaccess.com', noDomain, 'example.cloudflareaccess.com')?.message,
+    ).toContain('issuer cannot move');
+    expect(
+      checkTeam('EXAMPLE.cloudflareaccess.com', noDomain, 'example.cloudflareaccess.com'),
+    ).toBeUndefined();
+    // Nothing recorded (first create, cold adoption): nothing to compare, the declaration stands.
+    expect(checkTeam('other.cloudflareaccess.com', noDomain)).toBeUndefined();
+  });
+});
+
+describe('needsSync', () => {
+  test('is false for a live app that matches the declaration', () => {
+    expect(needsSync(publicClient(), live(), 'Headlamp')).toBe(false);
+  });
+
+  test('flips on redirect URIs, grants, PKCE flag, lifetime, policies and name', () => {
+    const props = publicClient();
+    const withSaas = (patch: object) => ({ ...props, saasApp: { ...props.saasApp, ...patch } });
+    expect(needsSync(withSaas({ redirectUris: ['https://x.test/cb'] }), live(), 'Headlamp')).toBe(
+      true,
+    );
+    expect(needsSync(withSaas({ grantTypes: ['authorization_code'] }), live(), 'Headlamp')).toBe(
+      true,
+    );
+    expect(needsSync(withSaas({ allowPkceWithoutClientSecret: false }), live(), 'Headlamp')).toBe(
+      true,
+    );
+    expect(needsSync(withSaas({ accessTokenLifetime: '1h' }), live(), 'Headlamp')).toBe(true);
+    expect(needsSync(withSaas({ refreshTokenLifetime: '30d' }), live(), 'Headlamp')).toBe(true);
+    expect(needsSync({ ...props, policies: ['a', 'b'] }, live(), 'Headlamp')).toBe(true);
+    expect(needsSync(props, live(), 'Renamed')).toBe(true);
+  });
+
+  test('ignores the order of sets', () => {
+    const props = publicClient();
+    const reordered = {
+      ...props,
+      saasApp: { ...props.saasApp, scopes: ['groups', 'openid', 'email'] as const },
+    };
+    expect(needsSync(reordered, live(), 'Headlamp')).toBe(false);
+  });
+});
+
+describe('policy order is part of the declaration', () => {
+  const ranked = (policies: Array<{ id: string; precedence?: number }>) =>
+    live({ policies: policies });
+
+  test('the same policies in a different order are drift', () => {
+    const props = publicClient({ policies: ['policy-a', 'policy-b'] });
+    const inOrder = ranked([
+      { id: 'policy-a', precedence: 1 },
+      { id: 'policy-b', precedence: 2 },
+    ]);
+    const swapped = ranked([
+      { id: 'policy-b', precedence: 1 },
+      { id: 'policy-a', precedence: 2 },
+    ]);
+    expect(needsSync(props, inOrder, 'Headlamp')).toBe(false);
+    expect(needsSync(props, swapped, 'Headlamp')).toBe(true);
+    expect(needsSync({ ...props, policies: ['policy-b', 'policy-a'] }, inOrder, 'Headlamp')).toBe(
+      true,
+    );
+  });
+
+  test('the live order is the API precedence, whatever order the array arrives in', () => {
+    const arrival = ranked([
+      { id: 'policy-b', precedence: 2 },
+      { id: 'policy-a', precedence: 1 },
+    ]);
+    expect(arrival.policyIds).toEqual(['policy-a', 'policy-b']);
+    expect(
+      needsSync(publicClient({ policies: ['policy-a', 'policy-b'] }), arrival, 'Headlamp'),
+    ).toBe(false);
+  });
+
+  test('without a precedence on every entry the array order stands', () => {
+    const partial = ranked([{ id: 'policy-b', precedence: 2 }, { id: 'policy-a' }]);
+    expect(partial.policyIds).toEqual(['policy-b', 'policy-a']);
+  });
+
+  test('a missing or extra policy is drift too', () => {
+    const one = ranked([{ id: 'policy-a', precedence: 1 }]);
+    expect(needsSync(publicClient({ policies: ['policy-a', 'policy-b'] }), one, 'Headlamp')).toBe(
+      true,
+    );
+    expect(needsSync(publicClient({ policies: [] }), one, 'Headlamp')).toBe(true);
+  });
+});
+
+describe('writeBody', () => {
+  test('a public client sends the PKCE grant and the flag, and no client secret field', () => {
+    const body = writeBody(publicClient(), 'Headlamp');
+    expect(body.saasApp).toMatchObject({
+      authType: 'oidc',
+      grantTypes: ['authorization_code_with_pkce'],
+      allowPkceWithoutClientSecret: true,
+    });
+    expect(JSON.stringify(body)).not.toContain('secret":"');
+    expect(body.sessionDuration).toBe('24h');
+    expect(body.appLauncherVisible).toBe(false);
+  });
+
+  test('the flag defaults to a confidential client', () => {
+    const props = publicClient();
+    const { allowPkceWithoutClientSecret: _flag, ...rest } = props.saasApp;
+    expect(writeBody({ ...props, saasApp: rest }, 'x').saasApp.allowPkceWithoutClientSecret).toBe(
+      false,
+    );
+  });
+});

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