@teamscala/service-boot 0.23.479 → 0.23.492

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

@@ -1,407 +0,0 @@
-/**
- * @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).
- *
- * Off-the-shelf path (building-applications): typed ORPC procedure, not a
- * hand-written Hono handler; writes go through context.prisma inside the
- * handler (orpc-is-the-only-api) so the audit trigger sees the ORPC caller.
- * ONE signing model, the DocuSign recipients shape: signature_data holds a
- * parties roster (JSON), each party is gated by its own email, and the
- * agreement completes only when every party has signed. A single signer is a
- * roster of one -- there is no separate single-signer path.
- *
- * A legacy signer_email/signer_name fallback used to sit alongside this and was
- * deleted 2026-09-03: measured across every agreement on the platform, 13 of 14
- * carried a roster and ZERO used the fallback (the 14th was an unsent draft with
- * no signature_data at all). It was never exercised, and it was not inert -- its
- * write put a BARE STRING into signature_data, which would have destroyed the
- * roster of any agreement that reached it. Keeping it also meant every change to
- * this handler had to be made twice: the Prisma 8 timestamptz fix that made
- * signing work at all had to be applied to both branches of one function.
- *
- * This module holds the three procedures (verify/sign/verifyDocument); the
- * supporting machinery lives as siblings (agreement-signing-evidence,
- * agreement-certificate, agreement-sign-side-effects) — split when the parent
- * held them all at 853 lines.
- */
-
-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 { recordEvent } from "@teamscala/event-log/record-event";
-import type { PrismaClient } from "@teamscala/db/client";
-import { signAgreementAccessToken } from "@teamscala/document-signing/agreement-access-token";
-import {
-	parseAgreementParties as parseParties,
-	toPublicParties as partySummary,
-} from "@teamscala/document-signing/agreement-parties";
-import { sendAgreementCompletionEmails } from "./agreement-completion-email.ts";
-import {
-	clientIp,
-	computeDocumentHash,
-	originFrom,
-	parseEvidence,
-} from "./agreement-signing-evidence.ts";
-import {
-	connectSignerToCrm,
-	invoicePayUrl,
-	maybeResetDemoAgreement,
-} from "./agreement-sign-side-effects.ts";
-
-export { buildCertificateData } from "./agreement-certificate.ts";
-export type { CertificateData, CertificateCopy } from "./agreement-certificate.ts";
-
-interface Context {
-	prisma: PrismaClient;
-	headers: Headers;
-	resolveUser?: (headers: Headers, prisma: PrismaClient) => Promise<unknown>;
-}
-
-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()),
-			};
-		}
-
-		// No roster means the agreement was never prepared for signing. It is
-		// not viewable, and it is certainly not signable.
-		return { matched: false as const };
-	}),
-
-	// 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" };
-
-		// TWO representations, deliberately, because they have two consumers.
-		//
-		// `now` is an ISO STRING and belongs in the parties roster, which is
-		// serialised to JSON in signature_data — a Temporal.Instant would
-		// stringify into that JSON as an object.
-		//
-		// `nowInstant` is what the timestamptz COLUMNS take. Under Prisma 8 the
-		// timestamptz codec ('pg/timestamptz-temporal@1') accepts a
-		// Temporal.Instant and NOTHING ELSE. Measured against the live service:
-		// a string gives "received a string", a Date gives "received a Date",
-		// and only Temporal.Instant writes. Passing `now` therefore threw on
-		// EVERY signature, and the handler's catch reported the generic "Could
-		// not submit your signature." -- so signing was impossible for every
-		// signer with nothing naming the cause.
-		//
-		// The cast is load-bearing and is NOT laziness: the generated Prisma
-		// types declare these fields `string | Date` and reject Instant, so the
-		// client's TYPES and its RUNTIME CODEC disagree. Following the types
-		// produces code that compiles and always throws, which is exactly how
-		// this shipped. The runtime is the authority here; the generated types
-		// are the defect, and they are the thing to fix upstream.
-		const now = new Date().toISOString();
-		const nowInstant = Temporal.Now.instant() as unknown as Date;
-
-		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: nowInstant,
-				};
-				if (executed) {
-					data.signed_at = nowInstant;
-					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;
-			}
-
-			// An agreement with no roster was never prepared for signing.
-			// Refuse rather than invent a signer.
-			return {
-				ok: false as const,
-				error: "This agreement has no signers recorded and cannot be signed.",
-			};
-		} catch (err) {
-			const detail = err instanceof Error ? err.message : String(err);
-			log.error(`[publicAgreement.sign] failed: ${detail}`);
-			// A LOG LINE IS NOT A RECORD. Measured 2026-09-03: signing was broken
-			// for every signer for hours -- first a 404 on the procedure, then a
-			// Prisma 8 codec rejecting the timestamp write -- and error_logs held
-			// ZERO rows the whole time. The page returned 200, the service was
-			// running, the deploy was green, and the signer saw only "Could not
-			// submit your signature.", which reads as transient and invites a
-			// retry that fails identically. The failure was discovered by a human
-			// being unable to sign, which is the same shape as
-			// page-server.render.failed above and takes the same cure: emit a
-			// durable event so a surface can answer "is signing failing" without
-			// somebody attempting a signature.
-			//
-			// Fire-and-forget and last: telemetry may never change what the signer
-			// is served, and this path is already handling a failure
-			// (observability-is-passive). The agreement id and the signer role
-			// make a recorded event lead to the specific failure.
-			recordEvent({
-				kind: "agreement.sign.failed",
-				payload: {
-					agreementId,
-					error: detail.slice(0, 500),
-					errorName: err instanceof Error ? err.name : "unknown",
-				},
-			});
-			return { ok: false as const, error: "Could not submit your signature." };
-		}
-	}),
-
-	// 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 [agreement] = await queryRows<
-				{
-					id: string;
-					name: string;
-					signed_at: Date | null;
-					signature_data: unknown;
-					page_id: string | null;
-				}
-			>`
-				SELECT id, name, signed_at, signature_data, page_id
-				  FROM agreements
-				 WHERE (id = ${agreementId} OR page_id = ${agreementId})
-				 LIMIT 1`;
-			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 queryRows<{ puck_data: unknown }>`
-					SELECT puck_data FROM builda_pages WHERE id = ${agreement.page_id} LIMIT 1`;
-				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,
-						}))
-					: [],
-			};
-		}),
-};