@homeflare/alchemy 0.48.1 → 0.49.0

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

package/src/cloudflare/saas-oidc.ts

@@ -0,0 +1,107 @@
+/**
+ * `HomeFlare.Access.SaasOidcApplication` — a Cloudflare Access SaaS application that makes Access an
+ * OIDC identity provider for one relying party (OpenBao's JWT/OIDC auth, Headlamp, a Kubernetes
+ * API server). Usage and the secret rules: docs/saas-oidc.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Access.Application`. Alchemy beta.81's Application has
+ *   no `saas_app` field (its source mentions `saas` only as a type and in two comments), and
+ *   `@distilled.cloud/cloudflare` rc.13 decodes a saas app's GET and create response WITHOUT it, so
+ *   the client id cannot be read back through either. See saas-oidc-api.ts.
+ *
+ * ⛔ THE TYPE ID IS A STATE KEY, AND THIS ONE WAS MOVED, NOT RENAMED. It is the string the
+ *   homeflare-openbao stack's live `OpenBaoOidcSaas` row was written under. A different string would
+ *   make the next plan see a new resource and an orphaned one: a second OIDC app, with a new
+ *   client id and `aud`, and a delete of the live one unless it were retained. `tests` pin it.
+ *
+ * ★ `retain` BY DEFAULT, like every kit resource whose deletion breaks its consumers: deleting the
+ *   app deletes the client id every relying party is configured with. The openbao declaration
+ *   already pipes `RemovalPolicy.retain()`; `delete` stays fully implemented for a declaration
+ *   that opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/http/HttpClient';
+import type { Providers } from './providers.ts';
+import { deleteSaasOidc, readSaasOidc, reconcileSaasOidc } from './saas-oidc-lifecycle.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-form.ts';
+
+export interface SaasOidcApplication extends Resource<
+  'HomeFlare.Access.SaasOidcApplication',
+  SaasOidcApplicationProps,
+  SaasOidcApplicationAttributes,
+  never,
+  Providers
+> {}
+
+export const SaasOidcApplication: ResourceClass<SaasOidcApplication> =
+  Resource<SaasOidcApplication>('HomeFlare.Access.SaasOidcApplication', {
+    defaultRemovalPolicy: 'retain',
+  });
+
+const accountId = Effect.gen(function* () {
+  const resolved = yield* yield* Cloudflare.CloudflareEnvironment;
+  return resolved.accountId;
+});
+
+/**
+ * ★ `Provider.effect`, CAPTURING THE THREE SERVICES AT BUILD, as MeshNodeProvider does
+ *   (mesh-node.ts): correct whether or not the stack also merges `Cloudflare.providers()`.
+ */
+export const SaasOidcApplicationProvider = () =>
+  Provider.effect(
+    SaasOidcApplication,
+    Effect.gen(function* () {
+      const services = Context.make(
+        Cloudflare.CloudflareEnvironment,
+        yield* Cloudflare.CloudflareEnvironment,
+      ).pipe(
+        Context.add(Credentials, yield* Credentials),
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      // ★ Only the three captured services are provided; `createPhysicalName` still takes
+      //   InstanceId, Stack and Stage from the engine at call time, as in every Alchemy provider.
+      const run = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        Effect.provideContext(effect, services);
+
+      return SaasOidcApplication.Provider.of({
+        /**
+         * ★ THE ISSUER AND EVERY ENDPOINT ARE STABLE. They depend only on the team domain and the
+         *   client id, and `checkTeam` refuses any team other than the app's own host, so no update
+         *   of this app can move them. Alchemy's plan (Plan.ts `withStables`, beta.81) keeps ONLY
+         *   the listed attributes resolved for consumers of an updated resource; without them, a
+         *   redirect-URI change would leave `app.issuer` unresolved and re-plan every consumer
+         *   (the Talos KubeAuthenticationConfig, so a kube-apiserver restart on each node).
+         * ⚠️ `teamDomain` is NOT listed: state written by the openbao copy has no such attribute,
+         *   so a consumer would read `undefined` on the first plan after the move.
+         */
+        stables: [
+          'applicationId',
+          'aud',
+          'clientId',
+          'accountId',
+          'issuer',
+          'authorizationEndpoint',
+          'tokenEndpoint',
+          'jwksEndpoint',
+          'userinfoEndpoint',
+          'configurationEndpoint',
+        ],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Access.Application` already lists
+         *   every Access application in the account for `alchemy unsafe nuke` (its `list`, saas
+         *   apps included); a second listing here would make nuke delete each app twice.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        read: ({ id, olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readSaasOidc(account, id, olds, output))),
+        reconcile: ({ id, news, output }) =>
+          run(Effect.flatMap(accountId, (account) => reconcileSaasOidc(account, id, news, output))),
+        delete: ({ output }) => run(deleteSaasOidc(output)),
+      });
+    }),
+  );