@homeflare/alchemy 0.48.1 → 0.49.0

package/dist/cloudflare/saas-oidc-form.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `HomeFlare.Access.SaasOidcApplication` — the pure helpers the lifecycle uses: validation, the
+ * issuer URLs, drift, the write body and the attribute mapping. The props and attributes types are
+ * declared in saas-oidc-props.ts and re-exported here.
+ *
+ * ⛔ THE ATTRIBUTES NEVER HOLD THE CLIENT SECRET, and nothing here can: `ObservedApp`
+ *   (saas-oidc-api.ts) has no field for it. A client that authenticates with PKCE alone declares
+ *   `allowPkceWithoutClientSecret: true`, and then no secret exists to keep.
+ * ★ THE ISSUER IS `https://<teamDomain>/cdn-cgi/access/sso/oidc/<clientId>`. The team domain is a
+ *   prop; the openbao copy this came from hardcoded one account's. Cloudflare also reports the
+ *   same host in the app's own `domain` field (Alchemy's `Access.Application` doc: for `saas`
+ *   "Cloudflare uses the OIDC issuer"), and `checkTeam` refuses a declaration that disagrees with it.
+ */
+import { SaasOidcError } from './saas-oidc-error.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-props.ts';
+import type { AppWrite, ObservedApp } from './saas-oidc-wire.ts';
+export type { OidcGrantType, OidcScope, SaasOidcApplicationAttributes, SaasOidcApplicationProps, } from './saas-oidc-props.ts';
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export declare const validateSaasOidc: (props: SaasOidcApplicationProps) => SaasOidcError | undefined;
+export declare const issuerFor: (teamDomain: string, clientId: string) => string;
+/**
+ * ⛔ A DECLARED TEAM DOMAIN THAT DISAGREES WITH THE APP'S OWN `domain` is refused: the issuer in
+ *   the attributes would point at a different team than the one that holds the app.
+ * ⛔ WHEN CLOUDFLARE REPORTS NO `domain` there is nothing to compare, so the team the row already
+ *   recorded (`knownTeam`, from state) stands in: a declaration that moves it is refused, because
+ *   `issuer` is a declared stable and must not move under the row. With no `knownTeam` either
+ *   (a first create or a cold adoption) there is nothing to compare against and the declaration
+ *   stands.
+ */
+export declare const checkTeam: (teamDomain: string, app: ObservedApp, knownTeam?: string) => SaasOidcError | undefined;
+/** The request body for a create or an update. */
+export declare const writeBody: (news: SaasOidcApplicationProps, name: string) => AppWrite;
+/**
+ * Does the live app differ from the declaration? Compared: name, auth type, redirect URIs, scopes,
+ * grant types (each as a set), both lifetimes, the PKCE flag and the policies IN ORDER — the
+ * openbao copy's set plus the policy order, kept so adopting a live app is not newly a write.
+ * ⚠️ NOT COMPARED: `sessionDuration`, `allowedIdps`, `autoRedirectToIdentity`, `appLauncherVisible`,
+ *   `appLauncherUrl`. They are written on create and on any sync, but a change to only those does
+ *   not trigger one. Carried over unchanged; see saas-oidc.md.
+ */
+export declare const needsSync: (news: SaasOidcApplicationProps, observed: ObservedApp, name: string) => boolean;
+/**
+ * The attributes of a live app, or `undefined` when it lacks an id, an `aud` or a client id (so it
+ * is not a SaaS OIDC app this package can describe). `teamDomain` is the declared one, or, for a
+ * read that has no declaration (state written before the prop existed), the host Cloudflare reports.
+ */
+export declare const toAttributes: (app: ObservedApp, accountId: string, fallbackName: string, declaredTeam: string | undefined) => SaasOidcApplicationAttributes | undefined;
+//# sourceMappingURL=saas-oidc-form.d.ts.map

package/dist/cloudflare/saas-oidc-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc-form.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIjE,YAAY,EACV,aAAa,EACb,SAAS,EACT,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAI9B,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,UAAW,wBAAwB,KAAG,aAAa,GAAG,SAmBlF,CAAC;AAEF,eAAO,MAAM,SAAS,eAAgB,MAAM,YAAY,MAAM,KAAG,MACJ,CAAC;AAI9D;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,eACR,MAAM,OACb,WAAW,cACJ,MAAM,KACjB,aAAa,GAAG,SAalB,CAAC;AAKF,kDAAkD;AAClD,eAAO,MAAM,SAAS,SAAU,wBAAwB,QAAQ,MAAM,KAAG,QAmBvE,CAAC;AAgBH;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,SACd,wBAAwB,YACpB,WAAW,QACf,MAAM,KACX,OAcF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAClB,WAAW,aACL,MAAM,gBACH,MAAM,gBACN,MAAM,GAAG,SAAS,KAC/B,6BAA6B,GAAG,SA6BlC,CAAC"}

package/dist/cloudflare/saas-oidc-harness.d.ts

@@ -0,0 +1,50 @@
+import * as State from 'alchemy/State';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import { type FakeAccess } from './fake-access.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-form.ts';
+import { SaasOidcApplication } from './saas-oidc.ts';
+export declare const strict: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const ids: {
+    fqn: string;
+    id: string;
+    instanceId: string;
+};
+export declare const extra: {
+    bindings: never;
+    session: never;
+};
+export type P = Effect.Success<typeof SaasOidcApplication.Provider>;
+/** A public PKCE client, the shape Headlamp declares (Q6). */
+export declare const publicClient: (over?: Partial<SaasOidcApplicationProps>) => SaasOidcApplicationProps;
+/** The wire `saas_app` of a live app that matches `publicClient()` exactly (no drift to sync). */
+export declare const LIVE_OIDC: {
+    auth_type: string;
+    redirect_uris: string[];
+    scopes: string[];
+    grant_types: string[];
+    access_token_lifetime: string;
+    allow_pkce_without_client_secret: boolean;
+};
+/** Build the provider over the fake and hand it to `use`. */
+export declare const run: <A, E>(fake: FakeAccess, use: (p: P) => Effect.Effect<A, E, never>) => Promise<A>;
+export declare const reconcile: (p: P, news: SaasOidcApplicationProps, output?: SaasOidcApplicationAttributes) => Effect.Effect<SaasOidcApplicationAttributes, any, never>;
+export declare const read: (p: P, olds: SaasOidcApplicationProps, output?: SaasOidcApplicationAttributes) => Effect.Effect<SaasOidcApplicationAttributes | undefined, any, never>;
+/** The writes the fake saw, in order: `['POST', 'PUT', …]`. */
+export declare const writes: (fake: FakeAccess) => string[];
+type Rows = Record<string, Record<string, Record<string, State.ResourceState>>>;
+/**
+ * ★ THE REAL ENGINE, NOT A MODEL OF IT: `Plan.make` + `apply` over an in-memory state store, as
+ *   mesh-node-harness.ts does. `rows` is that store, so a test can serialise exactly what Alchemy
+ *   would persist.
+ */
+export declare const engine: (fake: FakeAccess, extra?: Layer.Layer<never, never, never>) => {
+    deploy: <A, E, R>(declare: Effect.Effect<A, E, R>) => Promise<Exit.Exit<unknown, unknown>>;
+    rows: Rows;
+    status: (fqn: string) => "created" | "creating" | "deleting" | "replaced" | "replacing" | "updated" | "updating" | undefined;
+};
+/** The failure sentence of a deploy, or `''` when it succeeded. */
+export declare const failureOf: (exit: Exit.Exit<unknown, unknown>) => string;
+export {};
+//# sourceMappingURL=saas-oidc-harness.d.ts.map

package/dist/cloudflare/saas-oidc-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc-harness.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc-harness.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,KAAK,MAAM,eAAe,CAAC;AAGvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,mBAAmB,EAA+B,MAAM,gBAAgB,CAAC;AAclF,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACpB,CAAC;AAEnE,eAAO,MAAM,GAAG;IAAK,GAAG;IAAoB,EAAE;IAAc,UAAU;CAAS,CAAC;AAChF,eAAO,MAAM,KAAK;IAAK,QAAQ,EAAQ,KAAK;IAAE,OAAO,EAAe,KAAK;CAAE,CAAC;AAE5E,MAAM,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAEpE,8DAA8D;AAC9D,eAAO,MAAM,YAAY,UACjB,OAAO,CAAC,wBAAwB,CAAC,KACtC,wBAaD,CAAC;AAEH,kGAAkG;AAClG,eAAO,MAAM,SAAS;IACpB,SAAS;IACT,aAAa;IACb,MAAM;IACN,WAAW;IACX,qBAAqB;IACrB,gCAAgC;CACjC,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,QAAQ,UAAU,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,eAWlF,CAAC;AAEJ,eAAO,MAAM,SAAS,MACjB,CAAC,QACE,wBAAwB,WACrB,6BAA6B,6DAC6B,CAAC;AAEtE,eAAO,MAAM,IAAI,MACZ,CAAC,QACE,wBAAwB,WACrB,6BAA6B,yEAKvC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,MAAM,SAAU,UAAU,aAC2B,CAAC;AAEnE,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,MAAM,SAAU,UAAU,UAAS,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;aAO9D,CAAC,EAAE,CAAC,EAAE,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;;kBAexC,MAAM;CAEvB,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,SAAS,SAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,WACG,CAAC"}

package/dist/cloudflare/saas-oidc-lifecycle.d.ts

@@ -0,0 +1,14 @@
+import * as Effect from 'effect/Effect';
+import { SaasOidcError } from './saas-oidc-error.ts';
+import { type SaasOidcApplicationAttributes, type SaasOidcApplicationProps } from './saas-oidc-form.ts';
+/**
+ * Owned: refresh by the stored id ONLY (gone is `undefined`, never a same-named app). Cold: find the app by `applicationId` or exact name and hand it
+ * back `Unowned`, so Alchemy refuses to take it over until the stack says `adopt(true)`.
+ * ★ `olds` MAY PREDATE `teamDomain` (state written by the openbao copy of this resource): the host
+ *   Cloudflare reports for the app stands in, so the first plan after the move can still read.
+ */
+export declare const readSaasOidc: (accountId: string, id: string, olds: SaasOidcApplicationProps | undefined, output: SaasOidcApplicationAttributes | undefined) => Effect.Effect<SaasOidcApplicationAttributes | undefined, import("@distilled.cloud/cloudflare/zero-trust").AccessReferenceNotFound | import("@distilled.cloud/cloudflare/Errors").CloudflareError | import("@distilled.cloud/cloudflare/Errors").CloudflareHttpError | import("@distilled.cloud/cloudflare/Errors").CloudflareRateLimited | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/cloudflare/Errors").InvalidRoute | SaasOidcError | import("@distilled.cloud/cloudflare/Errors").UnknownCloudflareError | import("@distilled.cloud/cloudflare/Credentials").CredentialsError | import("@distilled.cloud/grafana").DefaultErrors, import("alchemy").InstanceId | import("alchemy").Stack | import("alchemy").Stage | import("@distilled.cloud/cloudflare/Protocol").CloudflareOpContext>;
+/** observe, ensure (create or sync), read back. A no-op when nothing drifted. */
+export declare const reconcileSaasOidc: (accountId: string, id: string, news: SaasOidcApplicationProps, output: SaasOidcApplicationAttributes | undefined) => Effect.Effect<SaasOidcApplicationAttributes, import("@distilled.cloud/cloudflare/zero-trust").AccessDestinationConflict | import("@distilled.cloud/cloudflare/zero-trust").AccessReferenceNotFound | import("@distilled.cloud/cloudflare/Errors").CloudflareError | import("@distilled.cloud/cloudflare/Errors").CloudflareHttpError | import("@distilled.cloud/cloudflare/Errors").CloudflareRateLimited | import("@distilled.cloud/caddy").ConfigError | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/cloudflare/Errors").InvalidRoute | import("@distilled.cloud/cloudflare/Credentials").OAuthRefreshError | import("@distilled.cloud/cloudflare/zero-trust").OrganizationNotFound | SaasOidcError | import("@distilled.cloud/cloudflare/Errors").UnknownCloudflareError | import("@distilled.cloud/grafana").DefaultErrors, import("alchemy").InstanceId | import("alchemy").Stack | import("alchemy").Stage | import("@distilled.cloud/cloudflare/Protocol").CloudflareOpContext>;
+export declare const deleteSaasOidc: (output: SaasOidcApplicationAttributes) => Effect.Effect<void, import("@distilled.cloud/cloudflare/Errors").CloudflareError | import("@distilled.cloud/cloudflare/Errors").CloudflareHttpError | import("@distilled.cloud/cloudflare/Errors").CloudflareRateLimited | import("@distilled.cloud/caddy").ConfigError | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/cloudflare/Errors").InvalidRoute | import("@distilled.cloud/cloudflare/Credentials").OAuthRefreshError | SaasOidcError | import("@distilled.cloud/cloudflare/Errors").UnknownCloudflareError | import("@distilled.cloud/grafana").DefaultErrors, import("@distilled.cloud/cloudflare/Protocol").CloudflareOpContext>;
+//# sourceMappingURL=saas-oidc-lifecycle.d.ts.map

package/dist/cloudflare/saas-oidc-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc-lifecycle.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc-lifecycle.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAM9B,MAAM,qBAAqB,CAAC;AAqC7B;;;;;GAKG;AACH,eAAO,MAAM,YAAY,cACZ,MAAM,MACb,MAAM,QACJ,wBAAwB,GAAG,SAAS,UAClC,6BAA6B,GAAG,SAAS,uyBAiB/C,CAAC;AASL,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,cACjB,MAAM,MACb,MAAM,QACJ,wBAAwB,UACtB,6BAA6B,GAAG,SAAS,g+BAmD/C,CAAC;AAEL,eAAO,MAAM,cAAc,WAAY,6BAA6B,opBACjB,CAAC"}

package/dist/cloudflare/saas-oidc-props.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The declared shape of `HomeFlare.Access.SaasOidcApplication` and what it reports back, apart from
+ * the pure helpers that use them (saas-oidc-form.ts re-exports both types, so imports keep working).
+ *
+ * ★ EVERY PROP FIELD CARRIES A JSDOC (provider standard S5). Where the wording below is the API's,
+ *   it is the SDK's own field doc on the request type
+ *   (`@distilled.cloud/cloudflare@1.0.0-rc.13` `zero-trust` `CreateAccessApplicationForAccountRequest`
+ *   and `AccessApplicationsCreateRequestSaasAppOIDCSaaSApp`, src/services/zero_trust.ts:9025-9053 and
+ *   :9728-9794), so a reader gets the vendor's meaning without leaving the editor.
+ * ⛔ THE ATTRIBUTES NEVER HOLD THE CLIENT SECRET, and nothing here can: there is no field for it.
+ */
+/**
+ * An OIDC flow Access can serve for the client: the five literals the SDK names
+ * (`AccessApplicationsCreateRequestSaasAppOIDCSaaSAppGrantTypesItem`, zero_trust.ts:8946-8951).
+ */
+export type OidcGrantType = 'authorization_code' | 'authorization_code_with_pkce' | 'refresh_tokens' | 'hybrid' | 'implicit';
+/** The user information the client may request from Access. */
+export type OidcScope = 'openid' | 'email' | 'profile' | 'groups';
+export interface SaasOidcApplicationProps {
+    /**
+     * Live Access application UUID. Set this when adopting a SaaS app that already exists. Without
+     * it the app is found by exact `name` among saas apps, which also works but refuses two matches.
+     */
+    readonly applicationId?: string;
+    /** The app's name. Defaults to a physical name derived from the logical id. */
+    readonly name?: string;
+    /**
+     * The Zero Trust team domain the issuer lives on, a bare hostname such as
+     * `example.cloudflareaccess.com`: no scheme, no path. Not read from the environment, so the
+     * issuer in the attributes is the one the declaration says.
+     */
+    readonly teamDomain: string;
+    /**
+     * How long Access sessions for this app last, in the API's duration format (`300ms` or `2h45m`).
+     * Written on create and on any sync; not drift-checked.
+     * @default '24h'
+     */
+    readonly sessionDuration?: string;
+    /**
+     * Ids of the identity providers users may pick for this app. Written on create and on any sync;
+     * not drift-checked.
+     * @default every IdP configured in the account (the field is left out of the write)
+     */
+    readonly allowedIdps?: ReadonlyArray<string>;
+    /**
+     * `true` makes users skip the identity-provider selection step; the API requires exactly one
+     * entry in `allowedIdps` then. Written on create and on any sync; not drift-checked.
+     * @default left out of the write (the API's default)
+     */
+    readonly autoRedirectToIdentity?: boolean;
+    /**
+     * Show the app in the App Launcher. Written on create and on any sync; not drift-checked.
+     * @default false
+     */
+    readonly appLauncherVisible?: boolean;
+    /**
+     * Ids of reusable Access policies, in ascending order of precedence (the SDK's own wording:
+     * zero_trust.ts:9774). The ORDER is part of the declaration: a reorder is drift and is synced.
+     */
+    readonly policies: ReadonlyArray<string>;
+    /** The OIDC client: the `saas_app` object of the Access application. */
+    readonly saasApp: {
+        /** The authentication protocol of the SaaS app. Only `oidc` is supported by this resource. */
+        readonly authType: 'oidc';
+        /**
+         * The permitted URLs for Cloudflare to return authorization codes and tokens to. Compared as
+         * a set (order is not significant to the API).
+         */
+        readonly redirectUris: ReadonlyArray<string>;
+        /** The user information shared with the client. Compared as a set. */
+        readonly scopes: ReadonlyArray<OidcScope>;
+        /** The OIDC flows the client may use. Compared as a set. */
+        readonly grantTypes: ReadonlyArray<OidcGrantType>;
+        /** Lifetime of the access token after creation: `m` or `h` units, `1m` to `24h` (the SDK field doc). */
+        readonly accessTokenLifetime: string;
+        /**
+         * How long a refresh token is valid after creation: `m`, `h` or `d` units, longer than `1m`
+         * (the SDK field doc). Needed for the `refresh_tokens` grant. Sent as `refreshTokenOptions.lifetime`.
+         * @default left out of the write
+         */
+        readonly refreshTokenLifetime?: string;
+        /**
+         * `true` makes this a PUBLIC client: the token endpoint does not require a client secret when
+         * the `authorization_code_with_pkce` grant is used, and then no secret exists to keep. Refused
+         * without that grant.
+         * @default false (a confidential client)
+         */
+        readonly allowPkceWithoutClientSecret?: boolean;
+        /**
+         * The URL the app's tile in the App Launcher sends users to. Written on create and on any
+         * sync; not drift-checked.
+         * @default left out of the write
+         */
+        readonly appLauncherUrl?: string;
+    };
+}
+export interface SaasOidcApplicationAttributes {
+    /** The Access application UUID. */
+    readonly applicationId: string;
+    /** The application audience tag, the `aud` of the Access JWTs for this app. */
+    readonly aud: string;
+    /** The `domain` Cloudflare reports for the app (the OIDC issuer without its scheme). */
+    readonly domain: string;
+    /** The app's name as Cloudflare reports it. */
+    readonly name: string;
+    /** The account the app lives in. */
+    readonly accountId: string;
+    /** The declared team domain (or, for state that predates the prop, the host Cloudflare reports). */
+    readonly teamDomain: string;
+    /** The OIDC client id, for the relying party's configuration. */
+    readonly clientId: string;
+    /** `https://<teamDomain>/cdn-cgi/access/sso/oidc/<clientId>`. */
+    readonly issuer: string;
+    /** `<issuer>/authorization`. */
+    readonly authorizationEndpoint: string;
+    /** `<issuer>/token`. */
+    readonly tokenEndpoint: string;
+    /** The signing keys, for a verifier that validates ID tokens. */
+    readonly jwksEndpoint: string;
+    /** `<issuer>/userinfo`. */
+    readonly userinfoEndpoint: string;
+    /** `<issuer>/.well-known/openid-configuration`. */
+    readonly configurationEndpoint: string;
+    /** The redirect URIs the live app permits. */
+    readonly redirectUris: ReadonlyArray<string>;
+    /** The scopes the live app serves. */
+    readonly scopes: ReadonlyArray<string>;
+    /** The grant types the live app allows. */
+    readonly grantTypes: ReadonlyArray<string>;
+    /** The live access token lifetime, or `''` when Cloudflare reports none. */
+    readonly accessTokenLifetime: string;
+    /** The live refresh token lifetime, or `''` when Cloudflare reports none. */
+    readonly refreshTokenLifetime: string;
+    /** When Cloudflare created the app, if it says. */
+    readonly createdAt: string | undefined;
+    /** When Cloudflare last updated the app, if it says. */
+    readonly updatedAt: string | undefined;
+}
+//# sourceMappingURL=saas-oidc-props.d.ts.map

package/dist/cloudflare/saas-oidc-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc-props.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc-props.ts"],"names":[],"mappings":"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"}

package/dist/cloudflare/saas-oidc-team.d.ts

@@ -0,0 +1,9 @@
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import { SaasOidcError } from './saas-oidc-error.ts';
+/**
+ * A refusal when the account's organization is read and its domain is not the declared one; else
+ * `undefined` (it matches, or it could not be read, see above). Hostnames compare case-insensitively.
+ */
+export declare const checkTeamBeforeCreate: (accountId: string, teamDomain: string) => Effect.Effect<SaasOidcError | undefined, import("@distilled.cloud/cloudflare/Errors").CloudflareError | import("@distilled.cloud/cloudflare/Errors").CloudflareHttpError | import("@distilled.cloud/cloudflare/Errors").CloudflareRateLimited | import("@distilled.cloud/caddy").ConfigError | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/cloudflare/Errors").InvalidRoute | import("@distilled.cloud/cloudflare/Credentials").OAuthRefreshError | zeroTrust.OrganizationNotFound | SaasOidcError | import("@distilled.cloud/cloudflare/Errors").UnknownCloudflareError | import("@distilled.cloud/grafana").DefaultErrors, zeroTrust.CloudflareOpContext>;
+//# sourceMappingURL=saas-oidc-team.d.ts.map

package/dist/cloudflare/saas-oidc-team.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc-team.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc-team.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,SAAS,MAAM,wCAAwC,CAAC;AACpE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,aAAa,EAAY,MAAM,sBAAsB,CAAC;AAyB/D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,cAAe,MAAM,cAAc,MAAM,qqBASxE,CAAC"}

package/dist/cloudflare/saas-oidc-wire.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The wire shapes of a SaaS OIDC application, and the parse that reads them: pure, no Effect, no
+ * request. saas-oidc-api.ts says why the read is raw JSON (the SDK's responses drop `saas_app`).
+ *
+ * ⛔ `parseApp` COPIES NAMED FIELDS ONLY, and `client_secret` is not among them: an `ObservedApp`
+ *   has nowhere to hold the client secret, so no code path can persist or log one.
+ */
+/** The OIDC half of a live SaaS app, from the wire JSON. */
+export interface ObservedSaas {
+    readonly authType: string | undefined;
+    readonly clientId: string | undefined;
+    readonly redirectUris: ReadonlyArray<string> | undefined;
+    readonly scopes: ReadonlyArray<string> | undefined;
+    readonly grantTypes: ReadonlyArray<string> | undefined;
+    readonly accessTokenLifetime: string | undefined;
+    readonly refreshTokenLifetime: string | undefined;
+    readonly allowPkceWithoutClientSecret: boolean | undefined;
+}
+/** A live Access application as this package sees it. ⛔ There is no secret field, on purpose. */
+export interface ObservedApp {
+    readonly id: string | undefined;
+    readonly aud: string | undefined;
+    readonly type: string | undefined;
+    readonly name: string | undefined;
+    readonly domain: string | undefined;
+    readonly createdAt: string | undefined;
+    readonly updatedAt: string | undefined;
+    readonly policyIds: ReadonlyArray<string>;
+    readonly saasApp: ObservedSaas | undefined;
+}
+/** What a create or an update sends. Built by `writeBody` in saas-oidc-form.ts. */
+export interface AppWrite {
+    readonly name: string;
+    readonly sessionDuration: string;
+    readonly allowedIdps: ReadonlyArray<string> | undefined;
+    readonly autoRedirectToIdentity: boolean | undefined;
+    readonly appLauncherVisible: boolean;
+    readonly policies: ReadonlyArray<string>;
+    readonly saasApp: {
+        readonly authType: 'oidc';
+        readonly redirectUris: ReadonlyArray<string>;
+        readonly scopes: ReadonlyArray<string>;
+        readonly grantTypes: ReadonlyArray<string>;
+        readonly accessTokenLifetime: string;
+        readonly refreshTokenOptions?: {
+            readonly lifetime: string;
+        };
+        readonly allowPkceWithoutClientSecret: boolean;
+        readonly appLauncherUrl: string | undefined;
+    };
+}
+export declare const record: (value: unknown) => Record<string, unknown> | undefined;
+/**
+ * Named fields only, from Cloudflare's snake_case JSON. ⛔ `client_secret` is not among them, and
+ * `public_key`, `custom_claims` and `hybrid_and_implicit_options` are not used by this resource.
+ */
+export declare const parseApp: (raw: Record<string, unknown>) => ObservedApp;
+//# sourceMappingURL=saas-oidc-wire.d.ts.map

package/dist/cloudflare/saas-oidc-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc-wire.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc-wire.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,4BAA4B,EAAE,OAAO,GAAG,SAAS,CAAC;CAC5D;AAED,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QACvC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC3C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE;YAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7D,QAAQ,CAAC,4BAA4B,EAAE,OAAO,CAAC;QAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;KAC7C,CAAC;CACH;AAOD,eAAO,MAAM,MAAM,UAAW,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAGnD,CAAC;AAuBhB;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,WA2BvD,CAAC"}

package/dist/cloudflare/saas-oidc.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `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 HttpClient from 'effect/http/HttpClient';
+import type { Providers } from './providers.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-form.ts';
+export interface SaasOidcApplication extends Resource<'HomeFlare.Access.SaasOidcApplication', SaasOidcApplicationProps, SaasOidcApplicationAttributes, never, Providers> {
+}
+export declare const SaasOidcApplication: ResourceClass<SaasOidcApplication>;
+/**
+ * ★ `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 declare const SaasOidcApplicationProvider: () => import("effect/Layer").Layer<Provider.Provider<SaasOidcApplication>, never, Cloudflare.CloudflareEnvironment | Credentials | HttpClient.HttpClient | import("alchemy").Stack | import("alchemy").Stage>;
+//# sourceMappingURL=saas-oidc.d.ts.map

package/dist/cloudflare/saas-oidc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saas-oidc.d.ts","sourceRoot":"","sources":["../../src/cloudflare/saas-oidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,KAAK,UAAU,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGhE,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEnG,MAAM,WAAW,mBAAoB,SAAQ,QAAQ,CACnD,sCAAsC,EACtC,wBAAwB,EACxB,6BAA6B,EAC7B,KAAK,EACL,SAAS,CACV;CAAG;AAEJ,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC,mBAAmB,CAG/D,CAAC;AAOL;;;GAGG;AACH,eAAO,MAAM,2BAA2B,+MAqDrC,CAAC"}

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)).