Settings live in cloudflare.config.ts; drop compatibility.ts and the nodejs_compat flag; .env holds only the admin password

Author: ascorbic

.env.example

@@ -1,8 +1,3 @@
-# Sourced into the shell before `pnpm run deploy`: set -a; source .env; set +a
-# ADMIN_PASSWORD is written here by `pnpm admin:password`
-# LABELERS='[]'   # disable the default Bluesky moderation-service labeler
-# IMAGES_ENABLED=true
-# BLOB_MAX_SIZE=25mb
-# MODE=scoped
-# SCOPED_COLLECTIONS=app.example.*
-# JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+# Written by `pnpm admin:password`; read by `pnpm test:deployed` and handy for curl -u.
+# All other settings live in cloudflare.config.ts.
+ADMIN_PASSWORD=

AGENTS.md

@@ -54,10 +54,11 @@ is a bug.
 10. **Scoped-mode admission is a forward `getRecord` membership check**
     through the `Record` entrypoint; never build a reverse index of blob
     references. Open and scoped routes never coexist in one deployment.
-11. **Config values come from `loadConfig(env)`** in `src/config.ts`;
-    every setting has a default in `CONFIG_DEFAULTS` and a matching text
-    binding in `cloudflare.config.ts`. Adding a setting means touching
-    both plus the README table.
+11. **Settings are text bindings in `cloudflare.config.ts`** — that file
+    is the user-facing configuration. `loadConfig(env)` in `src/config.ts`
+    parses them, with `CONFIG_DEFAULTS` as the fallback for environments
+    that omit a binding (tests). Adding a setting means touching both plus
+    the README table. Nothing reads `process.env` at build time.
 
 ## Layout
 
@@ -74,19 +75,19 @@ src/labels.ts drain.ts    labeler config, queryLabels client, subscribeLabels dr
 src/jetstream.ts socket.ts  Jetstream drain; shared outbound-websocket reader
 src/store.ts              the only KV schema: cursors, drain status, record-level deny set
 src/config.ts             CONFIG_DEFAULTS and loadConfig
-cloudflare.config.ts      bindings, exports (per-entrypoint cache), cron; text bindings read process.env at deploy
+cloudflare.config.ts      settings (text bindings), exports (per-entrypoint cache), Images, KV, cron
 test/                     vitest inside workerd; test/integration/ runs on Node against the deployed Worker
 ```
 
 ## Commands
 
 - `pnpm dev` — local dev server (real PLC/PDS, local cache semantics)
 - `pnpm test` — workerd suite; `pnpm test:deployed` — HTTP suite against
-  production (`set -a; source .env; set +a` first; it purges, so run it
+  production (reads `ADMIN_PASSWORD` from `.env`; it purges, so run it
   sparingly — the purge rate limit bites after a few runs)
 - `pnpm check` / `pnpm fix` — oxfmt + oxlint + types
 - `pnpm run deploy` — `cf deploy` (plain `pnpm deploy` is a pnpm builtin).
-  Source `.env` first; it supplies the text-binding values.
+- `pnpm admin:password` — generate the admin secret, set it, save it to `.env`.
 
 ## Testing notes
 
@@ -130,8 +131,9 @@ test/                     vitest inside workerd; test/integration/ runs on Node
   `@cloudflare/config` — different unique symbols break type inference).
   `Env` is inferred from it; there is no generated vars list to regenerate.
 - The entrypoint import uses `with { type: "cf-worker" }`; keep that form.
-- `compatibility.ts` is shared with the vitest runtime so tests match
-  production.
+- The compatibility date appears in `cloudflare.config.ts` and
+  `vite.config.ts`; change both. `nodejs_compat` is implied by dates
+  ≥ 2026-08-04; do not add it back.
 - `vite` must stay aliased to `@voidzero-dev/vite-plus-core` and the
   `vitest` pin must match vite-plus (`pnpm exec vp toolchain`).
 - Formatting uses tabs; `.claude/docs/**` is excluded from formatting.

README.md

@@ -7,7 +7,7 @@ against the CID before serving, enforces a MIME allowlist by sniffing, and
 applies moderation from the ATProto labeler ecosystem by purging the cache.
 
 ```
-https://your-worker.example/did:plc:ewvi7nxzyoun6zhxrhs64oiz/bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku
+https://your-worker.example/did:plc:<did>/<cid>
 ```
 
 Cache hits are served by Cloudflare without running the Worker. A miss
@@ -28,8 +28,6 @@ git clone https://github.com/ascorbic/cumulus
 cd cumulus
 pnpm install
 pnpm cf auth login
-cp .env.example .env        # optional settings; see Configuration
-set -a; source .env; set +a
 pnpm run deploy
 ```
 
@@ -41,31 +39,32 @@ it with:
 pnpm admin:password
 ```
 
-This generates a random password, saves it to `.env` as `ADMIN_PASSWORD`
-(gitignored) and sets it as the Worker's secret. Run it again any time to
-rotate. Then `pnpm run deploy`.
+This generates a random password, sets it as the Worker's secret, and
+saves it to `.env` (gitignored) so you can find it later — that file holds
+nothing else. Run it again any time to rotate. Then `pnpm run deploy` again.
 
 `pnpm dev` runs it locally (real PLC directory and PDSes, local cache).
 
 ## Configuration
 
-Settings are read from the environment at deploy time and baked into the
-Worker as bindings, so `.env` is the configuration file. Quote JSON values.
+Settings are plain values in [`cloudflare.config.ts`](cloudflare.config.ts);
+edit them there and deploy. Everything except `ADMIN_PASSWORD` is
+checked in, so a clone reproduces the deployment.
 
 | Variable                 | Default                                                | Meaning                                                                                                                                                                 |
 | ------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ADMIN_PASSWORD`         | (secret, required)                                     | Basic-auth password for `/admin/*`.                                                                                                                                     |
+| `ADMIN_PASSWORD`         | secret                                                 | Basic-auth password for `/admin/*`; set with `pnpm admin:password`.                                                                                                     |
 | `BLOB_MAX_SIZE`          | `3mb`                                                  | Largest blob served. 3 MB keeps a miss under the Free plan's 10 ms CPU cap; set `25mb` on Workers Paid.                                                                 |
 | `BLOB_ALLOWED_MIMETYPES` | `image/jpeg,image/png,image/webp,image/avif,image/gif` | Sniffed types that may be served. SVG is excluded on purpose: it is a script container, and serving it from a shared origin is an XSS risk even with a restrictive CSP. |
 | `BLOB_FETCH_TIMEOUT`     | `30s`                                                  | PDS and directory request timeout.                                                                                                                                      |
 | `PLC_URL`                | `https://plc.directory`                                | DID PLC directory.                                                                                                                                                      |
 | `BROWSER_MAX_AGE`        | `3600`                                                 | `Cache-Control: max-age` sent to clients.                                                                                                                               |
 | `EDGE_MAX_AGE`           | `31536000`                                             | How long Cloudflare keeps an entry. Purge, not expiry, is the takedown mechanism.                                                                                       |
-| `LABELERS`               | Bluesky moderation service, `!takedown`                | JSON array of labelers to enforce: `\'[{"did":"did:plc:…","vals":["!takedown"]}]\'`. Set `\'[]\'` to enforce nothing.                                                   |
+| `LABELERS`               | Bluesky moderation service, `!takedown`                | JSON array of labelers to enforce: `[{"did":"did:plc:…","vals":["!takedown"]}]`. `[]` enforces nothing.                                                                 |
 | `LABELER_FAIL_OPEN`      | `true`                                                 | Serve when a labeler is unreachable (the verdict is not cached).                                                                                                        |
 | `POLICY_URL`             | none                                                   | External policy service: `GET {POLICY_URL}/{did}/{cid}` → 200 allow, 403 deny.                                                                                          |
 | `POLICY_FAIL_OPEN`       | `false`                                                | Serve when the policy service is down.                                                                                                                                  |
-| `IMAGES_ENABLED`         | unset                                                  | `true` adds the Images binding and enables `/img/` presets.                                                                                                             |
+| `IMAGES`                 | on                                                     | The Images binding, which enables `/img/` presets. Delete the line to disable them.                                                                                     |
 | `MODE`                   | `open`                                                 | `scoped` restricts the proxy to blobs referenced by records in allowlisted collections.                                                                                 |
 | `SCOPED_COLLECTIONS`     | none                                                   | Scoped mode: NSIDs or prefixes, e.g. `app.example.post,app.example.*`.                                                                                                  |
 | `JETSTREAM_URL`          | none                                                   | Scoped mode: Jetstream endpoint, e.g. `wss://jetstream2.us-east.bsky.network`.                                                                                          |
@@ -91,7 +90,7 @@ Open mode:
 GET  /{did}/{cid}                          the blob
 HEAD /{did}/{cid}                          headers only, same cache entry
 GET  /metadata/{did}/{cid}                 { mime, ext, size, width, height, animated }
-GET  /img/{preset}/plain/{did}/{cid}       resized variant (IMAGES_ENABLED)
+GET  /img/{preset}/plain/{did}/{cid}       resized variant (IMAGES binding)
 GET  /img/{preset}/plain/{did}/{cid}@jpeg  …with an output format: webp (default), jpeg, png
 GET  /healthz                              200, never cached
 ```
@@ -221,7 +220,7 @@ the limit; hammering the admin API in a loop is not.
 
 ```sh
 pnpm test            # unit and Worker tests, run inside workerd
-pnpm test:deployed   # HTTP suite against the deployed Worker (needs ADMIN_PASSWORD)
+pnpm test:deployed   # HTTP suite against the deployed Worker (reads ADMIN_PASSWORD from .env)
 pnpm check           # format, lint, types
 pnpm build
 ```

cloudflare.config.ts

@@ -4,20 +4,13 @@ import {
 	exports,
 	triggers,
 } from "@cloudflare/vite-plugin/experimental-config";
-import { compatibilityDate, compatibilityFlags } from "./compatibility.ts";
-import { CONFIG_DEFAULTS } from "./src/config.ts";
 import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };
 
-/** Deploy-time overrides come from the environment (`.env` locally). */
-function setting(key: keyof typeof CONFIG_DEFAULTS): string {
-	return process.env[key] ?? CONFIG_DEFAULTS[key];
-}
-
 export default defineWorker({
 	name: "cumulus",
 	entrypoint,
-	compatibilityDate,
-	compatibilityFlags,
+	// Keep in sync with vite.config.ts so tests run on the deployed runtime.
+	compatibilityDate: "2026-08-22",
 	cache: {
 		enabled: true,
 		crossVersionCache: true,
@@ -29,22 +22,26 @@ export default defineWorker({
 	},
 	env: {
 		VERSION: bindings.versionMetadata(),
-		ADMIN_PASSWORD: bindings.secret(),
-		BLOB_MAX_SIZE: bindings.text(setting("BLOB_MAX_SIZE")),
-		BLOB_ALLOWED_MIMETYPES: bindings.text(setting("BLOB_ALLOWED_MIMETYPES")),
-		BLOB_FETCH_TIMEOUT: bindings.text(setting("BLOB_FETCH_TIMEOUT")),
-		PLC_URL: bindings.text(setting("PLC_URL")),
-		BROWSER_MAX_AGE: bindings.text(setting("BROWSER_MAX_AGE")),
-		EDGE_MAX_AGE: bindings.text(setting("EDGE_MAX_AGE")),
-		POLICY_URL: bindings.text(setting("POLICY_URL")),
-		POLICY_FAIL_OPEN: bindings.text(setting("POLICY_FAIL_OPEN")),
-		LABELERS: bindings.text(setting("LABELERS")),
-		LABELER_FAIL_OPEN: bindings.text(setting("LABELER_FAIL_OPEN")),
-		MODE: bindings.text(setting("MODE")),
-		SCOPED_COLLECTIONS: bindings.text(setting("SCOPED_COLLECTIONS")),
-		JETSTREAM_URL: bindings.text(setting("JETSTREAM_URL")),
 		LABELS_KV: bindings.kv(),
-		...(process.env.IMAGES_ENABLED === "true" ? { IMAGES: bindings.images() } : {}),
+		// Set with `pnpm admin:password`.
+		ADMIN_PASSWORD: bindings.secret(),
+		// Remove this binding to disable the /img/ presets.
+		IMAGES: bindings.images(),
+
+		// Settings. The README's Configuration section documents each one.
+		BLOB_MAX_SIZE: bindings.text("3mb"),
+		BLOB_ALLOWED_MIMETYPES: bindings.text("image/jpeg,image/png,image/webp,image/avif,image/gif"),
+		BLOB_FETCH_TIMEOUT: bindings.text("30s"),
+		PLC_URL: bindings.text("https://plc.directory"),
+		BROWSER_MAX_AGE: bindings.text("3600"),
+		EDGE_MAX_AGE: bindings.text("31536000"),
+		LABELERS: bindings.text('[{"did":"did:plc:ar7c4by46qjdydhdevvrndac","vals":["!takedown"]}]'),
+		LABELER_FAIL_OPEN: bindings.text("true"),
+		POLICY_URL: bindings.text(""),
+		POLICY_FAIL_OPEN: bindings.text("false"),
+		MODE: bindings.text("open"),
+		SCOPED_COLLECTIONS: bindings.text(""),
+		JETSTREAM_URL: bindings.text(""),
 	},
 	triggers: [triggers.scheduled({ schedule: "*/5 * * * *" })],
 	observability: {

compatibility.ts

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from "node:fs";
 import { beforeAll, describe, expect, it } from "vitest";
 import { decodeCborSequence } from "../../src/cbor.ts";
 
@@ -11,7 +12,15 @@ const BASE = (process.env.CUMULUS_URL ?? "https://cumulus.ascorbic.workers.dev")
 	/\/+$/,
 	"",
 );
-const PASSWORD = process.env.ADMIN_PASSWORD;
+const PASSWORD = process.env.ADMIN_PASSWORD ?? passwordFromDotenv();
+
+function passwordFromDotenv(): string | undefined {
+	if (!existsSync(".env")) return undefined;
+	const line = readFileSync(".env", "utf8")
+		.split("\n")
+		.find((entry) => entry.startsWith("ADMIN_PASSWORD="));
+	return line?.slice("ADMIN_PASSWORD=".length).trim() || undefined;
+}
 const DID = process.env.TEST_DID ?? "did:plc:uwbl4k3tza7eyjv3morkrld2";
 const CID = process.env.TEST_CID ?? "bafkreic4mwsbm2tmuonamj4jq4kcjofk35bwics2f4oorp57f3cdfusjwu";
 const MISSING_CID = "bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku";

test/integration/deployed.test.ts

@@ -21,12 +21,5 @@
 		"lib": ["es2022"],
 		"types": ["@cloudflare/vitest-plugin/types"]
 	},
-	"include": [
-		"src",
-		"test",
-		"cloudflare.config.ts",
-		"compatibility.ts",
-		"vite.config.ts",
-		"worker-configuration.d.ts"
-	]
+	"include": ["src", "test", "cloudflare.config.ts", "vite.config.ts", "worker-configuration.d.ts"]
 }

tsconfig.json

@@ -1,7 +1,6 @@
 import { cloudflare } from "@cloudflare/vite-plugin";
 import { cloudflareTest } from "@cloudflare/vitest-plugin";
 import { defineConfig } from "vite-plus";
-import { compatibilityDate, compatibilityFlags } from "./compatibility.ts";
 import { TEST_ADMIN_PASSWORD } from "./test/constants.ts";
 
 export default defineConfig({
@@ -12,8 +11,8 @@ export default defineConfig({
 			? cloudflareTest({
 					main: "./src/index.ts",
 					miniflare: {
-						compatibilityDate,
-						compatibilityFlags,
+						// Keep in sync with cloudflare.config.ts.
+						compatibilityDate: "2026-08-22",
 						versionMetadata: "VERSION",
 						kvNamespaces: ["LABELS_KV"],
 						bindings: { ADMIN_PASSWORD: TEST_ADMIN_PASSWORD, LABELERS: "[]" },