@tribe-nest/forge 3.17.0 → 3.20.0

package/src/ui/styled/CourseAccess.tsx

@@ -1,85 +1,216 @@
-import { useRef, useState } from "react";
-import { useCourseAccess, useUpdateCourseProgress } from "../../data/queries/useCourseAccess";
-import { useForgeTheme } from "../theme/ForgeThemeProvider";
+import type { CSSProperties } from "react";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { useCourseClassroom, type UseCourseClassroomOptions } from "../headless/course/useCourseClassroom";
 import { Loading } from "./Loading";
 
-export interface CourseAccessProps {
+export interface CourseAccessProps extends UseCourseClassroomOptions {
   /** Course access id (route param). */
   accessId: string;
+  /** SPA navigation adapter for the sign-in / secure-access links. Defaults to a full-page visit. */
+  navigate?: (href: string) => void;
+  className?: string;
+  style?: CSSProperties;
 }
 
-/** Enrolled course player — module/lesson sidebar, video progress tracking. Built on `useCourseAccess` + `useUpdateCourseProgress`. */
-export function CourseAccess({ accessId }: CourseAccessProps) {
-  const theme = useForgeTheme();
-  const { data, isLoading, error } = useCourseAccess(accessId);
-  const updateProgress = useUpdateCourseProgress(accessId);
-  const lastSent = useRef(0);
+/**
+ * Enrolled course player — module/lesson sidebar, video progress tracking, and
+ * the account-binding gate that stands in front of both. Built on the headless
+ * `useCourseClassroom`.
+ *
+ * The three states worth naming, because each one strands somebody if it is
+ * drawn as the others:
+ *
+ *   - **401** — a bound grant opened with no session. Almost always the buyer,
+ *     on an old email link, on a device that never signed in. Gets a sign-in
+ *     button that returns HERE, never a dead end.
+ *   - **403** — a bound grant opened as somebody else. Gets "this belongs to a
+ *     different account" and a way OUT of the current session. Never the word
+ *     "sign in", which they have already done.
+ *   - **legacy** — no `account_id`, so the link alone is the credential. Opens
+ *     normally, with a dismissible note offering to put it behind an account.
+ */
+export function CourseAccess({
+  accessId,
+  navigate,
+  className,
+  style,
+  ...classroomOptions
+}: CourseAccessProps) {
+  const t = useThemeTokens();
+  const classroom = useCourseClassroom(accessId, classroomOptions);
+  const go = navigate ?? ((href: string) => window.location.assign(href));
 
-  const modules = data?.course.modules ?? [];
-  const allLessons = modules.flatMap((m) => m.lessons);
-  const initialLessonId = data?.access.currentLessonId || allLessons[0]?.id || null;
-  const [selectedLessonId, setSelectedLessonId] = useState<string | null>(initialLessonId);
+  if (classroom.isLoading) return <Loading fullPage />;
 
-  if (isLoading) return <Loading fullPage />;
-  if (error || !data) return <p style={{ color: theme.colors.text }}>Course access not found.</p>;
+  const panel: CSSProperties = {
+    maxWidth: 520,
+    margin: "0 auto",
+    padding: 28,
+    borderRadius: t.cornerRadius,
+    border: `1px solid ${t.border}`,
+    background: t.surface,
+    color: t.text,
+    textAlign: "center",
+    display: "flex",
+    flexDirection: "column",
+    gap: 12,
+    fontFamily: t.fontFamily,
+  };
+
+  const primaryButton: CSSProperties = {
+    alignSelf: "center",
+    padding: "10px 20px",
+    borderRadius: t.cornerRadius,
+    border: "none",
+    background: t.primary,
+    color: t.textPrimary,
+    fontSize: 14,
+    fontWeight: 700,
+    cursor: "pointer",
+    textDecoration: "none",
+  };
+
+  const gate = classroom.gate;
+  if (gate) {
+    return (
+      <div className={className} style={{ ...panel, ...style }}>
+        <h1 style={{ fontSize: 20, fontWeight: 800, fontFamily: t.headingFontFamily || t.fontFamily }}>
+          {gate.title}
+        </h1>
+        <p style={{ fontSize: 14, color: t.muted, lineHeight: 1.6 }}>{gate.body}</p>
+
+        {/* Naming the session they are in is what makes "wrong account"
+            actionable — otherwise the reader has no idea which of their
+            addresses they are currently signed in with. */}
+        {gate.kind === "wrong_account" && classroom.signedInEmail && (
+          <p style={{ fontSize: 13, color: t.muted }}>
+            Signed in as <strong style={{ color: t.text }}>{classroom.signedInEmail}</strong>
+          </p>
+        )}
+
+        {gate.actionLabel && gate.actionHref && (
+          <button type="button" style={primaryButton} onClick={() => go(gate.actionHref!)}>
+            {gate.actionLabel}
+          </button>
+        )}
 
-  const selected = allLessons.find((l) => l.id === selectedLessonId) ?? allLessons[0];
+        {gate.actionLabel && !gate.actionHref && (
+          <button type="button" style={primaryButton} onClick={() => void classroom.signOutAndRetry()}>
+            {gate.actionLabel}
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  const data = classroom.data;
+  if (!data) return null;
+
+  const selected = classroom.selected;
   const videoUrl = selected?.media?.find((m) => m.type === "video")?.url;
   const files = selected?.media?.filter((m) => m.type !== "video") ?? [];
-  const completedCount = allLessons.filter((l) => l.progress?.isCompleted).length;
-
-  const handleTimeUpdate = (e: React.SyntheticEvent<HTMLVideoElement>) => {
-    const el = e.currentTarget;
-    if (!selected || !el.duration) return;
-    const now = Date.now();
-    if (now - lastSent.current < 1000) return;
-    lastSent.current = now;
-    const percent = (el.currentTime / el.duration) * 100;
-    const isCompleted = percent >= 95;
-    updateProgress.mutate({ lessonId: selected.id, videoProgress: percent, isCompleted });
-  };
+  const securePrompt = classroom.securePrompt;
 
   return (
     <div
+      className={className}
       style={{
         display: "flex",
         flexDirection: "column",
         gap: 24,
         maxWidth: 1100,
         margin: "0 auto",
-        color: theme.colors.text,
+        color: t.text,
+        fontFamily: t.fontFamily,
+        ...style,
       }}
     >
+      {/* Legacy grant, opened fine. An offer, not an obstacle — inline, muted,
+          dismissible, and never in front of the course the reader came for. */}
+      {securePrompt && (
+        <div
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            alignItems: "center",
+            gap: 12,
+            padding: "10px 14px",
+            borderRadius: t.cornerRadius,
+            border: `1px solid ${t.border}`,
+            background: `${t.primary}0d`,
+            fontSize: 13,
+          }}
+        >
+          <span style={{ flex: "1 1 260px", color: t.muted, lineHeight: 1.5 }}>
+            Anyone with this link can open your course. Create an account with{" "}
+            <strong style={{ color: t.text }}>{securePrompt.email}</strong> to keep it to yourself.
+          </span>
+          <button
+            type="button"
+            onClick={() => go(securePrompt.href)}
+            style={{
+              padding: "6px 14px",
+              borderRadius: t.cornerRadius,
+              border: `1px solid ${t.primary}`,
+              background: "transparent",
+              color: t.primary,
+              fontSize: 13,
+              fontWeight: 600,
+              cursor: "pointer",
+            }}
+          >
+            Secure my access
+          </button>
+          <button
+            type="button"
+            onClick={classroom.dismissSecurePrompt}
+            aria-label="Dismiss"
+            style={{
+              padding: "6px 10px",
+              border: "none",
+              background: "transparent",
+              color: t.muted,
+              fontSize: 13,
+              cursor: "pointer",
+            }}
+          >
+            Not now
+          </button>
+        </div>
+      )}
+
       <header>
-        <h1 style={{ fontSize: 26, fontWeight: 800 }}>{data.course.title}</h1>
-        <p style={{ fontSize: 14, opacity: 0.7 }}>
-          {completedCount} of {allLessons.length} lessons completed
+        <h1 style={{ fontSize: 26, fontWeight: 800, fontFamily: t.headingFontFamily || t.fontFamily }}>
+          {data.course.title}
+        </h1>
+        <p style={{ fontSize: 14, color: t.muted }}>
+          {classroom.completedCount} of {classroom.lessons.length} lessons completed
         </p>
       </header>
 
       <div style={{ display: "flex", gap: 24, flexWrap: "wrap" }}>
         {/* Sidebar */}
         <aside style={{ flex: "1 1 260px", minWidth: 240 }}>
-          {modules.map((module) => (
+          {classroom.modules.map((module) => (
             <div key={module.id} style={{ marginBottom: 16 }}>
               <h2 style={{ fontSize: 14, fontWeight: 700, marginBottom: 6 }}>{module.title}</h2>
               <div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
-                {module.lessons.map((lesson) => {
+                {(module.lessons ?? []).map((lesson) => {
                   const isSelected = lesson.id === selected?.id;
                   const done = lesson.progress?.isCompleted;
                   return (
                     <button
                       key={lesson.id}
-                      onClick={() => setSelectedLessonId(lesson.id)}
+                      onClick={() => classroom.selectLesson(lesson.id)}
                       style={{
                         textAlign: "left",
                         padding: "8px 10px",
-                        borderRadius: theme.cornerRadius,
+                        borderRadius: t.cornerRadius,
                         border: "none",
                         cursor: "pointer",
                         fontSize: 14,
-                        background: isSelected ? `${theme.colors.primary}20` : "transparent",
-                        color: isSelected ? theme.colors.primary : theme.colors.text,
+                        background: isSelected ? `${t.primary}20` : "transparent",
+                        color: isSelected ? t.primary : t.text,
                         fontWeight: isSelected ? 600 : 400,
                       }}
                     >
@@ -103,8 +234,8 @@ export function CourseAccess({ accessId }: CourseAccessProps) {
                   src={videoUrl}
                   controls
                   playsInline
-                  onTimeUpdate={handleTimeUpdate}
-                  style={{ width: "100%", aspectRatio: "16/9", background: "#000", borderRadius: theme.cornerRadius }}
+                  onTimeUpdate={(e) => classroom.reportProgress(e.currentTarget.currentTime, e.currentTarget.duration)}
+                  style={{ width: "100%", aspectRatio: "16/9", background: "#000", borderRadius: t.cornerRadius }}
                 />
               ) : (
                 <div
@@ -114,16 +245,25 @@ export function CourseAccess({ accessId }: CourseAccessProps) {
                     display: "flex",
                     alignItems: "center",
                     justifyContent: "center",
-                    background: `${theme.colors.text}0d`,
-                    borderRadius: theme.cornerRadius,
-                    opacity: 0.7,
+                    background: `${t.text}0d`,
+                    borderRadius: t.cornerRadius,
+                    color: t.muted,
                   }}
                 >
                   No video available for this lesson
                 </div>
               )}
 
-              <h2 style={{ fontSize: 20, fontWeight: 700, margin: "16px 0 8px" }}>{selected.title}</h2>
+              <h2
+                style={{
+                  fontSize: 20,
+                  fontWeight: 700,
+                  margin: "16px 0 8px",
+                  fontFamily: t.headingFontFamily || t.fontFamily,
+                }}
+              >
+                {selected.title}
+              </h2>
 
               {files.length > 0 && (
                 <div style={{ marginBottom: 16 }}>
@@ -139,16 +279,16 @@ export function CourseAccess({ accessId }: CourseAccessProps) {
                           display: "flex",
                           justifyContent: "space-between",
                           padding: "10px 12px",
-                          borderRadius: theme.cornerRadius,
-                          border: `1px solid ${theme.colors.primary}40`,
-                          background: `${theme.colors.primary}10`,
-                          color: theme.colors.text,
+                          borderRadius: t.cornerRadius,
+                          border: `1px solid ${t.border}`,
+                          background: `${t.primary}10`,
+                          color: t.text,
                           textDecoration: "none",
                           fontSize: 14,
                         }}
                       >
                         <span>{file.filename}</span>
-                        <span style={{ opacity: 0.6 }}>{(file.size / 1024 / 1024).toFixed(2)} MB</span>
+                        <span style={{ color: t.muted }}>{(file.size / 1024 / 1024).toFixed(2)} MB</span>
                       </a>
                     ))}
                   </div>
@@ -160,7 +300,7 @@ export function CourseAccess({ accessId }: CourseAccessProps) {
               )}
             </>
           ) : (
-            <p style={{ opacity: 0.7 }}>No lesson selected.</p>
+            <p style={{ color: t.muted }}>No lesson selected.</p>
           )}
         </main>
       </div>

package/src/ui/styled/CourseCheckout.tsx

@@ -28,7 +28,15 @@ export interface CourseCheckoutProps {
   formatAmount?: (amount: number) => string;
   /** Optional payment renderer — falls back to a registered <ForgePaymentProvider>. */
   renderPayment?: (props: PaymentRenderProps) => ReactNode;
-  /** Stripe return URL for a PAID enrollment. Default `/i/courses/:slug/finalise`. */
+  /**
+   * Stripe return URL for a PAID enrollment. Default `/i/courses/:slug/finalise`.
+   *
+   * Put ONLY the bookingId in this URL. The booking's secret is handled for you
+   * by the hook (stashed in `sessionStorage`, read back by `CourseConfirmation`)
+   * — putting it in the URL would hand it to history, referrers and shared
+   * links, which is the exact leak it exists to close. See
+   * `utils/bookingSecret`.
+   */
   finalisePath?: (slug: string, bookingId: string) => string;
   /** Host-owned navigation on FREE completion (e.g. router navigate). */
   onComplete?: (info: { slug: string; bookingId: string }) => void;

package/src/ui/styled/CourseConfirmation.tsx

@@ -3,9 +3,19 @@ import { useForgeTheme } from "../theme/ForgeThemeProvider";
 import { readableTextOn } from "../theme/contrast";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { Loading } from "./Loading";
-import { ConfirmationStage, ConfirmationCard, CheckSeal, WarnSeal, Perforation, ConfirmationRow, alpha } from "./Confirmation";
+import {
+  ConfirmationStage,
+  ConfirmationCard,
+  CheckSeal,
+  WarnSeal,
+  Perforation,
+  ConfirmationRow,
+  ConfirmationLostCheckout,
+  alpha,
+} from "./Confirmation";
 import { useCourseBookingFinalize } from "../../data/queries/useFinalize";
 import { useGetCourse } from "../../data/queries/useCourses";
+import { useBookingSecret } from "../headless/booking/useBookingSecret";
 
 export interface CourseConfirmationProps {
   slug: string;
@@ -14,6 +24,11 @@ export interface CourseConfirmationProps {
   formatAmount?: (n: number) => string;
   /** Where the "browse more courses" action links. */
   explorePath?: string;
+  /**
+   * Where "start over" goes when this browser has no credential for the booking
+   * — i.e. back to the course, to enroll again. Defaults to `/i/courses/:slug`.
+   */
+  restartPath?: string;
 }
 
 export function CourseConfirmation({
@@ -21,16 +36,25 @@ export function CourseConfirmation({
   bookingId,
   formatAmount,
   explorePath = "/i/courses",
+  restartPath,
 }: CourseConfirmationProps) {
   const theme = useForgeTheme();
   const fmt = useAmountFormatter(formatAmount);
-  const { data, isLoading, error } = useCourseBookingFinalize(slug, bookingId);
+  // The credential the checkout stashed before the payment redirect. `resolved`
+  // gates the finalise: storage can only be read on the client, so firing before
+  // then would send the call without a secret it actually has and get a 404.
+  const { secret, resolved, isMissing } = useBookingSecret(bookingId);
+  const { data, isLoading, error } = useCourseBookingFinalize(
+    slug,
+    resolved ? bookingId : undefined,
+    secret ?? undefined,
+  );
   const { data: course } = useGetCourse(slug);
 
   const text = theme.colors.text;
   const primary = theme.colors.primary;
 
-  if (isLoading) {
+  if (!resolved || isLoading) {
     return (
       <ConfirmationStage>
         <Loading label="Confirming your enrollment…" />
@@ -39,6 +63,21 @@ export function CourseConfirmation({
   }
 
   if (error || !data) {
+    // A booking with no credential in THIS browser is indistinguishable
+    // server-side from a stranger holding a leaked id, so it 404s on purpose.
+    // Explain that rather than implying the enrollment never existed.
+    if (isMissing) {
+      return (
+        <ConfirmationStage>
+          <ConfirmationLostCheckout
+            title="We can’t confirm your enrollment in this browser"
+            body="Confirming an enrollment needs the checkout details saved in the tab you started in — and they aren’t here. That usually means the tab was closed, this link was opened on a different device or browser, or private browsing cleared them. If your payment went through you’ll still get your enrollment email, so check your inbox before paying again. Otherwise, start the enrollment over."
+            restartPath={restartPath ?? `/i/courses/${slug}`}
+            restartLabel="Start over"
+          />
+        </ConfirmationStage>
+      );
+    }
     return (
       <ConfirmationStage>
         <p style={{ color: text }}>We couldn’t find your enrollment.</p>

package/src/ui/styled/InvoicePayment.tsx

@@ -1,13 +1,14 @@
 import { useInvoicePayment } from "../headless/invoice/useInvoicePayment";
 import { usePaymentRenderer } from "../payment/ForgePaymentProvider";
 import { useForgeTheme } from "../theme/ForgeThemeProvider";
-import { useAmountFormatter } from "../format/useFormatCurrency";
+import { getCurrencySymbol } from "../format/useFormatCurrency";
 import { summarizeTaxQuote } from "../format/PriceDisplay";
 import { Loading } from "./Loading";
 
 export interface InvoicePaymentProps {
   invoiceId: string;
-  /** Currency formatter (e.g. `(n) => formatCurrency(n, CURRENCY)`). Falls back to the invoice's own currency. */
+  /** Optional presentation override. Left unset, amounts render in the
+   *  invoice's OWN currency, unconverted — see `money` below. */
   formatAmount?: (n: number) => string;
   /** Return path after payment. Forwarded to `useInvoicePayment`. */
   returnPath?: string;
@@ -24,7 +25,6 @@ const formatDate = (value: string | number | Date): string =>
  */
 export function InvoicePayment({ invoiceId, formatAmount, returnPath }: InvoicePaymentProps) {
   const theme = useForgeTheme();
-  const fmt = useAmountFormatter(formatAmount);
   const renderPayment = usePaymentRenderer();
   const { invoice, downloadPdf, clientSecret, returnUrl, isStarting, error, taxQuote } = useInvoicePayment(invoiceId, {
     returnPath,
@@ -35,7 +35,27 @@ export function InvoicePayment({ invoiceId, formatAmount, returnPath }: InvoiceP
 
   const inv = invoice.data;
   const isPaid = inv.status === "paid" || !!inv.paidAt;
-  const money = (n: number) => fmt(n, inv.currency);
+  /**
+   * An invoice is a DEBT of a stated amount in a stated currency, not a price
+   * list — so it must show what the client owes, in the currency they owe it
+   * in, and never a converted approximation.
+   *
+   * This used to run every figure through the storefront formatter, whose job
+   * is to convert a tenant-currency price into whatever currency the VISITOR
+   * has selected. On an invoice that turned a £120.00 bill into "$159.91" —
+   * a different number, in a different currency, from both the document the
+   * client was emailed and the amount the pay link actually charges.
+   *
+   * `formatAmount` is still honoured for a caller that wants its own
+   * presentation; it just is not the storefront converter any more.
+   */
+  const money = (n: number) =>
+    formatAmount
+      ? formatAmount(n)
+      : `${getCurrencySymbol(inv.currency)}${Number(Number(n).toFixed(2)).toLocaleString("en-US", {
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        })}`;
 
   const handleDownload = async () => {
     const blob = await downloadPdf.mutateAsync();
@@ -72,15 +92,33 @@ export function InvoicePayment({ invoiceId, formatAmount, returnPath }: InvoiceP
       </div>
 
       <div style={{ fontSize: 14, opacity: 0.85, marginBottom: 16 }}>
-        <div>Billed to: {inv.clientName}{inv.clientCompany ? ` · ${inv.clientCompany}` : ""}</div>
-        <div>Issued: {formatDate(inv.issueDate)}{inv.dueDate ? ` · Due: ${formatDate(inv.dueDate)}` : ""}</div>
+        <div>
+          Billed to: {inv.clientName}
+          {inv.clientCompany ? ` · ${inv.clientCompany}` : ""}
+        </div>
+        <div>
+          Issued: {formatDate(inv.issueDate)}
+          {inv.dueDate ? ` · Due: ${formatDate(inv.dueDate)}` : ""}
+        </div>
       </div>
 
-      <div style={{ border: `1px solid ${theme.colors.primary}20`, borderRadius: theme.cornerRadius, overflow: "hidden", marginBottom: 16 }}>
+      <div
+        style={{
+          border: `1px solid ${theme.colors.primary}20`,
+          borderRadius: theme.cornerRadius,
+          overflow: "hidden",
+          marginBottom: 16,
+        }}
+      >
         {inv.lineItems.map((li) => (
           <div
             key={li.id}
-            style={{ display: "flex", justifyContent: "space-between", padding: "10px 14px", borderBottom: `1px solid ${theme.colors.primary}10` }}
+            style={{
+              display: "flex",
+              justifyContent: "space-between",
+              padding: "10px 14px",
+              borderBottom: `1px solid ${theme.colors.primary}10`,
+            }}
           >
             <span>
               {li.description}
@@ -94,7 +132,15 @@ export function InvoicePayment({ invoiceId, formatAmount, returnPath }: InvoiceP
           // columns (no re-quote) — surfaced via the start-payment taxQuote.
           const taxSummary = summarizeTaxQuote(taxQuote, money);
           return taxSummary?.mode === "exclusive" ? (
-            <div style={{ display: "flex", justifyContent: "space-between", padding: "10px 14px", borderBottom: `1px solid ${theme.colors.primary}10`, opacity: 0.8 }}>
+            <div
+              style={{
+                display: "flex",
+                justifyContent: "space-between",
+                padding: "10px 14px",
+                borderBottom: `1px solid ${theme.colors.primary}10`,
+                opacity: 0.8,
+              }}
+            >
               <span>Tax</span>
               <span>{taxSummary.formattedTax}</span>
             </div>
@@ -107,7 +153,9 @@ export function InvoicePayment({ invoiceId, formatAmount, returnPath }: InvoiceP
             {(() => {
               const taxSummary = summarizeTaxQuote(taxQuote, money);
               return taxSummary?.mode === "inclusive" ? (
-                <span style={{ display: "block", fontSize: 12, fontWeight: 400, color: theme.colors.text, opacity: 0.65 }}>
+                <span
+                  style={{ display: "block", fontSize: 12, fontWeight: 400, color: theme.colors.text, opacity: 0.65 }}
+                >
                   {taxSummary.label}
                 </span>
               ) : null;
@@ -132,7 +180,13 @@ export function InvoicePayment({ invoiceId, formatAmount, returnPath }: InvoiceP
               mode: "redirect",
             })
           ) : (
-            <>{isStarting ? <Loading label="Preparing payment…" size={22} /> : <p style={{ opacity: 0.7 }}>Payment is not available right now.</p>}</>
+            <>
+              {isStarting ? (
+                <Loading label="Preparing payment…" size={22} />
+              ) : (
+                <p style={{ opacity: 0.7 }}>Payment is not available right now.</p>
+              )}
+            </>
           )}
         </div>
       )}

package/src/utils/_tests/bookingSecret.spec.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { rememberBookingSecret, readBookingSecret, forgetBookingSecret } from "../bookingSecret";
+
+// A tiny in-memory `sessionStorage`. The real one isn't available in a node
+// environment, and half the behaviour under test is precisely what happens when
+// it is and isn't there.
+function fakeStorage(): Storage {
+  const map = new Map<string, string>();
+  return {
+    get length() {
+      return map.size;
+    },
+    key: (i: number) => Array.from(map.keys())[i] ?? null,
+    getItem: (k: string) => map.get(k) ?? null,
+    setItem: (k: string, v: string) => void map.set(k, v),
+    removeItem: (k: string) => void map.delete(k),
+    clear: () => map.clear(),
+  } as Storage;
+}
+
+const g = globalThis as unknown as { window?: unknown };
+
+function withStorage(storage: Storage | null) {
+  g.window = storage
+    ? { sessionStorage: storage }
+    : {
+        get sessionStorage(): Storage {
+          // What a browser does when storage is blocked (private mode, or a
+          // cookie policy that denies it) — a throwing getter, not undefined.
+          throw new Error("access denied");
+        },
+      };
+}
+
+const SECRET_A = "a".repeat(64);
+const SECRET_B = "b".repeat(64);
+
+describe("booking secret storage", () => {
+  afterEach(() => {
+    delete g.window;
+    vi.restoreAllMocks();
+  });
+
+  describe("with storage", () => {
+    let storage: Storage;
+    beforeEach(() => {
+      storage = fakeStorage();
+      withStorage(storage);
+    });
+
+    it("round-trips a secret for its booking", () => {
+      rememberBookingSecret("booking-1", SECRET_A);
+      expect(readBookingSecret("booking-1")).toBe(SECRET_A);
+    });
+
+    it("keys by bookingId so two checkouts in one tab don't clobber each other", () => {
+      // A buyer can have a course and a coaching checkout open at once. A single
+      // shared key would leave one of them holding the other's credential, and
+      // the secret is unrecoverable once overwritten.
+      rememberBookingSecret("booking-1", SECRET_A);
+      rememberBookingSecret("booking-2", SECRET_B);
+      expect(readBookingSecret("booking-1")).toBe(SECRET_A);
+      expect(readBookingSecret("booking-2")).toBe(SECRET_B);
+    });
+
+    it("returns null for a booking it never stored, and for no booking at all", () => {
+      expect(readBookingSecret("unknown")).toBeNull();
+      expect(readBookingSecret(undefined)).toBeNull();
+      expect(readBookingSecret(null)).toBeNull();
+    });
+
+    it("ignores a missing secret rather than storing an empty credential", () => {
+      // The backend omits the field for grandfathered bookings. Writing "" here
+      // would later read back as a present-but-wrong secret.
+      rememberBookingSecret("booking-1", undefined);
+      rememberBookingSecret("booking-2", null);
+      rememberBookingSecret("booking-3", "");
+      expect(readBookingSecret("booking-1")).toBeNull();
+      expect(readBookingSecret("booking-2")).toBeNull();
+      expect(readBookingSecret("booking-3")).toBeNull();
+      expect(storage.length).toBe(0);
+    });
+
+    it("forgets one booking without touching the others", () => {
+      rememberBookingSecret("booking-1", SECRET_A);
+      rememberBookingSecret("booking-2", SECRET_B);
+      forgetBookingSecret("booking-1");
+      expect(readBookingSecret("booking-1")).toBeNull();
+      expect(readBookingSecret("booking-2")).toBe(SECRET_B);
+    });
+
+    it("does not put the secret under a guessable bare-id key", () => {
+      // Namespacing keeps it out of the way of anything else the host site
+      // keeps in sessionStorage under the raw booking id.
+      rememberBookingSecret("booking-1", SECRET_A);
+      expect(storage.getItem("booking-1")).toBeNull();
+    });
+  });
+
+  describe("without storage", () => {
+    it("degrades quietly when storage throws — a live checkout must not break", () => {
+      withStorage(null);
+      expect(() => rememberBookingSecret("booking-1", SECRET_A)).not.toThrow();
+      expect(readBookingSecret("booking-1")).toBeNull();
+      expect(() => forgetBookingSecret("booking-1")).not.toThrow();
+    });
+
+    it("degrades quietly during SSR, where there is no window at all", () => {
+      delete g.window;
+      expect(() => rememberBookingSecret("booking-1", SECRET_A)).not.toThrow();
+      expect(readBookingSecret("booking-1")).toBeNull();
+      expect(() => forgetBookingSecret("booking-1")).not.toThrow();
+    });
+  });
+});