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

main
ts 311 lines 11.5 KB
Raw
1 import * as securityTxt from "@distilled.cloud/cloudflare/security-txt";
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 { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
8 import type { Providers } from "../Providers.ts";
9 import { listAllZones } from "../Zone/lookup.ts";
10
11 const TypeId = "Cloudflare.SecurityTxt.SecurityTxt" as const;
12 type TypeId = typeof TypeId;
13
14 export type Props = {
15 /**
16 * Zone the security.txt file belongs to. Stable — changing the zone
17 * triggers a replacement (the old zone's security.txt is deleted and a
18 * new one is created on the new zone).
19 */
20 zoneId: string;
21 /**
22 * Whether the security.txt file is served at
23 * `/.well-known/security.txt` on the zone. Mutable.
24 *
25 * @default true
26 */
27 enabled?: boolean;
28 /**
29 * Contact channels for security researchers — `mailto:` addresses,
30 * `tel:` numbers, or HTTPS URLs (RFC 9116 `Contact` field). Required —
31 * Cloudflare rejects a security.txt without it. Mutable.
32 */
33 contact: string[];
34 /**
35 * RFC 3339 timestamp after which the file's content should be
36 * considered stale (RFC 9116 `Expires` field), e.g.
37 * `2027-01-01T00:00:00Z`. Required — Cloudflare rejects a security.txt
38 * without it. Mutable.
39 */
40 expires: string;
41 /**
42 * URLs of pages crediting security researchers (RFC 9116
43 * `Acknowledgments` field). Mutable.
44 */
45 acknowledgments?: string[];
46 /**
47 * Canonical URLs where this security.txt file is served (RFC 9116
48 * `Canonical` field). Mutable.
49 */
50 canonical?: string[];
51 /**
52 * URLs of encryption keys for secure communication (RFC 9116
53 * `Encryption` field). Mutable.
54 */
55 encryption?: string[];
56 /**
57 * URLs of security-related job openings (RFC 9116 `Hiring` field).
58 * Mutable.
59 */
60 hiring?: string[];
61 /**
62 * URLs of the vulnerability disclosure policy (RFC 9116 `Policy`
63 * field). Mutable.
64 */
65 policy?: string[];
66 /**
67 * Comma-separated list of language tags the security team prefers
68 * (RFC 9116 `Preferred-Languages` field), e.g. `"en, es"`. Mutable.
69 */
70 preferredLanguages?: string;
71 };
72
73 export type Attributes = {
74 /** Zone the security.txt file belongs to. */
75 zoneId: string;
76 /** Whether the file is served at `/.well-known/security.txt`. */
77 enabled: boolean;
78 /** Contact channels for security researchers. */
79 contact: string[];
80 /** RFC 3339 timestamp after which the file is considered stale. */
81 expires: string;
82 /** URLs of pages crediting security researchers. */
83 acknowledgments: string[] | undefined;
84 /** Canonical URLs where this security.txt file is served. */
85 canonical: string[] | undefined;
86 /** URLs of encryption keys for secure communication. */
87 encryption: string[] | undefined;
88 /** URLs of security-related job openings. */
89 hiring: string[] | undefined;
90 /** URLs of the vulnerability disclosure policy. */
91 policy: string[] | undefined;
92 /** Comma-separated list of preferred language tags. */
93 preferredLanguages: string | undefined;
94 };
95
96 export type SecurityTxt = Resource<TypeId, Props, Attributes, never, Providers>;
97
98 /**
99 * A zone's `security.txt` file
100 * (`/zones/{zone_id}/security-center/securitytxt`), served by the
101 * Cloudflare edge at `https://<zone>/.well-known/security.txt` per
102 * RFC 9116 so security researchers know how to report vulnerabilities.
103 *
104 * The file is a singleton per zone with true create/delete semantics:
105 * creating the resource publishes the file, updating it is a full
106 * replace of every field, and destroying it removes the file from the
107 * zone entirely.
108 *
109 * Cloudflare requires the RFC 9116 mandatory fields — `contact` and
110 * `expires` — on every write.
111 * ### Publishing a security.txt
112 * **Example:** Minimal security.txt
113 * ```typescript
114 * const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });
115 *
116 * yield* Cloudflare.SecurityTxt.SecurityTxt("SecurityTxt", {
117 * zoneId: zone.zoneId,
118 * contact: ["mailto:security@example.com"],
119 * expires: "2027-01-01T00:00:00Z",
120 * });
121 * ```
122 *
123 * **Example:** Full security.txt with policy and acknowledgments
124 * ```typescript
125 * yield* Cloudflare.SecurityTxt.SecurityTxt("SecurityTxt", {
126 * zoneId: zone.zoneId,
127 * contact: ["mailto:security@example.com", "https://example.com/report"],
128 * expires: "2027-01-01T00:00:00Z",
129 * policy: ["https://example.com/security-policy"],
130 * acknowledgments: ["https://example.com/hall-of-fame"],
131 * encryption: ["https://example.com/pgp-key.txt"],
132 * preferredLanguages: "en, es",
133 * });
134 * ```
135 *
136 * ### Pausing without deleting
137 * **Example:** Keep the configuration but stop serving the file
138 * ```typescript
139 * yield* Cloudflare.SecurityTxt.SecurityTxt("SecurityTxt", {
140 * zoneId: zone.zoneId,
141 * enabled: false,
142 * contact: ["mailto:security@example.com"],
143 * expires: "2027-01-01T00:00:00Z",
144 * });
145 * ```
146 *
147 * @see https://developers.cloudflare.com/security-center/infrastructure/security-file/
148 *
149 * @resource
150 * @product Security.txt
151 * @category Application Security
152 */
153 export const SecurityTxt = Resource<SecurityTxt>(TypeId, {
154 aliases: ["Cloudflare.SecurityTxt"],
155 });
156
157 /**
158 * Returns true if the given value is a SecurityTxt resource.
159 */
160 export const isSecurityTxt = (value: unknown): value is SecurityTxt =>
161 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
162
163 export const SecurityTxtProvider = () =>
164 Provider.succeed(SecurityTxt, {
165 stables: ["zoneId"],
166
167 list: Effect.fn(function* () {
168 const { accountId } = yield* yield* CloudflareEnvironment;
169 // There is no account-wide API for this per-zone singleton, and the
170 // file is only present on zones that have explicitly configured it —
171 // enumerate every zone, read its security.txt, and emit one entry per
172 // configured zone (an empty-string sentinel means unconfigured, which
173 // `read` treats as absent, so skip it).
174 const allZones = yield* listAllZones(accountId);
175 const rows = yield* Effect.forEach(
176 allZones.map((zone) => zone.id),
177 (zoneId) =>
178 securityTxt
179 .getSecurityTxt({ zoneId })
180 .pipe(
181 Effect.map((observed) =>
182 typeof observed === "string" ? undefined : toAttributes(zoneId, observed),
183 ),
184 ),
185 { concurrency: 10 },
186 );
187 return rows.filter((row): row is Attributes => row !== undefined);
188 }),
189
190 diff: Effect.fn(function* ({ olds = {}, news, output }) {
191 const o = olds as Props;
192 const n = news as Props;
193 // zoneId is Input<string>; compare only once both sides are concrete.
194 const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
195 if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) {
196 return { action: "replace" } as const;
197 }
198 return undefined;
199 }),
200
201 read: Effect.fn(function* ({ output, olds }) {
202 const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
203 if (!zoneId) return undefined;
204 const observed = yield* securityTxt.getSecurityTxt({ zoneId });
205 // An unconfigured zone returns an empty-string sentinel — absent.
206 if (typeof observed === "string") return undefined;
207 const attrs = toAttributes(zoneId, observed);
208 // The file is a zone singleton with no ownership markers. On a cold
209 // read (no prior output) an existing file was configured outside
210 // Alchemy — brand it `Unowned` so the engine refuses to take over
211 // unless `--adopt` is set.
212 if (output === undefined) return Unowned(attrs);
213 return attrs;
214 }),
215
216 reconcile: Effect.fn(function* ({ news }) {
217 // Inputs have been resolved to concrete strings by Plan.
218 const zoneId = news.zoneId as string;
219 const desired = desiredAttributes(zoneId, news);
220
221 // 1. Observe — read the live file (an empty-string sentinel means
222 // the zone has no security.txt yet).
223 const observed = yield* securityTxt.getSecurityTxt({ zoneId });
224
225 // 2. Sync — PUT is a full replace (a true upsert), so create and
226 // update are the same call. Skip the API entirely when the
227 // observed file already matches the desired one.
228 if (
229 typeof observed !== "string" &&
230 attributesEqual(toAttributes(zoneId, observed), desired)
231 ) {
232 return toAttributes(zoneId, observed);
233 }
234 yield* securityTxt.putSecurityTxt({
235 zoneId,
236 enabled: desired.enabled,
237 contact: desired.contact,
238 expires: desired.expires,
239 acknowledgments: desired.acknowledgments,
240 canonical: desired.canonical,
241 encryption: desired.encryption,
242 hiring: desired.hiring,
243 policy: desired.policy,
244 preferredLanguages: desired.preferredLanguages,
245 });
246
247 // 3. Return — re-read so attributes reflect what Cloudflare stored.
248 const final = yield* securityTxt.getSecurityTxt({ zoneId });
249 return typeof final === "string" ? desired : toAttributes(zoneId, final);
250 }),
251
252 delete: Effect.fn(function* ({ output }) {
253 // DELETE on an already-absent security.txt returns success, so the
254 // operation is naturally idempotent.
255 yield* securityTxt.deleteSecurityTxt({ zoneId: output.zoneId });
256 }),
257 });
258
259 /** Normalize the desired state from input props into the Attributes shape. */
260 const desiredAttributes = (zoneId: string, news: Props): Attributes => ({
261 zoneId,
262 enabled: news.enabled ?? true,
263 contact: [...news.contact],
264 expires: news.expires,
265 acknowledgments: nonEmpty(news.acknowledgments),
266 canonical: nonEmpty(news.canonical),
267 encryption: nonEmpty(news.encryption),
268 hiring: nonEmpty(news.hiring),
269 policy: nonEmpty(news.policy),
270 preferredLanguages: news.preferredLanguages === "" ? undefined : news.preferredLanguages,
271 });
272
273 /** Normalize the observed GET response into the Attributes shape. */
274 const toAttributes = (
275 zoneId: string,
276 observed: Exclude<securityTxt.GetSecurityTxtResponse, string>,
277 ): Attributes => ({
278 zoneId,
279 enabled: observed.enabled ?? false,
280 contact: [...(observed.contact ?? [])],
281 expires: observed.expires ?? "",
282 acknowledgments: nonEmpty(observed.acknowledgments),
283 canonical: nonEmpty(observed.canonical),
284 encryption: nonEmpty(observed.encryption),
285 hiring: nonEmpty(observed.hiring),
286 // Cloudflare echoes an empty string for an unset Preferred-Languages.
287 policy: nonEmpty(observed.policy),
288 preferredLanguages:
289 observed.preferredLanguages === "" ? undefined : (observed.preferredLanguages ?? undefined),
290 });
291
292 /** Null/empty list fields normalize to `undefined` (not configured). */
293 const nonEmpty = (values: readonly string[] | null | undefined): string[] | undefined =>
294 values === null || values === undefined || values.length === 0 ? undefined : [...values];
295
296 const listEquals = (a: string[] | undefined, b: string[] | undefined): boolean => {
297 if (a === undefined || b === undefined) return a === b;
298 return a.length === b.length && a.every((v, i) => v === b[i]);
299 };
300
301 const attributesEqual = (a: Attributes, b: Attributes): boolean =>
302 a.zoneId === b.zoneId &&
303 a.enabled === b.enabled &&
304 a.expires === b.expires &&
305 a.preferredLanguages === b.preferredLanguages &&
306 listEquals(a.contact, b.contact) &&
307 listEquals(a.acknowledgments, b.acknowledgments) &&
308 listEquals(a.canonical, b.canonical) &&
309 listEquals(a.encryption, b.encryption) &&
310 listEquals(a.hiring, b.hiring) &&
311 listEquals(a.policy, b.policy);