import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { stripNullFields, stripUndefinedFields } from "alchemy/Util/data";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
export type OrganizationProps = {
/**
* The unique subdomain assigned to your Zero Trust organization, e.g.
* `acme.cloudflareaccess.com`. Per-account this is functionally immutable —
* Cloudflare allocates exactly one team domain when the account first
* enables Zero Trust and changing it is a manual support operation.
*
* @see https://developers.cloudflare.com/cloudflare-one/setup/#1-create-a-team-name
*/
authDomain: string;
/**
* Human-readable display name of your Zero Trust organization. Usually the
* same as `authDomain`. Mutable.
*
* @see https://developers.cloudflare.com/api/operations/zero-trust-organization-update-your-zero-trust-organization
*/
name?: string;
/**
* Default session lifetime for Access applications. Must be a Go duration
* string (e.g. `30m`, `2h45m`, `24h`). Valid units: `ns`, `us`, `ms`, `s`,
* `m`, `h`. Per-application settings override this default.
*
* @see https://developers.cloudflare.com/cloudflare-one/identity/users/session-management/
*/
sessionDuration?: string;
/**
* When `true`, users may authenticate to Access applications via the WARP
* client without going through the configured identity providers. Per-app
* settings take precedence.
*
* @default false
* @see https://developers.cloudflare.com/cloudflare-one/identity/devices/warp-authentication-identity/
*/
allowAuthenticateViaWarp?: boolean;
/**
* When `true`, all Zero Trust settings in the Cloudflare dashboard are
* read-only and may only be modified via the API or Terraform.
*
* @default false
*/
isUiReadOnly?: boolean;
/**
* When `true`, users skip the identity provider selection step on login.
* Only valid when exactly one IdP is configured (or one is set as default).
*
* @default false
*/
autoRedirectToIdentity?: boolean;
/**
* Free-form description of why `isUiReadOnly` is toggled. Surfaced in the
* Cloudflare dashboard.
*/
uiReadOnlyToggleReason?: string;
/**
* Duration of user-seat inactivity before the user is removed as an active
* seat and stops counting against the Teams seat quota. Go duration string.
*/
userSeatExpirationInactiveTime?: string;
/**
* Lifetime of tokens issued by the WARP authentication flow. Go duration
* string limited to `m` and `h` units, e.g. `30m` or `2h45m`.
*/
warpAuthSessionDuration?: string;
/**
* Branding for the Access login screen.
*
* @see https://developers.cloudflare.com/cloudflare-one/identity/users/login-page/
*/
loginDesign?: Organization.LoginDesign;
/**
* Pointers to custom HTML pages shown when Access blocks a request.
*
* @see https://developers.cloudflare.com/cloudflare-one/policies/access/custom-pages/
*/
customPages?: Organization.CustomPages;
/**
* When `true`, Access denies requests to hostnames on the account's zones
* that no Access application matches.
*
* @default false
* @see https://developers.cloudflare.com/cloudflare-one/access-controls/access-settings/require-access-protection/
*/
denyUnmatchedRequests?: boolean;
/**
* Zones exempted from `denyUnmatchedRequests`, by zone name (e.g.
* `example.com`).
*/
denyUnmatchedRequestsExemptedZoneNames?: string[];
/**
* When `true`, users can't create their own Access applications from the
* App Launcher.
*
* @default false
*/
disableEndUserAppCreation?: boolean;
/**
* Organization-wide multi-factor authentication settings, applied to
* applications that require Access MFA.
*
* @see https://developers.cloudflare.com/cloudflare-one/access-controls/access-settings/independent-mfa/
*/
mfaConfig?: Organization.MfaConfig;
/**
* Requirements for PIV keys and FIDO2 SSH keys used as MFA for
* infrastructure applications.
*/
mfaPivKeyRequirements?: Organization.MfaPivKeyRequirements;
/**
* When `true`, every Access application requires MFA unless it opts out.
*
* @default false
*/
mfaRequiredForAllApps?: boolean;
/**
* What happens to service tokens that go unused for a number of days.
*/
serviceTokenInactivity?: Organization.ServiceTokenInactivity;
/**
* When `true`, a request that presents a service token is evaluated only
* against service-token policies.
*
* @default false
*/
strictServiceTokenAuth?: boolean;
/**
* When `true`, WARP authentication answers non-browser requests that lack
* a session with `401` instead of redirecting to login.
*
* @default false
*/
warpAuthNonBrowser401?: boolean;
};
export declare namespace Organization {
/**
* Branding for the Access login screen.
*/
export interface LoginDesign {
/** URL of the logo image rendered at the top of the login form. */
logoPath?: string;
/** CSS color for the header background, e.g. `#1a1a1a`. */
headerBgColor?: string;
/** CSS color for the page background. */
backgroundColor?: string;
/** CSS color for the body text. */
textColor?: string;
/** Markdown rendered at the top of the login form (legacy). */
headerText?: string;
/** Markdown rendered at the bottom of the login form. */
footerText?: string;
}
/**
* Pointers to custom HTML pages shown when Access denies a request.
*/
export interface CustomPages {
/**
* UUID of a custom forbidden page (created via the Access Custom Pages
* API) shown when a policy denies access.
*/
forbidden?: string;
/**
* UUID of a custom identity-denied page shown when the identity provider
* rejects the user.
*/
identityDenied?: string;
}
/**
* Organization-wide MFA settings.
*/
export interface MfaConfig {
/**
* MFA methods users can authenticate with. `piv_key` and
* `ssh_fido2_key` apply only to infrastructure applications.
*/
allowedAuthenticators?: (
| "totp"
| "biometrics"
| "security_key"
| "piv_key"
| "ssh_fido2_key"
)[];
/**
* How long a user may skip Access MFA when their identity provider
* already reports MFA in the `amr` claim, e.g. `12h`. Minutes or hours,
* `0m` to `720h`.
*/
amrMatchingSessionDuration?: string;
/** ID of a Cloudflare List of allowed FIDO2 authenticator AAGUIDs. */
requiredAaguids?: string;
/** Lifetime of an MFA session, e.g. `24h`. Minutes or hours, `0m` to `720h`. */
sessionDuration?: string;
}
/**
* Requirements for PIV and SSH keys used as MFA.
*/
export interface MfaPivKeyRequirements {
/** When a PIN is required to use the key. */
pinPolicy?: "never" | "once" | "always";
/** Require a FIPS 140-2 Level 1 (or higher) validated device. */
requireFipsDevice?: boolean;
/** Allowed SSH key sizes in bits. Ed25519 keys have a fixed size. */
sshKeySize?: (256 | 384 | 521 | 2048 | 3072 | 4096)[];
/** Allowed SSH key types. */
sshKeyType?: ("ecdsa" | "ed25519" | "rsa")[];
/** When a physical touch is required (`cached` lasts 15 seconds). */
touchPolicy?: "never" | "always" | "cached";
}
/**
* Automatic handling of inactive service tokens.
*/
export interface ServiceTokenInactivity {
/** Whether inactive service tokens are acted on. */
enabled: boolean;
/** What to do with an inactive token. */
action: "disable" | "delete";
/** Days without use before a token counts as inactive. */
inactivityThresholdDays: number;
}
}
export type Organization = Resource<
"Cloudflare.Access.Organization",
OrganizationProps,
{
/** Cloudflare account that owns the Zero Trust organization. */
accountId: string;
/** The Zero Trust team domain, e.g. `acme.cloudflareaccess.com`. */
authDomain: string;
/** Display name of the organization. */
name: string;
/** Default Access application session duration. */
sessionDuration: string | undefined;
/** WARP-as-IdP toggle observed on Cloudflare. */
allowAuthenticateViaWarp: boolean | undefined;
/** Dashboard read-only lock observed on Cloudflare. */
isUiReadOnly: boolean | undefined;
/** Skip-IdP-picker toggle observed on Cloudflare. */
autoRedirectToIdentity: boolean | undefined;
/** Free-form note explaining the `isUiReadOnly` setting. */
uiReadOnlyToggleReason: string | undefined;
/** User-seat inactivity expiration observed on Cloudflare. */
userSeatExpirationInactiveTime: string | undefined;
/** WARP authentication session duration observed on Cloudflare. */
warpAuthSessionDuration: string | undefined;
/** Login-page branding observed on Cloudflare. */
loginDesign: Organization.LoginDesign | undefined;
/** Custom-pages pointers observed on Cloudflare. */
customPages: Organization.CustomPages | undefined;
/** Whether unmatched requests are denied. */
denyUnmatchedRequests: boolean | undefined;
/** Zones exempted from `denyUnmatchedRequests`. */
denyUnmatchedRequestsExemptedZoneNames: string[] | undefined;
/** Whether end users are blocked from creating applications. */
disableEndUserAppCreation: boolean | undefined;
/** Organization-wide MFA settings observed on Cloudflare. */
mfaConfig: Organization.MfaConfig | undefined;
/** PIV and SSH key requirements observed on Cloudflare. */
mfaPivKeyRequirements: Organization.MfaPivKeyRequirements | undefined;
/** Whether every application requires MFA. */
mfaRequiredForAllApps: boolean | undefined;
/** Inactive service token handling observed on Cloudflare. */
serviceTokenInactivity: Organization.ServiceTokenInactivity | undefined;
/** Whether service-token requests are evaluated only against service-token policies. */
strictServiceTokenAuth: boolean | undefined;
/** Whether WARP authentication answers non-browser requests with `401`. */
warpAuthNonBrowser401: boolean | undefined;
},
never,
Providers
>;
/**
* Account-level Cloudflare Zero Trust organization settings — the team
* domain, login branding, session lifetimes, MFA, WARP authentication, etc.
*
* Wraps `PUT /accounts/{account_id}/access/organizations`.
* @remarks
* **This resource is a singleton.** Every Cloudflare account owns exactly one
* Access Organization; you cannot create a second one and you cannot delete
* the existing one without deleting the entire Cloudflare account. As a
* result:
*
* - The `reconcile` lifecycle always **adopts** the existing organization on
* first deploy rather than failing on conflict.
* - The `delete` lifecycle is a **no-op** that logs a warning. Removing the
* resource from your stack leaves the Cloudflare-side settings untouched.
* - Every deploy converges the whole organization on the declared props. A
* setting you don't declare goes back to Cloudflare's default, including
* one changed in the dashboard — declare MFA, `denyUnmatchedRequests` and
* the rest here to keep them.
*
* ### Configuring the organization
* **Example:** Adopt and brand the organization
* ```typescript
* const org = yield* Cloudflare.Access.Organization("Org", {
* authDomain: "acme.cloudflareaccess.com",
* name: "Acme",
* sessionDuration: "24h",
* allowAuthenticateViaWarp: true,
* loginDesign: {
* logoPath: "https://acme.example/logo.png",
* backgroundColor: "#111111",
* textColor: "#ffffff",
* },
* });
* ```
*
* ### Branding the login page
* Keep the branding assets in your repo. An assets-only Worker serves the
* logo, and a custom page takes its HTML from a file.
*
* **Example:** Logo and block page from files
* ```typescript
* const fs = yield* FileSystem.FileSystem;
* const branding = yield* Cloudflare.Worker("Branding", {
* assets: "./branding/public", // logo.svg
* });
* const forbidden = yield* Cloudflare.Access.CustomPage("Forbidden", {
* type: "forbidden",
* customHtml: yield* fs.readFileString("./branding/forbidden.html"),
* });
* const org = yield* Cloudflare.Access.Organization("Org", {
* authDomain: "acme.cloudflareaccess.com",
* loginDesign: {
* logoPath: Output.interpolate`${branding.url}/logo.svg`,
* backgroundColor: "#111111",
* textColor: "#ffffff",
* footerText: "Acme employees only",
* },
* customPages: { forbidden: forbidden.customPageId },
* });
* ```
*
* ### Securing the organization
* **Example:** Require MFA and deny unmatched requests
* ```typescript
* const org = yield* Cloudflare.Access.Organization("Org", {
* authDomain: "acme.cloudflareaccess.com",
* mfaRequiredForAllApps: true,
* mfaConfig: {
* allowedAuthenticators: ["totp", "security_key"],
* sessionDuration: "12h",
* },
* denyUnmatchedRequests: true,
* denyUnmatchedRequestsExemptedZoneNames: ["public.example.com"],
* strictServiceTokenAuth: true,
* serviceTokenInactivity: {
* enabled: true,
* action: "disable",
* inactivityThresholdDays: 90,
* },
* });
* ```
*
* @resource
* @product Access
* @category Cloudflare One (Zero Trust)
*/
export const Organization = Resource<Organization>("Cloudflare.Access.Organization", {
aliases: ["Cloudflare.AccessOrganization"],
});
/**
* Cloudflare returned `OrganizationAlreadyExists` on create, but the
* organization could not be read back afterwards.
*/
export class OrganizationNotObserved extends Data.TaggedError("OrganizationNotObserved")<{
readonly accountId: string;
}> {}
export const OrganizationProvider = () =>
Provider.succeed(Organization, {
nuke: { singleton: true },
stables: ["accountId", "authDomain"],
reconcile: Effect.fn(function* ({ news }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const desiredName = news.name ?? news.authDomain;
// The body is the complete desired state: every setting the props
// don't declare converges to its default.
// Observe — singleton lookup. The org always exists for any
// account that has enabled Zero Trust; only a brand-new account
// returns "missing".
const observed = yield* observe();
const settings = settingsBody(news, desiredName, observed);
// Ensure — create on a fresh account. If a race or out-of-band
// setup created it between the observe and create call, fall
// back to update.
if (!observed) {
const { customPages: _, ...createSettings } = settings;
yield* zeroTrust.createOrganizationForAccount({ accountId, ...createSettings }).pipe(
Effect.catchTag("OrganizationAlreadyExists", () =>
Effect.gen(function* () {
const existing = yield* observe();
if (existing) return existing;
return yield* new OrganizationNotObserved({ accountId });
}),
),
);
}
// Sync — always push the full desired state so any drift converges
// in one call. Cheap and idempotent.
const updated = yield* zeroTrust.updateOrganizationForAccount({ accountId, ...settings });
return toAttrs(accountId, updated, news.authDomain, desiredName);
}),
delete: Effect.fn(function* () {
yield* Effect.logWarning(
"Organization.delete is a no-op — the Cloudflare Access Organization is a singleton tied to the account and cannot be deleted without deleting the Cloudflare account itself.",
);
}),
read: Effect.fn(function* ({ olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* observe();
if (!observed) return undefined;
return toAttrs(
accountId,
observed,
olds?.authDomain ?? observed.authDomain ?? "",
olds?.name ?? observed.name ?? olds?.authDomain ?? "",
);
}),
// Account singleton: every Cloudflare account owns exactly one Access
// Organization and there is no enumeration API. Read the single org via
// the same `observe` path `read` uses and return the one-element array
// (or `[]` when the account has never enabled Zero Trust). `observe`
// already swallows the typed `OrganizationNotFound` error.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* observe();
if (!observed) return [];
return [
toAttrs(
accountId,
observed,
observed.authDomain ?? "",
observed.name ?? observed.authDomain ?? "",
),
];
}),
});
const observe = Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
return yield* zeroTrust.listOrganizationsForAccount({ accountId }).pipe(
Effect.map((org) => {
// listOrganizationsForAccount returns a single object (the
// singleton org) under `result`; an account that has not yet
// enabled Zero Trust returns a sparse object with no
// `authDomain`. Treat that as "missing".
const typed = org;
return typed && typed.authDomain ? typed : undefined;
}),
Effect.catchTag("OrganizationNotFound", () => Effect.undefined),
);
});
/**
* The complete desired organization as an update body. Cloudflare resets
* most omitted settings but keeps some (`disableEndUserAppCreation`,
* `serviceTokenInactivity`), so undeclared toggles are sent as their
* defaults rather than left out.
*/
const settingsBody = (
news: OrganizationProps,
name: string,
observed: zeroTrust.ListOrganizationsResponse | undefined,
) =>
stripUndefinedFields({
authDomain: news.authDomain,
name,
sessionDuration: news.sessionDuration,
allowAuthenticateViaWarp: news.allowAuthenticateViaWarp ?? false,
isUiReadOnly: news.isUiReadOnly ?? false,
autoRedirectToIdentity: news.autoRedirectToIdentity ?? false,
uiReadOnlyToggleReason: news.uiReadOnlyToggleReason,
userSeatExpirationInactiveTime: news.userSeatExpirationInactiveTime,
warpAuthSessionDuration: news.warpAuthSessionDuration,
loginDesign: news.loginDesign,
customPages: news.customPages,
denyUnmatchedRequests: news.denyUnmatchedRequests ?? false,
denyUnmatchedRequestsExemptedZoneNames: news.denyUnmatchedRequestsExemptedZoneNames ?? [],
disableEndUserAppCreation: news.disableEndUserAppCreation ?? false,
mfaConfig: news.mfaConfig,
mfaPivKeyRequirements: news.mfaPivKeyRequirements,
mfaRequiredForAllApps: news.mfaRequiredForAllApps ?? false,
serviceTokenInactivity:
news.serviceTokenInactivity ??
disabledServiceTokenInactivity(observed?.serviceTokenInactivity),
strictServiceTokenAuth: news.strictServiceTokenAuth ?? false,
warp_auth_non_browser_401: news.warpAuthNonBrowser401 ?? false,
});
/**
* Turns off an enabled service-token inactivity policy the props don't
* declare. Cloudflare only accepts the full shape, so the observed action and
* threshold are sent back with `enabled: false`.
*/
const disabledServiceTokenInactivity = (
observed: zeroTrust.ListOrganizationsResponse["serviceTokenInactivity"],
): Organization.ServiceTokenInactivity | undefined =>
observed?.enabled && observed.action && observed.inactivityThresholdDays != null
? {
enabled: false,
action: observed.action as Organization.ServiceTokenInactivity["action"],
inactivityThresholdDays: observed.inactivityThresholdDays,
}
: undefined;
/**
* Drops `null` fields from an observed nested setting, so the attribute has
* the same shape as the prop.
*/
const observedSetting = <T>(value: object | null | undefined): T | undefined =>
value == null ? undefined : (stripNullFields(value) as T);
const toAttrs = (
accountId: string,
org: zeroTrust.ListOrganizationsResponse,
fallbackAuthDomain: string,
fallbackName: string,
) => ({
accountId,
authDomain: org.authDomain ?? fallbackAuthDomain,
name: org.name ?? fallbackName,
sessionDuration: org.sessionDuration ?? undefined,
allowAuthenticateViaWarp: org.allowAuthenticateViaWarp ?? undefined,
isUiReadOnly: org.isUiReadOnly ?? undefined,
autoRedirectToIdentity: org.autoRedirectToIdentity ?? undefined,
uiReadOnlyToggleReason: org.uiReadOnlyToggleReason ?? undefined,
userSeatExpirationInactiveTime: org.userSeatExpirationInactiveTime ?? undefined,
warpAuthSessionDuration: org.warpAuthSessionDuration ?? undefined,
loginDesign: observedSetting<Organization.LoginDesign>(org.loginDesign),
customPages: observedSetting<Organization.CustomPages>(org.customPages),
denyUnmatchedRequests: org.denyUnmatchedRequests ?? undefined,
denyUnmatchedRequestsExemptedZoneNames: org.denyUnmatchedRequestsExemptedZoneNames
? [...org.denyUnmatchedRequestsExemptedZoneNames]
: undefined,
disableEndUserAppCreation: org.disableEndUserAppCreation ?? undefined,
mfaConfig: observedSetting<Organization.MfaConfig>(org.mfaConfig),
mfaPivKeyRequirements: observedSetting<Organization.MfaPivKeyRequirements>(
org.mfaPivKeyRequirements,
),
mfaRequiredForAllApps: org.mfaRequiredForAllApps ?? undefined,
serviceTokenInactivity: observedSetting<Organization.ServiceTokenInactivity>(
org.serviceTokenInactivity,
),
strictServiceTokenAuth: org.strictServiceTokenAuth ?? undefined,
warpAuthNonBrowser401: org.warp_auth_non_browser_401 ?? undefined,
});