@homeflare/alchemy 0.48.1 → 0.49.0

package/docs/saas-oidc.md

@@ -0,0 +1,185 @@
+# SaasOidcApplication — Access as an OIDC provider, with no client secret in state
+
+`SaasOidcApplication` (`HomeFlare.Access.SaasOidcApplication`) declares a Cloudflare Access **SaaS
+application** of auth type `oidc`: Access acts as the OpenID Connect provider for one relying
+party (OpenBao's OIDC auth, Headlamp, a Kubernetes API server). It exposes the issuer, the client
+id and the JWKS endpoint as attributes, so the relying party's configuration can be declared from
+them. Read 2026-10-09 against `alchemy@2.0.0-beta.81` and
+`@distilled.cloud/cloudflare@1.0.0-rc.13`.
+
+## Why not `Cloudflare.Access.Application`
+
+- **It cannot send or read `saas_app`.** Its source mentions `saas` only as an app type and in two
+  comments (`Cloudflare/Access/Application.ts`, beta.81). An OIDC app is the `saas_app` object.
+- **The SDK drops it on the way back.** The request type carries `saasApp`
+  (`AccessApplicationsCreateRequestSaasAppOIDCSaaSApp`), so create and update use it. But a fake
+  API that answered a full `saas_app` decoded, for both `getAccessApplicationForAccount` and
+  `createAccessApplicationForAccount`, to `{ domain, type, id, aud, name, policies }` (measured
+  2026-10-09). So the client id, redirect URIs, scopes and grants are read from the wire JSON by
+  one raw `GET /accounts/{account_id}/access/apps/{app_id}`, over the same `HttpClient` and
+  credentials the SDK uses. That one read is the only hand-written call; it adds no path.
+  ❓ **Open question for Tim (lane contract 1, SDKs over hand-rolling):** the raw GET exists only
+  because rc.13 decodes the GET without `saas_app`. Approve it until upstream decodes the field, or
+  hold this resource.
+- Track upstream: when Alchemy's `Access.Application` gains `saas_app` (and distilled decodes it),
+  this resource should be retired in its favour. Nothing is filed upstream from here.
+
+## At a glance
+
+```ts
+import { SaasOidcApplication } from '@homeflare/alchemy/cloudflare';
+
+const app = yield * SaasOidcApplication('Headlamp', { teamDomain, policies, saasApp });
+// app.issuer, app.clientId, app.jwksEndpoint
+```
+
+- ⛔ **The client secret is never read, stored or logged.** A public client declares
+  `allowPkceWithoutClientSecret: true` with the PKCE grant, and then no secret exists.
+- ⛔ **The type id is a state key** (moved from homeflare-openbao verbatim) and it **retains on
+  destroy**: deleting the app deletes the client id every relying party uses.
+
+## Declaring an app
+
+```ts
+import { SaasOidcApplication, providers } from '@homeflare/alchemy/cloudflare';
+
+// providers: Layer.mergeAll(Cloudflare.providers(), providers()),
+const headlamp =
+  yield *
+  SaasOidcApplication('Headlamp', {
+    name: 'Headlamp',
+    teamDomain: 'example.cloudflareaccess.com',
+    policies: [adminPolicyId],
+    saasApp: {
+      authType: 'oidc',
+      redirectUris: ['https://headlamp.example.com/oidc-callback'],
+      scopes: ['openid', 'email', 'groups'],
+      grantTypes: ['authorization_code_with_pkce'],
+      accessTokenLifetime: '15m',
+      allowPkceWithoutClientSecret: true, // a public client: no secret exists
+    },
+  });
+// headlamp.issuer, headlamp.clientId, headlamp.jwksEndpoint
+```
+
+| prop                                           | notes                                                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `teamDomain`                                   | **Required.** Bare hostname of the Zero Trust team, no scheme or path.                       |
+| `applicationId`                                | Optional. Set it to adopt a known live app; otherwise the app is found by exact `name`.      |
+| `name`                                         | Optional. Defaults to a physical name from the logical id.                                   |
+| `policies`                                     | Reusable Access policy ids, in ascending precedence. The order is declared: a reorder syncs. |
+| `sessionDuration`, `allowedIdps`               | Optional. Written on create and on any sync. `sessionDuration` defaults to `24h`.            |
+| `autoRedirectToIdentity`, `appLauncherVisible` | Optional. `appLauncherVisible` defaults to `false`.                                          |
+| `saasApp.redirectUris`, `scopes`, `grantTypes` | The OIDC client's settings.                                                                  |
+| `saasApp.accessTokenLifetime`                  | `m` or `h` units, `1m` to `24h` (the SDK field doc).                                         |
+| `saasApp.refreshTokenLifetime`                 | Optional. Needed for the `refresh_tokens` grant.                                             |
+| `saasApp.allowPkceWithoutClientSecret`         | `true` = public client. Needs the `authorization_code_with_pkce` grant (refused otherwise).  |
+
+Attributes: everything above that Cloudflare reports, plus `applicationId`, `aud`, `clientId`,
+`accountId`, `teamDomain`, `domain`, and the OIDC URLs `issuer`
+(`https://<teamDomain>/cdn-cgi/access/sso/oidc/<clientId>`), `authorizationEndpoint`,
+`tokenEndpoint`, `jwksEndpoint`, `userinfoEndpoint` and `configurationEndpoint`.
+
+★ **The team domain is a prop, not a constant.** The openbao copy this came from hardcoded one
+account's. A declared `teamDomain` that disagrees with the host Cloudflare reports in the app's own
+`domain` is refused before any write to an existing app, so the issuer cannot point at a different
+team. When Cloudflare reports no `domain` at all, the team already recorded in the row stands in: a
+declaration that changes it is refused too (the issuer is a declared stable and cannot move).
+
+★ **A first create is checked against the account's organization, when it can be read.** No app
+exists to compare, so before the first write the resource reads the Zero Trust organization
+(`GET /accounts/{account_id}/access/organizations`, the SDK's `listOrganizationsForAccount`; its
+`auth_domain` is the team domain, the same read Alchemy's `Access.Organization` does) and refuses a
+`teamDomain` that differs, with **no write**. It is one attempt, so a token that may not read it does
+not wait on retries.
+
+⚠️ **Known limit: that read needs a token permission the app write does not.** Cloudflare's docs
+(read 2026-10-09, not measured against a live token) give `Access: Organizations Read` (or
+`Access: Organizations, Identity Providers, and Groups Read`) for it, and `Access: Apps and Policies
+Write` for creating the app. Where the token cannot read the organization (a 401 or 403, or no
+organization), the check gives no answer and the create goes on as before: a wrong `teamDomain` then
+writes one app, the post-write check fails the run, and a live app is left with no state row.
+**Cleanup:** the next run finds it by name as `Unowned`; fix the `teamDomain` and declare
+`adopt(true)`, or delete the stray app in the Zero Trust dashboard. **To close the limit**, add
+`Access: Organizations Read` to the token the deploy runs with. Any other failure of the read (a
+throttle, a 5xx) fails the run before a write; run again.
+
+## The client secret
+
+⛔ **It is never read, stored or logged by this package.** The SDK schema's own doc says the secret
+is "only returned on POST request". The create response is decoded by the SDK (which drops it, see
+above); the raw read copies named fields and has no field for it; the attributes have none.
+`saas-oidc-state.test.ts` serialises the whole in-memory state after a create whose fake response
+hands a secret out, and asserts it is absent.
+
+⚠️ **Two paths where the SDK itself holds or prints the raw body** (`@distilled.cloud/cloudflare`
+rc.13, `protocol.ts`), so "never logged" is a claim about this package, not about the SDK:
+
+1. `DISTILLED_DEBUG_HTTP` makes it `console.error` the first 400 characters of every response
+   (line 334). A write refuses to run while it is set. **This one stays an operator-only switch:**
+   the package can refuse to run, it cannot stop the SDK printing, so never set it for a deploy.
+2. A response that fails schema validation becomes `CloudflareParseError({ body, cause })`
+   (lines 452-457), and `body` is the whole parsed response, a create response with its secret
+   included. **Sanitized in this package:** every SDK call of the resource (create, update, list,
+   delete, and the organization read) catches that tag at the call and fails with a `SaasOidcError`
+   that names the operation and carries no body, no response field and no cause
+   (`saas-oidc-error.ts`). `saas-oidc-parse-error.test.ts` forces the error with a fake
+   `client_secret` planted and checks the message, the fields, `String(err)`, `JSON.stringify(err)`
+   and the printed cause. The raw `GET` is not an SDK call and never builds that error.
+   The error exists only under strict response validation (`ResponseValidation.strict`, which
+   neither Alchemy nor this kit turns on; the default is lenient). Measured 2026-10-09: rc.13
+   decodes a create or update response against `S.Unknown`, so it cannot raise the error for those
+   two today; the catch stays so a later SDK that types them cannot start leaking.
+
+Neither exposes anything for a public PKCE client, which has no secret.
+
+- **A public client has no secret to keep** (`allowPkceWithoutClientSecret: true` with the PKCE
+  grant). That is the design for Headlamp (Q6 of the Kubernetes platform decisions).
+- **A confidential client's secret is out of band.** This resource does not capture it. How to
+  obtain or rotate it for an existing app is UNVERIFIED here (no documented rotate verb was read);
+  homeflare-openbao keeps its live one in the macOS Keychain.
+- UNVERIFIED: whether Cloudflare still returns a `client_secret` on POST for a PKCE-without-secret
+  app. It does not matter here, since it is dropped either way.
+
+## Adopting the openbao app, and the state key
+
+⛔ **The type id `HomeFlare.Access.SaasOidcApplication` is kept verbatim.** Alchemy state rows are
+keyed by it, and homeflare-openbao's live `OpenBaoOidcSaas` row was written under it. A different
+id plans a second app (new client id, new `aud`) beside the orphaned live one. The state test
+seeds a row in the old shape (no `teamDomain`) and proves the next deploy updates it in place:
+no create, no delete, the same application and client ids.
+
+- State written before `teamDomain` existed still reads: the host from the app's own `domain`
+  stands in until the next reconcile stores the declared one.
+- homeflare-openbao's stack must merge this package's `providers()` (the kit's collection) where it
+  merged `Cloudflare.providers()` for this type, and add `teamDomain` to its declaration.
+- An **owned** row whose app was deleted out of band reads as gone, never as a same-named app; the
+  next reconcile then creates a new one (a new client id). The name fallback is for a cold read.
+- A live app is `Unowned` until the declaration says `adopt(true)`, like every kit resource.
+
+## What a change does
+
+- **The issuer and every endpoint are `stables`**: an update (a redirect URI, a policy) leaves
+  `app.issuer` and the others resolved for consumers at plan time, so a Talos
+  `KubeAuthenticationConfig` that reads them is not re-planned. `teamDomain` is deliberately not
+  stable (the openbao row has no such attribute). `saas-oidc-stable.test.ts` runs the engine.
+
+- **Created** when no app has the id or the exact name. Names are not unique in Access, so two
+  saas apps with the declared name are refused: set `applicationId`.
+- **Synced** (one PUT of the whole declaration) when the name, auth type, redirect URIs, scopes,
+  grant types, either token lifetime, the PKCE flag or the policies differ. Order is ignored for
+  redirect URIs, scopes and grant types. **It is not ignored for `policies`:** they are declared in
+  ascending precedence, so a reorder is drift (the live order is read from each policy's
+  `precedence`).
+- ⚠️ **Not drift-checked:** `sessionDuration`, `allowedIdps`, `autoRedirectToIdentity`,
+  `appLauncherVisible`, `appLauncherUrl`. They are written on create and on any sync, but a change
+  to only those does not trigger one. This is carried over from the openbao copy unchanged.
+- A matching live app is **zero writes**.
+- An `applicationId` that is not a `saas` app is refused, never rewritten.
+- Retries follow Alchemy's own `retryTransientAccessError` (same file as above): a freshly created
+  policy still propagating, and 403 as Cloudflare's throttle. About 45 seconds, then it fails.
+
+⛔ **Removal policy: `retain` by default**, because deleting the app deletes the client id every
+relying party is configured with. `delete` stays fully implemented (an app already gone is a
+success): opt in with `.pipe(RemovalPolicy.destroy())`. `list` is empty and `nuke` is skipped:
+Alchemy's own `Access.Application` already lists every Access app, saas ones included.

package/docs/upstream-conformance-families.md

@@ -72,7 +72,7 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
       in lifecycle operations; it is not a separate credentials-layer prohibition. The same
       shape in NetBox is therefore not an S20 follow-up. See [LiteLLM's Q6 resolution](./litellm.md#credentials).
 11. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
-    `R2BucketLock` and `MeshNode` declare `nuke`. The constructor already defaults `list`
+    `R2BucketLock`, `MeshNode` and `CloudflaredTunnel` declare `nuke`. The constructor already defaults `list`
     (S12). **Fix:** write the reason where it differs, and declare `nuke: { skip: true }`
     where nuke must never reach the object.
 12. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,

package/docs/upstream-conformance.md

@@ -66,6 +66,9 @@ then tidiness.
    type string `Cloudflare.MeshNode` sits inside upstream's own namespace (H14).
    **Options:** contribute `ha` upstream and raise the token-in-state concern, then switch;
    or keep the house resource as a recorded divergence. **Decision:** maintainer.
+   `cloudflare/CloudflaredTunnel` is the same divergence for `Cloudflare.Tunnel.Tunnel`
+   ([cloudflared-tunnel.md](./cloudflared-tunnel.md)): the token in state is the concern to raise
+   upstream, and its type string `Cloudflare.CloudflaredTunnel` also sits in upstream's namespace (H14).
 4. **Unguarded `Bun.*`, and the `node:*` modules upstream names, in shipped provider code**
    (S42). This is listed in [the Bun line](#the-bun-line). The exported `Bun.*` paths crash
    under Node, which is the runtime this package promises its consumers. The `node:*` paths

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/cloudflare/cloudflared-tunnel-api.ts

@@ -0,0 +1,150 @@
+/**
+ * The `cfd_tunnel` calls a Cloudflare Tunnel (the cloudflared kind) needs, and nothing else.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE, the same
+ *   one mesh-node-api.ts calls. The operations are `createTunnelCloudflared` (POST
+ *   `/accounts/{account_id}/cfd_tunnel`), `getTunnelCloudflared`, `patchTunnelCloudflared`,
+ *   `deleteTunnelCloudflared` and the account-wide `listTunnels` (GET `/accounts/{id}/tunnels`,
+ *   filtered to `cfd_tunnel`), all in distilled `1.0.0-rc.13` `src/services/zero_trust.ts`
+ *   (read 2026-10-09).
+ *
+ * ⛔ NO FUNCTION IN THIS FILE CALLS `getTunnelCloudflaredToken`, AND `observe` COPIES NAMED FIELDS
+ *   ONLY. Alchemy's own `Cloudflare.Tunnel.Tunnel` (beta.81, Tunnel/Tunnel.ts `reconcile`, `read`
+ *   and `list`) fetches the token on every call and stores it as a `Redacted` attribute, which
+ *   `encodeState` (State/StateEncoding.ts) writes into state as `{"__redacted__": "<token>"}`:
+ *   plaintext, and the token runs the tunnel. This package never holds it, so there is nothing to
+ *   leak. See cloudflared-tunnel-form.ts.
+ * ⚠️ `createTunnelCloudflared` takes no `tunnelSecret` here either: the schema calls the field the
+ *   password for a locally-managed tunnel and marks it optional (distilled rc.13 zero_trust.ts,
+ *   `CreateTunnelCloudflaredRequest`); that Cloudflare generates one when it is omitted is
+ *   UNVERIFIED, and a remotely managed tunnel needs no secret on our side.
+ */
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+/** A live tunnel as this package sees it. ⛔ There is no token or secret field, on purpose. */
+export interface ObservedTunnel {
+  readonly id: string;
+  readonly name: string;
+  /** `undefined` when the response omitted it; only an explicit `local` is refused (lifecycle). */
+  readonly configSrc: 'cloudflare' | 'local' | undefined;
+}
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a token. */
+export class CloudflaredTunnelError extends Data.TaggedError('CloudflaredTunnelError')<{
+  readonly message: string;
+}> {}
+
+type Raw = {
+  readonly id?: string | null;
+  readonly name?: string | null;
+  readonly configSrc?: string | null;
+  readonly tunType?: string | null;
+  readonly deletedAt?: string | null;
+};
+
+/**
+ * ⚠️ A DELETED TUNNEL IS NOT A TUNNEL. Cloudflare keeps deleted tunnels (every response carries
+ *   `deleted_at`), so a `GET` by id can answer for one; adopting that tombstone would PATCH it.
+ * ⚠️ NOR IS ANOTHER TUNNEL TYPE. `/tunnels` lists every type, and a `warp_connector` (a Mesh node)
+ *   shares the account's name space. An item whose `tun_type` is anything but `cfd_tunnel` is not
+ *   ours even when the name matches. A response with no `tun_type` is accepted: it came from a
+ *   `cfd_tunnel`-scoped call.
+ */
+export const observe = (raw: Raw): ObservedTunnel | undefined => {
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return undefined;
+  if (raw.deletedAt !== undefined && raw.deletedAt !== null) return undefined;
+  if (typeof raw.tunType === 'string' && raw.tunType !== 'cfd_tunnel') return undefined;
+  const configSrc =
+    raw.configSrc === 'cloudflare' || raw.configSrc === 'local' ? raw.configSrc : undefined;
+  return { id: raw.id, name: raw.name ?? '', configSrc };
+};
+
+/** The tunnel with this id, or `undefined` when it is gone (404 / code 1002, or soft-deleted). */
+export const getTunnel = (accountId: string, tunnelId: string) =>
+  zeroTrust.getTunnelCloudflared({ accountId, tunnelId }).pipe(
+    Effect.map(observe),
+    Effect.catchTag('TunnelNotFound', () => Effect.succeed(undefined)),
+  );
+
+/**
+ * The live cloudflared tunnel with exactly this name, or `undefined`.
+ *
+ * ★ `name` and `tunTypes` are sent as filters, but the match is re-checked here: the filter's
+ *   exactness is not documented, and a prefix match would adopt the wrong tunnel.
+ * ⛔ Two live matches is refused rather than resolved. Names are unique per account (the create
+ *   answers code 1013 otherwise), so two means something this package does not understand.
+ */
+export const findTunnelByName = (accountId: string, name: string) =>
+  zeroTrust.listTunnels.items({ accountId, name, isDeleted: false, tunTypes: ['cfd_tunnel'] }).pipe(
+    Stream.map(observe),
+    Stream.filter((t): t is ObservedTunnel => t !== undefined && t.name === name),
+    Stream.runCollect,
+    Effect.flatMap((chunk) => {
+      const matches = Array.from(chunk);
+      if (matches.length <= 1) return Effect.succeed(matches[0]);
+      const ids = matches.map((t) => t.id).join(', ');
+      return Effect.fail(
+        new CloudflaredTunnelError({
+          message: `Tunnel name "${name}" matches ${matches.length} live cloudflared tunnels (${ids}). Names are unique per account, so refusing to guess which one is meant.`,
+        }),
+      );
+    }),
+  );
+
+/**
+ * ⛔ ALWAYS `configSrc: 'cloudflare'` (remotely managed), NEVER OMITTED. The dashboard and the
+ *   ingress rules a consumer later PUTs are the remote configuration; a `local` tunnel ignores
+ *   them. The SDK types the field as optional with two values (zero_trust.ts
+ *   `CreateTunnelCloudflaredRequest`) and does not say which is the default, so it is sent
+ *   explicitly. Create-only (the PATCH body has `name` and `tunnelSecret` only).
+ */
+export const createTunnel = (accountId: string, name: string) =>
+  zeroTrust.createTunnelCloudflared({ accountId, name, configSrc: 'cloudflare' }).pipe(
+    Effect.flatMap((raw) => {
+      const tunnel = observe(raw);
+      return tunnel === undefined
+        ? Effect.fail(
+            new CloudflaredTunnelError({ message: `Creating tunnel "${name}" returned no id.` }),
+          )
+        : Effect.succeed(tunnel);
+    }),
+  );
+
+/** ★ A rename is a PATCH: same id, same connectors, same `<id>.cfargotunnel.com` target. */
+export const renameTunnel = (accountId: string, tunnelId: string, name: string) =>
+  zeroTrust
+    .patchTunnelCloudflared({ accountId, tunnelId, name })
+    .pipe(Effect.map((raw) => observe(raw) ?? { id: tunnelId, name, configSrc: undefined }));
+
+/**
+ * ⚠️ The SDK types `deleteTunnelCloudflared`'s errors as `CloudflareOpError`, which has no
+ *   `NotFound`, yet a 404 reaches the caller as `NotFound` at runtime (protocol.ts `HTTP_STATUS_MAP`,
+ *   measured through the fake). So the tag is matched by name, not by `catchTag`'s typed union.
+ */
+const isNotFound = (error: { readonly _tag: string }) => error._tag === 'NotFound';
+
+/**
+ * ⛔ DELETE BY THE STORED ID ONLY, AFTER A READ BY THAT ID. Never by name: a name can have been
+ *   re-used by another tunnel since this one was written, and a delete cannot be taken back. An
+ *   empty id is refused before any request (a blank path segment would address the collection).
+ * ★ Idempotent: a tunnel already gone or soft-deleted is a successful delete, including one that
+ *   vanishes between the read and the DELETE (see `isNotFound`). The API refuses a
+ *   delete while connectors are attached ("The tunnel must have no active connections", SDK doc on
+ *   `deleteTunnelCloudflared`); that error passes through, since the operator must stop cloudflared.
+ */
+export const deleteTunnel = (accountId: string, tunnelId: string) =>
+  Effect.gen(function* () {
+    if (tunnelId.length === 0) {
+      return yield* Effect.fail(
+        new CloudflaredTunnelError({ message: 'Refusing to delete a tunnel with an empty id.' }),
+      );
+    }
+    const live = yield* getTunnel(accountId, tunnelId);
+    if (live === undefined) return;
+    yield* zeroTrust
+      .deleteTunnelCloudflared({ accountId, tunnelId })
+      .pipe(Effect.catchIf(isNotFound, () => Effect.void));
+  });

package/src/cloudflare/cloudflared-tunnel-edges.test.ts

@@ -0,0 +1,179 @@
+/**
+ * CloudflaredTunnelProvider's refusals and recoveries — the cases a mutation of each guard must
+ * break: the two-match refusal, the tunnel-type check, the tombstone check, the 404 on a stored id
+ * (read says missing), the stored account, the 1013 race, the `local` refusal, delete's id
+ * precondition and a tunnel vanishing mid-delete.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { extra, ids, read, reconcile, run, stored, writes } from './cloudflared-tunnel-harness.ts';
+import { FAKE_ACCOUNT, fakeFailure } from './fake-mesh.ts';
+import { fakeTunnels } from './fake-tunnel.ts';
+
+const OTHER_ACCOUNT = '00000000000000000000000000000002';
+const UNKNOWN_ID = '00000000-0000-4000-9000-00000000ffff';
+const props = { name: 'k8s-admin' };
+
+describe('CloudflaredTunnelProvider edges', () => {
+  test('lookups filter by name, live-only and cfd_tunnel on the wire', async () => {
+    const fake = fakeTunnels();
+    await run(fake, (p) => read(p, props));
+    const list = fake.seen.find((s) => s.method === 'GET');
+    expect(list?.path).toContain('/tunnels?');
+    expect(list?.path).toContain('name=k8s-admin');
+    expect(list?.path).toContain('is_deleted=false');
+    expect(list?.path).toContain('tun_types=cfd_tunnel');
+  });
+
+  test('a prefix-only match, a deleted tunnel and a Mesh node of the same name are not adopted', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-admin-2' });
+    fake.seed({ name: 'k8s-admin', deleted_at: '2026-10-08T00:00:00Z' });
+    // ⚠️ The fake's list honours tun_types, so this proves the client's own re-check by id: GET.
+    fake.seed({ name: 'k8s-admin', tun_type: 'warp_connector' });
+    expect(await run(fake, (p) => read(p, props))).toBeUndefined();
+    const mesh = [...fake.tunnels.values()].find((t) => t.tun_type === 'warp_connector');
+    const viaId = stored(FAKE_ACCOUNT, { id: mesh?.id ?? '' });
+    expect(await run(fake, (p) => read(p, { name: 'zz' }, viaId))).toBeUndefined();
+  });
+
+  test('two live tunnels with the declared name are refused, both named', async () => {
+    const fake = fakeTunnels();
+    const a = fake.seed({ name: 'k8s-admin' });
+    const b = fake.seed({ name: 'k8s-admin' });
+    const failure = await run(fake, (p) => Effect.flip(read(p, props)));
+    expect(failure.message).toContain(a.id);
+    expect(failure.message).toContain(b.id);
+  });
+
+  test('a stored id the API no longer knows (404): read says missing and never probes the name, reconcile creates', async () => {
+    const fake = fakeTunnels();
+    // ⚠️ A same-named foreign tunnel: Drift treats what read returns as ours, so adopting it
+    // here would bypass adopt(true). The probe is for a row-less read only.
+    fake.seed({ name: 'k8s-admin' });
+    const gone = stored(FAKE_ACCOUNT, { id: UNKNOWN_ID, name: 'k8s-admin' });
+    expect(await run(fake, (p) => read(p, props, gone))).toBeUndefined();
+    expect(fake.seen.map((s) => s.method)).toEqual(['GET']);
+    expect(fake.seen.some((s) => s.path.includes('/tunnels?'))).toBe(false);
+
+    const fresh = fakeTunnels();
+    const created = await run(fresh, (p) => reconcile(p, { name: 'k8s-other' }, gone));
+    expect(created.id).not.toBe(UNKNOWN_ID);
+    expect(writes(fresh)).toEqual(['POST']);
+  });
+
+  test('a gone row over a same-named foreign tunnel: reconcile refuses and names it, writes nothing', async () => {
+    const fake = fakeTunnels();
+    const foreign = fake.seed({ name: 'k8s-admin' });
+    const gone = stored(FAKE_ACCOUNT, { id: UNKNOWN_ID });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, props, gone)));
+    expect(failure.message).toContain(foreign.id);
+    expect(failure.message).toContain('already exists');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('read refreshes in the account the tunnel was written to, not the current environment', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', status: 'healthy' });
+    const output = stored(FAKE_ACCOUNT, { id: tunnel.id });
+    // ⚠️ The fake throws on any other account, so reading in OTHER_ACCOUNT fails this test.
+    const fresh = await run(fake, (p) => read(p, props, output), OTHER_ACCOUNT);
+    expect(fresh).toMatchObject({ id: tunnel.id, accountId: FAKE_ACCOUNT });
+  });
+
+  test('a rename onto a name another tunnel holds is refused, not forced', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-taken' });
+    const failure = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, props);
+        return yield* Effect.flip(reconcile(p, { name: 'k8s-taken' }, first));
+      }),
+    );
+    expect(failure.message).toContain('already exists');
+  });
+
+  test('create never converges on a tunnel it did not create', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-admin' });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, props)));
+    expect(failure.message).toContain('already exists');
+    expect(failure.message).toContain('do not delete it');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('a 1013 after a clean lookup names the tunnel that appeared, and does not adopt it', async () => {
+    const fake = fakeTunnels({
+      onCreate: (name) => {
+        fake.seed({ name });
+        return fakeFailure(409, 1013, 'tunnel with name already exists');
+      },
+    });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, props)));
+    const holder = fake.live()[0];
+    expect(failure.message).toContain(holder?.id ?? 'no holder');
+    expect(failure.message).toContain('adopt(true)');
+  });
+
+  test('a locally configured tunnel is refused on adoption and left untouched', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', config_src: 'local' });
+    const failure = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const adopted = yield* read(p, props);
+        return yield* Effect.flip(reconcile(p, props, adopted));
+      }),
+    );
+    expect(failure.message).toContain('config_src local');
+    expect(writes(fake)).toEqual([]);
+    expect(fake.tunnels.get(tunnel.id)?.name).toBe('k8s-admin');
+  });
+
+  test('delete addresses the stored id only: a same-named newer tunnel survives', async () => {
+    const fake = fakeTunnels();
+    const old = fake.seed({ name: 'k8s-admin', deleted_at: '2026-10-08T00:00:00Z' });
+    const newer = fake.seed({ name: 'k8s-admin' });
+    await run(fake, (p) =>
+      p.delete({ ...ids, ...extra, olds: props, output: stored(FAKE_ACCOUNT, { id: old.id }) }),
+    );
+    expect(writes(fake)).toEqual([]);
+    expect(fake.live().map((t) => t.id)).toEqual([newer.id]);
+  });
+
+  test('delete refuses an empty id before any request', async () => {
+    const fake = fakeTunnels();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        p.delete({ ...ids, ...extra, olds: props, output: stored(FAKE_ACCOUNT, { id: '' }) }),
+      ),
+    );
+    expect(failure.message).toContain('empty id');
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('a tunnel that vanishes between the pre-read and the DELETE is a successful delete', async () => {
+    const fake = fakeTunnels({ onDelete: () => fakeFailure(404, 1002, 'Tunnel not found') });
+    const tunnel = fake.seed({ name: 'k8s-admin' });
+    await run(fake, (p) =>
+      p.delete({ ...ids, ...extra, olds: props, output: stored(FAKE_ACCOUNT, { id: tunnel.id }) }),
+    );
+    expect(writes(fake)).toEqual(['DELETE']);
+  });
+
+  test('delete while connectors are attached surfaces the API refusal, and deletes nothing', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', connected: true });
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        p.delete({
+          ...ids,
+          ...extra,
+          olds: props,
+          output: stored(FAKE_ACCOUNT, { id: tunnel.id }),
+        }),
+      ),
+    );
+    expect(String(JSON.stringify(failure))).toContain('active connections');
+    expect(fake.live()).toHaveLength(1);
+  });
+});

package/src/cloudflare/cloudflared-tunnel-form.ts

@@ -0,0 +1,78 @@
+/**
+ * `Cloudflare.CloudflaredTunnel` — its props, its attributes, and the pure `diff`.
+ *
+ * ⛔ THE ATTRIBUTES NEVER HOLD A TOKEN OR A SECRET. That is the reason this resource exists next to
+ *   Alchemy's `Cloudflare.Tunnel.Tunnel` (beta.81): its `reconcile`, `read` and `list` all call
+ *   `getTunnelCloudflaredToken` and keep the result as `token: Redacted<string>`, which
+ *   `encodeState` persists as `{"__redacted__": "<token>"}` in the (unencrypted) state store. That
+ *   token is what `cloudflared tunnel run --token` accepts: whoever reads state can run a connector
+ *   for the tunnel and receive its traffic. It also makes every PLAN need a token with a Write
+ *   permission. This resource never calls the endpoint, so a plan runs on a read token.
+ * ★ THE CONNECTOR'S TOKEN IS A RUNTIME CREDENTIAL, NOT INFRASTRUCTURE STATE. Whatever installs the
+ *   connector fetches it at that moment and hands it straight to the workload's secret store.
+ *   Nothing here does, and nothing here exports a helper that would.
+ * ★ SCOPE: the tunnel object only. No ingress rules, no routes, no DNS, no connector Deployment:
+ *   those are separate declarations that name this tunnel's `id`.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CloudflaredTunnelError } from './cloudflared-tunnel-api.ts';
+
+export interface CloudflaredTunnelProps {
+  /**
+   * The tunnel's name in the account — and its identity when adopting (names are unique per
+   * account). ★ Changing it RENAMES the tunnel in place (`PATCH`): the id, the connectors and the
+   * `<id>.cfargotunnel.com` target survive.
+   */
+  readonly name: string;
+}
+
+export interface CloudflaredTunnelAttributes {
+  /** The tunnel's UUID: the `<id>.cfargotunnel.com` target and the key for ingress rules. */
+  readonly id: string;
+  /**
+   * The account the provider environment resolved when the tunnel was written. Not a secret; it
+   * is what `delete` and `read` address, so they never act on the current environment's account.
+   */
+  readonly accountId: string;
+  readonly name: string;
+  // ★ No `status`: it moves on its own as connectors attach and drop, so a stored copy would make
+  //   every `alchemy drift` report this tunnel as drifted. Health is the API's or the metrics' to say.
+}
+
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export const validateCloudflaredTunnel = (
+  props: CloudflaredTunnelProps,
+): CloudflaredTunnelError | undefined => {
+  if (typeof props.name !== 'string' || props.name.trim().length === 0) {
+    return new CloudflaredTunnelError({
+      message: 'CloudflaredTunnel `name` must be a non-empty string.',
+    });
+  }
+  if (props.name !== props.name.trim()) {
+    return new CloudflaredTunnelError({
+      message: `CloudflaredTunnel name "${props.name}" has leading or trailing whitespace; adoption matches names exactly.`,
+    });
+  }
+  return undefined;
+};
+
+/**
+ * update or replace, from the declaration and what was last written.
+ *
+ * - Account changed → `replace`, create-first: names are unique per ACCOUNT, so the two
+ *   generations cannot collide.
+ * - Name changed → `update` (a PATCH rename).
+ * - Otherwise → no opinion; the engine compares props.
+ */
+export const diffCloudflaredTunnel = (
+  news: Input<CloudflaredTunnelProps>,
+  output: CloudflaredTunnelAttributes | undefined,
+  accountId: string,
+): Diff | undefined => {
+  if (output === undefined) return undefined;
+  if (output.accountId !== accountId) return { action: 'replace' };
+  const name = (news as { readonly name?: unknown }).name;
+  if (typeof name === 'string' && name !== output.name) return { action: 'update' };
+  return undefined;
+};