@tribe-nest/forge 3.17.0 → 3.20.0

package/src/utils/bookingSecret.ts

@@ -0,0 +1,100 @@
+// Per-booking checkout credential, held across the payment-provider redirect.
+//
+// ## What this is
+//
+// Course and coaching bookings used to be addressable by their id alone. That
+// id is a random uuid but it is NOT a secret: it rides in the finalise URL, so
+// it reaches browser history, `Referer` headers, shared links and support
+// screenshots. Anyone who learned one could move the purchase onto their own
+// address. The backend now mints a per-booking secret when the booking is
+// created and requires it on `booking/update`, `start-payment` and `finalize`.
+//
+// ## Why sessionStorage, and NOT the URL
+//
+// The confirmation page is reached by a redirect back from Stripe/Paystack, so
+// every bit of in-memory React state is gone by the time it renders. `bookingId`
+// survives that because it is a query param on the return URL — and that is
+// exactly the leak the secret exists to close, so the secret must not travel the
+// same way. It also rules out anything the server sees: a query param is logged,
+// a cookie is sent on every request to the origin.
+//
+// `sessionStorage` is the narrowest thing that still survives a full-page
+// navigation: same tab, same origin, unreadable by another site, never
+// transmitted, and destroyed when the tab closes. A discarded checkout does not
+// outlive the session that started it, which matches the lifetime of the secret
+// itself. `localStorage` would persist a live purchase credential on a shared
+// machine indefinitely, for no benefit — the redirect never leaves the tab.
+//
+// Keyed by bookingId so two checkouts open in the same tab (a course and a
+// coaching session, or two courses in sequence) cannot overwrite each other's
+// credential.
+//
+// ## The secret is returned exactly once
+//
+// The raw value comes back only from the call that CREATES the booking and can
+// never be re-read. If it is lost, that booking is unreachable and the buyer
+// must start again — which is why every write here is best-effort but every
+// read is treated as load-bearing by the callers.
+
+const KEY_PREFIX = "tn:booking_secret:";
+
+function safeStorage(): Storage | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage;
+  } catch {
+    // Private mode / storage disabled by policy.
+    return null;
+  }
+}
+
+const keyFor = (bookingId: string) => `${KEY_PREFIX}${bookingId}`;
+
+/**
+ * Persist the secret for `bookingId`. Call this the moment a booking is created
+ * — the value is never returned again.
+ *
+ * Best-effort: a storage failure (quota, disabled storage) must not break the
+ * checkout that is already in flight. The in-memory copy carries the rest of
+ * THIS page's calls; only the post-redirect leg degrades, and that surfaces as
+ * the "we lost track of your checkout" path rather than a bare not-found.
+ */
+export function rememberBookingSecret(bookingId: string, secret?: string | null): void {
+  if (!bookingId || !secret) return;
+  const storage = safeStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(keyFor(bookingId), secret);
+  } catch {
+    // See above — never throw into a live checkout.
+  }
+}
+
+/** The stored secret for `bookingId`, or null when it was never stored / is gone. */
+export function readBookingSecret(bookingId?: string | null): string | null {
+  if (!bookingId) return null;
+  const storage = safeStorage();
+  if (!storage) return null;
+  try {
+    return storage.getItem(keyFor(bookingId));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drop the secret for a booking that no longer exists (e.g. a released coaching
+ * hold). Deliberately NOT called on a successful finalise: that page is
+ * idempotent and gets reloaded and polled, and clearing the credential would
+ * turn a refresh into a not-found.
+ */
+export function forgetBookingSecret(bookingId?: string | null): void {
+  if (!bookingId) return;
+  const storage = safeStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(keyFor(bookingId));
+  } catch {
+    // Nothing to clear.
+  }
+}