fix(core): reject a hydration payload that parses but has the wrong shape (#656)

`getHydrationData` guards `typeof document`, returns null when the script is
absent, and wraps the parse in try/catch -- and then cast the result:

  return JSON.parse(content) as HydrationData;

So it caught a parse failure and handed back a parse success of any shape.
`initHydration` dereferences that through `applyHydratedHead(data.head)`, which
reads `head.title`:

  script content        getHydrationData    initHydration
  valid payload         the data            ok
  not json              null                ok
  (empty)               null                ok
  null                  null                ok
  {}                    {}                  throws on 'title'
  []                    []                  throws on 'title'
  {"head":null}         {"head":null}       throws on 'title'
  "str"                 "str"               throws on 'title'
  123                   123                 throws on 'title'

Malformed JSON was handled; well-formed JSON of the wrong shape was not, which
inverts what the guard looks like it is doing. `initHydration` runs at client
startup, so the exception aborts hydration for the whole page rather than
degrading to a client render.

This is not reachable through the framework's own rendering -- serializeHydrationData
always emits the right shape. It is reachable when something between the server
and the parse alters the script (an HTML minifier or transformer, a proxy that
rewrites the document, a stale script from a previous version), and through the
public exports, which a consumer can call against a document the framework did
not produce.

`applyHydratedHead` is likewise public, so it keeps its own guard for callers
that reach it directly, and now requires the title to be a string rather than
assigning whatever it was handed.

Closes #655

Author: chrismichaelps

packages/core/src/__tests__/ssr/hydration-payload-shape.test.ts

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Chris M. Perez
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+	applyHydratedHead,
+	getHydrationData,
+	initHydration,
+	serializeHydrationData,
+} from '../../ssr/hydration.js';
+import { HYDRATION_SCRIPT_ID } from '../../constants.js';
+
+/** Put `content` in the hydration script, as a transformed document might. */
+const putScript = (content: string): void => {
+	document.body.replaceChildren();
+	const script = document.createElement('script');
+	script.id = HYDRATION_SCRIPT_ID;
+	script.type = 'application/json';
+	script.textContent = content;
+	document.body.append(script);
+};
+
+const VALID = {
+	head: { title: 'T' },
+	state: { a: 1 },
+	url: '/',
+	timestamp: 0,
+};
+
+describe('hydration payloads that parse but have the wrong shape', () => {
+	afterEach(() => {
+		document.body.replaceChildren();
+		document.title = '';
+	});
+
+	// `getHydrationData` catches a parse failure and then cast the result, so
+	// these reached `applyHydratedHead` and threw on `head.title`.
+	const WRONG: [string, string][] = [
+		['an empty object', '{}'],
+		['an array', '[]'],
+		['a null head', '{"head":null}'],
+		['a string', '"str"'],
+		['a number', '123'],
+		['a head that is not an object', '{"head":5}'],
+	];
+
+	it.each(WRONG)('returns null for %s', (_label, content) => {
+		putScript(content);
+
+		expect(getHydrationData()).toBeNull();
+	});
+
+	it.each(WRONG)('does not throw from initHydration for %s', (_label, content) => {
+		putScript(content);
+
+		expect(() => initHydration()).not.toThrow();
+		expect(initHydration()).toBeNull();
+	});
+});
+
+describe('hydration payloads that were already handled', () => {
+	afterEach(() => {
+		document.body.replaceChildren();
+	});
+
+	it.each([
+		['malformed json', 'not json'],
+		['empty content', ''],
+		['a literal null', 'null'],
+	])('still returns null for %s', (_label, content) => {
+		putScript(content);
+
+		expect(getHydrationData()).toBeNull();
+		expect(() => initHydration()).not.toThrow();
+	});
+
+	it('returns null when there is no script at all', () => {
+		document.body.replaceChildren();
+
+		expect(getHydrationData()).toBeNull();
+		expect(initHydration()).toBeNull();
+	});
+});
+
+describe('a valid hydration payload', () => {
+	afterEach(() => {
+		document.body.replaceChildren();
+		document.title = '';
+	});
+
+	it('round-trips through the serializer', () => {
+		const html = serializeHydrationData(VALID);
+		const content = /type="application\/json">([\s\S]*)<\/script>/.exec(
+			html
+		)?.[1] as string;
+		putScript(content);
+
+		expect(getHydrationData()).toEqual(VALID);
+	});
+
+	it('is returned and applies its title', () => {
+		putScript(JSON.stringify(VALID));
+
+		expect(initHydration()).toEqual(VALID);
+		expect(document.title).toBe('T');
+	});
+
+	it('is accepted with an empty head and empty state', () => {
+		const payload = { head: {}, state: {}, url: '/', timestamp: 0 };
+		putScript(JSON.stringify(payload));
+
+		expect(getHydrationData()).toEqual(payload);
+		expect(() => initHydration()).not.toThrow();
+	});
+
+	it('tolerates a head carrying no title', () => {
+		expect(() => applyHydratedHead({})).not.toThrow();
+	});
+
+	it('tolerates being called directly with no head at all', () => {
+		// A public export, so a consumer reaches it without going through
+		// `getHydrationData` and its shape check.
+		expect(() => applyHydratedHead(null as never)).not.toThrow();
+		expect(() => applyHydratedHead(undefined as never)).not.toThrow();
+		expect(() => applyHydratedHead('str' as never)).not.toThrow();
+	});
+});

packages/core/src/ssr/hydration.ts

@@ -22,6 +22,7 @@
  * SOFTWARE.
  */
 
+import { Predicate } from 'effect';
 import type { HeadProps } from './types.js';
 import { HYDRATION_SCRIPT_ID } from '../constants.js';
 
@@ -48,6 +49,19 @@ export const serializeHydrationData = (data: HydrationData): string => {
 	return `<script id="${HYDRATION_SCRIPT_ID}" type="application/json">${escaped}</script>`;
 };
 
+/**
+ * Whether a parsed payload is actually hydration data.
+ *
+ * The parse result used to be cast straight to `HydrationData`, so the guard
+ * below caught malformed JSON and then handed back well-formed JSON of any
+ * shape: `{}`, `[]`, `"str"` and `123` all reached `applyHydratedHead`, which
+ * threw reading `head.title` and aborted hydration for the whole page.
+ *
+ * Only `head` is checked, because that is the field this module dereferences.
+ */
+const isHydrationData = (value: unknown): value is HydrationData =>
+	Predicate.isRecord(value) && Predicate.isRecord(value.head);
+
 /**
  * Retrieve hydration data from the DOM on the client side.
  * Returns null if the hydration script is not found or parsing fails.
@@ -65,7 +79,8 @@ export const getHydrationData = (): HydrationData | null => {
 	try {
 		const content = script.textContent;
 		if (!content) return null;
-		return JSON.parse(content) as HydrationData;
+		const parsed: unknown = JSON.parse(content);
+		return isHydrationData(parsed) ? parsed : null;
 	} catch {
 		return null;
 	}
@@ -154,9 +169,13 @@ const sameContent = (
  */
 export const applyHydratedHead = (head: HeadProps): void => {
 	if (typeof document === 'undefined') return;
+	// A public export, so it is reachable without `getHydrationData` and its
+	// shape check; `head.title` threw when it was handed null or a primitive.
+	if (!Predicate.isRecord(head)) return;
 
-	if (head.title && document.title !== head.title) {
-		document.title = head.title;
+	const title = head.title;
+	if (Predicate.isString(title) && title !== '' && document.title !== title) {
+		document.title = title;
 	}
 };