@homeflare/alchemy 0.48.0 → 0.49.0

package/docs/cloudflared-tunnel.md

@@ -0,0 +1,136 @@
+# CloudflaredTunnel — a Cloudflare Tunnel without its token in state
+
+`CloudflaredTunnel` (`Cloudflare.CloudflaredTunnel`) declares a Cloudflare Tunnel of the cloudflared
+kind (`cfd_tunnel`): the object whose `<id>.cfargotunnel.com` target DNS records point at and whose
+remote configuration holds the ingress rules. It declares **the tunnel object only**: no ingress
+rules, no routes, no DNS record, no connector Deployment. Those are separate declarations that name
+this tunnel's `id`. Read 2026-10-09 against `alchemy@2.0.0-beta.81` and
+`@distilled.cloud/cloudflare@1.0.0-rc.13`.
+
+## Why not `Cloudflare.Tunnel.Tunnel`
+
+- ⛔ **It puts the connector token in state.** Its `reconcile`, `read` and `list` call
+  `getTunnelCloudflaredToken` and keep the result as `token: Redacted<string>`
+  (`alchemy/src/Cloudflare/Tunnel/Tunnel.ts`). Alchemy's state encoder writes a `Redacted` value as
+  `{"__redacted__": "<the value>"}` (`alchemy/src/State/StateEncoding.ts`, `encodeState`, which
+  LocalState, HttpStateStore and PostgresState all call before writing). The state store is not
+  encrypted, and the token is what `cloudflared tunnel run --token` accepts, so anyone who can read
+  state can run a connector for the tunnel and receive its traffic.
+- **Its plans need a Write token.** The token endpoint is expected to need a Write permission, so even a plan
+  would. **UNVERIFIED for `cfd_tunnel`**: the only citation is the sibling Mesh node token endpoint
+  ("Cloudflare One Connectors Write", per its API reference, read 2026-09-21; see
+  `src/cloudflare/mesh-node-form.ts`), and the `cfd_tunnel` token endpoint's permission was not
+  read. `CloudflaredTunnel` never calls it, so a plan does not depend on the answer.
+
+`CloudflaredTunnel` follows the same pattern as [MeshNode](./mesh-node.md): attributes with no
+secret, adoption by exact name, `retain` by default. The type string is `CloudflaredTunnel`, not
+`Tunnel`, so it cannot be confused with upstream's `Cloudflare.Tunnel.Tunnel` in a stack that uses both.
+
+## Declaring a tunnel
+
+```ts
+import { CloudflaredTunnel, providers as homeflareCloudflare } from '@homeflare/alchemy/cloudflare';
+
+// providers: Layer.mergeAll(Cloudflare.providers(), homeflareCloudflare()),
+const admin = yield * CloudflaredTunnel('k8s-admin', { name: 'k8s-admin' });
+// admin.id → the tunnel UUID: `${admin.id}.cfargotunnel.com` is the DNS target
+```
+
+| prop   | type     | notes                                                                 |
+| ------ | -------- | --------------------------------------------------------------------- |
+| `name` | `string` | Unique per account. The identity used for adoption. Renames in place. |
+
+Attributes: `id`, `accountId` and `name`. ★ There is no `status`: it moves as connectors attach and
+drop, so a stored copy would make every `alchemy drift` flag the tunnel; read health from the API
+or the metrics. ⛔ There is no token, secret or `tunnelSecret` attribute, and none is sent. The request schema documents `tunnel_secret` as the password for a _locally-managed_ tunnel
+(`@distilled.cloud/cloudflare@1.0.0-rc.13`, `src/services/zero_trust.ts`, `CreateTunnelCloudflaredRequest`);
+this resource always sends `config_src: "cloudflare"`. **UNVERIFIED**: that Cloudflare itself generates and
+keeps a secret when `tunnel_secret` is omitted for such a tunnel; the schema says only that the field is optional. `accountId` is not a secret; it is what
+`read` and `delete` address, so they never act on whatever account the environment names today.
+
+The account and credentials come from Alchemy's own Cloudflare environment
+(`Cloudflare.CloudflareApiLive()`): an Alchemy profile, or `CLOUDFLARE_API_TOKEN` and
+`CLOUDFLARE_ACCOUNT_ID` in CI.
+
+### Remotely configured only
+
+The tunnel is always created with `config_src: "cloudflare"` (managed through the API and the Zero
+Trust dashboard), sent explicitly. The SDK types the field as optional (`local` or `cloudflare`)
+and does not document the default (`CreateTunnelCloudflaredRequest`, `zero_trust.ts`). It is
+create-only: the PATCH body has `name` and `tunnelSecret` only. A tunnel found by name whose
+`config_src` is `local` is **refused on adoption** with a sentence and left untouched, because its
+ingress is a YAML file on its origin and remote rules would be accepted and never applied.
+⚠️ UNVERIFIED: that every real GET/list response carries `config_src`. A response without it is
+accepted; only an explicit `local` is refused.
+
+## The token is not this resource's business
+
+Whatever installs the connector fetches the token at that moment and hands it straight to the
+workload's secret store (`GET /accounts/{id}/cfd_tunnel/{id}/token`, which needs a Write
+permission). It must not go into Alchemy state, a log line or a CI variable. No function in this
+package calls that endpoint, `observe` copies named fields only, and
+`cloudflared-tunnel-state.test.ts` proves the persisted state holds no token. ⚠️ Never deploy with
+`DISTILLED_DEBUG_HTTP` set: distilled prints the start of every response body.
+
+## What each change does
+
+| change                 | answer                  | what happens on Cloudflare                                                                                           |
+| ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `name`                 | `update`                | `PATCH`. The id, connectors and `cfargotunnel.com` target survive.                                                   |
+| account (provider env) | `replace`, create-first | A new tunnel in the new account. Under `retain` the old one stays.                                                   |
+| nothing                | none                    | Zero writes and no token read. An existing row's plan makes no request (`diff` is pure); the cold probe is one list. |
+
+⛔ **Removal policy: `retain` by default**, like MeshNode and the other kit resources whose deletion
+breaks their consumers. Deleting a tunnel drops its remote configuration and orphans every DNS record
+that targets it; a new tunnel has a new id and token. Dropping the declaration or `alchemy destroy`
+leaves the tunnel live and only drops it from state. Opt a declaration into deletion with
+`.pipe(RemovalPolicy.destroy())`. ⚠️ Under `retain` an account-change replace leaves the old tunnel
+live and unmanaged.
+
+## Adoption
+
+An existing tunnel is found by **exact** name among `cfd_tunnel`s and returned `Unowned`. Alchemy
+refuses to take it over until the resource is wrapped in `adopt(true)` (or `--adopt` is passed). A
+deleted tunnel, a tunnel of another type (a `warp_connector` Mesh node shares the name space) and a
+prefix match are never matched, and a name that matches two live tunnels is refused. Adoption is
+idempotent: the adopted row holds the id, so a repeat deploy takes the owned path and writes
+nothing. ⛔ The name probe runs only when there is **no** stored row. A stored id that the API no
+longer resolves (deleted out of band) reads as missing, never as a same-named tunnel: `alchemy drift`
+treats what `read` returns as already ours, so a probe there would write a foreign tunnel into this
+row without `adopt(true)`. Drift reports it missing and recreates, and the create refuses and
+names the holder. Without `adopt(true)`, a create whose name is held by another tunnel refuses and names the
+holder; it never converges on it, and the sentence says not to delete it.
+
+An interrupted create (the tunnel was made, its state was not saved) is found the same way on the
+next plan, so it too needs `adopt(true)`. ⚠️ distilled retries a create after a lost response or a
+5xx, and the retry is answered code 1013 by the tunnel the first attempt made: the error then names
+that tunnel's id and is not adopted silently, because a concurrent creator looks the same.
+
+## Deleting
+
+`delete` runs only under `RemovalPolicy.destroy()`. It addresses the **stored id and account**,
+never a name: it reads that id first, does nothing when the tunnel is already gone or soft-deleted,
+and refuses an empty id before any request. The API refuses a delete while connectors are attached
+("The tunnel must have no active connections", the SDK's own doc on `deleteTunnelCloudflared`); that
+error passes through unchanged, so scale cloudflared to zero first. No retry loop is added: a
+connector does not detach within seconds on its own. A tunnel that vanishes between the pre-read and
+the DELETE is a successful delete: the 404 reaches the caller as `NotFound` at runtime though the SDK's
+typed error union omits it (`protocol.ts`, `HTTP_STATUS_MAP`), so it is matched by tag name and caught. ⚠️ UNVERIFIED against the real API: the fake
+answers 404 / code 1002 there, the same shape `getTunnelCloudflared` documents.
+
+`list` is empty and `nuke` skips this type: Alchemy's own `Tunnel.Tunnel` already enumerates every
+`cfd_tunnel` for `alchemy unsafe nuke` (fetching each token to do it), and a second listing would
+delete each tunnel twice.
+
+## Tests
+
+Three test files in `src/cloudflare/` (plus `cloudflared-tunnel-harness.ts`, their shared helpers)
+run the provider against a fake API (`fake-tunnel.ts`) that hands out a token on every surface it can:
+
+- `cloudflared-tunnel.test.ts`: the lifecycle; the create body is `{name, config_src}` and no
+  request ever touches `/token`.
+- `cloudflared-tunnel-edges.test.ts`: each refusal and recovery, written to fail when its guard
+  is deleted.
+- `cloudflared-tunnel-state.test.ts`: Alchemy's real plan/apply, then `encodeState` over the stored
+  rows: no `__redacted__` marker, no `token` key, no token value, with a negative control showing
+  the same encoder does write a `Redacted` token. Also the removal policy and adoption.

package/docs/credentials.md

@@ -3,7 +3,7 @@
 Moved out of the README (2026-09-21) to make room under its 200-line cap; the text is unchanged.
 
 `CLOUDFLARE_API_TOKEN` is read from the environment at call time, never at module scope.
-`MeshNode` instead resolves credentials and the account the way `Cloudflare.providers()` does
+`MeshNode` and `CloudflaredTunnel` instead resolve credentials and the account the way `Cloudflare.providers()` does
 (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` in CI).
 
 ⛔ **Mint a short-lived, scoped token** — do not reuse a long-lived one, and never a Global

package/docs/ownership.md

@@ -100,8 +100,9 @@ escalating to `--adopt` only on `OwnedBySomeoneElse`
 ([inspecting state](https://alchemy.run/cli/inspecting-state#recover-from-bad-state)). For the
 families above that escalation always comes (decided 2026-09-21): an object whose row is gone is
 `Unowned`, so the deploy needs `--adopt`, or `adopt(true)` on its declaration. `MeshNode`
-([mesh-node.md](./mesh-node.md)) and `R2BucketLock` (`src/cloudflare/r2-bucket-lock.ts`) need it
-too. A `CaddyConfig` running the declared config re-imports without it, and so does every family
+([mesh-node.md](./mesh-node.md)), `CloudflaredTunnel`
+([cloudflared-tunnel.md](./cloudflared-tunnel.md)), `SaasOidcApplication` ([saas-oidc.md](./saas-oidc.md)) and
+`R2BucketLock` (`src/cloudflare/r2-bucket-lock.ts`) need it too. A `CaddyConfig` running the declared config re-imports without it, and so does every family
 whose `read` never answers `Unowned`: the `pveHandlers` resources (Limits), the `forgejoHandlers`
 resources and the Talos resources. Read the takeover first with `hf-adopt-verify`
 ([adopt-verify.md](./adopt-verify.md)).

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/talos-openbao-adapter.md

@@ -8,8 +8,9 @@ The design, the identity rule and the failure modes are in the header of
 
 ## Connect deadline
 
-Vault read and uid GET share one 10 s deadline. A hung `bao` or a silent apiserver fails closed
-with `TalosOpenBaoConnectTimeout` (the `bao` child is killed with its process group). The HTTPS
+The vault read and the uid GET share one 10 s deadline, and the uid GET has its own 5 s deadline
+inside it. A hung `bao` fails closed with `TalosOpenBaoConnectTimeout` (the `bao` child is killed
+with its process group); a silent apiserver fails closed first, with `TalosClusterIdentityTimeout`. The HTTPS
 GET itself cannot be cancelled: upstream `readObject` takes no abort signal, so the request may
 linger until the OS gives up. That is an upstream ask, not something to re-implement here.
 

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