@teamscala/service-boot 0.23.481 → 0.23.492

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

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

package/src/fn-routers/assessment-report-data.test.ts

@@ -1,404 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * report-data.test.ts — proves the report generation logic.
- *
- * The band table used to live in this file's subject as four hardcoded score
- * ranges with their advice strings. It now lives on `assessments.stage_bands`
- * (migration 560/561), so these tests assert the SELECTION and the FALLBACK
- * rather than any particular wording — copy changes are a row edit and must
- * never break the suite.
- */
-
-import { describe, expect, test } from "bun:test";
-import {
-	computeReportData,
-	generateNarrative,
-	orderRoadmap,
-	readStageBands,
-	selectStageBand,
-	pillarNote,
-	numberItems,
-	type StageBand,
-} from "./assessment-report-data.ts";
-
-/** Two bands plus a catch-all — the minimum shape that exercises selection. */
-const BANDS: StageBand[] = [
-	{
-		name: "Hidden",
-		max: 20,
-		tagline: "Early days.",
-		executiveSummary: "You scored {{score}} — you are at the Hidden stage.",
-		strongestAreas: ["Existing expertise"],
-		priorityActions: [{ title: "Clarify positioning", description: "Define one clear position." }],
-		strategicFocus: "Clarity before scale.",
-		strengths: ["Expertise"],
-		opportunities: ["LinkedIn"],
-		twelveMonthTarget: "A clear authority position.",
-		roadmap: {
-			month2: { focus: "Publish", actions: ["Publish weekly"] },
-			month1: { focus: "Position", actions: ["Define niche"] },
-		},
-		pillarNotes: { "be seen": "Your visibility is limited." },
-	},
-	{ name: "Emerging", max: 40, tagline: "Momentum is building." },
-	{ name: "Influential", tagline: "Shaping the category." },
-];
-
-const withBands = (score: number, categories: Record<string, number> = {}) =>
-	computeReportData({
-		input: {
-			response: { total_score: score, category_scores: categories },
-			assessment: { title: "The Launcha Authority Index", stage_bands: { bands: BANDS } },
-		},
-	});
-
-describe("computeReportData — shaping", () => {
-	test("shapes total_score + category_scores into gauge + pillar bars", () => {
-		// Resolver call shape: { input: { response, assessment } } — locks in that
-		// computeReportData reads input.response.total_score (not the whole ctx).
-		const r = computeReportData({
-			input: {
-				response: { total_score: 78, category_scores: { Strategy: 82, Execution: 70 } },
-				assessment: { title: "Ops Maturity" },
-			},
-		});
-		expect(r.totalScore).toBe(78);
-		expect(r.reportScore).toEqual([{ label: "Score", value: 78 }]);
-		expect(r.reportPillars).toEqual([
-			{ label: "Strategy", value: 82 },
-			{ label: "Execution", value: 70 },
-		]);
-	});
-
-	test("derives strongest/opportunity/gap for 3 pillars (Launcha shape)", () => {
-		const r = withBands(48, { "Be Seen": 46, "Be Heard": 54, "Be Chosen": 42 });
-		expect(r.strongest?.label).toBe("Be Heard");
-		expect(r.opportunity?.label).toBe("Be Seen");
-		expect(r.authorityGap?.label).toBe("Be Chosen");
-	});
-
-	test("rounds + clamps non-numeric / negative scores", () => {
-		const r = computeReportData({
-			input: {
-				response: {
-					total_score: -5,
-					category_scores: { A: 12.4, B: "not-a-number" as unknown as number },
-				},
-			},
-		});
-		expect(r.totalScore).toBe(0);
-		expect(r.reportPillars).toEqual([{ label: "A", value: 12 }]);
-	});
-});
-
-describe("computeReportData — the stage model comes from the row", () => {
-	test("selects the band the score falls in and returns its whole section set", () => {
-		const r = withBands(15);
-		expect(r.stage).toBe("Hidden");
-		expect(r.stageSummary).toBe("Early days.");
-		expect(r.strongestAreas).toEqual(["Existing expertise"]);
-		expect(r.priorityActions).toEqual([
-			{ title: "Clarify positioning", description: "Define one clear position." },
-		]);
-		expect(r.strategicFocus).toBe("Clarity before scale.");
-		expect(r.strengths).toEqual(["Expertise"]);
-		expect(r.opportunities).toEqual(["LinkedIn"]);
-		expect(r.twelveMonthTarget).toBe("A clear authority position.");
-	});
-
-	test("a score on a band boundary stays in the lower band", () => {
-		expect(withBands(20).stage).toBe("Hidden");
-		expect(withBands(21).stage).toBe("Emerging");
-	});
-
-	test("the band without a max catches every score above the last bound", () => {
-		expect(withBands(41).stage).toBe("Influential");
-		expect(withBands(100).stage).toBe("Influential");
-	});
-
-	test("{{score}} in the authored summary is replaced with this person's score", () => {
-		expect(withBands(15).narrative).toBe("You scored 15 — you are at the Hidden stage.");
-	});
-
-	test("roadmap renders in month order regardless of authored key order", () => {
-		// BANDS authors month2 before month1 deliberately.
-		expect(withBands(15).roadmap.map((p) => p.focus)).toEqual(["Position", "Publish"]);
-	});
-
-	test("an authored pillar note beats the generic column line", () => {
-		const r = withBands(15, { "Be Seen": 20, "Be Heard": 15 });
-		expect(r.strongest).toEqual({ label: "Be Seen", summary: "Your visibility is limited." });
-		// No note authored for "Be Heard" — the column keeps its generic role line.
-		expect(r.authorityGap?.summary).toContain("single biggest lever");
-	});
-});
-
-describe("computeReportData — degrades rather than throws", () => {
-	test("no stage_bands column: score still renders, stage sections come back empty", () => {
-		const r = computeReportData({
-			input: {
-				response: { total_score: 48, category_scores: { A: 10 } },
-				assessment: { title: "Ops Maturity" },
-			},
-		});
-		expect(r.totalScore).toBe(48);
-		expect(r.stage).toBe("");
-		expect(r.narrative).toBe("You scored 48 on Ops Maturity.");
-		expect(r.priorityActions).toEqual([]);
-		expect(r.roadmap).toEqual([]);
-	});
-
-	test("malformed stage_bands is ignored, not fatal", () => {
-		for (const stage_bands of [null, {}, { bands: "nope" }, { bands: [{ noName: true }] }]) {
-			const r = computeReportData({
-				input: { response: { total_score: 30 }, assessment: { stage_bands } },
-			});
-			expect(r.stage).toBe("");
-			expect(r.totalScore).toBe(30);
-		}
-	});
-
-	test("handles null response", () => {
-		const r = computeReportData({ input: { response: null } });
-		expect(r.totalScore).toBe(0);
-		expect(r.reportScore).toEqual([{ label: "Score", value: 0 }]);
-		expect(r.reportPillars).toEqual([]);
-		expect(r.strongest).toBeNull();
-		expect(r.opportunity).toBeNull();
-		expect(r.authorityGap).toBeNull();
-	});
-});
-
-describe("readStageBands", () => {
-	test("returns [] for anything that is not a bands array of named objects", () => {
-		expect(readStageBands(null)).toEqual([]);
-		expect(readStageBands({ stage_bands: undefined })).toEqual([]);
-		expect(readStageBands({ stage_bands: { bands: [{ max: 20 }] } })).toEqual([]);
-	});
-
-	test("keeps only the entries carrying a name", () => {
-		const bands = readStageBands({
-			stage_bands: { bands: [{ name: "Hidden", max: 20 }, { max: 40 }] },
-		});
-		expect(bands.map((b) => b.name)).toEqual(["Hidden"]);
-	});
-});
-
-describe("selectStageBand", () => {
-	test("returns null when there are no bands", () => {
-		expect(selectStageBand([], 50)).toBeNull();
-	});
-
-	test("falls back to the last band when every band is bounded and none matched", () => {
-		const bounded: StageBand[] = [
-			{ name: "Low", max: 10 },
-			{ name: "High", max: 20 },
-		];
-		expect(selectStageBand(bounded, 99)?.name).toBe("High");
-	});
-});
-
-describe("generateNarrative", () => {
-	test("uses the authored summary when the band has one", () => {
-		expect(generateNarrative(30, { name: "Emerging", executiveSummary: "At {{score}}." })).toBe(
-			"At 30.",
-		);
-	});
-
-	test("states only the score when no band and no title are available", () => {
-		expect(generateNarrative(30, null)).toBe("You scored 30 on your assessment.");
-	});
-});
-
-describe("orderRoadmap", () => {
-	test("empty for a missing or non-object roadmap", () => {
-		expect(orderRoadmap(undefined)).toEqual([]);
-	});
-
-	test("drops a phase with no actions array", () => {
-		const phases = orderRoadmap({
-			month1: { focus: "Position", actions: ["A"] },
-			month2: { focus: "Broken" } as never,
-		});
-		expect(phases.map((p) => p.focus)).toEqual(["Position"]);
-	});
-});
-
-describe("pillar cards", () => {
-	const assessment = {
-		title: "The Launcha Authority Index",
-		categories: ["Be Seen", "Be Heard", "Be Chosen"],
-		category_descriptions: {
-			"Be Seen": { subtitle: "Visibility + Positioning", color: "#2563eb" },
-			"Be Heard": { subtitle: "Credibility + Trust", color: "#FF4500" },
-			"Be Chosen": { subtitle: "Leads + Conversion", color: "#16a34a" },
-		},
-		stage_bands: {
-			bands: [
-				{
-					name: "Hidden",
-					pillarNotes: { seen: "Your visibility is limited.", "be chosen": "No conversion system." },
-				},
-			],
-		},
-	};
-
-	test("holds the authored order, not score order", () => {
-		const r = computeReportData({
-			input: {
-				response: { total_score: 15, category_scores: { "Be Chosen": 90, "Be Seen": 10 } },
-				assessment,
-			},
-		});
-		expect(r.pillarCards.map((c) => c.label)).toEqual(["Be Seen", "Be Heard", "Be Chosen"]);
-		// reportPillars stays score-sorted — the two serve different sections.
-		expect(r.reportPillars[0]?.label).toBe("Be Chosen");
-	});
-
-	test("carries subtitle, colour and this person's score", () => {
-		const r = computeReportData({
-			input: { response: { total_score: 15, category_scores: { "Be Seen": 20 } }, assessment },
-		});
-		const seen = r.pillarCards[0];
-		expect(seen?.subtitle).toBe("Visibility + Positioning");
-		expect(seen?.color).toBe("#2563eb");
-		expect(seen?.value).toBe(20);
-		expect(seen?.max).toBe(100);
-	});
-
-	test("a pillar the person did not score reads zero rather than vanishing", () => {
-		const r = computeReportData({
-			input: { response: { total_score: 15, category_scores: {} }, assessment },
-		});
-		expect(r.pillarCards.map((c) => c.value)).toEqual([0, 0, 0]);
-	});
-
-	test("the chart bars take the same colours as the cards", () => {
-		const r = computeReportData({
-			input: {
-				response: { total_score: 15, category_scores: { "Be Seen": 20, "Be Heard": 30 } },
-				assessment,
-			},
-		});
-		const byLabel = Object.fromEntries(r.reportPillars.map((p) => [p.label, p.color]));
-		expect(byLabel["Be Seen"]).toBe("#2563eb");
-		expect(byLabel["Be Heard"]).toBe("#FF4500");
-	});
-});
-
-describe("pillarNote", () => {
-	const band = {
-		name: "Hidden",
-		pillarNotes: { seen: "Short key.", "be chosen": "Full label key." },
-	};
-
-	test("matches a note keyed by the distinctive word alone", () => {
-		// The designs key notes as seen/heard/chosen while the assessment names
-		// pillars "Be Seen" — a plain lowercase lookup missed every one.
-		expect(pillarNote(band, "Be Seen")).toBe("Short key.");
-	});
-
-	test("matches a note keyed by the whole label", () => {
-		expect(pillarNote(band, "Be Chosen")).toBe("Full label key.");
-	});
-
-	test("empty when the band authors no note for that pillar", () => {
-		expect(pillarNote(band, "Be Heard")).toBe("");
-		expect(pillarNote(null, "Be Seen")).toBe("");
-	});
-});
-
-describe("numberItems", () => {
-	test("pairs each item with its 1-based ordinal", () => {
-		expect(numberItems(["a", "b"])).toEqual([
-			{ index: "1", text: "a" },
-			{ index: "2", text: "b" },
-		]);
-	});
-
-	test("an absent item carries no number, so a fixed slot renders nothing", () => {
-		// The stray-numeral defect: six slots, four authored items. Slots five and
-		// six resolve to undefined for BOTH index and text rather than printing a
-		// bare "5" beside empty space to a client.
-		const list = numberItems(["a", "b", "c", "d"]);
-		expect(list.length).toBe(4);
-		expect(list[4]).toBeUndefined();
-	});
-
-	test("blank entries are dropped and do not consume an ordinal", () => {
-		expect(numberItems(["a", "   ", "b"])).toEqual([
-			{ index: "1", text: "a" },
-			{ index: "2", text: "b" },
-		]);
-	});
-
-	test("empty for a missing list", () => {
-		expect(numberItems(undefined)).toEqual([]);
-	});
-});
-
-describe("Anna's page-5 block", () => {
-	test("empty when the stage authors no copy, so the page can hide the section", () => {
-		const r = computeReportData({
-			input: { response: { total_score: 48 }, assessment: { stage_bands: { bands: [{ name: "X" }] } } },
-		});
-		expect(r.recommendedTier).toBe("");
-		expect(r.finalWord).toBe("");
-	});
-
-	test("carries the authored tier and closing word when a stage supplies them", () => {
-		const r = computeReportData({
-			input: {
-				response: { total_score: 48 },
-				assessment: {
-					stage_bands: {
-						bands: [
-							{
-								name: "Recognised",
-								recommendedTier: "Authority Accelerator",
-								tierSummary: "A 90-day programme.",
-								whyItFits: "You have the foundations.",
-								whatItSolves: "Inconsistent conversion.",
-								implementationFocus: "Systems before scale.",
-								expectedOutcome: "Predictable pipeline.",
-								finalWord: "Authority compounds.",
-							},
-						],
-					},
-				},
-			},
-		});
-		expect(r.recommendedTier).toBe("Authority Accelerator");
-		expect(r.whyItFits).toBe("You have the foundations.");
-		expect(r.finalWord).toBe("Authority compounds.");
-	});
-});
-
-describe("every remaining template element is a stage row, not a build task", () => {
-	const ALL = [
-		"whoYouHelp", "knownFor", "northStar", "contentRhythm",
-		"priorityFocus", "priorityFocusSummary", "recommendedTier", "finalWord",
-	] as const;
-
-	test("all absent as empty strings when unauthored, so sections stay hidden", () => {
-		const r = computeReportData({
-			input: { response: { total_score: 48 }, assessment: { stage_bands: { bands: [{ name: "X" }] } } },
-		});
-		for (const key of ALL) expect(r[key]).toBe("");
-		expect(r.insights).toEqual([]);
-		expect(r.contentThemes).toEqual([]);
-	});
-
-	test("each surfaces verbatim once a stage authors it", () => {
-		const band: Record<string, unknown> = { name: "Recognised", insights: ["a", "b"] };
-		for (const key of ALL) band[key] = `copy:${key}`;
-		const r = computeReportData({
-			input: { response: { total_score: 48 }, assessment: { stage_bands: { bands: [band] } } },
-		});
-		for (const key of ALL) expect(r[key]).toBe(`copy:${key}`);
-		expect(r.insights).toEqual(["a", "b"]);
-	});
-});