@tokenoftrust/storefront-runner 2.4.79 → 2.4.80

package/apps/storefront/env.d.ts

@@ -152,6 +152,14 @@ declare global {
        * the pinned render.
        */
       apiBasePath: string;
+      /**
+       * True when this request was admitted to a store that is NOT public on this
+       * host (a login-gated host, tenant without `access.public`) — by session,
+       * preview grant, or QA bypass. Visitor routes read it to avoid recording
+       * side effects, such as a newsletter signup, for an audience that cannot
+       * exist yet. Unset on every public request.
+       */
+      storeNotPublic?: boolean;
       /**
        * Which customization environment to serve. "live" on production
        * hosts; "test" only behind a valid, tenant-bound preview token on a

package/apps/storefront/src/lib/auth/gatePage.ts

@@ -68,6 +68,14 @@ export function gatedHoldingHtml(loginHref: string): string {
 </html>`;
 }
 
+/**
+ * Names the gate's decision on every response it answers in place of the route, so a
+ * caller (or a curl) can tell "withheld by the store-not-public gate" from anything
+ * the route itself said without reading the body.
+ */
+export const GATE_HEADER = "x-tot-gate";
+export const GATE_WITHHELD = "store-not-public";
+
 /** A `200 OK` holding page — never indexed, never cached. */
 export function gatedHoldingResponse(loginHref: string): Response {
   return new Response(gatedHoldingHtml(loginHref), {
@@ -76,6 +84,39 @@ export function gatedHoldingResponse(loginHref: string): Response {
       "content-type": "text/html; charset=utf-8",
       "cache-control": "no-store",
       "x-robots-tag": "noindex, nofollow",
+      [GATE_HEADER]: GATE_WITHHELD,
     },
   });
 }
+
+/** A browser form submission or link, as opposed to a script's fetch. */
+function isNavigation(request: Request): boolean {
+  const mode = request.headers.get("sec-fetch-mode");
+  if (mode) return mode === "navigate";
+  const accept = request.headers.get("accept") ?? "";
+  return accept.includes("text/html") && !accept.includes("application/json");
+}
+
+/**
+ * The gate's answer to a withheld `/api/` request: `401`, never a `200` page a
+ * script would read as the route's own success. A browser form submission still gets
+ * the holding page with its Sign-in button, the same answer the store's pages give;
+ * a fetch gets JSON naming the reason and where to sign in.
+ */
+export function gatedApiResponse(loginHref: string, request: Request): Response {
+  const headers = {
+    "cache-control": "no-store",
+    "x-robots-tag": "noindex, nofollow",
+    [GATE_HEADER]: GATE_WITHHELD,
+  };
+  if (isNavigation(request)) {
+    return new Response(gatedHoldingHtml(loginHref), {
+      status: 401,
+      headers: { ...headers, "content-type": "text/html; charset=utf-8" },
+    });
+  }
+  return new Response(
+    JSON.stringify({ ok: false, error: GATE_WITHHELD, signIn: loginHref }),
+    { status: 401, headers: { ...headers, "content-type": "application/json; charset=utf-8" } },
+  );
+}

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -273,6 +273,36 @@ export function isBypassPrivilegedPath(pathname: string): boolean {
   return false;
 }
 
+/**
+ * The `/api/` routes a signed, tenant-bound preview grant admits: visitor forms on a
+ * tenant's own pages whose route has NO effect on a store that is not public. A
+ * reviewer on a copy-preview link submits them and gets the route's own answer
+ * instead of the holding page; the route reads `locals.storeNotPublic` and records
+ * nothing (the footer/homepage newsletter form confirms "off in preview").
+ *
+ * Membership is earned by that property, not by being visitor-facing. The checkout
+ * handoff and the compliance preflight stay refused: the preflight is the checkout
+ * enforcement gate and returns a real decision, and no preview credential may reach
+ * it. Admin, publish, change, and dashboard APIs still require a session, and beacons
+ * (RUM, tracking, CSP/tamper reports, blog reactions) are not admitted so preview
+ * traffic never lands in a store's live measurement.
+ *
+ * Exact paths, in BOTH addressing forms (the gate sees the PRE-STRIP path).
+ */
+export const PREVIEW_VISITOR_API_PATHS = ["/api/newsletter"] as const;
+
+export function isPreviewVisitorApiPath(pathname: string): boolean {
+  if ((PREVIEW_VISITOR_API_PATHS as readonly string[]).includes(pathname)) return true;
+  const prefixed = /^\/[^/]+(\/api\/.*)$/.exec(pathname);
+  return !!prefixed && (PREVIEW_VISITOR_API_PATHS as readonly string[]).includes(prefixed[1]!);
+}
+
+/** Any `/api/` route, bare or tenant-prefixed. */
+export function isApiPath(pathname: string): boolean {
+  if (pathname === "/api" || pathname.startsWith("/api/")) return true;
+  return /^\/[^/]+\/api(?:\/|$)/.test(pathname);
+}
+
 /**
  * Control surfaces a withheld visitor is sent straight to sign-in for, instead of the
  * "Coming soon" holding page: admin and the cockpit (with its `/dev` alias), in both the
@@ -327,8 +357,9 @@ export interface LoginGateInput {
    *
    * Available to EVERY tenant: previewing an unpublished storefront is platform
    * functionality, not a property of which tenant is being viewed. Passes the gate
-   * for PUBLIC CONTENT paths only; {@link isBypassPrivilegedPath} paths (admin,
-   * cockpit, /api) still require a real session.
+   * for PUBLIC CONTENT paths and {@link isPreviewVisitorApiPath} routes only; every
+   * other {@link isBypassPrivilegedPath} path (admin, cockpit, /api) still requires a
+   * real session.
    */
   previewTokenValid?: boolean;
   /** A verified, tenant-bound candidate content pin admits public content only. */
@@ -357,11 +388,12 @@ export function evaluateLoginGate(input: LoginGateInput): LoginGateDecision {
   // public content only. NEVER for admin/cockpit/api — that guard lives here (not
   // just in middleware) so /admin stays gated even if the flag is set upstream.
   if (input.qaBypass && !isBypassPrivilegedPath(input.pathname)) return { action: "pass" };
-  // Signed, tenant-bound preview grants admit public content only. Admin,
-  // cockpit, and API routes still require a session.
+  // Signed, tenant-bound preview grants admit public content and the side-effect-free
+  // visitor forms on it. Admin, cockpit, and every other API route still require a
+  // session.
   if (
     (input.previewTokenValid || input.candidatePinValid) &&
-    !isBypassPrivilegedPath(input.pathname)
+    (!isBypassPrivilegedPath(input.pathname) || isPreviewVisitorApiPath(input.pathname))
   ) {
     return { action: "pass" };
   }

package/apps/storefront/src/middleware/controlPlane.ts

@@ -23,6 +23,7 @@ import type {
 } from "@tot/public-runtime";
 import {
   evaluateLoginGate,
+  isApiPath,
   isAuthPath,
   isAdminPath,
   isSignInRedirectPath,
@@ -32,7 +33,7 @@ import {
 } from "@/lib/auth/loginGate";
 import { resolveAdminLanding, isAdminSelectPath } from "@/lib/auth/adminLanding";
 import { resolveAdminTenantMode } from "@/lib/adminTenantEnvelope";
-import { gatedHoldingResponse } from "@/lib/auth/gatePage";
+import { gatedApiResponse, gatedHoldingResponse } from "@/lib/auth/gatePage";
 import { readSession, KvSessionStore, SESSION_COOKIE } from "@/lib/auth/session";
 import { runRenderChain } from "./renderChain.js";
 import { resolveCandidateContentPin } from "./candidatePin.js";
@@ -191,9 +192,15 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
       if (isSignInRedirectPath(url.pathname)) {
         return context.redirect(decision.location, 303);
       }
+      // An API caller gets an honest 401, never a 200 page it would read as success.
+      if (isApiPath(url.pathname)) return gatedApiResponse(decision.location, request);
       // Withhold content but offer sign-in (carrying the intended destination).
       return gatedHoldingResponse(decision.location);
     }
+    // Admitted to a store that is not public on this host: by session, preview
+    // grant, or QA bypass. Visitor routes read this to stay side-effect-free for an
+    // audience that does not exist yet (see pages/api/newsletter.ts).
+    if (!tenantExempt) locals.storeNotPublic = true;
     if (admitted && viewerRecord) {
       // Surface the viewer's standing FOR THIS host's tenant as chrome, BOUND to
       // the host: a member sees their tenants[] role; the owner of their own tenant

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

@@ -1,29 +1,83 @@
 /**
- * Newsletter signup endpoint.
+ * Newsletter signup endpoint — the footer and homepage capture forms post here.
  *
- * ASSUMPTION (Phase 1): there is no ESP integration yet. We persist the email to
+ * ASSUMPTION (Phase 1): there is no ESP integration yet. We persist the signup to
  * the TENANT_CACHE KV namespace when the Cloudflare runtime binding is present
- * (key `newsletter:<email>`), and otherwise just log. Wiring a real ESP
- * (Klaviyo/Mailchimp) is a documented Phase 2 swap at the marked spot below.
+ * (key `newsletter:<tenant_id>:<email>`). Wiring a real ESP (Klaviyo/Mailchimp) is a
+ * documented Phase 2 swap at the marked spot below.
  *
- * Robustness: a signup must NEVER 500. All failures degrade to a friendly
- * thank-you so the visitor is never shown an error for handing us their email.
+ * A store that is not public yet (`locals.storeNotPublic` — a preview, a staged
+ * release, an owner browsing before cutover) has no audience, so a submission there
+ * records nothing and says so.
+ *
+ * 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.
  */
 import type { APIContext } from "astro";
 import { readKv } from "@/lib/env";
+import { withBase } from "@/lib/basePath";
 
 // Minimal, permissive email shape check — we are not the source of truth for
 // deliverability; the ESP validates properly downstream.
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
-function thankYou(message: string, status = 200): Response {
+export type NewsletterStatus = "subscribed" | "preview" | "invalid";
+
+const COPY: Record<NewsletterStatus, { heading: string; message: string }> = {
+  subscribed: {
+    heading: "You're on the list.",
+    message: "We'll send word when something worth knowing lands.",
+  },
+  preview: {
+    heading: "Newsletter is off in preview.",
+    message:
+      "This store isn't public yet, so no subscription was recorded. The form works the same way once the store is live.",
+  },
+  invalid: {
+    heading: "That didn't go through.",
+    message: "That address didn't look quite right — head back and try again.",
+  },
+};
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (ch) => `&#${ch.charCodeAt(0)};`);
+}
+
+/** Where "back" goes: the submitting page when it is on this origin, else the store root. */
+function backHref(context: APIContext): string {
+  const home = withBase(context.locals.basePath ?? "", "/");
+  const referer = context.request.headers.get("referer");
+  if (!referer) return home;
+  try {
+    const back = new URL(referer);
+    return back.origin === new URL(context.request.url).origin
+      ? `${back.pathname}${back.search}${back.hash}`
+      : home;
+  } catch {
+    return home;
+  }
+}
+
+function wantsJson(request: Request): boolean {
+  return (request.headers.get("accept") ?? "").includes("application/json");
+}
+
+function respond(context: APIContext, status: NewsletterStatus): Response {
+  if (wantsJson(context.request)) {
+    return new Response(JSON.stringify({ ok: status !== "invalid", status }), {
+      status: 200,
+      headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+    });
+  }
+  const { heading, message } = COPY[status];
   const html = `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="robots" content="noindex" />
-    <title>Thank you</title>
+    <title>${escapeHtml(heading)}</title>
     <style>
       :root { color-scheme: light dark; }
       body { font-family: ui-serif, Georgia, serif; margin: 0; min-height: 100vh;
@@ -36,16 +90,16 @@ function thankYou(message: string, status = 200): Response {
     </style>
   </head>
   <body>
-    <div class="card">
-      <h1>You're on the list.</h1>
-      <p>${message}</p>
-      <p><a href="/">Back to the shop →</a></p>
+    <div class="card" data-newsletter-status="${status}">
+      <h1>${escapeHtml(heading)}</h1>
+      <p>${escapeHtml(message)}</p>
+      <p><a href="${escapeHtml(backHref(context))}">Back to the shop →</a></p>
     </div>
   </body>
 </html>`;
   return new Response(html, {
-    status,
-    headers: { "content-type": "text/html; charset=utf-8" },
+    status: 200,
+    headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
   });
 }
 
@@ -59,46 +113,32 @@ export async function POST(context: APIContext): Promise<Response> {
     const email = String(form.get("email") ?? "").trim().toLowerCase();
     const source = String(form.get("source") ?? "unknown").trim();
 
-    if (!EMAIL_RE.test(email)) {
-      return thankYou(
-        "That address didn't look quite right — head back and try again.",
-        200,
-      );
-    }
+    if (!EMAIL_RE.test(email)) return respond(context, "invalid");
+    if (context.locals.storeNotPublic) return respond(context, "preview");
 
     // Persist. Phase 1: KV stub. Phase 2: replace with an ESP API call here.
+    const tenantId = context.locals.tenant.tenant_id;
     const kv = await readKv("TENANT_CACHE");
     if (kv) {
       await kv.put(
-        `newsletter:${email}`,
+        `newsletter:${tenantId}:${email}`,
         JSON.stringify({ email, source, at: new Date().toISOString() }),
       );
     } else {
-      // No KV binding (local/dev): log and move on.
-      console.log(`[newsletter] signup ${email} (source: ${source})`);
-    }
-
-    // Redirect back where they came from (or home) with a success flag, so the
-    // page can show its own confirmation in-context. Falls back to the
-    // thank-you page if there's no usable referer.
-    const referer = context.request.headers.get("referer");
-    if (referer) {
-      try {
-        const back = new URL(referer);
-        back.searchParams.set("subscribed", "1");
-        return Response.redirect(back.toString(), 303);
-      } catch {
-        // fall through to thank-you
-      }
+      // No KV binding (local/dev): nothing to persist to.
+      console.log(`[newsletter] signup not persisted (no TENANT_CACHE) tenant=${tenantId} source=${source}`);
     }
-    return thankYou("We'll send word when something worth knowing lands.");
-  } catch {
-    // Never 500 on a signup.
-    return thankYou("We'll send word when something worth knowing lands.");
+    return respond(context, "subscribed");
+  } catch (err) {
+    // Never 500 on a signup, but never swallow the failure silently either.
+    console.error(
+      `[newsletter] signup failed tenant=${context.locals.tenant?.tenant_id ?? "?"}: ${err instanceof Error ? err.name : "unknown"}`,
+    );
+    return respond(context, "subscribed");
   }
 }
 
 export async function GET(context: APIContext): Promise<Response> {
   // Nothing to render here directly — bounce back to the shop.
-  return context.redirect("/", 303);
+  return context.redirect(withBase(context.locals.basePath ?? "", "/"), 303);
 }

package/package.json

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