@caelo-cms/shared 0.11.1 → 0.11.2

package/src/preview-compose.ts

@@ -30,7 +30,7 @@ import type { ModuleFieldKind } from "./content.js";
 import { findInteractionIds, interactionAssets } from "./interactions.js";
 import { type LinkResolver, resolveLinkRefsInHtml } from "./link-refs.js";
 import type { ListPageContext } from "./lists/resolve.js";
-import { tagModuleId } from "./module-id-tag.js";
+import { MODULE_ID_ATTRIBUTE, tagModuleId } from "./module-id-tag.js";
 import {
   type NestedModuleResource,
   type NestedRenderFailure,
@@ -530,12 +530,28 @@ function recordFailures(
  * A module withheld from this render, as resolved by the plugin host
  * (#450). The composer never decides this — it only knows the verdict.
  */
-export interface ComposeDeferral {
+export type ComposeDeferral = ComposeGateDeferral | ComposeOmitDeferral;
+
+/** Withheld behind a placeholder until the plugin's runtime releases it. */
+export interface ComposeGateDeferral {
   readonly pluginSlug: string;
   readonly reason: string;
   readonly placeholderModuleSlug: string;
   readonly placeholderHtml: string;
   readonly placeholderCss: string;
+  readonly omit?: undefined;
+}
+
+/**
+ * Left out entirely: nothing on the visitor's side can release it. The
+ * plugin host passes the editor notice only to the editor preview; a
+ * build gets `null` and the module's place stays empty.
+ */
+export interface ComposeOmitDeferral {
+  readonly pluginSlug: string;
+  readonly reason: string;
+  readonly omit: true;
+  readonly editorNotice: { readonly html: string; readonly css: string } | null;
 }
 
 /**
@@ -566,10 +582,8 @@ function wrapDeferredModule(
   moduleHtml: string,
   module: Pick<ComposeModule, "moduleId" | "slug" | "css" | "js">,
   nestedModules: readonly Pick<NestedModuleResource, "moduleId" | "css" | "js">[],
-  deferral: ComposeDeferral,
+  deferral: ComposeGateDeferral,
 ): string {
-  const attr = (v: string): string =>
-    v.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
   // Inside the inert <template>, only an element's own end tag ends a
   // <style> / <script>; a `</template` there is text. So CSS needs just
   // its own close escaped, JS that could end its <script> ships base64
@@ -598,6 +612,25 @@ function wrapDeferredModule(
   ].join("");
 }
 
+/**
+ * Emit an omitted module: nothing in a build, the editor notice in the
+ * preview. The module's markup, CSS and JS never reach the page — not
+ * even in a `<template>`, since nothing would ever clone it out. The
+ * notice carries the module id (and its slug as the label) so the
+ * editor's chat affordances reference the module it stands in for.
+ */
+function omittedModuleNotice(
+  module: Pick<ComposeModule, "moduleId" | "slug">,
+  deferral: ComposeOmitDeferral,
+): string {
+  if (deferral.editorNotice === null) return "";
+  return `<div data-caelo-deferred="${attr(deferral.pluginSlug)}" data-reason="${attr(deferral.reason)}" data-module="${attr(module.slug)}" data-caelo-deferred-omitted ${MODULE_ID_ATTRIBUTE}="${attr(module.moduleId)}" aria-label="${attr(module.slug)}">${deferral.editorNotice.html}</div>`;
+}
+
+function attr(v: string): string {
+  return v.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+
 export interface ComposeLayoutBlock {
   readonly blockName: string;
   readonly modules: readonly ComposeModule[];
@@ -693,9 +726,9 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
   // Duplicate rule blocks made the cascade order-dependent and bloated
   // every page the same module appeared on twice.
   const seenAssetModules = new Set<string>();
-  // Placeholder CSS, keyed by placeholder slug: one withheld module's
-  // placeholder used on five placements is emitted once.
-  const deferredCss = new Map<string, string>();
+  // Placeholder and notice CSS: one withheld module's placeholder used
+  // on five placements is emitted once.
+  const deferredCss = new Set<string>();
   const moduleFailures: ComposeModuleFailure[] = [];
   // Nested modules rendered since the last asset flush (see flushNestedAssets).
   const nestedAssetIds: string[] = [];
@@ -734,7 +767,11 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     }
     const tagged = tagModuleId(baseHtml, m.moduleId);
     if (!deferral) return tagged;
-    deferredCss.set(deferral.placeholderModuleSlug, deferral.placeholderCss);
+    if (deferral.omit) {
+      if (deferral.editorNotice) deferredCss.add(deferral.editorNotice.css);
+      return omittedModuleNotice(m, deferral);
+    }
+    deferredCss.add(deferral.placeholderCss);
     const gatedNested = [...gatedNestedIds].map((id) => {
       const nested = input.nestedModules?.getModule(id);
       // renderModuleFields resolved every id it reports through this
@@ -791,7 +828,7 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     flushNestedAssets();
   }
 
-  for (const css of deferredCss.values()) {
+  for (const css of deferredCss) {
     if (css.trim().length > 0) cssParts.push(css);
   }
 

package/src/theme-importers/__tests__/proto-pollution.test.ts

@@ -10,6 +10,7 @@
 import { describe, expect, it } from "bun:test";
 import { isUnsafeKey } from "../../safe-keys.js";
 import { applyDtcgWrites, removeDtcgPath } from "../../themes.js";
+import { UnknownTokenName } from "../../themes-errors.js";
 import { importTailwind } from "../tailwind.js";
 
 describe("isUnsafeKey", () => {
@@ -41,10 +42,19 @@ describe("importTailwind prototype-pollution guard (S5)", () => {
 });
 
 describe("applyDtcgWrites / setLeafAtPath path guard (S5)", () => {
-  it("rejects a write whose path contains __proto__ (no pollution, no write)", () => {
-    const out = applyDtcgWrites({}, { "a.__proto__.polluted": "x" }, {});
+  it("refuses a write whose path contains __proto__, naming the path (no pollution)", () => {
+    expect(() => applyDtcgWrites({}, { "a.__proto__.polluted": "x" }, {})).toThrow(
+      /UnknownTokenName: cannot infer canonical path for 'a\.__proto__\.polluted'/,
+    );
     expect(({} as Record<string, unknown>).polluted).toBeUndefined();
-    expect(out).not.toHaveProperty("a");
+  });
+
+  it("refuses constructor/prototype segments, including as the leaf", () => {
+    expect(() => applyDtcgWrites({}, { "color.constructor": "#fff" }, {})).toThrow(
+      UnknownTokenName,
+    );
+    expect(() => applyDtcgWrites({}, { "prototype.x": "#fff" }, {})).toThrow(UnknownTokenName);
+    expect(({} as Record<string, unknown>).x).toBeUndefined();
   });
 
   it("still applies a legitimate dotted write", () => {

package/src/theme-render-sanitize.test.ts

@@ -38,6 +38,14 @@ describe("renderThemeCss CSS-token sanitization (S6)", () => {
     expect(css).not.toContain("-->");
   });
 
+  it("drops every < and > in one pass, so no nesting re-creates a breakout", () => {
+    for (const hostile of ["<</style>/style>", "<<!--!---->>", "</sty</style>le>", "a--!>b"]) {
+      const css = renderThemeCss(fontDoc(hostile));
+      expect(css).not.toMatch(/[<>]/);
+      expect(css.toLowerCase()).not.toContain("</style");
+    }
+  });
+
   it("leaves a normal fontFamily untouched", () => {
     const css = renderThemeCss(fontDoc("Inter, sans-serif"));
     expect(css).toContain("Inter, sans-serif");

package/src/theme-render.ts

@@ -519,16 +519,17 @@ function asString(value: unknown): string {
  * CSS values are otherwise unrestricted in character set (font-family
  * names legitimately contain quotes, commas, parens, hyphens), so we
  * don't HTML-encode broadly — that would break perfectly-valid
- * `font-family: "Segoe UI", sans-serif` declarations. Instead, scrub
- * the two sequences that let an attacker break out of the surrounding
- * `<style>…</style>` context:
+ * `font-family: "Segoe UI", sans-serif` declarations. Instead, drop the
+ * single characters that let a value leave its context:
  *
- *   - `</style` (case-insensitive) — premature end-tag would close
- *     the style block and let everything after it parse as HTML
- *     (`fontFamily: "Inter</style><script>alert(1)</script>"`).
- *   - `<!--` / `-->` — CDO/CDC tokens; some HTML parsers treat them
- *     specially inside `<style>` and they're never valid in a real
- *     CSS value anyway.
+ *   - `<` and `>` — every way out of the surrounding `<style>…</style>`
+ *     starts with one (`</style`, `<!--`, `-->`, `--!>`), and no color,
+ *     dimension, shadow or font name contains them. Removing single
+ *     characters cannot re-create a removed sequence, so one pass is
+ *     complete (a sequence-based scrub needs a fixed-point loop, which
+ *     CodeQL's js/incomplete-multi-character-sanitization cannot see).
+ *   - `;`, `{`, `}` — they would end the declaration or the rule and
+ *     inject CSS of the value's choosing.
  *
  * The themeColorToken / themeDimensionToken Zod regexes already
  * constrain those token types to character sets that exclude `<`, so
@@ -536,21 +537,5 @@ function asString(value: unknown): string {
  * (`typography.X.fontFamily`, `$description` if it ever lands in CSS).
  */
 function sanitizeCssTokenValue(value: string): string {
-  // Run to a fixed point: removing one sequence can re-create another
-  // (e.g. `<!--</style>-->` → `</style` only appears after the comment
-  // tokens go), which a single pass would leave behind (CodeQL
-  // js/incomplete-multi-character-sanitization). `--!>` is the HTML5
-  // alternative comment-close and must be scrubbed alongside `-->`
-  // (CodeQL js/bad-tag-filter).
-  let out = value;
-  let prev: string;
-  do {
-    prev = out;
-    out = out
-      .replace(/<\/style/gi, "")
-      .replace(/<!--/g, "")
-      .replace(/--!?>/g, "")
-      .replace(/[;{}]/g, "");
-  } while (out !== prev);
-  return out;
+  return value.replace(/[<>;{}]/g, "");
 }

package/src/themes.ts

@@ -880,21 +880,26 @@ function setLeafAtPath(doc: Record<string, unknown>, path: string, leaf: unknown
   const parts = path.split(".");
   // The dotted path comes from the caller's `writes` map (form / AI input),
   // so a segment like `__proto__` or `constructor` would let the walk below
-  // (`cur[k] = {}`, `cur[last] = leaf`) pollute the prototype chain (CodeQL
-  // js/prototype-pollution-utility). Reject the whole write on any unsafe
-  // segment rather than partially applying it.
-  if (parts.some(isUnsafeKey)) return;
+  // (`cur[k] = {}`, `cur[last] = leaf`) pollute the prototype chain. No
+  // token is named that, so the write fails loudly instead of being dropped
+  // (CLAUDE.md §2). The comparison sits inline at the assignment so CodeQL's
+  // js/prototype-pollution-utility sees the guard.
   let cur: Record<string, unknown> = doc;
-  for (let i = 0; i < parts.length - 1; i++) {
+  for (let i = 0; i < parts.length; i++) {
     const k = parts[i];
     if (!k) continue;
+    if (k === "__proto__" || k === "constructor" || k === "prototype") {
+      throw new UnknownTokenName(path, []);
+    }
+    if (i === parts.length - 1) {
+      cur[k] = leaf;
+      return;
+    }
     if (cur[k] === undefined || cur[k] === null || typeof cur[k] !== "object") {
       cur[k] = {};
     }
     cur = cur[k] as Record<string, unknown>;
   }
-  const last = parts[parts.length - 1];
-  if (last) cur[last] = leaf;
 }
 
 /**

package/src/version.ts

@@ -22,7 +22,7 @@
  * follow standard SemVer.
  */
 
-export const CAELO_VERSION = "0.11.1";
+export const CAELO_VERSION = "0.11.2";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this