@teamscala/service-boot 0.23.415 → 0.23.416

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.415",
+  "version": "0.23.416",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -1181,6 +1181,30 @@
     "./agreement-gate/authorized-emails.ts": {
       "types": "./src/agreement-gate/authorized-emails.d.ts",
       "default": "./src/agreement-gate/authorized-emails.ts"
+    },
+    "./fn-routers/agreement-signing-evidence": {
+      "types": "./src/fn-routers/agreement-signing-evidence.d.ts",
+      "default": "./src/fn-routers/agreement-signing-evidence.ts"
+    },
+    "./fn-routers/agreement-signing-evidence.ts": {
+      "types": "./src/fn-routers/agreement-signing-evidence.d.ts",
+      "default": "./src/fn-routers/agreement-signing-evidence.ts"
+    },
+    "./fn-routers/agreement-certificate": {
+      "types": "./src/fn-routers/agreement-certificate.d.ts",
+      "default": "./src/fn-routers/agreement-certificate.ts"
+    },
+    "./fn-routers/agreement-certificate.ts": {
+      "types": "./src/fn-routers/agreement-certificate.d.ts",
+      "default": "./src/fn-routers/agreement-certificate.ts"
+    },
+    "./fn-routers/agreement-sign-side-effects": {
+      "types": "./src/fn-routers/agreement-sign-side-effects.d.ts",
+      "default": "./src/fn-routers/agreement-sign-side-effects.ts"
+    },
+    "./fn-routers/agreement-sign-side-effects.ts": {
+      "types": "./src/fn-routers/agreement-sign-side-effects.d.ts",
+      "default": "./src/fn-routers/agreement-sign-side-effects.ts"
     }
   },
   "repository": "https://github.com/teamgbg/service-boot",

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

@@ -20,7 +20,7 @@ import {
 import {
 	buildCertificateData,
 	type CertificateData,
-} from "../fn-routers/public-agreement-router.ts";
+} from "../fn-routers/agreement-certificate.ts";
 import { findFirstAgreement, resolveAgreementViewerDirectory } from "./agreement-lookup.ts";
 
 export interface ContentBlock {

package/src/fn-routers/agreement-certificate.ts

@@ -0,0 +1,224 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The Certificate of Completion for an executed agreement: DB-driven display
+ * copy (config/certificate-of-completion), the CertificateData shape, and
+ * the party-gated builder.
+ *
+ * Split out of fn-routers/public-agreement-router.ts (853 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import * as v from "valibot";
+import { queryRows } from "@teamscala/db/query-rows";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import {
+	parseAgreementParties as parseParties,
+} from "@teamscala/document-signing/agreement-parties";
+import { parseEvidence } from "./agreement-signing-evidence.ts";
+
+/** The Certificate of Completion display copy. DB-driven via the
+ *  `config/certificate-of-completion` registry row — mirrors the agreement gate's
+ *  `config/content-gate-agreement` pattern (same signing surface), so an operator
+ *  can rebrand/reword the certificate via `registry_edit` with no deploy; the
+ *  hardcoded defaults are the fallback. Generic structural data-column labels
+ *  (Signer/Role/Envelope ID/…) stay in the component, exactly as the gate keeps
+ *  its structural markup in code. */
+export interface CertificateCopy {
+	title: string;
+	signersHeading: string;
+	sealHeading: string;
+	sealNote: string;
+	footer: string;
+	badgeCompleted: string;
+	badgeInProgress: string;
+	/** Audit-table column labels — DB-driven so rewording is a registry_edit.
+	 *  Each labels BOTH the <th> header AND the stacked-row data-label on mobile
+	 *  (one source, kept in sync), never a second hardcoded copy. */
+	colSigner: string;
+	colRole: string;
+	colSigned: string;
+	colIp: string;
+	colAuth: string;
+}
+
+const CERTIFICATE_COPY_DEFAULTS: CertificateCopy = {
+	title: "CERTIFICATE OF COMPLETION",
+	signersHeading: "Signers",
+	sealHeading: "Tamper-evident seal",
+	sealNote:
+		"{{hashAlgo}} hash of the executed document + signed roster, sealed {{hashedAt}}. Re-hashing the stored document and comparing to this value proves it has not been altered since signing.",
+	footer:
+		"This certificate is a record of the electronic signing of the above agreement, produced from the platform's permanent audit trail. Electronic signatures are legally recognised under the ESIGN Act and UETA (US) and eIDAS (EU).",
+	badgeCompleted: "Completed",
+	badgeInProgress: "In progress",
+	colSigner: "Signer",
+	colRole: "Role",
+	colSigned: "Signed (UTC)",
+	colIp: "IP address",
+	colAuth: "Auth",
+};
+
+const CertificateCopySchema = v.object({
+	title: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.title),
+	signersHeading: v.optional(
+		v.string(),
+		CERTIFICATE_COPY_DEFAULTS.signersHeading,
+	),
+	sealHeading: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.sealHeading),
+	sealNote: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.sealNote),
+	footer: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.footer),
+	badgeCompleted: v.optional(
+		v.string(),
+		CERTIFICATE_COPY_DEFAULTS.badgeCompleted,
+	),
+	badgeInProgress: v.optional(
+		v.string(),
+		CERTIFICATE_COPY_DEFAULTS.badgeInProgress,
+	),
+	colSigner: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colSigner),
+	colRole: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colRole),
+	colSigned: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colSigned),
+	colIp: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colIp),
+	colAuth: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colAuth),
+});
+
+async function loadCertificateCopy(): Promise<CertificateCopy | null> {
+	try {
+		return await loadRegistryConfig(
+			"config",
+			"certificate-of-completion",
+			CertificateCopySchema,
+		);
+	} catch {
+		// Absent signal, not a masking fallback (protective-layers-fail-explicitly):
+		// null propagates to CertificateData.copy, and the component renders its
+		// FALLBACK_COPY — same default values, but the absence is honest rather
+		// than disguised as a successful config load.
+		return null;
+	}
+}
+
+/** The Certificate of Completion data shape — the court-style audit certificate.
+ *  One home: {@link buildCertificateData} is consumed by the SSR agreement
+ *  gate, so the signing block receives the server-seeded prop. */
+export interface CertificateData {
+	ok: boolean;
+	envelopeId?: string;
+	documentName?: string | null;
+	issuedAt?: string;
+	complete?: boolean;
+	createdAt?: string | null;
+	sentAt?: string | null;
+	viewedAt?: string | null;
+	signedAt?: string | null;
+	documentHash?: string | null;
+	hashAlgo?: string | null;
+	hashedAt?: string | null;
+	parties?: {
+		role: string;
+		name: string | null;
+		email: string | null;
+		title: string | null;
+		company: string | null;
+		signedAt: string | null;
+		ip: string | null;
+		userAgent: string | null;
+		authMethod: string | null;
+	}[];
+	/** DB-driven display copy (config/certificate-of-completion); null when the
+	 *  config row is missing/broken — the component falls back to FALLBACK_COPY. */
+	copy?: CertificateCopy | null;
+}
+
+/**
+ * Build the Certificate of Completion data for an agreement, gated to a party
+ * email — signer evidence (IP/device) is never exposed to a non-party. One data
+ * home: the SSR agreement gate (`buildSigningSession` in agreement-gate.ts)
+ * calls this. The read is
+ * intentionally RLS-unscoped via the raw registry prisma — the certificate is
+ * reached without a session (AG cookie only), which context.prisma's RLS would
+ * otherwise treat as no-org and hide. Accepts either the agreement record id or
+ * its page id (the UUID the signer sees in the URL is the page id).
+ */
+export async function buildCertificateData(
+	agreementId: string,
+	email: string,
+): Promise<CertificateData> {
+	const id = agreementId.trim();
+	const mail = email.trim().toLowerCase();
+	if (!id || !mail) return { ok: false };
+	const [agreement] = await queryRows<
+		{
+			id: string;
+			name: string;
+			created_at: Date | null;
+			sent_at: Date | null;
+			viewed_at: Date | null;
+			signed_at: Date | null;
+			signature_data: unknown;
+			signer_email: string | null;
+			signer_name: string | null;
+		}[]
+	>`
+		SELECT id, name, created_at, sent_at, viewed_at, signed_at,
+		       signature_data, signer_email, signer_name
+		  FROM agreements
+		 WHERE (id = ${id} OR page_id = ${id})
+		 LIMIT 1`;
+	if (!agreement) return { ok: false };
+	const parties = parseParties(agreement.signature_data);
+	const evidence = parseEvidence(agreement.signature_data);
+	const isParty = parties
+		? parties.some((p) => p.email.trim().toLowerCase() === mail)
+		: String(agreement.signer_email ?? "")
+				.trim()
+				.toLowerCase() === mail;
+	if (!isParty) return { ok: false };
+	const complete =
+		!!agreement.signed_at || (parties?.every((p) => p.signedAt) ?? false);
+	const iso = (d: Date | null | undefined) => d?.toISOString() ?? null;
+	const copy = await loadCertificateCopy();
+	return {
+		ok: true,
+		copy,
+		envelopeId: agreement.id,
+		documentName: agreement.name,
+		issuedAt: new Date().toISOString(),
+		complete,
+		createdAt: iso(agreement.created_at),
+		sentAt: iso(agreement.sent_at),
+		viewedAt: iso(agreement.viewed_at),
+		signedAt: iso(agreement.signed_at),
+		documentHash: evidence?.documentHash ?? null,
+		hashAlgo: evidence?.hashAlgo ?? null,
+		hashedAt: evidence?.hashedAt ?? null,
+		parties: parties
+			? parties.map((p) => ({
+					role: p.key,
+					name: p.name,
+					email: p.email,
+					title: p.title,
+					company: p.company,
+					signedAt: p.signedAt,
+					ip: p.signedIp ?? null,
+					userAgent: p.signedUserAgent ?? null,
+					authMethod: p.authMethod ?? null,
+				}))
+			: [
+					{
+						role: "signer",
+						name: agreement.signer_name,
+						email: agreement.signer_email,
+						title: null,
+						company: null,
+						signedAt: iso(agreement.signed_at),
+						ip: null,
+						userAgent: null,
+						authMethod: "email-match",
+					},
+				],
+	};
+}

package/src/fn-routers/agreement-sign-side-effects.ts

@@ -0,0 +1,190 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Post-signature side effects of public agreement signing: Stripe invoice
+ * creation via the payments service, the self-resetting demo harness, and
+ * CRM connection of the captured signer.
+ *
+ * Split out of fn-routers/public-agreement-router.ts (853 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { queryRows } from "@teamscala/db/query-rows";
+import type { AgreementParty } from "@teamscala/document-signing/agreement-parties";
+
+/** On full agreement completion, delegate to the payment service over HTTP to
+ *  create the Stripe invoice (per payment-is-one-service — all Stripe logic
+ *  lives in @teamscala/payment, reached via POST /api/payments/checkout). Never
+ *  throws — a payment-setup failure must not undo a completed signature; the
+ *  signer is simply not auto-redirected to pay. But every failure mode is
+ *  logged at WARN with the actual cause (URL missing, non-2xx, network, parse)
+ *  so the silent-fail class the user would otherwise diagnose by hand is
+ *  observable in GlitchTip + pm2 logs. */
+export async function invoicePayUrl(
+	agreementId: string,
+	baseUrl: string,
+): Promise<string | null> {
+	const log = getAppLogger();
+	const paymentsUrl = (process.env.SCALA_PAYMENTS_URL ?? "").replace(/\/+$/, "");
+	if (!paymentsUrl) {
+		log.warn(
+			`[publicAgreement] agreement ${agreementId} signed but SCALA_PAYMENTS_URL is unset — no invoice created. Set the env var on scala-sign's service_env row to a pay-internal tunnel URL.`,
+		);
+		return null;
+	}
+	try {
+		const res = await fetch(`${paymentsUrl}/api/payments/checkout`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ agreementId, baseUrl }),
+		});
+		if (!res.ok) {
+			log.warn(
+				`[publicAgreement] payments checkout returned ${res.status} for agreement ${agreementId} (${paymentsUrl}/api/payments/checkout)`,
+			);
+			return null;
+		}
+		const json = (await res.json()) as { ok?: boolean; hostedInvoiceUrl?: string };
+		if (!json.ok) {
+			log.warn(
+				`[publicAgreement] payments checkout ok=false for agreement ${agreementId}: ${JSON.stringify(json).slice(0, 200)}`,
+			);
+			return null;
+		}
+		return json.hostedInvoiceUrl ?? null;
+	} catch (err) {
+		log.warn(
+			`[publicAgreement] payments checkout threw for agreement ${agreementId} (${paymentsUrl}): ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return null;
+	}
+}
+
+/**
+ * Self-resetting demo harness. If the signed agreement's `proposal_id` is in
+ * the `demo-reset-agreements.proposalIds` allow-list, reset its parties to
+ * UNSIGNED (signedAt/signature cleared) + clear signed_at/signed_by + status
+ * 'sent', so the next person gets a fresh form to test the UI.
+ *
+ * Keyed on the stable PROPOSAL id, NOT the agreement id: the demo agreement is
+ * regenerated under a fresh id whenever the demo proposal is re-accepted, but
+ * its `proposal_id` FK is constant — so the allow-list cannot dangle. This
+ * deletes the drift class (prevention, not a patrol): the prior design keyed on
+ * `agreementIds`, and when the demo was regenerated the list silently pointed
+ * at a dead id and the reset became a no-op for weeks. A `proposal_id`-
+ * referenced row that doesn't exist is a real proposal being deleted, not a
+ * regeneration — a negligible residual the operator would notice directly.
+ *
+ * Gated strictly by the allow-list — a real agreement is never reset.
+ * Best-effort: any failure is swallowed (a demo-reset must never fail the
+ * signer's own response). The current signer already has their response (incl.
+ * payUrl) before this runs; only the stored record is reset.
+ */
+export async function maybeResetDemoAgreement(
+	prisma: any,
+	agreementId: string,
+	proposalId: string | null,
+	parties: AgreementParty[],
+): Promise<void> {
+	if (!proposalId) return;
+	try {
+		const rows = await queryRows`
+			SELECT config FROM registry_entries
+			 WHERE type = 'config' AND slug = 'demo-reset-agreements' AND is_active = true
+			 LIMIT 1` as { config: { proposalIds?: string[] } }[];
+		const ids = rows?.[0]?.config?.proposalIds ?? [];
+		if (!Array.isArray(ids) || !ids.includes(proposalId)) return;
+		const reset = parties.map((p) => ({
+			...p,
+			signedAt: null,
+			signature: null,
+			title: null,
+			company: null,
+		}));
+		await prisma.agreements.update({
+			where: { id: agreementId },
+			data: {
+				signature_data: JSON.stringify({ parties: reset }),
+				signed_at: null,
+				signed_by: null,
+				status: "sent",
+			},
+		});
+		getAppLogger().info(`[publicAgreement.sign] demo agreement ${agreementId} auto-reset for re-testing`);
+	} catch {
+		// never fail the signer's response over a demo-reset
+	}
+}
+
+/**
+ * Connect a captured signer to the CRM — every signable document lands in
+ * client_database, the same find-or-create capture path proposals / public-GPT /
+ * assessments already use (scoped by organisation_id + primary_email). Also
+ * links agreement.contact_id when the agreement wasn't generated from a proposal
+ * (contact_id NULL), so a standalone signed doc still connects to the CRM.
+ * Best-effort: a CRM write must never fail the signature (the signature is the
+ * legal act; CRM connection is bookkeeping).
+ */
+export async function connectSignerToCrm(
+	prisma: any,
+	agreement: { id: string; organisation_id?: string | null; contact_id?: string | null },
+	email: string,
+	signerName?: string | null,
+	company?: string | null,
+): Promise<void> {
+	const orgId = agreement.organisation_id;
+	if (!orgId || !email || !prisma?.client_database) return;
+	try {
+		const parts = (signerName ?? "").trim().split(/\s+/).filter(Boolean);
+		const firstName = parts[0] ?? "";
+		const lastName = parts.slice(1).join(" ");
+		const existing = await prisma.client_database.findFirst({
+			where: { organisation_id: orgId, primary_email: email },
+			select: { id: true },
+		});
+		let contactId: string | null = null;
+		if (existing) {
+			contactId = existing.id as string;
+			await prisma.client_database.update({
+				where: { id: existing.id },
+				data: {
+					...(firstName ? { first_name: firstName } : {}),
+					...(lastName ? { last_name: lastName } : {}),
+					...(company ? { company_name: company } : {}),
+					last_updated_by: "agreement-sign",
+				},
+			});
+		} else {
+			const created = await prisma.client_database.create({
+				data: {
+					organisation_id: orgId,
+					first_name: firstName,
+					last_name: lastName,
+					primary_email: email,
+					...(company ? { company_name: company } : {}),
+					lead_source: "agreement-sign",
+					data_source: "public-form",
+					referral_source: agreement.id,
+					lifecycle_stage: "lead",
+					created_by: "agreement-sign",
+					last_updated_by: "agreement-sign",
+				},
+				select: { id: true },
+			});
+			contactId = (created?.id as string) ?? null;
+		}
+		if (contactId && !agreement.contact_id) {
+			await prisma.agreements.update({
+				where: { id: agreement.id },
+				data: { contact_id: contactId },
+			});
+		}
+	} catch (e) {
+		getAppLogger().warn(
+			`[publicAgreement.sign] CRM connect failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+}

package/src/fn-routers/agreement-signing-evidence.ts

@@ -0,0 +1,105 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Signing-evidence utilities for public agreement signing: the signer's
+ * origin/IP extraction from request headers, the canonical JSON form, the
+ * tamper-evident document hash, and the evidence-seal parser.
+ *
+ * Split out of fn-routers/public-agreement-router.ts (853 lines) —
+ * byte-for-byte move except createHash → Bun.CryptoHasher
+ * (bun-native-crypto guard; identical digest output).
+ */
+
+import type { AgreementParty } from "@teamscala/document-signing/agreement-parties";
+
+/** The signer's own origin, from the request headers (sign[-dev].scala.business),
+ *  so Checkout returns them to the same site they signed on. */
+export function originFrom(headers: Headers): string {
+	const host = headers.get("x-forwarded-host") ?? headers.get("host");
+	const proto = headers.get("x-forwarded-proto") ?? "https";
+	return host ? `${proto}://${host}` : "https://sign.scala.business";
+}
+
+/** The signer's real client IP at the moment of signing, for the audit trail.
+ *  Behind Cloudflare/Railway the original IP is the FIRST hop of
+ *  x-forwarded-for (the chain is client, proxy1, proxy2…); cf-connecting-ip and
+ *  x-real-ip are the per-proxy fallbacks. Returns null if none are present. */
+export function clientIp(headers: Headers): string | null {
+	const fwd = headers.get("x-forwarded-for");
+	const first = fwd?.split(",")[0]?.trim();
+	return (
+		first ||
+		headers.get("cf-connecting-ip") ||
+		headers.get("x-real-ip") ||
+		null
+	);
+}
+
+/** Deterministic JSON (recursively sorted object keys) so a hash over the same
+ *  logical content is reproducible regardless of property insertion order —
+ *  required for tamper-verification (re-hash later, compare). */
+function canonicalJson(value: unknown): string {
+	return JSON.stringify(value, (_key, val) =>
+		val && typeof val === "object" && !Array.isArray(val)
+			? Object.fromEntries(
+					Object.entries(val as Record<string, unknown>).sort(([a], [b]) =>
+						a.localeCompare(b),
+					),
+				)
+			: val,
+	);
+}
+
+/** Tamper-evident seal: SHA-256 over the executed document's content + the
+ *  full signed roster. Storing this at completion lets the verification surface
+ *  re-hash the stored document later and prove nothing changed after signing
+ *  (the marketplace "tamper-evident" bar, short of a qualified-CA PAdES seal). */
+export function computeDocumentHash(
+	documentContent: unknown,
+	parties: AgreementParty[],
+): string {
+	return new Bun.CryptoHasher("sha256")
+		.update(
+			canonicalJson({
+				document: documentContent ?? null,
+				signatures: parties.map((p) => ({
+					key: p.key,
+					email: p.email,
+					name: p.name,
+					title: p.title,
+					company: p.company,
+					signature: p.signature,
+					signedAt: p.signedAt,
+				})),
+			}),
+			"utf8",
+		)
+		.digest("hex");
+}
+
+/** Parse the optional evidence seal (document hash) from signature_data, which
+ *  has the shape { parties, evidence? }. Returns null when no seal is present. */
+export function parseEvidence(sigData: unknown): {
+	documentHash?: string;
+	hashAlgo?: string;
+	hashedAt?: string;
+} | null {
+	if (typeof sigData !== "string") return null;
+	const t = sigData.trim();
+	if (!t.startsWith("{")) return null;
+	try {
+		const o = JSON.parse(t) as { evidence?: Record<string, unknown> };
+		const e = o.evidence;
+		if (!e || typeof e !== "object") return null;
+		return {
+			documentHash:
+				typeof e.documentHash === "string" ? e.documentHash : undefined,
+			hashAlgo: typeof e.hashAlgo === "string" ? e.hashAlgo : undefined,
+			hashedAt: typeof e.hashedAt === "string" ? e.hashedAt : undefined,
+		};
+	} catch {
+		return null;
+	}
+}

package/src/fn-routers/public-agreement-router.ts

@@ -1,6 +1,6 @@
 /**
  * @system service-boot
- * @status handwritten @indivisible-unit
+ * @status handwritten
  * @edit edit directly
  *
  * Public ORPC procedures for DocuSign-style agreement signing, reached by the
@@ -20,488 +20,39 @@
  * with no schema change. Each party is gated by its own email; the agreement
  * completes (signed_at set) only when every party has signed. A single-signer
  * agreement falls back to the original signer_email/signer_name columns.
+ *
+ * This module holds the three procedures (verify/sign/verifyDocument). The
+ * supporting machinery lives as siblings: agreement-signing-evidence.ts
+ * (origin/IP extraction, tamper-evident hash, evidence parser),
+ * agreement-certificate.ts (Certificate of Completion), and
+ * agreement-sign-side-effects.ts (invoice, demo-reset, CRM connect) — split
+ * when the parent held them all at 853 lines.
  */
 
-import { createHash } from "node:crypto";
 import { os } from "@orpc/server";
 import * as v from "valibot";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { queryRows } from "@teamscala/db/query-rows";
 import { signAgreementAccessToken } from "@teamscala/document-signing/agreement-access-token";
 import {
-	type AgreementParty,
 	parseAgreementParties as parseParties,
 	toPublicParties as partySummary,
 } from "@teamscala/document-signing/agreement-parties";
 import { sendAgreementCompletionEmails } from "./agreement-completion-email.ts";
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-/** On full agreement completion, delegate to the payment service over HTTP to
- *  create the Stripe invoice (per payment-is-one-service — all Stripe logic
- *  lives in @teamscala/payment, reached via POST /api/payments/checkout). Never
- *  throws — a payment-setup failure must not undo a completed signature; the
- *  signer is simply not auto-redirected to pay. But every failure mode is
- *  logged at WARN with the actual cause (URL missing, non-2xx, network, parse)
- *  so the silent-fail class the user would otherwise diagnose by hand is
- *  observable in GlitchTip + pm2 logs. */
-async function invoicePayUrl(
-	agreementId: string,
-	baseUrl: string,
-): Promise<string | null> {
-	const log = getAppLogger();
-	const paymentsUrl = (process.env.SCALA_PAYMENTS_URL ?? "").replace(/\/+$/, "");
-	if (!paymentsUrl) {
-		log.warn(
-			`[publicAgreement] agreement ${agreementId} signed but SCALA_PAYMENTS_URL is unset — no invoice created. Set the env var on scala-sign's service_env row to a pay-internal tunnel URL.`,
-		);
-		return null;
-	}
-	try {
-		const res = await fetch(`${paymentsUrl}/api/payments/checkout`, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({ agreementId, baseUrl }),
-		});
-		if (!res.ok) {
-			log.warn(
-				`[publicAgreement] payments checkout returned ${res.status} for agreement ${agreementId} (${paymentsUrl}/api/payments/checkout)`,
-			);
-			return null;
-		}
-		const json = (await res.json()) as { ok?: boolean; hostedInvoiceUrl?: string };
-		if (!json.ok) {
-			log.warn(
-				`[publicAgreement] payments checkout ok=false for agreement ${agreementId}: ${JSON.stringify(json).slice(0, 200)}`,
-			);
-			return null;
-		}
-		return json.hostedInvoiceUrl ?? null;
-	} catch (err) {
-		log.warn(
-			`[publicAgreement] payments checkout threw for agreement ${agreementId} (${paymentsUrl}): ${err instanceof Error ? err.message : String(err)}`,
-		);
-		return null;
-	}
-}
-
-/** The signer's own origin, from the request headers (sign[-dev].scala.business),
- *  so Checkout returns them to the same site they signed on. */
-function originFrom(headers: Headers): string {
-	const host = headers.get("x-forwarded-host") ?? headers.get("host");
-	const proto = headers.get("x-forwarded-proto") ?? "https";
-	return host ? `${proto}://${host}` : "https://sign.scala.business";
-}
-
-/** The signer's real client IP at the moment of signing, for the audit trail.
- *  Behind Cloudflare/Railway the original IP is the FIRST hop of
- *  x-forwarded-for (the chain is client, proxy1, proxy2…); cf-connecting-ip and
- *  x-real-ip are the per-proxy fallbacks. Returns null if none are present. */
-function clientIp(headers: Headers): string | null {
-	const fwd = headers.get("x-forwarded-for");
-	const first = fwd?.split(",")[0]?.trim();
-	return (
-		first ||
-		headers.get("cf-connecting-ip") ||
-		headers.get("x-real-ip") ||
-		null
-	);
-}
-
-/** Deterministic JSON (recursively sorted object keys) so a hash over the same
- *  logical content is reproducible regardless of property insertion order —
- *  required for tamper-verification (re-hash later, compare). */
-function canonicalJson(value: unknown): string {
-	return JSON.stringify(value, (_key, val) =>
-		val && typeof val === "object" && !Array.isArray(val)
-			? Object.fromEntries(
-					Object.entries(val as Record<string, unknown>).sort(([a], [b]) =>
-						a.localeCompare(b),
-					),
-				)
-			: val,
-	);
-}
-
-/** Tamper-evident seal: SHA-256 over the executed document's content + the
- *  full signed roster. Storing this at completion lets the verification surface
- *  re-hash the stored document later and prove nothing changed after signing
- *  (the marketplace "tamper-evident" bar, short of a qualified-CA PAdES seal). */
-function computeDocumentHash(
-	documentContent: unknown,
-	parties: AgreementParty[],
-): string {
-	return createHash("sha256")
-		.update(
-			canonicalJson({
-				document: documentContent ?? null,
-				signatures: parties.map((p) => ({
-					key: p.key,
-					email: p.email,
-					name: p.name,
-					title: p.title,
-					company: p.company,
-					signature: p.signature,
-					signedAt: p.signedAt,
-				})),
-			}),
-			"utf8",
-		)
-		.digest("hex");
-}
-
-/** Parse the optional evidence seal (document hash) from signature_data, which
- *  has the shape { parties, evidence? }. Returns null when no seal is present. */
-function parseEvidence(sigData: unknown): {
-	documentHash?: string;
-	hashAlgo?: string;
-	hashedAt?: string;
-} | null {
-	if (typeof sigData !== "string") return null;
-	const t = sigData.trim();
-	if (!t.startsWith("{")) return null;
-	try {
-		const o = JSON.parse(t) as { evidence?: Record<string, unknown> };
-		const e = o.evidence;
-		if (!e || typeof e !== "object") return null;
-		return {
-			documentHash:
-				typeof e.documentHash === "string" ? e.documentHash : undefined,
-			hashAlgo: typeof e.hashAlgo === "string" ? e.hashAlgo : undefined,
-			hashedAt: typeof e.hashedAt === "string" ? e.hashedAt : undefined,
-		};
-	} catch {
-		return null;
-	}
-}
-
-/** The Certificate of Completion display copy. DB-driven via the
- *  `config/certificate-of-completion` registry row — mirrors the agreement gate's
- *  `config/content-gate-agreement` pattern (same signing surface), so an operator
- *  can rebrand/reword the certificate via `registry_edit` with no deploy; the
- *  hardcoded defaults are the fallback. Generic structural data-column labels
- *  (Signer/Role/Envelope ID/…) stay in the component, exactly as the gate keeps
- *  its structural markup in code. */
-export interface CertificateCopy {
-	title: string;
-	signersHeading: string;
-	sealHeading: string;
-	sealNote: string;
-	footer: string;
-	badgeCompleted: string;
-	badgeInProgress: string;
-	/** Audit-table column labels — DB-driven so rewording is a registry_edit.
-	 *  Each labels BOTH the <th> header AND the stacked-row data-label on mobile
-	 *  (one source, kept in sync), never a second hardcoded copy. */
-	colSigner: string;
-	colRole: string;
-	colSigned: string;
-	colIp: string;
-	colAuth: string;
-}
-
-const CERTIFICATE_COPY_DEFAULTS: CertificateCopy = {
-	title: "CERTIFICATE OF COMPLETION",
-	signersHeading: "Signers",
-	sealHeading: "Tamper-evident seal",
-	sealNote:
-		"{{hashAlgo}} hash of the executed document + signed roster, sealed {{hashedAt}}. Re-hashing the stored document and comparing to this value proves it has not been altered since signing.",
-	footer:
-		"This certificate is a record of the electronic signing of the above agreement, produced from the platform's permanent audit trail. Electronic signatures are legally recognised under the ESIGN Act and UETA (US) and eIDAS (EU).",
-	badgeCompleted: "Completed",
-	badgeInProgress: "In progress",
-	colSigner: "Signer",
-	colRole: "Role",
-	colSigned: "Signed (UTC)",
-	colIp: "IP address",
-	colAuth: "Auth",
-};
-
-const CertificateCopySchema = v.object({
-	title: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.title),
-	signersHeading: v.optional(
-		v.string(),
-		CERTIFICATE_COPY_DEFAULTS.signersHeading,
-	),
-	sealHeading: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.sealHeading),
-	sealNote: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.sealNote),
-	footer: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.footer),
-	badgeCompleted: v.optional(
-		v.string(),
-		CERTIFICATE_COPY_DEFAULTS.badgeCompleted,
-	),
-	badgeInProgress: v.optional(
-		v.string(),
-		CERTIFICATE_COPY_DEFAULTS.badgeInProgress,
-	),
-	colSigner: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colSigner),
-	colRole: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colRole),
-	colSigned: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colSigned),
-	colIp: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colIp),
-	colAuth: v.optional(v.string(), CERTIFICATE_COPY_DEFAULTS.colAuth),
-});
-
-async function loadCertificateCopy(): Promise<CertificateCopy | null> {
-	try {
-		return await loadRegistryConfig(
-			"config",
-			"certificate-of-completion",
-			CertificateCopySchema,
-		);
-	} catch {
-		// Absent signal, not a masking fallback (protective-layers-fail-explicitly):
-		// null propagates to CertificateData.copy, and the component renders its
-		// FALLBACK_COPY — same default values, but the absence is honest rather
-		// than disguised as a successful config load.
-		return null;
-	}
-}
-
-/** The Certificate of Completion data shape — the court-style audit certificate.
- *  One home: {@link buildCertificateData} is consumed by the SSR agreement
- *  gate, so the signing block receives the server-seeded prop. */
-export interface CertificateData {
-	ok: boolean;
-	envelopeId?: string;
-	documentName?: string | null;
-	issuedAt?: string;
-	complete?: boolean;
-	createdAt?: string | null;
-	sentAt?: string | null;
-	viewedAt?: string | null;
-	signedAt?: string | null;
-	documentHash?: string | null;
-	hashAlgo?: string | null;
-	hashedAt?: string | null;
-	parties?: {
-		role: string;
-		name: string | null;
-		email: string | null;
-		title: string | null;
-		company: string | null;
-		signedAt: string | null;
-		ip: string | null;
-		userAgent: string | null;
-		authMethod: string | null;
-	}[];
-	/** DB-driven display copy (config/certificate-of-completion); null when the
-	 *  config row is missing/broken — the component falls back to FALLBACK_COPY. */
-	copy?: CertificateCopy | null;
-}
-
-/**
- * Build the Certificate of Completion data for an agreement, gated to a party
- * email — signer evidence (IP/device) is never exposed to a non-party. One data
- * home: the SSR agreement gate (`buildSigningSession` in agreement-gate.ts)
- * calls this. The read is
- * intentionally RLS-unscoped via the raw registry prisma — the certificate is
- * reached without a session (AG cookie only), which context.prisma's RLS would
- * otherwise treat as no-org and hide. Accepts either the agreement record id or
- * its page id (the UUID the signer sees in the URL is the page id).
- */
-export async function buildCertificateData(
-	agreementId: string,
-	email: string,
-): Promise<CertificateData> {
-	const id = agreementId.trim();
-	const mail = email.trim().toLowerCase();
-	if (!id || !mail) return { ok: false };
-	const [agreement] = await queryRows<
-		{
-			id: string;
-			name: string;
-			created_at: Date | null;
-			sent_at: Date | null;
-			viewed_at: Date | null;
-			signed_at: Date | null;
-			signature_data: unknown;
-			signer_email: string | null;
-			signer_name: string | null;
-		}[]
-	>`
-		SELECT id, name, created_at, sent_at, viewed_at, signed_at,
-		       signature_data, signer_email, signer_name
-		  FROM agreements
-		 WHERE (id = ${id} OR page_id = ${id})
-		 LIMIT 1`;
-	if (!agreement) return { ok: false };
-	const parties = parseParties(agreement.signature_data);
-	const evidence = parseEvidence(agreement.signature_data);
-	const isParty = parties
-		? parties.some((p) => p.email.trim().toLowerCase() === mail)
-		: String(agreement.signer_email ?? "")
-				.trim()
-				.toLowerCase() === mail;
-	if (!isParty) return { ok: false };
-	const complete =
-		!!agreement.signed_at || (parties?.every((p) => p.signedAt) ?? false);
-	const iso = (d: Date | null | undefined) => d?.toISOString() ?? null;
-	const copy = await loadCertificateCopy();
-	return {
-		ok: true,
-		copy,
-		envelopeId: agreement.id,
-		documentName: agreement.name,
-		issuedAt: new Date().toISOString(),
-		complete,
-		createdAt: iso(agreement.created_at),
-		sentAt: iso(agreement.sent_at),
-		viewedAt: iso(agreement.viewed_at),
-		signedAt: iso(agreement.signed_at),
-		documentHash: evidence?.documentHash ?? null,
-		hashAlgo: evidence?.hashAlgo ?? null,
-		hashedAt: evidence?.hashedAt ?? null,
-		parties: parties
-			? parties.map((p) => ({
-					role: p.key,
-					name: p.name,
-					email: p.email,
-					title: p.title,
-					company: p.company,
-					signedAt: p.signedAt,
-					ip: p.signedIp ?? null,
-					userAgent: p.signedUserAgent ?? null,
-					authMethod: p.authMethod ?? null,
-				}))
-			: [
-					{
-						role: "signer",
-						name: agreement.signer_name,
-						email: agreement.signer_email,
-						title: null,
-						company: null,
-						signedAt: iso(agreement.signed_at),
-						ip: null,
-						userAgent: null,
-						authMethod: "email-match",
-					},
-				],
-	};
-}
-
-/**
- * Self-resetting demo harness. If the signed agreement's `proposal_id` is in
- * the `demo-reset-agreements.proposalIds` allow-list, reset its parties to
- * UNSIGNED (signedAt/signature cleared) + clear signed_at/signed_by + status
- * 'sent', so the next person gets a fresh form to test the UI.
- *
- * Keyed on the stable PROPOSAL id, NOT the agreement id: the demo agreement is
- * regenerated under a fresh id whenever the demo proposal is re-accepted, but
- * its `proposal_id` FK is constant — so the allow-list cannot dangle. This
- * deletes the drift class (prevention, not a patrol): the prior design keyed on
- * `agreementIds`, and when the demo was regenerated the list silently pointed
- * at a dead id and the reset became a no-op for weeks. A `proposal_id`-
- * referenced row that doesn't exist is a real proposal being deleted, not a
- * regeneration — a negligible residual the operator would notice directly.
- *
- * Gated strictly by the allow-list — a real agreement is never reset.
- * Best-effort: any failure is swallowed (a demo-reset must never fail the
- * signer's own response). The current signer already has their response (incl.
- * payUrl) before this runs; only the stored record is reset.
- */
-async function maybeResetDemoAgreement(
-	prisma: any,
-	agreementId: string,
-	proposalId: string | null,
-	parties: AgreementParty[],
-): Promise<void> {
-	if (!proposalId) return;
-	try {
-		const rows = await queryRows`
-			SELECT config FROM registry_entries
-			 WHERE type = 'config' AND slug = 'demo-reset-agreements' AND is_active = true
-			 LIMIT 1` as { config: { proposalIds?: string[] } }[];
-		const ids = rows?.[0]?.config?.proposalIds ?? [];
-		if (!Array.isArray(ids) || !ids.includes(proposalId)) return;
-		const reset = parties.map((p) => ({
-			...p,
-			signedAt: null,
-			signature: null,
-			title: null,
-			company: null,
-		}));
-		await prisma.agreements.update({
-			where: { id: agreementId },
-			data: {
-				signature_data: JSON.stringify({ parties: reset }),
-				signed_at: null,
-				signed_by: null,
-				status: "sent",
-			},
-		});
-		getAppLogger().info(`[publicAgreement.sign] demo agreement ${agreementId} auto-reset for re-testing`);
-	} catch {
-		// never fail the signer's response over a demo-reset
-	}
-}
+import {
+	clientIp,
+	computeDocumentHash,
+	originFrom,
+	parseEvidence,
+} from "./agreement-signing-evidence.ts";
+import {
+	connectSignerToCrm,
+	invoicePayUrl,
+	maybeResetDemoAgreement,
+} from "./agreement-sign-side-effects.ts";
 
-/**
- * Connect a captured signer to the CRM — every signable document lands in
- * client_database, the same find-or-create capture path proposals / public-GPT /
- * assessments already use (scoped by organisation_id + primary_email). Also
- * links agreement.contact_id when the agreement wasn't generated from a proposal
- * (contact_id NULL), so a standalone signed doc still connects to the CRM.
- * Best-effort: a CRM write must never fail the signature (the signature is the
- * legal act; CRM connection is bookkeeping).
- */
-async function connectSignerToCrm(
-	prisma: any,
-	agreement: { id: string; organisation_id?: string | null; contact_id?: string | null },
-	email: string,
-	signerName?: string | null,
-	company?: string | null,
-): Promise<void> {
-	const orgId = agreement.organisation_id;
-	if (!orgId || !email || !prisma?.client_database) return;
-	try {
-		const parts = (signerName ?? "").trim().split(/\s+/).filter(Boolean);
-		const firstName = parts[0] ?? "";
-		const lastName = parts.slice(1).join(" ");
-		const existing = await prisma.client_database.findFirst({
-			where: { organisation_id: orgId, primary_email: email },
-			select: { id: true },
-		});
-		let contactId: string | null = null;
-		if (existing) {
-			contactId = existing.id as string;
-			await prisma.client_database.update({
-				where: { id: existing.id },
-				data: {
-					...(firstName ? { first_name: firstName } : {}),
-					...(lastName ? { last_name: lastName } : {}),
-					...(company ? { company_name: company } : {}),
-					last_updated_by: "agreement-sign",
-				},
-			});
-		} else {
-			const created = await prisma.client_database.create({
-				data: {
-					organisation_id: orgId,
-					first_name: firstName,
-					last_name: lastName,
-					primary_email: email,
-					...(company ? { company_name: company } : {}),
-					lead_source: "agreement-sign",
-					data_source: "public-form",
-					referral_source: agreement.id,
-					lifecycle_stage: "lead",
-					created_by: "agreement-sign",
-					last_updated_by: "agreement-sign",
-				},
-				select: { id: true },
-			});
-			contactId = (created?.id as string) ?? null;
-		}
-		if (contactId && !agreement.contact_id) {
-			await prisma.agreements.update({
-				where: { id: agreement.id },
-				data: { contact_id: contactId },
-			});
-		}
-	} catch (e) {
-		getAppLogger().warn(
-			`[publicAgreement.sign] CRM connect failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`,
-		);
-	}
-}
+export { buildCertificateData } from "./agreement-certificate.ts";
+export type { CertificateData, CertificateCopy } from "./agreement-certificate.ts";
 
 interface Context {
 	prisma: any;