@teamscala/service-boot 0.23.284

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

@@ -0,0 +1,865 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Public ORPC procedures for DocuSign-style agreement signing, reached by the
+ * sign-in block's in-document signing blocks over the public HTTP transport
+ * (getOrpcClient().fn.publicAgreement.*). The unguessable agreement id plus an
+ * email that matches one of the agreement's parties IS the gate (no password).
+ *
+ * This is the off-the-shelf path per building-applications: server logic beyond
+ * CRUD is a typed ORPC procedure (the publicAssessment/publicGptSession shape),
+ * NOT a hand-written /api/data/* Hono handler and NOT a loopback fetch to the
+ * service's own ORPC. Writes go through context.prisma inside the handler — the
+ * sanctioned in-handler DB access (orpc-is-the-only-api) — so the audit trigger
+ * sees the ORPC caller context, the same proven path publicGptSession uses.
+ *
+ * Multi-party model: signature_data holds a parties roster (JSON) so one
+ * agreement can require signatures from several parties (e.g. Provider + Client)
+ * 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.
+ */
+
+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 both the
+ *  `publicAgreement.certificate` ORPC and the SSR agreement gate, so the signing
+ *  block receives identical data whether it reads the ORPC response or 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 `publicAgreement.certificate` ORPC and the SSR agreement gate
+ * (`buildSigningSession` in agreement-gate.ts) both call 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 { getPrisma } = await import("@teamscala/db/prisma-registry");
+	const db = getPrisma();
+	const agreement = await db.agreements.findFirst({
+		where: { OR: [{ id }, { page_id: id }] },
+		select: {
+			id: true,
+			name: true,
+			created_at: true,
+			sent_at: true,
+			viewed_at: true,
+			signed_at: true,
+			signature_data: true,
+			signer_email: true,
+			signer_name: true,
+		},
+	});
+	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
+	}
+}
+
+/**
+ * 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)}`,
+		);
+	}
+}
+
+interface Context {
+	prisma: any;
+	headers: Headers;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+}
+
+const pub = os.$context<Context>();
+
+const verifySchema = v.object({
+	agreementId: v.string(),
+	email: v.string(),
+});
+
+const signSchema = v.object({
+	agreementId: v.string(),
+	email: v.string(),
+	signatureData: v.optional(v.string()),
+	signerName: v.optional(v.string()),
+	// Legal signature-block fields, captured in the signing modal.
+	title: v.optional(v.string()),
+	company: v.optional(v.string()),
+});
+
+export const publicAgreementRouter = {
+	// View-gate: confirms an email matches a party on the agreement AND, only on a
+	// match, returns the document content. The content is NOT in the public page
+	// SSR (the public route ships only the SignIn gate block) — the document blocks
+	// live on the agreement's page_id and are served here, gated by the email
+	// match, so an unauthenticated/wrong-email request never receives the bytes.
+	verify: pub.input(verifySchema).handler(async ({ input, context }) => {
+		const agreementId = input.agreementId.trim();
+		const email = input.email.trim().toLowerCase();
+		if (!agreementId || !email) return { matched: false as const };
+
+		const agreement = await context.prisma.agreements.findFirst({
+			where: { id: agreementId },
+			select: {
+				id: true,
+				name: true,
+				signer_email: true,
+				signer_name: true,
+				signed_at: true,
+				signature_data: true,
+			},
+		});
+		if (!agreement) return { matched: false as const };
+
+		const parties = parseParties(agreement.signature_data);
+		if (parties) {
+			const me = parties.find((p) => p.email.trim().toLowerCase() === email);
+			if (!me) return { matched: false as const };
+			return {
+				matched: true,
+				multiParty: true,
+				name: agreement.name,
+				role: me.key,
+				signerName: me.name,
+				partySignedAt: me.signedAt ?? null,
+				allSigned: parties.every((p) => p.signedAt),
+				parties: partySummary(parties),
+				// Signed proof for the page loader: only with this token does the SSR
+				// include the document. The client sets it as a cookie and reloads;
+				// the loader validates it and renders the document server-side.
+				accessToken: signAgreementAccessToken(agreementId, email, Date.now()),
+			};
+		}
+
+		// Legacy single-signer path.
+		const matched =
+			String(agreement.signer_email ?? "")
+				.trim()
+				.toLowerCase() === email;
+		if (!matched) return { matched: false as const };
+		return {
+			matched: true,
+			name: agreement.name,
+			signerName: agreement.signer_name,
+			signedAt: agreement.signed_at,
+			accessToken: signAgreementAccessToken(agreementId, email, Date.now()),
+		};
+	}),
+
+	// Commit the authed party's signature. Returns { ok, parties } so the block
+	// can refresh the roster; on a gate failure returns { ok:false, error } so
+	// the block can show the specific message rather than a generic throw.
+	sign: pub.input(signSchema).handler(async ({ input, context }) => {
+		const log = getAppLogger();
+		const agreementId = input.agreementId.trim();
+		const email = input.email.trim().toLowerCase();
+		if (!agreementId || !email) {
+			return { ok: false as const, error: "agreementId and email are required" };
+		}
+
+		const agreement = await context.prisma.agreements.findFirst({
+			where: { id: agreementId },
+			select: {
+				id: true,
+				organisation_id: true,
+				signer_email: true,
+				signer_name: true,
+				contact_id: true,
+				signed_at: true,
+				signature_data: true,
+				page_id: true,
+				proposal_id: true,
+			},
+		});
+		if (!agreement) return { ok: false as const, error: "Agreement not found" };
+
+		const now = new Date().toISOString();
+
+		try {
+			// Multi-party path: signature_data holds a parties roster.
+			const parties = parseParties(agreement.signature_data);
+			if (parties) {
+				const idx = parties.findIndex(
+					(p) => p.email.trim().toLowerCase() === email,
+				);
+				if (idx < 0) {
+					return {
+						ok: false as const,
+						error: "This email is not a signer on this agreement.",
+					};
+				}
+				if (!parties[idx].signedAt) {
+					parties[idx].signedAt = now;
+					parties[idx].signature = (
+						input.signatureData ?? parties[idx].name
+					).trim();
+					if (input.title != null)
+						parties[idx].title = input.title.trim() || null;
+					if (input.company != null)
+						parties[idx].company = input.company.trim() || null;
+					// Signing-evidence capture (DocuSign-style audit trail): the
+					// signer's IP + device at the moment of signing, plus how they
+					// were authenticated. Stored in signature_data → captured
+					// immutably by audit_trail on this update. The agreement gate
+					// currently authorises by email-match; authMethod becomes "email-otp"
+					// once the gate unifies onto the standard OTP login.
+					// unifies onto the standard OTP login.
+					parties[idx].signedIp = clientIp(context.headers);
+					parties[idx].signedUserAgent =
+						context.headers.get("user-agent") ?? null;
+					parties[idx].authMethod = "email-match";
+				}
+				// EXECUTION vs PAYMENT are separate (agreement-signing.md §2):
+				//  • executed = every party has signed → gates signed_at, signed_by,
+				//    the tamper-evident seal, and the Certificate of Completion. An
+				//    agreement is NOT "complete" until all parties have signed.
+				//  • firePayment = the CLIENT's signature triggers Checkout (operator
+				//    ruling) — the client pays when they sign, even before the provider
+				//    has countersigned. This does NOT mark the document executed.
+				const allSigned = parties.every((p) => p.signedAt);
+				const clientSigned = parties[idx].key === "client";
+				const executed = allSigned;
+				const firePayment = clientSigned;
+				// Tamper-evident seal: at completion, hash the executed document +
+				// signed roster and store it alongside the parties. The verification
+				// surface re-hashes later to prove the document was not altered.
+				let evidence: Record<string, unknown> | undefined;
+				if (executed && agreement.page_id) {
+					try {
+						const doc = await context.prisma.builda_pages.findFirst({
+							where: { id: agreement.page_id },
+							select: { puck_data: true },
+						});
+						evidence = {
+							documentHash: computeDocumentHash(doc?.puck_data ?? null, parties),
+							hashAlgo: "sha256",
+							hashedAt: now,
+						};
+					} catch (e) {
+						// A hashing failure must never block the signature itself.
+						log.warn(
+							`[publicAgreement.sign] document-hash failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`,
+						);
+					}
+				}
+				const data: Record<string, unknown> = {
+					signature_data: JSON.stringify(
+						evidence ? { parties, evidence } : { parties },
+					),
+					viewed_at: now,
+				};
+				if (executed) {
+					data.signed_at = now;
+					data.signed_by = agreement.contact_id ?? null;
+				}
+				const updated = await context.prisma.agreements.update({
+					where: { id: agreementId },
+					data,
+				});
+				// Completion delivery: when THIS signature is the one that fully
+				// executes the agreement (it was not executed before this call),
+				// email every party their executed copy + Certificate of Completion.
+				// Fire-and-forget — the helper is best-effort and self-contained, so
+				// a mail failure never blocks or undoes the signature.
+				if (executed && !agreement.signed_at) {
+					void sendAgreementCompletionEmails(
+						agreementId,
+						originFrom(context.headers),
+					);
+				}
+				// Every captured identity → CRM: connect this signer to client_database.
+				await connectSignerToCrm(
+					context.prisma,
+					agreement,
+					email,
+					parties[idx].name,
+					input.company ?? parties[idx].company,
+				);
+				const fresh = parseParties(updated.signature_data) ?? parties;
+				const payUrl = firePayment
+					? await invoicePayUrl(agreementId, originFrom(context.headers))
+					: null;
+				const result = {
+					ok: true as const,
+					role: parties[idx].key,
+					signedAt: parties[idx].signedAt,
+					allSigned: executed,
+					parties: partySummary(fresh),
+					payUrl,
+				};
+				// Self-resetting demo harness: an allow-listed demo agreement
+				// auto-unsigns once it reaches payment, so the next person gets a
+				// fresh form to test the UI. The current signer's response (above)
+				// still shows their signature + payUrl; only the stored record is
+				// reset. Real agreements are never in the allow-list, so they never
+				// auto-reset. (config: demo-reset-agreements)
+				if (firePayment) {
+					await maybeResetDemoAgreement(
+						context.prisma,
+						agreementId,
+						agreement.proposal_id ?? null,
+						parties,
+					);
+				}
+				return result;
+			}
+
+			// Legacy single-signer path.
+			const signerEmail = String(agreement.signer_email ?? "")
+				.trim()
+				.toLowerCase();
+			if (!signerEmail || signerEmail !== email) {
+				return {
+					ok: false as const,
+					error: "This email does not match the agreement's signer.",
+				};
+			}
+			if (agreement.signed_at) {
+				return {
+					ok: true as const,
+					alreadySigned: true,
+					signedAt: agreement.signed_at,
+					signerName: agreement.signer_name,
+				};
+			}
+			const updated = await context.prisma.agreements.update({
+				where: { id: agreementId },
+				data: {
+					signature_data: input.signatureData ?? agreement.signer_name ?? "",
+					signed_at: now,
+					viewed_at: now,
+					signed_by: agreement.contact_id ?? null,
+					...(input.signerName ? { signer_name: input.signerName } : {}),
+				},
+			});
+			// Every captured identity → CRM: connect this signer to client_database.
+			await connectSignerToCrm(
+				context.prisma,
+				agreement,
+				email,
+				input.signerName ?? agreement.signer_name,
+				input.company,
+			);
+			return {
+				ok: true as const,
+				signedAt: updated.signed_at,
+				signerName: updated.signer_name,
+				payUrl: await invoicePayUrl(agreementId, originFrom(context.headers)),
+			};
+		} catch (err) {
+			log.error(
+				`[publicAgreement.sign] failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return { ok: false as const, error: "Could not submit your signature." };
+		}
+	}),
+
+	// Certificate of Completion — the court-style audit certificate for an
+	// agreement. Delegates to buildCertificateData (the single data home shared
+	// with the SSR agreement gate); the email-must-be-a-party gate lives there,
+	// so signer evidence (IP/device) is never exposed to a non-party. Read-only;
+	// the signing block renders it inline.
+	certificate: pub
+		.input(v.object({ agreementId: v.string(), email: v.string() }))
+		.handler(async ({ input }) =>
+			buildCertificateData(input.agreementId, input.email),
+		),
+
+	// Public tamper-verification: re-hash the currently-stored document + roster
+	// and compare to the sealed hash captured at completion. Returns only
+	// public-safe data (names, roles, signed timestamps, hash match) — never
+	// emails or IPs — so it can back a public "verify this document" page.
+	verifyDocument: pub
+		.input(v.object({ agreementId: v.string() }))
+		.handler(async ({ input }) => {
+			const agreementId = input.agreementId.trim();
+			if (!agreementId) return { ok: false as const };
+			// Public verification is intentionally unscoped: anyone holding the id
+			// confirms authenticity and gets only public-safe data back. The caller
+			// is unauthenticated (no access cookie), so context.prisma's RLS would
+			// hide the row — use the raw registry prisma, the same bypass the gate's
+			// signer-email resolver uses.
+			const { getPrisma } = await import("@teamscala/db/prisma-registry");
+			const db = getPrisma();
+			const agreement = await db.agreements.findFirst({
+				where: { OR: [{ id: agreementId }, { page_id: agreementId }] },
+				select: {
+					id: true,
+					name: true,
+					signed_at: true,
+					signature_data: true,
+					page_id: true,
+				},
+			});
+			if (!agreement) return { ok: false as const };
+			const parties = parseParties(agreement.signature_data);
+			const evidence = parseEvidence(agreement.signature_data);
+			const complete =
+				!!agreement.signed_at || (parties?.every((p) => p.signedAt) ?? false);
+			let recomputedHash: string | null = null;
+			if (evidence?.documentHash && parties && agreement.page_id) {
+				const doc = await db.builda_pages.findFirst({
+					where: { id: agreement.page_id },
+					select: { puck_data: true },
+				});
+				recomputedHash = computeDocumentHash(doc?.puck_data ?? null, parties);
+			}
+			return {
+				ok: true as const,
+				envelopeId: agreement.id,
+				documentName: agreement.name,
+				complete,
+				signedAt: agreement.signed_at?.toISOString() ?? null,
+				sealedHash: evidence?.documentHash ?? null,
+				recomputedHash,
+				valid:
+					!!evidence?.documentHash && recomputedHash === evidence.documentHash,
+				parties: parties
+					? parties.map((p) => ({
+							role: p.key,
+							name: p.name,
+							signedAt: p.signedAt,
+						}))
+					: [],
+			};
+		}),
+};