@wdprlib/render 2.0.0 → 3.0.0

package/src/escape/css-colors.ts

@@ -0,0 +1,183 @@
+/**
+ * Complete set of CSS Level 4 named colors plus CSS-wide keywords
+ * (`transparent`, `currentcolor`, `inherit`, `initial`, `unset`).
+ */
+import { isValidCssColorFunction } from "./css-color-functions";
+
+const CSS_NAMED_COLORS = new Set([
+  "aliceblue",
+  "antiquewhite",
+  "aqua",
+  "aquamarine",
+  "azure",
+  "beige",
+  "bisque",
+  "black",
+  "blanchedalmond",
+  "blue",
+  "blueviolet",
+  "brown",
+  "burlywood",
+  "cadetblue",
+  "chartreuse",
+  "chocolate",
+  "coral",
+  "cornflowerblue",
+  "cornsilk",
+  "crimson",
+  "cyan",
+  "darkblue",
+  "darkcyan",
+  "darkgoldenrod",
+  "darkgray",
+  "darkgreen",
+  "darkgrey",
+  "darkkhaki",
+  "darkmagenta",
+  "darkolivegreen",
+  "darkorange",
+  "darkorchid",
+  "darkred",
+  "darksalmon",
+  "darkseagreen",
+  "darkslateblue",
+  "darkslategray",
+  "darkslategrey",
+  "darkturquoise",
+  "darkviolet",
+  "deeppink",
+  "deepskyblue",
+  "dimgray",
+  "dimgrey",
+  "dodgerblue",
+  "firebrick",
+  "floralwhite",
+  "forestgreen",
+  "fuchsia",
+  "gainsboro",
+  "ghostwhite",
+  "gold",
+  "goldenrod",
+  "gray",
+  "green",
+  "greenyellow",
+  "grey",
+  "honeydew",
+  "hotpink",
+  "indianred",
+  "indigo",
+  "ivory",
+  "khaki",
+  "lavender",
+  "lavenderblush",
+  "lawngreen",
+  "lemonchiffon",
+  "lightblue",
+  "lightcoral",
+  "lightcyan",
+  "lightgoldenrodyellow",
+  "lightgray",
+  "lightgreen",
+  "lightgrey",
+  "lightpink",
+  "lightsalmon",
+  "lightseagreen",
+  "lightskyblue",
+  "lightslategray",
+  "lightslategrey",
+  "lightsteelblue",
+  "lightyellow",
+  "lime",
+  "limegreen",
+  "linen",
+  "magenta",
+  "maroon",
+  "mediumaquamarine",
+  "mediumblue",
+  "mediumorchid",
+  "mediumpurple",
+  "mediumseagreen",
+  "mediumslateblue",
+  "mediumspringgreen",
+  "mediumturquoise",
+  "mediumvioletred",
+  "midnightblue",
+  "mintcream",
+  "mistyrose",
+  "moccasin",
+  "navajowhite",
+  "navy",
+  "oldlace",
+  "olive",
+  "olivedrab",
+  "orange",
+  "orangered",
+  "orchid",
+  "palegoldenrod",
+  "palegreen",
+  "paleturquoise",
+  "palevioletred",
+  "papayawhip",
+  "peachpuff",
+  "peru",
+  "pink",
+  "plum",
+  "powderblue",
+  "purple",
+  "rebeccapurple",
+  "red",
+  "rosybrown",
+  "royalblue",
+  "saddlebrown",
+  "salmon",
+  "sandybrown",
+  "seagreen",
+  "seashell",
+  "sienna",
+  "silver",
+  "skyblue",
+  "slateblue",
+  "slategray",
+  "slategrey",
+  "snow",
+  "springgreen",
+  "steelblue",
+  "tan",
+  "teal",
+  "thistle",
+  "tomato",
+  "turquoise",
+  "violet",
+  "wheat",
+  "white",
+  "whitesmoke",
+  "yellow",
+  "yellowgreen",
+  "transparent",
+  "currentcolor",
+  "inherit",
+  "initial",
+  "unset",
+]);
+
+/**
+ * Validate that a string is a safe CSS color value.
+ */
+export function isValidCssColor(color: string): boolean {
+  const trimmed = color.trim().toLowerCase();
+
+  if (!trimmed) return false;
+  if (CSS_NAMED_COLORS.has(trimmed)) return true;
+
+  if (/^#[0-9a-f]{3}([0-9a-f])?$/.test(trimmed) || /^#[0-9a-f]{6}([0-9a-f]{2})?$/.test(trimmed)) {
+    return true;
+  }
+
+  if (isValidCssColorFunction(trimmed)) return true;
+
+  return false;
+}
+
+export function sanitizeCssColor(color: string, fallback = "inherit"): string {
+  return isValidCssColor(color) ? color : fallback;
+}

package/src/escape/css-danger.ts

@@ -0,0 +1,22 @@
+import { normalizeCssValue } from "./css-normalize";
+import { isCssUrlAllowed, iterateCssUrls } from "./css-urls";
+
+/**
+ * Check whether a CSS property value contains dangerous patterns that
+ * could enable script execution or disallowed external resource loading.
+ */
+export function isDangerousCssValue(value: string): boolean {
+  const normalized = normalizeCssValue(value);
+
+  for (const { inner, malformed } of iterateCssUrls(normalized)) {
+    if (malformed) return true;
+    if (!isCssUrlAllowed(inner)) return true;
+  }
+
+  if (normalized.includes("expression(")) return true;
+  if (normalized.includes("-moz-binding")) return true;
+  if (normalized.includes("behavior:")) return true;
+  if (normalized.includes("@import")) return true;
+
+  return false;
+}

package/src/escape/css-normalize.ts

@@ -0,0 +1,54 @@
+/**
+ * Normalize a CSS value by resolving escape sequences, removing comments,
+ * stripping whitespace and control characters, and lowercasing.
+ */
+export function normalizeCssValue(value: string): string {
+  let result = value;
+
+  result = stripCssComments(result);
+  result = result.replace(/\\(?:\r\n|[\n\r\f])/g, "");
+  result = result.replace(/\\([0-9a-f]{1,6})\s?/gi, (_, hex) => {
+    const code = Number.parseInt(hex, 16);
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : "";
+  });
+  result = result.replace(/\\(.)/g, "$1");
+  result = stripControlAndWhitespace(result);
+
+  return result.toLowerCase();
+}
+
+const WHITESPACE = /\s/;
+
+function stripCssComments(value: string): string {
+  let result = "";
+  let cursor = 0;
+
+  while (cursor < value.length) {
+    const start = value.indexOf("/*", cursor);
+    if (start === -1) {
+      result += value.slice(cursor);
+      break;
+    }
+
+    result += value.slice(cursor, start);
+    const end = value.indexOf("*/", start + 2);
+    if (end === -1) {
+      break;
+    }
+    cursor = end + 2;
+  }
+
+  return result;
+}
+
+function stripControlAndWhitespace(value: string): string {
+  let result = "";
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (WHITESPACE.test(char) || code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}

package/src/escape/css-style.ts

@@ -0,0 +1,78 @@
+import { isDangerousCssValue } from "./css-danger";
+import { normalizeCssValue } from "./css-normalize";
+
+/**
+ * Sanitize a `style` attribute value by removing dangerous declarations
+ * while preserving safe ones.
+ */
+export function sanitizeStyleValue(style: string): string {
+  const endsWithSemicolon = style.trimEnd().endsWith(";");
+
+  if (style.indexOf(";") === -1) {
+    return sanitizeSingleDeclaration(style.trim());
+  }
+
+  const safe: string[] = [];
+  for (const rawDecl of splitDeclarations(style)) {
+    const decl = sanitizeSingleDeclaration(rawDecl.trim());
+    if (decl) safe.push(decl);
+  }
+
+  if (safe.length === 0) return "";
+  return endsWithSemicolon ? safe.join(";") + ";" : safe.join(";");
+}
+
+function sanitizeSingleDeclaration(decl: string): string {
+  if (decl === "") return "";
+
+  const colonIdx = decl.indexOf(":");
+  if (colonIdx === -1) return "";
+
+  const property = decl.slice(0, colonIdx).trim();
+  const value = decl.slice(colonIdx + 1).trim();
+  if (isDangerousCssValue(value)) return "";
+
+  const normalisedProperty = normalizeCssValue(property);
+  if (normalisedProperty.startsWith("-moz-binding")) return "";
+  if (normalisedProperty === "behavior") return "";
+
+  return decl;
+}
+
+/**
+ * Split a CSS style attribute value into declarations, respecting
+ * parentheses and quoted strings.
+ */
+function splitDeclarations(style: string): string[] {
+  const out: string[] = [];
+  let start = 0;
+  let parenDepth = 0;
+  let quoteChar: string | null = null;
+
+  for (let i = 0; i < style.length; i++) {
+    const ch = style[i]!;
+    if (quoteChar !== null) {
+      if (ch === quoteChar) quoteChar = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quoteChar = ch;
+      continue;
+    }
+    if (ch === "(") {
+      parenDepth++;
+      continue;
+    }
+    if (ch === ")") {
+      if (parenDepth > 0) parenDepth--;
+      continue;
+    }
+    if (ch === ";" && parenDepth === 0) {
+      out.push(style.slice(start, i));
+      start = i + 1;
+      continue;
+    }
+  }
+  if (start < style.length) out.push(style.slice(start));
+  return out;
+}

package/src/escape/css-urls.ts

@@ -0,0 +1,76 @@
+export interface CssUrlToken {
+  inner: string;
+  malformed: boolean;
+}
+
+/**
+ * Allowlist check for a raw URL string extracted from a normalized `url(...)` token.
+ */
+export function isCssUrlAllowed(rawUrl: string): boolean {
+  let url = rawUrl;
+
+  if (url.length >= 2) {
+    const first = url[0];
+    const last = url[url.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      url = url.slice(1, -1);
+    }
+  }
+
+  if (url === "") return true;
+  if (url.startsWith("#")) return true;
+  if (url.startsWith("./") || url.startsWith("../")) return true;
+  if (url.startsWith("//")) return true;
+  if (url.startsWith("/")) return true;
+  if (url.startsWith("http://") || url.startsWith("https://")) return true;
+
+  if (url.startsWith("data:image/")) {
+    const after = url.slice("data:image/".length);
+    const sep = Math.min(
+      after.indexOf(";") === -1 ? after.length : after.indexOf(";"),
+      after.indexOf(",") === -1 ? after.length : after.indexOf(","),
+    );
+    const mime = after.slice(0, sep);
+    if (mime === "png" || mime === "jpeg" || mime === "jpg" || mime === "gif" || mime === "webp") {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract every `url(...)` invocation from a normalized CSS value.
+ */
+export function* iterateCssUrls(normalized: string): Generator<CssUrlToken> {
+  let searchPos = 0;
+  while (searchPos < normalized.length) {
+    const idx = normalized.indexOf("url(", searchPos);
+    if (idx === -1) return;
+
+    let depth = 1;
+    let quoteChar: string | null = null;
+    let i = idx + 4;
+    while (i < normalized.length && depth > 0) {
+      const ch = normalized[i];
+      if (quoteChar !== null) {
+        if (ch === quoteChar) quoteChar = null;
+      } else if (ch === '"' || ch === "'") {
+        quoteChar = ch;
+      } else if (ch === "(") {
+        depth++;
+      } else if (ch === ")") {
+        depth--;
+      }
+      i++;
+    }
+
+    if (depth > 0) {
+      yield { inner: normalized.slice(idx + 4), malformed: true };
+      return;
+    }
+
+    yield { inner: normalized.slice(idx + 4, i - 1), malformed: false };
+    searchPos = i;
+  }
+}

package/src/escape/css.ts

@@ -0,0 +1,4 @@
+export { isValidCssColor, sanitizeCssColor } from "./css-colors";
+export { normalizeCssValue } from "./css-normalize";
+export { isDangerousCssValue } from "./css-danger";
+export { sanitizeStyleValue } from "./css-style";

package/src/escape/email.ts

@@ -0,0 +1,22 @@
+/**
+ * Validate that a string looks like a safe email address.
+ *
+ * Uses a deliberately simple pattern that accepts the vast majority of
+ * real-world addresses while blocking characters that could enable
+ * injection attacks when the address is used in a `mailto:` link.
+ *
+ * The percent character (`%`) is intentionally disallowed because
+ * `mailto:` URLs undergo percent-decoding, allowing an attacker to
+ * inject headers (e.g. `a%0d%0abcc%3aevil@example.com` decodes to
+ * a BCC header injection).
+ *
+ * @param email - The email string to validate.
+ * @returns `true` if the email matches the safe pattern.
+ */
+export function isValidEmail(email: string): boolean {
+  // Simple email pattern: local@domain
+  // - local: alphanumeric, dots, underscores, hyphens, plus signs (NO percent)
+  // - domain: alphanumeric, dots, hyphens
+  // Does NOT allow: spaces, colons, angle brackets, percent, or other special chars
+  return /^[a-zA-Z0-9._+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email);
+}

package/src/escape/html.ts

@@ -0,0 +1,68 @@
+export function escapeHtml(text: string): string {
+  let start = 0;
+  let escaped = "";
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    let replacement: string | null = null;
+    if (char === "&") {
+      replacement = "&amp;";
+    } else if (char === "<") {
+      replacement = "&lt;";
+    } else if (char === ">") {
+      replacement = "&gt;";
+    }
+
+    if (replacement) {
+      if (start < i) {
+        escaped += text.slice(start, i);
+      }
+      escaped += replacement;
+      start = i + 1;
+    }
+  }
+
+  if (start === 0) {
+    return text;
+  }
+  return start < text.length ? escaped + text.slice(start) : escaped;
+}
+
+export function escapeAttr(value: string): string {
+  if (
+    value.indexOf("&") === -1 &&
+    value.indexOf("<") === -1 &&
+    value.indexOf(">") === -1 &&
+    value.indexOf('"') === -1 &&
+    value.indexOf("'") === -1
+  ) {
+    return value;
+  }
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function escapeStyleContent(css: string): string {
+  if (css.indexOf("</") === -1) {
+    return css;
+  }
+  return css.replace(/<\/style/gi, "<\\/style");
+}
+
+export function escapeJsString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/'/g, "\\x27")
+    .replace(/"/g, "\\x22")
+    .replace(/</g, "\\x3c")
+    .replace(/>/g, "\\x3e")
+    .replace(/&/g, "\\x26")
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}

package/src/escape/index.ts

@@ -0,0 +1,15 @@
+/**
+ *
+ * HTML, CSS, URL, and attribute sanitization utilities for the render pipeline.
+ *
+ * Every piece of user-supplied content that flows into the HTML output must
+ * pass through one of these functions to prevent Cross-Site Scripting (XSS)
+ * and CSS injection attacks.
+ *
+ * @module
+ */
+export { escapeAttr, escapeHtml, escapeJsString, escapeStyleContent } from "./html";
+export { isDangerousUrl } from "./url";
+export { isValidCssColor, sanitizeCssColor, isDangerousCssValue, sanitizeStyleValue } from "./css";
+export { isValidEmail } from "./email";
+export { isSafeAttribute, sanitizeAttributes } from "./attributes";

package/src/escape/url.ts

@@ -0,0 +1,18 @@
+export function isDangerousUrl(value: string): boolean {
+  const normalized = stripControlAndWhitespace(value);
+  return /^(javascript|data|vbscript):/i.test(normalized);
+}
+
+const WHITESPACE = /\s/;
+
+function stripControlAndWhitespace(value: string): string {
+  let result = "";
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (WHITESPACE.test(char) || code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}

package/src/hash.ts

@@ -0,0 +1,62 @@
+/**
+ *
+ * Pure-JavaScript hash functions for generating deterministic element IDs.
+ *
+ * These functions use FNV-1a internally and produce hex strings whose
+ * lengths match SHA-1 (40 chars) and MD5 (32 chars) for compatibility
+ * with Wikidot's ID generation patterns. Cryptographic security is not
+ * required; the hashes only need to be deterministic and well-distributed.
+ *
+ * `node:crypto` is intentionally avoided because `bunup`'s ESM build
+ * injects `createRequire` from `node:module`, which is incompatible
+ * with browser environments.
+ *
+ * @module
+ */
+
+/**
+ * Generate a 40-character hex hash (same length as SHA-1) from the input string.
+ *
+ * @param input - The string to hash.
+ * @returns A 40-character lowercase hex string.
+ */
+export function syncHashSha1(input: string): string {
+  return fnv1aHash(input, 40);
+}
+
+/**
+ * Generate a 32-character hex hash (same length as MD5) from the input string.
+ *
+ * @param input - The string to hash.
+ * @returns A 32-character lowercase hex string.
+ */
+export function syncHashMd5(input: string): string {
+  return fnv1aHash(input, 32);
+}
+
+/**
+ * Compute an FNV-1a hash of the given input and return a hex string of
+ * the requested length.
+ *
+ * Because a single FNV-1a pass produces only 32 bits (8 hex chars), the
+ * function runs multiple rounds with different initial seeds (XOR of
+ * the round index into the offset basis) and concatenates the results
+ * to reach the desired length.
+ *
+ * @param input - The string to hash.
+ * @param hexLen - Desired length of the output hex string (e.g. 32 or 40).
+ * @returns A lowercase hex string of exactly `hexLen` characters.
+ */
+function fnv1aHash(input: string, hexLen: number): string {
+  let result = "";
+  const rounds = Math.ceil(hexLen / 8);
+  for (let round = 0; round < rounds; round++) {
+    let h = 0x811c9dc5 ^ round;
+    for (let i = 0; i < input.length; i++) {
+      h ^= input.charCodeAt(i);
+      h = Math.imul(h, 0x01000193);
+    }
+    result += (h >>> 0).toString(16).padStart(8, "0");
+  }
+  return result.substring(0, hexLen);
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * HTML renderer for the Wikidot AST.
+ *
+ * Takes a `SyntaxTree` produced by `@wdprlib/parser` and serialises
+ * it to an HTML string. Page context, user resolution, and security
+ * settings (embed allowlists, iframe sandboxing) are configurable via
+ * {@link RenderOptions}.
+ *
+ * ```ts
+ * import { parse } from "@wdprlib/parser";
+ * import { renderToHtml } from "@wdprlib/render";
+ *
+ * const html = renderToHtml(parse("**hello**"));
+ * // => "<p><strong>hello</strong></p>"
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { renderToHtml } from "./render";
+export type { RenderOptions, RenderResolvers, PageContext, ResolvedUser } from "./types";
+export { DEFAULT_EMBED_ALLOWLIST } from "./elements/embed-block";
+
+// Wikitext settings (re-exported from @wdprlib/ast)
+export type { WikitextMode, WikitextSettings } from "@wdprlib/ast";
+export { createSettings, DEFAULT_SETTINGS } from "@wdprlib/ast";

package/src/libs/highlighter/engine/end-pattern.ts

@@ -0,0 +1,26 @@
+import type { LanguageDefinition } from "../types";
+import { escapeRegex, matchingBrackets } from "./utils";
+
+export function buildEndPattern(
+  def: LanguageDefinition,
+  prevState: number,
+  patternIndex: number,
+  count: number,
+  captureIndex: number,
+  match: RegExpExecArray,
+  endRe: RegExp | undefined,
+): RegExp | null {
+  if (!def.subst[prevState]?.[patternIndex] || !endRe) {
+    return endRe ?? null;
+  }
+
+  let epSource = endRe.source;
+  for (let k = 0; k <= count; k++) {
+    const subIdx = captureIndex + k;
+    if (subIdx >= match.length || match[subIdx] == null) break;
+    const quoted = escapeRegex(match[subIdx]!);
+    epSource = epSource.replace(`%${k}%`, quoted);
+    epSource = epSource.replace(`%b${k}%`, matchingBrackets(quoted));
+  }
+  return new RegExp(epSource, endRe.flags);
+}

package/src/libs/highlighter/engine/html.ts

@@ -0,0 +1,19 @@
+/**
+ * Escape HTML special characters for use inside highlighted code spans.
+ */
+export function escapeHighlightHtml(str: string): string {
+  if (
+    str.indexOf("&") === -1 &&
+    str.indexOf("<") === -1 &&
+    str.indexOf(">") === -1 &&
+    str.indexOf('"') === -1
+  ) {
+    return str;
+  }
+
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/libs/highlighter/engine/index.ts

@@ -0,0 +1,3 @@
+export { renderTokens } from "./render";
+export { tokenize } from "./tokenizer";
+export type { HighlightToken } from "./token";