@homeflare/alchemy 0.48.0 → 0.49.0

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

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