@alpaca-headless/dynamic-renderings-engine 1.0.4694

package/dist/css-policy/css-policy.d.mts

@@ -0,0 +1,13 @@
+// Types for css-policy.mjs (the engine bundles the same module).
+export type CssDiagnostic = { severity?: string; file?: string; line?: number; column?: number; message: string };
+export declare const LAYER: string;
+export declare function normalizeRenderingId(id: string): string;
+export declare function scopeSelectorFor(renderingId: string): string;
+export declare function namePrefixFor(renderingId: string): string;
+export declare function scopeCss(rawCss: string, renderingId: string): { css: string; errors: CssDiagnostic[] };
+export declare function verifyScopedCss(css: string, renderingId: string, maxBytes?: number): { ok: boolean; errors: CssDiagnostic[] };
+export declare function normalizeThemeTokens(text: string | null | undefined): string;
+export declare function parseThemeTokens(
+  text: string | null | undefined,
+  maxBytes?: number,
+): { ok: boolean; declarations: { name: string; value: string }[]; css: string; errors: CssDiagnostic[] };

package/dist/css-policy/css-policy.mjs

@@ -0,0 +1,396 @@
+// Stylesheet policy for dynamic renderings, shared by the rendering hosts and the render
+// worker (which bundles this module from @alpaca-headless/dynamic-renderings-engine/css-policy):
+//   - the worker's build calls scopeCss() on Tailwind's output,
+//   - the host calls verifyScopedCss() before inserting a stylesheet, and drops the whole
+//     stylesheet on any violation.
+//
+// A rendering's stylesheet may only style descendants of its own wrapper element
+// ([data-parhelia-rendering="<id>"]), may not declare document-global names, and may not
+// load anything (no url(), image-set(), @import, @font-face, backslash escapes).
+import postcss from "postcss";
+import selectorParser from "postcss-selector-parser";
+import valueParser from "postcss-value-parser";
+
+export const LAYER = "dynamic-renderings";
+
+const CONTAINER_AT_RULES = new Set(["media", "supports", "container", "starting-style"]);
+
+const ALLOWED_FUNCTIONS = new Set([
+  "", // plain parentheses
+  "var", "calc", "calc-size", "min", "max", "clamp", "round", "mod", "rem", "abs", "sign",
+  "rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color", "color-mix", "light-dark",
+  "linear-gradient", "radial-gradient", "conic-gradient",
+  "repeating-linear-gradient", "repeating-radial-gradient", "repeating-conic-gradient",
+  "translate", "translatex", "translatey", "translatez", "translate3d",
+  "rotate", "rotatex", "rotatey", "rotatez", "rotate3d",
+  "scale", "scalex", "scaley", "scalez", "scale3d",
+  "skew", "skewx", "skewy", "matrix", "matrix3d", "perspective",
+  "cubic-bezier", "steps", "linear",
+  "repeat", "minmax", "fit-content",
+  "blur", "brightness", "contrast", "drop-shadow", "grayscale", "hue-rotate", "invert", "opacity", "saturate", "sepia",
+  "inset", "circle", "ellipse", "polygon", "rect", "xywh",
+  "counter", "counters",
+]);
+
+const IMAGE_PROPERTIES = new Set([
+  "background", "background-image", "border-image", "border-image-source", "mask", "mask-image",
+  "mask-border", "mask-border-source", "list-style", "list-style-image", "cursor", "shape-outside",
+  "filter", "backdrop-filter", "clip-path", "src", "marker", "marker-start", "marker-mid", "marker-end",
+]);
+
+const FORBIDDEN_PSEUDOS = new Set([":root", ":host", ":host-context", "::slotted", ":scope"]);
+
+export function normalizeRenderingId(id) {
+  return String(id).replace(/[{}]/g, "").toLowerCase();
+}
+
+export function scopeSelectorFor(renderingId) {
+  return `[data-parhelia-rendering="${normalizeRenderingId(renderingId)}"]`;
+}
+
+export function namePrefixFor(renderingId) {
+  return `pr${normalizeRenderingId(renderingId).replace(/-/g, "").slice(0, 8)}-`;
+}
+
+function problem(errors, message, node) {
+  const line = node && node.source && node.source.start ? node.source.start.line : undefined;
+  errors.push({ severity: "error", file: "styles.css", line, column: undefined, message });
+}
+
+// Tailwind registers its variables with @property { syntax: "<length>"; ... }. That descriptor,
+// and only there, may hold "<": a quoted list of data type names, nothing else.
+const PROPERTY_SYNTAX = /^"(\*|<[a-z-]+>[+#]?(\s*\|\s*<[a-z-]+>[+#]?)*)"$/i;
+
+function isPropertySyntax(prop, value, node) {
+  const parent = node && node.parent;
+  return (
+    prop.toLowerCase() === "syntax" &&
+    parent && parent.type === "atrule" && parent.name.toLowerCase() === "property" &&
+    PROPERTY_SYNTAX.test(value.trim())
+  );
+}
+
+function checkValue(prop, value, errors, node) {
+  if (isPropertySyntax(prop, value, node)) return;
+  if (value.includes("\\")) {
+    problem(errors, `CSS value for ${prop} contains a backslash escape, which is not allowed.`, node);
+    return;
+  }
+  if (value.includes("<")) {
+    problem(errors, `CSS value for ${prop} contains "<", which is not allowed.`, node);
+    return;
+  }
+  const lowerProp = prop.toLowerCase();
+  valueParser(value).walk((part) => {
+    if (part.type === "function") {
+      const name = part.value.toLowerCase();
+      if (!ALLOWED_FUNCTIONS.has(name)) {
+        problem(errors, `CSS function ${part.value}() in ${prop} is not allowed.`, node);
+      }
+    } else if (part.type === "string" && IMAGE_PROPERTIES.has(lowerProp)) {
+      problem(errors, `Quoted strings are not allowed in ${prop}.`, node);
+    }
+  });
+}
+
+function checkProperty(prop, errors, node) {
+  if (!/^(--[A-Za-z0-9_-]+|-?[a-z][a-z-]*)$/.test(prop)) {
+    problem(errors, `CSS property name ${JSON.stringify(prop)} is not allowed.`, node);
+  }
+}
+
+function renameInValue(value, rename) {
+  const parsed = valueParser(value);
+  let changed = false;
+  parsed.walk((part) => {
+    if (part.type === "word") {
+      const next = rename(part.value);
+      if (next !== part.value) {
+        part.value = next;
+        changed = true;
+      }
+    }
+  });
+  return changed ? valueParser.stringify(parsed.nodes) : value;
+}
+
+function isInsideKeyframes(node) {
+  for (let parent = node.parent; parent; parent = parent.parent) {
+    if (parent.type === "atrule" && /keyframes$/i.test(parent.name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Turns Tailwind's output for one rendering into a stylesheet that can only affect that
+ * rendering. Returns { css, errors }; any error means the build must fail.
+ */
+export function scopeCss(rawCss, renderingId) {
+  const errors = [];
+  const scope = scopeSelectorFor(renderingId);
+  const prefix = namePrefixFor(renderingId);
+  let root;
+  try {
+    root = postcss.parse(rawCss);
+  } catch (err) {
+    return { css: "", errors: [{ severity: "error", file: "styles.css", message: `CSS could not be parsed: ${err.message}` }] };
+  }
+
+  root.walkComments((comment) => comment.remove());
+
+  // Flatten every @layer: a rendering must not be able to (re)order the document cascade.
+  const layers = [];
+  root.walkAtRules(/^layer$/i, (at) => layers.push(at));
+  for (const at of layers.reverse()) {
+    if (at.nodes && at.nodes.length) at.replaceWith(at.nodes);
+    else at.remove();
+  }
+
+  const keyframeNames = new Set();
+  const properties = [];
+  const keyframes = [];
+  const renameCustom = (name) => (name.startsWith("--tw-") ? `--${prefix}${name.slice(5)}` : name);
+
+  root.walkAtRules((at) => {
+    const name = at.name.toLowerCase();
+    if (CONTAINER_AT_RULES.has(name)) {
+      if (at.params.includes("\\") || /<\//.test(at.params)) problem(errors, `@${at.name} condition is not allowed.`, at);
+      return;
+    }
+    if (name === "keyframes") {
+      const original = at.params.trim().replace(/^["']|["']$/g, "");
+      if (!/^[A-Za-z0-9_-]+$/.test(original)) {
+        problem(errors, `@keyframes name ${JSON.stringify(original)} is not allowed.`, at);
+        return;
+      }
+      keyframeNames.add(original);
+      at.params = `${prefix}${original}`;
+      keyframes.push(at);
+      return;
+    }
+    if (name === "property") {
+      const original = at.params.trim();
+      if (!original.startsWith("--tw-")) {
+        problem(errors, `@property ${original} is not allowed; only Tailwind's own properties are.`, at);
+        return;
+      }
+      at.params = renameCustom(original);
+      properties.push(at);
+      return;
+    }
+    problem(errors, `@${at.name} is not allowed in rendering styles.`, at);
+  });
+
+  root.walkDecls((decl) => {
+    checkProperty(decl.prop, errors, decl);
+    decl.prop = renameCustom(decl.prop);
+    decl.value = renameInValue(decl.value, (word) => (word.startsWith("--tw-") ? renameCustom(word) : word));
+    if (/^animation(-name)?$/i.test(decl.prop)) {
+      decl.value = renameInValue(decl.value, (word) => (keyframeNames.has(word) ? `${prefix}${word}` : word));
+    }
+    checkValue(decl.prop, decl.value, errors, decl);
+  });
+
+  root.walkRules((rule) => {
+    if (isInsideKeyframes(rule)) return;
+    if (rule.selector.includes("<")) {
+      problem(errors, "Selectors containing \"<\" are not allowed.", rule);
+      return;
+    }
+    const scoped = [];
+    try {
+      selectorParser((selectors) => {
+        selectors.each((selector) => {
+          const first = selector.first;
+          if (!first) return;
+          if (first.type === "combinator") {
+            problem(errors, `Selector ${selector.toString().trim()} starts with a combinator.`, rule);
+            return;
+          }
+          let bad = false;
+          selector.walk((part) => {
+            if (part.type === "nesting") bad = "uses nesting (&)";
+            else if (part.type === "pseudo" && FORBIDDEN_PSEUDOS.has(part.value.toLowerCase())) bad = `uses ${part.value}`;
+            else if (part.type === "tag" && /^(html|body|head)$/i.test(part.value)) bad = `targets <${part.value}>`;
+          });
+          if (bad) {
+            problem(errors, `Selector ${selector.toString().trim()} ${bad}.`, rule);
+            return;
+          }
+          scoped.push(`${scope} ${selector.toString().trim()}`);
+        });
+      }).processSync(rule.selector);
+    } catch (err) {
+      problem(errors, `Selector ${rule.selector} could not be parsed: ${err.message}`, rule);
+      return;
+    }
+    if (scoped.length === 0) rule.remove();
+    else rule.selector = scoped.join(",\n");
+  });
+
+  if (errors.length) return { css: "", errors };
+
+  for (const at of [...properties, ...keyframes]) at.remove();
+  const layer = postcss.atRule({ name: "layer", params: LAYER });
+  layer.append(root.nodes.map((n) => n.clone()));
+  const out = postcss.root();
+  if (layer.nodes.length) out.append(layer);
+  out.append(properties);
+  out.append(keyframes);
+  const css = out.toString();
+
+  const verified = verifyScopedCss(css, renderingId);
+  return verified.ok ? { css, errors: [] } : { css: "", errors: verified.errors };
+}
+
+/**
+ * Checks a stored stylesheet against the invariants scopeCss() guarantees. The host runs this
+ * before every insertion; ok:false means the stylesheet must not be inserted at all.
+ */
+export function verifyScopedCss(css, renderingId, maxBytes = 65536) {
+  const errors = [];
+  if (typeof css !== "string") return { ok: false, errors: [{ message: "Stylesheet is not a string." }] };
+  if (css.length > maxBytes) problem(errors, `Stylesheet exceeds ${maxBytes} bytes.`);
+  if (/<\//.test(css)) problem(errors, "Stylesheet contains \"</\".");
+  if (errors.length) return { ok: false, errors };
+
+  const scope = scopeSelectorFor(renderingId);
+  const prefix = namePrefixFor(renderingId);
+  const id = normalizeRenderingId(renderingId);
+  let root;
+  try {
+    root = postcss.parse(css);
+  } catch (err) {
+    return { ok: false, errors: [{ message: `Stylesheet could not be parsed: ${err.message}` }] };
+  }
+
+  root.each((node) => {
+    if (node.type === "comment") return;
+    if (node.type !== "atrule") return problem(errors, "Top-level rules must sit inside the rendering layer.", node);
+    const name = node.name.toLowerCase();
+    if (name === "layer" && node.params.trim() === LAYER && node.nodes) return;
+    if (name === "property" && node.params.trim().startsWith(`--${prefix}`)) return;
+    if (name === "keyframes" && node.params.trim().startsWith(prefix)) return;
+    problem(errors, `Top-level @${node.name} ${node.params} is not allowed.`, node);
+  });
+
+  root.walkAtRules((at) => {
+    const name = at.name.toLowerCase();
+    if (at.parent === root) return;
+    if (CONTAINER_AT_RULES.has(name)) {
+      if (at.params.includes("\\")) problem(errors, `@${at.name} condition contains an escape.`, at);
+      return;
+    }
+    if (name === "keyframes" || name === "property" || name === "layer") {
+      problem(errors, `@${at.name} must not be nested.`, at);
+      return;
+    }
+    problem(errors, `@${at.name} is not allowed.`, at);
+  });
+
+  root.walkDecls((decl) => {
+    checkProperty(decl.prop, errors, decl);
+    checkValue(decl.prop, decl.value, errors, decl);
+  });
+
+  root.walkRules((rule) => {
+    if (isInsideKeyframes(rule)) return;
+    if (rule.selector.includes("<")) {
+      problem(errors, "Selector contains \"<\".", rule);
+      return;
+    }
+    try {
+      selectorParser((selectors) => {
+        selectors.each((selector) => {
+          const nodes = selector.nodes;
+          const head = nodes[0];
+          const next = nodes[1];
+          const scoped =
+            head &&
+            head.type === "attribute" &&
+            head.attribute === "data-parhelia-rendering" &&
+            head.operator === "=" &&
+            head.value === id &&
+            next &&
+            next.type === "combinator" &&
+            (next.value.trim() === "" || next.value.trim() === ">");
+          if (!scoped) problem(errors, `Selector ${selector.toString().trim()} is not confined to ${scope}.`, rule);
+          selector.walk((part) => {
+            if (part.type === "nesting") problem(errors, "Selector uses nesting.", rule);
+            if (part.type === "pseudo" && FORBIDDEN_PSEUDOS.has(part.value.toLowerCase())) {
+              problem(errors, `Selector uses ${part.value}.`, rule);
+            }
+          });
+        });
+      }).processSync(rule.selector);
+    } catch (err) {
+      problem(errors, `Selector could not be parsed: ${err.message}`, rule);
+    }
+    let parent = rule.parent;
+    while (parent && parent !== root) {
+      if (parent.type === "atrule" && parent.name.toLowerCase() === "layer" && parent.parent === root) break;
+      parent = parent.parent;
+    }
+    if (!parent || parent === root) problem(errors, "Rule sits outside the rendering layer.", rule);
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+const THEME_TOKEN_NAME = /^--[A-Za-z][A-Za-z0-9-]{0,63}$/;
+const RESERVED_TOKEN_PREFIXES = ["--tw-", "--pr", "--parhelia", "--a-editor", "--alpaca", "--sc-"];
+
+/** LF-normalized, trimmed theme token text: what the build hashes (the CM hashes the same). */
+export function normalizeThemeTokens(text) {
+  return String(text || "").replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+}
+
+/**
+ * A theme rendering's tokens: custom property declarations only, e.g.
+ *   --color-brand: oklch(0.62 0.19 255);
+ *   --font-display: "Space Grotesk", sans-serif;
+ * Values follow the stylesheet value rules (no url(), image-set(), backslash or "<"). Names
+ * reserved for Tailwind internals, rendering prefixes and the editor are refused. The build
+ * adds the tokens to Tailwind's @theme (so utilities such as bg-brand exist) and the host
+ * declares them on :root.
+ */
+export function parseThemeTokens(text, maxBytes = 16384) {
+  const errors = [];
+  const source = normalizeThemeTokens(text);
+  const fail = () => ({ ok: false, declarations: [], css: "", errors: errors.map((e) => ({ ...e, file: "theme" })) });
+  if (!source) return { ok: true, declarations: [], css: "", errors: [] };
+  if (source.length > maxBytes) {
+    problem(errors, `Theme tokens exceed ${maxBytes} bytes.`);
+    return fail();
+  }
+  let root;
+  try {
+    root = postcss.parse(`:root{${source}}`);
+  } catch (err) {
+    problem(errors, `Theme tokens could not be parsed: ${err.reason || err.message}`);
+    return fail();
+  }
+  const rule = root.nodes.length === 1 && root.nodes[0].type === "rule" ? root.nodes[0] : null;
+  if (!rule) {
+    problem(errors, "Theme tokens must be plain declarations such as --color-brand: #0a84ff;");
+    return fail();
+  }
+  const declarations = [];
+  rule.each((node) => {
+    if (node.type === "comment") return;
+    if (node.type !== "decl") return problem(errors, "Theme tokens may only contain custom property declarations.", node);
+    const name = node.prop;
+    if (!THEME_TOKEN_NAME.test(name)) return problem(errors, `${JSON.stringify(name)} is not a theme token name (use --name-with-dashes).`, node);
+    if (RESERVED_TOKEN_PREFIXES.some((prefix) => name.toLowerCase().startsWith(prefix))) {
+      return problem(errors, `Theme token ${name} uses a reserved prefix.`, node);
+    }
+    if (node.important) return problem(errors, `!important is not allowed in ${name}.`, node);
+    const value = node.value.trim();
+    if (!value) return problem(errors, `Theme token ${name} has no value.`, node);
+    const before = errors.length;
+    checkValue(name, value, errors, node);
+    if (errors.length === before) declarations.push({ name, value });
+  });
+  if (errors.length) return fail();
+  return { ok: true, declarations, css: declarations.map((d) => `${d.name}: ${d.value};`).join("\n"), errors: [] };
+}