@cparkerwebm/webmonterey 1.0.0

package/src/includes/cloudflare/d1/client.ts

@@ -0,0 +1,86 @@
+/*
+ * Thin helpers over Cloudflare D1.
+ *
+ * D1 holds PRIVATE data — form submissions, user accounts, anything that is not public page
+ * content. Public marketing copy belongs in src/content/pages/*.json, never here.
+ *
+ * Every helper takes the database as its first argument rather than reaching for the binding
+ * itself, so this module stays honest about its dependency and typechecks before any binding
+ * exists. Callers do:
+ *
+ *     export const prerender = false;   // REQUIRED — bindings are unavailable when prerendering
+ *
+ *     import { env } from 'cloudflare:workers';
+ *     import { all } from '../includes/cloudflare/d1/client.ts';
+ *
+ *     const rows = await all(env.DB, 'SELECT * FROM submissions WHERE form = ?', 'contact');
+ *
+ * Before `env.DB` typechecks, the binding must be in wrangler.jsonc and `wrangler types` must
+ * have re-run. Until then use `getBinding<D1Database>('DB')` from ../workers/env.
+ *
+ * ALWAYS pass values as bound parameters. Never build SQL by string concatenation.
+ *
+ * The one thing you CANNOT bind is an identifier — a table or column name. `ORDER BY ?` does
+ * not work, so a sortable table tempts you into `ORDER BY ${column}`, which is an injection.
+ * Map untrusted input through an allowlist instead, so only names you wrote can ever appear:
+ *
+ *     const SORTABLE = { name: 'name', date: 'created_at' } as const;
+ *     const column = SORTABLE[input as keyof typeof SORTABLE] ?? 'created_at';
+ *     const rows = await all(env.DB, `SELECT * FROM submissions ORDER BY ${column} DESC`);
+ */
+
+/** Bind params only when there are some — `.bind()` with no arguments is an error in D1. */
+function prepare(db: D1Database, sql: string, params: unknown[]) {
+  const statement = db.prepare(sql);
+  return params.length ? statement.bind(...params) : statement;
+}
+
+/** Every matching row. Returns an empty array when there are none. */
+export async function all<T = Record<string, unknown>>(
+  db: D1Database,
+  sql: string,
+  ...params: unknown[]
+): Promise<T[]> {
+  const { results } = await prepare(db, sql, params).all<T>();
+  return results ?? [];
+}
+
+/** The first matching row, or null. */
+export async function first<T = Record<string, unknown>>(
+  db: D1Database,
+  sql: string,
+  ...params: unknown[]
+): Promise<T | null> {
+  return await prepare(db, sql, params).first<T>();
+}
+
+/**
+ * For INSERT / UPDATE / DELETE. Read `meta.last_row_id` and `meta.changes` off the result.
+ *
+ * Returns `D1Result<T>` (not just `D1Response`) so `INSERT … RETURNING id` can read
+ * `.results` without a type error.
+ */
+export async function run<T = Record<string, unknown>>(
+  db: D1Database,
+  sql: string,
+  ...params: unknown[]
+): Promise<D1Result<T>> {
+  return await prepare(db, sql, params).run<T>();
+}
+
+/**
+ * Run several statements as one atomic batch.
+ *
+ * D1 has no interactive transactions — this is the only way to get all-or-nothing behavior.
+ *
+ *     await batch(env.DB, [
+ *       env.DB.prepare('INSERT INTO submissions (form, body) VALUES (?, ?)').bind(form, body),
+ *       env.DB.prepare('UPDATE counters SET n = n + 1 WHERE name = ?').bind(form),
+ *     ]);
+ */
+export async function batch<T = Record<string, unknown>>(
+  db: D1Database,
+  statements: D1PreparedStatement[],
+): Promise<D1Result<T>[]> {
+  return await db.batch<T>(statements);
+}

package/src/includes/cloudflare/r2/README.md

@@ -0,0 +1,68 @@
+# R2 media — `media.<client-domain>`
+
+Large or numerous files that should not live in git: video, audio, PDFs, galleries, downloads,
+and anything migrated wholesale out of a WordPress uploads folder.
+
+`media.ts` builds URLs. A binding is only needed if the Worker itself reads or writes objects —
+serving them to visitors goes through the custom domain and never touches the Worker.
+
+## Setup
+
+Do this **after** `go-live` has moved the zone onto the agency Cloudflare account. A custom
+domain on a bucket requires the zone to be on the same account as the bucket, so doing it
+earlier fails for the same reason `preview.<client-domain>` does.
+
+```sh
+npx wrangler r2 bucket create webm-<domain-dashed>-media
+```
+
+Then in the dashboard: **R2 → the bucket → Settings → Custom Domains → Connect Domain**, and
+enter `media.<client-domain>`. Cloudflare creates the DNS record itself.
+
+**Do not enable the `r2.dev` subdomain.** It is rate-limited, Cloudflare documents it as
+unsuitable for production, and it puts client media on a hostname the client does not own.
+
+Only add a binding to `wrangler.jsonc` if the Worker reads or writes objects — an upload
+endpoint, a signed download. Serving public media does not need one.
+
+## Bulk uploads: use rclone, not wrangler
+
+`wrangler r2 object put` **caps at 300 MiB per object**, and there is no object-listing or
+recursive-download command at all. It cannot perform a migration; do not spend an afternoon
+scripting around it.
+
+Create a bucket-scoped R2 API token (Object Read & Write), then:
+
+```
+[webm-media]
+type = s3
+provider = Cloudflare
+access_key_id = <token id>
+secret_access_key = <token secret>
+endpoint = https://<account-id>.r2.cloudflarestorage.com
+region = auto
+no_check_bucket = true
+```
+
+`no_check_bucket = true` is **required**, not tuning. A bucket-scoped token cannot
+`CreateBucket`, and rclone probes for exactly that before its first upload — so without it
+every transfer fails with an error naming an operation you never asked for.
+
+```sh
+rclone copy ./uploads webm-media:webm-<domain-dashed>-media --transfers 2 --progress
+rclone check ./uploads webm-media:webm-<domain-dashed>-media
+```
+
+Two things learned the hard way:
+
+- **`rclone check` is what proves a transfer**, not `rclone copy`'s exit code.
+- **A slow uplink wants FEWER parallel transfers.** 8 streams on a ~17 Mbps uplink produced
+  constant connection timeouts; 2 streams did not. Raising `--transfers` to fix slowness makes
+  it worse.
+
+## Local and remote are separate stores
+
+`wrangler dev` writes to a local simulated bucket under `.wrangler/`. Objects **never** move
+between it and production, in either direction, and nothing warns you. Code moves on push;
+objects do not move at all. A deployed site starts with an empty bucket and has to be seeded
+there. Same rule as D1 — see CLAUDE.md.

package/src/includes/cloudflare/r2/media.ts

@@ -0,0 +1,41 @@
+/*
+ * R2 media, served from `media.<client-domain>`.
+ *
+ * WHAT BELONGS HERE, and what does not:
+ *
+ *   src/assets/    images the DESIGN uses — imported, hashed, optimised at build by sharp.
+ *                  A logo, an icon, a hero shot. These belong in the repo.
+ *   public/        small fixed files that need a stable URL (favicons, open-graph.png).
+ *   R2 (here)      everything too large or too numerous to sit in git: video, audio, PDFs,
+ *                  photo galleries, downloads, anything migrated wholesale off a WordPress
+ *                  uploads folder.
+ *
+ * The deciding question is not file size, it is "should `git clone` carry this?" A 40MB
+ * showreel makes every clone slower forever and can never be optimised by the build.
+ *
+ * NAMING (rule 5):
+ *   bucket    webm-<domain-dashed>-media     e.g. webm-example-com-media
+ *   hostname  media.<client-domain>          e.g. media.example.com
+ *
+ * WHY A CUSTOM DOMAIN AND NOT r2.dev: Cloudflare's r2.dev subdomain is rate-limited and
+ * documented as unsuitable for production. It is also a hostname the client does not own,
+ * which puts their media on someone else's brand. A custom domain is also the only way the
+ * objects get Cache-Reserve and normal zone caching.
+ *
+ * THE ZONE MUST BE ON THE SAME CLOUDFLARE ACCOUNT AS THE BUCKET. This is the same constraint
+ * that makes `preview.<client-domain>` unusable before launch (see CLAUDE.md Traps) — but
+ * unlike previews it is not a blocker here, because `go-live` moves the zone onto the account
+ * anyway. Set up media AFTER the zone move, not before.
+ */
+import { domain, hasDomain } from '../../webmonterey/site.ts';
+import { buildMediaUrl, mediaHostFor } from './url.ts';
+
+export { buildMediaUrl, mediaHostFor };
+
+/** The media hostname for this site, or null while `domain` is still CHANGEME. */
+export const mediaHost = mediaHostFor(domain, hasDomain);
+
+/** Absolute URL for an object in this site's media bucket. See buildMediaUrl. */
+export function mediaUrl(key: string): string {
+  return buildMediaUrl(mediaHost, key);
+}

package/src/includes/cloudflare/r2/url.test.ts

@@ -0,0 +1,44 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildMediaUrl, mediaHostFor } from './url.ts';
+
+/*
+ * Tests the PURE builder, not the config-bound wrapper.
+ *
+ * In generation 2 this file imported the bound module and had to branch on whether the site it
+ * happened to be running in was configured yet - so the assertions were about properties that
+ * hold in every configuration rather than about behavior. Separating buildMediaUrl from
+ * mediaUrl means the interesting case (an unconfigured domain) is testable directly, on any
+ * machine, with no build.
+ */
+
+test('an absolute https URL is built from the host and key', () => {
+  assert.equal(
+    buildMediaUrl('media.example.com', 'video/reel.mp4'),
+    'https://media.example.com/video/reel.mp4',
+  );
+});
+
+test('a leading slash on the key does not produce a double slash', () => {
+  assert.equal(
+    buildMediaUrl('media.example.com', '/video/reel.mp4'),
+    'https://media.example.com/video/reel.mp4',
+  );
+  assert.equal(buildMediaUrl('media.example.com', '///a.pdf'), 'https://media.example.com/a.pdf');
+});
+
+test('a null host throws rather than returning a URL pointing at CHANGEME', () => {
+  // A dead image is only ever noticed by a visitor. Fail the build instead.
+  assert.throws(() => buildMediaUrl(null, 'a.pdf'), /CHANGEME/);
+});
+
+test('the error names the file and the field, so the fix is obvious from the message', () => {
+  assert.throws(() => buildMediaUrl(null, 'a.pdf'), /webmonterey\.json/);
+  assert.throws(() => buildMediaUrl(null, 'a.pdf'), /domain/);
+});
+
+test('mediaHostFor is null until the domain is configured', () => {
+  assert.equal(mediaHostFor('CHANGEME', false), null);
+  assert.equal(mediaHostFor(null, false), null);
+  assert.equal(mediaHostFor('example.com', true), 'media.example.com');
+});

package/src/includes/cloudflare/r2/url.ts

@@ -0,0 +1,34 @@
+/*
+ * Pure media-URL construction. No config, no virtual module, no imports.
+ *
+ * Separated from media.ts so it is testable with `node --test` and no build. media.ts binds
+ * this to the site's own host; anything importing media.ts transitively pulls in
+ * virtual:webm/site, which only exists inside an Astro build.
+ *
+ * THE PATTERN, applied throughout the package: pure logic lives in a file with no virtual-module
+ * imports; the binding lives beside it. Generation 2 could not do this because everything shared
+ * one repo, so its tests had to branch on whether the site they happened to run in was configured
+ * yet - asserting properties that hold in every configuration rather than behavior.
+ */
+
+/**
+ * Absolute URL for an object in the media bucket.
+ *
+ * Throws on a null host rather than returning a broken URL: a link silently pointing at
+ * `https://media.CHANGEME/…` renders as a dead image or a dead download, and the failure would
+ * only ever be noticed by a visitor.
+ */
+export function buildMediaUrl(host: string | null, key: string): string {
+  if (!host) {
+    throw new Error(
+      '[webm] Cannot build a media URL: webmonterey.json "domain" is still CHANGEME. ' +
+        'Set the production domain, or do not reference R2 media yet.',
+    );
+  }
+  return `https://${host}/${key.replace(/^\/+/, '')}`;
+}
+
+/** The media hostname for a domain, or null while it is still the placeholder. */
+export function mediaHostFor(domain: string | null, configured: boolean): string | null {
+  return configured && domain ? `media.${domain}` : null;
+}

package/src/includes/cloudflare/turnstile/Turnstile.astro

@@ -0,0 +1,161 @@
+---
+/*
+ * Cloudflare Turnstile widget. The client half; verify.ts is the server half.
+ *
+ *   <form method="POST" action={actions.submitForm}>
+ *     …fields…
+ *     <Turnstile />
+ *     <button type="submit">Send</button>
+ *   </form>
+ *
+ * Injects a hidden `cf-turnstile-response` input that submits with the form. The server MUST
+ * verify that token — rendering this widget alone protects nothing.
+ *
+ * The SITE key is public and comes from `vars` in wrangler.jsonc as PUBLIC_TURNSTILE_SITE_KEY.
+ * The SECRET key never touches the client.
+ *
+ * NOT consent-gated. Turnstile is strictly necessary for a form to resist abuse, which makes
+ * it an essential cookie under CCPA/GDPR — it runs regardless of the visitor's choices. See
+ * the consent rules in CLAUDE.md.
+ */
+interface Props {
+  /**
+   * Site key. Defaults to PUBLIC_TURNSTILE_SITE_KEY from the environment.
+   * Public by design — safe in markup.
+   */
+  siteKey?: string;
+  /**
+   * Distinguishes this form from others on the site, so a token minted by one cannot be
+   * replayed against another. Pass the SAME value to verifyTurnstile({ expectedAction }).
+   */
+  action?: string;
+  theme?: 'auto' | 'light' | 'dark';
+  size?: 'normal' | 'flexible' | 'compact';
+}
+
+const {
+  siteKey = import.meta.env.PUBLIC_TURNSTILE_SITE_KEY,
+  action,
+  theme = 'auto',
+  size = 'flexible',
+} = Astro.props;
+
+if (!siteKey) {
+  throw new Error(
+    '[webm] Turnstile has no site key. Set PUBLIC_TURNSTILE_SITE_KEY in `vars` in ' +
+      'wrangler.jsonc (and in .dev.vars for local dev), or pass siteKey directly. ' +
+      'This is the PUBLIC site key - the secret key belongs in `wrangler secret put`.',
+  );
+}
+
+// Test keys always pass and must never reach production. `go-live` checks for this too.
+const isTestKey = /^[12]x/.test(siteKey);
+---
+
+<div
+  class="cf-turnstile webm-turnstile"
+  data-sitekey={siteKey}
+  data-action={action}
+  data-theme={theme}
+  data-size={size}
+  data-error-callback="webmTurnstileError"
+>
+</div>
+
+<!--
+  Surfaced failure. Without this the widget fails COMPLETELY silently: if it cannot render —
+  most commonly `110200`, meaning this hostname is not in the widget's Hostname Management —
+  no token is ever minted, the server rejects every submission 403, and the form looks
+  entirely normal. The only symptom in the DOM is a missing iframe, and the only symptom
+  anywhere is a console exception nobody has open.
+
+  A visitor filling this in deserves to be told before they type a message they are about to
+  lose. `hidden` works here because reset.css forces it — see CLAUDE.md Traps.
+-->
+<p class="webm-turnstile__error" role="alert" hidden data-webm-turnstile-error>
+  This form could not load its spam protection, so it cannot be submitted right now. Please reload
+  the page, or contact us another way if the problem continues.
+</p>
+
+{
+  isTestKey && (
+    <p class="webm-turnstile__warning" role="status">
+      Turnstile is using a <strong>test key</strong> — every submission passes. Replace it before
+      launch.
+    </p>
+  )
+}
+
+{
+  /*
+  Defined BEFORE the api.js tag below, and `is:inline` so Astro neither bundles nor defers it.
+  Turnstile resolves `data-error-callback` by name off `window` at the moment it fails, which
+  can be immediately on script load — a module-scoped or deferred function would not exist yet
+  and the failure would go back to being silent.
+*/
+}
+<script is:inline>
+  window.webmTurnstileError = function (code) {
+    /*
+     * The callback receives an error code, not the element that failed. A widget that failed
+     * to render has no iframe, which is what identifies it — and on the overwhelmingly common
+     * single-form page it is simply the only one.
+     */
+    document.querySelectorAll('.webm-turnstile').forEach(function (widget) {
+      if (widget.querySelector('iframe')) return;
+
+      var message =
+        widget.parentNode && widget.parentNode.querySelector('[data-webm-turnstile-error]');
+      if (message) message.hidden = false;
+
+      /*
+       * Disable submit. The server rejects these anyway — this replaces "the button does
+       * nothing" with an explanation, rather than changing whether the form can be sent.
+       */
+      var form = widget.closest('form');
+      if (form) {
+        form
+          .querySelectorAll('button[type="submit"], input[type="submit"]')
+          .forEach(function (button) {
+            button.disabled = true;
+          });
+      }
+    });
+
+    console.error(
+      '[webm] Turnstile failed to render (code ' +
+        code +
+        '). ' +
+        "A 110200 means this hostname is not listed in the widget's Hostname Management.",
+    );
+  };
+</script>
+
+<script is:inline async defer src="https://challenges.cloudflare.com/turnstile/v0/api.js"></script>
+
+<style>
+  @layer webm.components.core {
+    .webm-turnstile {
+      /* Reserve the widget's height so the form does not jump when it loads. */
+      min-block-size: 4.0625rem;
+    }
+
+    .webm-turnstile__warning {
+      margin-block-start: var(--webm-space-2xs);
+      padding: var(--webm-space-2xs) var(--webm-space-xs);
+      border-radius: var(--webm-radius-sm);
+      background-color: var(--webm-surface-alt);
+      color: var(--webm-state-warning);
+      font-size: var(--webm-font-size-xs);
+    }
+
+    .webm-turnstile__error {
+      margin-block-start: var(--webm-space-2xs);
+      padding: var(--webm-space-2xs) var(--webm-space-xs);
+      border-radius: var(--webm-radius-sm);
+      background-color: var(--webm-surface-alt);
+      color: var(--webm-state-danger);
+      font-size: var(--webm-font-size-xs);
+    }
+  }
+</style>

package/src/includes/cloudflare/turnstile/verify.ts

@@ -0,0 +1,157 @@
+/*
+ * Cloudflare Turnstile — server-side verification.
+ *
+ * There is NO official Astro or Workers integration. `@cloudflare/pages-plugin-turnstile` is
+ * a Pages Functions plugin and does not work here. Verification is this one POST.
+ *
+ * TWO KEYS, do not mix them up:
+ *   SITE key   — public. Goes in `vars` in wrangler.jsonc, rendered into the widget markup.
+ *   SECRET key — never leaves the server. `npx wrangler secret put TURNSTILE_SECRET_KEY`.
+ *
+ * The route that calls this needs `export const prerender = false`.
+ */
+
+const SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+
+/** The field Turnstile injects into the form. */
+export const TURNSTILE_FIELD = 'cf-turnstile-response';
+
+/** Give up rather than hold a Worker request open on a hung connection. */
+const TIMEOUT_MS = 10_000;
+
+export interface TurnstileResult {
+  success: boolean;
+  /** Failure reasons — Cloudflare's codes, plus `hostname-mismatch` / `action-mismatch`. */
+  errorCodes: string[];
+  challengeTs?: string;
+  /** The hostname the challenge was actually solved on. */
+  hostname?: string;
+  /** The action the widget was configured with, if any. */
+  action?: string;
+}
+
+export interface VerifyOptions {
+  /** The widget's SECRET key. */
+  secretKey: string;
+  /** The token from the `cf-turnstile-response` form field. */
+  token: string;
+  /**
+   * The hostname this submission must have been solved on — pass `Astro.url.hostname`.
+   *
+   * REQUIRED, and not ceremony. A Turnstile token is bound to the sitekey/secret pair, NOT
+   * to a site or a form. If one widget is ever reused across client sites (or one widget
+   * lists several hostnames), an attacker solves the challenge once on site A and replays
+   * the token at site B's form — siteverify returns success, and without this check nobody
+   * notices. Verifying the hostname is what binds the token to this site.
+   */
+  expectedHostname: string;
+  /**
+   * The `data-action` on the widget, if set. When provided, a token minted by a different
+   * form on the same site is rejected — otherwise a newsletter widget's token replays
+   * against the contact form.
+   */
+  expectedAction?: string;
+  /** Visitor IP. Pass `request.headers.get('CF-Connecting-IP')`. */
+  remoteIp?: string | null;
+  /**
+   * Idempotency key for safely retrying ONE submission attempt.
+   *
+   * Must be freshly generated per attempt (`crypto.randomUUID()`). Never a constant, never
+   * derived from user input: Cloudflare returns the CACHED result for a repeated key, which
+   * defeats the single-use guarantee (`timeout-or-duplicate`) that stops token replay. A
+   * hardcoded value turns one solved challenge into unlimited accepted submissions.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Verify a Turnstile token.
+ *
+ * Returns `success: false` rather than throwing on a failed challenge — a bot submission is
+ * an expected outcome, not an exception. It DOES throw if Cloudflare is unreachable, times
+ * out, or answers with a non-2xx, because that is a real fault and should not be silently
+ * counted as spam.
+ *
+ * A caught error MUST reject the submission, never admit it. Failing open here hands an
+ * attacker a bypass: make the siteverify call fail and every submission sails through.
+ *
+ *     export const prerender = false;
+ *
+ *     const form = await request.formData();
+ *     let result;
+ *     try {
+ *       result = await verifyTurnstile({
+ *         secretKey: getBinding<string>('TURNSTILE_SECRET_KEY'),
+ *         token: String(form.get(TURNSTILE_FIELD) ?? ''),
+ *         expectedHostname: Astro.url.hostname,
+ *         remoteIp: request.headers.get('CF-Connecting-IP'),
+ *       });
+ *     } catch {
+ *       return new Response('Verification unavailable', { status: 503 }); // reject, not admit
+ *     }
+ *     if (!result.success) return new Response('Failed verification', { status: 400 });
+ */
+export async function verifyTurnstile(options: VerifyOptions): Promise<TurnstileResult> {
+  const { secretKey, token, expectedHostname, expectedAction, remoteIp, idempotencyKey } = options;
+
+  // An empty token means the widget never solved — no point spending a round trip.
+  if (!token) {
+    return { success: false, errorCodes: ['missing-input-response'] };
+  }
+
+  const response = await fetch(SITEVERIFY_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      secret: secretKey,
+      response: token,
+      ...(remoteIp ? { remoteip: remoteIp } : {}),
+      ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+    }),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `[webm] Turnstile siteverify returned ${response.status}. This is an outage or a ` +
+        `malformed request, not a failed challenge - reject the submission, do not admit it.`,
+    );
+  }
+
+  const data = (await response.json()) as {
+    success: boolean;
+    'error-codes'?: string[];
+    challenge_ts?: string;
+    hostname?: string;
+    action?: string;
+  };
+
+  const result: TurnstileResult = {
+    success: data.success === true,
+    errorCodes: data['error-codes'] ?? [],
+    challengeTs: data.challenge_ts,
+    hostname: data.hostname,
+    action: data.action,
+  };
+
+  if (!result.success) return result;
+
+  // Cloudflare said the challenge was solved. Now confirm it was solved HERE, for THIS form.
+  if (result.hostname !== expectedHostname) {
+    return {
+      ...result,
+      success: false,
+      errorCodes: [...result.errorCodes, 'hostname-mismatch'],
+    };
+  }
+
+  if (expectedAction !== undefined && result.action !== expectedAction) {
+    return {
+      ...result,
+      success: false,
+      errorCodes: [...result.errorCodes, 'action-mismatch'],
+    };
+  }
+
+  return result;
+}

package/src/includes/cloudflare/workers/env.ts

@@ -0,0 +1,56 @@
+/*
+ * Access to Cloudflare bindings and secrets.
+ *
+ * THE ONLY CORRECT IMPORT is `cloudflare:workers`. `Astro.locals.runtime` was removed in
+ * @astrojs/cloudflare v13 — any snippet using it is Cloudflare-Pages-era and will not work.
+ *
+ * Bindings are UNAVAILABLE while prerendering. Any route that reads one needs:
+ *
+ *     export const prerender = false;
+ */
+import { env } from 'cloudflare:workers';
+
+/*
+ * `env` is deliberately NOT re-exported.
+ *
+ * Every secret is a plain string property on it, so a single `{JSON.stringify(env)}` on a
+ * debug page — exactly what gets added while chasing a "binding is undefined" problem —
+ * dumps every secret into the response. Import it from 'cloudflare:workers' directly if you
+ * genuinely need the whole object, or use getBinding() below to take one value at a time.
+ */
+
+/**
+ * Read a binding or secret by name, failing loudly if it is not configured.
+ *
+ * Bindings you have not declared yet do not exist on the generated `Env` type, so
+ * `env.DB` will not typecheck until the binding is in wrangler.jsonc and you have re-run
+ * `wrangler types` (which `npm run dev` and `npm run build` do for you). This helper is the
+ * bridge: it looks the binding up at runtime and hands back the type you assert.
+ *
+ *     const db = getBinding<D1Database>('DB');
+ *
+ * Once `wrangler types` knows about the binding, prefer plain `env.DB` — it is genuinely
+ * type-checked, whereas this is an assertion you are making.
+ */
+export function getBinding<T>(name: string): T {
+  const value = (env as unknown as Record<string, unknown>)[name];
+
+  if (value === undefined || value === null || value === '') {
+    throw new Error(
+      `[webm] Missing Cloudflare binding or secret "${name}".\n` +
+        `  - Local dev: add it to .dev.vars (copy .dev.vars.example)\n` +
+        `  - Production: npx wrangler secret put ${name}\n` +
+        `  - Resource bindings (D1, KV, R2, Queues) go in wrangler.jsonc, not secrets\n` +
+        `  - Reading a binding on a prerendered route always fails; set ` +
+        `\`export const prerender = false\` on the route.`,
+    );
+  }
+
+  return value as T;
+}
+
+/** True if a binding or secret is configured. Use to make a feature degrade rather than throw. */
+export function hasBinding(name: string): boolean {
+  const value = (env as unknown as Record<string, unknown>)[name];
+  return value !== undefined && value !== null && value !== '';
+}