@tokenoftrust/storefront-runner 4.9.0 → 4.9.1

package/apps/storefront/src/lib/access/rate/kvWindow.ts

@@ -1,16 +1,23 @@
 /**
- * Fixed-window KV rate limiter — the storefront's first throttle, built small
- * and generic so any public POST can share it (reactions today; blog comments
- * and other reader writes next).
+ * Fixed-window KV rate limiter for public POSTs.
  *
  * A request is counted into the bucket for the current fixed window
  * (`floor(now / windowSeconds)`), keyed `<key>:<bucket>`. The counter TTLs out a
  * window after it is first written, so old buckets self-expire — no sweep.
  *
- * Best-effort by construction: a KV read/write hiccup FAILS OPEN (returns
- * `allowed: true`) and never throws. A rate limiter must never turn a KV blip
- * into a rejected legitimate request; the abuse it guards against is low-stakes
- * (mirrors the "never throws" discipline of `blog/viewCounts.ts`).
+ * Two entry points, and the difference is the decision a caller makes:
+ *   - {@link checkRateLimit} FAILS CLOSED. No KV binding, or a KV read/write error,
+ *     refuses with `reason: "unavailable"`. This is the default for every public
+ *     write whose abuse is not trivial (a stored message, a subscriber row, a mail).
+ *   - {@link checkRateLimitFailOpen} admits when KV is missing or erroring. Only for
+ *     a write whose abuse blast radius is a counter and where refusing a legitimate
+ *     request on a KV blip is the worse outcome; the call site names that choice.
+ *
+ * Keys carry a hashed client identifier, never a raw IP: build one with
+ * `requestClientIp` + `hashConsentIp`.
+ *
+ * Increment is a read-modify-write, so under concurrency a few increments can be
+ * lost to KV's last-write-wins — acceptable for a soft abuse throttle, not a hard quota.
  */
 
 export interface RateLimitOptions {
@@ -20,54 +27,26 @@ export interface RateLimitOptions {
   maxRequests: number;
 }
 
+export type RateLimitVerdict =
+  | { allowed: true }
+  | { allowed: false; reason: "limited" | "unavailable" };
+
 /** The current fixed-window bucket index for `now` (ms epoch). */
 function windowBucket(windowSeconds: number, nowMs: number): number {
   return Math.floor(nowMs / 1000 / windowSeconds);
 }
 
 /**
- * Count one request against `key` and report whether it is within the cap for
- * the current window. Increment is a read-modify-write, so under concurrency a
- * few increments can be lost to KV's last-write-wins — acceptable for a soft
- * abuse throttle, not a hard quota. Fails OPEN on any KV error.
+ * Count one request against `key` and report whether it is within the cap for the
+ * current window. FAIL-CLOSED: no KV binding, or a KV read/write error, refuses
+ * with `reason: "unavailable"` instead of admitting.
  */
 export async function checkRateLimit(
   kv: KVNamespace | undefined,
   key: string,
   opts: RateLimitOptions,
   nowMs: number = Date.now(),
-): Promise<{ allowed: boolean }> {
-  if (!kv) return { allowed: true };
-  try {
-    const bucket = windowBucket(opts.windowSeconds, nowMs);
-    const bucketKey = `${key}:${bucket}`;
-    const raw = await kv.get(bucketKey);
-    const current = raw == null ? 0 : Number.parseInt(raw, 10);
-    const count = Number.isFinite(current) && current >= 0 ? current : 0;
-    if (count >= opts.maxRequests) return { allowed: false };
-    await kv.put(bucketKey, String(count + 1), { expirationTtl: opts.windowSeconds });
-    return { allowed: true };
-  } catch {
-    return { allowed: true };
-  }
-}
-
-export type ClosedRateLimitVerdict =
-  | { allowed: true }
-  | { allowed: false; reason: "limited" | "unavailable" };
-
-/**
- * The same fixed window, FAIL-CLOSED: no KV binding, or a KV read/write error,
- * refuses with `reason: "unavailable"` instead of admitting. For public writes
- * whose abuse is not low-stakes (a stored visitor message), where an unthrottled
- * window is worse than a refused request.
- */
-export async function checkRateLimitClosed(
-  kv: KVNamespace | undefined,
-  key: string,
-  opts: RateLimitOptions,
-  nowMs: number = Date.now(),
-): Promise<ClosedRateLimitVerdict> {
+): Promise<RateLimitVerdict> {
   if (!kv) return { allowed: false, reason: "unavailable" };
   let count: number;
   const bucketKey = `${key}:${windowBucket(opts.windowSeconds, nowMs)}`;
@@ -86,3 +65,18 @@ export async function checkRateLimitClosed(
   }
   return { allowed: true };
 }
+
+/**
+ * The same fixed window, FAIL-OPEN: no KV binding, or a KV error, returns
+ * `allowed: true` and never throws. A call site uses this only for a write whose
+ * abuse is low-stakes (a reaction counter), and says so where it calls.
+ */
+export async function checkRateLimitFailOpen(
+  kv: KVNamespace | undefined,
+  key: string,
+  opts: RateLimitOptions,
+  nowMs: number = Date.now(),
+): Promise<{ allowed: boolean }> {
+  const verdict = await checkRateLimit(kv, key, opts, nowMs);
+  return { allowed: verdict.allowed || verdict.reason === "unavailable" };
+}

package/apps/storefront/src/pages/api/blog/[collection]/[slug]/react.ts

@@ -5,21 +5,23 @@
  *
  * Discipline (mirrors the other public POSTs, `newsletter.ts` / `rum/vitals.ts`):
  *   - Tenant is resolved from `locals.tenant`, NEVER the request body.
- *   - A soft per-IP KV rate limit stops trivial scripted inflation; over-cap
+ *   - A soft per-visitor KV rate limit (hashed client IP, fail-open) stops trivial scripted inflation; over-cap
  *     returns the current tallies (429) without counting — abuse blast-radius is
  *     ~0 (a counter), so the cap is lenient.
  *   - Never 500. Every path returns a clean JSON response; `recordReaction` is
  *     itself best-effort and never throws.
  */
 import type { APIRoute } from "astro";
-import { readKv } from "@/lib/publication/shared/env";
+import { readEnv, readKv } from "@/lib/publication/shared/env";
+import { requestClientIp } from "@/lib/publication/shared/cdnForward";
+import { hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import {
   getReactionCounts,
   isReaction,
   recordReaction,
   type Reaction,
 } from "@/lib/content/blog/reactions";
-import { checkRateLimit } from "@/lib/access/rate/kvWindow";
+import { checkRateLimitFailOpen } from "@/lib/access/rate/kvWindow";
 
 export const prerender = false;
 
@@ -33,15 +35,6 @@ function json(body: unknown, status = 200): Response {
   });
 }
 
-/** Best-effort client IP for rate-limit keying — Cloudflare's header, else XFF. */
-function clientIp(request: Request): string {
-  const cf = request.headers.get("cf-connecting-ip");
-  if (cf) return cf;
-  const xff = request.headers.get("x-forwarded-for");
-  if (xff) return xff.split(",")[0]!.trim();
-  return "unknown";
-}
-
 /** Pull the reaction from a JSON or form-encoded body. */
 async function readReaction(request: Request): Promise<string | null> {
   try {
@@ -80,7 +73,11 @@ export const POST: APIRoute = async (context) => {
     );
   }
 
-  const { allowed } = await checkRateLimit(kv, `react:${tenantId}:${clientIp(context.request)}`, {
+  // Deliberately fail-open: a reaction is a counter, so a KV blip must not refuse a reader.
+  const cdnSecret = await readEnv("CDN_ORIGIN_SECRET");
+  const ip = await requestClientIp(context.request.headers, cdnSecret);
+  const ipKey = await hashConsentIp(ip, `react-rate:${cdnSecret ?? tenantId}`);
+  const { allowed } = await checkRateLimitFailOpen(kv, `react:${tenantId}:${ipKey}`, {
     windowSeconds: RATE_WINDOW_SECONDS,
     maxRequests: RATE_MAX_PER_WINDOW,
   });

package/apps/storefront/src/pages/api/contact.ts

@@ -13,7 +13,7 @@
 import type { APIContext } from "astro";
 import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
 import { fromD1 } from "@/lib/catalog/d1/catalog";
-import { checkRateLimitClosed } from "@/lib/access/rate/kvWindow";
+import { checkRateLimit } from "@/lib/access/rate/kvWindow";
 import { hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import { ContactMessagesStore } from "@/lib/engagement/contact/contactMessages";
 import { verifyContactToken } from "@/lib/engagement/contact/submitToken";
@@ -107,7 +107,7 @@ export async function POST(context: APIContext): Promise<Response> {
   const kv = await readKv("TENANT_CACHE");
   const ip = await requestClientIp(request.headers, await readEnv("CDN_ORIGIN_SECRET"));
   const ipKey = await hashConsentIp(ip, `contact-rate:${secret}`);
-  const limit = await checkRateLimitClosed(kv, `contact:${tenantId}:${ipKey}`, {
+  const limit = await checkRateLimit(kv, `contact:${tenantId}:${ipKey}`, {
     windowSeconds: CONTACT_RATE_WINDOW_SECONDS,
     maxRequests: CONTACT_RATE_MAX_PER_WINDOW,
   });

package/apps/storefront/src/pages/api/newsletter/[collection]/subscribe.ts

@@ -5,19 +5,22 @@
  * Discipline (mirrors the other public POSTs, `blog/.../react.ts` / `newsletter.ts`):
  *   - `tenant_id` is resolved from `locals.tenant`, `collection` from the ROUTE —
  *     NEVER the request body (tenant is the isolation boundary).
- *   - A soft per-IP KV rate limit (`kvWindow`) stops trivial scripted signups.
+ *   - A per-visitor KV rate limit (`kvWindow`, keyed on the hashed client IP,
+ *     fail-closed) stops scripted signups; a missing or failing KV refuses (503).
  *   - `INSERT OR IGNORE` a `pending` row with a fresh opaque token + consent
  *     record (`consent_source` = referrer, `consent_ip_hash` = sha256(ip+salt) —
  *     NEVER a raw IP). A repeat subscribe is idempotent.
- *   - Confirmation email is STUBBED (no ESP in-repo yet — N4 wires it); a stub
- *     failure never fails the subscribe.
+ *   - A confirmation email that cannot be sent, a missing apps DB and a failed
+ *     write are errors (502/503 JSON), never a success: the visitor is not told to
+ *     check an inbox that will stay empty. A retry re-sends while the row is pending.
  *   - Never 500. A `fetch`/JSON caller gets a clean JSON body; a plain form POST
- *     is redirected back to the referrer so the page can show its own thanks.
+ *     that succeeded is redirected back to the referrer so the page can show its own thanks.
  */
 import type { APIRoute } from "astro";
 import { readD1, readKv, readEnv } from "@/lib/publication/shared/env";
 import { fromD1 } from "@/lib/catalog/d1/catalog";
 import { checkRateLimit } from "@/lib/access/rate/kvWindow";
+import { requestClientIp } from "@/lib/publication/shared/cdnForward";
 import { NewsletterSubscribersStore } from "@/lib/engagement/newsletter/subscribers";
 import { randomToken, hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import { sendConfirmationEmail } from "@/lib/engagement/newsletter/confirmationEmail";
@@ -38,15 +41,6 @@ function json(body: unknown, status = 200): Response {
   });
 }
 
-/** Best-effort client IP for rate-limit keying + consent record — CF header, else XFF. */
-function clientIp(request: Request): string {
-  const cf = request.headers.get("cf-connecting-ip");
-  if (cf) return cf;
-  const xff = request.headers.get("x-forwarded-for");
-  if (xff) return xff.split(",")[0]!.trim();
-  return "unknown";
-}
-
 /** Read `email` from a JSON or form-encoded body; null if unparseable. */
 async function readEmail(request: Request): Promise<string | null> {
   try {
@@ -98,26 +92,31 @@ export const POST: APIRoute = async (context) => {
       return json({ ok: false, error: "invalid_email" }, 400);
     }
 
+    const salt = (await readEnv("NEWSLETTER_CONSENT_SALT")) ?? DEV_CONSENT_SALT;
+    const ip = await requestClientIp(context.request.headers, await readEnv("CDN_ORIGIN_SECRET"));
+    const consentIpHash = await hashConsentIp(ip, salt);
+    const rateKey = await hashConsentIp(ip, `newsletter-rate:${salt}`);
+
     const kv = await readKv("TENANT_CACHE");
-    const { allowed } = await checkRateLimit(
+    const limit = await checkRateLimit(
       kv,
-      `newsletter-subscribe:${tenantId}:${clientIp(context.request)}`,
+      `newsletter-subscribe:${tenantId}:${rateKey}`,
       { windowSeconds: RATE_WINDOW_SECONDS, maxRequests: RATE_MAX_PER_WINDOW },
     );
-    if (!allowed) return json({ ok: false, error: "rate_limited" }, 429);
+    if (!limit.allowed) {
+      return limit.reason === "limited"
+        ? json({ ok: false, error: "rate_limited" }, 429)
+        : json({ ok: false, error: "unavailable" }, 503);
+    }
 
     const d1 = await readD1("STOREFRONT_APPS_DB");
     if (!d1) {
-      // No apps DB binding (local/dev without D1): can't persist. Don't fail the
-      // visitor — log and acknowledge so the flow is exercisable in dev.
-      console.log(`[newsletter] subscribe not persisted (no D1) → ${tenantId}/${collection}`);
-      return ok(context.request);
+      console.error(`[newsletter] subscribe refused: no apps DB binding tenant=${tenantId} collection=${collection}`);
+      return json({ ok: false, error: "unavailable" }, 503);
     }
 
     const referer = context.request.headers.get("referer");
     const consentSource = referer ? new URL(referer).pathname : null;
-    const salt = (await readEnv("NEWSLETTER_CONSENT_SALT")) ?? DEV_CONSENT_SALT;
-    const consentIpHash = await hashConsentIp(clientIp(context.request), salt);
 
     const store = new NewsletterSubscribersStore(fromD1(d1));
     const result = await store.subscribe({
@@ -130,25 +129,29 @@ export const POST: APIRoute = async (context) => {
     });
 
     // Only (re)send confirmation while still pending — never re-mail a confirmed
-    // or unsubscribed address. Best-effort; a stub failure must not fail signup.
+    // or unsubscribed address. A failed send is an error: the row stays pending, so
+    // the visitor's retry re-sends.
     if (result.status === "pending") {
       const origin = new URL(context.request.url).origin;
       // The tenant's real routed prefix: a pinned preview's basePath has no API mirror.
       const apiBasePath = context.locals?.apiBasePath ?? context.locals?.basePath ?? "";
       const confirmUrl = `${origin}${apiBasePath}/api/newsletter/confirm?token=${result.token}`;
-      await sendConfirmationEmail({ email, collection, confirmUrl }).catch((err: unknown) => {
+      try {
+        await sendConfirmationEmail({ email, collection, confirmUrl });
+      } catch (err) {
         console.error(
           `[newsletter] confirmation email failed tenant=${tenantId} collection=${collection}: ${err instanceof Error ? err.name : "unknown"}`,
         );
-      });
+        return json({ ok: false, error: "confirmation_not_sent" }, 502);
+      }
     }
 
     return ok(context.request);
   } catch (err) {
-    // Never 500 on a signup — acknowledge, but never swallow the failure silently.
+    // Never 500 on a signup, and never report a success that did not happen.
     console.error(
       `[newsletter] subscribe failed collection=${collection}: ${err instanceof Error ? err.name : "unknown"}`,
     );
-    return ok(context.request);
+    return json({ ok: false, error: "unavailable" }, 503);
   }
 };

package/apps/storefront/src/pages/api/newsletter.ts

@@ -12,7 +12,8 @@
  *
  * Every outcome is a confirmation page with a link back to where the visitor was;
  * a script that asks for JSON gets `{ ok, status }`. Robustness: a signup must NEVER
- * 500. All failures degrade to a friendly thank-you.
+ * 500, and a signup that was not recorded (no KV binding, a failed write) answers
+ * `failed` with a 503 rather than a thank-you.
  */
 import type { APIContext } from "astro";
 import { readKv } from "@/lib/publication/shared/env";
@@ -22,7 +23,7 @@ import { withBase } from "@/lib/publication/shared/basePath";
 // deliverability; the ESP validates properly downstream.
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
-export type NewsletterStatus = "subscribed" | "preview" | "invalid";
+export type NewsletterStatus = "subscribed" | "preview" | "invalid" | "failed";
 
 const COPY: Record<NewsletterStatus, { heading: string; message: string }> = {
   subscribed: {
@@ -38,8 +39,15 @@ const COPY: Record<NewsletterStatus, { heading: string; message: string }> = {
     heading: "That didn't go through.",
     message: "That address didn't look quite right — head back and try again.",
   },
+  failed: {
+    heading: "That didn't go through.",
+    message: "We couldn't record your signup just now — head back and try again in a moment.",
+  },
 };
 
+/** A failed recording is a 503; every other outcome is a 200 page or body. */
+const HTTP_STATUS: Record<NewsletterStatus, number> = { subscribed: 200, preview: 200, invalid: 200, failed: 503 };
+
 function escapeHtml(value: string): string {
   return value.replace(/[&<>"']/g, (ch) => `&#${ch.charCodeAt(0)};`);
 }
@@ -65,8 +73,8 @@ function wantsJson(request: Request): boolean {
 
 function respond(context: APIContext, status: NewsletterStatus): Response {
   if (wantsJson(context.request)) {
-    return new Response(JSON.stringify({ ok: status !== "invalid", status }), {
-      status: 200,
+    return new Response(JSON.stringify({ ok: status !== "invalid" && status !== "failed", status }), {
+      status: HTTP_STATUS[status],
       headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
     });
   }
@@ -98,7 +106,7 @@ function respond(context: APIContext, status: NewsletterStatus): Response {
   </body>
 </html>`;
   return new Response(html, {
-    status: 200,
+    status: HTTP_STATUS[status],
     headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
   });
 }
@@ -125,16 +133,16 @@ export async function POST(context: APIContext): Promise<Response> {
         JSON.stringify({ email, source, at: new Date().toISOString() }),
       );
     } else {
-      // No KV binding (local/dev): nothing to persist to.
-      console.log(`[newsletter] signup not persisted (no TENANT_CACHE) tenant=${tenantId} source=${source}`);
+      console.error(`[newsletter] signup not recorded: no TENANT_CACHE binding tenant=${tenantId}`);
+      return respond(context, "failed");
     }
     return respond(context, "subscribed");
   } catch (err) {
-    // Never 500 on a signup, but never swallow the failure silently either.
+    // Never 500 on a signup, and never report a success that did not happen.
     console.error(
       `[newsletter] signup failed tenant=${context.locals.tenant?.tenant_id ?? "?"}: ${err instanceof Error ? err.name : "unknown"}`,
     );
-    return respond(context, "subscribed");
+    return respond(context, "failed");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",