@reblu/site-next 1.5.2 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @reblu/site-next
 
-Next.js glue for Reblu SITEs (REB-418, REB-510). Four responsibilities, all
+Next.js glue for Reblu SITEs (REB-418, REB-510). Five responsibilities, all
 intentionally Next-coupled so the lower SDK layers —
 [`@reblu/site-client`](../site-client), [`@reblu/site-contracts`](../site-contracts),
 [`@reblu/site-ui`](../site-ui) — stay framework-agnostic:
@@ -15,6 +15,9 @@ intentionally Next-coupled so the lower SDK layers —
    factory that proxies them to base-api's `/api/site/auth/*`.
 4. **`<JsonLd>`** (`./json-ld`) — safe `application/ld+json` `<script>`
    rendering; see "Structured data (JSON-LD)" below.
+5. **reCAPTCHA v3** (`./recaptcha`) — the SITE's half of the contact-form
+   captcha contract: the canonical action, the render gate, and the
+   interaction-mount key. See "reCAPTCHA v3" below.
 
 ## Install
 
@@ -105,6 +108,27 @@ import { LoginForm, AuthLogo, mapLoginError } from '@reblu/site-next/auth'
 | `AuthLogo`                  | —                                    | Dynamic tenant logo, `next-themes`-driven |
 | `mapLoginError`             | —                                    | Maps Supabase `?error=` to Spanish copy   |
 
+### Recovering from an expired magic link (REB-762 / REB-763)
+
+A SITE may render `LoginForm` on the same page as `AuthCallback`, so someone who
+arrives with a dead link can ask for a new one without leaving. Two things make
+that path work, and both are on by default — no wiring in the SITE:
+
+- **A successful request clears the callback's verdict.** `LoginForm` dispatches
+  the `reblu:magic-link-requested` DOM event on `window`; `AuthCallback` listens
+  and drops a terminal verdict about the old link ("Enlace caducado", "Enlace
+  inválido", or a failed exchange), rendering nothing so the form's own message
+  is the only one on screen. Both components stay independently usable: alone,
+  one dispatches to nobody and the other hears nothing. `emitMagicLinkRequested`
+  and `onMagicLinkRequested` are exported if a SITE wants to join in.
+- **A 60-second cooldown on the form.** Supabase Auth drops a second magic link
+  requested inside its per-project "minimum interval per user" *before any email
+  is sent*, while the request route still answers 200. The success panel holds
+  the form for `MAGIC_LINK_COOLDOWN_SECONDS` with a visible countdown, then
+  offers "Pedir otro enlace". The interval is the Supabase project's setting,
+  not ours — `MAGIC_LINK_COOLDOWN_SECONDS` mirrors it in one place, and a SITE
+  whose project uses a different value passes `cooldownSeconds`.
+
 `ResetPasswordConfirm`, `SetPassword`, and `AuthConfirm` read their own URL
 params internally via `useSearchParams()`. Next.js requires that hook's
 subtree to render inside a `<Suspense>` boundary — wrap the page/route that
@@ -158,6 +182,101 @@ must never drag in `CtaButtons`/`EditableCta`'s client-component graph.
 Measured: `dist/json-ld.js` is 701 B (451 B gzipped) and its only runtime
 import is `react/jsx-runtime` — no parser, no sanitiser chain.
 
+## reCAPTCHA v3
+
+`@reblu/site-next/recaptcha` (REB-588, zero dependencies, no `'use client'`) is
+the SITE's half of the captcha contract. It does **not** load Google's script
+and does **not** verify tokens — it makes the three decisions every SITE was
+otherwise making alone and differently.
+
+### Which half lives where
+
+| | Where | Who holds it |
+| --- | --- | --- |
+| **Site key** | `/api/site/analytics` → the browser | Public by design. This module. |
+| **Secret** | `site_integration_config.recaptchaSecretKey`, read only by base-api | **Never leaves base-api.** Not in this package, not in any `@reblu/site-*` package, not in the browser. |
+| **Verification** | `POST /api/site/contact-form` → Google `siteverify` | base-api, per tenant. |
+
+The SITE mints a token and posts it as `ContactFormInput.captcha`; base-api
+decides. A SITE holding the secret would be a SITE that could be tricked into
+approving its own tokens, and a distributable SDK is the worst possible place to
+put a credential. **Nothing here calls `siteverify`.**
+
+### Should this form render at all?
+
+```tsx
+import {
+  isContactFormAvailable,
+  resolveContactFormAvailability,
+} from '@reblu/site-next/recaptcha'
+
+const availability = resolveContactFormAvailability(analytics)
+if (!isContactFormAvailable(availability)) return <ContactDetailsOnly />
+
+// availability.recaptchaSiteKey is a confirmed, usable key
+```
+
+An **allow-list** (`DB_ONLY`, `WEBHOOK`, `RESEND`), never `mode !== 'DISABLED'`,
+held to the same members in the same order as base-api's own list by a drift
+guard (`apps/base-api/tests/unit/lib/contracts/contact-form-mode-drift.test.ts`).
+The deny-list version is a real incident: it rendered a form for
+`NOT_CONFIGURED` too — which is what every freshly provisioned tenant carries
+until someone finishes the wizard (REB-586) — so a visitor typed out a medical
+enquiry, pressed send, and got `503 Contact form is disabled`. They learned the
+clinic could not be reached only after writing to it. An unknown mode, a mode
+from a base-api newer than your SDK, and a config read that threw all resolve to
+the same answer: no form. The page still shows the phone and the address.
+
+The key is checked too, because `ContactFormInput.captcha` is required: an
+accepting mode with no usable key is a form whose every submission is dead on
+arrival. `missing-recaptcha-key` and `malformed-recaptcha-key` are separate
+reasons on purpose — one owner never filled the field, the other filled it with
+the wrong thing, and as of REB-588 **nothing validates that column** in nexus, on
+the way out of `/api/site/analytics`, or in the response contract.
+
+### Load Google only when someone actually uses the form
+
+```tsx
+import { RECAPTCHA_ACTION, deferredRecaptchaKey } from '@reblu/site-next/recaptcha'
+
+const [armed, setArmed] = useState(false)
+
+<GoogleReCaptchaProvider reCaptchaKey={deferredRecaptchaKey(siteKey, armed)}>
+  <form onFocusCapture={() => setArmed(true)}>…</form>
+</GoogleReCaptchaProvider>
+
+// at submit: await executeRecaptcha(RECAPTCHA_ACTION)
+```
+
+`GoogleReCaptchaProvider` loads `api.js` the moment it mounts, so mounting it
+with the form means every visitor who merely lands on the page to read the phone
+number has contacted Google. `deferredRecaptchaKey` returns `''` until `armed`,
+and an empty key mounts the provider while injecting nothing; swapping the real
+key in re-runs the library's effect and injects it then, **without remounting
+the children** — so the visitor never loses focus or a half-typed word.
+
+Both of those are claims about the vendor's code, so they are pinned by
+`tests/recaptcha-deferred-oracle.test.tsx`, which drives the real
+`react-google-recaptcha-v3` and counts script tags in the DOM. If a future
+version injects eagerly, that test goes red rather than this README quietly
+becoming false.
+
+**This is not cookie consent.** Deferring the script narrows the exposure; it
+does not gate it on a lawful basis. That is REB-642.
+
+`RECAPTCHA_ACTION` is exported because reCAPTCHA v3 scores **per action**: two
+SITEs calling `executeRecaptcha('submit_form')` and `'contact_form'` build two
+unrelated score histories for the same feature.
+
+It is **not a security control.** base-api's `serverCaptchaVerify` checks only
+`success` and `score`, and never reads the `action` Google returns — so a token
+minted for a different action on the same site verifies exactly as well. Binding
+the token to this form needs base-api to assert `action === RECAPTCHA_ACTION`;
+until it does, treat the constant as consistency, not enforcement.
+
+`react-google-recaptcha-v3` stays **your** dependency — the subpath imports
+nothing at all, guarded by `tests/recaptcha-subpath-isolation.test.ts`.
+
 ## Build
 
 `tsup` → dual ESM/CJS + `.d.ts`. Code-splitting is **off** so each entry keeps its

package/dist/auth.cjs

@@ -35,10 +35,14 @@ __export(auth_exports, {
   AuthConfirm: () => AuthConfirm,
   AuthLogo: () => AuthLogo,
   LoginForm: () => LoginForm,
+  MAGIC_LINK_COOLDOWN_SECONDS: () => MAGIC_LINK_COOLDOWN_SECONDS,
+  MAGIC_LINK_REQUESTED_EVENT: () => MAGIC_LINK_REQUESTED_EVENT,
   ResetPasswordConfirm: () => ResetPasswordConfirm,
   ResetPasswordRequest: () => ResetPasswordRequest,
   SetPassword: () => SetPassword,
-  mapLoginError: () => mapLoginError
+  emitMagicLinkRequested: () => emitMagicLinkRequested,
+  mapLoginError: () => mapLoginError,
+  onMagicLinkRequested: () => onMagicLinkRequested
 });
 module.exports = __toCommonJS(auth_exports);
 
@@ -58,6 +62,27 @@ function isSafeRedirectUrl(url) {
   return ["http", "https"].includes(scheme) || clean.startsWith("/");
 }
 
+// src/auth/magic-link-cooldown.ts
+var MAGIC_LINK_COOLDOWN_SECONDS = 60;
+
+// src/auth/magic-link-events.ts
+var MAGIC_LINK_REQUESTED_EVENT = "reblu:magic-link-requested";
+function emitMagicLinkRequested() {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(MAGIC_LINK_REQUESTED_EVENT));
+}
+function onMagicLinkRequested(listener) {
+  if (typeof window === "undefined") return () => {
+  };
+  const handler = () => {
+    listener();
+  };
+  window.addEventListener(MAGIC_LINK_REQUESTED_EVENT, handler);
+  return () => {
+    window.removeEventListener(MAGIC_LINK_REQUESTED_EVENT, handler);
+  };
+}
+
 // src/auth/login-form.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var DEFAULT_COPY = {
@@ -70,8 +95,15 @@ var DEFAULT_COPY = {
   passwordSubmitCta: "Iniciar sesi\xF3n",
   forgotPasswordCta: "\xBFOlvidaste tu contrase\xF1a?",
   magicLinkSubmitCta: "Enviar enlace de acceso",
-  magicLinkSuccessTitle: "\xA1Enlace enviado!",
-  magicLinkSuccessMessage: "Revisa tu correo para acceder.",
+  magicLinkSuccessTitle: "Revisa tu correo",
+  // True in every branch, and leaks nothing: the request path answers an
+  // identical 200 whether or not the account exists, and whether or not an
+  // email actually went out (REB-762). "¡Enlace enviado!" asserted a send that
+  // may never have happened — the user then waited for something that was not
+  // coming.
+  magicLinkSuccessMessage: "Si la cuenta existe, recibir\xE1s un enlace en unos minutos. Si ya lo has pedido hace poco, espera antes de volver a intentarlo.",
+  magicLinkCooldownMessage: "Podr\xE1s pedir otro enlace en {seconds} s.",
+  magicLinkResendCta: "Pedir otro enlace",
   mfaTitle: "Verificaci\xF3n en dos pasos",
   mfaMessage: "Introduce el c\xF3digo de 6 d\xEDgitos de tu aplicaci\xF3n autenticadora.",
   mfaCodeLabel: "C\xF3digo de verificaci\xF3n",
@@ -95,6 +127,7 @@ function LoginForm(props) {
     copy,
     className,
     defaultMethod = "password",
+    cooldownSeconds = MAGIC_LINK_COOLDOWN_SECONDS,
     onPasswordSubmitted,
     onMagicLinkSubmitted,
     onMfaSubmitted
@@ -107,12 +140,37 @@ function LoginForm(props) {
   const [password, setPassword] = React.useState("");
   const [mfa, setMfa] = React.useState(null);
   const [mfaCode, setMfaCode] = React.useState("");
+  const [cooldownLeft, setCooldownLeft] = React.useState(0);
+  const successHeadingRef = React.useRef(null);
+  const magicEmailRef = React.useRef(null);
+  const returningFromSuccessRef = React.useRef(false);
+  const isCoolingDown = cooldownLeft > 0;
+  React.useEffect(() => {
+    if (!isCoolingDown) return;
+    const id = setInterval(() => {
+      setCooldownLeft((s) => Math.max(0, s - 1));
+    }, 1e3);
+    return () => {
+      clearInterval(id);
+    };
+  }, [isCoolingDown]);
+  React.useEffect(() => {
+    if (state === "magic-link-success") successHeadingRef.current?.focus();
+    if (state === "idle" && returningFromSuccessRef.current) {
+      returningFromSuccessRef.current = false;
+      magicEmailRef.current?.focus();
+    }
+  }, [state]);
   const resetTransientState = React.useCallback(() => {
     setState("idle");
     setError(null);
     setMfa(null);
     setMfaCode("");
   }, []);
+  const handleResend = () => {
+    returningFromSuccessRef.current = true;
+    resetTransientState();
+  };
   const handleTabChange = (next) => {
     if (next !== "magic-link" && next !== "password") return;
     setMethod(next);
@@ -137,6 +195,8 @@ function LoginForm(props) {
       });
       if (res.ok) {
         setState("magic-link-success");
+        setCooldownLeft(cooldownSeconds);
+        emitMagicLinkRequested();
         onMagicLinkSubmitted?.(trimmed);
         return;
       }
@@ -279,9 +339,18 @@ function LoginForm(props) {
     ] });
   }
   if (state === "magic-link-success") {
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: (0, import_site_ui.cn)("space-y-2 text-center", className), children: [
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h2", { className: "text-xl font-semibold", children: c.magicLinkSuccessTitle }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "text-muted-foreground", children: c.magicLinkSuccessMessage })
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: (0, import_site_ui.cn)("space-y-3 text-center", className), children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h2", { className: "text-xl font-semibold", ref: successHeadingRef, tabIndex: -1, children: c.magicLinkSuccessTitle }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "text-muted-foreground", children: c.magicLinkSuccessMessage }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { role: "status", "aria-live": "polite", className: "sr-only", children: cooldownLeft > 0 ? "" : c.magicLinkResendCta }),
+      cooldownLeft > 0 ? (
+        // A ticking number is VISUAL. Every text mutation inside a live
+        // region is a separate announcement, so marking this one would queue
+        // ~60 polite interruptions; the heading above already took focus and
+        // spoke the new state once. The only transition worth announcing is
+        // the end of the wait, which the region above carries.
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "text-muted-foreground text-sm", children: c.magicLinkCooldownMessage.replaceAll("{seconds}", String(cooldownLeft)) })
+      ) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_site_ui.Button, { type: "button", variant: "outline", onClick: handleResend, children: c.magicLinkResendCta })
     ] });
   }
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: (0, import_site_ui.cn)("space-y-6", className), children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_tabs.Tabs, { value: method, onValueChange: handleTabChange, children: [
@@ -341,6 +410,7 @@ function LoginForm(props) {
           import_site_ui.Input,
           {
             id: "login-email-magic",
+            ref: magicEmailRef,
             type: "email",
             autoComplete: "email",
             placeholder: c.emailPlaceholder,
@@ -361,6 +431,7 @@ function LoginForm(props) {
 var React2 = __toESM(require("react"), 1);
 var import_site_ui2 = require("@reblu/site-ui");
 var import_jsx_runtime2 = require("react/jsx-runtime");
+var TERMINAL_FAILURE_STATES = ["expired", "network", "malformed"];
 var DEFAULT_COPY2 = {
   loadingTitle: "Autenticando...",
   loadingMessage: "Estamos verificando tu identidad.",
@@ -472,7 +543,14 @@ function AuthCallback({
     if (state === "network") retryRef.current?.focus();
     if (state === "expired" || state === "malformed") linkRef.current?.focus();
   }, [state]);
+  React2.useEffect(
+    () => onMagicLinkRequested(() => {
+      setState((current) => TERMINAL_FAILURE_STATES.includes(current) ? "stale" : current);
+    }),
+    []
+  );
   const isLoading = state === "mounting" || state === "parsing" || state === "exchanging";
+  if (state === "stale") return null;
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("main", { className: (0, import_site_ui2.cn)("flex min-h-screen items-center justify-center", className), children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { "aria-live": "polite", className: "w-full max-w-md space-y-4 p-6 text-center", children: [
     isLoading && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { className: "text-xl font-semibold", children: c.loadingTitle }),
@@ -1093,9 +1171,13 @@ function AuthConfirm(props) {
   AuthConfirm,
   AuthLogo,
   LoginForm,
+  MAGIC_LINK_COOLDOWN_SECONDS,
+  MAGIC_LINK_REQUESTED_EVENT,
   ResetPasswordConfirm,
   ResetPasswordRequest,
   SetPassword,
-  mapLoginError
+  emitMagicLinkRequested,
+  mapLoginError,
+  onMagicLinkRequested
 });
 //# sourceMappingURL=auth.cjs.map