@homeflare/alchemy 0.48.1 → 0.50.0

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

@@ -0,0 +1,128 @@
+/**
+ * SaasOidcApplication through Alchemy's real plan/apply (`engine` in saas-oidc-harness.ts) over the
+ * fake Access API. The engine owns state keys, removal policy and what gets persisted, so the
+ * handler-level tests beside this one cannot see them.
+ *
+ * ⛔ WHAT THESE PIN:
+ *   - NO CLIENT SECRET IS EVER PERSISTED: the serialised state rows (props and attributes) do not
+ *     contain the secret the fake's create response hands out.
+ *   - STATE-KEY STABILITY: a row written by the openbao copy of this resource (same type id, props
+ *     and attributes without `teamDomain`) is UPDATED IN PLACE by this one — no create, no delete,
+ *     the same application id and client id. A renamed type id would plan a second app.
+ *   - `retain` is the default: dropping the declaration leaves the app live and sends no DELETE.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { FAKE_CLIENT_SECRET, TEAM, fakeAccess } from './fake-access.ts';
+import { FAKE_ACCOUNT } from './fake-mesh.ts';
+import { LIVE_OIDC, engine, failureOf, publicClient, writes } from './saas-oidc-harness.ts';
+import { SaasOidcApplication } from './saas-oidc.ts';
+
+const ID = 'headlamp';
+const declare = (over = {}) => SaasOidcApplication(ID, publicClient(over));
+
+describe('SaasOidcApplication (the real engine)', () => {
+  test('state holds no client secret, and is keyed by the pinned type id', async () => {
+    const fake = fakeAccess();
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(declare()))).toBe('');
+    const row = stack.rows['oidc']?.['test']?.[ID];
+    expect(row?.resourceType).toBe('HomeFlare.Access.SaasOidcApplication');
+    expect(row?.status).toBe('created');
+    expect(JSON.stringify(stack.rows)).not.toContain(FAKE_CLIENT_SECRET);
+    expect(JSON.stringify(stack.rows)).not.toContain('client_secret');
+    expect(JSON.stringify(fake.seen)).not.toContain(FAKE_CLIENT_SECRET);
+    expect(row?.attr).toMatchObject({ teamDomain: TEAM, accountId: FAKE_ACCOUNT });
+  });
+
+  test('a second identical deploy writes nothing', async () => {
+    const fake = fakeAccess();
+    const stack = engine(fake);
+    await stack.deploy(declare());
+    expect(failureOf(await stack.deploy(declare()))).toBe('');
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('a row written by the openbao copy is updated in place, never replaced', async () => {
+    const fake = fakeAccess();
+    const live = fake.seed({
+      name: 'Headlamp',
+      policies: ['policy-admin'],
+      saas_app: LIVE_OIDC,
+    });
+    const clientId = String(live.saas_app?.['client_id']);
+    const stack = engine(fake);
+    const { teamDomain: _team, ...oldProps } = publicClient();
+    const issuer = `https://${TEAM}/cdn-cgi/access/sso/oidc/${clientId}`;
+    stack.rows['oidc'] = {
+      test: {
+        [ID]: {
+          resourceType: 'HomeFlare.Access.SaasOidcApplication',
+          namespace: undefined,
+          fqn: ID,
+          logicalId: ID,
+          instanceId: 'i-old',
+          providerVersion: 0,
+          status: 'created',
+          downstream: [],
+          bindings: [],
+          props: oldProps,
+          attr: {
+            applicationId: live.id,
+            aud: live.aud,
+            clientId,
+            accountId: FAKE_ACCOUNT,
+            name: 'Headlamp',
+            domain: issuer.replace('https://', ''),
+            issuer,
+          },
+        },
+      },
+    };
+    expect(failureOf(await stack.deploy(declare()))).toBe('');
+    expect(writes(fake)).toEqual([]);
+    expect(fake.apps.size).toBe(1);
+    expect(stack.rows['oidc']?.['test']?.[ID]?.attr).toMatchObject({
+      applicationId: live.id,
+      clientId,
+      teamDomain: TEAM,
+      jwksEndpoint: `${issuer}/jwks`,
+    });
+  });
+
+  test('retain is the default: dropping the declaration deletes nothing', async () => {
+    const fake = fakeAccess();
+    const stack = engine(fake);
+    await stack.deploy(declare());
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(fake.apps.size).toBe(1);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('RemovalPolicy.destroy() still reaches the implemented delete', async () => {
+    const fake = fakeAccess();
+    const stack = engine(fake);
+    await stack.deploy(declare().pipe(RemovalPolicy.destroy()));
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(fake.apps.size).toBe(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE']);
+  });
+
+  test('a live app is not taken over without adopt(true), and is with it', async () => {
+    const fake = fakeAccess();
+    fake.seed({
+      name: 'Headlamp',
+      policies: ['policy-admin'],
+      saas_app: LIVE_OIDC,
+    });
+    const refused = engine(fake);
+    expect(failureOf(await refused.deploy(declare()))).not.toBe('');
+    expect(writes(fake)).toEqual([]);
+    const taken = engine(fake);
+    expect(failureOf(await taken.deploy(declare().pipe(adopt(true))))).toBe('');
+    expect(writes(fake)).toEqual([]);
+    expect(taken.status(ID)).toBe('updated');
+  });
+});

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

@@ -0,0 +1,88 @@
+/**
+ * The team-domain check before a FIRST create (saas-oidc-team.ts): a wrong `teamDomain` is refused
+ * with no write when the account's Zero Trust organization can be read, and where it cannot be read
+ * the create goes on as it always did, leaving the documented orphan (docs/saas-oidc.md).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { type FakeAccess, TEAM, fakeAccess } from './fake-access.ts';
+import { publicClient, reconcile, run, writes } from './saas-oidc-harness.ts';
+
+const orgReads = (fake: FakeAccess) =>
+  fake.seen.filter((s) => s.method === 'GET' && s.path.endsWith('/access/organizations')).length;
+
+describe('a first create checks the declared team against the organization', () => {
+  test('a different organization domain is refused before any write', async () => {
+    const fake = fakeAccess({ org: { authDomain: 'real.cloudflareaccess.com' } });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, publicClient())));
+    expect(String(failure)).toContain('real.cloudflareaccess.com');
+    expect(String(failure)).toContain(TEAM);
+    expect(String(failure)).toContain('Refused before any write');
+    expect(writes(fake)).toEqual([]);
+    expect(fake.apps.size).toBe(0);
+  });
+
+  test('the same domain, in any case, creates the app after one organization read', async () => {
+    const fake = fakeAccess({ org: { authDomain: TEAM.toUpperCase() } });
+    const out = await run(fake, (p) => reconcile(p, publicClient()));
+    expect(out.teamDomain).toBe(TEAM);
+    expect(orgReads(fake)).toBe(1);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('the organization is read before the create and not again for an existing app', async () => {
+    const fake = fakeAccess();
+    const [first] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, publicClient());
+        yield* reconcile(p, publicClient(), created);
+        return [created] as const;
+      }),
+    );
+    expect(first.teamDomain).toBe(TEAM);
+    expect(orgReads(fake)).toBe(1);
+    const order = fake.seen.map((s) => (s.path.endsWith('/organizations') ? 'org' : s.method));
+    expect(order.indexOf('org')).toBeLessThan(order.indexOf('POST'));
+  });
+
+  test('an owned row whose app vanished is a create again, so it checks again', async () => {
+    const fake = fakeAccess();
+    const made = await run(fake, (p) => reconcile(p, publicClient()));
+    fake.apps.delete(made.applicationId);
+    await run(fake, (p) => reconcile(p, publicClient(), made));
+    expect(orgReads(fake)).toBe(2);
+  });
+
+  test('an update to an existing app never reads the organization', async () => {
+    const fake = fakeAccess();
+    const live = fake.seed({ name: 'Headlamp', policies: ['policy-old'] });
+    await run(fake, (p) => reconcile(p, publicClient({ applicationId: live.id })));
+    expect(writes(fake)).toEqual(['PUT']);
+    expect(orgReads(fake)).toBe(0);
+  });
+});
+
+describe('where the organization cannot be read, the create goes on (the known limit)', () => {
+  test.each(['unauthorized', 'forbidden', 'not_found'] as const)(
+    '%s: one attempt, then the create proceeds with a right team',
+    async (org) => {
+      const fake = fakeAccess({ org });
+      const out = await run(fake, (p) => reconcile(p, publicClient()));
+      expect(out.teamDomain).toBe(TEAM);
+      // ★ Retry.none: the SDK's default policy would retry "Authentication error" eight times.
+      expect(orgReads(fake)).toBe(1);
+      expect(writes(fake)).toEqual(['POST']);
+    },
+  );
+
+  test('a wrong team still writes the app, and the post-write check then fails the run', async () => {
+    const fake = fakeAccess({ team: 'real.cloudflareaccess.com', org: 'forbidden' });
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, publicClient({ teamDomain: 'other.cloudflareaccess.com' }))),
+    );
+    expect(String(failure)).toContain('Cloudflare reports the app on "real.cloudflareaccess.com"');
+    // The documented orphan: a live app, and no state row for it (docs/saas-oidc.md).
+    expect(writes(fake)).toEqual(['POST']);
+    expect(fake.apps.size).toBe(1);
+  });
+});

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

@@ -0,0 +1,70 @@
+/**
+ * The team-domain check that runs BEFORE a first create, so a wrong `teamDomain` is refused with no
+ * write instead of after one (saas-oidc-lifecycle.ts says where it is called).
+ *
+ * ★ THE ACCOUNT'S TEAM DOMAIN CAN BE READ BEFORE ANY APP EXISTS: `GET /accounts/{account_id}/access/
+ *   organizations` returns the Zero Trust organization, whose `auth_domain` is "The unique subdomain
+ *   assigned to your Zero Trust organization" (`@distilled.cloud/cloudflare@1.0.0-rc.13`
+ *   `listOrganizationsForAccount`, zero_trust.ts:168990 for the path and :238313-238324 for the
+ *   operation; `ListOrganizationsResponse.authDomain`, :169161). Alchemy's own
+ *   `Cloudflare/Access/Organization.ts` (beta.81, `observe`, line 338) reads it the same way. The
+ *   app's OIDC issuer host is that same domain, which is what `checkTeam` already compares after
+ *   the write.
+ * ⚠️ BUT IT IS A DIFFERENT API-TOKEN PERMISSION than the one that writes the app. Cloudflare's docs
+ *   (developers.cloudflare.com/fundamentals/api/reference/permissions, read 2026-10-09) give
+ *   `Access: Organizations Read` (or `Access: Organizations, Identity Providers, and Groups Read`)
+ *   for this endpoint, while creating an Access application needs `Access: Apps and Policies
+ *   Write` (the same docs, e.g. cloudflare-one/access-controls/ai-controls/secure-mcp-servers). So
+ *   a token minted only for the app write may be refused here.
+ * ★ THEREFORE THE CHECK IS ADVISORY WHERE IT CANNOT READ, AND STRICT WHERE IT CAN. Refused only when
+ *   the organization was read and names a different domain. A token that may not read it
+ *   (`Unauthorized`, `Forbidden`) or an account with no organization (`OrganizationNotFound`)
+ *   gives no answer, and the create goes on exactly as before, with the post-write `checkTeam`
+ *   still the backstop: that is the documented known limit (docs/saas-oidc.md). Any other failure
+ *   (a throttle, a 5xx) fails the run here, before a write; run again.
+ * ★ ONE ATTEMPT (`Retry.none`, retry.ts:48-51). The SDK's default policy retries "Authentication
+ *   error", which is what a token without the permission gets, up to eight times with backoff
+ *   (core retry.ts `makeDefault`): a first create would wait for an answer it can never get.
+ */
+import * as Retry from '@distilled.cloud/cloudflare/Retry';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import { SaasOidcError, withheld } from './saas-oidc-error.ts';
+
+/**
+ * ⚠️ WHY A TAG PREDICATE AND NOT `catchTags` for these three. `Forbidden` is built by the SDK's 4xx
+ *   mapping (protocol.ts:164-169 for code 10001, :423-436 for a bare 403) but is not in this
+ *   operation's declared error union (it lists `Unauthorized`, `OrganizationNotFound`, … only), so
+ *   `catchTags({ Forbidden })` does not typecheck. Which of `Unauthorized` (code 10000 "Authentication
+ *   error", protocol.ts:155-158) and `Forbidden` (10001 "Method not allowed for token") a token
+ *   without the permission gets was not measured live, so both stand. Tag equality only: no status,
+ *   no message, as `retryTransient` in saas-oidc-api.ts does.
+ */
+const cannotRead = (error: { readonly _tag: string }): boolean =>
+  error._tag === 'Unauthorized' ||
+  error._tag === 'Forbidden' ||
+  error._tag === 'OrganizationNotFound';
+
+/** The organization's `auth_domain`, or `undefined` when this token cannot read it or there is none. */
+const readAuthDomain = (accountId: string) =>
+  zeroTrust.listOrganizationsForAccount({ accountId }).pipe(
+    Retry.none,
+    Effect.map((organization) => organization.authDomain ?? undefined),
+    Effect.catchTag('CloudflareParseError', withheld('organization read')),
+    Effect.catchIf(cannotRead, () => Effect.succeed(undefined)),
+  );
+
+/**
+ * A refusal when the account's organization is read and its domain is not the declared one; else
+ * `undefined` (it matches, or it could not be read, see above). Hostnames compare case-insensitively.
+ */
+export const checkTeamBeforeCreate = (accountId: string, teamDomain: string) =>
+  readAuthDomain(accountId).pipe(
+    Effect.map((authDomain) =>
+      authDomain === undefined || authDomain.toLowerCase() === teamDomain.toLowerCase()
+        ? undefined
+        : new SaasOidcError({
+            message: `SaasOidcApplication declares teamDomain "${teamDomain}" but this account's Zero Trust organization is "${authDomain}". Refused before any write; no application was created.`,
+          }),
+    ),
+  );

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

@@ -0,0 +1,116 @@
+/**
+ * The wire shapes of a SaaS OIDC application, and the parse that reads them: pure, no Effect, no
+ * request. saas-oidc-api.ts says why the read is raw JSON (the SDK's responses drop `saas_app`).
+ *
+ * ⛔ `parseApp` COPIES NAMED FIELDS ONLY, and `client_secret` is not among them: an `ObservedApp`
+ *   has nowhere to hold the client secret, so no code path can persist or log one.
+ */
+
+/** The OIDC half of a live SaaS app, from the wire JSON. */
+export interface ObservedSaas {
+  readonly authType: string | undefined;
+  readonly clientId: string | undefined;
+  readonly redirectUris: ReadonlyArray<string> | undefined;
+  readonly scopes: ReadonlyArray<string> | undefined;
+  readonly grantTypes: ReadonlyArray<string> | undefined;
+  readonly accessTokenLifetime: string | undefined;
+  readonly refreshTokenLifetime: string | undefined;
+  readonly allowPkceWithoutClientSecret: boolean | undefined;
+}
+
+/** A live Access application as this package sees it. ⛔ There is no secret field, on purpose. */
+export interface ObservedApp {
+  readonly id: string | undefined;
+  readonly aud: string | undefined;
+  readonly type: string | undefined;
+  readonly name: string | undefined;
+  readonly domain: string | undefined;
+  readonly createdAt: string | undefined;
+  readonly updatedAt: string | undefined;
+  readonly policyIds: ReadonlyArray<string>;
+  readonly saasApp: ObservedSaas | undefined;
+}
+
+/** What a create or an update sends. Built by `writeBody` in saas-oidc-form.ts. */
+export interface AppWrite {
+  readonly name: string;
+  readonly sessionDuration: string;
+  readonly allowedIdps: ReadonlyArray<string> | undefined;
+  readonly autoRedirectToIdentity: boolean | undefined;
+  readonly appLauncherVisible: boolean;
+  readonly policies: ReadonlyArray<string>;
+  readonly saasApp: {
+    readonly authType: 'oidc';
+    readonly redirectUris: ReadonlyArray<string>;
+    readonly scopes: ReadonlyArray<string>;
+    readonly grantTypes: ReadonlyArray<string>;
+    readonly accessTokenLifetime: string;
+    readonly refreshTokenOptions?: { readonly lifetime: string };
+    readonly allowPkceWithoutClientSecret: boolean;
+    readonly appLauncherUrl: string | undefined;
+  };
+}
+
+const str = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
+const bool = (value: unknown): boolean | undefined =>
+  typeof value === 'boolean' ? value : undefined;
+const strings = (value: unknown): ReadonlyArray<string> | undefined =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
+export const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+/**
+ * The policy ids in the order Access applies them. Each policy on the wire carries a `precedence`
+ * ("The order of execution for this policy", zero_trust.ts:13630-13631), and the declared list is
+ * "in ascending order of precedence" (zero_trust.ts:9774). Sorted by it only when EVERY entry
+ * reports one (ties keep array order); otherwise the array order stands, since a partial ranking
+ * says nothing about where the unranked entries sit.
+ */
+const policyIds = (policies: ReadonlyArray<unknown>): ReadonlyArray<string> => {
+  const entries = policies.flatMap((policy, index) => {
+    const id = str(record(policy)?.['id']);
+    const precedence = record(policy)?.['precedence'];
+    return id === undefined
+      ? []
+      : [{ id, index, precedence: typeof precedence === 'number' ? precedence : undefined }];
+  });
+  if (!entries.every((entry) => entry.precedence !== undefined)) return entries.map((e) => e.id);
+  return [...entries]
+    .sort((a, b) => (a.precedence ?? 0) - (b.precedence ?? 0) || a.index - b.index)
+    .map((entry) => entry.id);
+};
+
+/**
+ * Named fields only, from Cloudflare's snake_case JSON. ⛔ `client_secret` is not among them, and
+ * `public_key`, `custom_claims` and `hybrid_and_implicit_options` are not used by this resource.
+ */
+export const parseApp = (raw: Record<string, unknown>): ObservedApp => {
+  const saas = record(raw['saas_app']);
+  const refresh = record(saas?.['refresh_token_options']);
+  const policies = Array.isArray(raw['policies']) ? raw['policies'] : [];
+  return {
+    id: str(raw['id']),
+    aud: str(raw['aud']),
+    type: str(raw['type']),
+    name: str(raw['name']),
+    domain: str(raw['domain']),
+    createdAt: str(raw['created_at']),
+    updatedAt: str(raw['updated_at']),
+    policyIds: policyIds(policies),
+    saasApp:
+      saas === undefined
+        ? undefined
+        : {
+            authType: str(saas['auth_type']),
+            clientId: str(saas['client_id']),
+            redirectUris: strings(saas['redirect_uris']),
+            scopes: strings(saas['scopes']),
+            grantTypes: strings(saas['grant_types']),
+            accessTokenLifetime: str(saas['access_token_lifetime']),
+            refreshTokenLifetime: str(refresh?.['lifetime']),
+            allowPkceWithoutClientSecret: bool(saas['allow_pkce_without_client_secret']),
+          },
+  };
+};

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

@@ -0,0 +1,201 @@
+/**
+ * SaasOidcApplicationProvider against a fake Access API (fake-access.ts), its handlers called the
+ * way the engine calls them. Read, delete and adoption: saas-oidc-read.test.ts.
+ *
+ * ⛔ THE ASSERTIONS THAT MATTER MOST: a public PKCE client is created with
+ *   `allow_pkce_without_client_secret` and the `authorization_code_with_pkce` grant, and the client
+ *   secret — which the fake's create response DOES hand out, as the API does on POST — appears in
+ *   no attribute, no log line and no request body.
+ */
+import { afterEach, describe, expect, spyOn, test } from 'bun:test';
+import type { StackServices } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import { FAKE_CLIENT_SECRET, TEAM, fakeAccess } from './fake-access.ts';
+import { FAKE_ACCOUNT } from './fake-mesh.ts';
+import { providers } from './providers.ts';
+import { LIVE_OIDC, publicClient, reconcile, run, writes } from './saas-oidc-harness.ts';
+import { SaasOidcApplication } from './saas-oidc.ts';
+
+// ⛔ Compile-time: a stack's `providers` must be `Layer<…, never, StackServices>`. A provider with
+//   an open error channel leaks it here, and `bun run types` catches that.
+type Built = Layer.Success<ReturnType<typeof providers>>;
+const _stackShaped: Layer.Layer<Built, never, StackServices> = providers();
+void _stackShaped;
+
+const postBody = (fake: ReturnType<typeof fakeAccess>) =>
+  fake.seen.find((s) => s.method === 'POST')?.body as Record<string, unknown>;
+
+describe('SaasOidcApplication identity', () => {
+  test('the type id is the one the openbao state rows are keyed by', () => {
+    expect(SaasOidcApplication.Type).toBe('HomeFlare.Access.SaasOidcApplication');
+  });
+});
+
+describe('create', () => {
+  const debug = process.env['DISTILLED_DEBUG_HTTP'];
+  afterEach(() => {
+    if (debug === undefined) delete process.env['DISTILLED_DEBUG_HTTP'];
+    else process.env['DISTILLED_DEBUG_HTTP'] = debug;
+  });
+
+  test('a public client is sent as PKCE with no secret, and read back for its client id', async () => {
+    const fake = fakeAccess();
+    const spies = [spyOn(console, 'log'), spyOn(console, 'error'), spyOn(console, 'warn')];
+    const out = await run(fake, (p) => reconcile(p, publicClient()));
+    const logged = JSON.stringify(spies.map((spy) => spy.mock.calls));
+    for (const spy of spies) spy.mockRestore();
+    expect(postBody(fake)).toMatchObject({
+      type: 'saas',
+      name: 'Headlamp',
+      policies: ['policy-admin'],
+      saas_app: {
+        auth_type: 'oidc',
+        grant_types: ['authorization_code_with_pkce'],
+        allow_pkce_without_client_secret: true,
+        access_token_lifetime: '15m',
+      },
+    });
+    expect(writes(fake)).toEqual(['POST']);
+    expect(out).toMatchObject({ accountId: FAKE_ACCOUNT, teamDomain: TEAM, name: 'Headlamp' });
+    expect(out.issuer).toBe(`https://${TEAM}/cdn-cgi/access/sso/oidc/${out.clientId}`);
+    expect(out.jwksEndpoint).toBe(`${out.issuer}/jwks`);
+    // ⛔ The secret was in the create response. It is nowhere we control.
+    expect(JSON.stringify(out)).not.toContain(FAKE_CLIENT_SECRET);
+    expect(JSON.stringify(fake.seen)).not.toContain(FAKE_CLIENT_SECRET);
+    expect(logged).not.toContain(FAKE_CLIENT_SECRET);
+    expect(Object.keys(out)).not.toContain('clientSecret');
+  });
+
+  test('refuses while DISTILLED_DEBUG_HTTP is set, before any write', async () => {
+    process.env['DISTILLED_DEBUG_HTTP'] = '1';
+    const fake = fakeAccess();
+    // The SDK prints the name lookup's (secret-free) response while the variable is set.
+    const quiet = spyOn(console, 'error').mockImplementation(() => {});
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, publicClient())));
+    quiet.mockRestore();
+    expect(String(failure)).toContain('DISTILLED_DEBUG_HTTP');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('an invalid declaration fails before any request', async () => {
+    const fake = fakeAccess();
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, publicClient({ teamDomain: 'https://x.test' }))),
+    );
+    expect(String(failure)).toContain('teamDomain');
+    expect(fake.seen).toEqual([]);
+  });
+});
+
+describe('reconcile against a live app', () => {
+  test('makes zero writes when nothing drifted', async () => {
+    const fake = fakeAccess();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, publicClient());
+        return [created, yield* reconcile(p, publicClient(), created)] as const;
+      }),
+    );
+    expect(second).toEqual(first);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('a changed redirect URI is one PUT, and the client id survives', async () => {
+    const fake = fakeAccess();
+    const base = publicClient();
+    const changed = {
+      ...base,
+      saasApp: { ...base.saasApp, redirectUris: ['https://headlamp.example.test/new'] },
+    };
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, base);
+        return [created, yield* reconcile(p, changed, created)] as const;
+      }),
+    );
+    expect(writes(fake)).toEqual(['POST', 'PUT']);
+    expect(second.redirectUris).toEqual(['https://headlamp.example.test/new']);
+    expect(second.clientId).toBe(first.clientId);
+    expect(second.applicationId).toBe(first.applicationId);
+    expect(JSON.stringify(fake.seen)).not.toContain(FAKE_CLIENT_SECRET);
+  });
+
+  test('a reordered policy list is one PUT that carries the new order', async () => {
+    const fake = fakeAccess();
+    const base = publicClient({ policies: ['policy-a', 'policy-b'] });
+    const swapped = { ...base, policies: ['policy-b', 'policy-a'] };
+    const second = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, base);
+        return yield* reconcile(p, swapped, created);
+      }),
+    );
+    expect(second.applicationId).toBeDefined();
+    expect(writes(fake)).toEqual(['POST', 'PUT']);
+    expect(fake.seen.filter((s) => s.method === 'PUT')[0]?.body).toMatchObject({
+      policies: ['policy-b', 'policy-a'],
+    });
+    // The fake holds the new order, so the next read sees it in sync.
+    expect(fake.apps.get(second.applicationId)?.policies).toEqual(['policy-b', 'policy-a']);
+  });
+
+  test("a declared team that is not the app's team is refused before any write", async () => {
+    const fake = fakeAccess({ team: 'real.cloudflareaccess.com' });
+    const live = fake.seed({ name: 'Headlamp' });
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        reconcile(
+          p,
+          publicClient({ applicationId: live.id, teamDomain: 'other.cloudflareaccess.com' }),
+        ),
+      ),
+    );
+    expect(String(failure)).toContain('real.cloudflareaccess.com');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('an owned row whose app was deleted out of band never adopts a same-named app', async () => {
+    const fake = fakeAccess();
+    const made = await run(fake, (p) => reconcile(p, publicClient()));
+    fake.apps.delete(made.applicationId);
+    const impostor = fake.seed({
+      name: 'Headlamp',
+      policies: ['policy-admin'],
+      saas_app: LIVE_OIDC,
+    });
+    const before = fake.seen.length;
+    const out = await run(fake, (p) => reconcile(p, publicClient(), made));
+    // A fresh app is created; the same-named one is neither adopted nor written.
+    expect(out.applicationId).not.toBe(impostor.id);
+    expect(out.applicationId).not.toBe(made.applicationId);
+    expect(
+      fake.seen
+        .slice(before)
+        .filter((r) => r.method !== 'GET')
+        .map((r) => r.method),
+    ).toEqual(['POST']);
+    expect(fake.apps.get(impostor.id)?.saas_app?.['client_id']).toBe(
+      impostor.saas_app?.['client_id'],
+    );
+  });
+
+  test('an id that is not a saas app is refused, never rewritten', async () => {
+    const fake = fakeAccess();
+    const selfHosted = fake.seed({ name: 'Headlamp', type: 'self_hosted' });
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, publicClient({ applicationId: selfHosted.id }))),
+    );
+    expect(String(failure)).toContain('not "saas"');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('two saas apps with the declared name are refused, not guessed between', async () => {
+    const fake = fakeAccess();
+    fake.seed({ name: 'Headlamp' });
+    fake.seed({ name: 'Headlamp' });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, publicClient())));
+    expect(String(failure)).toContain('matches 2 live apps');
+    expect(writes(fake)).toEqual([]);
+  });
+});