@homeflare/alchemy 0.48.1 → 0.50.0

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

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

@@ -0,0 +1,147 @@
+/**
+ * The declared shape of `HomeFlare.Access.SaasOidcApplication` and what it reports back, apart from
+ * the pure helpers that use them (saas-oidc-form.ts re-exports both types, so imports keep working).
+ *
+ * ★ EVERY PROP FIELD CARRIES A JSDOC (provider standard S5). Where the wording below is the API's,
+ *   it is the SDK's own field doc on the request type
+ *   (`@distilled.cloud/cloudflare@1.0.0-rc.13` `zero-trust` `CreateAccessApplicationForAccountRequest`
+ *   and `AccessApplicationsCreateRequestSaasAppOIDCSaaSApp`, src/services/zero_trust.ts:9025-9053 and
+ *   :9728-9794), so a reader gets the vendor's meaning without leaving the editor.
+ * ⛔ THE ATTRIBUTES NEVER HOLD THE CLIENT SECRET, and nothing here can: there is no field for it.
+ */
+
+/**
+ * An OIDC flow Access can serve for the client: the five literals the SDK names
+ * (`AccessApplicationsCreateRequestSaasAppOIDCSaaSAppGrantTypesItem`, zero_trust.ts:8946-8951).
+ */
+export type OidcGrantType =
+  | 'authorization_code'
+  | 'authorization_code_with_pkce'
+  | 'refresh_tokens'
+  | 'hybrid'
+  | 'implicit';
+
+/** The user information the client may request from Access. */
+export type OidcScope = 'openid' | 'email' | 'profile' | 'groups';
+
+export interface SaasOidcApplicationProps {
+  /**
+   * Live Access application UUID. Set this when adopting a SaaS app that already exists. Without
+   * it the app is found by exact `name` among saas apps, which also works but refuses two matches.
+   */
+  readonly applicationId?: string;
+  /** The app's name. Defaults to a physical name derived from the logical id. */
+  readonly name?: string;
+  /**
+   * The Zero Trust team domain the issuer lives on, a bare hostname such as
+   * `example.cloudflareaccess.com`: no scheme, no path. Not read from the environment, so the
+   * issuer in the attributes is the one the declaration says.
+   */
+  readonly teamDomain: string;
+  /**
+   * How long Access sessions for this app last, in the API's duration format (`300ms` or `2h45m`).
+   * Written on create and on any sync; not drift-checked.
+   * @default '24h'
+   */
+  readonly sessionDuration?: string;
+  /**
+   * Ids of the identity providers users may pick for this app. Written on create and on any sync;
+   * not drift-checked.
+   * @default every IdP configured in the account (the field is left out of the write)
+   */
+  readonly allowedIdps?: ReadonlyArray<string>;
+  /**
+   * `true` makes users skip the identity-provider selection step; the API requires exactly one
+   * entry in `allowedIdps` then. Written on create and on any sync; not drift-checked.
+   * @default left out of the write (the API's default)
+   */
+  readonly autoRedirectToIdentity?: boolean;
+  /**
+   * Show the app in the App Launcher. Written on create and on any sync; not drift-checked.
+   * @default false
+   */
+  readonly appLauncherVisible?: boolean;
+  /**
+   * Ids of reusable Access policies, in ascending order of precedence (the SDK's own wording:
+   * zero_trust.ts:9774). The ORDER is part of the declaration: a reorder is drift and is synced.
+   */
+  readonly policies: ReadonlyArray<string>;
+  /** The OIDC client: the `saas_app` object of the Access application. */
+  readonly saasApp: {
+    /** The authentication protocol of the SaaS app. Only `oidc` is supported by this resource. */
+    readonly authType: 'oidc';
+    /**
+     * The permitted URLs for Cloudflare to return authorization codes and tokens to. Compared as
+     * a set (order is not significant to the API).
+     */
+    readonly redirectUris: ReadonlyArray<string>;
+    /** The user information shared with the client. Compared as a set. */
+    readonly scopes: ReadonlyArray<OidcScope>;
+    /** The OIDC flows the client may use. Compared as a set. */
+    readonly grantTypes: ReadonlyArray<OidcGrantType>;
+    /** Lifetime of the access token after creation: `m` or `h` units, `1m` to `24h` (the SDK field doc). */
+    readonly accessTokenLifetime: string;
+    /**
+     * How long a refresh token is valid after creation: `m`, `h` or `d` units, longer than `1m`
+     * (the SDK field doc). Needed for the `refresh_tokens` grant. Sent as `refreshTokenOptions.lifetime`.
+     * @default left out of the write
+     */
+    readonly refreshTokenLifetime?: string;
+    /**
+     * `true` makes this a PUBLIC client: the token endpoint does not require a client secret when
+     * the `authorization_code_with_pkce` grant is used, and then no secret exists to keep. Refused
+     * without that grant.
+     * @default false (a confidential client)
+     */
+    readonly allowPkceWithoutClientSecret?: boolean;
+    /**
+     * The URL the app's tile in the App Launcher sends users to. Written on create and on any
+     * sync; not drift-checked.
+     * @default left out of the write
+     */
+    readonly appLauncherUrl?: string;
+  };
+}
+
+export interface SaasOidcApplicationAttributes {
+  /** The Access application UUID. */
+  readonly applicationId: string;
+  /** The application audience tag, the `aud` of the Access JWTs for this app. */
+  readonly aud: string;
+  /** The `domain` Cloudflare reports for the app (the OIDC issuer without its scheme). */
+  readonly domain: string;
+  /** The app's name as Cloudflare reports it. */
+  readonly name: string;
+  /** The account the app lives in. */
+  readonly accountId: string;
+  /** The declared team domain (or, for state that predates the prop, the host Cloudflare reports). */
+  readonly teamDomain: string;
+  /** The OIDC client id, for the relying party's configuration. */
+  readonly clientId: string;
+  /** `https://<teamDomain>/cdn-cgi/access/sso/oidc/<clientId>`. */
+  readonly issuer: string;
+  /** `<issuer>/authorization`. */
+  readonly authorizationEndpoint: string;
+  /** `<issuer>/token`. */
+  readonly tokenEndpoint: string;
+  /** The signing keys, for a verifier that validates ID tokens. */
+  readonly jwksEndpoint: string;
+  /** `<issuer>/userinfo`. */
+  readonly userinfoEndpoint: string;
+  /** `<issuer>/.well-known/openid-configuration`. */
+  readonly configurationEndpoint: string;
+  /** The redirect URIs the live app permits. */
+  readonly redirectUris: ReadonlyArray<string>;
+  /** The scopes the live app serves. */
+  readonly scopes: ReadonlyArray<string>;
+  /** The grant types the live app allows. */
+  readonly grantTypes: ReadonlyArray<string>;
+  /** The live access token lifetime, or `''` when Cloudflare reports none. */
+  readonly accessTokenLifetime: string;
+  /** The live refresh token lifetime, or `''` when Cloudflare reports none. */
+  readonly refreshTokenLifetime: string;
+  /** When Cloudflare created the app, if it says. */
+  readonly createdAt: string | undefined;
+  /** When Cloudflare last updated the app, if it says. */
+  readonly updatedAt: string | undefined;
+}

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

@@ -0,0 +1,85 @@
+/** SaasOidcApplicationProvider's read, delete and adoption paths against the fake Access API. */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import { TEAM, fakeAccess } from './fake-access.ts';
+import { FAKE_ACCOUNT, fakeClientLayer } from './fake-mesh.ts';
+import { deleteSaasOidc } from './saas-oidc-lifecycle.ts';
+import { LIVE_OIDC, publicClient, read, reconcile, run, writes } from './saas-oidc-harness.ts';
+
+describe('read', () => {
+  test('finds a cold app by exact name across pages and returns it Unowned', async () => {
+    const fake = fakeAccess();
+    fake.seed({ name: 'Headlamp-old' });
+    fake.seed({ name: 'Other', type: 'self_hosted' });
+    const live = fake.seed({ name: 'Headlamp', policies: ['policy-admin'], saas_app: LIVE_OIDC });
+    const probe = await run(fake, (p) => read(p, publicClient()));
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({
+      applicationId: live.id,
+      clientId: live.saas_app?.['client_id'],
+      accountId: FAKE_ACCOUNT,
+      redirectUris: ['https://headlamp.example.test/oidc-callback'],
+    });
+  });
+
+  test('an owned row refreshes by id and is not Unowned', async () => {
+    const fake = fakeAccess();
+    const [created, refreshed] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const made = yield* reconcile(p, publicClient());
+        return [made, yield* read(p, publicClient(), made)] as const;
+      }),
+    );
+    expect(Unowned.is(refreshed)).toBe(false);
+    expect(refreshed).toEqual(created);
+  });
+
+  test('an owned row whose app is gone reads undefined, not a same-named app', async () => {
+    const fake = fakeAccess();
+    const made = await run(fake, (p) => reconcile(p, publicClient()));
+    fake.apps.delete(made.applicationId);
+    fake.seed({ name: 'Headlamp', policies: ['policy-admin'], saas_app: LIVE_OIDC });
+    expect(await run(fake, (p) => read(p, publicClient(), made))).toBeUndefined();
+  });
+
+  test('adopts by applicationId from state that predates the teamDomain prop', async () => {
+    const fake = fakeAccess();
+    const live = fake.seed({ name: 'OpenBao', policies: ['policy-admin'], saas_app: LIVE_OIDC });
+    const { teamDomain: _team, ...before } = publicClient({
+      applicationId: live.id,
+      name: 'OpenBao',
+    });
+    const probe = await run(fake, (p) => read(p, before as never));
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ applicationId: live.id, teamDomain: TEAM });
+  });
+
+  test('adopting a matching live app is a no-op: zero writes', async () => {
+    const fake = fakeAccess();
+    const live = fake.seed({ name: 'Headlamp', policies: ['policy-admin'], saas_app: LIVE_OIDC });
+    const out = await run(fake, (p) => reconcile(p, publicClient({ applicationId: live.id })));
+    expect(out.applicationId).toBe(live.id);
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('answers undefined when nothing matches', async () => {
+    const fake = fakeAccess();
+    expect(await run(fake, (p) => read(p, publicClient()))).toBeUndefined();
+  });
+});
+
+describe('delete', () => {
+  test('removes the app, and a second delete of the same app is a success', async () => {
+    const fake = fakeAccess();
+    const out = await run(fake, (p) => reconcile(p, publicClient()));
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        yield* deleteSaasOidc(out);
+        yield* deleteSaasOidc(out);
+      }).pipe(Effect.provide(fakeClientLayer(fake))),
+    );
+    expect(fake.apps.size).toBe(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE', 'DELETE']);
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * The attributes a consumer of a SaasOidcApplication reads through `app.issuer` must stay
+ * resolved when the app itself is UPDATED, or every consumer re-plans (the Talos
+ * KubeAuthenticationConfig would restart kube-apiserver for a change that cannot move the issuer).
+ * Alchemy's plan keeps only the provider's `stables` resolved for an updated resource (Plan.ts
+ * `withStables`, beta.81), so this runs the real engine with a downstream resource and counts its
+ * reconciles.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeAccess } from './fake-access.ts';
+import { IssuerConsumer, consumerProvider } from './saas-oidc-consumer.ts';
+import { engine, failureOf, publicClient, writes } from './saas-oidc-harness.ts';
+import { SaasOidcApplication } from './saas-oidc.ts';
+
+const declare = (redirect: string) =>
+  Effect.gen(function* () {
+    const base = publicClient();
+    const app = yield* SaasOidcApplication('headlamp', {
+      ...base,
+      saasApp: { ...base.saasApp, redirectUris: [redirect] },
+    });
+    yield* IssuerConsumer('kube-auth', { issuer: app.issuer, jwks: app.jwksEndpoint });
+  });
+
+describe('consumers of an updated SaasOidcApplication', () => {
+  test('a redirect-URI update does not re-plan a resource that reads the issuer', async () => {
+    const fake = fakeAccess();
+    const consumer = consumerProvider();
+    const stack = engine(fake, consumer.layer);
+    expect(failureOf(await stack.deploy(declare('https://a.example.test/cb')))).toBe('');
+    expect(consumer.reconciled).toHaveLength(1);
+    expect(failureOf(await stack.deploy(declare('https://b.example.test/cb')))).toBe('');
+    expect(writes(fake)).toEqual(['POST', 'PUT']);
+    expect(consumer.reconciled).toHaveLength(1);
+    expect(consumer.reconciled[0]).toContain('/cdn-cgi/access/sso/oidc/');
+  });
+});