@teamscala/service-boot 0.23.284

package/src/asset-cache-key.ts

@@ -0,0 +1,59 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ETag derivation for the asset proxy that incorporates the negotiated
+ * image format so per-Accept variants cache independently.
+ */
+
+const SKIP_FORMATS = new Set(["webp", "avif", "gif", "svg", "ico"]);
+
+export type TargetFormat =
+	| "webp"
+	| "avif"
+	| "jpeg"
+	| "png"
+	| "gif"
+	| "svg"
+	| "ico"
+	| "original";
+
+export function negotiateFormat(
+	acceptHeader: string | null,
+	storedContentType: string,
+): TargetFormat {
+	const stored = contentTypeToFormat(storedContentType);
+
+	if (SKIP_FORMATS.has(stored)) return stored;
+
+	const accept = (acceptHeader || "").toLowerCase();
+
+	if (accept.includes("image/avif") && !accept.includes("image/avif;q=0"))
+		return "avif";
+	if (accept.includes("image/webp") && !accept.includes("image/webp;q=0"))
+		return "webp";
+
+	return stored;
+}
+
+export function buildEtag(baseEtag: string, format: TargetFormat): string {
+	const bare = baseEtag.replace(/"/g, "");
+	return `"${bare}-${format}"`;
+}
+
+function contentTypeToFormat(contentType: string): TargetFormat {
+	const ct = contentType.toLowerCase().split(";")[0]?.trim();
+	const map: Record<string, TargetFormat> = {
+		"image/webp": "webp",
+		"image/avif": "avif",
+		"image/gif": "gif",
+		"image/svg+xml": "svg",
+		"image/x-icon": "ico",
+		"image/vnd.microsoft.icon": "ico",
+		"image/png": "png",
+		"image/jpeg": "jpeg",
+		"image/jpg": "jpeg",
+	};
+	return map[ct] ?? "original";
+}

package/src/asset-optimize.ts

@@ -0,0 +1,93 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * On-the-fly image optimisation for the asset proxy. Converts stored
+ * PNG/JPEG to WebP or AVIF when the browser signals support, using
+ * @teamscala/image-optimizer's compressImage primitive. Returns null
+ * on failure so the caller can fall back to the original stream.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { TargetFormat } from "./asset-cache-key.ts";
+
+export interface OptimizeResult {
+	data: Buffer;
+	format: string;
+	processedSize: number;
+}
+
+// Dynamic-imported optional dependency. service-runtime is the universal
+// boot pipeline used by every service; only the small subset of services
+// that actually serve images via the asset proxy need image-optimizer.
+// Static imports here would force every service tree (loga, agents,
+// mcp-gateway, etc.) to install image-optimizer as a transitive — a
+// real-world incident in 2026-05 (loga unable to boot because its node
+// tree was missing @teamscala/image-optimizer/config). Lazy + try/catch
+// keeps image-optimizer optional: services that have it use it, services
+// that don't get a null OptimizeResult and the asset proxy serves the
+// original buffer.
+
+export async function optimizeImage(
+	buffer: Buffer,
+	targetFormat: TargetFormat,
+): Promise<OptimizeResult | null> {
+	if (targetFormat !== "webp" && targetFormat !== "avif") return null;
+
+	let getConfig: () => {
+		defaultQuality: number;
+		defaultMaxWidth: number;
+		defaultMaxHeight: number;
+	};
+	let compressImage: (
+		buf: Buffer,
+		opts: {
+			format: TargetFormat;
+			lossless: boolean;
+			quality: number;
+			maxWidth: number;
+			maxHeight: number;
+		},
+	) => Promise<{ data: Buffer; format: string; processedSize: number }>;
+	// Build specifiers via template literal so the package-json codegen
+	// walker (which captures literal `import("...")` strings) doesn't add
+	// image-optimizer to service-runtime's static deps.
+	const pkg = "@teamscala/image-optimizer";
+	try {
+		const configMod = await import(`${pkg}/config`);
+		const opsMod = await import(`${pkg}/image-operations`);
+		getConfig = configMod.getConfig;
+		compressImage = opsMod.compressImage;
+	} catch {
+		// image-optimizer not installed in this service tree — caller falls
+		// back to serving the original buffer.
+		return null;
+	}
+
+	const cfg = getConfig();
+
+	try {
+		const result = await compressImage(buffer, {
+			format: targetFormat,
+			lossless: false,
+			quality: cfg.defaultQuality,
+			maxWidth: cfg.defaultMaxWidth,
+			maxHeight: cfg.defaultMaxHeight,
+		});
+
+		return {
+			data: result.data,
+			format: result.format,
+			processedSize: result.processedSize,
+		};
+	} catch (err) {
+		getAppLogger().error(
+			"[asset-proxy] image optimisation failed, serving original",
+			{
+				error: err,
+			},
+		);
+		return null;
+	}
+}

package/src/asset-proxy.ts

@@ -0,0 +1,148 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Same-origin S3 asset proxy with on-the-fly image optimisation.
+ * Streams objects from the configured S3 bucket, converting PNG/JPEG
+ * to WebP/AVIF when the browser declares support via Accept header.
+ * Returns 404 for missing keys, 502 for S3 failures. Never redirects.
+ */
+
+import { getClient } from "@teamscala/aws/create/client/get-client";
+import {
+	buildEtag,
+	negotiateFormat,
+	type TargetFormat,
+} from "./asset-cache-key.ts";
+import { optimizeImage } from "./asset-optimize.ts";
+import { renderSocialCard } from "./asset-social-card.ts";
+
+const CACHE_HEADERS = {
+	"Cache-Control": "public, max-age=31536000, immutable",
+	Vary: "Accept",
+} as const;
+
+export async function handleAssetProxy(req: Request): Promise<Response> {
+	const url = new URL(req.url);
+	const prefix = "/api/assets/";
+	if (!url.pathname.startsWith(prefix)) {
+		return new Response("Not Found", { status: 404 });
+	}
+
+	const key = decodeURIComponent(url.pathname.slice(prefix.length));
+	if (!key) {
+		return new Response("Not Found", { status: 404 });
+	}
+
+	const s3 = await getClient();
+	if (!s3) {
+		return new Response("", { status: 502 });
+	}
+
+	const file = s3.file(key);
+
+	let stats: Awaited<ReturnType<typeof file.stat>>;
+	try {
+		stats = await file.stat();
+	} catch {
+		return new Response("Not Found", { status: 404 });
+	}
+
+	const baseEtag = stats.etag || `"${key}"`;
+	const contentType = stats.type || file.type || "application/octet-stream";
+	const ogRequested = url.searchParams.get("og") === "1";
+	const targetFormat: TargetFormat = ogRequested
+		? "jpeg"
+		: negotiateFormat(req.headers.get("Accept"), contentType);
+	const baseFormatTag = buildEtag(baseEtag, targetFormat);
+	const etag = ogRequested
+		? `${baseFormatTag.slice(0, -1)}-og"`
+		: baseFormatTag;
+
+	const ifNoneMatch = req.headers.get("If-None-Match");
+	if (ifNoneMatch && ifNoneMatch === etag) {
+		return new Response(null, {
+			status: 304,
+			headers: { ETag: etag, ...CACHE_HEADERS },
+		});
+	}
+
+	if (ogRequested) {
+		try {
+			const buffer = Buffer.from(await file.arrayBuffer());
+			const result = await renderSocialCard(buffer);
+
+			if (result) {
+				return new Response(new Uint8Array(result.data), {
+					status: 200,
+					headers: {
+						"Content-Type": "image/jpeg",
+						"Content-Length": String(result.processedSize),
+						ETag: etag,
+						...CACHE_HEADERS,
+					},
+				});
+			}
+		} catch {
+			// fall through to pass-through
+		}
+	}
+
+	const stored = contentTypeToFormat(contentType);
+	const shouldOptimize = targetFormat === "webp" || targetFormat === "avif";
+	const needsTransform = shouldOptimize && stored !== targetFormat;
+
+	if (needsTransform) {
+		try {
+			const buffer = Buffer.from(await file.arrayBuffer());
+			const result = await optimizeImage(buffer, targetFormat as TargetFormat);
+
+			if (result) {
+				return new Response(new Uint8Array(result.data), {
+					status: 200,
+					headers: {
+						"Content-Type": `image/${result.format}`,
+						"Content-Length": String(result.processedSize),
+						ETag: etag,
+						...CACHE_HEADERS,
+					},
+				});
+			}
+		} catch {
+			// fall through to pass-through
+		}
+	}
+
+	let body: ReadableStream<Uint8Array<ArrayBuffer>>;
+	try {
+		body = file.stream();
+	} catch {
+		return new Response("", { status: 502 });
+	}
+
+	return new Response(body, {
+		status: 200,
+		headers: {
+			"Content-Type": contentType,
+			ETag: etag,
+			...CACHE_HEADERS,
+		},
+	});
+}
+
+function contentTypeToFormat(contentType: string): string {
+	const ct = contentType.toLowerCase().split(";")[0]?.trim();
+	const map: Record<string, string> = {
+		"image/webp": "webp",
+		"image/avif": "avif",
+		"image/gif": "gif",
+		"image/svg+xml": "svg",
+		"image/x-icon": "ico",
+		"image/vnd.microsoft.icon": "ico",
+		"image/png": "png",
+		"image/jpeg": "jpeg",
+		"image/jpg": "jpeg",
+	};
+	return map[ct] || "original";
+}

package/src/asset-social-card.ts

@@ -0,0 +1,58 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Dynamic-import wrapper around image-optimizer's in-process sharp
+ * social-card op. Mirrors asset-optimize.ts's optional-dependency shape:
+ * services without image-optimizer installed transparently get null and
+ * fall back to the raw asset stream. In-process (not HTTP) because the
+ * og:image transform is a cold path per shared link — no auth handshake,
+ * no per-consumer service config.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+export interface SocialCardOutcome {
+	data: Buffer;
+	processedSize: number;
+}
+
+export async function renderSocialCard(
+	buffer: Buffer,
+): Promise<SocialCardOutcome | null> {
+	const pkg = "@teamscala/image-optimizer";
+
+	let socialCardImage: (
+		buf: Buffer,
+		opts?: {
+			width?: number;
+			height?: number;
+			quality?: number;
+			padding?: number;
+		},
+	) => Promise<{ data: Buffer; processedSize: number }>;
+
+	try {
+		const mod = await import(`${pkg}/social-card-op`);
+		socialCardImage = mod.socialCardImage;
+	} catch {
+		return null;
+	}
+
+	try {
+		const result = await socialCardImage(buffer);
+		return {
+			data: result.data,
+			processedSize: result.processedSize,
+		};
+	} catch (err) {
+		getAppLogger().error(
+			"[asset-proxy] social-card render failed, serving original",
+			{
+				error: err,
+			},
+		);
+		return null;
+	}
+}

package/src/attach-agreement-magic.ts

@@ -0,0 +1,62 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The agreement MAGIC-LINK endpoint. A recipient who clicks an emailed
+ * "Review & sign" link — which carries a pre-authorised, signed ag_token for
+ * THEIR party — lands here: the token is verified for the agreement, the
+ * ag_token cookie is set on the shared parent domain, and the browser is
+ * 302-redirected straight into the signing page. No email-entry gate, no OTP —
+ * "came from our email" IS the proof of identity, exactly like the
+ * proposal-accept hand-off (attach-proposal-accept.ts).
+ *
+ * The token is the same HMAC ag_token the gate verifies (30-min TTL, scoped to
+ * {agreementId, email}); an invalid/expired/forged token sets no cookie and the
+ * destination page simply shows the normal email gate. GET so it is a plain
+ * clickable link in an email.
+ */
+
+import type { Hono } from "hono";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { verifyAgreementAccessToken } from "@teamscala/document-signing/agreement-access-token";
+import { agTtlMs } from "./gate-ttls.ts";
+import { getCookieDomain } from "@teamscala/db/registry/cookie-domain";
+
+const AG_COOKIE = "ag_token";
+
+export async function attachAgreementMagic(
+	app: Hono,
+	serviceSlug: string,
+): Promise<void> {
+	const log = getAppLogger();
+
+	app.get("/api/agreement-magic", async (c) => {
+		const token = c.req.query("t") ?? "";
+		const agreementId = c.req.query("a") ?? "";
+		const toRaw = c.req.query("to") ?? "/";
+		// Same-origin path only — never an open redirect.
+		const dest =
+			toRaw.startsWith("/") && !toRaw.startsWith("//") ? toRaw : "/";
+
+		// Verify before trusting. Invalid/expired/forged → no cookie; the
+		// destination page falls through to its normal email gate.
+		const email = verifyAgreementAccessToken(token, agreementId, Date.now());
+		if (email) {
+			const maxAge = Math.floor(agTtlMs() / 1000);
+			const domain = await getCookieDomain();
+			c.header(
+				"Set-Cookie",
+				`${AG_COOKIE}=${encodeURIComponent(token)}; Domain=${domain}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,
+			);
+			log.info(
+				`[agreement-magic] ${agreementId} → authorised ${email}; redirecting to ${dest}`,
+			);
+		}
+		return c.redirect(dest, 302);
+	});
+
+	log.info(
+		`[scala-install:${serviceSlug}] agreement magic-link endpoint mounted: /api/agreement-magic`,
+	);
+}

package/src/attach-portal-members.ts

@@ -0,0 +1,107 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Portal-secured member directory endpoint. Resolves members of an org via a
+ * parameterized raw join over better_auth_member + "user" — NOT the typed
+ * `member` ORPC model, which is deliberately omitted from the portal's
+ * service_schema (security: the raw table is not exposed as a typed CRUD
+ * surface). Mirrors the agreement-gate.ts:109-150 precedent.
+ *
+ * The portal's auth middleware (better-auth-cookie) gates the endpoint — only
+ * authenticated users can call it. The orgId comes from the caller's context
+ * (the portal resolves it from the session + passes it).
+ *
+ * Endpoint: GET /api/portal/members?orgId=<uuid>
+ *   - orgId omitted: super-admin all-orgs mode (returns every member across
+ *     all orgs, strictly gated to super-admin via getSession; used by the
+ *     "View As" impersonation dropdown).
+ * Response: { members: Array<{ id, user_id, organization_id, role, email, name, image }> }
+ */
+
+import type { Hono } from "hono";
+import { getSession } from "@teamscala/auth/get-session";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { queryRows } from "@teamscala/db/query-rows";
+
+export async function attachPortalMembers(app: Hono): Promise<void> {
+	const log = getAppLogger();
+
+	app.get("/api/portal/members", async (c) => {
+		const orgId = c.req.query("orgId");
+
+		// No orgId = super-admin all-orgs mode. The "View As" impersonation
+		// dropdown requests every member across all orgs so a super-admin can
+		// impersonate anyone; the client omits orgId for super-admins
+		// (useLeftMenuBarSession). Gate strictly to super-admin — any other
+		// caller without an orgId is forbidden.
+		if (!orgId || typeof orgId !== "string") {
+			// isSuperAdmin is DB-derived (the better-auth session omits role) —
+			// mirror resolve-portal-context's gate (the same one that shows the
+			// View As switcher): user.role is "admin" OR "super_admin".
+			const session = await getSession(c.req.raw.headers);
+			const userId = session?.user?.id;
+			const { getPrisma } = await import("@teamscala/db/prisma-registry");
+			const superAdminUser = userId
+				? await getPrisma().user.findFirst({
+						where: { id: userId, role: { in: ["admin", "super_admin"] } },
+						select: { id: true },
+					})
+				: null;
+			if (!superAdminUser) {
+				return c.json({ error: "orgId query parameter required", members: [] }, 400);
+			}
+			try {
+				const allRows = await queryRows`
+					SELECT m.id, m.user_id, m.organization_id, m.role,
+					       u.email, u.name, u.image
+					FROM better_auth_member m
+					JOIN "user" u ON u.id = m.user_id
+					ORDER BY m.organization_id, u.name
+				` as Array<{
+					id: string;
+					user_id: string;
+					organization_id: string;
+					role: string | null;
+					email: string | null;
+					name: string | null;
+					image: string | null;
+				}>;
+				return c.json({ members: allRows });
+			} catch (err) {
+				log.error(
+					`[portal-members] resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+				return c.json({ error: "resolve-failed", members: [] });
+			}
+		}
+
+		try {
+			const { getPrisma } = await import("@teamscala/db/prisma-registry");
+			const rows = await queryRows`
+				SELECT m.id, m.user_id, m.organization_id, m.role,
+				       u.email, u.name, u.image
+				FROM better_auth_member m
+				JOIN "user" u ON u.id = m.user_id
+				WHERE m.organization_id = ${orgId}
+			` as 
+				Array<{
+					id: string;
+					user_id: string;
+					organization_id: string;
+					role: string | null;
+					email: string | null;
+					name: string | null;
+					image: string | null;
+				}>
+			;
+			return c.json({ members: rows });
+		} catch (err) {
+			log.error(
+				`[portal-members] resolve failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return c.json({ error: "resolve-failed", members: [] });
+		}
+	});
+}

package/src/attach-proposal-accept.ts

@@ -0,0 +1,123 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The proposal ACCEPT endpoint. A viewer who has passed the proposal gate (holds
+ * a valid prop_token) POSTs {proposalId} here to accept; the server generates a
+ * signing document from the proposal (createAgreementFromProposal) and
+ * 302-redirects them straight into signing it on the sign site. This replaces
+ * the old mailto CTA. Mounted BEFORE the auth gate so it is publicly reachable —
+ * the prop_token (not a login) is the proof of identity, exactly like the
+ * content-gate access endpoint.
+ *
+ * Single sign-on across the journey: the viewer already proved their email at
+ * the proposal gate (prop_token), so we MUST NOT make them re-enter it on the
+ * sign site. Before redirecting, we mint the agreement's ag_token for that same
+ * verified email and set it on the SHARED parent domain (Domain=.scala.business)
+ * so the browser carries it from proposals.scala.business to sign.scala.business
+ * — the agreement gate then auto-reveals + seeds the signing session with zero
+ * extra prompts. This requires both hosts to resolve the SAME token secret
+ * (AUTH_SECRET→ENCRYPTION_KEY→DATABASE_URL): scala-sign must carry ENCRYPTION_KEY
+ * (also required to decrypt the org's Stripe key on full sign), so both hosts
+ * land on ENCRYPTION_KEY and the carried token verifies.
+ */
+
+import type { Hono } from "hono";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { signAgreementAccessToken } from "@teamscala/document-signing/agreement-access-token";
+import { parseCookie } from "./content-gate/parse-cookie.ts";
+import { verifyAccessToken } from "./content-gate/token.ts";
+import { agTtlMs } from "./gate-ttls.ts";
+import { createAgreementFromProposal } from "@teamscala/agreement-generation/create-agreement-from-proposal";
+import { getCookieDomain } from "@teamscala/db/registry/cookie-domain";
+
+const PROP_COOKIE = "prop_token";
+const AG_COOKIE = "ag_token";
+
+/** Map the proposals host to the sign host (proposals[-dev].scala.business →
+ *  sign[-dev].scala.business); fall back to the canonical prod sign site. */
+function signBaseUrlFor(host: string | undefined): string {
+	if (host && /^proposals(-dev)?\./.test(host)) {
+		return `https://${host.replace(/^proposals/, "sign")}`;
+	}
+	return "https://sign.scala.business";
+}
+
+function backToProposal(proposalId: string): string {
+	return proposalId ? `/${proposalId}` : "/";
+}
+
+export async function attachProposalAccept(
+	app: Hono,
+	serviceSlug: string,
+): Promise<void> {
+	const log = getAppLogger();
+
+	app.post("/api/proposal-accept", async (c) => {
+		let proposalId = "";
+		let cartSelection: unknown = null;
+		try {
+			const form = await c.req.parseBody();
+			proposalId = String(form.proposalId ?? "").trim();
+			const raw = form.cartSelection;
+			if (typeof raw === "string" && raw.trim()) {
+				cartSelection = JSON.parse(raw);
+			}
+		} catch {
+			return c.redirect("/", 302);
+		}
+		const back = backToProposal(proposalId);
+		if (!proposalId) return c.redirect("/", 302);
+
+		// Identity = the verified email from the proposal gate token. No valid
+		// token → they haven't passed the gate; send them back to enter their email.
+		const token = parseCookie(c.req.header("cookie") ?? null, PROP_COOKIE);
+		const email = verifyAccessToken(token, PROP_COOKIE, proposalId, Date.now());
+		if (!email) {
+			const sep = back.includes("?") ? "&" : "?";
+			return c.redirect(`${back}${sep}accept_error=auth`, 302);
+		}
+
+		const signBase = signBaseUrlFor(c.req.header("host"));
+		const result = await createAgreementFromProposal(proposalId, email, signBase, cartSelection);
+		if (!result.ok || !result.url) {
+			log.error(
+				`[proposal-accept] ${proposalId}: ${result.error ?? "unknown error"}`,
+			);
+			const sep = back.includes("?") ? "&" : "?";
+			return c.redirect(`${back}${sep}accept_error=1`, 302);
+		}
+		log.info(
+			`[proposal-accept] ${proposalId} → agreement ${result.agreementId} (${email})`,
+		);
+
+		// Carry the verified identity through to the agreement gate: we already
+		// matched this email at the proposal gate, so mint the agreement's
+		// ag_token now and set it on the shared parent domain. The browser sends
+		// it to sign.scala.business on the redirect, so the signer never re-enters
+		// their email — one login across proposal → sign → pay. Best-effort: if
+		// the token can't be minted (no secret), the sign site simply shows its
+		// own email gate, which still works.
+		if (result.agreementId) {
+			const agToken = signAgreementAccessToken(
+				result.agreementId,
+				email,
+				Date.now(),
+			);
+			if (agToken) {
+				const maxAge = Math.floor(agTtlMs() / 1000);
+				const domain = await getCookieDomain();
+				c.header(
+					"Set-Cookie",
+					`${AG_COOKIE}=${encodeURIComponent(agToken)}; Domain=${domain}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,
+				);
+			}
+		}
+		return c.redirect(result.url, 302);
+	});
+
+	log.info(
+		`[scala-install:${serviceSlug}] proposal-accept endpoint mounted: /api/proposal-accept`,
+	);
+}