import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { stripNullFields } from "alchemy/Util/data";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
export class PolicyUnexpectedResponse extends Data.TaggedError("PolicyUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
/**
* One arm of a Cloudflare Access policy rule discriminated union. A rule is a
* single-key object whose key selects the rule kind (`email`, `emailDomain`,
* `everyone`, `ip`, etc.) and whose value carries the rule's parameters.
*
* Re-exported from `@distilled.cloud/cloudflare/zero-trust`'s
* `CreateAccessPolicyRequest` so the full Cloudflare rule surface is available
* without re-declaring the union.
*/
export type PolicyRule = zeroTrust.CreateAccessPolicyRequest["include"][number];
/**
* One arm of the exclude-side rule union, and its require-side twin.
* Cloudflare's spec types the exclude/require rule lists separately from
* include — a few rule kinds (e.g. the GitHub-organization rule) carry the
* raw wire shape there — so these props use the SDK's own unions rather
* than reusing {@link PolicyRule}.
*/
export type PolicyExcludeRule = NonNullable<zeroTrust.CreateAccessPolicyRequest["exclude"]>[number];
export type PolicyRequireRule = NonNullable<zeroTrust.CreateAccessPolicyRequest["require"]>[number];
/**
* Scalar shorthand for rule kinds with a single parameter (and bare names
* for the parameter-less kinds) — expanded to Cloudflare's wire shape by
* the providers, so both spellings are equivalent:
*
* ```ts
* include: [{ emailDomain: "example.com" }] // { emailDomain: { domain: "example.com" } }
* include: [{ email: "sam@example.com" }] // { email: { email: "sam@example.com" } }
* include: ["everyone"] // { everyone: {} }
* require: [{ geo: "US" }] // { geo: { countryCode: "US" } }
* ```
*
* Multi-parameter kinds (`gsuite`, `okta`, `saml`, `oidc`, `azureAD`,
* `githubOrganization`, `externalEvaluation`, `authContext`) keep their
* wire shape — there is no scalar to collapse them to.
*/
export type PolicyRuleShorthand =
| "everyone"
| "certificate"
| "anyValidServiceToken"
| { email: string }
| { emailDomain: string }
| { emailList: string }
| { ip: string }
| { ipList: string }
| { group: string }
| { loginMethod: string }
| { serviceToken: string }
| { geo: string }
| { authMethod: string }
| { devicePosture: string }
| { commonName: string }
| { linkedAppToken: string }
| { userRiskScore: string }
| { cloudflareAccountMember: string };
/** A rule in either spelling: Cloudflare's wire shape or the scalar shorthand. */
export type PolicyRuleInput = PolicyRule | PolicyRuleShorthand;
export type PolicyExcludeRuleInput = PolicyExcludeRule | PolicyRuleShorthand;
export type PolicyRequireRuleInput = PolicyRequireRule | PolicyRuleShorthand;
/** Rule kind → its single parameter's (camelCase) member name. */
const SCALAR_RULE_PARAMS: Record<string, string> = {
email: "email",
emailDomain: "domain",
emailList: "id",
ip: "ip",
ipList: "id",
group: "id",
loginMethod: "id",
serviceToken: "tokenId",
geo: "countryCode",
authMethod: "authMethod",
devicePosture: "integrationUid",
commonName: "commonName",
linkedAppToken: "appUid",
userRiskScore: "userRiskScore",
cloudflareAccountMember: "accountId",
};
/**
* Expand the scalar shorthand to Cloudflare's wire shape; wire-shaped rules
* pass through untouched.
*/
export const normalizePolicyRule = <Rule>(rule: Rule | PolicyRuleShorthand): Rule => {
if (typeof rule === "string") {
// "everyone" -> { everyone: {} }
return { [rule]: {} } as Rule;
}
const keys = Object.keys(rule as object);
if (keys.length === 1) {
const kind = keys[0];
const value = (rule as Record<string, unknown>)[kind];
const param = SCALAR_RULE_PARAMS[kind];
if (param !== undefined && (value === null || typeof value !== "object")) {
return { [kind]: { [param]: value } } as Rule;
}
}
return rule as Rule;
};
export function normalizePolicyRules<Rule>(
rules: ReadonlyArray<Rule | PolicyRuleShorthand>,
): Rule[];
export function normalizePolicyRules<Rule>(
rules: ReadonlyArray<Rule | PolicyRuleShorthand> | undefined,
): Rule[] | undefined;
export function normalizePolicyRules<Rule>(
rules: ReadonlyArray<Rule | PolicyRuleShorthand> | undefined,
): Rule[] | undefined {
return rules === undefined ? undefined : rules.map((r) => normalizePolicyRule(r));
}
/**
* Decision Cloudflare Access takes when a request matches this policy.
*
* - `"allow"` — admit the user.
* - `"deny"` — block the user.
* - `"non_identity"` — admit without requiring an identity provider login.
* - `"bypass"` — skip Access entirely.
*/
export type PolicyDecision =
| "allow"
| "deny"
| "non_identity"
| "bypass"
// Match distilled's open-ended literal union so Cloudflare-returned values
// outside the closed set still narrow cleanly.
| (string & {});
export type PolicyApprovalGroup = NonNullable<
zeroTrust.CreateAccessPolicyRequest["approvalGroups"]
>[number];
export type PolicyConnectionRules = NonNullable<
zeroTrust.CreateAccessPolicyRequest["connectionRules"]
>;
export type PolicyMfaConfig = NonNullable<zeroTrust.CreateAccessPolicyRequest["mfaConfig"]>;
export type PolicyProps = {
/**
* Display name for the policy. Treated as a stable identifier so the
* provider can locate the policy by name during adoption / state recovery.
* If omitted, a unique name is generated from the stack/stage/logical id.
*
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* Decision the policy enforces when its rules match. Changing the decision
* triggers replacement.
*/
decision: PolicyDecision;
/**
* Rules combined with logical OR. A request must satisfy at least one
* include rule for the policy to match. Required and must be non-empty.
*/
include: PolicyRuleInput[];
/**
* Rules combined with logical NOT. A request matching any exclude rule is
* rejected by the policy even if it satisfied an include rule.
*/
exclude?: PolicyExcludeRuleInput[];
/**
* Rules combined with logical AND. A request must satisfy every require
* rule in addition to an include rule.
*/
require?: PolicyRequireRuleInput[];
/**
* Duration of issued session tokens. Format: `300ms`, `2h45m`, etc. When
* unset, applications using this policy fall back to their own configured
* session duration.
*/
sessionDuration?: string;
/**
* When true, Access requires an administrator to approve each authentication
* request before the user is admitted.
*
* @default false
*/
approvalRequired?: boolean;
/**
* When true, users must enter a justification when logging in to any
* application that consumes this policy.
*
* @default false
*/
purposeJustificationRequired?: boolean;
/**
* Custom message shown on the purpose justification screen.
*/
purposeJustificationPrompt?: string;
/**
* Administrators who can approve a temporary authentication request.
*/
approvalGroups?: PolicyApprovalGroup[];
/**
* Serve applications in an isolated browser for users matching this
* policy. Requires Clientless Web Isolation on the account.
*
* @default false
*/
isolationRequired?: boolean;
/**
* How users may connect to targets secured by an infrastructure
* application: allowed SSH usernames, RDP clipboard formats.
*
* @example
* ```ts
* connectionRules: { ssh: { usernames: ["root", "ubuntu"] } }
* ```
*/
connectionRules?: PolicyConnectionRules;
/**
* Multi-factor authentication settings enforced by this policy.
*/
mfaConfig?: PolicyMfaConfig;
/**
* Adopt an existing reusable policy with the same name when the engine has
* no prior state for this logical id.
*
* @default false
*/
adopt?: boolean;
};
export declare namespace Policy {
/**
* A single Access policy rule. See {@link PolicyRule} for the full
* discriminated union (email, emailDomain, everyone, ip, ipList, group,
* gsuite, githubOrganization, okta, azureAD, saml, oidc, deviceCheck via
* `devicePosture`, externalEvaluation, etc.).
*/
export type RuleGroup = PolicyRuleInput;
}
export type Policy = Resource<
"Cloudflare.Access.Policy",
PolicyProps,
{
/** UUID of the policy assigned by Cloudflare. */
policyId: string;
/** Display name reported by Cloudflare. */
name: string;
/** Decision the policy enforces. */
decision: string;
/** Cloudflare account that owns the policy. */
accountId: string;
/** Creation timestamp reported by Cloudflare, when available. */
createdAt: string | undefined;
/** Last-modified timestamp reported by Cloudflare, when available. */
updatedAt: string | undefined;
},
never,
Providers
>;
/**
* A reusable, account-scoped Cloudflare Access policy. Distinct from the
* inline policies attached directly to an `Application` — a reusable
* policy can be referenced by multiple applications by id.
*
* Optional fields you leave out keep their live value on update, so adopting
* a policy never drops rules you did not declare. Pass `[]` or `false` to
* clear one.
*
* ### Creating a Policy
* **Example:** Allow a single email domain
* ```typescript
* const policy = yield* Cloudflare.Access.Policy("AllowExampleDomain", {
* decision: "allow",
* include: [{ emailDomain: { domain: "example.com" } }],
* });
* ```
*
* **Example:** Allow everyone but require purpose justification
* ```typescript
* const policy = yield* Cloudflare.Access.Policy("OpenWithJustification", {
* decision: "allow",
* include: [{ everyone: {} }],
* purposeJustificationRequired: true,
* sessionDuration: "12h",
* });
* ```
*
* ### Combining rule groups
* **Example:** Include + exclude + require
* ```typescript
* const policy = yield* Cloudflare.Access.Policy("EngineersExceptInterns", {
* decision: "allow",
* include: [{ emailDomain: { domain: "example.com" } }],
* exclude: [{ email: { email: "intern@example.com" } }],
* require: [{ geo: { countryCode: "US" } }],
* });
* ```
*
* ### Infrastructure access
* **Example:** Allow SSH as specific Unix users
* ```typescript
* const policy = yield* Cloudflare.Access.Policy("SshOps", {
* decision: "allow",
* include: [{ emailDomain: "example.com" }],
* connectionRules: {
* ssh: { usernames: ["root", "ubuntu"], allowEmailAlias: true },
* },
* });
* ```
*
* @resource
* @product Access
* @category Cloudflare One (Zero Trust)
*/
export const Policy = Resource<Policy>("Cloudflare.Access.Policy", {
aliases: ["Cloudflare.AccessPolicy"],
});
export const PolicyProvider = () =>
Provider.succeed(Policy, {
stables: ["policyId", "accountId", "decision"],
diff: Effect.fn(function* ({ id, olds = {}, news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
if (!isResolved(news)) return undefined;
if ((output?.accountId ?? accountId) !== accountId) {
return { action: "replace" } as const;
}
const oldName = output?.name ?? (yield* createPolicyName(id, olds.name));
// Auto-generated names are engine-owned: the deployed name stays
// authoritative even if the generator would name this id differently
// today. Only an explicit user-provided name can force a replace.
const name = news.name ?? oldName;
if (name !== oldName) {
return { action: "replace" } as const;
}
const oldDecision = output?.decision ?? olds.decision;
if (oldDecision && oldDecision !== news.decision) {
return { action: "replace" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news = {} as PolicyProps, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
// Prefer the deployed name: regenerating would target a different
// resource if the generator's output for this id ever drifts.
const name = yield* createPolicyName(id, news.name ?? output?.name);
const acct = output?.accountId ?? accountId;
// Observe — prefer cached policyId, fall back to a name lookup so
// we recover from out-of-band deletes and partial state-persistence
// failures.
let observed: RawPolicy | undefined;
if (output?.policyId) {
observed = yield* zeroTrust
.getAccessPolicy({
accountId: acct,
policyId: output.policyId,
})
.pipe(Effect.orElseSucceed((): RawPolicy | undefined => undefined));
}
if (!observed) {
observed = yield* findPolicyByName(acct, name);
}
// Ensure — create the policy if missing. Tolerate a race where a
// parallel actor created the same-named policy by re-observing.
let ensured: ObservedPolicy;
if (!observed || !observed.id) {
ensured = yield* zeroTrust
.createAccessPolicy({ accountId: acct, ...policyBody(name, news) })
.pipe(
Effect.map(toObserved),
Effect.catch((err) =>
Effect.gen(function* () {
const existing = yield* findPolicyByName(acct, name);
if (existing && existing.id) return existing;
return yield* err;
}),
),
);
} else {
// Sync — Cloudflare PUTs the policy as a whole replacement and
// resets every field the body omits, so undeclared optional fields
// are sent back with their live value.
const prior = observed;
const updated = yield* zeroTrust.updateAccessPolicy({
accountId: acct,
policyId: prior.id!,
...withLiveFields(policyBody(name, news), prior),
});
ensured = {
id: updated.id ?? prior.id,
name: updated.name ?? prior.name,
decision: updated.decision ?? prior.decision,
createdAt: updated.createdAt ?? prior.createdAt,
updatedAt: updated.updatedAt ?? prior.updatedAt,
};
}
if (!ensured.id) {
return yield* new PolicyUnexpectedResponse({
message: "Policy: ensured policy missing id",
});
}
return {
policyId: ensured.id,
name: ensured.name ?? name,
decision: ensured.decision ?? news.decision,
accountId: acct,
createdAt: ensured.createdAt ?? undefined,
updatedAt: ensured.updatedAt ?? undefined,
};
}),
// Account-scoped collection (pattern (b)): enumerate every reusable
// Access policy in the ambient account, exhaustively paginated, and
// hydrate each into the exact `read` Attributes shape. Items missing the
// mandatory id are skipped (typed per-item drop).
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
return yield* zeroTrust.listAccessPolicies.pages({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).flatMap((raw) => {
const observed = toObserved(raw as RawPolicy);
if (!observed.id) return [];
return [
{
policyId: observed.id,
name: observed.name ?? "",
decision: observed.decision ?? "allow",
accountId,
createdAt: observed.createdAt ?? undefined,
updatedAt: observed.updatedAt ?? undefined,
},
];
}),
),
),
);
}),
delete: Effect.fn(function* ({ output }) {
yield* zeroTrust
.deleteAccessPolicy({
accountId: output.accountId,
policyId: output.policyId,
})
.pipe(Effect.catch((): Effect.Effect<void> => Effect.void));
}),
read: Effect.fn(function* ({ id, output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
if (output?.policyId) {
const direct = yield* zeroTrust
.getAccessPolicy({
accountId: acct,
policyId: output.policyId,
})
.pipe(Effect.orElseSucceed((): ObservedPolicy | undefined => undefined));
if (direct && direct.id) {
return {
policyId: direct.id,
name: direct.name ?? output.name,
decision: direct.decision ?? output.decision,
accountId: acct,
createdAt: direct.createdAt ?? output.createdAt,
updatedAt: direct.updatedAt ?? output.updatedAt,
};
}
}
const name = yield* createPolicyName(id, olds?.name ?? output?.name);
const existing = yield* findPolicyByName(acct, name);
if (!existing || !existing.id) return undefined;
return {
policyId: existing.id,
name: existing.name ?? name,
decision: existing.decision ?? olds?.decision ?? "allow",
accountId: acct,
createdAt: existing.createdAt ?? undefined,
updatedAt: existing.updatedAt ?? undefined,
};
}),
});
const policyBody = (name: string, news: PolicyProps) => ({
name,
decision: news.decision,
include: normalizePolicyRules(news.include),
exclude: normalizePolicyRules(news.exclude),
require: normalizePolicyRules(news.require),
sessionDuration: news.sessionDuration,
approvalRequired: news.approvalRequired,
approvalGroups: news.approvalGroups,
isolationRequired: news.isolationRequired,
purposeJustificationRequired: news.purposeJustificationRequired,
purposeJustificationPrompt: news.purposeJustificationPrompt,
connectionRules: news.connectionRules,
mfaConfig: news.mfaConfig,
});
// Optional fields a whole-replacement PUT would reset when omitted.
const PRESERVED_FIELDS = [
"exclude",
"require",
"sessionDuration",
"approvalRequired",
"approvalGroups",
"isolationRequired",
"purposeJustificationRequired",
"purposeJustificationPrompt",
"connectionRules",
"mfaConfig",
] as const;
const withLiveFields = (
body: ReturnType<typeof policyBody>,
live: RawPolicy,
): ReturnType<typeof policyBody> => ({
...body,
...Object.fromEntries(
PRESERVED_FIELDS.flatMap((key) =>
body[key] === undefined && live[key] != null ? [[key, stripNullFields(live[key])]] : [],
),
),
});
const createPolicyName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
if (name) return name;
return yield* createPhysicalName({ id });
});
const findPolicyByName = (acct: string, name: string) =>
zeroTrust.listAccessPolicies.items({ accountId: acct }).pipe(
Stream.filter((p) => p.name === name),
Stream.runHead,
Effect.map(Option.getOrUndefined),
Effect.orElseSucceed(() => undefined),
);
type ObservedPolicy = {
id?: string | null;
name?: string | null;
decision?: PolicyDecision | null;
createdAt?: string | null;
updatedAt?: string | null;
};
// Distilled response shapes (Get / List / Create / Update) all carry the same
// set of fields we care about, but typed wider than `ObservedPolicy`. Narrow
// at the API boundary so the rest of the reconciler stays in our shape.
type RawPolicy = {
id?: string | null;
name?: string | null;
decision?: string | null;
createdAt?: string | null;
updatedAt?: string | null;
} & { [K in (typeof PRESERVED_FIELDS)[number]]?: unknown };
const toObserved = (r: RawPolicy): ObservedPolicy => ({
id: r.id,
name: r.name,
decision: r.decision ?? null,
createdAt: r.createdAt,
updatedAt: r.updatedAt,
});