@teamscala/service-boot 0.23.414 → 0.23.415

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.414",
+  "version": "0.23.415",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -1133,6 +1133,54 @@
     "./ws-boot-self-test.ts": {
       "types": "./src/ws-boot-self-test.d.ts",
       "default": "./src/ws-boot-self-test.ts"
+    },
+    "./agreement-gate/settings": {
+      "types": "./src/agreement-gate/settings.d.ts",
+      "default": "./src/agreement-gate/settings.ts"
+    },
+    "./agreement-gate/settings.ts": {
+      "types": "./src/agreement-gate/settings.d.ts",
+      "default": "./src/agreement-gate/settings.ts"
+    },
+    "./agreement-gate/agreement-lookup": {
+      "types": "./src/agreement-gate/agreement-lookup.d.ts",
+      "default": "./src/agreement-gate/agreement-lookup.ts"
+    },
+    "./agreement-gate/agreement-lookup.ts": {
+      "types": "./src/agreement-gate/agreement-lookup.d.ts",
+      "default": "./src/agreement-gate/agreement-lookup.ts"
+    },
+    "./agreement-gate/signing-session": {
+      "types": "./src/agreement-gate/signing-session.d.ts",
+      "default": "./src/agreement-gate/signing-session.ts"
+    },
+    "./agreement-gate/signing-session.ts": {
+      "types": "./src/agreement-gate/signing-session.d.ts",
+      "default": "./src/agreement-gate/signing-session.ts"
+    },
+    "./agreement-gate/placeholder-strip": {
+      "types": "./src/agreement-gate/placeholder-strip.d.ts",
+      "default": "./src/agreement-gate/placeholder-strip.ts"
+    },
+    "./agreement-gate/placeholder-strip.ts": {
+      "types": "./src/agreement-gate/placeholder-strip.d.ts",
+      "default": "./src/agreement-gate/placeholder-strip.ts"
+    },
+    "./agreement-gate/signing-shell": {
+      "types": "./src/agreement-gate/signing-shell.d.ts",
+      "default": "./src/agreement-gate/signing-shell.ts"
+    },
+    "./agreement-gate/signing-shell.ts": {
+      "types": "./src/agreement-gate/signing-shell.d.ts",
+      "default": "./src/agreement-gate/signing-shell.ts"
+    },
+    "./agreement-gate/authorized-emails": {
+      "types": "./src/agreement-gate/authorized-emails.d.ts",
+      "default": "./src/agreement-gate/authorized-emails.ts"
+    },
+    "./agreement-gate/authorized-emails.ts": {
+      "types": "./src/agreement-gate/authorized-emails.d.ts",
+      "default": "./src/agreement-gate/authorized-emails.ts"
     }
   },
   "repository": "https://github.com/teamgbg/service-boot",

package/src/agreement-gate/agreement-lookup.ts

@@ -0,0 +1,127 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Agreement lookups + the gate's resolution caches: the page→agreement
+ * association cache, the owning/party org member-directory caches, and the
+ * event-driven invalidation (LISTEN registry_config_changed) that clears them.
+ *
+ * Split out of agreement-gate.ts (909 lines) — byte-for-byte move; import
+ * paths adjusted only.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { queryRows } from "@teamscala/db/query-rows";
+import { createCache } from "@teamscala/cache/create-cache";
+import { createNotifyListener, getDirectDatabaseUrl } from "@teamscala/db/notify-listener/index";
+import { getServerClient } from "../page-server-orpc/server-client.ts";
+
+export async function findFirstAgreement<T>(input: {
+	where: Record<string, unknown>;
+	select: Record<string, boolean>;
+}): Promise<T | null> {
+	const client = getServerClient() as unknown as {
+		agreements: { findFirst: (args: typeof input) => Promise<T | null> };
+	};
+	return client.agreements.findFirst(input);
+}
+
+/**
+ * Cache for the page→agreement association (new-flow pages that have no
+ * pre-placed gate block). The association changes rarely (only when a new
+ * agreement is created or a page is rebound), so a 30s TTL avoids a DB query
+ * per request while staying fresh enough for just-created agreements to appear.
+ * Negative results are cached too (id="") so non-agreement pages never re-query.
+ */
+export const pageAgreementCache = createCache<{ id: string; name: string }>(
+	"agreement-gate:page-association",
+	{ maxSize: 256, ttlMs: 30_000 },
+);
+
+/**
+ * Cache for the owning org's member directory (org id → lowercased email → name),
+ * used to grant VIEW-ONLY access to an agreement to any member of the org that
+ * owns it (signing stays roster-bound). Membership changes on human timescales,
+ * so a 30s TTL keeps the per-request authorize cheap (hot-path-resolutions-are-cached).
+ */
+export const orgMemberCache = createCache<Map<string, string>>(
+	"agreement-gate:org-members",
+	{ maxSize: 256, ttlMs: 30_000 },
+);
+
+/**
+ * The owning org's member directory: lowercased email → display name, for every
+ * member of `organisationId`. Empty when the org is unknown or has no members.
+ *
+ * Resolved via a parameterized raw join over better_auth_member + "user" rather
+ * rather than a service-local Prisma `member` model: `member` is a shared
+ * @@map'd Prisma model, and each
+ * service's per-service client is generated by live DB introspection from only
+ * the tables its service_schema declares — so that model is undefined
+ * on a service (scala-sign, scala-proposals) that doesn't list better_auth_member.
+ * A read-only raw query needs no model declaration and works on every client,
+ * which is what makes org-member VIEW access actually resolve (the typed access
+ * silently crashed → caught → empty directory → org members wrongly challenged).
+ */
+export async function resolveOrgMemberDirectory(
+	organisationId: string | null,
+): Promise<Map<string, string>> {
+	if (!organisationId) return new Map();
+	const cached = orgMemberCache.get(organisationId);
+	if (cached !== undefined) return cached;
+	const directory = new Map<string, string>();
+	try {
+		const rows = await queryRows`
+			SELECT u.email AS email, u.name AS name
+			FROM better_auth_member m
+			JOIN "user" u ON u.id = m.user_id
+			WHERE m.organization_id = ${organisationId}
+		` as
+			Array<{ email: string | null; name: string | null }>
+		;
+		for (const r of rows) {
+			const email = typeof r.email === "string" ? r.email.trim().toLowerCase() : "";
+			if (email) directory.set(email, String(r.name ?? r.email));
+		}
+		orgMemberCache.set(organisationId, directory);
+		return directory;
+	} catch (err) {
+		getAppLogger().error(
+			`[agreement-gate] org-member resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return directory;
+	}
+}
+
+/**
+ * The combined member directory for EVERY org an agreement's parties represent
+ * (each party's `organisationId`) plus the agreement's owning org. Any of these
+ * members may VIEW the agreement; signing stays restricted to the designated
+ * signer (the party email). Usually 1 org (one of our orgs + an external party),
+ * so the loop is over a 1-2 element set, each entry cached.
+ */
+export async function resolveAgreementViewerDirectory(
+	orgIds: Iterable<string | null | undefined>,
+): Promise<Map<string, string>> {
+	const out = new Map<string, string>();
+	const unique = new Set(
+		[...orgIds].filter((id): id is string => typeof id === "string" && id.length > 0),
+	);
+	for (const orgId of unique) {
+		const dir = await resolveOrgMemberDirectory(orgId);
+		for (const [email, name] of dir) if (!out.has(email)) out.set(email, name);
+	}
+	return out;
+}
+
+// Event-driven invalidation via LISTEN on registry_config_changed
+{
+	const _url = getDirectDatabaseUrl();
+	if (_url) {
+		createNotifyListener(_url).listen("registry_config_changed", () => {
+			pageAgreementCache.clear();
+			orgMemberCache.clear();
+		}).catch((e: unknown) => console.error("[cache-invalidation] subscribe failed: " + e));
+	}
+}

package/src/agreement-gate/authorized-emails.ts

@@ -0,0 +1,85 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The agreement's authorized email sets: the signer roster (who may sign) and
+ * the roster ∪ owning/party-org members (who may view past the gate).
+ *
+ * Split out of agreement-gate.ts (909 lines) — byte-for-byte move; import
+ * paths adjusted only.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { parseAgreementParties } from "@teamscala/document-signing/agreement-parties";
+import { findFirstAgreement, resolveAgreementViewerDirectory } from "./agreement-lookup.ts";
+
+/** The agreement's authorized email set (its signer roster) for the access endpoint. */
+export async function resolveAgreementSignerEmails(
+	agreementId: string,
+): Promise<Set<string>> {
+	const emails = new Set<string>();
+	try {
+		const agreement = await findFirstAgreement<{
+			signer_email: string | null;
+			signature_data: unknown;
+		}>({
+			where: { id: agreementId },
+			select: { signer_email: true, signature_data: true },
+		});
+		if (!agreement) return emails;
+		const parties = parseAgreementParties(agreement.signature_data);
+		if (parties) {
+			for (const p of parties) {
+				if (p.email) emails.add(p.email.trim().toLowerCase());
+			}
+		}
+		if (agreement.signer_email) {
+			emails.add(String(agreement.signer_email).trim().toLowerCase());
+		}
+		return emails;
+	} catch (err) {
+		getAppLogger().error(
+			`[agreement-gate] signer-email resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return emails;
+	}
+}
+
+/**
+ * Every email allowed PAST the gate: the signer roster (who may sign) UNION every
+ * member of the owning org (who may VIEW). Signing authority stays roster-only —
+ * buildSigningSession gives a non-party org member a view-only session. This is
+ * what the access endpoint and session-authorize check.
+ */
+export async function resolveAgreementAuthorizedEmails(
+	agreementId: string,
+): Promise<Set<string>> {
+	const emails = await resolveAgreementSignerEmails(agreementId);
+	try {
+		const agreement = await findFirstAgreement<{
+			organisation_id: string | null;
+			signature_data: unknown;
+		}>({
+			where: { id: agreementId },
+			select: { organisation_id: true, signature_data: true },
+		});
+		// View-orgs = each party's organisationId (self-describing model) ∪ the
+		// agreement's owning org (also included for agreements that predate
+		// per-party org). Members of any of these may view; signing stays designated-signer-only.
+		const orgIds = new Set<string | null | undefined>();
+		if (typeof agreement?.organisation_id === "string") {
+			orgIds.add(agreement.organisation_id);
+		}
+		for (const p of parseAgreementParties(agreement?.signature_data) ?? []) {
+			if (p.organisationId) orgIds.add(p.organisationId);
+		}
+		const directory = await resolveAgreementViewerDirectory(orgIds);
+		for (const email of directory.keys()) emails.add(email);
+	} catch (err) {
+		getAppLogger().error(
+			`[agreement-gate] authorized-emails resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+	return emails;
+}

package/src/agreement-gate/placeholder-strip.ts

@@ -0,0 +1,42 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The withholding transform: drop blocks whose own text still carries an
+ * {{agreement.*}} token, recursively, so unauthed viewers never see raw
+ * placeholders.
+ *
+ * Split out of agreement-gate.ts (909 lines) — byte-for-byte move; import
+ * paths adjusted only.
+ */
+
+import type { ContentBlock } from "./signing-session.ts";
+
+/** True if any of the block's OWN string props carries an {{agreement.*}} token. */
+function blockHasAgreementPlaceholder(block: ContentBlock): boolean {
+	const props = block.props;
+	if (!props) return false;
+	for (const propVal of Object.values(props)) {
+		if (typeof propVal === "string" && /\{\{\s*agreement\./.test(propVal)) return true;
+	}
+	return false;
+}
+
+/** Drop blocks whose own text still holds an {{agreement.*}} token, recursively. */
+export function stripAgreementPlaceholderBlocks(content: ContentBlock[]): ContentBlock[] {
+	const out: ContentBlock[] = [];
+	for (const block of content) {
+		if (blockHasAgreementPlaceholder(block)) continue;
+		const props = block.props;
+		if (props) {
+			for (const [k, propVal] of Object.entries(props)) {
+				if (Array.isArray(propVal)) {
+					props[k] = stripAgreementPlaceholderBlocks(propVal as ContentBlock[]);
+				}
+			}
+		}
+		out.push(block);
+	}
+	return out;
+}

package/src/agreement-gate/settings.ts

@@ -0,0 +1,59 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * DB-driven display + behaviour settings for the AGREEMENT content gate
+ * (config/content-gate-agreement), plus its cookie name.
+ *
+ * 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";
+
+export const AG_COOKIE = "ag_token";
+
+/**
+ * Agreement gate display + behaviour, DB-driven (config/content-gate-agreement),
+ * never hardcoded — mirrors proposal-gate's loadProposalGateSettings. requireOtp
+ * is the per-gate OTP switch (agreements default ON: a signer verifies identity
+ * before signing). title is the fallback used when no agreement name resolves. A
+ * missing/invalid row falls back to these defaults so the gate UI ALWAYS renders.
+ */
+export interface AgreementGateSettings {
+	title: string;
+	subtitle: string;
+	submitLabel: string;
+	requireOtp: boolean;
+}
+
+export const AGREEMENT_GATE_DEFAULTS: AgreementGateSettings = {
+	title: "Private document",
+	subtitle: "Verify your email to view and sign this document.",
+	submitLabel: "Access document",
+	requireOtp: true,
+};
+
+const AgreementGateSettingsSchema = v.object({
+	title: v.optional(v.string(), AGREEMENT_GATE_DEFAULTS.title),
+	subtitle: v.optional(v.string(), AGREEMENT_GATE_DEFAULTS.subtitle),
+	submitLabel: v.optional(v.string(), AGREEMENT_GATE_DEFAULTS.submitLabel),
+	requireOtp: v.optional(v.boolean(), AGREEMENT_GATE_DEFAULTS.requireOtp),
+});
+
+/** Gate copy/behaviour, or null when the config row is absent/broken. Null is
+ *  the absent signal — callers default explicitly so a missing row neither 500s
+ *  the page nor masks as a populated value (protective-layers-fail-explicitly). */
+export async function loadAgreementGateSettings(): Promise<AgreementGateSettings | null> {
+	try {
+		return await loadRegistryConfig(
+			"config",
+			"content-gate-agreement",
+			AgreementGateSettingsSchema,
+		);
+	} catch {
+		return null;
+	}
+}

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;
+}