@reblu/site-next 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @reblu/site-next
 
+## 1.11.0
+
+### Minor Changes
+
+- 604d464: Add `@reblu/site-next/recaptcha-provider` (REB-793): `<DeferredRecaptchaProvider>` and `useDeferredRecaptcha()` fix a defect in the REB-588 deferred-load pattern where wiring `deferredRecaptchaKey`'s return value directly into `<GoogleReCaptchaProvider reCaptchaKey={...}>` loaded Google's script with the correct site key but kept calling `executeRecaptcha` with the stale empty key from before arming — `react-google-recaptcha-v3@1.11.0` captures `reCaptchaKey` in a `useRef` on first mount and never re-reads it for invisible v3. Every token mint threw, so every contact-form submission silently failed to reach base-api. `DeferredRecaptchaProvider` applies the same validated key as both the `key` and the `reCaptchaKey` prop, forcing a full remount of the vendor provider on arm instead of a prop swap, while republishing `executeRecaptcha` through a stable context so the SITE's own form (and any in-flight submit) never remounts. `deferredRecaptchaKey` (`./recaptcha`) stays exported and unchanged — now documented `@deprecated` for direct use with `<GoogleReCaptchaProvider>` — and `react-google-recaptcha-v3` remains the consuming SITE's own optional peer dependency, never bundled into the SDK.
+
+## 1.10.0
+
+### Minor Changes
+
+- 2e53bf9: Add `@reblu/site-next/consent` and `@reblu/site-next/consent-server` (REB-642): a cookie-consent mechanism for Reblu SITEs — `<ConsentProvider>`/`useConsent()`, `<ConsentGate>`, `<CookieBanner>` (accept/reject/configure, three equal-weight buttons + an accessible preferences dialog), `<CookiePreferencesTrigger>` for permanent withdrawal, and `<ConsentedAnalytics>` wrapping `<AnalyticsScripts>` behind the `analytics` category. Every non-necessary category defaults to denied, and a stored choice is re-asked automatically when the tenant's cookie-policy content hash changes. `./consent-server` is a dependency-free, isomorphic module (cookie name, category taxonomy, fail-closed cookie parsing, `cookiePolicyVersion()` content hash).
+
+### Patch Changes
+
+- Updated dependencies [34b15c4]
+  - @reblu/site-contracts@1.2.0
+
 ## 1.9.0
 
 ### Minor Changes

package/README.md

@@ -15,9 +15,10 @@ 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.
+5. **reCAPTCHA v3** (`./recaptcha`, `./recaptcha-provider`) — the SITE's half
+   of the contact-form captcha contract: the canonical action, the render
+   gate, and a defect-fixed (REB-793) interaction-mount provider,
+   `<DeferredRecaptchaProvider>`. See "reCAPTCHA v3" below.
 6. **Academy** (`./academy`, `./academy-server`) — `AcademyEnrollmentForm`,
    the anonymous enrollment-request form, plus `deriveValidationFields` to
    build its per-tenant validation fields from course/config data. See
@@ -29,7 +30,9 @@ intentionally Next-coupled so the lower SDK layers —
 pnpm add @reblu/site-next @reblu/site-client @reblu/site-contracts @reblu/site-ui next-themes
 ```
 
-Peer deps: `react >=19`, `next >=16`, `@reblu/site-ui`, `next-themes`.
+Peer deps: `react >=19`, `next >=16`, `@reblu/site-ui`, `next-themes`, and
+optionally `react-google-recaptcha-v3` (only if you use
+`@reblu/site-next/recaptcha-provider` — see "reCAPTCHA v3" below).
 
 `next-themes` is required by the `./auth` entry as a whole, not only by
 `AuthLogo`: `tsup.config.ts` builds `auth.js`/`auth.cjs` as ONE
@@ -328,33 +331,76 @@ 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'
+import { RECAPTCHA_ACTION } from '@reblu/site-next/recaptcha'
+import { DeferredRecaptchaProvider, useDeferredRecaptcha } from '@reblu/site-next/recaptcha-provider'
 
 const [armed, setArmed] = useState(false)
 
-<GoogleReCaptchaProvider reCaptchaKey={deferredRecaptchaKey(siteKey, armed)}>
+<DeferredRecaptchaProvider siteKey={siteKey} armed={armed}>
   <form onFocusCapture={() => setArmed(true)}>…</form>
-</GoogleReCaptchaProvider>
+</DeferredRecaptchaProvider>
 
-// at submit: await executeRecaptcha(RECAPTCHA_ACTION)
+// inside the form, instead of react-google-recaptcha-v3's own useGoogleReCaptcha():
+const { executeRecaptcha } = useDeferredRecaptcha()
+// 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.
+with the form means every visitor who merely lands on the page to read the
+phone number has contacted Google. `DeferredRecaptchaProvider` withholds a real
+key until `armed`, exactly like `deferredRecaptchaKey` (below) did — but see
+**REB-793** for why it does not stop there.
+
+> **REB-793 — do not wire `deferredRecaptchaKey` straight into
+> `<GoogleReCaptchaProvider>`.** That was this section's guidance before
+> REB-793 and it is a confirmed defect: `react-google-recaptcha-v3@1.11.0`
+> captures `reCaptchaKey` in a `useRef` on the FIRST render and only ever
+> reassigns it through a callback the library wires when a visible widget
+> `container` is configured — invisible v3 (no `container`, the only mode any
+> Reblu SITE uses) never triggers that path. Swapping the prop from `''` to
+> the real key therefore loads `api.js` with the correct key while
+> `executeRecaptcha` keeps sending `''` to `grecaptcha.execute` forever —
+> every token mint throws, every submission silently dies. Found 29-Sep in the
+> first real contact-form test on dermamedicin preprod: zero requests reached
+> `/api/site/contact-form`. `deferredRecaptchaKey` stays exported (see its own
+> `@deprecated` doc) because `DeferredRecaptchaProvider` calls it internally
+> and removing it would be a breaking change — but do not call it directly
+> against `<GoogleReCaptchaProvider>` yourself.
+
+`DeferredRecaptchaProvider` fixes this by applying that same validated key as
+BOTH the `key` prop and the `reCaptchaKey` prop on the vendor's
+`GoogleReCaptchaProvider`. A `key` change forces React to unmount the
+empty-key instance (which never loaded anything) and mount a brand-new one
+whose `useRef` captures the real key from its very first render — never a
+stale prop swap on a live instance. That remount is contained to an internal,
+invisible bridge component; **the SITE's own `children` — the form — never
+remounts**, because they render as a sibling under a separate, stable context
+that `useDeferredRecaptcha()` reads. A visitor's typed fields, and an
+in-flight submit awaiting `executeRecaptcha` (demo-site's own arm-on-submit
+fallback for a visitor who tabs straight to the button), both survive arming.
+
+Both the vendor's mount-vs-inject behaviour and this fix's own claims about
+key-vs-execute correctness are pinned by real end-to-end tests, not prose:
+`tests/recaptcha-deferred-oracle.test.tsx` drives the real
+`react-google-recaptcha-v3` and counts script tags in the DOM (the original
+REB-588 oracle); `tests/recaptcha-provider.test.tsx` goes one step further and
+actually calls `executeRecaptcha`, asserting `grecaptcha.execute` was invoked
+with the ARMED site key — including a negative control that reproduces the
+REB-793 bug directly against the vendor library, so this suite is proven to
+catch it if it ever comes back. If a future library version injects eagerly,
+or stops honoring `key`-based remounts, these tests go 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.
 
+`DeferredRecaptchaProvider`/`useDeferredRecaptcha` live in their own subpath
+(`./recaptcha-provider`), separate from `./recaptcha` above, because they
+import React and `react-google-recaptcha-v3` — see "Which half lives where" —
+so `react-google-recaptcha-v3` is an OPTIONAL peer dependency of this package:
+install it yourself alongside `@reblu/site-next` (it already is, if you
+followed "Install" above).
+
 `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.

package/dist/consent-server.cjs

@@ -0,0 +1,88 @@
+"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/consent-server.ts
+var consent_server_exports = {};
+__export(consent_server_exports, {
+  CONSENT_CATEGORIES: () => CONSENT_CATEGORIES,
+  CONSENT_COOKIE_NAME: () => CONSENT_COOKIE_NAME,
+  DEFAULT_CONSENT_CATEGORIES: () => DEFAULT_CONSENT_CATEGORIES,
+  cookiePolicyVersion: () => cookiePolicyVersion,
+  parseConsentCookie: () => parseConsentCookie,
+  serializeConsentCookie: () => serializeConsentCookie
+});
+module.exports = __toCommonJS(consent_server_exports);
+var import_node_crypto = require("crypto");
+
+// src/consent-shared.ts
+var CONSENT_COOKIE_NAME = "reblu_consent";
+var CONSENT_CATEGORIES = ["analytics", "marketing", "preferences"];
+var DEFAULT_CONSENT_CATEGORIES = Object.freeze(
+  CONSENT_CATEGORIES.reduce(
+    (state, category) => ({ ...state, [category]: false }),
+    {}
+  )
+);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseCategories(value) {
+  if (!isPlainObject(value)) return null;
+  const result = {};
+  for (const category of CONSENT_CATEGORIES) {
+    const raw = value[category];
+    if (typeof raw !== "boolean") return null;
+    result[category] = raw;
+  }
+  return result;
+}
+function parseConsentCookie(raw) {
+  if (!raw) return null;
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(json)) return null;
+  const categories = parseCategories(json.categories);
+  if (!categories) return null;
+  const policyVersion = json.policyVersion;
+  if (policyVersion !== null && typeof policyVersion !== "string") return null;
+  return { categories, policyVersion };
+}
+function serializeConsentCookie(payload) {
+  return JSON.stringify(payload);
+}
+
+// src/consent-server.ts
+function cookiePolicyVersion(policy) {
+  if (!policy) return null;
+  return (0, import_node_crypto.createHash)("sha256").update(policy, "utf8").digest("hex").slice(0, 12);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONSENT_CATEGORIES,
+  CONSENT_COOKIE_NAME,
+  DEFAULT_CONSENT_CATEGORIES,
+  cookiePolicyVersion,
+  parseConsentCookie,
+  serializeConsentCookie
+});
+//# sourceMappingURL=consent-server.cjs.map

package/dist/consent-server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consent-server.ts","../src/consent-shared.ts"],"sourcesContent":["import { createHash } from 'node:crypto'\n\nimport {\n  CONSENT_CATEGORIES,\n  CONSENT_COOKIE_NAME,\n  DEFAULT_CONSENT_CATEGORIES,\n  parseConsentCookie,\n  serializeConsentCookie,\n  type ConsentCategory,\n  type ConsentCategoryState,\n  type ConsentCookiePayload,\n} from './consent-shared'\n\n/**\n * `@reblu/site-next/consent-server` — the full server-side surface of cookie\n * consent (REB-642): everything in `./consent-shared` (cookie name, category\n * taxonomy, fail-closed parse/serialise), PLUS `cookiePolicyVersion()`, the\n * one function in this whole mechanism that needs a real dependency\n * (`node:crypto`, a Node builtin — not an npm package).\n *\n * This is the PUBLIC subpath (`@reblu/site-next/consent-server`) — a SITE's\n * server-side code (Route Handler, Server Component) imports from here.\n * `./consent-shared` re-exported below is intentionally the ONLY thing the\n * CLIENT entry (`./consent`) imports from; see that file's doc comment for\n * why `cookiePolicyVersion` and its `node:crypto` import must never be\n * reachable from a client component, even transitively.\n */\n\nexport {\n  CONSENT_CATEGORIES,\n  CONSENT_COOKIE_NAME,\n  DEFAULT_CONSENT_CATEGORIES,\n  parseConsentCookie,\n  serializeConsentCookie,\n  type ConsentCategory,\n  type ConsentCategoryState,\n  type ConsentCookiePayload,\n}\n\n/**\n * A content hash of the tenant's cookie policy, standing in for a stored\n * version string (REB-642 §7.2). A hash cannot drift the way a manually\n * bumped version number can: a tenant editing the policy text automatically\n * produces a new version, and `./consent`'s provider re-asks consent the\n * moment the version it holds no longer matches. `null` in, `null` out — a\n * tenant with no cookie policy stored has no version to pin.\n *\n * SERVER-ONLY: a SITE computes this once (from `SiteSettings.cookiePolicy`)\n * and passes the resulting string to `<ConsentProvider policyVersion>` as a\n * plain prop. Nothing under `@reblu/site-next/consent` calls this function or\n * imports `node:crypto` — enforced by `tests/consent-subpath-isolation.test.ts`.\n *\n * First 12 hex characters of SHA-256, matching the length asserted by this\n * function's own test and short enough to store cheaply alongside the\n * categories in the cookie.\n */\nexport function cookiePolicyVersion(policy: string | null | undefined): string | null {\n  if (!policy) return null\n  return createHash('sha256').update(policy, 'utf8').digest('hex').slice(0, 12)\n}\n","/**\n * `../consent-shared` — the truly isomorphic core of cookie consent (REB-642):\n * the cookie name, the category taxonomy, and fail-closed parse/serialise.\n * ZERO dependencies, including Node builtins — this is the one thing that\n * matters about this file's existence.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHY THIS IS A SEPARATE FILE FROM `./consent-server.ts`\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `./consent` (the client entry) needs `CONSENT_CATEGORIES` and friends, and\n * imports them straight from here. `./consent-server.ts` ALSO needs them, plus\n * `cookiePolicyVersion()`, which needs `node:crypto`. Those two facts collide\n * under this package's build rules: `tsup.config.ts` runs with\n * `treeshake: false` — REQUIRED to keep the `'use client'` prologue on the\n * `./consent` entry from being stripped (see the R4 note there) — and with\n * tree-shaking off, esbuild bundles an imported FILE WHOLESALE, not just the\n * specific binding a module asked for. So if `cookiePolicyVersion` (and its\n * `node:crypto` import) lived in the SAME file as `CONSENT_CATEGORIES`, every\n * client component that only wanted the category list would drag `node:crypto`\n * into the browser bundle too — dead weight at best, a broken build on a\n * bundler stricter than tsup about Node builtins in client code at worst. This\n * was caught live: `tests/consent-subpath-isolation.test.ts` asserts `./consent`\n * never references `crypto`, and failed until this split existed.\n *\n * `./consent-server.ts` re-exports everything here, so\n * `@reblu/site-next/consent-server` keeps serving the full public surface —\n * this split is purely internal.\n *\n * A cookie is attacker- and drift-controlled input: a visitor can edit it in\n * devtools, an older SDK version can leave a differently-shaped payload\n * behind, and a proxy or extension can mangle it in transit.\n * `parseConsentCookie` never coerces a doubtful value toward \"granted\" —\n * anything that is not EXACTLY the expected shape (an object, every known\n * category present and a strict boolean, `policyVersion` a string or `null`)\n * resolves to `null`, which `./consent`'s provider treats identically to \"no\n * cookie yet\": ask again, default every category denied. Silently granting a\n * truthy-but-malformed value is the one mistake this module is built to make\n * impossible.\n */\n\n/** The first-party cookie a visitor's consent choice is stored in. */\nexport const CONSENT_COOKIE_NAME = 'reblu_consent'\n\n/**\n * The fixed, non-tenant-editable category taxonomy (REB-642 §7.1): \"If each\n * SITE invents its own categories, no two clinics can be audited the same\n * way.\" `necessary` is deliberately NOT a member — it is not a choice, it has\n * no toggle, and it is never read from or written to the cookie.\n */\nexport const CONSENT_CATEGORIES = ['analytics', 'marketing', 'preferences'] as const\n\n/** One of the fixed consent categories. */\nexport type ConsentCategory = (typeof CONSENT_CATEGORIES)[number]\n\n/** A visitor's granted/denied state for every optional category. */\nexport type ConsentCategoryState = Record<ConsentCategory, boolean>\n\n/** The full payload stored in the consent cookie. */\nexport interface ConsentCookiePayload {\n  categories: ConsentCategoryState\n  /** The `cookiePolicyVersion()` in force when this choice was recorded, or `null`. */\n  policyVersion: string | null\n}\n\n/** Every optional category denied — the only safe default. */\nexport const DEFAULT_CONSENT_CATEGORIES: Readonly<ConsentCategoryState> = Object.freeze(\n  CONSENT_CATEGORIES.reduce(\n    (state, category) => ({ ...state, [category]: false }),\n    {} as ConsentCategoryState,\n  ),\n)\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * Reads and validates the categories object, requiring every known category to\n * be present as a STRICT boolean. Returns `null` on any deviation — a missing\n * category, an extra one being the only thing wrong is fine (ignored, never\n * leaked into the result), but a category that is present and not `true`/`false`\n * literally, or one that is simply absent, fails the whole parse closed. A\n * partial payload does NOT default the missing categories to `false`: that\n * would make \"a payload half-stripped by a proxy\" indistinguishable from \"a\n * visitor who explicitly denied the rest\", which is not a distinction this\n * function is in a position to make safely.\n */\nfunction parseCategories(value: unknown): ConsentCategoryState | null {\n  if (!isPlainObject(value)) return null\n\n  const result = {} as ConsentCategoryState\n  for (const category of CONSENT_CATEGORIES) {\n    const raw = value[category]\n    if (typeof raw !== 'boolean') return null\n    result[category] = raw\n  }\n  return result\n}\n\n/**\n * Parses a raw consent cookie value into a validated payload, or `null` if the\n * value is absent or does not match the expected shape exactly. See the module\n * doc for why this fails closed rather than coercing.\n */\nexport function parseConsentCookie(raw: string | null | undefined): ConsentCookiePayload | null {\n  if (!raw) return null\n\n  let json: unknown\n  try {\n    json = JSON.parse(raw)\n  } catch {\n    return null\n  }\n\n  if (!isPlainObject(json)) return null\n\n  const categories = parseCategories(json.categories)\n  if (!categories) return null\n\n  const policyVersion = json.policyVersion\n  if (policyVersion !== null && typeof policyVersion !== 'string') return null\n\n  return { categories, policyVersion }\n}\n\n/** Serialises a consent payload for storage in the cookie. */\nexport function serializeConsentCookie(payload: ConsentCookiePayload): string {\n  return JSON.stringify(payload)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAA2B;;;AC0CpB,IAAM,sBAAsB;AAQ5B,IAAM,qBAAqB,CAAC,aAAa,aAAa,aAAa;AAgBnE,IAAM,6BAA6D,OAAO;AAAA,EAC/E,mBAAmB;AAAA,IACjB,CAAC,OAAO,cAAc,EAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,MAAM;AAAA,IACpD,CAAC;AAAA,EACH;AACF;AAEA,SAAS,cAAc,OAAkD;AACvE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAaA,SAAS,gBAAgB,OAA6C;AACpE,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO;AAElC,QAAM,SAAS,CAAC;AAChB,aAAW,YAAY,oBAAoB;AACzC,UAAM,MAAM,MAAM,QAAQ;AAC1B,QAAI,OAAO,QAAQ,UAAW,QAAO;AACrC,WAAO,QAAQ,IAAI;AAAA,EACrB;AACA,SAAO;AACT;AAOO,SAAS,mBAAmB,KAA6D;AAC9F,MAAI,CAAC,IAAK,QAAO;AAEjB,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,MAAI,CAAC,cAAc,IAAI,EAAG,QAAO;AAEjC,QAAM,aAAa,gBAAgB,KAAK,UAAU;AAClD,MAAI,CAAC,WAAY,QAAO;AAExB,QAAM,gBAAgB,KAAK;AAC3B,MAAI,kBAAkB,QAAQ,OAAO,kBAAkB,SAAU,QAAO;AAExE,SAAO,EAAE,YAAY,cAAc;AACrC;AAGO,SAAS,uBAAuB,SAAuC;AAC5E,SAAO,KAAK,UAAU,OAAO;AAC/B;;;ADzEO,SAAS,oBAAoB,QAAkD;AACpF,MAAI,CAAC,OAAQ,QAAO;AACpB,aAAO,+BAAW,QAAQ,EAAE,OAAO,QAAQ,MAAM,EAAE,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AAC9E;","names":[]}

package/dist/consent-server.d.cts

@@ -0,0 +1,22 @@
+export { C as CONSENT_CATEGORIES, a as CONSENT_COOKIE_NAME, b as ConsentCategory, c as ConsentCategoryState, d as ConsentCookiePayload, D as DEFAULT_CONSENT_CATEGORIES, p as parseConsentCookie, s as serializeConsentCookie } from './consent-shared-DbdhEXW2.cjs';
+
+/**
+ * A content hash of the tenant's cookie policy, standing in for a stored
+ * version string (REB-642 §7.2). A hash cannot drift the way a manually
+ * bumped version number can: a tenant editing the policy text automatically
+ * produces a new version, and `./consent`'s provider re-asks consent the
+ * moment the version it holds no longer matches. `null` in, `null` out — a
+ * tenant with no cookie policy stored has no version to pin.
+ *
+ * SERVER-ONLY: a SITE computes this once (from `SiteSettings.cookiePolicy`)
+ * and passes the resulting string to `<ConsentProvider policyVersion>` as a
+ * plain prop. Nothing under `@reblu/site-next/consent` calls this function or
+ * imports `node:crypto` — enforced by `tests/consent-subpath-isolation.test.ts`.
+ *
+ * First 12 hex characters of SHA-256, matching the length asserted by this
+ * function's own test and short enough to store cheaply alongside the
+ * categories in the cookie.
+ */
+declare function cookiePolicyVersion(policy: string | null | undefined): string | null;
+
+export { cookiePolicyVersion };

package/dist/consent-server.d.ts

@@ -0,0 +1,22 @@
+export { C as CONSENT_CATEGORIES, a as CONSENT_COOKIE_NAME, b as ConsentCategory, c as ConsentCategoryState, d as ConsentCookiePayload, D as DEFAULT_CONSENT_CATEGORIES, p as parseConsentCookie, s as serializeConsentCookie } from './consent-shared-DbdhEXW2.js';
+
+/**
+ * A content hash of the tenant's cookie policy, standing in for a stored
+ * version string (REB-642 §7.2). A hash cannot drift the way a manually
+ * bumped version number can: a tenant editing the policy text automatically
+ * produces a new version, and `./consent`'s provider re-asks consent the
+ * moment the version it holds no longer matches. `null` in, `null` out — a
+ * tenant with no cookie policy stored has no version to pin.
+ *
+ * SERVER-ONLY: a SITE computes this once (from `SiteSettings.cookiePolicy`)
+ * and passes the resulting string to `<ConsentProvider policyVersion>` as a
+ * plain prop. Nothing under `@reblu/site-next/consent` calls this function or
+ * imports `node:crypto` — enforced by `tests/consent-subpath-isolation.test.ts`.
+ *
+ * First 12 hex characters of SHA-256, matching the length asserted by this
+ * function's own test and short enough to store cheaply alongside the
+ * categories in the cookie.
+ */
+declare function cookiePolicyVersion(policy: string | null | undefined): string | null;
+
+export { cookiePolicyVersion };

package/dist/consent-server.js

@@ -0,0 +1,58 @@
+// src/consent-server.ts
+import { createHash } from "crypto";
+
+// src/consent-shared.ts
+var CONSENT_COOKIE_NAME = "reblu_consent";
+var CONSENT_CATEGORIES = ["analytics", "marketing", "preferences"];
+var DEFAULT_CONSENT_CATEGORIES = Object.freeze(
+  CONSENT_CATEGORIES.reduce(
+    (state, category) => ({ ...state, [category]: false }),
+    {}
+  )
+);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseCategories(value) {
+  if (!isPlainObject(value)) return null;
+  const result = {};
+  for (const category of CONSENT_CATEGORIES) {
+    const raw = value[category];
+    if (typeof raw !== "boolean") return null;
+    result[category] = raw;
+  }
+  return result;
+}
+function parseConsentCookie(raw) {
+  if (!raw) return null;
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(json)) return null;
+  const categories = parseCategories(json.categories);
+  if (!categories) return null;
+  const policyVersion = json.policyVersion;
+  if (policyVersion !== null && typeof policyVersion !== "string") return null;
+  return { categories, policyVersion };
+}
+function serializeConsentCookie(payload) {
+  return JSON.stringify(payload);
+}
+
+// src/consent-server.ts
+function cookiePolicyVersion(policy) {
+  if (!policy) return null;
+  return createHash("sha256").update(policy, "utf8").digest("hex").slice(0, 12);
+}
+export {
+  CONSENT_CATEGORIES,
+  CONSENT_COOKIE_NAME,
+  DEFAULT_CONSENT_CATEGORIES,
+  cookiePolicyVersion,
+  parseConsentCookie,
+  serializeConsentCookie
+};
+//# sourceMappingURL=consent-server.js.map

package/dist/consent-server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consent-server.ts","../src/consent-shared.ts"],"sourcesContent":["import { createHash } from 'node:crypto'\n\nimport {\n  CONSENT_CATEGORIES,\n  CONSENT_COOKIE_NAME,\n  DEFAULT_CONSENT_CATEGORIES,\n  parseConsentCookie,\n  serializeConsentCookie,\n  type ConsentCategory,\n  type ConsentCategoryState,\n  type ConsentCookiePayload,\n} from './consent-shared'\n\n/**\n * `@reblu/site-next/consent-server` — the full server-side surface of cookie\n * consent (REB-642): everything in `./consent-shared` (cookie name, category\n * taxonomy, fail-closed parse/serialise), PLUS `cookiePolicyVersion()`, the\n * one function in this whole mechanism that needs a real dependency\n * (`node:crypto`, a Node builtin — not an npm package).\n *\n * This is the PUBLIC subpath (`@reblu/site-next/consent-server`) — a SITE's\n * server-side code (Route Handler, Server Component) imports from here.\n * `./consent-shared` re-exported below is intentionally the ONLY thing the\n * CLIENT entry (`./consent`) imports from; see that file's doc comment for\n * why `cookiePolicyVersion` and its `node:crypto` import must never be\n * reachable from a client component, even transitively.\n */\n\nexport {\n  CONSENT_CATEGORIES,\n  CONSENT_COOKIE_NAME,\n  DEFAULT_CONSENT_CATEGORIES,\n  parseConsentCookie,\n  serializeConsentCookie,\n  type ConsentCategory,\n  type ConsentCategoryState,\n  type ConsentCookiePayload,\n}\n\n/**\n * A content hash of the tenant's cookie policy, standing in for a stored\n * version string (REB-642 §7.2). A hash cannot drift the way a manually\n * bumped version number can: a tenant editing the policy text automatically\n * produces a new version, and `./consent`'s provider re-asks consent the\n * moment the version it holds no longer matches. `null` in, `null` out — a\n * tenant with no cookie policy stored has no version to pin.\n *\n * SERVER-ONLY: a SITE computes this once (from `SiteSettings.cookiePolicy`)\n * and passes the resulting string to `<ConsentProvider policyVersion>` as a\n * plain prop. Nothing under `@reblu/site-next/consent` calls this function or\n * imports `node:crypto` — enforced by `tests/consent-subpath-isolation.test.ts`.\n *\n * First 12 hex characters of SHA-256, matching the length asserted by this\n * function's own test and short enough to store cheaply alongside the\n * categories in the cookie.\n */\nexport function cookiePolicyVersion(policy: string | null | undefined): string | null {\n  if (!policy) return null\n  return createHash('sha256').update(policy, 'utf8').digest('hex').slice(0, 12)\n}\n","/**\n * `../consent-shared` — the truly isomorphic core of cookie consent (REB-642):\n * the cookie name, the category taxonomy, and fail-closed parse/serialise.\n * ZERO dependencies, including Node builtins — this is the one thing that\n * matters about this file's existence.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHY THIS IS A SEPARATE FILE FROM `./consent-server.ts`\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `./consent` (the client entry) needs `CONSENT_CATEGORIES` and friends, and\n * imports them straight from here. `./consent-server.ts` ALSO needs them, plus\n * `cookiePolicyVersion()`, which needs `node:crypto`. Those two facts collide\n * under this package's build rules: `tsup.config.ts` runs with\n * `treeshake: false` — REQUIRED to keep the `'use client'` prologue on the\n * `./consent` entry from being stripped (see the R4 note there) — and with\n * tree-shaking off, esbuild bundles an imported FILE WHOLESALE, not just the\n * specific binding a module asked for. So if `cookiePolicyVersion` (and its\n * `node:crypto` import) lived in the SAME file as `CONSENT_CATEGORIES`, every\n * client component that only wanted the category list would drag `node:crypto`\n * into the browser bundle too — dead weight at best, a broken build on a\n * bundler stricter than tsup about Node builtins in client code at worst. This\n * was caught live: `tests/consent-subpath-isolation.test.ts` asserts `./consent`\n * never references `crypto`, and failed until this split existed.\n *\n * `./consent-server.ts` re-exports everything here, so\n * `@reblu/site-next/consent-server` keeps serving the full public surface —\n * this split is purely internal.\n *\n * A cookie is attacker- and drift-controlled input: a visitor can edit it in\n * devtools, an older SDK version can leave a differently-shaped payload\n * behind, and a proxy or extension can mangle it in transit.\n * `parseConsentCookie` never coerces a doubtful value toward \"granted\" —\n * anything that is not EXACTLY the expected shape (an object, every known\n * category present and a strict boolean, `policyVersion` a string or `null`)\n * resolves to `null`, which `./consent`'s provider treats identically to \"no\n * cookie yet\": ask again, default every category denied. Silently granting a\n * truthy-but-malformed value is the one mistake this module is built to make\n * impossible.\n */\n\n/** The first-party cookie a visitor's consent choice is stored in. */\nexport const CONSENT_COOKIE_NAME = 'reblu_consent'\n\n/**\n * The fixed, non-tenant-editable category taxonomy (REB-642 §7.1): \"If each\n * SITE invents its own categories, no two clinics can be audited the same\n * way.\" `necessary` is deliberately NOT a member — it is not a choice, it has\n * no toggle, and it is never read from or written to the cookie.\n */\nexport const CONSENT_CATEGORIES = ['analytics', 'marketing', 'preferences'] as const\n\n/** One of the fixed consent categories. */\nexport type ConsentCategory = (typeof CONSENT_CATEGORIES)[number]\n\n/** A visitor's granted/denied state for every optional category. */\nexport type ConsentCategoryState = Record<ConsentCategory, boolean>\n\n/** The full payload stored in the consent cookie. */\nexport interface ConsentCookiePayload {\n  categories: ConsentCategoryState\n  /** The `cookiePolicyVersion()` in force when this choice was recorded, or `null`. */\n  policyVersion: string | null\n}\n\n/** Every optional category denied — the only safe default. */\nexport const DEFAULT_CONSENT_CATEGORIES: Readonly<ConsentCategoryState> = Object.freeze(\n  CONSENT_CATEGORIES.reduce(\n    (state, category) => ({ ...state, [category]: false }),\n    {} as ConsentCategoryState,\n  ),\n)\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * Reads and validates the categories object, requiring every known category to\n * be present as a STRICT boolean. Returns `null` on any deviation — a missing\n * category, an extra one being the only thing wrong is fine (ignored, never\n * leaked into the result), but a category that is present and not `true`/`false`\n * literally, or one that is simply absent, fails the whole parse closed. A\n * partial payload does NOT default the missing categories to `false`: that\n * would make \"a payload half-stripped by a proxy\" indistinguishable from \"a\n * visitor who explicitly denied the rest\", which is not a distinction this\n * function is in a position to make safely.\n */\nfunction parseCategories(value: unknown): ConsentCategoryState | null {\n  if (!isPlainObject(value)) return null\n\n  const result = {} as ConsentCategoryState\n  for (const category of CONSENT_CATEGORIES) {\n    const raw = value[category]\n    if (typeof raw !== 'boolean') return null\n    result[category] = raw\n  }\n  return result\n}\n\n/**\n * Parses a raw consent cookie value into a validated payload, or `null` if the\n * value is absent or does not match the expected shape exactly. See the module\n * doc for why this fails closed rather than coercing.\n */\nexport function parseConsentCookie(raw: string | null | undefined): ConsentCookiePayload | null {\n  if (!raw) return null\n\n  let json: unknown\n  try {\n    json = JSON.parse(raw)\n  } catch {\n    return null\n  }\n\n  if (!isPlainObject(json)) return null\n\n  const categories = parseCategories(json.categories)\n  if (!categories) return null\n\n  const policyVersion = json.policyVersion\n  if (policyVersion !== null && typeof policyVersion !== 'string') return null\n\n  return { categories, policyVersion }\n}\n\n/** Serialises a consent payload for storage in the cookie. */\nexport function serializeConsentCookie(payload: ConsentCookiePayload): string {\n  return JSON.stringify(payload)\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;;;AC0CpB,IAAM,sBAAsB;AAQ5B,IAAM,qBAAqB,CAAC,aAAa,aAAa,aAAa;AAgBnE,IAAM,6BAA6D,OAAO;AAAA,EAC/E,mBAAmB;AAAA,IACjB,CAAC,OAAO,cAAc,EAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,MAAM;AAAA,IACpD,CAAC;AAAA,EACH;AACF;AAEA,SAAS,cAAc,OAAkD;AACvE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAaA,SAAS,gBAAgB,OAA6C;AACpE,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO;AAElC,QAAM,SAAS,CAAC;AAChB,aAAW,YAAY,oBAAoB;AACzC,UAAM,MAAM,MAAM,QAAQ;AAC1B,QAAI,OAAO,QAAQ,UAAW,QAAO;AACrC,WAAO,QAAQ,IAAI;AAAA,EACrB;AACA,SAAO;AACT;AAOO,SAAS,mBAAmB,KAA6D;AAC9F,MAAI,CAAC,IAAK,QAAO;AAEjB,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,MAAI,CAAC,cAAc,IAAI,EAAG,QAAO;AAEjC,QAAM,aAAa,gBAAgB,KAAK,UAAU;AAClD,MAAI,CAAC,WAAY,QAAO;AAExB,QAAM,gBAAgB,KAAK;AAC3B,MAAI,kBAAkB,QAAQ,OAAO,kBAAkB,SAAU,QAAO;AAExE,SAAO,EAAE,YAAY,cAAc;AACrC;AAGO,SAAS,uBAAuB,SAAuC;AAC5E,SAAO,KAAK,UAAU,OAAO;AAC/B;;;ADzEO,SAAS,oBAAoB,QAAkD;AACpF,MAAI,CAAC,OAAQ,QAAO;AACpB,SAAO,WAAW,QAAQ,EAAE,OAAO,QAAQ,MAAM,EAAE,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AAC9E;","names":[]}

package/dist/consent-shared-DbdhEXW2.d.cts

@@ -0,0 +1,71 @@
+/**
+ * `../consent-shared` — the truly isomorphic core of cookie consent (REB-642):
+ * the cookie name, the category taxonomy, and fail-closed parse/serialise.
+ * ZERO dependencies, including Node builtins — this is the one thing that
+ * matters about this file's existence.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS IS A SEPARATE FILE FROM `./consent-server.ts`
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `./consent` (the client entry) needs `CONSENT_CATEGORIES` and friends, and
+ * imports them straight from here. `./consent-server.ts` ALSO needs them, plus
+ * `cookiePolicyVersion()`, which needs `node:crypto`. Those two facts collide
+ * under this package's build rules: `tsup.config.ts` runs with
+ * `treeshake: false` — REQUIRED to keep the `'use client'` prologue on the
+ * `./consent` entry from being stripped (see the R4 note there) — and with
+ * tree-shaking off, esbuild bundles an imported FILE WHOLESALE, not just the
+ * specific binding a module asked for. So if `cookiePolicyVersion` (and its
+ * `node:crypto` import) lived in the SAME file as `CONSENT_CATEGORIES`, every
+ * client component that only wanted the category list would drag `node:crypto`
+ * into the browser bundle too — dead weight at best, a broken build on a
+ * bundler stricter than tsup about Node builtins in client code at worst. This
+ * was caught live: `tests/consent-subpath-isolation.test.ts` asserts `./consent`
+ * never references `crypto`, and failed until this split existed.
+ *
+ * `./consent-server.ts` re-exports everything here, so
+ * `@reblu/site-next/consent-server` keeps serving the full public surface —
+ * this split is purely internal.
+ *
+ * A cookie is attacker- and drift-controlled input: a visitor can edit it in
+ * devtools, an older SDK version can leave a differently-shaped payload
+ * behind, and a proxy or extension can mangle it in transit.
+ * `parseConsentCookie` never coerces a doubtful value toward "granted" —
+ * anything that is not EXACTLY the expected shape (an object, every known
+ * category present and a strict boolean, `policyVersion` a string or `null`)
+ * resolves to `null`, which `./consent`'s provider treats identically to "no
+ * cookie yet": ask again, default every category denied. Silently granting a
+ * truthy-but-malformed value is the one mistake this module is built to make
+ * impossible.
+ */
+/** The first-party cookie a visitor's consent choice is stored in. */
+declare const CONSENT_COOKIE_NAME = "reblu_consent";
+/**
+ * The fixed, non-tenant-editable category taxonomy (REB-642 §7.1): "If each
+ * SITE invents its own categories, no two clinics can be audited the same
+ * way." `necessary` is deliberately NOT a member — it is not a choice, it has
+ * no toggle, and it is never read from or written to the cookie.
+ */
+declare const CONSENT_CATEGORIES: readonly ["analytics", "marketing", "preferences"];
+/** One of the fixed consent categories. */
+type ConsentCategory = (typeof CONSENT_CATEGORIES)[number];
+/** A visitor's granted/denied state for every optional category. */
+type ConsentCategoryState = Record<ConsentCategory, boolean>;
+/** The full payload stored in the consent cookie. */
+interface ConsentCookiePayload {
+    categories: ConsentCategoryState;
+    /** The `cookiePolicyVersion()` in force when this choice was recorded, or `null`. */
+    policyVersion: string | null;
+}
+/** Every optional category denied — the only safe default. */
+declare const DEFAULT_CONSENT_CATEGORIES: Readonly<ConsentCategoryState>;
+/**
+ * Parses a raw consent cookie value into a validated payload, or `null` if the
+ * value is absent or does not match the expected shape exactly. See the module
+ * doc for why this fails closed rather than coercing.
+ */
+declare function parseConsentCookie(raw: string | null | undefined): ConsentCookiePayload | null;
+/** Serialises a consent payload for storage in the cookie. */
+declare function serializeConsentCookie(payload: ConsentCookiePayload): string;
+
+export { CONSENT_CATEGORIES as C, DEFAULT_CONSENT_CATEGORIES as D, CONSENT_COOKIE_NAME as a, type ConsentCategory as b, type ConsentCategoryState as c, type ConsentCookiePayload as d, parseConsentCookie as p, serializeConsentCookie as s };

package/dist/consent-shared-DbdhEXW2.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `../consent-shared` — the truly isomorphic core of cookie consent (REB-642):
+ * the cookie name, the category taxonomy, and fail-closed parse/serialise.
+ * ZERO dependencies, including Node builtins — this is the one thing that
+ * matters about this file's existence.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS IS A SEPARATE FILE FROM `./consent-server.ts`
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `./consent` (the client entry) needs `CONSENT_CATEGORIES` and friends, and
+ * imports them straight from here. `./consent-server.ts` ALSO needs them, plus
+ * `cookiePolicyVersion()`, which needs `node:crypto`. Those two facts collide
+ * under this package's build rules: `tsup.config.ts` runs with
+ * `treeshake: false` — REQUIRED to keep the `'use client'` prologue on the
+ * `./consent` entry from being stripped (see the R4 note there) — and with
+ * tree-shaking off, esbuild bundles an imported FILE WHOLESALE, not just the
+ * specific binding a module asked for. So if `cookiePolicyVersion` (and its
+ * `node:crypto` import) lived in the SAME file as `CONSENT_CATEGORIES`, every
+ * client component that only wanted the category list would drag `node:crypto`
+ * into the browser bundle too — dead weight at best, a broken build on a
+ * bundler stricter than tsup about Node builtins in client code at worst. This
+ * was caught live: `tests/consent-subpath-isolation.test.ts` asserts `./consent`
+ * never references `crypto`, and failed until this split existed.
+ *
+ * `./consent-server.ts` re-exports everything here, so
+ * `@reblu/site-next/consent-server` keeps serving the full public surface —
+ * this split is purely internal.
+ *
+ * A cookie is attacker- and drift-controlled input: a visitor can edit it in
+ * devtools, an older SDK version can leave a differently-shaped payload
+ * behind, and a proxy or extension can mangle it in transit.
+ * `parseConsentCookie` never coerces a doubtful value toward "granted" —
+ * anything that is not EXACTLY the expected shape (an object, every known
+ * category present and a strict boolean, `policyVersion` a string or `null`)
+ * resolves to `null`, which `./consent`'s provider treats identically to "no
+ * cookie yet": ask again, default every category denied. Silently granting a
+ * truthy-but-malformed value is the one mistake this module is built to make
+ * impossible.
+ */
+/** The first-party cookie a visitor's consent choice is stored in. */
+declare const CONSENT_COOKIE_NAME = "reblu_consent";
+/**
+ * The fixed, non-tenant-editable category taxonomy (REB-642 §7.1): "If each
+ * SITE invents its own categories, no two clinics can be audited the same
+ * way." `necessary` is deliberately NOT a member — it is not a choice, it has
+ * no toggle, and it is never read from or written to the cookie.
+ */
+declare const CONSENT_CATEGORIES: readonly ["analytics", "marketing", "preferences"];
+/** One of the fixed consent categories. */
+type ConsentCategory = (typeof CONSENT_CATEGORIES)[number];
+/** A visitor's granted/denied state for every optional category. */
+type ConsentCategoryState = Record<ConsentCategory, boolean>;
+/** The full payload stored in the consent cookie. */
+interface ConsentCookiePayload {
+    categories: ConsentCategoryState;
+    /** The `cookiePolicyVersion()` in force when this choice was recorded, or `null`. */
+    policyVersion: string | null;
+}
+/** Every optional category denied — the only safe default. */
+declare const DEFAULT_CONSENT_CATEGORIES: Readonly<ConsentCategoryState>;
+/**
+ * Parses a raw consent cookie value into a validated payload, or `null` if the
+ * value is absent or does not match the expected shape exactly. See the module
+ * doc for why this fails closed rather than coercing.
+ */
+declare function parseConsentCookie(raw: string | null | undefined): ConsentCookiePayload | null;
+/** Serialises a consent payload for storage in the cookie. */
+declare function serializeConsentCookie(payload: ConsentCookiePayload): string;
+
+export { CONSENT_CATEGORIES as C, DEFAULT_CONSENT_CATEGORIES as D, CONSENT_COOKIE_NAME as a, type ConsentCategory as b, type ConsentCategoryState as c, type ConsentCookiePayload as d, parseConsentCookie as p, serializeConsentCookie as s };