@cosmicdrift/kumiko-headless 0.165.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.165.0",
+  "version": "2.0.0",
   "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.165.0",
+    "@cosmicdrift/kumiko-framework": "2.0.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

package/src/dispatcher/index.ts

@@ -13,3 +13,4 @@ export type {
   WriteOpts,
   WriteResult,
 } from "./types";
+export { StreamFrame, type StreamFrameEvent } from "./types";

package/src/dispatcher/types.ts

@@ -153,6 +153,18 @@ export type StreamOpts = {
   readonly signal?: AbortSignal;
 };
 
+// SSE frame event names for POST /api/stream — shared across the server route,
+// the live-dispatcher wire parser, and their tests so a typo on one side
+// fails the type-checker instead of the integration test.
+export const StreamFrame = {
+  chunk: "chunk",
+  ping: "ping",
+  done: "done",
+  error: "error",
+} as const;
+
+export type StreamFrameEvent = (typeof StreamFrame)[keyof typeof StreamFrame];
+
 // ---------------------------------------------------------------------------
 // The contract
 // ---------------------------------------------------------------------------

package/src/format/escape.ts

@@ -22,3 +22,58 @@ export function escapeXml(s: string): string {
     .replace(/"/g, """)
     .replace(/'/g, "'");
 }
+
+// Strips ASCII control chars + space (codepoints 0x00-0x20 and 0x7f) — the
+// same characters browsers strip before scheme detection. `.trim()` alone
+// only removes leading/trailing whitespace, so a scheme like
+// "java\tscript:" (tab embedded mid-scheme) survives to isSafeHref's regex
+// check below, breaks its character class before the ":", falls through to
+// `return true`, and the browser then normalizes it back to "javascript:"
+// and executes it. Written as a char-code filter rather than a regex range
+// to avoid embedding literal control characters in source.
+export function stripControlChars(value: string): string {
+  let result = "";
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code > 0x20 && code !== 0x7f) result += ch;
+  }
+  return result;
+}
+
+// http(s)/mailto or scheme-less (relative/anchor) allowed; javascript:,
+// data:, vbscript:, etc. rejected. Shared between renderer-web's Link
+// primitive and page-render's server-side markdown renderer (both take
+// untrusted tenant-authored hrefs) — no sanitizer dependency needed for a
+// four-line regex check.
+// Browsers decode HTML character references (:, :, :, 	,
+// 	, ...) while parsing the href attribute, before the URL parser ever
+// sees the value — so "javascript:alert(1)" and "java	script:"
+// both normalize to an executable javascript: URL at click time even though
+// neither contains a literal ":" for the regex below to catch. Decode
+// (not delete) so the scheme check sees what the browser will execute —
+// deleting ":" would leave no colon at all, which reads as a safe
+// scheme-less href, exactly backwards.
+const NAMED_HTML_ENTITY_CHARS: Record<string, string> = {
+  colon: ":",
+  tab: "\t",
+  newline: "\n",
+  semi: ";",
+  amp: "&",
+};
+
+function decodeHtmlEntities(value: string): string {
+  return value.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z][a-z0-9]*);/gi, (match, entity: string) => {
+    if (entity[0] === "#") {
+      const isHex = entity[1]?.toLowerCase() === "x";
+      const code = Number.parseInt(isHex ? entity.slice(2) : entity.slice(1), isHex ? 16 : 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+    }
+    return NAMED_HTML_ENTITY_CHARS[entity.toLowerCase()] ?? match;
+  });
+}
+
+export function isSafeHref(href: string): boolean {
+  const trimmed = stripControlChars(decodeHtmlEntities(href)).toLowerCase();
+  if (!/^[a-z][a-z0-9+.-]*:/.test(trimmed)) return true;
+  return /^(?:https?|mailto):/.test(trimmed);
+}

package/src/format/index.ts

@@ -67,7 +67,7 @@ function formatDateCell(
   }
 }
 
-export { escapeHtml, escapeHtmlAttr, escapeXml } from "./escape";
+export { escapeHtml, escapeHtmlAttr, escapeXml, isSafeHref, stripControlChars } from "./escape";
 export { type HtmlValue, html, RawHtml, raw } from "./html-template";
 export function applyFormatSpec(
   spec: { format: string } & Record<string, unknown>,

package/src/index.ts

@@ -38,6 +38,7 @@ export type {
   WriteOpts,
   WriteResult,
 } from "./dispatcher";
+export { StreamFrame, type StreamFrameEvent } from "./dispatcher";
 export type {
   FieldConditionPredicate,
   FieldConditions,
@@ -59,8 +60,10 @@ export {
   escapeXml,
   type HtmlValue,
   html,
+  isSafeHref,
   RawHtml,
   raw,
+  stripControlChars,
   toInstant,
 } from "./format";
 export type {