@teamscala/service-boot 0.23.413 → 0.23.415

package/src/agreement-gate/signing-session.ts

@@ -0,0 +1,254 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The verified signer's signing session: gate-block discovery across regions,
+ * roster/party session construction (signer vs view-only org member), and
+ * seeding of the session into every SignatureField.
+ *
+ * Split out of agreement-gate.ts (909 lines) — byte-for-byte move; import
+ * paths adjusted only.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import {
+	type PublicAgreementParty,
+	parseAgreementParties,
+	toPublicParties,
+} from "@teamscala/document-signing/agreement-parties";
+import {
+	buildCertificateData,
+	type CertificateData,
+} from "../fn-routers/public-agreement-router.ts";
+import { findFirstAgreement, resolveAgreementViewerDirectory } from "./agreement-lookup.ts";
+
+export interface ContentBlock {
+	type?: string;
+	props?: Record<string, unknown>;
+}
+
+export 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. */
+export 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`.
+ */
+export 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. */
+export async function buildSigningSession(
+	agreementUuid: string,
+	verifiedEmail: string,
+): Promise<SigningSession | null> {
+	const log = getAppLogger();
+	const lower = verifiedEmail.trim().toLowerCase();
+	try {
+		const agreement = await findFirstAgreement<{
+			name: string | null;
+			signer_name: string | null;
+			signed_at: Date | string | null;
+			signature_data: unknown;
+			organisation_id: string | null;
+		}>({
+			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) 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. */
+export 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);
+	}
+}
+
+/** The org's display name (for the footer audit line), from the resolved brand. */
+export 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;
+}

package/src/agreement-gate/signing-shell.ts

@@ -0,0 +1,201 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * New-flow signing-shell injection (no pre-placed gate required): agreement
+ * meta stashing, body-content discovery, the SignIn gate block builder, and
+ * the DB-driven signing shell (config/agreement-signing-shell) with its
+ * hardcoded fallback.
+ *
+ * Split out of agreement-gate.ts (909 lines) — byte-for-byte move; import
+ * paths adjusted only.
+ */
+
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+import { findAgreementGate } from "./signing-session.ts";
+import type { ContentBlock } from "./signing-session.ts";
+import type { AgreementGateSettings } from "./settings.ts";
+
+/** Agreement metadata stashed on resolved during getResourceId. */
+export const AGREEMENT_META_KEY = "_agreementMeta";
+
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export 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). */
+export function hasPrePlacedGate(resolved: Record<string, unknown>): boolean {
+	return findAgreementGate(resolved).agreementUuid !== "";
+}