@homeflare/alchemy 0.48.0 → 0.49.0

package/src/cloudflare/index.ts

@@ -1,10 +1,15 @@
 /**
  * Cloudflare providers for Alchemy — the gaps the vendor SDK leaves.
  *
- * ★ Built on vendor SDKs, not hand-rolled HTTP. Both `R2BucketLock` and `MeshNode` call
- *   `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare providers use — R2BucketLock
- *   over `/r2` (`getBucketLock`/`putBucketLock`), MeshNode over `/zero-trust`, because
- *   `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). Neither invents a path string.
+ * ★ Built on vendor SDKs, not hand-rolled HTTP. `R2BucketLock`, `MeshNode`, `CloudflaredTunnel` and
+ *   `SaasOidcApplication` all call `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare
+ *   providers use — R2BucketLock over `/r2` (`getBucketLock`/`putBucketLock`), MeshNode over
+ *   `/zero-trust`, because `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). None
+ *   invents a path string.
+ * ⚠️ ONE EXCEPTION, A READ: `SaasOidcApplication` writes and looks up names through the SDK, but its
+ *   responses drop `saas_app`, so `getApp` reads that one object from the wire JSON — the same
+ *   `GET /accounts/{account_id}/access/apps/{app_id}` the SDK's get verb sends, over the SDK's own
+ *   `HttpClient`, credentials and base URL (saas-oidc-api.ts).
  */
 export type { R2LockRule } from './lock-rules.ts';
 export { R2BucketLock, type R2BucketLockProps } from './r2-bucket-lock.ts';
@@ -12,6 +17,24 @@ export { MeshNode, MeshNodeProvider, type MeshNodeServices } from './mesh-node.t
 export type { MeshNodeAttributes, MeshNodeProps } from './mesh-node-form.ts';
 export { MeshNodeError, type MeshNodeStatus } from './mesh-node-api.ts';
 export { fetchMeshNodeToken, type MeshNodeRef } from './mesh-node-token.ts';
+export {
+  CloudflaredTunnel,
+  CloudflaredTunnelProvider,
+  type CloudflaredTunnelServices,
+} from './cloudflared-tunnel.ts';
+export type {
+  CloudflaredTunnelAttributes,
+  CloudflaredTunnelProps,
+} from './cloudflared-tunnel-form.ts';
+export { CloudflaredTunnelError } from './cloudflared-tunnel-api.ts';
+export { SaasOidcApplication, SaasOidcApplicationProvider } from './saas-oidc.ts';
+export type {
+  OidcGrantType,
+  OidcScope,
+  SaasOidcApplicationAttributes,
+  SaasOidcApplicationProps,
+} from './saas-oidc-form.ts';
+export { SaasOidcError } from './saas-oidc-error.ts';
 export { providers } from './providers.ts';
 export {
   astroWebsite,

package/src/cloudflare/providers.ts

@@ -13,26 +13,39 @@
  *   `Cloudflare.providers()` does (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
  *   `CLOUDFLARE_ACCOUNT_ID` in CI) — a lock and the Gateway rules that reference the same bucket
  *   land in the same account.
- * ⚠️ THE LAYER IS BUILT TWICE ON PURPOSE, once per provider, even when the stack also merges
+ * ⚠️ THE LAYER IS BUILT ONCE PER PROVIDER ON PURPOSE, even when the stack also merges
  *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: each feeds its own provider
  *   only and adds nothing to the stack's context.
  */
 import * as Cloudflare from 'alchemy/Cloudflare';
 import * as Provider from 'alchemy/Provider';
 import * as Layer from 'effect/Layer';
+import { CloudflaredTunnel, CloudflaredTunnelProvider } from './cloudflared-tunnel.ts';
 import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
 import { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';
+import { SaasOidcApplication, SaasOidcApplicationProvider } from './saas-oidc.ts';
 
 export class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}
 
-// ⛔ `orDie` ON BOTH, as `Cloudflare.providers()` ends with: a stack's providers layer must not
+// ⛔ `orDie` ON EACH of the four, as `Cloudflare.providers()` ends with: a stack's providers layer must not
 //   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
 export const providers = () =>
-  Layer.effect(Providers, Provider.collection([R2BucketLock, MeshNode])).pipe(
+  Layer.effect(
+    Providers,
+    Provider.collection([R2BucketLock, MeshNode, CloudflaredTunnel, SaasOidcApplication]),
+  ).pipe(
     Layer.provide(
       Layer.mergeAll(
         R2BucketLockProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
         MeshNodeProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
+        CloudflaredTunnelProvider().pipe(
+          Layer.provide(Cloudflare.CloudflareApiLive()),
+          Layer.orDie,
+        ),
+        SaasOidcApplicationProvider().pipe(
+          Layer.provide(Cloudflare.CloudflareApiLive()),
+          Layer.orDie,
+        ),
       ),
     ),
   );

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

@@ -0,0 +1,224 @@
+/**
+ * The Access application calls a SaaS OIDC application needs, and nothing else.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare` FOR EVERY WRITE AND FOR THE NAME LOOKUP; ONE RAW READ. Alchemy
+ *   `2.0.0-beta.81`'s `Cloudflare.Access.Application` has no `saas_app` at all (Application.ts:
+ *   `saas` appears only as an app type and in two doc comments), so this resource exists. The SDK
+ *   does carry `saasApp` on the REQUEST (`AccessApplicationsCreateRequestSaasAppOIDCSaaSApp`,
+ *   zero_trust.ts, `@distilled.cloud/cloudflare@1.0.0-rc.13`), so create and update go through it.
+ * ⚠️ BUT ITS RESPONSES DROP IT. Measured 2026-10-09 against rc.13 with a fake API that answered a
+ *   full `saas_app` object: `getAccessApplicationForAccount` and `createAccessApplicationForAccount`
+ *   both decoded to `{ domain, type, id, aud, name, policies }`, with no `saasApp`. The response
+ *   union is discriminated by field names (`T.UnionCases`) and a saas app falls in a variant with
+ *   no `saas_app`. So the OIDC client id, redirect URIs, scopes and grant types can only be read
+ *   from the wire JSON, and `getApp` below does that through the `HttpClient` the SDK itself runs
+ *   on, with the SDK's own credentials and base URL. It invents no path: it is the same
+ *   `GET /accounts/{account_id}/access/apps/{app_id}` the SDK's get verb sends.
+ *
+ * ⛔ THE CLIENT SECRET NEVER REACHES THIS PACKAGE'S MEMORY. The field doc on the SDK schema says
+ *   "The application client secret, only returned on POST request". The create response is
+ *   decoded by the SDK, whose `saasApp`-less variant drops it, and `getApp` copies named fields
+ *   only and never reads `client_secret`. TWO paths remain where the SDK itself holds or prints the
+ *   raw body (`@distilled.cloud/cloudflare@1.0.0-rc.13`, protocol.ts):
+ *   1. `DISTILLED_DEBUG_HTTP` makes it `console.error` the first 400 characters of every response
+ *      (line 334), so `refuseDebugHttp` stops a write while it is set. THIS ONE STAYS AN
+ *      OPERATOR-ONLY SWITCH: the package can refuse to run, it cannot stop the SDK printing.
+ *   2. A response that fails schema validation becomes `CloudflareParseError({ body, cause })`
+ *      (lines 452-457), whose `body` is the whole parsed response, create response included.
+ *      ⛔ SANITISED HERE: every SDK call of this resource (create, update, list, delete, and the
+ *      organization read in saas-oidc-team.ts) catches that tag at the call and fails with a
+ *      `SaasOidcError` that names the operation and nothing from the response. Why, when it can
+ *      happen at all, and what rc.13 will and will not raise: saas-oidc-error.ts (`withheld`).
+ *      The raw `get` below is not an SDK call and never builds that error.
+ *   A PUBLIC PKCE client (`allowPkceWithoutClientSecret: true`) has no secret at all, so neither
+ *   path exposes one for the Headlamp app.
+ */
+import { Credentials, formatHeaders } from '@distilled.cloud/cloudflare/Credentials';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import * as Schedule from 'effect/Schedule';
+import * as Stream from 'effect/Stream';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { SaasOidcError, withheld } from './saas-oidc-error.ts';
+import { type AppWrite, parseApp, record } from './saas-oidc-wire.ts';
+
+/**
+ * The two SDK writes, as properties of an object so saas-oidc-parse-error.test.ts can stand in for
+ * one: rc.13 cannot be made to fail a create or update with `CloudflareParseError` (the ⚠️ in
+ * saas-oidc-error.ts), and the catch on those two calls still has to be proven wired. Nothing
+ * else assigns here.
+ */
+export const sdkWrites = {
+  create: zeroTrust.createAccessApplicationForAccount,
+  update: zeroTrust.updateAccessApplicationForAccount,
+};
+
+const TRANSIENT_STATUS = (status: number): boolean =>
+  status === 403 || status === 429 || status >= 500;
+
+/**
+ * ★ UPSTREAM'S OWN RETRY, EXACTLY (alchemy beta.81 `Cloudflare/Access/Application.ts`, the comment
+ *   and `retryTransientAccessError` above `ApplicationProvider`): `AccessReferenceNotFound` is a
+ *   freshly created policy still propagating, and `Forbidden` is how Cloudflare throttles a valid
+ *   token. Capped exponential, about 45 seconds, then fail. The raw read joins it for the same
+ *   statuses so it is throttled the way the SDK calls are.
+ */
+export const retryTransient = <A, E extends { readonly _tag: string }, R>(
+  effect: Effect.Effect<A, E, R>,
+) =>
+  effect.pipe(
+    Effect.retry({
+      while: (e) =>
+        e._tag === 'AccessReferenceNotFound' ||
+        e._tag === 'Forbidden' ||
+        (e._tag === 'SaasOidcError' &&
+          TRANSIENT_STATUS((e as unknown as SaasOidcError).status ?? 0)),
+      schedule: Schedule.max([
+        Schedule.min([Schedule.exponential('1 second', 1.5), Schedule.spaced('5 seconds')]),
+        Schedule.recurs(12),
+      ]),
+    }),
+  );
+
+/**
+ * ⛔ REFUSED BEFORE ANY WRITE while `DISTILLED_DEBUG_HTTP` is set: the SDK would print the create
+ *   response, which carries the client secret, to stderr (protocol.ts). Read from `process.env`
+ *   because that is what distilled reads, as mesh-node-token.ts does.
+ */
+export const refuseDebugHttp = Effect.suspend(() =>
+  (globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') === ''
+    ? Effect.void
+    : Effect.fail(
+        new SaasOidcError({
+          message:
+            'Refusing to write a SaaS OIDC application while DISTILLED_DEBUG_HTTP is set: the SDK would print the response, which carries the client secret, to stderr. Unset it and run again.',
+        }),
+      ),
+);
+
+/**
+ * The app with this id, from the wire JSON, or `undefined` when it is gone (404).
+ * ⚠️ Error messages carry the reason and the status only: the request holds the bearer token.
+ */
+export const getApp = (accountId: string, appId: string) =>
+  Effect.gen(function* () {
+    const credentials = yield* yield* Credentials;
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.get(
+      `${credentials.apiBaseUrl}/accounts/${accountId}/access/apps/${appId}`,
+    ).pipe(HttpClientRequest.setHeaders(formatHeaders(credentials)), HttpClientRequest.acceptJson);
+    const transport = (cause: { readonly message: string }) =>
+      new SaasOidcError({ message: `Access application GET failed: ${cause.message}`, status: 0 });
+    const response = yield* client.execute(request).pipe(Effect.mapError(transport));
+    if (response.status === 404) return undefined;
+    if (response.status < 200 || response.status >= 300) {
+      return yield* Effect.fail(
+        new SaasOidcError({
+          message: `Access application GET returned ${response.status}`,
+          status: response.status,
+        }),
+      );
+    }
+    const text = yield* response.text.pipe(Effect.mapError(transport));
+    const body = yield* Effect.try({
+      try: () => record(JSON.parse(text) as unknown),
+      catch: () =>
+        new SaasOidcError({ message: 'Access application GET was not JSON', status: 200 }),
+    });
+    const result = record(body?.['result']);
+    return result === undefined ? undefined : parseApp(result);
+  }).pipe(retryTransient);
+
+/**
+ * The live saas app with exactly this name, or `undefined`. The list payload carries no `saas_app`
+ * (see the ⚠️ above), so the caller re-reads the match by id with `getApp`.
+ * ⛔ Two matches are refused rather than resolved: Access does not enforce unique app names, so two
+ *   means this package cannot tell which one is meant.
+ */
+export const findSaasByName = (accountId: string, name: string) =>
+  zeroTrust.listAccessApplicationsForAccount.items({ accountId }).pipe(
+    Stream.filter((app) => app.type === 'saas' && app.name === name),
+    Stream.runCollect,
+    Effect.catchTag('CloudflareParseError', withheld('application list')),
+    retryTransient,
+    Effect.flatMap((chunk) => {
+      const ids = Array.from(chunk).flatMap((app) => (app.id == null ? [] : [app.id]));
+      if (ids.length <= 1) return Effect.succeed(ids[0]);
+      return Effect.fail(
+        new SaasOidcError({
+          message: `SaaS application name "${name}" matches ${ids.length} live apps (${ids.join(', ')}). Refusing to guess which one is meant; set \`applicationId\`.`,
+        }),
+      );
+    }),
+  );
+
+const sdkBody = (write: AppWrite) => ({
+  type: 'saas' as const,
+  name: write.name,
+  sessionDuration: write.sessionDuration,
+  ...(write.allowedIdps === undefined ? {} : { allowedIdps: [...write.allowedIdps] }),
+  ...(write.autoRedirectToIdentity === undefined
+    ? {}
+    : { autoRedirectToIdentity: write.autoRedirectToIdentity }),
+  appLauncherVisible: write.appLauncherVisible,
+  policies: [...write.policies],
+  saasApp: {
+    authType: write.saasApp.authType,
+    redirectUris: [...write.saasApp.redirectUris],
+    scopes: [...write.saasApp.scopes],
+    grantTypes: [...write.saasApp.grantTypes],
+    accessTokenLifetime: write.saasApp.accessTokenLifetime,
+    allowPkceWithoutClientSecret: write.saasApp.allowPkceWithoutClientSecret,
+    ...(write.saasApp.refreshTokenOptions === undefined
+      ? {}
+      : { refreshTokenOptions: write.saasApp.refreshTokenOptions }),
+    ...(write.saasApp.appLauncherUrl === undefined
+      ? {}
+      : { appLauncherUrl: write.saasApp.appLauncherUrl }),
+  } satisfies zeroTrust.AccessApplicationsCreateRequestSaasAppOIDCSaaSApp,
+});
+
+/** Create the app and return its id. The response's other fields are not trusted: re-read it. */
+export const createApp = (accountId: string, write: AppWrite) =>
+  refuseDebugHttp.pipe(
+    Effect.andThen(
+      sdkWrites
+        .create({ accountId, ...sdkBody(write) })
+        .pipe(
+          Effect.catchTag('CloudflareParseError', withheld('application create')),
+          retryTransient,
+        ),
+    ),
+    Effect.flatMap((created) =>
+      created.id == null
+        ? Effect.fail(new SaasOidcError({ message: 'SaaS OIDC create did not return an id.' }))
+        : Effect.succeed(created.id),
+    ),
+  );
+
+export const updateApp = (accountId: string, appId: string, write: AppWrite) =>
+  refuseDebugHttp.pipe(
+    Effect.andThen(
+      sdkWrites
+        .update({ accountId, appId, ...sdkBody(write) })
+        .pipe(
+          Effect.catchTag('CloudflareParseError', withheld('application update')),
+          retryTransient,
+        ),
+    ),
+    Effect.asVoid,
+  );
+
+/**
+ * Idempotent: an app already gone is a successful delete. Any other failure propagates, except
+ * that a response the SDK cannot validate is withheld (see `withheld`).
+ */
+export const deleteApp = (accountId: string, appId: string) =>
+  zeroTrust.deleteAccessApplicationForAccount({ accountId, appId }).pipe(
+    Effect.asVoid,
+    Effect.catchTags({
+      AccessApplicationNotFound: () => Effect.void,
+      CloudflareParseError: withheld('application delete'),
+    }),
+  );

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

@@ -0,0 +1,35 @@
+/**
+ * A test-only downstream resource for saas-oidc-stable.test.ts: it takes the app's issuer as a prop
+ * and counts how often the engine reconciles it, so a test can tell "planned noop" from "planned
+ * update" for a consumer of `app.issuer`. ⛔ TEST-ONLY. No provider imports this file.
+ */
+import * as Provider from 'alchemy/Provider';
+import { Resource } from 'alchemy/Resource';
+import * as Effect from 'effect/Effect';
+
+export interface IssuerConsumer extends Resource<
+  'Test.IssuerConsumer',
+  { readonly issuer: string; readonly jwks: string },
+  { readonly issuer: string; readonly jwks: string }
+> {}
+export const IssuerConsumer = Resource<IssuerConsumer>('Test.IssuerConsumer');
+
+/** The provider, and the list of props it was reconciled with (one entry per reconcile). */
+export const consumerProvider = () => {
+  const reconciled: string[] = [];
+  const layer = Provider.effect(
+    IssuerConsumer,
+    Effect.succeed(
+      IssuerConsumer.Provider.of({
+        list: () => Effect.succeed([]),
+        reconcile: ({ news }) =>
+          Effect.sync(() => {
+            reconciled.push(news.issuer);
+            return { issuer: news.issuer, jwks: news.jwks };
+          }),
+        delete: () => Effect.void,
+      }),
+    ),
+  );
+  return { layer, reconciled };
+};

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

@@ -0,0 +1,52 @@
+/**
+ * The one error type of the SaaS OIDC resource, and the handler that keeps the SDK's raw
+ * `CloudflareParseError` (which can hold the client secret) from leaving this package.
+ *
+ * ⛔ THE LEAK. A response that fails schema validation becomes `CloudflareParseError({ body, cause })`
+ *   (`@distilled.cloud/cloudflare@1.0.0-rc.13` protocol.ts:452-457). `body` is the WHOLE parsed
+ *   response, a create response included, and for a confidential client that carries
+ *   `client_secret`; `cause` is a SchemaError that quotes the values that failed. A raw SDK error
+ *   that reached an engine log or a trace would print both.
+ * ★ THE FIX is at every SDK call of this resource (create, update, list, delete, and the
+ *   organization read in saas-oidc-team.ts): `Effect.catchTag('CloudflareParseError', withheld(…))`,
+ *   applied before the retry or any other combinator sees the error. It is the house's catchTag
+ *   doctrine (a typed tag, no status or message sniffing), and the replacement carries the
+ *   operation name and nothing from the response. The raw `get` in saas-oidc-api.ts is not an SDK
+ *   call and never builds this error.
+ * ⚠️ WHEN IT CAN HAPPEN AT ALL. The error exists only under STRICT response validation (core
+ *   response-validation.ts:29 "without one, every call is lenient", :104-116); neither Alchemy nor
+ *   this kit turns strict on, so a consumer's own `ResponseValidation.strict` is what makes it
+ *   reachable. MEASURED 2026-10-09 against rc.13 under strict validation: a create or update
+ *   response decodes against `S.Unknown` (`AccessApplicationsCreateResult`, zero_trust.ts:35025;
+ *   `AccessApplicationsUpdateResult`, :210218), which accepts anything, so the real SDK cannot
+ *   raise it for those two today (the tests reach them through `sdkWrites` in saas-oidc-api.ts).
+ *   List (a non-array result, :147403-147410), delete (`id` typed, :61601-61607) and the organization
+ *   read (:169193-169253) are typed and can. The catch is on all five so a later SDK that types the
+ *   union cannot start leaking.
+ * ⛔ `DISTILLED_DEBUG_HTTP` is the other raw-body path and stays an operator-only switch: the
+ *   package refuses a write while it is set (`refuseDebugHttp`), it cannot stop the SDK printing.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a secret. */
+export class SaasOidcError extends Data.TaggedError('SaasOidcError')<{
+  readonly message: string;
+  /** The HTTP status when the failure is a response (0 for a transport failure). */
+  readonly status?: number;
+}> {}
+
+/**
+ * ⛔ THE ONLY THING THIS PACKAGE SAYS ABOUT A RESPONSE THE SDK COULD NOT VALIDATE. The handler for
+ *   `Effect.catchTag('CloudflareParseError', …)`: it never touches the error it replaces, because
+ *   that error's `body` is the whole response (a create's carries `client_secret`) and its `cause`
+ *   quotes the values that failed. The message names the operation only. No status is claimed: the
+ *   SDK builds this error after its failure branch (protocol.ts:359, :452), so the response was a
+ *   success as far as HTTP and the envelope go, and nothing more is known.
+ */
+export const withheld = (operation: string) => (): Effect.Effect<never, SaasOidcError> =>
+  Effect.fail(
+    new SaasOidcError({
+      message: `Access ${operation} succeeded at the HTTP level but the SDK could not validate the response. The response is withheld on purpose (a create response carries the client secret). Check the application in the Zero Trust dashboard, then run again.`,
+    }),
+  );

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