@reblu/site-next 1.5.1 → 1.6.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
 
@@ -158,6 +161,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/recaptcha.cjs

@@ -0,0 +1,75 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/recaptcha.ts
+var recaptcha_exports = {};
+__export(recaptcha_exports, {
+  CONTACT_FORM_OPERATIONAL_MODES: () => CONTACT_FORM_OPERATIONAL_MODES,
+  RECAPTCHA_ACTION: () => RECAPTCHA_ACTION,
+  RECAPTCHA_SITE_KEY_PATTERN: () => RECAPTCHA_SITE_KEY_PATTERN,
+  deferredRecaptchaKey: () => deferredRecaptchaKey,
+  isContactFormAvailable: () => isContactFormAvailable,
+  isSafeRecaptchaSiteKey: () => isSafeRecaptchaSiteKey,
+  resolveContactFormAvailability: () => resolveContactFormAvailability
+});
+module.exports = __toCommonJS(recaptcha_exports);
+var RECAPTCHA_ACTION = "contact_form";
+var RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+function isSafeRecaptchaSiteKey(value) {
+  return typeof value === "string" && RECAPTCHA_SITE_KEY_PATTERN.test(value);
+}
+var CONTACT_FORM_OPERATIONAL_MODES = ["DB_ONLY", "WEBHOOK", "RESEND"];
+function trimmed(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  return text.length > 0 ? text : null;
+}
+function isOperationalMode(mode) {
+  return CONTACT_FORM_OPERATIONAL_MODES.includes(mode);
+}
+function resolveContactFormAvailability(analytics) {
+  if (!analytics) return { state: "unavailable", reason: "unreadable" };
+  const mode = analytics.contactFormMode;
+  if (!isOperationalMode(mode)) return { state: "unavailable", reason: "mode-not-operational" };
+  const recaptchaSiteKey = trimmed(analytics.recaptchaSiteKey);
+  if (!recaptchaSiteKey) return { state: "unavailable", reason: "missing-recaptcha-key" };
+  if (!isSafeRecaptchaSiteKey(recaptchaSiteKey)) {
+    return { state: "unavailable", reason: "malformed-recaptcha-key" };
+  }
+  return { state: "available", mode, recaptchaSiteKey };
+}
+function isContactFormAvailable(availability) {
+  return availability.state === "available";
+}
+function deferredRecaptchaKey(siteKey, armed) {
+  if (!armed) return "";
+  const key = trimmed(siteKey);
+  return key && isSafeRecaptchaSiteKey(key) ? key : "";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONTACT_FORM_OPERATIONAL_MODES,
+  RECAPTCHA_ACTION,
+  RECAPTCHA_SITE_KEY_PATTERN,
+  deferredRecaptchaKey,
+  isContactFormAvailable,
+  isSafeRecaptchaSiteKey,
+  resolveContactFormAvailability
+});
+//# sourceMappingURL=recaptcha.cjs.map

package/dist/recaptcha.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recaptcha.ts"],"sourcesContent":["/**\n * reCAPTCHA v3 — the SITE's half of the contract (REB-588).\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHICH HALF LIVES WHERE, AND WHY\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * reCAPTCHA is two secrets and two steps, and they are deliberately split across\n * a trust boundary:\n *\n *   SITE KEY  — public by design. It ships to the browser inside the script URL,\n *               so the tenant serves it from `/api/site/analytics`. This module\n *               handles it.\n *   SECRET    — never leaves base-api. It is stored per tenant in\n *               `site_integration_config.recaptchaSecretKey` and read only by\n *               `serverCaptchaVerify` when `POST /api/site/contact-form` runs.\n *\n * **Nothing in this module, in this package, or anywhere in the `@reblu/site-*`\n * SDK ever sees the secret, and nothing here calls Google's `siteverify`.** A\n * SITE holding the secret would be a SITE that could be tricked into approving\n * its own tokens, and a distributable SDK is the worst possible place to put a\n * credential. Verification is base-api's job and already works: the SITE mints a\n * token, posts it as `ContactFormInput.captcha`, and base-api decides.\n *\n * That is also why this module is NOT \"reCAPTCHA support\" in the round. It is\n * the three decisions every SITE was otherwise making alone and differently:\n * which action to name, whether a form may be shown at all, and when Google's\n * script is allowed to load.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHY IT IS IN THE SDK AT ALL\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * Because it was already being written four times. `apps/base-api`,\n * `apps/demo-site` and the external `reblu-site-dermamedicin` each grew their\n * own copy of this flow, and they had already drifted — different action\n * strings, different mount timing, a retry loop in one of them. A score that\n * reCAPTCHA reports per action is not comparable across SITEs that name the\n * action differently, and a defect fixed in one copy stays live in the other\n * two. The SDK is where a decision gets made once.\n *\n * This module has ZERO runtime dependencies and imports nothing — not React, not\n * `next`, not `react-google-recaptcha-v3`, not `@reblu/site-ui`. It is pure\n * functions over plain data, callable from a Server Component deciding whether\n * to render a form and from the Client Component that renders it. The subpath is\n * kept dependency-free by `tests/recaptcha-subpath-isolation.test.ts`.\n */\n\nimport type { Analytics, ContactFormMode } from '@reblu/site-contracts'\n\n/**\n * The action name every Reblu SITE mints its contact-form token under.\n *\n * reCAPTCHA v3 scores PER ACTION, and a score is only interpretable against a\n * stable one: Google's own admin console charts each action separately, and a\n * threshold tuned on one action says nothing about another. Two SITEs calling\n * `executeRecaptcha('submit_form')` and `executeRecaptcha('contact_form')` are\n * building two unrelated score histories for the same feature — which is exactly\n * the state the repo was in before this constant existed.\n *\n * `contact_form` over `submit_form` because it names the form, not the verb;\n * a second protected form would need its own action, and `submit_form` would\n * have nothing left to call it.\n *\n * ── WHAT THIS CONSTANT DOES **NOT** BUY, STATED PLAINLY ──\n *\n * It buys comparable scores. It does NOT bind a token to this form, because\n * `serverCaptchaVerify` in base-api checks only `success` and `score`, and never\n * reads the `action` field Google returns. A token minted for any other action\n * on the same site verifies here exactly as well. Making the action load-bearing\n * requires base-api to assert `action === RECAPTCHA_ACTION` on verify; until it\n * does, do not read this constant as a security control.\n */\nexport const RECAPTCHA_ACTION = 'contact_form'\n\n/**\n * The shape a site key must have before this SDK will hand it to Google.\n *\n * ── WHAT THIS IS, AND EMPHATICALLY WHAT IT IS NOT ──\n *\n * It is a SINK-SAFETY guard, not a guess at Google's key format. The key is\n * interpolated into the loader's script URL as a query parameter, so what\n * matters here is that it cannot carry a space, a quote, a newline, an `&`, or a\n * `#` — characters that make a URL mean something other than what was intended.\n * The base64url alphabet Google actually issues from (`A-Z a-z 0-9 - _`) is a\n * strict subset of \"safe\", so a real key passes by construction.\n *\n * The length bounds are deliberately far wider than any key Google issues\n * (theirs are 40 characters). A bound tight enough to be a real format check\n * would be a bound tight enough to take a WORKING tenant's contact form offline\n * the day Google changes its key length — which is strictly worse than the\n * malformed key it was meant to catch. If you are tempted to tighten this,\n * the thing to tighten is the nexus write path, where an owner can still see\n * and fix the error, not this read path where they cannot.\n *\n * ── WHY THE SDK RE-VALIDATES AT ALL ──\n *\n * Same reason `@reblu/site-next/analytics` re-checks `gaId` and `clarityId`\n * (REB-617): base-api is not the only thing a SITE ever talks to, and the layer\n * that owns the value is not the layer that suffers from it being wrong. As of\n * REB-588 this column has NO validation anywhere — not in the nexus form, not on\n * the way out of `/api/site/analytics`, not in the response contract, which is\n * the one asymmetry `gaId`/`clarityId` do not share. Until that is fixed\n * upstream, this is the only guard between a mistyped key and a contact form\n * that renders, looks live, and silently eats every enquiry.\n */\nexport const RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/\n\n/**\n * Whether `value` is a site key safe to put in the loader's script URL.\n *\n * Takes `unknown` on purpose: the value arrives over HTTP, so the contract's\n * `string | null` is a promise about the shape, not a guarantee about the bytes.\n */\nexport function isSafeRecaptchaSiteKey(value: unknown): value is string {\n  return typeof value === 'string' && RECAPTCHA_SITE_KEY_PATTERN.test(value)\n}\n\n/**\n * The modes in which base-api will actually accept a submission.\n *\n * An ALLOW-LIST, never `mode !== 'DISABLED'`. The three differ only in what\n * base-api DOES with the payload — a row, a webhook, an email — and the SITE\n * must not care and must never learn the destination: a webhook URL or a Resend\n * key is a tenant secret with no business in a public site.\n *\n * The deny-list version of this is a real incident, not a hypothetical: a page\n * that hid the form on `DISABLED` and rendered it otherwise rendered it for\n * `NOT_CONFIGURED` too — which is what EVERY freshly provisioned tenant carries\n * until someone finishes the wizard (REB-586). A visitor typed out a medical\n * enquiry, pressed send, and got `503 Contact form is disabled`. They learned\n * the clinic could not be reached only after writing to it.\n */\nexport const CONTACT_FORM_OPERATIONAL_MODES = ['DB_ONLY', 'WEBHOOK', 'RESEND'] as const\n\n/** A mode in which the form may be shown. */\nexport type ContactFormOperationalMode = (typeof CONTACT_FORM_OPERATIONAL_MODES)[number]\n\n/**\n * The modes deliberately declined. A TYPE, never a value: the runtime must never\n * read it, because an allow-list must not be expressible as \"everything except\n * this list\", and this subpath's defining property is that it ships nothing it\n * does not need. It exists only to feed {@link ContactFormModeExhaustiveCheck}.\n */\ntype DeclinedMode = 'NOT_CONFIGURED' | 'DISABLED'\n\n/**\n * Compile-time exhaustiveness guard over `ContactFormMode`.\n *\n * `Missing` is constrained to `never` and DEFAULTS to the contract modes that\n * are neither accepted nor explicitly declined, so a default violating its own\n * constraint breaks the build the moment `@reblu/site-contracts` gains a mode.\n *\n * At runtime a new mode already fails closed, which is correct but SILENT — and\n * silence is how a tenant switches their form on in nexus and watches nothing\n * appear. This forces a human to make the call in a diff instead.\n *\n * Exported so it is never reported as an unused symbol.\n */\nexport type ContactFormModeExhaustiveCheck<\n  Missing extends never = Exclude<ContactFormMode, ContactFormOperationalMode | DeclinedMode>,\n> = Missing\n\n/** Why the form is not being shown. Drives diagnostics, never visitor-facing copy. */\nexport type ContactFormUnavailableReason =\n  /** The analytics read failed or was never made — no answer at all. */\n  | 'unreadable'\n  /** The tenant's mode is not one base-api accepts submissions in. */\n  | 'mode-not-operational'\n  /** Accepting mode, but no site key: the browser cannot mint a token. */\n  | 'missing-recaptcha-key'\n  /** A site key is present but cannot be a key — see {@link RECAPTCHA_SITE_KEY_PATTERN}. */\n  | 'malformed-recaptcha-key'\n\nexport type ContactFormAvailability =\n  /**\n   * Confirmed: base-api accepts submissions AND a usable site key exists. The\n   * key travels inside the `available` case on purpose — a component that has\n   * proven the form may render should not have to re-read (and re-null-check)\n   * the payload to find out what to render it WITH.\n   */\n  | { state: 'available'; mode: ContactFormOperationalMode; recaptchaSiteKey: string }\n  | { state: 'unavailable'; reason: ContactFormUnavailableReason }\n\n/** Whitespace-only is absent — a key someone saved blank is not a key. */\nfunction trimmed(value: unknown): string | null {\n  if (typeof value !== 'string') return null\n  const text = value.trim()\n  return text.length > 0 ? text : null\n}\n\nfunction isOperationalMode(mode: unknown): mode is ContactFormOperationalMode {\n  // Widened to `unknown` deliberately: see isSafeRecaptchaSiteKey. A base-api\n  // newer than this SDK sends a string TypeScript has never heard of, and it\n  // must fail closed rather than be assumed accepting.\n  return (CONTACT_FORM_OPERATIONAL_MODES as readonly string[]).includes(mode as string)\n}\n\n/**\n * Resolve whether a contact form may be rendered for this tenant.\n *\n * We offer what we can CONFIRM, never what we have merely failed to disprove: an\n * unknown mode, a mode from a runtime newer than this build, and a config read\n * that threw all resolve to the same answer — no form. The page still shows the\n * phone, the email and the address, so a hidden form costs a visitor one extra\n * glance; a form that eats their message costs them the message.\n *\n * Order matters. The mode is checked BEFORE the key, because \"the tenant has not\n * switched the form on\" is the actionable half of a double failure — a site key\n * for a form nobody enabled is not the problem to fix first.\n */\nexport function resolveContactFormAvailability(\n  analytics: Analytics | null | undefined,\n): ContactFormAvailability {\n  if (!analytics) return { state: 'unavailable', reason: 'unreadable' }\n\n  const mode = analytics.contactFormMode\n  if (!isOperationalMode(mode)) return { state: 'unavailable', reason: 'mode-not-operational' }\n\n  // `ContactFormInput.captcha` is REQUIRED and base-api verifies it, so an\n  // accepting mode with no usable key is still a form whose every submission is\n  // dead on arrival. \"Missing\" and \"malformed\" are separated because they call\n  // for different fixes by different people: one owner never filled the field,\n  // the other filled it with the wrong thing.\n  const recaptchaSiteKey = trimmed(analytics.recaptchaSiteKey)\n  if (!recaptchaSiteKey) return { state: 'unavailable', reason: 'missing-recaptcha-key' }\n  if (!isSafeRecaptchaSiteKey(recaptchaSiteKey)) {\n    return { state: 'unavailable', reason: 'malformed-recaptcha-key' }\n  }\n\n  return { state: 'available', mode, recaptchaSiteKey }\n}\n\n/** Narrowing helper — the single question a renderer should ask. */\nexport function isContactFormAvailable(\n  availability: ContactFormAvailability,\n): availability is Extract<ContactFormAvailability, { state: 'available' }> {\n  return availability.state === 'available'\n}\n\n/**\n * The key to hand `GoogleReCaptchaProvider` on this render — `''` until `armed`.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHAT THIS BUYS\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `GoogleReCaptchaProvider` loads Google's `api.js` the moment it MOUNTS. Mount\n * it with the form and every visitor who merely lands on the page to read the\n * phone number has contacted Google — on a clinic's contact page, a third-party\n * request nobody asked for, on a route whose whole subject is personal data.\n *\n * Arming on first interaction with the form (focus, first keystroke) means\n * Google is contacted only for a visitor who is actually about to submit, which\n * is the only visitor whose token is worth anything. It is a smaller page, a\n * faster one, and a materially smaller consent surface.\n *\n * **This is NOT a cookie-consent implementation.** Deferring the script narrows\n * the exposure; it does not gate it on a lawful basis. Full consent gating for\n * third parties is REB-642 and has its own owner.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * HOW, WITHOUT A HACK — MEASURED, NOT ASSUMED\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `react-google-recaptcha-v3` injects the script from an effect shaped\n *\n *     useEffect(() => { if (reCaptchaKey) { …inject…; return cleanup } … },\n *               [ …, reCaptchaKey, … ])\n *\n * Two facts fall out, and together they are the whole mechanism:\n *\n *   1. An EMPTY key mounts the provider and injects NOTHING.\n *   2. `reCaptchaKey` is a dependency, so swapping the real key in later re-runs\n *      the effect and injects the script then.\n *\n * Crucially the provider element never leaves the tree, so its children are\n * never remounted: the visitor does not lose focus, a half-typed word, or the\n * caret position at the instant the script arrives. This is the library's own\n * documented prop doing its documented job — no imperative script injection, no\n * reaching into the DOM, no fork.\n *\n * Both facts are pinned by `tests/recaptcha-deferred-oracle.test.tsx`, which\n * drives the REAL library and counts script tags in the DOM. They are claims\n * about someone else's code, so prose asserting them is not enough — if a future\n * version of the library injects eagerly, that test goes red and this whole\n * optimisation is known to be void.\n *\n * ── THE ONE COST, MEASURED ──\n *\n * On the empty-key render the library calls its own warn helper, which is\n * written inverted, so the warning fires in PRODUCTION and stays silent in\n * development. A visitor who opens devtools before touching a field sees one\n * `\"<GoogleReCaptchaProvider /> recaptcha key not provided\"`. Cosmetic console\n * noise, traded against a third-party request on every view of the page. Worth\n * it, and recorded here so the next reader knows it is expected.\n *\n * ── AND NO FALLBACK KEY, EVER ──\n *\n * `''` for a blank OR malformed key however armed. There is no hardcoded\n * fallback anywhere in this module, because a captcha key that is not the\n * tenant's fails Google's verification while LOOKING configured — converting a\n * visible gap an owner can fix in nexus into a silent one nobody can.\n * {@link resolveContactFormAvailability} hides the form in that case; this is\n * the second lock on the same door.\n */\nexport function deferredRecaptchaKey(siteKey: string, armed: boolean): string {\n  if (!armed) return ''\n  const key = trimmed(siteKey)\n  return key && isSafeRecaptchaSiteKey(key) ? key : ''\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyEO,IAAM,mBAAmB;AAiCzB,IAAM,6BAA6B;AAQnC,SAAS,uBAAuB,OAAiC;AACtE,SAAO,OAAO,UAAU,YAAY,2BAA2B,KAAK,KAAK;AAC3E;AAiBO,IAAM,iCAAiC,CAAC,WAAW,WAAW,QAAQ;AAoD7E,SAAS,QAAQ,OAA+B;AAC9C,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,OAAO,MAAM,KAAK;AACxB,SAAO,KAAK,SAAS,IAAI,OAAO;AAClC;AAEA,SAAS,kBAAkB,MAAmD;AAI5E,SAAQ,+BAAqD,SAAS,IAAc;AACtF;AAeO,SAAS,+BACd,WACyB;AACzB,MAAI,CAAC,UAAW,QAAO,EAAE,OAAO,eAAe,QAAQ,aAAa;AAEpE,QAAM,OAAO,UAAU;AACvB,MAAI,CAAC,kBAAkB,IAAI,EAAG,QAAO,EAAE,OAAO,eAAe,QAAQ,uBAAuB;AAO5F,QAAM,mBAAmB,QAAQ,UAAU,gBAAgB;AAC3D,MAAI,CAAC,iBAAkB,QAAO,EAAE,OAAO,eAAe,QAAQ,wBAAwB;AACtF,MAAI,CAAC,uBAAuB,gBAAgB,GAAG;AAC7C,WAAO,EAAE,OAAO,eAAe,QAAQ,0BAA0B;AAAA,EACnE;AAEA,SAAO,EAAE,OAAO,aAAa,MAAM,iBAAiB;AACtD;AAGO,SAAS,uBACd,cAC0E;AAC1E,SAAO,aAAa,UAAU;AAChC;AAoEO,SAAS,qBAAqB,SAAiB,OAAwB;AAC5E,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,MAAM,QAAQ,OAAO;AAC3B,SAAO,OAAO,uBAAuB,GAAG,IAAI,MAAM;AACpD;","names":[]}

package/dist/recaptcha.d.cts

@@ -0,0 +1,264 @@
+import { ContactFormMode, Analytics } from '@reblu/site-contracts';
+
+/**
+ * reCAPTCHA v3 — the SITE's half of the contract (REB-588).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHICH HALF LIVES WHERE, AND WHY
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * reCAPTCHA is two secrets and two steps, and they are deliberately split across
+ * a trust boundary:
+ *
+ *   SITE KEY  — public by design. It ships to the browser inside the script URL,
+ *               so the tenant serves it from `/api/site/analytics`. This module
+ *               handles it.
+ *   SECRET    — never leaves base-api. It is stored per tenant in
+ *               `site_integration_config.recaptchaSecretKey` and read only by
+ *               `serverCaptchaVerify` when `POST /api/site/contact-form` runs.
+ *
+ * **Nothing in this module, in this package, or anywhere in the `@reblu/site-*`
+ * SDK ever sees the secret, and nothing here calls Google's `siteverify`.** 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. Verification is base-api's job and already works: the SITE mints a
+ * token, posts it as `ContactFormInput.captcha`, and base-api decides.
+ *
+ * That is also why this module is NOT "reCAPTCHA support" in the round. It is
+ * the three decisions every SITE was otherwise making alone and differently:
+ * which action to name, whether a form may be shown at all, and when Google's
+ * script is allowed to load.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY IT IS IN THE SDK AT ALL
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Because it was already being written four times. `apps/base-api`,
+ * `apps/demo-site` and the external `reblu-site-dermamedicin` each grew their
+ * own copy of this flow, and they had already drifted — different action
+ * strings, different mount timing, a retry loop in one of them. A score that
+ * reCAPTCHA reports per action is not comparable across SITEs that name the
+ * action differently, and a defect fixed in one copy stays live in the other
+ * two. The SDK is where a decision gets made once.
+ *
+ * This module has ZERO runtime dependencies and imports nothing — not React, not
+ * `next`, not `react-google-recaptcha-v3`, not `@reblu/site-ui`. It is pure
+ * functions over plain data, callable from a Server Component deciding whether
+ * to render a form and from the Client Component that renders it. The subpath is
+ * kept dependency-free by `tests/recaptcha-subpath-isolation.test.ts`.
+ */
+
+/**
+ * The action name every Reblu SITE mints its contact-form token under.
+ *
+ * reCAPTCHA v3 scores PER ACTION, and a score is only interpretable against a
+ * stable one: Google's own admin console charts each action separately, and a
+ * threshold tuned on one action says nothing about another. Two SITEs calling
+ * `executeRecaptcha('submit_form')` and `executeRecaptcha('contact_form')` are
+ * building two unrelated score histories for the same feature — which is exactly
+ * the state the repo was in before this constant existed.
+ *
+ * `contact_form` over `submit_form` because it names the form, not the verb;
+ * a second protected form would need its own action, and `submit_form` would
+ * have nothing left to call it.
+ *
+ * ── WHAT THIS CONSTANT DOES **NOT** BUY, STATED PLAINLY ──
+ *
+ * It buys comparable scores. It does NOT bind a token to this form, because
+ * `serverCaptchaVerify` in base-api checks only `success` and `score`, and never
+ * reads the `action` field Google returns. A token minted for any other action
+ * on the same site verifies here exactly as well. Making the action load-bearing
+ * requires base-api to assert `action === RECAPTCHA_ACTION` on verify; until it
+ * does, do not read this constant as a security control.
+ */
+declare const RECAPTCHA_ACTION = "contact_form";
+/**
+ * The shape a site key must have before this SDK will hand it to Google.
+ *
+ * ── WHAT THIS IS, AND EMPHATICALLY WHAT IT IS NOT ──
+ *
+ * It is a SINK-SAFETY guard, not a guess at Google's key format. The key is
+ * interpolated into the loader's script URL as a query parameter, so what
+ * matters here is that it cannot carry a space, a quote, a newline, an `&`, or a
+ * `#` — characters that make a URL mean something other than what was intended.
+ * The base64url alphabet Google actually issues from (`A-Z a-z 0-9 - _`) is a
+ * strict subset of "safe", so a real key passes by construction.
+ *
+ * The length bounds are deliberately far wider than any key Google issues
+ * (theirs are 40 characters). A bound tight enough to be a real format check
+ * would be a bound tight enough to take a WORKING tenant's contact form offline
+ * the day Google changes its key length — which is strictly worse than the
+ * malformed key it was meant to catch. If you are tempted to tighten this,
+ * the thing to tighten is the nexus write path, where an owner can still see
+ * and fix the error, not this read path where they cannot.
+ *
+ * ── WHY THE SDK RE-VALIDATES AT ALL ──
+ *
+ * Same reason `@reblu/site-next/analytics` re-checks `gaId` and `clarityId`
+ * (REB-617): base-api is not the only thing a SITE ever talks to, and the layer
+ * that owns the value is not the layer that suffers from it being wrong. As of
+ * REB-588 this column has NO validation anywhere — not in the nexus form, not on
+ * the way out of `/api/site/analytics`, not in the response contract, which is
+ * the one asymmetry `gaId`/`clarityId` do not share. Until that is fixed
+ * upstream, this is the only guard between a mistyped key and a contact form
+ * that renders, looks live, and silently eats every enquiry.
+ */
+declare const RECAPTCHA_SITE_KEY_PATTERN: RegExp;
+/**
+ * Whether `value` is a site key safe to put in the loader's script URL.
+ *
+ * Takes `unknown` on purpose: the value arrives over HTTP, so the contract's
+ * `string | null` is a promise about the shape, not a guarantee about the bytes.
+ */
+declare function isSafeRecaptchaSiteKey(value: unknown): value is string;
+/**
+ * The modes in which base-api will actually accept a submission.
+ *
+ * An ALLOW-LIST, never `mode !== 'DISABLED'`. The three differ only in what
+ * base-api DOES with the payload — a row, a webhook, an email — and the SITE
+ * must not care and must never learn the destination: a webhook URL or a Resend
+ * key is a tenant secret with no business in a public site.
+ *
+ * The deny-list version of this is a real incident, not a hypothetical: a page
+ * that hid the form on `DISABLED` and rendered it otherwise rendered it for
+ * `NOT_CONFIGURED` too — which is what EVERY freshly provisioned tenant carries
+ * until someone finishes the wizard (REB-586). 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.
+ */
+declare const CONTACT_FORM_OPERATIONAL_MODES: readonly ["DB_ONLY", "WEBHOOK", "RESEND"];
+/** A mode in which the form may be shown. */
+type ContactFormOperationalMode = (typeof CONTACT_FORM_OPERATIONAL_MODES)[number];
+/**
+ * The modes deliberately declined. A TYPE, never a value: the runtime must never
+ * read it, because an allow-list must not be expressible as "everything except
+ * this list", and this subpath's defining property is that it ships nothing it
+ * does not need. It exists only to feed {@link ContactFormModeExhaustiveCheck}.
+ */
+type DeclinedMode = 'NOT_CONFIGURED' | 'DISABLED';
+/**
+ * Compile-time exhaustiveness guard over `ContactFormMode`.
+ *
+ * `Missing` is constrained to `never` and DEFAULTS to the contract modes that
+ * are neither accepted nor explicitly declined, so a default violating its own
+ * constraint breaks the build the moment `@reblu/site-contracts` gains a mode.
+ *
+ * At runtime a new mode already fails closed, which is correct but SILENT — and
+ * silence is how a tenant switches their form on in nexus and watches nothing
+ * appear. This forces a human to make the call in a diff instead.
+ *
+ * Exported so it is never reported as an unused symbol.
+ */
+type ContactFormModeExhaustiveCheck<Missing extends never = Exclude<ContactFormMode, ContactFormOperationalMode | DeclinedMode>> = Missing;
+/** Why the form is not being shown. Drives diagnostics, never visitor-facing copy. */
+type ContactFormUnavailableReason = 
+/** The analytics read failed or was never made — no answer at all. */
+'unreadable'
+/** The tenant's mode is not one base-api accepts submissions in. */
+ | 'mode-not-operational'
+/** Accepting mode, but no site key: the browser cannot mint a token. */
+ | 'missing-recaptcha-key'
+/** A site key is present but cannot be a key — see {@link RECAPTCHA_SITE_KEY_PATTERN}. */
+ | 'malformed-recaptcha-key';
+type ContactFormAvailability = 
+/**
+ * Confirmed: base-api accepts submissions AND a usable site key exists. The
+ * key travels inside the `available` case on purpose — a component that has
+ * proven the form may render should not have to re-read (and re-null-check)
+ * the payload to find out what to render it WITH.
+ */
+{
+    state: 'available';
+    mode: ContactFormOperationalMode;
+    recaptchaSiteKey: string;
+} | {
+    state: 'unavailable';
+    reason: ContactFormUnavailableReason;
+};
+/**
+ * Resolve whether a contact form may be rendered for this tenant.
+ *
+ * We offer what we can CONFIRM, never what we have merely failed to disprove: an
+ * unknown mode, a mode from a runtime newer than this build, and a config read
+ * that threw all resolve to the same answer — no form. The page still shows the
+ * phone, the email and the address, so a hidden form costs a visitor one extra
+ * glance; a form that eats their message costs them the message.
+ *
+ * Order matters. The mode is checked BEFORE the key, because "the tenant has not
+ * switched the form on" is the actionable half of a double failure — a site key
+ * for a form nobody enabled is not the problem to fix first.
+ */
+declare function resolveContactFormAvailability(analytics: Analytics | null | undefined): ContactFormAvailability;
+/** Narrowing helper — the single question a renderer should ask. */
+declare function isContactFormAvailable(availability: ContactFormAvailability): availability is Extract<ContactFormAvailability, {
+    state: 'available';
+}>;
+/**
+ * The key to hand `GoogleReCaptchaProvider` on this render — `''` until `armed`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT THIS BUYS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `GoogleReCaptchaProvider` loads Google's `api.js` the moment it MOUNTS. Mount
+ * it with the form and every visitor who merely lands on the page to read the
+ * phone number has contacted Google — on a clinic's contact page, a third-party
+ * request nobody asked for, on a route whose whole subject is personal data.
+ *
+ * Arming on first interaction with the form (focus, first keystroke) means
+ * Google is contacted only for a visitor who is actually about to submit, which
+ * is the only visitor whose token is worth anything. It is a smaller page, a
+ * faster one, and a materially smaller consent surface.
+ *
+ * **This is NOT a cookie-consent implementation.** Deferring the script narrows
+ * the exposure; it does not gate it on a lawful basis. Full consent gating for
+ * third parties is REB-642 and has its own owner.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * HOW, WITHOUT A HACK — MEASURED, NOT ASSUMED
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `react-google-recaptcha-v3` injects the script from an effect shaped
+ *
+ *     useEffect(() => { if (reCaptchaKey) { …inject…; return cleanup } … },
+ *               [ …, reCaptchaKey, … ])
+ *
+ * Two facts fall out, and together they are the whole mechanism:
+ *
+ *   1. An EMPTY key mounts the provider and injects NOTHING.
+ *   2. `reCaptchaKey` is a dependency, so swapping the real key in later re-runs
+ *      the effect and injects the script then.
+ *
+ * Crucially the provider element never leaves the tree, so its children are
+ * never remounted: the visitor does not lose focus, a half-typed word, or the
+ * caret position at the instant the script arrives. This is the library's own
+ * documented prop doing its documented job — no imperative script injection, no
+ * reaching into the DOM, no fork.
+ *
+ * Both facts are pinned by `tests/recaptcha-deferred-oracle.test.tsx`, which
+ * drives the REAL library and counts script tags in the DOM. They are claims
+ * about someone else's code, so prose asserting them is not enough — if a future
+ * version of the library injects eagerly, that test goes red and this whole
+ * optimisation is known to be void.
+ *
+ * ── THE ONE COST, MEASURED ──
+ *
+ * On the empty-key render the library calls its own warn helper, which is
+ * written inverted, so the warning fires in PRODUCTION and stays silent in
+ * development. A visitor who opens devtools before touching a field sees one
+ * `"<GoogleReCaptchaProvider /> recaptcha key not provided"`. Cosmetic console
+ * noise, traded against a third-party request on every view of the page. Worth
+ * it, and recorded here so the next reader knows it is expected.
+ *
+ * ── AND NO FALLBACK KEY, EVER ──
+ *
+ * `''` for a blank OR malformed key however armed. There is no hardcoded
+ * fallback anywhere in this module, because a captcha key that is not the
+ * tenant's fails Google's verification while LOOKING configured — converting a
+ * visible gap an owner can fix in nexus into a silent one nobody can.
+ * {@link resolveContactFormAvailability} hides the form in that case; this is
+ * the second lock on the same door.
+ */
+declare function deferredRecaptchaKey(siteKey: string, armed: boolean): string;
+
+export { CONTACT_FORM_OPERATIONAL_MODES, type ContactFormAvailability, type ContactFormModeExhaustiveCheck, type ContactFormOperationalMode, type ContactFormUnavailableReason, RECAPTCHA_ACTION, RECAPTCHA_SITE_KEY_PATTERN, deferredRecaptchaKey, isContactFormAvailable, isSafeRecaptchaSiteKey, resolveContactFormAvailability };

package/dist/recaptcha.d.ts

@@ -0,0 +1,264 @@
+import { ContactFormMode, Analytics } from '@reblu/site-contracts';
+
+/**
+ * reCAPTCHA v3 — the SITE's half of the contract (REB-588).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHICH HALF LIVES WHERE, AND WHY
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * reCAPTCHA is two secrets and two steps, and they are deliberately split across
+ * a trust boundary:
+ *
+ *   SITE KEY  — public by design. It ships to the browser inside the script URL,
+ *               so the tenant serves it from `/api/site/analytics`. This module
+ *               handles it.
+ *   SECRET    — never leaves base-api. It is stored per tenant in
+ *               `site_integration_config.recaptchaSecretKey` and read only by
+ *               `serverCaptchaVerify` when `POST /api/site/contact-form` runs.
+ *
+ * **Nothing in this module, in this package, or anywhere in the `@reblu/site-*`
+ * SDK ever sees the secret, and nothing here calls Google's `siteverify`.** 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. Verification is base-api's job and already works: the SITE mints a
+ * token, posts it as `ContactFormInput.captcha`, and base-api decides.
+ *
+ * That is also why this module is NOT "reCAPTCHA support" in the round. It is
+ * the three decisions every SITE was otherwise making alone and differently:
+ * which action to name, whether a form may be shown at all, and when Google's
+ * script is allowed to load.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY IT IS IN THE SDK AT ALL
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Because it was already being written four times. `apps/base-api`,
+ * `apps/demo-site` and the external `reblu-site-dermamedicin` each grew their
+ * own copy of this flow, and they had already drifted — different action
+ * strings, different mount timing, a retry loop in one of them. A score that
+ * reCAPTCHA reports per action is not comparable across SITEs that name the
+ * action differently, and a defect fixed in one copy stays live in the other
+ * two. The SDK is where a decision gets made once.
+ *
+ * This module has ZERO runtime dependencies and imports nothing — not React, not
+ * `next`, not `react-google-recaptcha-v3`, not `@reblu/site-ui`. It is pure
+ * functions over plain data, callable from a Server Component deciding whether
+ * to render a form and from the Client Component that renders it. The subpath is
+ * kept dependency-free by `tests/recaptcha-subpath-isolation.test.ts`.
+ */
+
+/**
+ * The action name every Reblu SITE mints its contact-form token under.
+ *
+ * reCAPTCHA v3 scores PER ACTION, and a score is only interpretable against a
+ * stable one: Google's own admin console charts each action separately, and a
+ * threshold tuned on one action says nothing about another. Two SITEs calling
+ * `executeRecaptcha('submit_form')` and `executeRecaptcha('contact_form')` are
+ * building two unrelated score histories for the same feature — which is exactly
+ * the state the repo was in before this constant existed.
+ *
+ * `contact_form` over `submit_form` because it names the form, not the verb;
+ * a second protected form would need its own action, and `submit_form` would
+ * have nothing left to call it.
+ *
+ * ── WHAT THIS CONSTANT DOES **NOT** BUY, STATED PLAINLY ──
+ *
+ * It buys comparable scores. It does NOT bind a token to this form, because
+ * `serverCaptchaVerify` in base-api checks only `success` and `score`, and never
+ * reads the `action` field Google returns. A token minted for any other action
+ * on the same site verifies here exactly as well. Making the action load-bearing
+ * requires base-api to assert `action === RECAPTCHA_ACTION` on verify; until it
+ * does, do not read this constant as a security control.
+ */
+declare const RECAPTCHA_ACTION = "contact_form";
+/**
+ * The shape a site key must have before this SDK will hand it to Google.
+ *
+ * ── WHAT THIS IS, AND EMPHATICALLY WHAT IT IS NOT ──
+ *
+ * It is a SINK-SAFETY guard, not a guess at Google's key format. The key is
+ * interpolated into the loader's script URL as a query parameter, so what
+ * matters here is that it cannot carry a space, a quote, a newline, an `&`, or a
+ * `#` — characters that make a URL mean something other than what was intended.
+ * The base64url alphabet Google actually issues from (`A-Z a-z 0-9 - _`) is a
+ * strict subset of "safe", so a real key passes by construction.
+ *
+ * The length bounds are deliberately far wider than any key Google issues
+ * (theirs are 40 characters). A bound tight enough to be a real format check
+ * would be a bound tight enough to take a WORKING tenant's contact form offline
+ * the day Google changes its key length — which is strictly worse than the
+ * malformed key it was meant to catch. If you are tempted to tighten this,
+ * the thing to tighten is the nexus write path, where an owner can still see
+ * and fix the error, not this read path where they cannot.
+ *
+ * ── WHY THE SDK RE-VALIDATES AT ALL ──
+ *
+ * Same reason `@reblu/site-next/analytics` re-checks `gaId` and `clarityId`
+ * (REB-617): base-api is not the only thing a SITE ever talks to, and the layer
+ * that owns the value is not the layer that suffers from it being wrong. As of
+ * REB-588 this column has NO validation anywhere — not in the nexus form, not on
+ * the way out of `/api/site/analytics`, not in the response contract, which is
+ * the one asymmetry `gaId`/`clarityId` do not share. Until that is fixed
+ * upstream, this is the only guard between a mistyped key and a contact form
+ * that renders, looks live, and silently eats every enquiry.
+ */
+declare const RECAPTCHA_SITE_KEY_PATTERN: RegExp;
+/**
+ * Whether `value` is a site key safe to put in the loader's script URL.
+ *
+ * Takes `unknown` on purpose: the value arrives over HTTP, so the contract's
+ * `string | null` is a promise about the shape, not a guarantee about the bytes.
+ */
+declare function isSafeRecaptchaSiteKey(value: unknown): value is string;
+/**
+ * The modes in which base-api will actually accept a submission.
+ *
+ * An ALLOW-LIST, never `mode !== 'DISABLED'`. The three differ only in what
+ * base-api DOES with the payload — a row, a webhook, an email — and the SITE
+ * must not care and must never learn the destination: a webhook URL or a Resend
+ * key is a tenant secret with no business in a public site.
+ *
+ * The deny-list version of this is a real incident, not a hypothetical: a page
+ * that hid the form on `DISABLED` and rendered it otherwise rendered it for
+ * `NOT_CONFIGURED` too — which is what EVERY freshly provisioned tenant carries
+ * until someone finishes the wizard (REB-586). 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.
+ */
+declare const CONTACT_FORM_OPERATIONAL_MODES: readonly ["DB_ONLY", "WEBHOOK", "RESEND"];
+/** A mode in which the form may be shown. */
+type ContactFormOperationalMode = (typeof CONTACT_FORM_OPERATIONAL_MODES)[number];
+/**
+ * The modes deliberately declined. A TYPE, never a value: the runtime must never
+ * read it, because an allow-list must not be expressible as "everything except
+ * this list", and this subpath's defining property is that it ships nothing it
+ * does not need. It exists only to feed {@link ContactFormModeExhaustiveCheck}.
+ */
+type DeclinedMode = 'NOT_CONFIGURED' | 'DISABLED';
+/**
+ * Compile-time exhaustiveness guard over `ContactFormMode`.
+ *
+ * `Missing` is constrained to `never` and DEFAULTS to the contract modes that
+ * are neither accepted nor explicitly declined, so a default violating its own
+ * constraint breaks the build the moment `@reblu/site-contracts` gains a mode.
+ *
+ * At runtime a new mode already fails closed, which is correct but SILENT — and
+ * silence is how a tenant switches their form on in nexus and watches nothing
+ * appear. This forces a human to make the call in a diff instead.
+ *
+ * Exported so it is never reported as an unused symbol.
+ */
+type ContactFormModeExhaustiveCheck<Missing extends never = Exclude<ContactFormMode, ContactFormOperationalMode | DeclinedMode>> = Missing;
+/** Why the form is not being shown. Drives diagnostics, never visitor-facing copy. */
+type ContactFormUnavailableReason = 
+/** The analytics read failed or was never made — no answer at all. */
+'unreadable'
+/** The tenant's mode is not one base-api accepts submissions in. */
+ | 'mode-not-operational'
+/** Accepting mode, but no site key: the browser cannot mint a token. */
+ | 'missing-recaptcha-key'
+/** A site key is present but cannot be a key — see {@link RECAPTCHA_SITE_KEY_PATTERN}. */
+ | 'malformed-recaptcha-key';
+type ContactFormAvailability = 
+/**
+ * Confirmed: base-api accepts submissions AND a usable site key exists. The
+ * key travels inside the `available` case on purpose — a component that has
+ * proven the form may render should not have to re-read (and re-null-check)
+ * the payload to find out what to render it WITH.
+ */
+{
+    state: 'available';
+    mode: ContactFormOperationalMode;
+    recaptchaSiteKey: string;
+} | {
+    state: 'unavailable';
+    reason: ContactFormUnavailableReason;
+};
+/**
+ * Resolve whether a contact form may be rendered for this tenant.
+ *
+ * We offer what we can CONFIRM, never what we have merely failed to disprove: an
+ * unknown mode, a mode from a runtime newer than this build, and a config read
+ * that threw all resolve to the same answer — no form. The page still shows the
+ * phone, the email and the address, so a hidden form costs a visitor one extra
+ * glance; a form that eats their message costs them the message.
+ *
+ * Order matters. The mode is checked BEFORE the key, because "the tenant has not
+ * switched the form on" is the actionable half of a double failure — a site key
+ * for a form nobody enabled is not the problem to fix first.
+ */
+declare function resolveContactFormAvailability(analytics: Analytics | null | undefined): ContactFormAvailability;
+/** Narrowing helper — the single question a renderer should ask. */
+declare function isContactFormAvailable(availability: ContactFormAvailability): availability is Extract<ContactFormAvailability, {
+    state: 'available';
+}>;
+/**
+ * The key to hand `GoogleReCaptchaProvider` on this render — `''` until `armed`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT THIS BUYS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `GoogleReCaptchaProvider` loads Google's `api.js` the moment it MOUNTS. Mount
+ * it with the form and every visitor who merely lands on the page to read the
+ * phone number has contacted Google — on a clinic's contact page, a third-party
+ * request nobody asked for, on a route whose whole subject is personal data.
+ *
+ * Arming on first interaction with the form (focus, first keystroke) means
+ * Google is contacted only for a visitor who is actually about to submit, which
+ * is the only visitor whose token is worth anything. It is a smaller page, a
+ * faster one, and a materially smaller consent surface.
+ *
+ * **This is NOT a cookie-consent implementation.** Deferring the script narrows
+ * the exposure; it does not gate it on a lawful basis. Full consent gating for
+ * third parties is REB-642 and has its own owner.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * HOW, WITHOUT A HACK — MEASURED, NOT ASSUMED
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `react-google-recaptcha-v3` injects the script from an effect shaped
+ *
+ *     useEffect(() => { if (reCaptchaKey) { …inject…; return cleanup } … },
+ *               [ …, reCaptchaKey, … ])
+ *
+ * Two facts fall out, and together they are the whole mechanism:
+ *
+ *   1. An EMPTY key mounts the provider and injects NOTHING.
+ *   2. `reCaptchaKey` is a dependency, so swapping the real key in later re-runs
+ *      the effect and injects the script then.
+ *
+ * Crucially the provider element never leaves the tree, so its children are
+ * never remounted: the visitor does not lose focus, a half-typed word, or the
+ * caret position at the instant the script arrives. This is the library's own
+ * documented prop doing its documented job — no imperative script injection, no
+ * reaching into the DOM, no fork.
+ *
+ * Both facts are pinned by `tests/recaptcha-deferred-oracle.test.tsx`, which
+ * drives the REAL library and counts script tags in the DOM. They are claims
+ * about someone else's code, so prose asserting them is not enough — if a future
+ * version of the library injects eagerly, that test goes red and this whole
+ * optimisation is known to be void.
+ *
+ * ── THE ONE COST, MEASURED ──
+ *
+ * On the empty-key render the library calls its own warn helper, which is
+ * written inverted, so the warning fires in PRODUCTION and stays silent in
+ * development. A visitor who opens devtools before touching a field sees one
+ * `"<GoogleReCaptchaProvider /> recaptcha key not provided"`. Cosmetic console
+ * noise, traded against a third-party request on every view of the page. Worth
+ * it, and recorded here so the next reader knows it is expected.
+ *
+ * ── AND NO FALLBACK KEY, EVER ──
+ *
+ * `''` for a blank OR malformed key however armed. There is no hardcoded
+ * fallback anywhere in this module, because a captcha key that is not the
+ * tenant's fails Google's verification while LOOKING configured — converting a
+ * visible gap an owner can fix in nexus into a silent one nobody can.
+ * {@link resolveContactFormAvailability} hides the form in that case; this is
+ * the second lock on the same door.
+ */
+declare function deferredRecaptchaKey(siteKey: string, armed: boolean): string;
+
+export { CONTACT_FORM_OPERATIONAL_MODES, type ContactFormAvailability, type ContactFormModeExhaustiveCheck, type ContactFormOperationalMode, type ContactFormUnavailableReason, RECAPTCHA_ACTION, RECAPTCHA_SITE_KEY_PATTERN, deferredRecaptchaKey, isContactFormAvailable, isSafeRecaptchaSiteKey, resolveContactFormAvailability };

package/dist/recaptcha.js

@@ -0,0 +1,44 @@
+// src/recaptcha.ts
+var RECAPTCHA_ACTION = "contact_form";
+var RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+function isSafeRecaptchaSiteKey(value) {
+  return typeof value === "string" && RECAPTCHA_SITE_KEY_PATTERN.test(value);
+}
+var CONTACT_FORM_OPERATIONAL_MODES = ["DB_ONLY", "WEBHOOK", "RESEND"];
+function trimmed(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  return text.length > 0 ? text : null;
+}
+function isOperationalMode(mode) {
+  return CONTACT_FORM_OPERATIONAL_MODES.includes(mode);
+}
+function resolveContactFormAvailability(analytics) {
+  if (!analytics) return { state: "unavailable", reason: "unreadable" };
+  const mode = analytics.contactFormMode;
+  if (!isOperationalMode(mode)) return { state: "unavailable", reason: "mode-not-operational" };
+  const recaptchaSiteKey = trimmed(analytics.recaptchaSiteKey);
+  if (!recaptchaSiteKey) return { state: "unavailable", reason: "missing-recaptcha-key" };
+  if (!isSafeRecaptchaSiteKey(recaptchaSiteKey)) {
+    return { state: "unavailable", reason: "malformed-recaptcha-key" };
+  }
+  return { state: "available", mode, recaptchaSiteKey };
+}
+function isContactFormAvailable(availability) {
+  return availability.state === "available";
+}
+function deferredRecaptchaKey(siteKey, armed) {
+  if (!armed) return "";
+  const key = trimmed(siteKey);
+  return key && isSafeRecaptchaSiteKey(key) ? key : "";
+}
+export {
+  CONTACT_FORM_OPERATIONAL_MODES,
+  RECAPTCHA_ACTION,
+  RECAPTCHA_SITE_KEY_PATTERN,
+  deferredRecaptchaKey,
+  isContactFormAvailable,
+  isSafeRecaptchaSiteKey,
+  resolveContactFormAvailability
+};
+//# sourceMappingURL=recaptcha.js.map

package/dist/recaptcha.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recaptcha.ts"],"sourcesContent":["/**\n * reCAPTCHA v3 — the SITE's half of the contract (REB-588).\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHICH HALF LIVES WHERE, AND WHY\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * reCAPTCHA is two secrets and two steps, and they are deliberately split across\n * a trust boundary:\n *\n *   SITE KEY  — public by design. It ships to the browser inside the script URL,\n *               so the tenant serves it from `/api/site/analytics`. This module\n *               handles it.\n *   SECRET    — never leaves base-api. It is stored per tenant in\n *               `site_integration_config.recaptchaSecretKey` and read only by\n *               `serverCaptchaVerify` when `POST /api/site/contact-form` runs.\n *\n * **Nothing in this module, in this package, or anywhere in the `@reblu/site-*`\n * SDK ever sees the secret, and nothing here calls Google's `siteverify`.** A\n * SITE holding the secret would be a SITE that could be tricked into approving\n * its own tokens, and a distributable SDK is the worst possible place to put a\n * credential. Verification is base-api's job and already works: the SITE mints a\n * token, posts it as `ContactFormInput.captcha`, and base-api decides.\n *\n * That is also why this module is NOT \"reCAPTCHA support\" in the round. It is\n * the three decisions every SITE was otherwise making alone and differently:\n * which action to name, whether a form may be shown at all, and when Google's\n * script is allowed to load.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHY IT IS IN THE SDK AT ALL\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * Because it was already being written four times. `apps/base-api`,\n * `apps/demo-site` and the external `reblu-site-dermamedicin` each grew their\n * own copy of this flow, and they had already drifted — different action\n * strings, different mount timing, a retry loop in one of them. A score that\n * reCAPTCHA reports per action is not comparable across SITEs that name the\n * action differently, and a defect fixed in one copy stays live in the other\n * two. The SDK is where a decision gets made once.\n *\n * This module has ZERO runtime dependencies and imports nothing — not React, not\n * `next`, not `react-google-recaptcha-v3`, not `@reblu/site-ui`. It is pure\n * functions over plain data, callable from a Server Component deciding whether\n * to render a form and from the Client Component that renders it. The subpath is\n * kept dependency-free by `tests/recaptcha-subpath-isolation.test.ts`.\n */\n\nimport type { Analytics, ContactFormMode } from '@reblu/site-contracts'\n\n/**\n * The action name every Reblu SITE mints its contact-form token under.\n *\n * reCAPTCHA v3 scores PER ACTION, and a score is only interpretable against a\n * stable one: Google's own admin console charts each action separately, and a\n * threshold tuned on one action says nothing about another. Two SITEs calling\n * `executeRecaptcha('submit_form')` and `executeRecaptcha('contact_form')` are\n * building two unrelated score histories for the same feature — which is exactly\n * the state the repo was in before this constant existed.\n *\n * `contact_form` over `submit_form` because it names the form, not the verb;\n * a second protected form would need its own action, and `submit_form` would\n * have nothing left to call it.\n *\n * ── WHAT THIS CONSTANT DOES **NOT** BUY, STATED PLAINLY ──\n *\n * It buys comparable scores. It does NOT bind a token to this form, because\n * `serverCaptchaVerify` in base-api checks only `success` and `score`, and never\n * reads the `action` field Google returns. A token minted for any other action\n * on the same site verifies here exactly as well. Making the action load-bearing\n * requires base-api to assert `action === RECAPTCHA_ACTION` on verify; until it\n * does, do not read this constant as a security control.\n */\nexport const RECAPTCHA_ACTION = 'contact_form'\n\n/**\n * The shape a site key must have before this SDK will hand it to Google.\n *\n * ── WHAT THIS IS, AND EMPHATICALLY WHAT IT IS NOT ──\n *\n * It is a SINK-SAFETY guard, not a guess at Google's key format. The key is\n * interpolated into the loader's script URL as a query parameter, so what\n * matters here is that it cannot carry a space, a quote, a newline, an `&`, or a\n * `#` — characters that make a URL mean something other than what was intended.\n * The base64url alphabet Google actually issues from (`A-Z a-z 0-9 - _`) is a\n * strict subset of \"safe\", so a real key passes by construction.\n *\n * The length bounds are deliberately far wider than any key Google issues\n * (theirs are 40 characters). A bound tight enough to be a real format check\n * would be a bound tight enough to take a WORKING tenant's contact form offline\n * the day Google changes its key length — which is strictly worse than the\n * malformed key it was meant to catch. If you are tempted to tighten this,\n * the thing to tighten is the nexus write path, where an owner can still see\n * and fix the error, not this read path where they cannot.\n *\n * ── WHY THE SDK RE-VALIDATES AT ALL ──\n *\n * Same reason `@reblu/site-next/analytics` re-checks `gaId` and `clarityId`\n * (REB-617): base-api is not the only thing a SITE ever talks to, and the layer\n * that owns the value is not the layer that suffers from it being wrong. As of\n * REB-588 this column has NO validation anywhere — not in the nexus form, not on\n * the way out of `/api/site/analytics`, not in the response contract, which is\n * the one asymmetry `gaId`/`clarityId` do not share. Until that is fixed\n * upstream, this is the only guard between a mistyped key and a contact form\n * that renders, looks live, and silently eats every enquiry.\n */\nexport const RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/\n\n/**\n * Whether `value` is a site key safe to put in the loader's script URL.\n *\n * Takes `unknown` on purpose: the value arrives over HTTP, so the contract's\n * `string | null` is a promise about the shape, not a guarantee about the bytes.\n */\nexport function isSafeRecaptchaSiteKey(value: unknown): value is string {\n  return typeof value === 'string' && RECAPTCHA_SITE_KEY_PATTERN.test(value)\n}\n\n/**\n * The modes in which base-api will actually accept a submission.\n *\n * An ALLOW-LIST, never `mode !== 'DISABLED'`. The three differ only in what\n * base-api DOES with the payload — a row, a webhook, an email — and the SITE\n * must not care and must never learn the destination: a webhook URL or a Resend\n * key is a tenant secret with no business in a public site.\n *\n * The deny-list version of this is a real incident, not a hypothetical: a page\n * that hid the form on `DISABLED` and rendered it otherwise rendered it for\n * `NOT_CONFIGURED` too — which is what EVERY freshly provisioned tenant carries\n * until someone finishes the wizard (REB-586). A visitor typed out a medical\n * enquiry, pressed send, and got `503 Contact form is disabled`. They learned\n * the clinic could not be reached only after writing to it.\n */\nexport const CONTACT_FORM_OPERATIONAL_MODES = ['DB_ONLY', 'WEBHOOK', 'RESEND'] as const\n\n/** A mode in which the form may be shown. */\nexport type ContactFormOperationalMode = (typeof CONTACT_FORM_OPERATIONAL_MODES)[number]\n\n/**\n * The modes deliberately declined. A TYPE, never a value: the runtime must never\n * read it, because an allow-list must not be expressible as \"everything except\n * this list\", and this subpath's defining property is that it ships nothing it\n * does not need. It exists only to feed {@link ContactFormModeExhaustiveCheck}.\n */\ntype DeclinedMode = 'NOT_CONFIGURED' | 'DISABLED'\n\n/**\n * Compile-time exhaustiveness guard over `ContactFormMode`.\n *\n * `Missing` is constrained to `never` and DEFAULTS to the contract modes that\n * are neither accepted nor explicitly declined, so a default violating its own\n * constraint breaks the build the moment `@reblu/site-contracts` gains a mode.\n *\n * At runtime a new mode already fails closed, which is correct but SILENT — and\n * silence is how a tenant switches their form on in nexus and watches nothing\n * appear. This forces a human to make the call in a diff instead.\n *\n * Exported so it is never reported as an unused symbol.\n */\nexport type ContactFormModeExhaustiveCheck<\n  Missing extends never = Exclude<ContactFormMode, ContactFormOperationalMode | DeclinedMode>,\n> = Missing\n\n/** Why the form is not being shown. Drives diagnostics, never visitor-facing copy. */\nexport type ContactFormUnavailableReason =\n  /** The analytics read failed or was never made — no answer at all. */\n  | 'unreadable'\n  /** The tenant's mode is not one base-api accepts submissions in. */\n  | 'mode-not-operational'\n  /** Accepting mode, but no site key: the browser cannot mint a token. */\n  | 'missing-recaptcha-key'\n  /** A site key is present but cannot be a key — see {@link RECAPTCHA_SITE_KEY_PATTERN}. */\n  | 'malformed-recaptcha-key'\n\nexport type ContactFormAvailability =\n  /**\n   * Confirmed: base-api accepts submissions AND a usable site key exists. The\n   * key travels inside the `available` case on purpose — a component that has\n   * proven the form may render should not have to re-read (and re-null-check)\n   * the payload to find out what to render it WITH.\n   */\n  | { state: 'available'; mode: ContactFormOperationalMode; recaptchaSiteKey: string }\n  | { state: 'unavailable'; reason: ContactFormUnavailableReason }\n\n/** Whitespace-only is absent — a key someone saved blank is not a key. */\nfunction trimmed(value: unknown): string | null {\n  if (typeof value !== 'string') return null\n  const text = value.trim()\n  return text.length > 0 ? text : null\n}\n\nfunction isOperationalMode(mode: unknown): mode is ContactFormOperationalMode {\n  // Widened to `unknown` deliberately: see isSafeRecaptchaSiteKey. A base-api\n  // newer than this SDK sends a string TypeScript has never heard of, and it\n  // must fail closed rather than be assumed accepting.\n  return (CONTACT_FORM_OPERATIONAL_MODES as readonly string[]).includes(mode as string)\n}\n\n/**\n * Resolve whether a contact form may be rendered for this tenant.\n *\n * We offer what we can CONFIRM, never what we have merely failed to disprove: an\n * unknown mode, a mode from a runtime newer than this build, and a config read\n * that threw all resolve to the same answer — no form. The page still shows the\n * phone, the email and the address, so a hidden form costs a visitor one extra\n * glance; a form that eats their message costs them the message.\n *\n * Order matters. The mode is checked BEFORE the key, because \"the tenant has not\n * switched the form on\" is the actionable half of a double failure — a site key\n * for a form nobody enabled is not the problem to fix first.\n */\nexport function resolveContactFormAvailability(\n  analytics: Analytics | null | undefined,\n): ContactFormAvailability {\n  if (!analytics) return { state: 'unavailable', reason: 'unreadable' }\n\n  const mode = analytics.contactFormMode\n  if (!isOperationalMode(mode)) return { state: 'unavailable', reason: 'mode-not-operational' }\n\n  // `ContactFormInput.captcha` is REQUIRED and base-api verifies it, so an\n  // accepting mode with no usable key is still a form whose every submission is\n  // dead on arrival. \"Missing\" and \"malformed\" are separated because they call\n  // for different fixes by different people: one owner never filled the field,\n  // the other filled it with the wrong thing.\n  const recaptchaSiteKey = trimmed(analytics.recaptchaSiteKey)\n  if (!recaptchaSiteKey) return { state: 'unavailable', reason: 'missing-recaptcha-key' }\n  if (!isSafeRecaptchaSiteKey(recaptchaSiteKey)) {\n    return { state: 'unavailable', reason: 'malformed-recaptcha-key' }\n  }\n\n  return { state: 'available', mode, recaptchaSiteKey }\n}\n\n/** Narrowing helper — the single question a renderer should ask. */\nexport function isContactFormAvailable(\n  availability: ContactFormAvailability,\n): availability is Extract<ContactFormAvailability, { state: 'available' }> {\n  return availability.state === 'available'\n}\n\n/**\n * The key to hand `GoogleReCaptchaProvider` on this render — `''` until `armed`.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHAT THIS BUYS\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `GoogleReCaptchaProvider` loads Google's `api.js` the moment it MOUNTS. Mount\n * it with the form and every visitor who merely lands on the page to read the\n * phone number has contacted Google — on a clinic's contact page, a third-party\n * request nobody asked for, on a route whose whole subject is personal data.\n *\n * Arming on first interaction with the form (focus, first keystroke) means\n * Google is contacted only for a visitor who is actually about to submit, which\n * is the only visitor whose token is worth anything. It is a smaller page, a\n * faster one, and a materially smaller consent surface.\n *\n * **This is NOT a cookie-consent implementation.** Deferring the script narrows\n * the exposure; it does not gate it on a lawful basis. Full consent gating for\n * third parties is REB-642 and has its own owner.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * HOW, WITHOUT A HACK — MEASURED, NOT ASSUMED\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `react-google-recaptcha-v3` injects the script from an effect shaped\n *\n *     useEffect(() => { if (reCaptchaKey) { …inject…; return cleanup } … },\n *               [ …, reCaptchaKey, … ])\n *\n * Two facts fall out, and together they are the whole mechanism:\n *\n *   1. An EMPTY key mounts the provider and injects NOTHING.\n *   2. `reCaptchaKey` is a dependency, so swapping the real key in later re-runs\n *      the effect and injects the script then.\n *\n * Crucially the provider element never leaves the tree, so its children are\n * never remounted: the visitor does not lose focus, a half-typed word, or the\n * caret position at the instant the script arrives. This is the library's own\n * documented prop doing its documented job — no imperative script injection, no\n * reaching into the DOM, no fork.\n *\n * Both facts are pinned by `tests/recaptcha-deferred-oracle.test.tsx`, which\n * drives the REAL library and counts script tags in the DOM. They are claims\n * about someone else's code, so prose asserting them is not enough — if a future\n * version of the library injects eagerly, that test goes red and this whole\n * optimisation is known to be void.\n *\n * ── THE ONE COST, MEASURED ──\n *\n * On the empty-key render the library calls its own warn helper, which is\n * written inverted, so the warning fires in PRODUCTION and stays silent in\n * development. A visitor who opens devtools before touching a field sees one\n * `\"<GoogleReCaptchaProvider /> recaptcha key not provided\"`. Cosmetic console\n * noise, traded against a third-party request on every view of the page. Worth\n * it, and recorded here so the next reader knows it is expected.\n *\n * ── AND NO FALLBACK KEY, EVER ──\n *\n * `''` for a blank OR malformed key however armed. There is no hardcoded\n * fallback anywhere in this module, because a captcha key that is not the\n * tenant's fails Google's verification while LOOKING configured — converting a\n * visible gap an owner can fix in nexus into a silent one nobody can.\n * {@link resolveContactFormAvailability} hides the form in that case; this is\n * the second lock on the same door.\n */\nexport function deferredRecaptchaKey(siteKey: string, armed: boolean): string {\n  if (!armed) return ''\n  const key = trimmed(siteKey)\n  return key && isSafeRecaptchaSiteKey(key) ? key : ''\n}\n"],"mappings":";AAyEO,IAAM,mBAAmB;AAiCzB,IAAM,6BAA6B;AAQnC,SAAS,uBAAuB,OAAiC;AACtE,SAAO,OAAO,UAAU,YAAY,2BAA2B,KAAK,KAAK;AAC3E;AAiBO,IAAM,iCAAiC,CAAC,WAAW,WAAW,QAAQ;AAoD7E,SAAS,QAAQ,OAA+B;AAC9C,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,OAAO,MAAM,KAAK;AACxB,SAAO,KAAK,SAAS,IAAI,OAAO;AAClC;AAEA,SAAS,kBAAkB,MAAmD;AAI5E,SAAQ,+BAAqD,SAAS,IAAc;AACtF;AAeO,SAAS,+BACd,WACyB;AACzB,MAAI,CAAC,UAAW,QAAO,EAAE,OAAO,eAAe,QAAQ,aAAa;AAEpE,QAAM,OAAO,UAAU;AACvB,MAAI,CAAC,kBAAkB,IAAI,EAAG,QAAO,EAAE,OAAO,eAAe,QAAQ,uBAAuB;AAO5F,QAAM,mBAAmB,QAAQ,UAAU,gBAAgB;AAC3D,MAAI,CAAC,iBAAkB,QAAO,EAAE,OAAO,eAAe,QAAQ,wBAAwB;AACtF,MAAI,CAAC,uBAAuB,gBAAgB,GAAG;AAC7C,WAAO,EAAE,OAAO,eAAe,QAAQ,0BAA0B;AAAA,EACnE;AAEA,SAAO,EAAE,OAAO,aAAa,MAAM,iBAAiB;AACtD;AAGO,SAAS,uBACd,cAC0E;AAC1E,SAAO,aAAa,UAAU;AAChC;AAoEO,SAAS,qBAAqB,SAAiB,OAAwB;AAC5E,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,MAAM,QAAQ,OAAO;AAC3B,SAAO,OAAO,uBAAuB,GAAG,IAAI,MAAM;AACpD;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reblu/site-next",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Next.js RSC glue for Reblu SITEs — cache + CTA + auth server/client components.",
   "license": "Apache-2.0",
   "author": "Reblu — Adolfo Unturbe",
@@ -100,6 +100,16 @@
         "types": "./dist/analytics.d.cts",
         "default": "./dist/analytics.cjs"
       }
+    },
+    "./recaptcha": {
+      "import": {
+        "types": "./dist/recaptcha.d.ts",
+        "default": "./dist/recaptcha.js"
+      },
+      "require": {
+        "types": "./dist/recaptcha.d.cts",
+        "default": "./dist/recaptcha.cjs"
+      }
     }
   },
   "publishConfig": {
@@ -113,7 +123,7 @@
   "dependencies": {
     "@reblu/site-client": "^4.0.0",
     "@reblu/site-contracts": "^0.5.0",
-    "@reblu/site-ui": "^0.4.0"
+    "@reblu/site-ui": "^0.5.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -128,6 +138,7 @@
     "next-themes": "^0.4.6",
     "react": "19.2.4",
     "react-dom": "19.2.4",
+    "react-google-recaptcha-v3": "^1.11.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.0.15",