@teamscala/service-boot 0.23.284

package/src/compose-page-title.test.ts

@@ -0,0 +1,88 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Pins composePageTitle: the single canonical title composer. The title is
+ * derived from website + page/entity name with meta_title as an explicit
+ * per-page OVERRIDE only, and it NEVER degrades to a bare org name.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { composePageTitle } from "./compose-page-title.ts";
+
+describe("composePageTitle", () => {
+	test("per-page meta_title override wins outright", () => {
+		expect(
+			composePageTitle({
+				pageMetaTitle: "Custom SEO Title",
+				websiteName: "creata Portal",
+				pageName: "Dashboard",
+			}),
+		).toBe("Custom SEO Title");
+	});
+
+	test("whitespace-only meta_title is not treated as an override", () => {
+		expect(
+			composePageTitle({
+				pageMetaTitle: "   ",
+				websiteName: "creata Portal",
+				pageName: "Dashboard",
+			}),
+		).toBe("creata Portal: Dashboard");
+	});
+
+	test("curated resource template beats the default derivation", () => {
+		expect(
+			composePageTitle({
+				templateTitle: "Sales Agent — GBG Indo",
+				websiteName: "scala GPT",
+				pageName: "chat",
+			}),
+		).toBe("Sales Agent — GBG Indo");
+	});
+
+	test("override beats template", () => {
+		expect(
+			composePageTitle({
+				pageMetaTitle: "Override",
+				templateTitle: "Template",
+				websiteName: "W",
+				pageName: "P",
+			}),
+		).toBe("Override");
+	});
+
+	test("default derivation: '<website>: <subject>' (portal spec)", () => {
+		expect(
+			composePageTitle({ websiteName: "creata Portal", pageName: "Dashboard" }),
+		).toBe("creata Portal: Dashboard");
+	});
+
+	test("entity title is the preferred subject over page name", () => {
+		expect(
+			composePageTitle({
+				websiteName: "scala Portal",
+				pageName: "view",
+				entityTitle: "Q3 Proposal",
+			}),
+		).toBe("scala Portal: Q3 Proposal");
+	});
+
+	test("app root with no subject renders the website name alone", () => {
+		expect(composePageTitle({ websiteName: "scala Roadmap" })).toBe(
+			"scala Roadmap",
+		);
+	});
+
+	test("subject without a website name renders the subject alone", () => {
+		expect(composePageTitle({ pageName: "Dashboard" })).toBe("Dashboard");
+	});
+
+	test("never degrades to a bare org name — no website + no subject is 'Untitled'", () => {
+		// The regression: a default titleTemplate of "{org.name}" produced
+		// "GBG Indo" with no context. The composer structurally cannot.
+		expect(composePageTitle({})).toBe("Untitled");
+		expect(composePageTitle({ websiteName: "" })).toBe("Untitled");
+	});
+});

package/src/compose-page-title.ts

@@ -0,0 +1,73 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The single canonical page-title composer. Every SSR page handler routes
+ * through this (portal/region-shell, public shell, single-page resource). A
+ * page title is DERIVED from data that already exists — the website name +
+ * the page/entity name — with `builda_pages.meta_title` as an explicit
+ * per-page OVERRIDE only, never the primary source.
+ *
+ * Mirrors the brand-is-org-owned-full-scheme precedent: a value that should
+ * be DERIVED was instead hand-set per row, and when unset it silently fell
+ * back to something wrong. For themes the wrong fallback was the generic
+ * light palette; for titles it was the bare org name — the `default`
+ * page_meta_template `titleTemplate: "{org.name}"` produced "GBG Indo" with
+ * no site or page context, and per-row `meta_title` carried stale product
+ * literals like "Dashboard | scala Hub". The fix is identical in shape:
+ * derive by default, override explicitly.
+ *
+ * Canonical format: `<website.name>: <subject>` (subject = entity title or
+ * page name), site-first so a browser tab reads the surface then the page.
+ * A resource surface (forms/quiz/gpt) may supply a curated `templateTitle`
+ * (e.g. "{agent.name} — {org.name}"); it wins over the default derivation
+ * but NOT over an explicit per-page override. The composer NEVER returns a
+ * bare org name — that is the regression this closes, and the
+ * `page-title-not-bare-org` guard backstops it at the template layer.
+ */
+
+export interface TitleContext {
+	/** Per-page override (builda_pages.meta_title). Wins outright when set. */
+	pageMetaTitle?: string | null;
+	/** Resolved resource-template string (forms/quiz/gpt). Curated per-surface shape. */
+	templateTitle?: string | null;
+	/** builda_websites.name — the surface, the primary site context. */
+	websiteName?: string | null;
+	/** builda_pages.name — the page (e.g. "Dashboard"). */
+	pageName?: string | null;
+	/** Resource entity title (proposal/form/quiz/agent name) — preferred subject. */
+	entityTitle?: string | null;
+}
+
+function trimToDefined(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+export function composePageTitle(ctx: TitleContext): string {
+	// 1. Explicit per-page override wins outright — the operator's escape
+	// hatch for a custom SEO/social title. It is NEVER the default source.
+	const override = trimToDefined(ctx.pageMetaTitle);
+	if (override) return override;
+
+	// 2. Curated resource template (forms/quiz/gpt). Already contextual
+	// (entity + org), so it beats the generic derivation for those surfaces.
+	const template = trimToDefined(ctx.templateTitle);
+	if (template) return template;
+
+	// 3. Default derivation: <website.name>: <subject>. Site-first so the
+	// stable surface precedes the varying page — how a tab is scanned.
+	const subject = trimToDefined(ctx.entityTitle) ?? trimToDefined(ctx.pageName);
+	const websiteName = trimToDefined(ctx.websiteName);
+	if (websiteName && subject) return `${websiteName}: ${subject}`;
+	if (websiteName) return websiteName;
+	if (subject) return subject;
+
+	// No website name and no subject: the page is misconfigured (a website
+	// with no resolvable name). "Untitled" signals that honestly. We NEVER
+	// fall back to a bare org name — that is the exact regression
+	// ("GBG Indo" with no context) this composer exists to prevent.
+	return "Untitled";
+}

package/src/content-gate/access.ts

@@ -0,0 +1,89 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The content-gate ACCESS endpoint mounter. One generic POST handler for every
+ * gate: a plain <form> posts {<recordIdField>, email}; on a match against the
+ * resource's authorized set it sets the signed access cookie and redirects back,
+ * so the page loader's gate then releases the content. No bespoke endpoint per
+ * type — each gate is one AccessConfig. Mounted BEFORE the auth gate so it is
+ * publicly reachable.
+ */
+
+import type { Hono } from "hono";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { AccessConfig } from "./config-types.ts";
+
+/** Same-origin path to redirect back to (the gated page the form was on). */
+function safeReturnPath(referer: string | undefined): string {
+	if (!referer) return "/";
+	try {
+		return new URL(referer).pathname || "/";
+	} catch {
+		return referer.startsWith("/") ? referer : "/";
+	}
+}
+
+export async function attachContentGateAccess(
+	app: Hono,
+	serviceSlug: string,
+	config: AccessConfig,
+): Promise<void> {
+	const log = getAppLogger();
+
+	app.post(config.path, async (c) => {
+		const back = safeReturnPath(c.req.header("referer"));
+		let resourceId = "";
+		let email = "";
+		let name = "";
+		try {
+			const form = await c.req.parseBody();
+			resourceId = String(form[config.recordIdField] ?? "").trim();
+			email = String(form.email ?? "").trim().toLowerCase();
+			// Optional captured display name (open-capture gates carry it in the
+			// token; allow-list gates ignore it via signToken).
+			name = String(form.name ?? "").trim();
+		} catch {
+			return c.redirect(back, 302);
+		}
+		if (!resourceId || !email) return c.redirect(back, 302);
+
+		let matched = false;
+		if (config.openCapture) {
+			// Open lead-capture gate (the public GPT): any non-empty email is a
+			// valid visitor — there is no allow-list to authorize against. We
+			// already required a non-empty email above, so this is a match.
+			matched = true;
+		} else {
+			try {
+				const authorized = await config.resolveAuthorizedEmails(resourceId);
+				matched = authorized.has(email);
+			} catch (err) {
+				log.error(
+					`[content-gate:${config.cookieName}] authorize failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+				return c.redirect(back, 302);
+			}
+		}
+
+		if (!matched) {
+			const sep = back.includes("?") ? "&" : "?";
+			return c.redirect(`${back}${sep}gate_error=1`, 302);
+		}
+
+		const token = config.signToken(resourceId, email, Date.now(), name || undefined);
+		if (token) {
+			const maxAge = Math.floor(config.ttlMs / 1000);
+			c.header(
+				"Set-Cookie",
+				`${config.cookieName}=${encodeURIComponent(token)}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,
+			);
+		}
+		return c.redirect(back, 302);
+	});
+
+	log.info(
+		`[scala-install:${serviceSlug}] content-gate access endpoint mounted: ${config.path}`,
+	);
+}

package/src/content-gate/config-types.ts

@@ -0,0 +1,108 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The config contracts that PROGRAM a content gate. Each gated content type
+ * (agreement, proposal, …) is one ContentGateConfig + one AccessConfig — no
+ * bespoke gate functions per type; the engine (gate.ts) and the access mounter
+ * (access.ts) are the single shared primitive driven by these.
+ */
+
+type Resolved = Record<string, unknown>;
+
+/** Drives the SSR-time gate (gate.ts / runContentGate). */
+export interface ContentGateConfig {
+	/** Cookie that carries this gate's access token (e.g. "ag_token"). */
+	cookieName: string;
+	/**
+	 * The gated resource id from the resolved graph, or "" when this gate does
+	 * not apply to the current page (the engine then no-ops). This is also how a
+	 * gate detects "is this my kind of page". Async to allow DB-backed resolution
+	 * (e.g. agreement gate resolving the UUID from the page→agreement association
+	 * when no pre-placed gate block exists).
+	 */
+	getResourceId(resolved: Resolved): string | Promise<string>;
+	/**
+	 * Verify the cookie's token for this resource → the verified identity
+	 * ({email, optional display name}), or null. Token-agnostic by design:
+	 * proposals use the shared content-gate token; agreements keep their existing
+	 * token (also minted by the signing ORPC), so the engine never assumes one
+	 * token format. Allow-list gates return just {email}; the GPT lead-capture
+	 * gate also returns the captured name (carried in its token).
+	 */
+	verifyToken(
+		token: string | undefined,
+		resourceId: string,
+		nowMs: number,
+	): { email: string; name?: string } | null;
+	/**
+	 * BAKED-IN unified auth. When a gate provides this resolver, the engine
+	 * AUTOMATICALLY releases a logged-in viewer whose session email is in the
+	 * authorized set — with no valid token and no per-gate code. This is the
+	 * platform default for EVERY gated resource: any application surface with
+	 * authentication gets "a signed-in, authorized viewer is never re-asked for
+	 * their email/OTP" for free, just by exposing its authorized-email set (the
+	 * same resolver its AccessConfig uses). Not called when the session is
+	 * anonymous. Omit only for open-capture gates that have no authorized set.
+	 */
+	resolveAuthorizedEmails?(resourceId: string): Promise<Set<string>>;
+	/**
+	 * OPTIONAL OVERRIDE of the baked-in session check above — for the rare gate
+	 * whose session→identity rule isn't simply "session email ∈ authorized set".
+	 * When present it wins; otherwise the engine uses `resolveAuthorizedEmails`.
+	 * Called only when no valid access token is present.
+	 */
+	sessionAuthorize?(
+		resolved: Resolved,
+		resourceId: string,
+	):
+		| { email: string; name?: string }
+		| null
+		| Promise<{ email: string; name?: string } | null>;
+	/** Reveal + seed the verified viewer's identity/session (token was valid). */
+	onAuthorized(
+		resolved: Resolved,
+		resourceId: string,
+		identity: { email: string; name?: string },
+	): void | Promise<void>;
+	/** Withhold content (strip/inject the gate) — token absent/invalid. Async-
+	 *  capable so a gate can load its display/behaviour settings from a registry
+	 *  row (DB-driven, not hardcoded); sync implementations remain valid. */
+	onUnauthorized(resolved: Resolved, resourceId: string): void | Promise<void>;
+}
+
+/** Drives the public access endpoint (access.ts / attachContentGateAccess). */
+export interface AccessConfig {
+	/** Route to mount, e.g. "/api/proposal-access". */
+	path: string;
+	/** Cookie to set on a match. */
+	cookieName: string;
+	/** Cookie lifetime in ms (Max-Age). */
+	ttlMs: number;
+	/** Form field carrying the resource id, e.g. "proposalId". */
+	recordIdField: string;
+	/**
+	 * Open lead-capture gate: ANY non-empty email is accepted (no allow-list).
+	 * For surfaces whose "gate" captures a visitor rather than authorizing one
+	 * against a fixed set (the public GPT). When true, `resolveAuthorizedEmails`
+	 * is not called. Default/omitted = allow-list mode (proposals, agreements).
+	 */
+	openCapture?: boolean;
+	/**
+	 * The authorized email set for a resource (lowercased), checked server-side.
+	 * Not called when `openCapture` is true.
+	 */
+	resolveAuthorizedEmails(resourceId: string): Promise<Set<string>>;
+	/**
+	 * Mint the access token for a matched email (token-agnostic per gate).
+	 * `name` is the optional captured display name (open-capture gates carry it
+	 * in the token; allow-list gates ignore it).
+	 */
+	signToken(
+		resourceId: string,
+		email: string,
+		nowMs: number,
+		name?: string,
+	): string | null;
+}

package/src/content-gate/gate.ts

@@ -0,0 +1,74 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The content-gate ENGINE. Runs in the page loader after the resource graph
+ * resolves, BEFORE SSR. Orchestration only — the per-type behaviour (which
+ * resource, who's authorized, what to seed, how to withhold) is supplied by a
+ * ContentGateConfig, so agreements/proposals/future gates are configs, not new
+ * functions. The single place that decides whether gated bytes reach the HTML.
+ */
+
+import type { ContentGateConfig } from "./config-types.ts";
+import { parseCookie } from "./parse-cookie.ts";
+
+export async function runContentGate(
+	resolved: Record<string, unknown>,
+	cookieHeader: string | null,
+	nowMs: number,
+	config: ContentGateConfig,
+): Promise<void> {
+	const resourceId = await config.getResourceId(resolved);
+	if (!resourceId) return; // gate does not apply to this page.
+
+	const token = parseCookie(cookieHeader, config.cookieName);
+	const identity = config.verifyToken(token, resourceId, nowMs);
+
+	if (identity) {
+		await config.onAuthorized(resolved, resourceId, identity);
+		return;
+	}
+
+	// No valid access token — BAKED-IN unified auth: release a logged-in viewer
+	// whose session email is authorized for this resource, with no per-gate
+	// email/OTP entry. This is platform-wide and automatic: every gate that
+	// exposes its authorized-email set (resolveAuthorizedEmails) gets it for free
+	// — a signed-in, authorized viewer is never re-challenged on ANY auth-bearing
+	// surface. A gate may override with a bespoke sessionAuthorize when its
+	// session→identity rule isn't simply "session email ∈ authorized set".
+	const sessionIdentity = await resolveSessionIdentity(
+		resolved,
+		resourceId,
+		config,
+	);
+	if (sessionIdentity) {
+		await config.onAuthorized(resolved, resourceId, sessionIdentity);
+		return;
+	}
+
+	await config.onUnauthorized(resolved, resourceId);
+}
+
+/**
+ * The signed-in viewer's authorized identity for this resource, or null. The
+ * default (used by every gate) is "session email ∈ the gate's authorized set";
+ * a gate may supply a custom sessionAuthorize to override. Anonymous sessions
+ * and gates with no authorized-email set return null (stay token-only).
+ */
+async function resolveSessionIdentity(
+	resolved: Record<string, unknown>,
+	resourceId: string,
+	config: ContentGateConfig,
+): Promise<{ email: string; name?: string } | null> {
+	if (config.sessionAuthorize) {
+		return config.sessionAuthorize(resolved, resourceId);
+	}
+	if (!config.resolveAuthorizedEmails) return null;
+	const sv = (resolved as { sessionVisitor?: { email: string; name?: string } })
+		.sessionVisitor;
+	if (!sv?.email) return null;
+	const email = sv.email.trim().toLowerCase();
+	const authorized = await config.resolveAuthorizedEmails(resourceId);
+	return authorized.has(email) ? { email, name: sv.name } : null;
+}

package/src/content-gate/parse-cookie.ts

@@ -0,0 +1,23 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Parse a single cookie value out of a raw Cookie header — shared by the
+ * content-gate engine and any gate config.
+ */
+
+export function parseCookie(
+	header: string | null,
+	name: string,
+): string | undefined {
+	if (!header) return undefined;
+	for (const part of header.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq < 0) continue;
+		if (part.slice(0, eq).trim() === name) {
+			return decodeURIComponent(part.slice(eq + 1).trim());
+		}
+	}
+	return undefined;
+}

package/src/content-gate/token.test.ts

@@ -0,0 +1,70 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Round-trip + binding tests for the content-gate access token. Covers the
+ * identity-carrying additions (signAccessToken `name` + verifyAccessTokenIdentity)
+ * used by the public GPT lead-capture gate, plus the gate/resource/expiry
+ * binding that every gate relies on to withhold content from a link holder.
+ */
+
+// A stable secret so secret() resolves deterministically in the test. Set BEFORE
+// importing the module under test (secret() reads it at call time, so order is
+// not strictly required, but this keeps the intent explicit).
+process.env.AUTH_SECRET = "test-secret-at-least-16-chars-long";
+
+import { describe, expect, test } from "bun:test";
+import {
+	signAccessToken,
+	verifyAccessToken,
+	verifyAccessTokenIdentity,
+} from "./token.ts";
+
+const NOW = 1_000_000_000_000;
+const TTL = 60_000;
+
+describe("content-gate token — identity", () => {
+	test("signs + verifies email AND name (GPT capture)", () => {
+		const t = signAccessToken("gpt_token", "gpt-1", "A@B.com", NOW, TTL, "Ann");
+		expect(t).toBeTruthy();
+		const id = verifyAccessTokenIdentity(t, "gpt_token", "gpt-1", NOW + 1);
+		expect(id).toEqual({ email: "a@b.com", name: "Ann" });
+	});
+
+	test("name omitted → identity has email, name undefined", () => {
+		const t = signAccessToken("gpt_token", "gpt-1", "a@b.com", NOW, TTL);
+		const id = verifyAccessTokenIdentity(t, "gpt_token", "gpt-1", NOW + 1);
+		expect(id).toEqual({ email: "a@b.com", name: undefined });
+	});
+
+	test("email-only verifyAccessToken still works (proposals/agreements)", () => {
+		const t = signAccessToken("prop_token", "p-1", "a@b.com", NOW, TTL);
+		expect(verifyAccessToken(t, "prop_token", "p-1", NOW + 1)).toBe("a@b.com");
+	});
+});
+
+describe("content-gate token — binding (withholds content)", () => {
+	const t = signAccessToken("gpt_token", "gpt-1", "a@b.com", NOW, TTL, "Ann");
+
+	test("wrong gate (cookieName) → null", () => {
+		expect(verifyAccessTokenIdentity(t, "prop_token", "gpt-1", NOW + 1)).toBeNull();
+	});
+
+	test("wrong resource → null", () => {
+		expect(verifyAccessTokenIdentity(t, "gpt_token", "gpt-2", NOW + 1)).toBeNull();
+	});
+
+	test("expired → null", () => {
+		expect(verifyAccessTokenIdentity(t, "gpt_token", "gpt-1", NOW + TTL + 1)).toBeNull();
+	});
+
+	test("tampered signature → null", () => {
+		const bad = `${t?.split(".")[0]}.deadbeef`;
+		expect(verifyAccessTokenIdentity(bad, "gpt_token", "gpt-1", NOW + 1)).toBeNull();
+	});
+
+	test("missing token → null", () => {
+		expect(verifyAccessTokenIdentity(undefined, "gpt_token", "gpt-1", NOW)).toBeNull();
+	});
+});

package/src/content-gate/token.ts

@@ -0,0 +1,148 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The single signed, short-lived access token for EVERY content gate (agreement,
+ * proposal, and any future gated content). A gate withholds page content
+ * server-side until the request carries a valid token for that resource; this is
+ * the only thing that releases the content into the SSR, so without it a gated
+ * page is never readable/scrapable by a link holder.
+ *
+ * HMAC-SHA256 (Bun-native) over {c:cookieName, r:resourceId, e:email, x:exp}.
+ * `cookieName` is bound INTO the payload so a token minted for one gate
+ * (e.g. ag_token) can never satisfy another gate's check (e.g. prop_token).
+ *
+ * Secret resolver, in preference order: AUTH_SECRET → ENCRYPTION_KEY →
+ * DATABASE_URL (first one ≥16 chars). A gate signs AND verifies inside one
+ * service, so it only needs a stable per-deployment secret; the fallback keeps a
+ * gate working on a service that was never given AUTH_SECRET (e.g. the former
+ * public-only proposals viewer) instead of failing closed and locking out every
+ * authorized viewer. Any service that has AUTH_SECRET transparently prefers it.
+ * Fail-closed: no usable secret yields null (no token, no access).
+ */
+
+function secret(): string | null {
+	for (const s of [
+		process.env.AUTH_SECRET,
+		process.env.ENCRYPTION_KEY,
+		process.env.DATABASE_URL,
+	]) {
+		if (s && s.length >= 16) return s;
+	}
+	return null;
+}
+
+function hmac(payloadB64: string, key: string): string {
+	return new Bun.CryptoHasher("sha256", key).update(payloadB64).digest("base64url");
+}
+
+/** Constant-time string compare (equal-length); avoids node:crypto. */
+function safeEqual(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+
+/** Mint a token proving `email` is authorized for `resourceId` under `cookieName`. */
+export function signAccessToken(
+	cookieName: string,
+	resourceId: string,
+	email: string,
+	nowMs: number,
+	ttlMs: number,
+	/**
+	 * Optional display name to carry in the token (the public GPT lead-capture
+	 * gate uses this so a returning visitor's name is known at SSR — first paint
+	 * renders the full identity, not just the email). Allow-list gates
+	 * (proposals/agreements) omit it.
+	 */
+	name?: string,
+): string | null {
+	const key = secret();
+	if (!key) return null;
+	const payload: { c: string; r: string; e: string; x: number; n?: string } = {
+		c: cookieName,
+		r: resourceId,
+		e: email.trim().toLowerCase(),
+		x: nowMs + ttlMs,
+	};
+	const trimmedName = name?.trim();
+	if (trimmedName) payload.n = trimmedName;
+	const payloadB64 = Buffer.from(JSON.stringify(payload)).toString("base64url");
+	return `${payloadB64}.${hmac(payloadB64, key)}`;
+}
+
+/**
+ * Validate a token for `cookieName` + `resourceId`. Returns the verified email
+ * on success, null otherwise (bad signature, wrong gate, wrong resource,
+ * expired, no secret).
+ */
+export function verifyAccessToken(
+	token: string | undefined | null,
+	cookieName: string,
+	resourceId: string,
+	nowMs: number,
+): string | null {
+	if (!token) return null;
+	const key = secret();
+	if (!key) return null;
+	const dot = token.indexOf(".");
+	if (dot <= 0) return null;
+	const payloadB64 = token.slice(0, dot);
+	const sig = token.slice(dot + 1);
+	if (!safeEqual(sig, hmac(payloadB64, key))) return null;
+	try {
+		const p = JSON.parse(Buffer.from(payloadB64, "base64url").toString()) as {
+			c?: string;
+			r?: string;
+			e?: string;
+			x?: number;
+		};
+		if (p.c !== cookieName) return null;
+		if (p.r !== resourceId) return null;
+		if (typeof p.x !== "number" || p.x < nowMs) return null;
+		return typeof p.e === "string" ? p.e : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Like `verifyAccessToken` but returns the full verified identity ({email, name})
+ * so a gate that carries a display name in the token (the public GPT lead-capture
+ * gate) can seed the visitor's name — not just the email — at SSR. Same
+ * signature/expiry/gate-binding checks; null on any failure.
+ */
+export function verifyAccessTokenIdentity(
+	token: string | undefined | null,
+	cookieName: string,
+	resourceId: string,
+	nowMs: number,
+): { email: string; name?: string } | null {
+	if (!token) return null;
+	const key = secret();
+	if (!key) return null;
+	const dot = token.indexOf(".");
+	if (dot <= 0) return null;
+	const payloadB64 = token.slice(0, dot);
+	const sig = token.slice(dot + 1);
+	if (!safeEqual(sig, hmac(payloadB64, key))) return null;
+	try {
+		const p = JSON.parse(Buffer.from(payloadB64, "base64url").toString()) as {
+			c?: string;
+			r?: string;
+			e?: string;
+			x?: number;
+			n?: string;
+		};
+		if (p.c !== cookieName) return null;
+		if (p.r !== resourceId) return null;
+		if (typeof p.x !== "number" || p.x < nowMs) return null;
+		if (typeof p.e !== "string") return null;
+		return { email: p.e, name: typeof p.n === "string" ? p.n : undefined };
+	} catch {
+		return null;
+	}
+}