@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/constants.ts

@@ -6,19 +6,31 @@
 // Plugin-Renderer in `renderer-foundation` matchen auf kind; der
 // Resolver hier ist kind-agnostisch — er lädt nur, das Content-Format
 // (markdown/mjml/html) entscheidet wer's rendert.
-export const RENDER_KINDS = [
-  "notification",
-  "mail-html",
-  "document-pdf",
-  "image-snapshot",
-] as const;
+export const RENDER_KINDS = ["mail", "document-pdf", "image-snapshot"] as const;
 export type RenderKind = (typeof RENDER_KINDS)[number];
 
-// Kinds without a renderer plugin: `text-block` is the Markdown text store
-// (ex text-content feature), `ai-prompt` holds LLM prompts. Both are read,
-// not rendered — keeping them out of RENDER_KINDS is what stops
+// Kinds whose html body is a rich document: the server rebuilds it through the
+// document schema on every write (see document-sanitizer.ts).
+export const DOCUMENT_HTML_KINDS = ["mail", "document-pdf"] as const;
+export type DocumentHtmlKind = (typeof DOCUMENT_HTML_KINDS)[number];
+
+// Kinds without a renderer plugin: `notification` is the retired sections-JSON
+// notification kind, kept so rows stored before mails moved to `mail` stay
+// valid on replay; nothing writes or renders it any more. `text-block` is the Markdown text store
+// (ex text-content feature), `snippet` is the content of app collections such
+// as reply snippets and signatures (own kind so they stay out of the text-block
+// content tree), `ai-prompt` holds LLM prompts, `mail-layout` and
+// `pdf-layout` hold the frame a mail/pdf body is rendered into. All are read,
+// not rendered on their own — keeping them out of RENDER_KINDS is what stops
 // DEFAULT_PLUGIN_BY_KIND from demanding a plugin for them.
-export const NON_RENDER_KINDS = ["text-block", "ai-prompt"] as const;
+export const NON_RENDER_KINDS = [
+  "notification",
+  "text-block",
+  "snippet",
+  "ai-prompt",
+  "mail-layout",
+  "pdf-layout",
+] as const;
 export type NonRenderKind = (typeof NON_RENDER_KINDS)[number];
 
 // Full kind domain of the entity; RENDER_KINDS is the renderer-foundation subset.
@@ -28,7 +40,7 @@ export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
 // Kinds written through upsertSystem/upsertTenant. `text-block` is absent on
 // purpose: it goes through set.write (title + folder tree); two write paths
 // onto the same row would drift apart.
-export const UPSERT_KINDS = [...RENDER_KINDS, "ai-prompt"] as const;
+export const UPSERT_KINDS = [...RENDER_KINDS, "ai-prompt", "mail-layout", "pdf-layout"] as const;
 export type UpsertKind = (typeof UPSERT_KINDS)[number];
 
 // The only kind served by the anonymous-capable by-slug/by-tenant queries and
@@ -36,6 +48,11 @@ export type UpsertKind = (typeof UPSERT_KINDS)[number];
 // must not leak through the anonymous path.
 export const TEXT_BLOCK_KIND = "text-block" as const;
 
+// Kinds a content collection must not write: a tenant row of these kinds would
+// shadow the system notification template or layout without the meta and
+// placeholder gates that upsertTenant applies.
+export const COLLECTION_REFUSED_KINDS: readonly string[] = ["mail", "mail-layout", "pdf-layout"];
+
 export const CONTENT_FORMATS = ["markdown", "mjml", "html", "plain"] as const;
 export type ContentFormat = (typeof CONTENT_FORMATS)[number];
 
@@ -45,6 +62,27 @@ export type TemplateScope = (typeof TEMPLATE_SCOPES)[number];
 export const TEMPLATE_STATUSES = ["draft", "active", "archived"] as const;
 export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
 
+export {
+  PDF_DEFAULT_MARGIN_MM,
+  PDF_FOOTER_MARGIN_MM,
+  PDF_HEADER_MARGIN_MM,
+  PDF_ORIENTATIONS,
+  PDF_PAGE_FORMATS,
+  type PdfOrientation,
+  type PdfPageFormat,
+} from "./pdf-constants.js";
+
+// Colors end up inside MJML attributes, so only a strict hex is ever written there.
+export const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
+export const DEFAULT_MAIL_LAYOUT_SLUG = "default";
+
+// The mail transport enforces no size limit of its own; 10 MiB is a common provider ceiling.
+export const MAIL_PREVIEW_MAX_BYTES = 10 * 1024 * 1024;
+
+export const TEST_MAIL_NOTIFICATION_TYPE = "template-resolver:test-mail";
+export const TEST_MAIL_SUBJECT_PREFIX = "[TEST] ";
+
 // System-Templates leben unter der canonical SYSTEM_TENANT_ID-Sentinel-UUID.
 // Re-Export aus framework — single source of truth, vermeidet Drift.
 export { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";

package/packages/bundled-features/src/template-resolver/document-sanitizer.ts

@@ -0,0 +1,335 @@
+// Server-only: pulls in happy-dom via @tiptap/html/server, so it must stay out
+// of client barrels and the document-schema subpath export.
+import type { FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { generateHTML, generateJSON } from "@tiptap/html/server";
+import { type Element as ScanElement, Window } from "happy-dom";
+import type { ContentFormat } from "./constants.js";
+import { DOCUMENT_HTML_KINDS } from "./constants.js";
+import {
+  documentExtensions,
+  isAllowedDocumentLinkHref,
+  isDocumentPlaceholderHref,
+  isDocumentReferenceName,
+  isDocumentResourceKey,
+} from "./document-schema.js";
+
+export type DocumentViolationCode =
+  | "script_element"
+  | "event_handler_attribute"
+  | "disallowed_link_href"
+  | "external_image_source"
+  | "image_without_resource"
+  | "invalid_reference_name"
+  | "embedded_content"
+  | "unsafe_attribute_value"
+  | "button_href_not_placeholder"
+  | "document_requires_html_format"
+  | "layout_requires_mjml_format"
+  | "layout_invalid_structure"
+  | "layout_missing_content_slot"
+  | "layout_source_system_only";
+
+export type DocumentViolation = {
+  readonly code: DocumentViolationCode;
+  readonly detail: string;
+  readonly message: string;
+};
+
+export type SanitizeHtmlResult =
+  | { readonly ok: true; readonly html: string }
+  | { readonly ok: false; readonly violations: readonly DocumentViolation[] };
+
+export type SanitizeBodyResult =
+  | { readonly ok: true; readonly content: string | null }
+  | { readonly ok: false; readonly violations: readonly DocumentViolation[] };
+
+export function violation(
+  code: DocumentViolationCode,
+  detail: string,
+  message: string,
+): DocumentViolation {
+  return { code, detail, message };
+}
+
+// Same switches tiptap's generateJSON uses, plus navigation off: the scan
+// window must never fetch or navigate anything.
+function createScanWindow(): Window {
+  return new Window({
+    settings: {
+      disableJavaScriptEvaluation: true,
+      disableJavaScriptFileLoading: true,
+      disableCSSFileLoading: true,
+      disableIframePageLoading: true,
+      disableComputedStyleRendering: true,
+      navigation: {
+        disableMainFrameNavigation: true,
+        disableChildFrameNavigation: true,
+        disableChildPageNavigation: true,
+      },
+    },
+  });
+}
+
+function scanScriptAndHandlers(tag: string, element: ScanElement, out: DocumentViolation[]): void {
+  if (tag === "script") {
+    out.push(
+      violation("script_element", "script", "<script> elements are not allowed in template bodies"),
+    );
+  }
+  for (const attribute of Array.from(element.attributes)) {
+    if (/^on/i.test(attribute.name)) {
+      out.push(
+        violation(
+          "event_handler_attribute",
+          attribute.name,
+          `Inline event handler "${attribute.name}" on <${tag}> is not allowed`,
+        ),
+      );
+    }
+  }
+}
+
+function scanAnchor(element: ScanElement, out: DocumentViolation[]): void {
+  const href = element.getAttribute("href");
+  if (href !== null && !isAllowedDocumentLinkHref(href)) {
+    out.push(
+      violation(
+        "disallowed_link_href",
+        href,
+        `Link target "${href}" is not allowed; use https, http, mailto, tel or a {{placeholder}}`,
+      ),
+    );
+  }
+  if (element.hasAttribute("data-button") && !isDocumentPlaceholderHref(href ?? "")) {
+    out.push(
+      violation(
+        "button_href_not_placeholder",
+        href ?? "",
+        `Button target "${href ?? ""}" must be a {{placeholder}}`,
+      ),
+    );
+  }
+}
+
+function scanImage(element: ScanElement, out: DocumentViolation[]): void {
+  const source = element.getAttribute("src") ?? element.getAttribute("srcset");
+  if (source !== null) {
+    out.push(
+      violation(
+        "external_image_source",
+        source,
+        `Images must reference an uploaded resource via data-resource; external or inline image source "${source}" is not allowed`,
+      ),
+    );
+  }
+  if (!element.hasAttribute("data-resource")) {
+    out.push(
+      violation(
+        "image_without_resource",
+        "img",
+        "Images must reference an uploaded resource via the data-resource attribute",
+      ),
+    );
+  }
+}
+
+const REFERENCE_ATTRIBUTES: ReadonlyArray<readonly [string, (value: string) => boolean]> = [
+  ["data-variable", isDocumentReferenceName],
+  ["data-each", isDocumentReferenceName],
+  ["data-resource", isDocumentResourceKey],
+];
+
+function scanReferences(tag: string, element: ScanElement, out: DocumentViolation[]): void {
+  for (const [attribute, isValid] of REFERENCE_ATTRIBUTES) {
+    const value = element.getAttribute(attribute);
+    if (value !== null && !isValid(value)) {
+      out.push(
+        violation(
+          "invalid_reference_name",
+          value,
+          `Value "${value}" of ${attribute} on <${tag}> is not a valid name`,
+        ),
+      );
+    }
+  }
+}
+
+const EMBEDDING_TAGS: ReadonlySet<string> = new Set([
+  "iframe",
+  "frame",
+  "frameset",
+  "object",
+  "embed",
+  "applet",
+  "portal",
+]);
+const SVG_IMAGE_TAGS: ReadonlySet<string> = new Set(["image", "feimage", "use"]);
+const URL_ATTRIBUTES = ["href", "xlink:href", "action", "formaction"] as const;
+
+function scanEmbedding(tag: string, out: DocumentViolation[]): void {
+  if (EMBEDDING_TAGS.has(tag)) {
+    out.push(
+      violation("embedded_content", tag, `<${tag}> elements are not allowed in template bodies`),
+    );
+  }
+}
+
+// html <a href> has its own rules in scanAnchor; everywhere else (svg, base,
+// form controls) a URL attribute has no business in a template body.
+function scanUrlAttributes(tag: string, element: ScanElement, out: DocumentViolation[]): void {
+  for (const name of URL_ATTRIBUTES) {
+    const value = element.getAttribute(name);
+    if (value === null || (tag === "a" && name === "href")) continue;
+    if (SVG_IMAGE_TAGS.has(tag) && name.endsWith("href")) {
+      out.push(
+        violation(
+          "external_image_source",
+          value,
+          `Images must reference an uploaded resource via data-resource; image source "${value}" is not allowed`,
+        ),
+      );
+    } else if (tag === "base" || !isAllowedDocumentLinkHref(value)) {
+      out.push(
+        violation(
+          "disallowed_link_href",
+          value,
+          `Link target "${value}" is not allowed; use https, http, mailto, tel or a {{placeholder}}`,
+        ),
+      );
+    }
+  }
+}
+
+// happy-dom serializes < and > inside attribute values unescaped, so a later
+// parser (MJML) could read them as markup.
+function scanAltText(element: ScanElement, out: DocumentViolation[]): void {
+  const alt = element.getAttribute("alt");
+  if (alt !== null && /[<>]/.test(alt)) {
+    out.push(
+      violation(
+        "unsafe_attribute_value",
+        alt,
+        `Attribute alt must not contain "<" or ">": "${alt}"`,
+      ),
+    );
+  }
+}
+
+function scanElement(element: ScanElement, out: DocumentViolation[]): void {
+  const tag = element.tagName.toLowerCase();
+  scanEmbedding(tag, out);
+  scanUrlAttributes(tag, element, out);
+  scanAltText(element, out);
+  scanScriptAndHandlers(tag, element, out);
+  if (tag === "a") scanAnchor(element, out);
+  if (tag === "img") scanImage(element, out);
+  scanReferences(tag, element, out);
+}
+
+// Parses `html` in the hardened scan window and always closes it again, also
+// when `read` throws. Shared by the sanitizer and the placeholder scan so there
+// is exactly one DOM setup.
+export function withParsedDocument<T>(html: string, read: (body: ScanElement) => T): T {
+  const window = createScanWindow();
+  try {
+    const parsed = new window.DOMParser().parseFromString(
+      ["<!DOCTYPE html><html><body>", html, "</body></html>"].join(""),
+      "text/html",
+    );
+    return read(parsed.body);
+  } finally {
+    window.happyDOM.abort();
+    window.happyDOM.close();
+  }
+}
+
+function scanDocumentHtml(html: string): DocumentViolation[] {
+  const violations: DocumentViolation[] = [];
+  withParsedDocument(html, (body) => {
+    // A second `<body ...>` in the input merges its attributes into this body.
+    for (const element of [body, ...Array.from(body.querySelectorAll("*"))]) {
+      scanElement(element, violations);
+    }
+  });
+  return violations;
+}
+
+// Rejects hostile constructs, then rebuilds the body from the document model.
+// The rebuilt HTML is always what gets returned (never the input), so anything
+// the model cannot express is dropped silently.
+export function sanitizeDocumentHtml(html: string): SanitizeHtmlResult {
+  const violations = scanDocumentHtml(html);
+  if (violations.length > 0) return { ok: false, violations };
+  return {
+    ok: true,
+    html: generateHTML(generateJSON(html, documentExtensions), documentExtensions),
+  };
+}
+
+// Snippets accept any format, but their html is as untrusted as a mail body.
+function isSanitizedHtmlKind(kind: string): boolean {
+  return kind === "snippet" || isOneOf(DOCUMENT_HTML_KINDS, kind);
+}
+
+const HTML_ONLY_KINDS: ReadonlySet<string> = new Set(DOCUMENT_HTML_KINDS);
+
+function requiredFormatViolation(
+  kind: string,
+  contentFormat: ContentFormat,
+): DocumentViolation | null {
+  if (HTML_ONLY_KINDS.has(kind) && contentFormat !== "html") {
+    return violation(
+      "document_requires_html_format",
+      contentFormat,
+      `Templates of kind ${kind} require contentFormat html, got "${contentFormat}"`,
+    );
+  }
+  return null;
+}
+
+export function sanitizeTemplateBody(input: {
+  readonly kind: string;
+  readonly contentFormat: ContentFormat;
+  readonly content: string | null;
+}): SanitizeBodyResult {
+  const formatViolation = requiredFormatViolation(input.kind, input.contentFormat);
+  if (formatViolation !== null) return { ok: false, violations: [formatViolation] };
+  if (
+    !isSanitizedHtmlKind(input.kind) ||
+    input.contentFormat !== "html" ||
+    input.content === null
+  ) {
+    return { ok: true, content: input.content };
+  }
+  const result = sanitizeDocumentHtml(input.content);
+  return result.ok ? { ok: true, content: result.html } : result;
+}
+
+const VIOLATION_I18N_KEYS: Readonly<Record<DocumentViolationCode, string>> = {
+  script_element: "templateResolver.errors.document.scriptElement",
+  event_handler_attribute: "templateResolver.errors.document.eventHandlerAttribute",
+  disallowed_link_href: "templateResolver.errors.document.disallowedLinkHref",
+  external_image_source: "templateResolver.errors.document.externalImageSource",
+  image_without_resource: "templateResolver.errors.document.imageWithoutResource",
+  invalid_reference_name: "templateResolver.errors.document.invalidReferenceName",
+  embedded_content: "templateResolver.errors.document.embeddedContent",
+  unsafe_attribute_value: "templateResolver.errors.document.unsafeAttributeValue",
+  button_href_not_placeholder: "templateResolver.errors.document.buttonHrefNotPlaceholder",
+  document_requires_html_format: "templateResolver.errors.document.documentRequiresHtmlFormat",
+  layout_requires_mjml_format: "templateResolver.errors.document.layoutRequiresMjmlFormat",
+  layout_invalid_structure: "templateResolver.errors.document.layoutInvalidStructure",
+  layout_missing_content_slot: "templateResolver.errors.document.layoutMissingContentSlot",
+  layout_source_system_only: "templateResolver.errors.document.layoutSourceSystemOnly",
+};
+
+export function documentViolationsToFieldIssues(
+  violations: readonly DocumentViolation[],
+): FieldIssue[] {
+  return violations.map((item) => ({
+    path: "content",
+    code: item.code,
+    i18nKey: VIOLATION_I18N_KEYS[item.code],
+    params: { detail: item.detail },
+  }));
+}