@cosmicdrift/kumiko-bundled-features 0.50.0 → 0.51.0

package/src/managed-pages/seeding.ts

@@ -0,0 +1,99 @@
+// Test-/Seed-Helper für managed-pages. Legt eine Page direkt über den
+// Event-Store-Executor an — gleicher Pfad wie der echte set-Handler, aber
+// ohne Access-Check. Default ifExists="skip".
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { type PageRow, pageEntity, pagesTable } from "./table";
+
+const executor = createEventStoreExecutor(pagesTable, pageEntity, { entityName: "page" });
+
+export type SeedPageOptions = {
+  readonly tenantId: TenantId;
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body?: string | null;
+  readonly description?: string | null;
+  readonly ogImage?: string | null;
+  readonly published?: boolean;
+  readonly by?: SessionUser;
+  readonly ifExists?: SeedIfExists;
+};
+
+export async function seedPage(db: DbConnection, opts: SeedPageOptions): Promise<{ id: string }> {
+  // Default-user muss user.tenantId === opts.tenantId haben (sonst landet
+  // der event-store-stream im falschen tenant-bucket → version_conflict
+  // bei späteren echten writes). TestUsers.systemAdmin ist testTenantId(1).
+  const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
+  const tdb = createTenantDb(db, opts.tenantId, "system");
+
+  const existing = await fetchOne<PageRow>(db, pagesTable, {
+    tenantId: opts.tenantId,
+    slug: opts.slug,
+    lang: opts.lang,
+  });
+
+  const description = opts.description ?? null;
+  const ogImage = opts.ogImage ?? null;
+  const published = opts.published ?? false;
+
+  return runEventStoreSeed({
+    existing,
+    ifExists: opts.ifExists,
+    create: async () => {
+      const result = await executor.create(
+        {
+          slug: opts.slug,
+          lang: opts.lang,
+          title: opts.title,
+          body: opts.body ?? null,
+          description,
+          ogImage,
+          published,
+          tenantId: opts.tenantId,
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedPage create failed: ${JSON.stringify(result)}`);
+      }
+      // @cast-boundary db-row: executor.create result.data ist die inserted
+      // Drizzle-Row (Record<string, unknown>), projected nach RETURNING.
+      const data = result.data as Partial<PageRow>;
+      if (data.id === undefined) {
+        throw new Error("seedPage: executor.create did not return an id");
+      }
+      return { id: data.id };
+    },
+    update: async (row) => {
+      const result = await executor.update(
+        {
+          id: row.id,
+          version: row.version,
+          changes: {
+            title: opts.title,
+            body: opts.body ?? null,
+            description,
+            ogImage,
+            published,
+          },
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedPage update failed: ${JSON.stringify(result)}`);
+      }
+      return { id: row.id };
+    },
+  });
+}

package/src/managed-pages/table.ts

@@ -0,0 +1,58 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Page — vom Tenant editierbare, server-gerenderte Public-Page (Landing,
+// About, custom). Pro (tenantId, slug, lang) genau eine Row. Body ist
+// Markdown (gehärtet server-gerendert über page-render). `published` gated
+// die Auslieferung an anonyme Besucher: Drafts → 404. description/ogImage
+// für SEO + Social-Preview. SYSTEM_TENANT_ID für app-weite Pages, sonst
+// Tenant-eigene Pages (Host → tenantId via resolveApexTenant am Render-Pfad).
+export const pageEntity = createEntity({
+  table: "read_pages",
+  fields: {
+    slug: createTextField({ required: true, maxLength: 64, sortable: true, searchable: true }),
+    lang: createTextField({ required: true, maxLength: 8, sortable: true }),
+    title: createTextField({ required: true, maxLength: 200, searchable: true }),
+    // Body + description sind vom Tenant-Admin authored Business-Content
+    // (Markdown), keine User-Generated-PII. `multiline` → der entityEdit-
+    // Renderer gibt ein <textarea> aus (createLongTextField hat aktuell
+    // einen Render-Gap: edit.ts/render-field.tsx gaten nur type==="text").
+    // maxLengths spiegeln die Handler-Schemas (set.write + Convention-CRUD
+    // leiten ihre zod-Caps aus diesen Field-maxLengths ab).
+    body: createTextField({
+      multiline: { rows: 16 },
+      maxLength: 100_000,
+      allowPlaintext: "is-business-data",
+    }),
+    description: createTextField({ maxLength: 500, allowPlaintext: "is-business-data" }),
+    ogImage: createTextField({ maxLength: 2000 }),
+    published: createBooleanField({ default: false }),
+  },
+  indexes: [{ unique: true, columns: ["tenantId", "slug", "lang"], name: "read_pages_unique" }],
+});
+
+export const pagesTable = buildEntityTable("page", pageEntity);
+
+// Concrete Row-Type — single-source für die benannten Werte (statt
+// `row["x"] as Y`-Casts in Handlern). entity.fields + Standard-Spalten
+// (id, version, tenantId, createdAt, updatedAt, createdBy, updatedBy).
+export type PageRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly tenantId: string;
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly description: string | null;
+  readonly ogImage: string | null;
+  readonly published: boolean;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly createdBy: string;
+  readonly updatedBy: string;
+};

package/src/page-render/__tests__/branding.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type BrandingTokens,
+  brandingHeaderHtml,
+  brandingStyleBlock,
+  EMPTY_BRANDING,
+} from "../branding";
+
+const tokens = (over: Partial<BrandingTokens>): BrandingTokens => ({ ...EMPTY_BRANDING, ...over });
+
+// The branding tokens are RAW tenant input (title/description only length-capped
+// at write). These emitters are the safe boundary a custom wrapLayout must use —
+// prove they escape/re-validate, since interpolating branding.title directly
+// would be stored XSS on the anonymous public page.
+describe("brandingHeaderHtml — escapes untrusted tokens", () => {
+  test("a <script> in the title is HTML-escaped, not emitted live", () => {
+    const html = brandingHeaderHtml(tokens({ title: "<script>alert(1)</script>" }));
+    expect(html).not.toContain("<script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+
+  test("tag/quote syntax in the title can't break out of the logo alt", () => {
+    const html = brandingHeaderHtml(
+      tokens({ logoUrl: "https://cdn.test/l.png", title: '"><img src=x onerror=alert(1)>' }),
+    );
+    // the title's angle brackets are escaped → the injected tag is inert text
+    // in the alt, never a live element.
+    expect(html).not.toContain("<img src=x");
+    expect(html).toContain("&lt;img src=x");
+    expect(html).toContain('<img class="brand-logo"'); // the real logo survives
+  });
+
+  test("a non-https logo URL is dropped (no <img>)", () => {
+    expect(brandingHeaderHtml(tokens({ logoUrl: "javascript:alert(1)" }))).toBe("");
+    expect(brandingHeaderHtml(tokens({ logoUrl: "http://cdn.test/l.png" }))).toBe("");
+  });
+
+  test("a non-https siteUrl never becomes a home link", () => {
+    const html = brandingHeaderHtml(tokens({ title: "Acme", siteUrl: "javascript:alert(1)" }));
+    expect(html).toContain("Acme");
+    expect(html).not.toContain("<a href");
+    expect(html).not.toContain("javascript:");
+  });
+});
+
+describe("brandingStyleBlock — re-validates theme tokens", () => {
+  test("an invalid accent color is dropped (no --accent injected)", () => {
+    const css = brandingStyleBlock(tokens({ accentColor: "red;}</style><script>" }));
+    expect(css).not.toContain("--accent:red");
+    expect(css).not.toContain("</style><script>");
+    expect(css).not.toContain("--accent:");
+  });
+
+  test("a valid hex accent color is injected", () => {
+    expect(brandingStyleBlock(tokens({ accentColor: "#ff0066" }))).toContain("--accent:#ff0066");
+  });
+});

package/src/page-render/__tests__/css-sanitize.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, test } from "bun:test";
+import { sanitizeTenantCss } from "../css-sanitize";
+
+const SCOPE = "[data-tenant-content]";
+const css = (input: string): string => sanitizeTenantCss(input, SCOPE);
+
+// Bypass-first: the literal-string attacks (@import, url(javascript:)) are easy
+// to pass; the parser-differential ones (CSS escapes, comma scope-escape,
+// case/whitespace variants) are where a naive blocklist breaks. Lead with those.
+describe("sanitizeTenantCss — bypass vectors", () => {
+  test("CSS hex escape \\75rl( can't re-form url() — backslash drops the decl", () => {
+    // \75 = 'u'. A literal-`url(` blocklist sees an unknown ident; the browser
+    // decodes it to url(. We reject any backslash outright instead.
+    const out = css(".x { background-color: \\75rl(javascript:alert(1)); }");
+    expect(out).toBe("");
+    expect(out).not.toContain("\\");
+  });
+
+  test("escaped @import (@imp\\6frt) is dropped, not executed", () => {
+    expect(css("@imp\\6frt url(evil);")).toBe("");
+  });
+
+  test("a lone backslash anywhere drops the whole rule", () => {
+    expect(css(".x { color: red\\9; }")).toBe("");
+    expect(css(".x\\3a hover { color: red; }")).toBe("");
+  });
+
+  test("backslash in one rule doesn't poison the others", () => {
+    const out = css(".ok { color: red; } .bad { width: \\31 0px; }");
+    expect(out).toContain("[data-tenant-content] .ok");
+    expect(out).toContain("color: red");
+    expect(out).not.toContain(".bad");
+    expect(out).not.toContain("\\");
+  });
+
+  test("comma selector list is scoped per-segment (no scope-escape)", () => {
+    const out = css(".a, .b { color: red; }");
+    expect(out).toContain("[data-tenant-content] .a");
+    expect(out).toContain("[data-tenant-content] .b");
+    // the second segment must NOT survive unscoped
+    expect(out).not.toMatch(/(^|,)\s*\.b\s*\{/);
+  });
+
+  test("commas inside :is()/:not() don't break top-level splitting", () => {
+    // comma inside the pseudo keeps it one segment; that segment is then
+    // rejected (comma not allowed in a single selector) — dropped, not split.
+    expect(css(":is(.a, .b) { color: red; }")).toBe("");
+  });
+
+  test("case/whitespace url variants are all caught", () => {
+    expect(css(".x { background-color: URL(x); }")).toBe("");
+    expect(css(".x { background-color: url (x); }")).toBe("");
+    expect(css(".x { background-color: Url( x ); }")).toBe("");
+  });
+
+  test("</style> breakout in trailing text or value never reaches output", () => {
+    const trailing = css(".x { color: red; } </style><script>alert(1)</script>");
+    expect(trailing).not.toContain("</style");
+    expect(trailing).not.toContain("<script");
+    expect(trailing).not.toContain("<");
+    const inValue = css(".x { color: red</style>; }");
+    expect(inValue).not.toContain("<");
+  });
+
+  test("comment-split tokens can't smuggle url(", () => {
+    expect(css(".x { background-color: u/**/rl(x); }")).toBe("");
+    expect(css(".x { background-color: ur/**/l(evil); }")).toBe("");
+  });
+});
+
+describe("sanitizeTenantCss — named attack classes", () => {
+  test("@import is dropped", () => {
+    expect(css("@import url('http://evil.test');")).toBe("");
+    expect(css("@import 'x';")).toBe("");
+  });
+
+  test("url(javascript:) / url(data:) are dropped, sibling decls survive", () => {
+    const out = css(".x { color: red; background-color: url(javascript:alert(1)); }");
+    expect(out).toContain("color: red");
+    expect(out).not.toContain("url");
+    expect(out).not.toContain("javascript");
+  });
+
+  test("expression() is dropped", () => {
+    expect(css(".x { width: expression(alert(1)); }")).toBe("");
+  });
+
+  test("var()/custom-props are dropped in v1", () => {
+    expect(css(".x { color: var(--accent); }")).toBe("");
+  });
+
+  test("position:fixed / sticky are denied (clickjacking)", () => {
+    expect(css(".x { position: fixed; top: 0; left: 0; }")).toBe("");
+    expect(css(".x { position: sticky; }")).toBe("");
+  });
+
+  test("position:absolute / relative are allowed (boxed by scope)", () => {
+    expect(css(".x { position: absolute; }")).toContain("position: absolute");
+    expect(css(".x { position: relative; }")).toContain("position: relative");
+  });
+
+  test("@media (and any at-rule with a nested block) is dropped whole", () => {
+    expect(css("@media screen { .x { color: red; } }")).toBe("");
+    expect(css("@font-face { font-family: evil; src: url(x); }")).toBe("");
+  });
+
+  test("content + pseudo-elements are dropped (text injection / defacement)", () => {
+    expect(css(".x::before { content: 'hacked'; }")).toBe("");
+    expect(css(".x { content: 'hi'; }")).toBe("");
+  });
+
+  test("attribute selectors are dropped (exfil-style selectors)", () => {
+    expect(css('.x[href^="http"] { color: red; }')).toBe("");
+  });
+
+  test("-moz-binding / behavior (non-allowlisted props) are dropped", () => {
+    expect(css(".x { -moz-binding: url(evil); }")).toBe("");
+    expect(css(".x { behavior: url(evil.htc); }")).toBe("");
+  });
+});
+
+describe("sanitizeTenantCss — structural robustness", () => {
+  test("unbalanced braces fail closed (drop the rest)", () => {
+    expect(css(".x { color: red;")).toBe("");
+    expect(css(".ok { color: red; } .bad { color: blue;")).toContain(".ok");
+    expect(css(".ok { color: red; } .bad { color: blue;")).not.toContain(".bad");
+  });
+
+  test("a rule with zero valid declarations is dropped", () => {
+    expect(css(".x { unknownprop: 1; }")).toBe("");
+  });
+});
+
+describe("sanitizeTenantCss — valid CSS passes, scoped", () => {
+  test("a plain rule is scoped and preserved", () => {
+    const out = css(".note { color: red; font-size: 1.2rem; }");
+    expect(out).toBe("[data-tenant-content] .note { color: red; font-size: 1.2rem }");
+  });
+
+  test("allowed functions (rgb/rgba/hsl/calc) pass", () => {
+    expect(css(".x { color: rgba(0,0,0,.5); }")).toContain("rgba(0,0,0,.5)");
+    expect(css(".x { width: calc(100% - 10px); }")).toContain("calc(100% - 10px)");
+  });
+
+  test("!important is preserved", () => {
+    expect(css(".x { color: red !important; }")).toContain("color: red !important");
+  });
+
+  test("multiple rules are each scoped", () => {
+    const out = css("h1 { margin: 1rem; } .box { padding: 8px; }");
+    expect(out).toContain("[data-tenant-content] h1");
+    expect(out).toContain("[data-tenant-content] .box");
+  });
+
+  test("universal + html/body are rendered inert via scoping, not bare", () => {
+    expect(css("* { color: red; }")).toBe("[data-tenant-content] * { color: red }");
+    // body is scoped (inert: no <body> inside the container), never emitted bare
+    const body = css("body { color: red; }");
+    expect(body).toBe("[data-tenant-content] body { color: red }");
+    expect(body).not.toMatch(/^body/);
+  });
+
+  test("leading comment is stripped, following rule survives", () => {
+    expect(css("/* theme */ .x { color: red; }")).toContain("color: red");
+  });
+
+  test("over-length input is dropped wholesale", () => {
+    const huge = `.x { color: red; }${" ".repeat(9000)}`;
+    expect(css(huge)).toBe("");
+  });
+});
+
+// Regressions for bypasses surfaced by the adversarial sanitizer workflow.
+describe("sanitizeTenantCss — adversarial regressions", () => {
+  test("leading sibling/child combinator can't escape the scope to host chrome", () => {
+    expect(css("~ .brand-header { color: red; }")).toBe("");
+    expect(css("+ .brand-header { position: absolute; z-index: 999; }")).toBe("");
+    expect(css("~ * { position: absolute; top: 0; width: 100%; height: 100%; }")).toBe("");
+    expect(css("> .x { color: red; }")).toBe("");
+    // one escaping segment in a comma-list drops the whole rule
+    expect(css(".a, ~ .b { color: red; }")).toBe("");
+  });
+
+  test("internal combinators stay in-scope and survive (child works end-to-end)", () => {
+    expect(css(".a > .b { color: red; }")).toBe("[data-tenant-content] .a > .b { color: red }");
+    expect(css(".a ~ .b { color: red; }")).toBe("[data-tenant-content] .a ~ .b { color: red }");
+    expect(css(".nav:nth-child(2) { color: red; }")).toContain(
+      "[data-tenant-content] .nav:nth-child(2)",
+    );
+  });
+
+  test("single-colon pseudo-elements are rejected too (not just ::)", () => {
+    expect(css(":before { color: red; }")).toBe("");
+    expect(css(".x:before { color: red; }")).toBe("");
+    expect(css(".x:after { color: red; }")).toBe("");
+    expect(css(".x:first-line { color: red; }")).toBe("");
+    expect(css("a:hover:before { color: red; }")).toBe("");
+  });
+
+  test("url()/expression() inside a selector is rejected", () => {
+    expect(css(":not(url(x)) { color: red; }")).toBe("");
+    expect(css(":is(expression(1)) { color: red; }")).toBe("");
+  });
+
+  test("overlay attacks survive the sanitizer but are clipped by the container", () => {
+    // The sanitizer allows presentational props; geometric containment is the
+    // container's overflow:hidden (layout.ts), not the sanitizer. Here we prove
+    // the output is still SCOPED (so the clip applies) — not unscoped.
+    const out = css(
+      ".overlay { position: absolute; margin: -100vh; width: 200vw; height: 200vh; z-index: 9999; }",
+    );
+    expect(out).toContain("[data-tenant-content] .overlay");
+    expect(out).not.toMatch(/(^|\n)\s*\.overlay/); // never unscoped
+  });
+});

package/src/page-render/__tests__/markdown.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { renderSafeMarkdown } from "../markdown";
+
+describe("renderSafeMarkdown — XSS-Härtung", () => {
+  test("block-level <script> wird als Text escaped, nicht durchgereicht", () => {
+    const html = renderSafeMarkdown("# Titel\n\n<script>alert(1)</script>");
+    expect(html).not.toContain("<script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+
+  test("inline raw HTML (<img onerror>) wird escaped", () => {
+    const html = renderSafeMarkdown('Text <img src=x onerror="alert(1)"> mehr');
+    expect(html).not.toContain("<img");
+    expect(html).toContain("&lt;img");
+  });
+
+  test("javascript:-Link-href wird neutralisiert", () => {
+    const html = renderSafeMarkdown("[klick](javascript:alert(1))");
+    expect(html.toLowerCase()).not.toContain("javascript:");
+    expect(html).toContain('href="#"');
+  });
+
+  test("data:-Image-src wird neutralisiert", () => {
+    const html = renderSafeMarkdown("![x](data:text/html;base64,PHNjcmlwdD4=)");
+    expect(html.toLowerCase()).not.toContain("data:");
+  });
+
+  test("https/mailto/relative Hrefs bleiben erhalten", () => {
+    expect(renderSafeMarkdown("[a](https://example.com)")).toContain('href="https://example.com"');
+    expect(renderSafeMarkdown("[b](mailto:x@y.de)")).toContain('href="mailto:x@y.de"');
+    expect(renderSafeMarkdown("[c](/impressum)")).toContain('href="/impressum"');
+  });
+
+  test("normale Markdown-Struktur bleibt intakt", () => {
+    const html = renderSafeMarkdown("# H1\n\n**fett** und `code`\n\n- a\n- b");
+    expect(html).toContain("<h1");
+    expect(html).toContain("<strong>fett</strong>");
+    expect(html).toContain("<code>code</code>");
+    expect(html).toContain("<li>a</li>");
+  });
+});

package/src/page-render/branding.ts

@@ -0,0 +1,99 @@
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+
+// Tenant-branding tokens resolved at render time (managed-pages reads them
+// from config — see managed-pages/branding.ts). Empty string = "unset, use
+// the base-layout default" (mirrors the publicstatus convention). Every value
+// is tenant-supplied + untrusted, so it is re-validated/escaped HERE before it
+// touches HTML/CSS output — independent of the write-time config `pattern`
+// gate. Defense-in-depth: a value could have been seeded or migrated around
+// the write path, so the render path never trusts the stored string.
+export type BrandingTokens = {
+  readonly title: string;
+  readonly description: string;
+  readonly siteUrl: string;
+  readonly accentColor: string;
+  readonly logoUrl: string;
+  readonly layoutPreset: string;
+  // RAW, untrusted tenant CSS — "" unless the custom-css capability is gated on
+  // (managed-pages allowCustomCss + the per-tenant toggle). It is NOT pre-
+  // sanitized here: the layer that emits it MUST run it through
+  // sanitizeTenantCss(value, scopeSelector) with its own scope (the default
+  // wrapInLayout does). Scoping is a render concern, so sanitization lives at
+  // emit, not in transport.
+  readonly customCss: string;
+};
+
+export const EMPTY_BRANDING: BrandingTokens = {
+  title: "",
+  description: "",
+  siteUrl: "",
+  accentColor: "",
+  logoUrl: "",
+  layoutPreset: "",
+  customCss: "",
+};
+
+// CSS hex color: #rgb | #rrggbb | #rrggbbaa, anchored. Contains no `;`/`}`/`<`/
+// whitespace, so a value passing this can never break out of `:root{--x:V}`
+// or the surrounding <style>…</style>. Linear → ReDoS-safe on untrusted input.
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+// https URL, length-bounded, no whitespace/quote/angle chars. Anchored +
+// linear (no backtracking).
+const HTTPS_URL = /^https:\/\/[^\s"'<>]{1,2000}$/;
+
+export function isSafeHexColor(value: string): boolean {
+  return HEX_COLOR.test(value);
+}
+
+export function isSafeHttpsUrl(value: string): boolean {
+  return HTTPS_URL.test(value);
+}
+
+// Layout preset → body max-width. Unknown/empty → default. Keeps the
+// `branding-layout-preset` config key live (read at render, not a declared-
+// but-unread key).
+const LAYOUT_MAX_WIDTH: Record<string, string> = {
+  minimal: "640px",
+  centered: "720px",
+  wide: "1100px",
+};
+
+export function layoutMaxWidth(preset: string): string {
+  return LAYOUT_MAX_WIDTH[preset] ?? "720px";
+}
+
+// Scoped CSS-variable block, injected after the base <style> so its :root
+// declarations override the defaults. Only emits a var whose source value
+// passes re-validation — an invalid accent color is dropped (base CSS keeps
+// its var() fallback), never injected. The id is stable so an app's custom
+// layout can target/override it.
+export function brandingStyleBlock(tokens: BrandingTokens): string {
+  const decls: string[] = [];
+  if (isSafeHexColor(tokens.accentColor)) {
+    decls.push(`--accent:${tokens.accentColor}`);
+  }
+  decls.push(`--page-max-width:${layoutMaxWidth(tokens.layoutPreset)}`);
+  return `<style id="tenant-theme">:root{${decls.join(";")}}</style>`;
+}
+
+// Optional branded page header (logo + title). The logo is only emitted for a
+// re-validated https URL, escaped as an HTML attribute; an invalid/non-https
+// URL is dropped. A re-validated https siteUrl turns the header into a
+// home-link. Returns "" when there is nothing to show.
+export function brandingHeaderHtml(tokens: BrandingTokens): string {
+  const parts: string[] = [];
+  if (isSafeHttpsUrl(tokens.logoUrl)) {
+    const alt = tokens.title ? escapeHtmlAttr(tokens.title) : "logo";
+    parts.push(`<img class="brand-logo" src="${escapeHtmlAttr(tokens.logoUrl)}" alt="${alt}">`);
+  }
+  if (tokens.title) {
+    parts.push(`<span class="brand-title">${escapeHtml(tokens.title)}</span>`);
+  }
+  if (parts.length === 0) return "";
+
+  const inner = parts.join("\n");
+  if (isSafeHttpsUrl(tokens.siteUrl)) {
+    return `<header class="brand-header"><a href="${escapeHtmlAttr(tokens.siteUrl)}">${inner}</a></header>`;
+  }
+  return `<header class="brand-header">${inner}</header>`;
+}