@carrierllc/mcp 0.13.40 → 0.13.47

package/templates/storefront/src/lib/buyer-session.ts

@@ -0,0 +1,41 @@
+import { auth } from "@clerk/nextjs/server";
+
+/**
+ * Buyers share a Clerk instance that can leave a new session pending on
+ * choose-organization. Buyers have no organization, so that one task still
+ * counts as signed in. A session pending on password reset or MFA does not:
+ * it must not read orders.
+ */
+const BUYER_PENDING_TASK = "choose-organization";
+
+export function buyerPendingTasksAllowed(tasks: readonly string[]): boolean {
+  return tasks.length > 0 && tasks.every((task) => task === BUYER_PENDING_TASK);
+}
+
+export async function pendingSessionTasks(sessionId: string): Promise<string[] | null> {
+  const secretKey = process.env.CLERK_SECRET_KEY?.trim();
+  if (!secretKey) return null;
+  try {
+    const res = await fetch(`https://api.clerk.com/v1/sessions/${encodeURIComponent(sessionId)}`, {
+      headers: { Authorization: `Bearer ${secretKey}` },
+      cache: "no-store",
+    });
+    if (!res.ok) return null;
+    const session = (await res.json()) as { status?: unknown; tasks?: unknown };
+    if (session.status !== "pending" || !Array.isArray(session.tasks)) return null;
+    return session.tasks.map((task) => String((task as { key?: unknown } | null)?.key ?? ""));
+  } catch {
+    return null;
+  }
+}
+
+/** Signed-in buyer id, including a session whose only pending task is choose-organization. */
+export async function buyerUserId(): Promise<string | null> {
+  const { userId, sessionId, sessionStatus } = await auth({ treatPendingAsSignedOut: false });
+  if (!userId) return null;
+  if (sessionStatus !== "pending") return userId;
+  if (!sessionId) return null;
+  const tasks = await pendingSessionTasks(sessionId);
+  if (!tasks || !buyerPendingTasksAllowed(tasks)) return null;
+  return userId;
+}

package/templates/storefront/src/lib/catalog-countries.ts

@@ -0,0 +1,179 @@
+/**
+ * ISO country codes for the plans this template can sell today.
+ *
+ * The 44 Europe codes and the 44 destination codes are the countries the
+ * current shop sells. Together they are 88, with no overlap. The 160+ bar
+ * is a catalog decision and is not filled in here.
+ *
+ * Those codes belong to the eSIMMY shop. Other storefronts keep whatever
+ * coverage the plan already lists. Set NEXT_PUBLIC_COUNTRY_CATALOG=esimmy
+ * to expand Europe, Schengen and Global to this list.
+ */
+
+export const ESIMMY_EUROPE_CODES = [
+  "AL", "AD", "AT", "BE", "BA", "BG", "HR", "CY", "CZ", "DK",
+  "EE", "FO", "FI", "FR", "GE", "DE", "GI", "GR", "HU", "IS",
+  "IE", "IT", "LV", "LI", "LT", "LU", "MT", "MD", "ME", "NL",
+  "MK", "NO", "PL", "PT", "RO", "RS", "SK", "SI", "ES", "SE",
+  "CH", "TR", "UA", "GB",
+] as const;
+
+/** The 26 countries the Schengen sample plan advertises. All sit inside Europe. */
+export const ESIMMY_SCHENGEN_CODES = [
+  "AT", "BE", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU",
+  "IS", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL",
+  "PT", "SK", "SI", "ES", "SE", "CH",
+] as const;
+
+export const ESIMMY_DESTINATION_CODES = [
+  "AR", "AU", "BH", "BR", "KH", "CA", "CL", "CN", "CO", "CR",
+  "FJ", "HK", "IN", "ID", "IL", "JM", "JP", "JO", "KE", "KW",
+  "LA", "MY", "MV", "MU", "MX", "NP", "NZ", "OM", "PA", "PE",
+  "PH", "QA", "SA", "SG", "ZA", "KR", "LK", "TW", "TZ", "TH",
+  "TN", "AE", "US", "VN",
+] as const;
+
+export const ESIMMY_SOLD_COUNTRY_CODES: readonly string[] = [
+  ...ESIMMY_EUROPE_CODES,
+  ...ESIMMY_DESTINATION_CODES,
+];
+
+const REGION_LABELS: Record<string, readonly string[]> = {
+  europe: ESIMMY_EUROPE_CODES,
+  schengen: ESIMMY_SCHENGEN_CODES,
+  global: ESIMMY_SOLD_COUNTRY_CODES,
+};
+
+export type CountryCatalogMode = "plan" | "esimmy";
+
+/** Empty and anything other than `esimmy` keep the plan's own coverage. */
+export function countryCatalogMode(raw: string | undefined): CountryCatalogMode {
+  return raw?.trim().toLowerCase() === "esimmy" ? "esimmy" : "plan";
+}
+
+const regionNames = new Intl.DisplayNames(["en"], { type: "region" });
+const NAME_TO_CODE = new Map<string, string>();
+
+for (const code of ESIMMY_SOLD_COUNTRY_CODES) {
+  try {
+    const label = regionNames.of(code);
+    if (label && label.toUpperCase() !== code) NAME_TO_CODE.set(fold(label), code);
+  } catch {
+    // A runtime without that region still accepts the code itself.
+  }
+}
+
+NAME_TO_CODE.set("uk", "GB");
+NAME_TO_CODE.set("united kingdom", "GB");
+NAME_TO_CODE.set("czech republic", "CZ");
+NAME_TO_CODE.set("uae", "AE");
+NAME_TO_CODE.set("united arab emirates", "AE");
+NAME_TO_CODE.set("usa", "US");
+NAME_TO_CODE.set("united states", "US");
+NAME_TO_CODE.set("south korea", "KR");
+NAME_TO_CODE.set("korea", "KR");
+NAME_TO_CODE.set("holland", "NL");
+NAME_TO_CODE.set("turkey", "TR");
+
+function fold(value: string): string {
+  return value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").trim().toLowerCase();
+}
+
+function addCode(out: string[], seen: Set<string>, code: string): void {
+  if (!/^[A-Z]{2}$/.test(code) || code === "ZZ" || seen.has(code)) return;
+  seen.add(code);
+  out.push(code);
+}
+
+function keepToken(out: string[], seen: Set<string>, token: string): void {
+  if (seen.has(token)) return;
+  seen.add(token);
+  out.push(token);
+}
+
+/**
+ * Turn a plan's coverage into the codes the shop can search.
+ *
+ * `plan` (the default) keeps the plan's own words. Europe stays Europe.
+ * `esimmy` expands Europe, Schengen and Global to that shop's country list.
+ * A two-letter code or a country the plan names is kept either way.
+ */
+export function resolvePlanRegions(
+  regions: readonly string[],
+  mode: CountryCatalogMode = "plan",
+): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of regions) {
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+    const upper = trimmed.toUpperCase();
+    if (upper === "UK") {
+      addCode(out, seen, "GB");
+      continue;
+    }
+    if (/^[A-Z]{2}$/.test(upper)) {
+      addCode(out, seen, upper);
+      continue;
+    }
+    const labelled = REGION_LABELS[fold(trimmed)];
+    if (labelled) {
+      if (mode === "esimmy") {
+        for (const code of labelled) addCode(out, seen, code);
+      } else {
+        keepToken(out, seen, trimmed);
+      }
+      continue;
+    }
+    const named = NAME_TO_CODE.get(fold(trimmed));
+    if (named) addCode(out, seen, named);
+    else keepToken(out, seen, trimmed);
+  }
+  return out;
+}
+
+export function withCountryCodes<T extends { regions?: readonly string[] | null }>(
+  plans: readonly T[],
+  mode: CountryCatalogMode = "plan",
+): T[] {
+  return plans.map((plan) => ({
+    ...plan,
+    regions: resolvePlanRegions(Array.isArray(plan.regions) ? plan.regions : [], mode),
+  }));
+}
+
+/**
+ * Country search is honest only when every plan is already a list of countries.
+ *
+ * A region word such as Europe is not a country. In plan mode this template
+ * does not invent the eSIMMY list for that word, so search would tell a buyer
+ * that Germany is uncovered. Hide search and show the plans instead.
+ * `esimmy` has already expanded those words, so search can stay.
+ */
+export function catalogCanSearchCountries(
+  plans: readonly { regions?: readonly string[] | null }[],
+  mode: CountryCatalogMode,
+): boolean {
+  if (mode === "esimmy") return true;
+  return plans.every((plan) =>
+    (plan.regions ?? []).every((region) => REGION_LABELS[fold(region.trim())] === undefined),
+  );
+}
+
+/** Plans to show for a country query. Region plans are not filtered down to none. */
+export function plansForCountry<T extends { regions?: readonly string[] | null }>(
+  plans: readonly T[],
+  country: string,
+  mode: CountryCatalogMode,
+): { plans: T[]; search: boolean; code: string } {
+  const search = catalogCanSearchCountries(plans, mode);
+  const code = search && /^[A-Za-z]{2}$/.test(country) ? country.toUpperCase() : "";
+  if (!code) return { plans: [...plans], search, code };
+  return {
+    search,
+    code,
+    plans: plans.filter((plan) =>
+      (plan.regions ?? []).some((region) => region.toUpperCase() === code),
+    ),
+  };
+}

package/templates/storefront/src/lib/checkout-client-error.ts

@@ -0,0 +1,28 @@
+/**
+ * Buyer copy for the checkout screen.
+ *
+ * Browser and JSON parser messages are never shown. A coded refusal may
+ * carry its own allow-listed sentence; everything else uses the fallback.
+ */
+
+export const GENERIC_CHECKOUT_ERROR = "Checkout is unavailable right now. Please try again in a moment.";
+
+export class BuyerCopyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BuyerCopyError";
+  }
+}
+
+export function checkoutErrorCopy(err: unknown): string {
+  if (err instanceof BuyerCopyError && err.message.length > 0) return err.message;
+  return GENERIC_CHECKOUT_ERROR;
+}
+
+export async function readCheckoutJson(res: { json: () => Promise<unknown> }): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}

package/templates/storefront/src/lib/checkout-copy.ts

@@ -0,0 +1,89 @@
+/**
+ * Buyer-facing confirmation copy.
+ *
+ * The order reference is a short tail of the Checkout Session id. The full
+ * `cs_` value stays in the activate URL and is never drawn on the page.
+ * Claim failures are chosen from this allow-list by HTTP status. The response
+ * body is never buyer copy.
+ */
+
+const CLAIM_ERROR_FALLBACK = "We could not link this purchase to your account. Your payment is unchanged.";
+
+const CLAIM_ERROR_COPY: Record<number, string> = {
+  400: CLAIM_ERROR_FALLBACK,
+  401: "Sign in again to link this purchase. Your payment is unchanged.",
+  403: "This purchase is linked to a different email. Your payment is unchanged.",
+  502: "We could not link this purchase right now. Your payment is unchanged.",
+};
+
+const ACCOUNT_STEP_FALLBACK = "We could not finish this step. Your payment is unchanged.";
+
+/**
+ * Clerk error codes the buyer can act on, with copy we own. Only the `code` is
+ * read, never Clerk's message text, so an unknown or reworded Clerk error
+ * degrades to the generic line instead of leaking provider text.
+ */
+const ACCOUNT_STEP_COPY: Record<string, string> = {
+  form_identifier_exists: "An account with this email already exists. Choose Sign in instead.",
+  form_password_pwned: "That password has appeared in a data breach. Choose a different password.",
+  form_password_length_too_short: "Use a password of at least 8 characters.",
+  form_password_not_strong_enough: "That password is too easy to guess. Add length or mix in numbers and symbols.",
+  form_password_size_in_bytes_exceeded: "That password is too long. Choose a shorter one.",
+  form_code_incorrect: "That code is not right. Check the email and try again.",
+  verification_expired: "That code has expired. Go back and create the account again to get a new one.",
+  verification_failed: "We could not verify that code. Check the email and try again.",
+  form_identifier_not_found: "Email or password is not right. Try again or create an account.",
+  form_password_incorrect: "Email or password is not right. Try again or create an account.",
+  too_many_requests: "Too many attempts. Wait a minute and try again.",
+  session_exists: "You are already signed in. Refresh this page to continue.",
+};
+
+/** Buyer copy for a failed Clerk sign-up or sign-in step, chosen by error code. */
+export function accountStepError(err: unknown): string {
+  const errors = (err as { errors?: unknown } | null | undefined)?.errors;
+  if (Array.isArray(errors)) {
+    for (const entry of errors) {
+      const code = (entry as { code?: unknown } | null)?.code;
+      if (typeof code === "string" && Object.prototype.hasOwnProperty.call(ACCOUNT_STEP_COPY, code)) {
+        return ACCOUNT_STEP_COPY[code];
+      }
+    }
+  }
+  return ACCOUNT_STEP_FALLBACK;
+}
+
+export function shortOrderReference(orderId: string): string {
+  const stripped = orderId.replace(/^cs_(?:test|live)_/i, "");
+  const alnum = stripped.replace(/[^A-Za-z0-9]/g, "");
+  const tail = alnum.slice(-6).toUpperCase();
+  return tail.length > 0 ? tail : "------";
+}
+
+export function buyerFacingError(status: number): string {
+  return CLAIM_ERROR_COPY[status] ?? CLAIM_ERROR_FALLBACK;
+}
+
+type ConfirmationTitleInput =
+  | "mock"
+  | { ok: true }
+  | { ok: false; status: "processing" | "unpaid" | "unavailable" | "rejected" };
+
+/** Document title for a confirmation outcome. Only a settled session is confirmed. */
+export function confirmationDocumentTitle(outcome: ConfirmationTitleInput): string {
+  if (outcome === "mock") return "Payment was not completed";
+  if (outcome.ok) return "Payment confirmed";
+  switch (outcome.status) {
+    case "processing":
+      return "Payment processing";
+    case "unpaid":
+      return "Payment did not go through";
+    case "unavailable":
+      return "We couldn't confirm your payment yet";
+    case "rejected":
+      return "Payment could not be confirmed";
+    default: {
+      const unhandled: never = outcome.status;
+      return unhandled;
+    }
+  }
+}

package/templates/storefront/src/lib/checkout-order-claim.ts

@@ -1,4 +1,5 @@
 import { clerkClient } from "@clerk/nextjs/server";
+import { buyerFacingError } from "@/lib/checkout-copy";
 import { verifyCheckoutSession } from "@/lib/verify-checkout-session";
 
 type StripeSession = {
@@ -156,7 +157,7 @@ export async function claimCheckoutOrder(
 ): Promise<{ ok: true; orderId: string } | { ok: false; status: number; error: string }> {
   const verification = await verifyCheckoutSession(sessionId, templateId);
   if (!verification.ok) {
-    return { ok: false, status: 400, error: "Invalid or unpaid checkout session" };
+    return { ok: false, status: 400, error: buyerFacingError(400) };
   }
 
   const orderId = verification.orderId;
@@ -164,11 +165,11 @@ export async function claimCheckoutOrder(
   if (sessionId !== "mock" && process.env.STRIPE_SECRET_KEY) {
     const session = await fetchStripeSession(sessionId);
     if (!session) {
-      return { ok: false, status: 400, error: "Invalid or unpaid checkout session" };
+      return { ok: false, status: 400, error: buyerFacingError(400) };
     }
 
     if (!(await userMatchesSessionPurchaser(session, userId))) {
-      return { ok: false, status: 403, error: "This order is linked to another account" };
+      return { ok: false, status: 403, error: buyerFacingError(403) };
     }
 
     const claimedBy = session.metadata?.claimedByUserId;
@@ -191,11 +192,11 @@ export async function claimCheckoutOrder(
        */
       const moved = await setStripeClaimedBy(sessionId, userId);
       if (!moved) {
-        return { ok: false, status: 502, error: "Failed to claim order" };
+        return { ok: false, status: 502, error: buyerFacingError(502) };
       }
       const afterMove = await fetchStripeSession(sessionId);
       if (afterMove?.metadata?.claimedByUserId !== userId) {
-        return { ok: false, status: 403, error: "This order is linked to another account" };
+        return { ok: false, status: 403, error: buyerFacingError(403) };
       }
 
       // Best-effort tidy-up. The order is already on the right account; a
@@ -209,12 +210,12 @@ export async function claimCheckoutOrder(
     if (!claimedBy) {
       const updated = await setStripeClaimedBy(sessionId, userId);
       if (!updated) {
-        return { ok: false, status: 502, error: "Failed to claim order" };
+        return { ok: false, status: 502, error: buyerFacingError(502) };
       }
 
       const afterClaim = await fetchStripeSession(sessionId);
       if (afterClaim?.metadata?.claimedByUserId !== userId) {
-        return { ok: false, status: 403, error: "This order is linked to another account" };
+        return { ok: false, status: 403, error: buyerFacingError(403) };
       }
     }
   }

package/templates/storefront/src/lib/checkout-return.ts

@@ -0,0 +1,18 @@
+/**
+ * What the buyer should see when they land on the return URL.
+ *
+ * `session_id=mock` is the old no-Stripe shortcut. It is an error: no money
+ * moved and no eSIM was issued. A paid Stripe session is a confirmation.
+ */
+export interface CheckoutProblem {
+  title: string;
+  message: string;
+}
+
+export function mockSessionProblem(sessionId: string | undefined): CheckoutProblem | null {
+  if (sessionId !== "mock") return null;
+  return {
+    title: "Payment was not completed",
+    message: "This checkout did not take a payment, and no eSIM was issued.",
+  };
+}

package/templates/storefront/src/lib/clerk-instance.ts

@@ -0,0 +1,89 @@
+/**
+ * Which Clerk instance this storefront talks to.
+ *
+ * `dev` is the default and the only instance this template configures.
+ * `production` is a switch: it reads a different pair of key names and does
+ * not create, fetch, or modify a Clerk application. Leave those keys empty
+ * until a production instance is approved.
+ */
+
+export type ClerkInstanceMode = "dev" | "production";
+
+export interface ClerkKeyNames {
+  publishable: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY" | "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY_PRODUCTION";
+  secret: "CLERK_SECRET_KEY" | "CLERK_SECRET_KEY_PRODUCTION";
+}
+
+function blankToUndefined(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function clerkInstanceMode(raw: string | undefined): ClerkInstanceMode {
+  return raw?.trim().toLowerCase() === "production" ? "production" : "dev";
+}
+
+export function clerkKeyNames(mode: ClerkInstanceMode): ClerkKeyNames {
+  switch (mode) {
+    case "production":
+      return {
+        publishable: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY_PRODUCTION",
+        secret: "CLERK_SECRET_KEY_PRODUCTION",
+      };
+    case "dev":
+      return {
+        publishable: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+        secret: "CLERK_SECRET_KEY",
+      };
+    default: {
+      const neverMode: never = mode;
+      return neverMode;
+    }
+  }
+}
+
+export function clerkKeyFrom(
+  mode: ClerkInstanceMode,
+  keys: { dev?: string; production?: string },
+): string | undefined {
+  switch (mode) {
+    case "production":
+      return blankToUndefined(keys.production);
+    case "dev":
+      return blankToUndefined(keys.dev);
+    default: {
+      const neverMode: never = mode;
+      return neverMode;
+    }
+  }
+}
+
+/** Publishable key for the active instance. Static env reads so Next can inline them. */
+export function clerkPublishableKey(): string | undefined {
+  return clerkKeyFrom(clerkInstanceMode(process.env.NEXT_PUBLIC_CLERK_INSTANCE), {
+    dev: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
+    production: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY_PRODUCTION,
+  });
+}
+
+/** Secret key for the active instance. Server only. */
+export function clerkSecretKey(): string | undefined {
+  return clerkKeyFrom(clerkInstanceMode(process.env.NEXT_PUBLIC_CLERK_INSTANCE), {
+    dev: process.env.CLERK_SECRET_KEY,
+    production: process.env.CLERK_SECRET_KEY_PRODUCTION,
+  });
+}
+
+/**
+ * Point Clerk's own env names at the production pair when the switch is on.
+ *
+ * @clerk/nextjs reads `CLERK_SECRET_KEY` itself. Dev mode leaves both names
+ * untouched, so a production key sitting in the environment is not used.
+ */
+export function applyClerkInstanceEnv(): void {
+  if (clerkInstanceMode(process.env.NEXT_PUBLIC_CLERK_INSTANCE) !== "production") return;
+  const publishable = blankToUndefined(process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY_PRODUCTION);
+  const secret = blankToUndefined(process.env.CLERK_SECRET_KEY_PRODUCTION);
+  if (publishable) process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY = publishable;
+  if (secret) process.env.CLERK_SECRET_KEY = secret;
+}

package/templates/storefront/src/lib/order-reference.ts

@@ -0,0 +1,15 @@
+/**
+ * A short label a buyer can quote.
+ *
+ * The dashboard must not print a full checkout session id (`cs_…`).
+ */
+export function shortOrderReference(orderId: string): string {
+  const body = orderId.replace(/^cs_(?:test_|live_)?/i, "");
+  const tail = body.replace(/[^a-zA-Z0-9]/g, "").slice(-4).toUpperCase();
+  return tail.length > 0 ? `Order ${tail}` : "Order";
+}
+
+/** The full checkout id stays in the subject. The link text does not include it. */
+export function supportOrderHref(email: string, orderId: string): string {
+  return `mailto:${email}?subject=${encodeURIComponent(`Order ${orderId}`)}`;
+}

package/templates/storefront/src/lib/request-origin.ts

@@ -0,0 +1,28 @@
+/**
+ * Origin used to keep a sign-in return path on this shop.
+ *
+ * Built from the request, not from the browser. `NEXT_PUBLIC_APP_URL` wins
+ * when it is set. Otherwise the forwarded host on this request is used.
+ */
+export function requestOrigin(headerStore: { get(name: string): string | null }): string {
+  const configured = process.env.NEXT_PUBLIC_APP_URL?.trim();
+  if (configured) {
+    try {
+      return new URL(configured).origin;
+    } catch {
+      // A bad configured URL falls through to the request host.
+    }
+  }
+  const host = firstHeader(headerStore.get("x-forwarded-host") ?? headerStore.get("host"));
+  if (!host) return "";
+  const proto = firstHeader(headerStore.get("x-forwarded-proto")) || "https";
+  try {
+    return new URL(`${proto}://${host}`).origin;
+  } catch {
+    return "";
+  }
+}
+
+function firstHeader(value: string | null): string {
+  return value?.split(",")[0]?.trim() ?? "";
+}

package/templates/storefront/src/lib/sanitize-auth-redirect.ts

@@ -1,15 +1,31 @@
 const ALLOWED_PATHS = /^\/[a-zA-Z0-9\-._~:/?#[\]@!$&'()*+,;=%]*$/;
 
+/**
+ * Keep a buyer on the path they asked for.
+ *
+ * A path stays a path. Clerk sometimes sends a same-origin absolute URL;
+ * `new URL` accepts that only when the origin matches. Anything else,
+ * including another host, falls back.
+ */
 export function sanitizeAuthRedirect(
   rawRedirect: string | null | undefined,
   fallback = "/dashboard",
+  origin?: string,
 ): string {
   if (!rawRedirect) return fallback;
+  const raw = rawRedirect.trim();
+  if (!raw || raw.startsWith("//")) return fallback;
   try {
-    // Reject absolute URLs and protocol-relative
-    if (rawRedirect.startsWith("//") || rawRedirect.includes(":")) return fallback;
-    if (!ALLOWED_PATHS.test(rawRedirect)) return fallback;
-    return rawRedirect;
+    if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(raw)) {
+      if (!origin) return fallback;
+      const url = new URL(raw);
+      if (url.origin !== new URL(origin).origin) return fallback;
+      const path = `${url.pathname}${url.search}${url.hash}`;
+      if (!path.startsWith("/") || path.startsWith("//")) return fallback;
+      return path;
+    }
+    if (!ALLOWED_PATHS.test(raw)) return fallback;
+    return raw;
   } catch {
     return fallback;
   }

package/templates/storefront/src/lib/tap-target.ts

@@ -0,0 +1,17 @@
+/**
+ * 16px type so a phone does not zoom the page on focus.
+ * 44px tall so a thumb can hit the control.
+ */
+export const fieldClass =
+  "w-full min-h-11 rounded-lg border border-sand-200 bg-sand-50 px-3 text-base text-sand-900 placeholder:text-sand-400 focus:border-[var(--brand-accent-text)] dark:border-sand-800 dark:bg-sand-950 dark:text-sand-50";
+
+/** Filled #FF6B35. The label is #111111, never white. */
+export const primaryButtonClass =
+  "inline-flex min-h-11 w-full items-center justify-center rounded-lg bg-[var(--brand-accent)] px-4 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90 disabled:opacity-50";
+
+/** Accent text and links use #C2410C on light surfaces. */
+export const textLinkClass =
+  "inline-flex min-h-11 items-center text-base font-semibold text-[var(--brand-accent-text)] hover:underline";
+
+export const filledAccentClass =
+  "inline-flex min-h-11 items-center justify-center rounded-full bg-[var(--brand-accent)] px-4 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90";