The best way to control Claude Code, Codex and more from any computer or phone

main
ts 316 lines 11 KB
Raw
1 import * as emailSecurity from "@distilled.cloud/cloudflare/email-security";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Effect from "effect/Effect";
6 import * as Predicate from "effect/Predicate";
7 import * as Stream from "effect/Stream";
8 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
9 import type { Providers } from "../Providers.ts";
10
11 const EmailSecurityAllowPolicyTypeId = "Cloudflare.Email.AllowPolicy" as const;
12 type EmailSecurityAllowPolicyTypeId = typeof EmailSecurityAllowPolicyTypeId;
13
14 /**
15 * Type of pattern matching for Email Security sender/recipient patterns.
16 * `UNKNOWN` is deprecated and rejected on create/update, so it is not
17 * accepted as an input.
18 */
19 export type PatternType = "EMAIL" | "DOMAIN" | "IP";
20
21 export interface AllowPolicyProps {
22 /**
23 * The email address, domain, IP, or regular expression to match.
24 * The pattern is the policy's identity for cold-state recovery — a
25 * pre-existing policy with the same pattern is reported as unowned and
26 * only taken over when adoption is enabled.
27 */
28 pattern: string;
29 /**
30 * Type of pattern matching.
31 */
32 patternType: PatternType;
33 /**
34 * Whether `pattern` is a regular expression.
35 * @default false
36 */
37 isRegex?: boolean;
38 /**
39 * Messages from this sender are exempted from Spam, Spoof, and Bulk
40 * dispositions. Does not exempt Malicious or Suspicious dispositions.
41 * @default false
42 */
43 isAcceptableSender?: boolean;
44 /**
45 * Messages to this recipient bypass all detections.
46 * @default false
47 */
48 isExemptRecipient?: boolean;
49 /**
50 * Messages from this sender bypass all detections and link following.
51 * @default false
52 */
53 isTrustedSender?: boolean;
54 /**
55 * Enforce DMARC, SPF, or DKIM authentication — when on, Email Security
56 * only honors the policy when the message passes authentication.
57 * @default true
58 */
59 verifySender?: boolean;
60 /**
61 * Free-form notes about the policy.
62 */
63 comments?: string;
64 }
65
66 export interface AllowPolicyAttributes {
67 /** Cloudflare-assigned allow policy identifier. */
68 policyId: string;
69 /** The account the policy belongs to. */
70 accountId: string;
71 /** The matched pattern. */
72 pattern: string;
73 /** Type of pattern matching. */
74 patternType: PatternType;
75 /** Whether the pattern is a regular expression. */
76 isRegex: boolean;
77 /** Whether the sender is exempted from Spam/Spoof/Bulk dispositions. */
78 isAcceptableSender: boolean;
79 /** Whether messages to the recipient bypass all detections. */
80 isExemptRecipient: boolean;
81 /** Whether the sender bypasses all detections and link following. */
82 isTrustedSender: boolean;
83 /** Whether sender authentication (SPF/DKIM/DMARC) is enforced. */
84 verifySender: boolean;
85 /** Free-form notes about the policy, if set. */
86 comments: string | undefined;
87 /** ISO8601 creation timestamp. */
88 createdAt: string;
89 /** ISO8601 last-modified timestamp, if the policy has been modified. */
90 modifiedAt: string | undefined;
91 }
92
93 export type AllowPolicy = Resource<
94 EmailSecurityAllowPolicyTypeId,
95 AllowPolicyProps,
96 AllowPolicyAttributes,
97 never,
98 Providers
99 >;
100
101 /**
102 * A Cloudflare Email Security (Area 1) allow policy — exempts messages
103 * matching a sender/recipient pattern from detections.
104 *
105 * All fields are mutable in place. Requires the Email Security enterprise
106 * add-on; accounts without the entitlement receive the typed
107 * `EmailSecurityNotEntitled` error.
108 * ### Creating an Allow Policy
109 * **Example:** Acceptable sender by email address
110 * ```typescript
111 * yield* Cloudflare.Email.AllowPolicy("NewsletterSender", {
112 * pattern: "news@partner.example.com",
113 * patternType: "EMAIL",
114 * isAcceptableSender: true,
115 * });
116 * ```
117 *
118 * **Example:** Trusted sender domain (bypasses all detections)
119 * ```typescript
120 * yield* Cloudflare.Email.AllowPolicy("TrustedPartner", {
121 * pattern: "partner.example.com",
122 * patternType: "DOMAIN",
123 * isTrustedSender: true,
124 * comments: "contractually trusted partner",
125 * });
126 * ```
127 *
128 * **Example:** Exempt recipient
129 * ```typescript
130 * // Messages delivered to the abuse mailbox must never be filtered.
131 * yield* Cloudflare.Email.AllowPolicy("AbuseMailbox", {
132 * pattern: "abuse@example.com",
133 * patternType: "EMAIL",
134 * isExemptRecipient: true,
135 * verifySender: false,
136 * });
137 * ```
138 *
139 * @see https://developers.cloudflare.com/cloudflare-one/email-security/
140 *
141 * @resource
142 * @product Email Security
143 * @category Email
144 */
145 export const AllowPolicy = Resource<AllowPolicy>(EmailSecurityAllowPolicyTypeId, {
146 aliases: ["Cloudflare.EmailSecurity.AllowPolicy"],
147 });
148
149 /**
150 * Returns true if the given value is an AllowPolicy resource.
151 */
152 export const isAllowPolicy = (value: unknown): value is AllowPolicy =>
153 Predicate.hasProperty(value, "Type") && value.Type === EmailSecurityAllowPolicyTypeId;
154
155 export const AllowPolicyProvider = () =>
156 Provider.succeed(AllowPolicy, {
157 stables: ["policyId", "accountId", "createdAt"],
158
159 list: Effect.fn(function* () {
160 const { accountId } = yield* yield* CloudflareEnvironment;
161 return yield* emailSecurity.listSettingAllowPolicies.pages({ accountId }).pipe(
162 Stream.runCollect,
163 Effect.map((chunk) =>
164 Array.from(chunk).flatMap((page) =>
165 (page.result ?? []).map((policy) => toAttributes(policy, accountId)),
166 ),
167 ),
168 // Email Security is a paid add-on gated by both account
169 // entitlement and token scope: an unentitled account answers
170 // `EmailSecurityNotEntitled`, while a credential lacking the
171 // Email Security scope (e.g. Cloudflare OAuth) answers a bare
172 // `Forbidden`. Neither can enumerate, so both mean "none
173 // visible" — matching `Domain.list()`. Returning `[]` is the
174 // safe direction for the callers of `list` (orphan detection
175 // never deletes what it cannot see).
176 Effect.catchTag(["EmailSecurityNotEntitled", "Forbidden"], () =>
177 Effect.succeed([] as AllowPolicyAttributes[]),
178 ),
179 );
180 }),
181
182 read: Effect.fn(function* ({ output, olds }) {
183 const { accountId } = yield* yield* CloudflareEnvironment;
184 const acct = output?.accountId ?? accountId;
185
186 // Owned path: refresh by the persisted policy id.
187 if (output?.policyId) {
188 const observed = yield* getPolicy(acct, output.policyId);
189 if (observed) return toAttributes(observed, acct);
190 }
191
192 // Cold lookup: recover by pattern. Allow policies carry no ownership
193 // markers, so a match is reported as `Unowned` and only taken over
194 // when adoption is enabled.
195 const pattern = output?.pattern ?? olds?.pattern;
196 if (pattern !== undefined) {
197 const observed = yield* findByPattern(acct, pattern);
198 if (observed) return Unowned(toAttributes(observed, acct));
199 }
200 return undefined;
201 }),
202
203 reconcile: Effect.fn(function* ({ news, output }) {
204 const { accountId } = yield* yield* CloudflareEnvironment;
205 const desired = withDefaults(news);
206
207 // 1. Observe — the id on `output` is a hint, not a guarantee; a
208 // missing policy falls through to the pattern scan and create.
209 let observed = output?.policyId ? yield* getPolicy(accountId, output.policyId) : undefined;
210 if (!observed) {
211 observed = yield* findByPattern(accountId, news.pattern);
212 }
213
214 // 2. Ensure — create when missing.
215 if (!observed) {
216 const created = yield* emailSecurity.createSettingAllowPolicy({
217 accountId,
218 ...desired,
219 });
220 return toAttributes(created, accountId);
221 }
222
223 // 3. Sync — diff observed cloud state against desired and patch only
224 // on a delta.
225 const dirty =
226 (observed.pattern ?? "") !== desired.pattern ||
227 (observed.patternType ?? "") !== desired.patternType ||
228 (observed.isRegex ?? false) !== desired.isRegex ||
229 (observed.isAcceptableSender ?? false) !== desired.isAcceptableSender ||
230 (observed.isExemptRecipient ?? false) !== desired.isExemptRecipient ||
231 (observed.isTrustedSender ?? false) !== desired.isTrustedSender ||
232 (observed.verifySender ?? false) !== desired.verifySender ||
233 (news.comments !== undefined && (observed.comments ?? "") !== news.comments);
234 if (!dirty) {
235 return toAttributes(observed, accountId);
236 }
237
238 const patched = yield* emailSecurity.patchSettingAllowPolicy({
239 accountId,
240 policyId: observed.id,
241 ...desired,
242 });
243 return toAttributes(patched, accountId);
244 }),
245
246 delete: Effect.fn(function* ({ output }) {
247 yield* emailSecurity
248 .deleteSettingAllowPolicy({
249 accountId: output.accountId,
250 policyId: output.policyId,
251 })
252 .pipe(Effect.catchTag("AllowPolicyNotFound", () => Effect.void));
253 }),
254 });
255
256 type ObservedAllowPolicy = emailSecurity.GetSettingAllowPolicyResponse;
257
258 /**
259 * Read an allow policy by id, mapping "gone" (`AllowPolicyNotFound`,
260 * HTTP 404) to `undefined`.
261 */
262 const getPolicy = (accountId: string, policyId: string) =>
263 emailSecurity.getSettingAllowPolicy({ accountId, policyId }).pipe(
264 Effect.map((policy): ObservedAllowPolicy | undefined => policy),
265 Effect.catchTag("AllowPolicyNotFound", () => Effect.undefined),
266 );
267
268 /**
269 * Find an allow policy by exact pattern. The `pattern` query filter is a
270 * server-side hint; the exact match is re-checked client-side. Picks the
271 * oldest match for determinism.
272 */
273 const findByPattern = (accountId: string, pattern: string) =>
274 emailSecurity.listSettingAllowPolicies.items({ accountId, pattern }).pipe(
275 Stream.runCollect,
276 Effect.map((chunk) =>
277 Array.from(chunk)
278 .filter((p) => p.pattern === pattern)
279 .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
280 .at(0),
281 ),
282 );
283
284 const withDefaults = (news: AllowPolicyProps) => ({
285 pattern: news.pattern,
286 patternType: news.patternType,
287 isRegex: news.isRegex ?? false,
288 isAcceptableSender: news.isAcceptableSender ?? false,
289 isExemptRecipient: news.isExemptRecipient ?? false,
290 isTrustedSender: news.isTrustedSender ?? false,
291 verifySender: news.verifySender ?? true,
292 comments: news.comments,
293 });
294
295 const toAttributes = (
296 policy:
297 | ObservedAllowPolicy
298 | emailSecurity.CreateSettingAllowPolicyResponse
299 | emailSecurity.PatchSettingAllowPolicyResponse,
300 accountId: string,
301 ): AllowPolicyAttributes => ({
302 policyId: policy.id,
303 accountId,
304 pattern: policy.pattern ?? "",
305 // UNKNOWN can only appear on legacy entries; new policies always echo
306 // the type they were created with.
307 patternType: (policy.patternType ?? "EMAIL") as PatternType,
308 isRegex: policy.isRegex ?? false,
309 isAcceptableSender: policy.isAcceptableSender ?? false,
310 isExemptRecipient: policy.isExemptRecipient ?? false,
311 isTrustedSender: policy.isTrustedSender ?? false,
312 verifySender: policy.verifySender ?? false,
313 comments: policy.comments ?? undefined,
314 createdAt: policy.createdAt,
315 modifiedAt: policy.modifiedAt ?? undefined,
316 });