@teamscala/service-boot 0.23.284

package/src/agreement-gate.ts

@@ -0,0 +1,887 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The AGREEMENT content gate, expressed as config for the content-gate primitive
+ * (content-gate/). The agreement-specific bits: which resource (the placed
+ * SignIn gate block's id), who's authorized (the signer roster), what to seed
+ * (the verified signer's signing session into every SignatureField), and how to
+ * withhold (strip the gate region to gate-only + strip {{agreement.*}} chrome).
+ * The engine handles cookie/token/verify/orchestration.
+ *
+ * The signing logic (buildSigningSession, seedSigningBlocks, roster expansion,
+ * placeholder strip) is preserved verbatim from the former gate-agreement-
+ * content.ts — only the cookie/token orchestration moved into the shared engine.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { queryRows } from "@teamscala/db/query-rows";
+import { createCache } from "@teamscala/cache/create-cache";
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+import {
+	signAgreementAccessToken,
+	verifyAgreementAccessToken,
+} from "@teamscala/document-signing/agreement-access-token";
+import {
+	type PublicAgreementParty,
+	parseAgreementParties,
+	toPublicParties,
+} from "@teamscala/document-signing/agreement-parties";
+import { expandRosterTemplates } from "./expand-roster.ts";
+import { injectResourceChatLauncher } from "./resource-chat-inject.ts";
+import { agTtlMs } from "./gate-ttls.ts";
+import {
+	buildCertificateData,
+	type CertificateData,
+} from "./fn-routers/public-agreement-router.ts";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+const AG_COOKIE = "ag_token";
+
+/**
+ * Agreement gate display + behaviour, DB-driven (config/content-gate-agreement),
+ * never hardcoded — mirrors proposal-gate's loadProposalGateSettings. requireOtp
+ * is the per-gate OTP switch (agreements default ON: a signer verifies identity
+ * before signing). title is the fallback used when no agreement name resolves. A
+ * missing/invalid row falls back to these defaults so the gate UI ALWAYS renders.
+ */
+interface AgreementGateSettings {
+	title: string;
+	subtitle: string;
+	submitLabel: string;
+	requireOtp: boolean;
+}
+
+const AGREEMENT_GATE_DEFAULTS: AgreementGateSettings = {
+	title: "Private document",
+	subtitle: "Verify your email to view and sign this document.",
+	submitLabel: "Access document",
+	requireOtp: true,
+};
+
+const AgreementGateSettingsSchema = v.object({
+	title: v.optional(v.string(), AGREEMENT_GATE_DEFAULTS.title),
+	subtitle: v.optional(v.string(), AGREEMENT_GATE_DEFAULTS.subtitle),
+	submitLabel: v.optional(v.string(), AGREEMENT_GATE_DEFAULTS.submitLabel),
+	requireOtp: v.optional(v.boolean(), AGREEMENT_GATE_DEFAULTS.requireOtp),
+});
+
+/** Gate copy/behaviour, or null when the config row is absent/broken. Null is
+ *  the absent signal — callers default explicitly so a missing row neither 500s
+ *  the page nor masks as a populated value (protective-layers-fail-explicitly). */
+async function loadAgreementGateSettings(): Promise<AgreementGateSettings | null> {
+	try {
+		return await loadRegistryConfig(
+			"config",
+			"content-gate-agreement",
+			AgreementGateSettingsSchema,
+		);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Cache for the page→agreement association (new-flow pages that have no
+ * pre-placed gate block). The association changes rarely (only when a new
+ * agreement is created or a page is rebound), so a 30s TTL avoids a DB query
+ * per request while staying fresh enough for just-created agreements to appear.
+ * Negative results are cached too (id="") so non-agreement pages never re-query.
+ */
+const pageAgreementCache = createCache<{ id: string; name: string }>(
+	"agreement-gate:page-association",
+	{ maxSize: 256, ttlMs: 30_000 },
+);
+
+/**
+ * Cache for the owning org's member directory (org id → lowercased email → name),
+ * used to grant VIEW-ONLY access to an agreement to any member of the org that
+ * owns it (signing stays roster-bound). Membership changes on human timescales,
+ * so a 30s TTL keeps the per-request authorize cheap (hot-path-resolutions-are-cached).
+ */
+const orgMemberCache = createCache<Map<string, string>>(
+	"agreement-gate:org-members",
+	{ maxSize: 256, ttlMs: 30_000 },
+);
+
+/**
+ * The owning org's member directory: lowercased email → display name, for every
+ * member of `organisationId`. Empty when the org is unknown or has no members.
+ *
+ * Resolved via a parameterized raw join over better_auth_member + "user" rather
+ * than `getPrisma().member`: `member` is a shared @@map'd Prisma model, and each
+ * service's per-service client is generated by live DB introspection from only
+ * the tables its service_schema declares — so `getPrisma().member` is UNDEFINED
+ * on a service (scala-sign, scala-proposals) that doesn't list better_auth_member.
+ * A read-only raw query needs no model declaration and works on every client,
+ * which is what makes org-member VIEW access actually resolve (the typed access
+ * silently crashed → caught → empty directory → org members wrongly challenged).
+ */
+async function resolveOrgMemberDirectory(
+	organisationId: string | null,
+): Promise<Map<string, string>> {
+	if (!organisationId) return new Map();
+	const cached = orgMemberCache.get(organisationId);
+	if (cached !== undefined) return cached;
+	const directory = new Map<string, string>();
+	try {
+		const { getPrisma } = await import("@teamscala/db/prisma-registry");
+		const rows = await queryRows`
+			SELECT u.email AS email, u.name AS name
+			FROM better_auth_member m
+			JOIN "user" u ON u.id = m.user_id
+			WHERE m.organization_id = ${organisationId}
+		` as 
+			Array<{ email: string | null; name: string | null }>
+		;
+		for (const r of rows) {
+			const email = typeof r.email === "string" ? r.email.trim().toLowerCase() : "";
+			if (email) directory.set(email, String(r.name ?? r.email));
+		}
+		orgMemberCache.set(organisationId, directory);
+		return directory;
+	} catch (err) {
+		getAppLogger().error(
+			`[agreement-gate] org-member resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return directory;
+	}
+}
+
+/**
+ * The combined member directory for EVERY org an agreement's parties represent
+ * (each party's `organisationId`) plus the agreement's owning org. Any of these
+ * members may VIEW the agreement; signing stays restricted to the designated
+ * signer (the party email). Usually 1 org (one of our orgs + an external party),
+ * so the loop is over a 1-2 element set, each entry cached.
+ */
+async function resolveAgreementViewerDirectory(
+	orgIds: Iterable<string | null | undefined>,
+): Promise<Map<string, string>> {
+	const out = new Map<string, string>();
+	const unique = new Set(
+		[...orgIds].filter((id): id is string => typeof id === "string" && id.length > 0),
+	);
+	for (const orgId of unique) {
+		const dir = await resolveOrgMemberDirectory(orgId);
+		for (const [email, name] of dir) if (!out.has(email)) out.set(email, name);
+	}
+	return out;
+}
+
+interface ContentBlock {
+	type?: string;
+	props?: Record<string, unknown>;
+}
+
+interface SigningSession {
+	authedRole: string;
+	authedName: string;
+	authedEmail: string;
+	agreementUuid: string;
+	parties: PublicAgreementParty[];
+	agreementName: string;
+	agreementRef: string;
+	completedAt: string | null;
+	orgName: string | null;
+	organisationId: string | null;
+	/** Certificate of Completion data (built for a party signer via
+	 *  buildCertificateData); null for view-only recipients. Seeded into the
+	 *  SignatureField so the certificate renders inline, immediately. */
+	certificate: CertificateData | null;
+}
+
+/** Every resolved region's content[] array, paired with its puck_data holder. */
+function* regionContents(
+	resolved: Record<string, unknown>,
+): Generator<{ pd: { content?: unknown[] }; content: ContentBlock[] }> {
+	for (const value of Object.values(resolved)) {
+		const pd = (value as { puck_data?: { content?: unknown[] } } | null)?.puck_data;
+		const content = pd?.content;
+		if (pd && Array.isArray(content)) {
+			yield { pd, content: content as ContentBlock[] };
+		}
+	}
+}
+
+/**
+ * Locate the agreement gate block(s) across regions. A gate is the SignIn block
+ * in `gate` mode whose field is NOT "proposalId" (that field marks a proposal
+ * gate); the agreement id lives in `gateContextValue`.
+ */
+function findAgreementGate(resolved: Record<string, unknown>): {
+	agreementUuid: string;
+	gateRegions: { pd: { content?: unknown[] }; content: ContentBlock[]; gateIdx: number }[];
+} {
+	let agreementUuid = "";
+	const gateRegions: {
+		pd: { content?: unknown[] };
+		content: ContentBlock[];
+		gateIdx: number;
+	}[] = [];
+	for (const { pd, content } of regionContents(resolved)) {
+		const gateIdx = content.findIndex(
+			(b) =>
+				b?.type === "SignIn" &&
+				b?.props?.mode === "gate" &&
+				b?.props?.gateContextField !== "proposalId",
+		);
+		if (gateIdx < 0) continue;
+		const uuid = content[gateIdx].props?.gateContextValue;
+		if (typeof uuid === "string" && uuid) agreementUuid = uuid;
+		gateRegions.push({ pd, content, gateIdx });
+	}
+	return { agreementUuid, gateRegions };
+}
+
+/** Build the verified signer's session from the agreement's parties roster. */
+async function buildSigningSession(
+	agreementUuid: string,
+	verifiedEmail: string,
+): Promise<SigningSession | null> {
+	const log = getAppLogger();
+	const lower = verifiedEmail.trim().toLowerCase();
+	try {
+		const { getPrisma } = await import("@teamscala/db/prisma-registry");
+		const agreement = await getPrisma().agreements.findFirst({
+			where: { id: agreementUuid },
+			select: {
+				name: true,
+				signer_name: true,
+				signed_at: true,
+				signature_data: true,
+				organisation_id: true,
+			},
+		});
+		if (!agreement) return null;
+
+		const meta = {
+			agreementName: String(agreement.name ?? "Agreement"),
+			agreementRef: agreementUuid.split("-")[0] ?? agreementUuid,
+			completedAt: agreement.signed_at
+				? new Date(agreement.signed_at as unknown as string).toISOString()
+				: null,
+			orgName: null as string | null,
+			organisationId:
+				typeof agreement.organisation_id === "string"
+					? agreement.organisation_id
+					: null,
+		};
+
+		const parties = parseAgreementParties(agreement.signature_data);
+		if (parties) {
+			const me = parties.find((p) => p.email.trim().toLowerCase() === lower);
+			if (me) {
+				// Only a "signer" recipient gets a signing session (authedRole = its
+				// party key, which the SignatureField matches to render its sign slot).
+				// A named "viewer"/"cc" recipient — like an org member below — is
+				// view-only: authedRole "viewer" matches no party key, so no slot.
+				// Certificate data is built only for a party signer (same email-must-
+				// be-a-party gate as publicAgreement.certificate) and seeded for inline
+				// render; a view-only recipient gets null (and the cell never shows it).
+				const isSigner = me.recipientRole === "signer";
+				const cert = isSigner
+					? await buildCertificateData(agreementUuid, verifiedEmail)
+					: null;
+				return {
+					authedRole: isSigner ? me.key : "viewer",
+					authedName: me.name,
+					authedEmail: verifiedEmail,
+					agreementUuid,
+					parties: toPublicParties(parties),
+					certificate: cert && cert.ok ? cert : null,
+					...meta,
+				};
+			}
+			// Not a roster party — admit any member of an org this agreement's parties
+			// represent (each party's organisationId ∪ the owning org) as a VIEW-ONLY
+			// viewer. authedRole "viewer" matches no party key, so every SignatureField
+			// renders read-only "Awaiting <name>" — no signature slot. Only the
+			// designated signer (the party email matched above) ever signs.
+			const directory = await resolveAgreementViewerDirectory([
+				meta.organisationId,
+				...parties.map((p) => p.organisationId),
+			]);
+			const viewerName = directory.get(lower);
+			if (viewerName !== undefined) {
+				return {
+					authedRole: "viewer",
+					authedName: viewerName,
+					authedEmail: verifiedEmail,
+					agreementUuid,
+					parties: toPublicParties(parties),
+					certificate: null,
+					...meta,
+				};
+			}
+			return null;
+		}
+
+		const name = String(agreement.signer_name ?? "");
+		const cert = await buildCertificateData(agreementUuid, verifiedEmail);
+		return {
+			authedRole: "signer",
+			authedName: name,
+			authedEmail: verifiedEmail,
+			agreementUuid,
+			parties: [
+			{
+				key: "signer",
+				role: name || "Signer",
+				recipientRole: "signer",
+				name,
+					title: null,
+					company: null,
+					signedAt: null,
+					signature: null,
+				},
+			],
+			certificate: cert && cert.ok ? cert : null,
+			...meta,
+		};
+	} catch (err) {
+		log.error(
+			`[agreement-gate] session build failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return null;
+	}
+}
+
+const SIGNING_BLOCK_TYPES = new Set(["SignatureField"]);
+
+/** Seed the verified session into every signing block across all regions. */
+function seedSigningBlocks(
+	resolved: Record<string, unknown>,
+	session: SigningSession,
+): void {
+	const seed = {
+		authed: true,
+		authedRole: session.authedRole,
+		authedName: session.authedName,
+		authedEmail: session.authedEmail,
+		agreementUuid: session.agreementUuid,
+		parties: session.parties,
+		agreementName: session.agreementName,
+		agreementRef: session.agreementRef,
+		completedAt: session.completedAt,
+		orgName: session.orgName,
+		certificate: session.certificate,
+	};
+	const seedBlock = (block: ContentBlock): void => {
+		if (block?.type && SIGNING_BLOCK_TYPES.has(block.type)) {
+			block.props = { ...(block.props ?? {}), ...seed };
+		}
+		const props = block?.props;
+		if (!props) return;
+		for (const propVal of Object.values(props)) {
+			if (!Array.isArray(propVal)) continue;
+			for (const child of propVal) {
+				if (child && typeof child === "object") seedBlock(child as ContentBlock);
+			}
+		}
+	};
+	for (const { content } of regionContents(resolved)) {
+		for (const block of content) seedBlock(block);
+	}
+}
+
+/** True if any of the block's OWN string props carries an {{agreement.*}} token. */
+function blockHasAgreementPlaceholder(block: ContentBlock): boolean {
+	const props = block.props;
+	if (!props) return false;
+	for (const propVal of Object.values(props)) {
+		if (typeof propVal === "string" && /\{\{\s*agreement\./.test(propVal)) return true;
+	}
+	return false;
+}
+
+/** Drop blocks whose own text still holds an {{agreement.*}} token, recursively. */
+function stripAgreementPlaceholderBlocks(content: ContentBlock[]): ContentBlock[] {
+	const out: ContentBlock[] = [];
+	for (const block of content) {
+		if (blockHasAgreementPlaceholder(block)) continue;
+		const props = block.props;
+		if (props) {
+			for (const [k, propVal] of Object.entries(props)) {
+				if (Array.isArray(propVal)) {
+					props[k] = stripAgreementPlaceholderBlocks(propVal as ContentBlock[]);
+				}
+			}
+		}
+		out.push(block);
+	}
+	return out;
+}
+
+/** The org's display name (for the footer audit line), from the resolved brand. */
+function brandOrgName(resolved: Record<string, unknown>): string | null {
+	const brand = resolved.brand as
+		| { companyFriendlyName?: unknown; companyName?: unknown }
+		| undefined;
+	const name = brand?.companyFriendlyName ?? brand?.companyName;
+	return typeof name === "string" && name ? name : null;
+}
+
+// ─── New-flow signing-shell injection (no pre-placed gate required) ──────────
+// When a Puck page has no pre-placed SignIn gate block, the machinery resolves
+// the agreement from the page→agreement association and injects the full
+// signing shell (gate when unauthed; title + execution + signature panel +
+// print + audit when authed). The Puck page holds ONLY document content.
+
+/** Agreement metadata stashed on resolved during getResourceId. */
+const AGREEMENT_META_KEY = "_agreementMeta";
+
+function stashAgreementMeta(
+	resolved: Record<string, unknown>,
+	id: string,
+	name: string,
+): void {
+	resolved[AGREEMENT_META_KEY] = { id, name };
+}
+
+/**
+ * The body content array for the agreement. The public shell composes the body
+ * region FROM resolved.page (register-registry-page-route.ts Branch 2:
+ * `bodyPuck = extractPuckData(resolved.page)`, returned un-cloned), so this IS
+ * the live array whose mutation reaches the SSR render. Header/footer are
+ * separate region sources (resolved.header / resolved.footer) — never the body.
+ *
+ * A prior version scored every region by top-level non-shell block count and
+ * picked the highest. That misroutes when the body wraps its clauses inside a
+ * Container (body's top-level count is ~2 while its nested clause count is ~40):
+ * a /header region with more top-level blocks out-scores the body, so
+ * onUnauthorized cleared the HEADER and injected the gate there, leaving the
+ * entire agreement body visible past the gate. The body is the resource page —
+ * identified, not heuristically guessed.
+ */
+function getBodyContentArray(
+	resolved: Record<string, unknown>,
+): ContentBlock[] | null {
+	const pd = (
+		resolved.page as { puck_data?: { content?: unknown[] } } | undefined
+	)?.puck_data;
+	if (!pd || !Array.isArray(pd.content)) return null;
+	return pd.content as ContentBlock[];
+}
+
+/** Construct the SignIn gate block for injection. */
+function buildGateBlock(
+	agreementUuid: string,
+	title: string,
+	settings: AgreementGateSettings,
+): ContentBlock {
+	return {
+		type: "SignIn",
+		props: {
+			id: `agreement-gate-${agreementUuid}`,
+			mode: "gate",
+			title: title || settings.title,
+			subtitle: settings.subtitle,
+			gateAction: "/api/agreement-access",
+			showBackToHome: true,
+			gateContextField: "agreementId",
+			gateContextValue: agreementUuid,
+			gateSubmitLabel: settings.submitLabel,
+			// Require OTP is DB-driven (config/content-gate-agreement.requireOtp).
+			// String "true"/"false" (not boolean) to match the select-field enum the
+			// render validates against — a boolean is stripped before reaching the
+			// component (the same coercion that bit the pre-placed gate block).
+			gateRequireOtp: settings.requireOtp ? "true" : "false",
+		},
+	};
+}
+
+/**
+ * Construct the signing shell blocks that wrap the body content when authed:
+ * [0] title ({{agreement.name}}), [1] execution clause, [2] signature panel
+ * (grid Container holding a per-party SignatureField template), [3] print
+ * button, [4] audit footer. The title is unshift'd before body; the rest are
+ * pushed after. expandRosterTemplates expands the SignatureField per party;
+ * seedSigningBlocks seeds each cell with the verified session.
+ */
+const AGREEMENT_SIGNING_SHELL_DEFAULT: ContentBlock[] = [
+		{
+			type: "Text",
+			props: {
+				id: "agreement-title",
+				text: "{{agreement.name}}",
+				size: "xl",
+				weight: "bold",
+				align: "left",
+				element: "h1",
+			},
+		},
+		{
+			type: "Text",
+			props: {
+				id: "agreement-execution",
+				text: "IN WITNESS WHEREOF, the parties have executed this Agreement as of the date(s) of signature below.",
+				size: "sm",
+				weight: "normal",
+				align: "left",
+				element: "p",
+			},
+		},
+		{
+			type: "Container",
+			props: {
+				id: "agreement-signature-panel",
+				layout: "grid",
+				columns: 2,
+				direction: "column",
+				gap: "md",
+				padding: "md",
+				mobileBehavior: "stack",
+				content: [
+					{
+						type: "SignatureField",
+						props: {
+							id: "agreement-signature-field",
+							label: "",
+						},
+					},
+				],
+			},
+		},
+		// Print button — preset:"action-primary" is the single styling knob: it
+		// resolves (button-presets config) to variant:primary → brand-coloured
+		// background. NO explicit `variant` prop: button-styles.ts does
+		// `variant ?? preset.variant`, so any explicit variant overrides the preset
+		// (a stray variant:"secondary" — not a real variant — fell back to a
+		// transparent ghost; that was the bare-text bug). icon:"lucide:printer"
+		// renders the printer glyph (baseStyle provides the icon↔label gap).
+		{
+			type: "Button",
+			props: {
+				id: "agreement-print",
+				label: "Print",
+				icon: "lucide:printer",
+				actionType: "print",
+				preset: "action-primary",
+				size: "default",
+				borderColor: "var(--border-color-default)",
+				borderWidth: "var(--border-width-default)",
+				borderRadius: "var(--radius-md)",
+				fullWidth: false,
+				pushRight: false,
+				href: "",
+				target: "_self",
+			},
+		},
+		{
+			type: "Text",
+			props: {
+				id: "agreement-audit",
+				text: "Secured electronic signature · {{agreement.org}}",
+				size: "xs",
+				align: "center",
+				element: "p",
+			},
+		},
+];
+
+const SigningShellSchema = v.object({ blocks: v.array(v.unknown()) });
+
+/**
+ * The signing-shell block tree, DB-driven (config/agreement-signing-shell) so the
+ * clauses, labels, and structure are editable without a deploy. Deep-cloned per
+ * call because injection (expandRosterTemplates/seedSigningBlocks) mutates the
+ * tree. Falls back to AGREEMENT_SIGNING_SHELL_DEFAULT so signing ALWAYS renders.
+ */
+async function buildSigningShellBlocks(): Promise<ContentBlock[]> {
+	try {
+		const cfg = await loadRegistryConfig(
+			"config",
+			"agreement-signing-shell",
+			SigningShellSchema,
+		);
+		const blocks = cfg?.blocks as ContentBlock[] | undefined;
+		if (Array.isArray(blocks) && blocks.length > 0) {
+			return structuredClone(blocks);
+		}
+	} catch {
+		// fall through to the default so the signing shell ALWAYS renders
+	}
+	return structuredClone(AGREEMENT_SIGNING_SHELL_DEFAULT);
+}
+
+/** True if the page has a pre-placed SignIn gate block (old-flow page). */
+function hasPrePlacedGate(resolved: Record<string, unknown>): boolean {
+	return findAgreementGate(resolved).agreementUuid !== "";
+}
+
+export const agreementGateConfig: ContentGateConfig = {
+	cookieName: AG_COOKIE,
+	async getResourceId(resolved) {
+		// Old-flow pages: a pre-placed SignIn gate block carries the UUID.
+		const gate = findAgreementGate(resolved);
+		if (gate.agreementUuid) {
+			const gateRegion = gate.gateRegions[0];
+			const gateBlock = gateRegion?.content[gateRegion.gateIdx];
+			const name =
+				(gateBlock?.props?.title as string | undefined) ?? "Agreement";
+			stashAgreementMeta(resolved, gate.agreementUuid, name);
+			return gate.agreementUuid;
+		}
+
+		// New-flow pages: resolve UUID from the page→agreement association.
+		const pageId = (resolved.page as { id?: string } | undefined)?.id;
+		if (!pageId) return "";
+
+		const cached = pageAgreementCache.get(pageId);
+		if (cached !== undefined) {
+			if (cached.id) stashAgreementMeta(resolved, cached.id, cached.name);
+			return cached.id;
+		}
+
+		try {
+			const { getPrisma } = await import("@teamscala/db/prisma-registry");
+			const agreement = await getPrisma().agreements.findFirst({
+				where: { page_id: pageId },
+				select: { id: true, name: true },
+			});
+			if (agreement) {
+				pageAgreementCache.set(pageId, {
+					id: agreement.id,
+					name: agreement.name,
+				});
+				stashAgreementMeta(resolved, agreement.id, agreement.name);
+				return agreement.id;
+			}
+			// Cache negative so non-agreement pages never re-query.
+			pageAgreementCache.set(pageId, { id: "", name: "" });
+			return "";
+		} catch (err) {
+			getAppLogger().error(
+				`[agreement-gate] page association lookup failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return "";
+		}
+	},
+	// Baked-in unified auth (engine default): a logged-in viewer whose session
+	// email is in the authorized set (signer roster ∪ owning/party-org members)
+	// is released with no per-gate OTP — session verify is local, works on
+	// Railway. Just exposing the resolver opts into the platform-wide behaviour.
+	resolveAuthorizedEmails: resolveAgreementAuthorizedEmails,
+	verifyToken(token, resourceId, nowMs) {
+		const email = verifyAgreementAccessToken(token, resourceId, nowMs);
+		return email ? { email } : null;
+	},
+	async onAuthorized(resolved, agreementUuid, { email }) {
+		const session = await buildSigningSession(agreementUuid, email);
+		if (!session) {
+			// Session build failed — withhold content as if unauthorized.
+			if (!hasPrePlacedGate(resolved)) {
+				const content = getBodyContentArray(resolved);
+				if (content) {
+					const settings =
+					(await loadAgreementGateSettings()) ?? AGREEMENT_GATE_DEFAULTS;
+					content.length = 0;
+					content.push(
+						buildGateBlock(agreementUuid, "Private document", settings),
+					);
+				}
+			}
+			return;
+		}
+
+		session.orgName = brandOrgName(resolved);
+		const signedCount = session.parties.filter((p) => p.signedAt).length;
+		const completedDate = session.completedAt
+			? new Date(session.completedAt).toLocaleDateString("en-AU", {
+					day: "numeric",
+					month: "long",
+					year: "numeric",
+				})
+			: "";
+
+		// New-flow pages: inject the signing shell BEFORE roster expansion so
+		// the SignatureField template is expanded per party. Old-flow pages
+		// already have pre-placed blocks — skip injection.
+		if (!hasPrePlacedGate(resolved)) {
+			const content = getBodyContentArray(resolved);
+			if (content) {
+				const shell = await buildSigningShellBlocks();
+				const bodyBlocks = [...content];
+				content.length = 0;
+				content.push(shell[0], ...bodyBlocks, ...shell.slice(1));
+			}
+		}
+
+		// Expand roster templates + bind agreement-meta placeholders (both flows).
+		expandRosterTemplates(resolved, session.parties, {
+			name: session.agreementName,
+			ref: session.agreementRef,
+			org: session.orgName ?? "",
+			signer: session.authedName,
+			// Role-aware verb for the header status line. authedRole is a party key
+			// for a designated signer, or the literal "viewer" for a view-only
+			// recipient (an org member who isn't on the signer roster). So the
+			// header reads "Viewing as <name>" for a viewer, "Signing as <name>"
+			// for a signer — never implying a viewer can sign.
+			signerVerb: session.authedRole === "viewer" ? "Viewing" : "Signing",
+			signedCount: String(signedCount),
+			total: String(session.parties.length),
+			completedDate,
+		});
+		// Seed the verified session into every SignatureField (both flows).
+		seedSigningBlocks(resolved, session);
+
+		// Floating "Ask about this agreement" GPT bubble — the generic
+		// ResourceChatLauncher (one-ai-chat-system), strictly behind the email
+		// gate. The agreement's clause text becomes the chat's runtime context.
+		await injectResourceChatLauncher(resolved, email, {
+			resourceKey: "agreement",
+			agentConfigSlug: "agreement-assistant-agent",
+			organisationId: session.organisationId ?? undefined,
+			title: "Agreement Assistant",
+			launchLabel: "Ask about this agreement",
+			welcomeMessage:
+				"Hi! Ask me anything about this agreement — clauses, fees, the schedules, or how signing works.",
+			placeholder: "Ask about this agreement…",
+			conversationStarters: [
+				"What are the key terms?",
+				"Summarise the fees and payment terms.",
+				"What's in Schedule A and Schedule B?",
+				"How do I sign this?",
+			],
+		});
+
+		// Old-flow only: drop the pre-placed gate block (new flow has none).
+		if (hasPrePlacedGate(resolved)) {
+			const { gateRegions } = findAgreementGate(resolved);
+			for (const { pd, content, gateIdx } of gateRegions) {
+				pd.content = content.filter((_, i) => i !== gateIdx);
+			}
+		}
+	},
+	async onUnauthorized(resolved, agreementUuid) {
+		if (hasPrePlacedGate(resolved)) {
+			// Old flow: strip region to gate-only.
+			const { gateRegions } = findAgreementGate(resolved);
+			for (const { pd, content, gateIdx } of gateRegions) {
+				pd.content = [content[gateIdx]];
+			}
+		} else {
+			// New flow: inject gate, withhold all body content.
+			const meta = resolved[AGREEMENT_META_KEY] as
+				| { name?: string }
+				| undefined;
+			const content = getBodyContentArray(resolved);
+			if (content) {
+				const settings =
+					(await loadAgreementGateSettings()) ?? AGREEMENT_GATE_DEFAULTS;
+				content.length = 0;
+				content.push(
+					buildGateBlock(
+						agreementUuid,
+						meta?.name ?? "Private document",
+						settings,
+					),
+				);
+			}
+		}
+
+		// Common: strip agreement-placeholder blocks + neutralize page meta.
+		for (const value of Object.values(resolved)) {
+			const pd = (
+				value as { puck_data?: { content?: unknown[] } } | null
+			)?.puck_data;
+			if (pd && Array.isArray(pd.content)) {
+				pd.content = stripAgreementPlaceholderBlocks(
+					pd.content as ContentBlock[],
+				);
+			}
+		}
+		const page = resolved.page as
+			| { meta_title?: unknown; meta_description?: unknown; name?: unknown }
+			| null
+			| undefined;
+		if (page) {
+			page.meta_title = "Private document";
+			page.meta_description = "";
+			page.name = "Private document";
+		}
+	},
+};
+
+/** The agreement's authorized email set (its signer roster) for the access endpoint. */
+async function resolveAgreementSignerEmails(
+	agreementId: string,
+): Promise<Set<string>> {
+	const emails = new Set<string>();
+	try {
+		const { getPrisma } = await import("@teamscala/db/prisma-registry");
+		const agreement = await getPrisma().agreements.findFirst({
+			where: { id: agreementId },
+			select: { signer_email: true, signature_data: true },
+		});
+		if (!agreement) return emails;
+		const parties = parseAgreementParties(agreement.signature_data);
+		if (parties) {
+			for (const p of parties) {
+				if (p.email) emails.add(p.email.trim().toLowerCase());
+			}
+		}
+		if (agreement.signer_email) {
+			emails.add(String(agreement.signer_email).trim().toLowerCase());
+		}
+		return emails;
+	} catch (err) {
+		getAppLogger().error(
+			`[agreement-gate] signer-email resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return emails;
+	}
+}
+
+/**
+ * Every email allowed PAST the gate: the signer roster (who may sign) UNION every
+ * member of the owning org (who may VIEW). Signing authority stays roster-only —
+ * buildSigningSession gives a non-party org member a view-only session. This is
+ * what the access endpoint and session-authorize check.
+ */
+async function resolveAgreementAuthorizedEmails(
+	agreementId: string,
+): Promise<Set<string>> {
+	const emails = await resolveAgreementSignerEmails(agreementId);
+	try {
+		const { getPrisma } = await import("@teamscala/db/prisma-registry");
+		const agreement = await getPrisma().agreements.findFirst({
+			where: { id: agreementId },
+			select: { organisation_id: true, signature_data: true },
+		});
+		// View-orgs = each party's organisationId (self-describing model) ∪ the
+		// agreement's owning org (also included for agreements that predate
+		// per-party org). Members of any of these may view; signing stays designated-signer-only.
+		const orgIds = new Set<string | null | undefined>();
+		if (typeof agreement?.organisation_id === "string") {
+			orgIds.add(agreement.organisation_id);
+		}
+		for (const p of parseAgreementParties(agreement?.signature_data) ?? []) {
+			if (p.organisationId) orgIds.add(p.organisationId);
+		}
+		const directory = await resolveAgreementViewerDirectory(orgIds);
+		for (const email of directory.keys()) emails.add(email);
+	} catch (err) {
+		getAppLogger().error(
+			`[agreement-gate] authorized-emails resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+	return emails;
+}
+
+export const agreementAccessConfig: AccessConfig = {
+	path: "/api/agreement-access",
+	cookieName: AG_COOKIE,
+	get ttlMs() {
+		return agTtlMs();
+	},
+	recordIdField: "agreementId",
+	resolveAuthorizedEmails: resolveAgreementAuthorizedEmails,
+	signToken(resourceId, email, nowMs) {
+		return signAgreementAccessToken(resourceId, email, nowMs);
+	},
+};