@wdprlib/render 2.0.0 → 2.1.0

package/src/elements/embed-block.ts

@@ -0,0 +1,327 @@
+/**
+ *
+ * Renderer for `[[embed]]...[[/embed]]` block-level embeds.
+ *
+ * Unlike inline embeds (which target specific providers like YouTube),
+ * embed blocks contain raw HTML that the user provides. This module
+ * validates and sanitizes that HTML through a multi-layer pipeline:
+ *
+ * 1. `sanitize-html` strips everything except a single `<iframe>` with
+ *    a limited set of safe attributes.
+ * 2. The iframe's `src` URL must use HTTP or HTTPS.
+ * 3. The hostname and path must match the configured allowlist (or the
+ *    allowlist can be set to `null` for Wikidot's "anyiframe" mode).
+ *
+ * If any validation step fails, a Wikidot-compatible error block is
+ * rendered instead.
+ *
+ * @module
+ */
+
+import type { EmbedBlockData } from "@wdprlib/ast";
+import type { Element } from "domhandler";
+import { parseDocument } from "htmlparser2";
+import sanitizeHtml from "sanitize-html";
+import type { RenderContext } from "../context";
+
+/**
+ * Boolean attributes that should be normalized to attr="attr" format
+ * (Wikidot normalizes these attributes in its output)
+ */
+const BOOLEAN_ATTRIBUTES = [
+  "allowfullscreen",
+  "async",
+  "autofocus",
+  "autoplay",
+  "checked",
+  "controls",
+  "default",
+  "defer",
+  "disabled",
+  "formnovalidate",
+  "hidden",
+  "ismap",
+  "loop",
+  "multiple",
+  "muted",
+  "novalidate",
+  "open",
+  "readonly",
+  "required",
+  "reversed",
+  "selected",
+];
+
+/**
+ * Allowlist entry for embed content validation
+ * Each entry specifies a host pattern and optional path prefix
+ */
+export interface EmbedAllowlistEntry {
+  /** Host pattern. Supports wildcard prefix '*.' (e.g., '*.youtube.com') */
+  host: string;
+  /** Optional path prefix that must match (e.g., '/embed/') */
+  pathPrefix?: string;
+}
+
+/**
+ * Default allowlist for embed content (ported from Wikidot's default.php)
+ * Only iframes with src matching these host+path patterns will be rendered.
+ *
+ * Note: Set to null to allow any HTTPS iframe (Wikidot's 'anyiframe' behavior).
+ * sanitize-html still enforces HTTPS-only and blocks dangerous attributes.
+ */
+export const DEFAULT_EMBED_ALLOWLIST: EmbedAllowlistEntry[] | null = [
+  // YouTube
+  { host: "*.youtube.com", pathPrefix: "/embed/" },
+  { host: "*.youtube-nocookie.com", pathPrefix: "/embed/" },
+  // Vimeo
+  { host: "player.vimeo.com", pathPrefix: "/video/" },
+  // Google Maps
+  { host: "*.google.com", pathPrefix: "/maps/embed" },
+  // Google Calendar
+  { host: "calendar.google.com", pathPrefix: "/calendar/embed" },
+  // Spotify
+  { host: "open.spotify.com", pathPrefix: "/embed/" },
+  // SoundCloud
+  { host: "w.soundcloud.com", pathPrefix: "/player/" },
+  // CodePen
+  { host: "codepen.io" },
+];
+
+/**
+ * sanitize-html configuration for embed content.
+ * Only allows iframe elements with safe attributes, HTTPS scheme only.
+ */
+const SANITIZE_CONFIG: sanitizeHtml.IOptions = {
+  allowedTags: ["iframe"],
+  allowedAttributes: {
+    iframe: [
+      "class",
+      "src",
+      "style",
+      "allow",
+      "allowfullscreen",
+      "frameborder",
+      "height",
+      "loading",
+      "referrerpolicy",
+      "sandbox",
+      "title",
+      "width",
+    ],
+  },
+  allowedSchemes: ["https", "http"],
+};
+
+/**
+ * Parse HTML and recursively find all `<iframe>` elements.
+ *
+ * Recursion is needed because `sanitize-html` might leave nested
+ * structures intact, and we need to ensure exactly one iframe exists
+ * at any nesting level.
+ *
+ * @param html - Sanitized HTML string.
+ * @returns Array of found iframe DOM elements.
+ */
+function findIframes(html: string): Element[] {
+  const doc = parseDocument(html);
+  const iframes: Element[] = [];
+  function walk(nodes: typeof doc.children): void {
+    for (const node of nodes) {
+      if (node.type === "tag") {
+        if (node.name === "iframe") {
+          iframes.push(node);
+        }
+        if (node.children) {
+          walk(node.children);
+        }
+      }
+    }
+  }
+  walk(doc.children);
+  return iframes;
+}
+
+/**
+ * Check whether a hostname matches a host pattern.
+ *
+ * Supports wildcard prefix `*.` (e.g., `*.youtube.com` matches both
+ * `youtube.com` and `www.youtube.com` but not `evil-youtube.com`).
+ * Non-wildcard patterns require an exact match.
+ *
+ * @param hostname - The actual hostname from the iframe `src` URL.
+ * @param pattern - The allowlist host pattern to match against.
+ * @returns `true` if the hostname matches the pattern.
+ */
+function matchesHostPattern(hostname: string, pattern: string): boolean {
+  const lowerHostname = hostname.toLowerCase();
+  const lowerPattern = pattern.toLowerCase();
+
+  if (lowerPattern.startsWith("*.")) {
+    // Wildcard match: *.example.com matches example.com and sub.example.com
+    // But not evil-example.com (must be exact or have dot boundary)
+    const base = lowerPattern.slice(2); // Remove '*.'
+    return lowerHostname === base || lowerHostname.endsWith("." + base);
+  }
+  // Exact match
+  return lowerHostname === lowerPattern;
+}
+
+/**
+ * Check whether a URL matches an allowlist entry's host and optional path prefix.
+ *
+ * The path prefix must match at a boundary: it must be followed by `/`, `?`,
+ * `#`, or end of string to prevent partial matches (e.g., `/embed` must not
+ * match `/embedX`).
+ *
+ * @param url - Parsed URL from the iframe `src` attribute.
+ * @param entry - Allowlist entry with host pattern and optional path prefix.
+ * @returns `true` if both host and path conditions are satisfied.
+ */
+function matchesAllowlistEntry(url: URL, entry: EmbedAllowlistEntry): boolean {
+  if (!matchesHostPattern(url.hostname, entry.host)) {
+    return false;
+  }
+  if (entry.pathPrefix) {
+    const pathLower = url.pathname.toLowerCase();
+    const prefixLower = entry.pathPrefix.toLowerCase();
+    if (!pathLower.startsWith(prefixLower)) {
+      return false;
+    }
+    // If prefix ends with /, boundary check is already satisfied
+    // Otherwise ensure prefix matches at a boundary (not partial, e.g., /embed vs /embedX)
+    if (!prefixLower.endsWith("/")) {
+      const remainder = pathLower.slice(prefixLower.length);
+      if (remainder && !/^[/?#]/.test(remainder)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+/**
+ * Validate and sanitize embed block content through a multi-step pipeline.
+ *
+ * Steps:
+ * 1. Strip all elements except `<iframe>` with safe attributes via `sanitize-html`.
+ * 2. Verify exactly one iframe element exists.
+ * 3. Parse the iframe `src` URL and enforce HTTP/HTTPS scheme.
+ * 4. Match the URL against the allowlist (unless `null` for anyiframe mode).
+ *
+ * @param content - Raw HTML content from the `[[embed]]` block.
+ * @param allowlist - Host/path allowlist entries, or `null` for anyiframe mode.
+ * @param baseUrl - Optional base URL for resolving protocol-relative `src` values.
+ * @returns Sanitized HTML string, or `null` if validation fails.
+ */
+function validateAndSanitizeEmbed(
+  content: string,
+  allowlist: EmbedAllowlistEntry[] | null,
+  baseUrl?: string,
+): string | null {
+  // Sanitize with sanitize-html to remove dangerous content
+  const sanitized = sanitizeHtml(content.trim(), SANITIZE_CONFIG);
+
+  if (!sanitized.trim()) {
+    return null;
+  }
+
+  // Parse sanitized content to find iframes
+  const iframes = findIframes(sanitized);
+
+  // Must have exactly one iframe
+  if (iframes.length !== 1) {
+    return null;
+  }
+
+  const iframe = iframes[0]!;
+  const src = iframe.attribs.src?.trim();
+  if (!src) {
+    return null;
+  }
+
+  // Parse URL (protocol-relative URLs are resolved against baseUrl)
+  let url: URL;
+  try {
+    if (src.startsWith("//")) {
+      // Protocol-relative URL: resolve against baseUrl, defaulting to https:
+      const base = baseUrl ?? "https://localhost";
+      url = new URL(src, base);
+    } else {
+      url = new URL(src);
+    }
+  } catch {
+    return null;
+  }
+
+  // Only allow HTTP and HTTPS
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return null;
+  }
+
+  // If allowlist is null, allow any HTTP(S) iframe (Wikidot's 'anyiframe' behavior)
+  if (allowlist !== null) {
+    // Check if URL matches any allowlist entry
+    const matched = allowlist.some((entry) => matchesAllowlistEntry(url, entry));
+    if (!matched) {
+      return null;
+    }
+  }
+
+  return sanitized;
+}
+
+/**
+ * Normalize HTML boolean attributes to Wikidot's format.
+ *
+ * Wikidot outputs boolean attributes as `attr="attr"` rather than the
+ * minimized form (`attr`) or empty form (`attr=""`). This function
+ * rewrites both forms to match.
+ *
+ * @param html - HTML string potentially containing boolean attributes.
+ * @returns HTML with boolean attributes in `attr="attr"` format.
+ */
+function normalizeBooleanAttributes(html: string): string {
+  let result = html;
+  for (const attr of BOOLEAN_ATTRIBUTES) {
+    // Match standalone boolean attribute (not already having a value)
+    // Pattern: attr followed by whitespace, > or />
+    const standalonePattern = new RegExp(`\\s${attr}(?=\\s|>|/>)`, "gi");
+    result = result.replace(standalonePattern, ` ${attr}="${attr}"`);
+
+    // Match attr="" (empty value, sanitize-html output)
+    const emptyValuePattern = new RegExp(`\\s${attr}=""`, "gi");
+    result = result.replace(emptyValuePattern, ` ${attr}="${attr}"`);
+  }
+  return result;
+}
+
+/**
+ * Render an `[[embed]]...[[/embed]]` block element.
+ *
+ * The raw HTML content is validated and sanitized through the full
+ * pipeline. On failure, a Wikidot-compatible error block is shown:
+ * `<div class="error-block">Sorry, no match for the embedded content.</div>`.
+ *
+ * The allowlist is taken from `ctx.options.embedAllowlist`, falling back
+ * to {@link DEFAULT_EMBED_ALLOWLIST} when not specified. Setting it to
+ * `null` enables Wikidot's "anyiframe" mode (any HTTPS iframe allowed).
+ *
+ * @param ctx - The current render context.
+ * @param data - Embed block data containing the raw HTML contents.
+ */
+export function renderEmbedBlock(ctx: RenderContext, data: EmbedBlockData): void {
+  // Use explicit undefined check to allow null (anyiframe mode)
+  const allowlist =
+    ctx.options.embedAllowlist !== undefined ? ctx.options.embedAllowlist : DEFAULT_EMBED_ALLOWLIST;
+
+  const sanitized = validateAndSanitizeEmbed(data.contents, allowlist, ctx.options.baseUrl);
+  if (sanitized === null) {
+    ctx.push('<div class="error-block">Sorry, no match for the embedded content.</div>');
+    return;
+  }
+
+  // Normalize boolean attributes and output
+  const normalized = normalizeBooleanAttributes(sanitized);
+  ctx.push(normalized);
+}

package/src/elements/embed.ts

@@ -0,0 +1,166 @@
+/**
+ *
+ * Renderer for inline embed elements (`[[embed]]`) that reference
+ * third-party content providers.
+ *
+ * Supported providers:
+ * - YouTube (`[[embedvideo youtube:VIDEO_ID]]`)
+ * - Vimeo (`[[embedvideo vimeo:VIDEO_ID]]`)
+ * - GitHub Gist (`[[embed github-gist:USER/HASH]]`)
+ * - GitLab Snippet (`[[embed gitlab-snippet:ID]]`)
+ *
+ * Each provider has a strict ID validation function to prevent path
+ * traversal, injection, and other attacks via embed parameters.
+ *
+ * @module
+ */
+
+import type { Embed } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeAttr } from "../escape";
+
+// =============================================================================
+// ID Validation
+// Prevents path traversal and injection via embed parameters
+// =============================================================================
+
+/**
+ * Validate a YouTube or Vimeo video ID.
+ * Only alphanumeric characters, underscores, and hyphens are allowed.
+ *
+ * @param id - The video ID string to validate.
+ * @returns `true` if the ID contains only safe characters.
+ */
+function isValidVideoId(id: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
+/**
+ * Validate a GitHub username (alphanumeric + hyphen, 1-39 characters).
+ *
+ * @param username - The GitHub username to validate.
+ * @returns `true` if the username matches GitHub's format rules.
+ */
+function isValidGithubUsername(username: string): boolean {
+  return /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(username);
+}
+
+/**
+ * Validate a GitHub Gist hash (lowercase hex characters only).
+ *
+ * @param hash - The gist hash string to validate.
+ * @returns `true` if the hash contains only hex characters.
+ */
+function isValidGistHash(hash: string): boolean {
+  return /^[a-f0-9]+$/.test(hash);
+}
+
+/**
+ * Validate a GitLab snippet ID (numeric digits only).
+ *
+ * @param id - The snippet ID string to validate.
+ * @returns `true` if the ID is numeric.
+ */
+function isValidGitlabSnippetId(id: string): boolean {
+  return /^[0-9]+$/.test(id);
+}
+
+// =============================================================================
+// Render Functions
+// =============================================================================
+
+/**
+ * Render an inline embed element by dispatching to the appropriate
+ * provider-specific renderer.
+ *
+ * Invalid provider parameters (e.g. a video ID containing path traversal
+ * characters) result in an HTML comment instead of the embed.
+ *
+ * @param ctx - The current render context.
+ * @param data - Embed data with provider type and provider-specific fields.
+ */
+export function renderEmbed(ctx: RenderContext, data: Embed): void {
+  switch (data.embed) {
+    case "youtube":
+      renderYoutube(ctx, data.data["video-id"]);
+      break;
+    case "vimeo":
+      renderVimeo(ctx, data.data["video-id"]);
+      break;
+    case "github-gist":
+      renderGithubGist(ctx, data.data.username, data.data.hash);
+      break;
+    case "gitlab-snippet":
+      renderGitlabSnippet(ctx, data.data["snippet-id"]);
+      break;
+  }
+}
+
+/**
+ * Render a YouTube embed as a responsive iframe.
+ *
+ * @param ctx - The current render context.
+ * @param videoId - YouTube video ID (validated before use).
+ */
+function renderYoutube(ctx: RenderContext, videoId: string): void {
+  if (!isValidVideoId(videoId)) {
+    ctx.push(`<!-- Invalid YouTube video ID -->`);
+    return;
+  }
+  ctx.push(`<div class="embed-youtube">`);
+  ctx.push(
+    `<iframe src="https://www.youtube.com/embed/${escapeAttr(videoId)}" ` +
+      `frameborder="0" allowfullscreen></iframe>`,
+  );
+  ctx.push("</div>");
+}
+
+/**
+ * Render a Vimeo embed as a responsive iframe.
+ *
+ * @param ctx - The current render context.
+ * @param videoId - Vimeo video ID (validated before use).
+ */
+function renderVimeo(ctx: RenderContext, videoId: string): void {
+  if (!isValidVideoId(videoId)) {
+    ctx.push(`<!-- Invalid Vimeo video ID -->`);
+    return;
+  }
+  ctx.push(`<div class="embed-vimeo">`);
+  ctx.push(
+    `<iframe src="https://player.vimeo.com/video/${escapeAttr(videoId)}" ` +
+      `frameborder="0" allowfullscreen></iframe>`,
+  );
+  ctx.push("</div>");
+}
+
+/**
+ * Render a GitHub Gist embed as a `<script>` tag.
+ *
+ * @param ctx - The current render context.
+ * @param username - GitHub username owning the gist (validated before use).
+ * @param hash - Gist hash identifier (validated before use).
+ */
+function renderGithubGist(ctx: RenderContext, username: string, hash: string): void {
+  if (!isValidGithubUsername(username) || !isValidGistHash(hash)) {
+    ctx.push(`<!-- Invalid GitHub Gist parameters -->`);
+    return;
+  }
+  ctx.push(
+    `<script src="https://gist.github.com/${escapeAttr(username)}/${escapeAttr(hash)}.js"></script>`,
+  );
+}
+
+/**
+ * Render a GitLab Snippet embed as a `<script>` tag.
+ *
+ * @param ctx - The current render context.
+ * @param snippetId - GitLab snippet ID (validated before use).
+ */
+function renderGitlabSnippet(ctx: RenderContext, snippetId: string): void {
+  if (!isValidGitlabSnippetId(snippetId)) {
+    ctx.push(`<!-- Invalid GitLab snippet ID -->`);
+    return;
+  }
+  ctx.push(`<script src="https://gitlab.com/snippets/${escapeAttr(snippetId)}.js"></script>`);
+}

package/src/elements/expr.ts

@@ -0,0 +1,102 @@
+/**
+ *
+ * Renderers for Wikidot's expression and conditional constructs:
+ *
+ * - `[[#expr EXPRESSION]]` -- evaluate a mathematical expression and
+ *   display the numeric result.
+ * - `[[#if VALUE | THEN | ELSE]]` -- simple string-based truthiness check.
+ * - `[[#ifexpr EXPRESSION | THEN | ELSE]]` -- evaluate a math expression
+ *   and branch on the numeric result (0 = false, non-zero = true).
+ *
+ * All error messages match Wikidot's format (`"run-time error: ..."`).
+ *
+ * @module
+ */
+
+import type { Element, ExprData, IfCondData, IfExprData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { renderElements } from "../render";
+import { evaluateExpression, formatExprValue, isTruthy } from "@wdprlib/ast";
+
+/**
+ * Render a `[[#expr]]` element.
+ *
+ * Evaluates the mathematical expression and outputs the formatted numeric
+ * result. On evaluation error, a Wikidot-compatible error message is
+ * displayed. Empty expressions produce no output.
+ *
+ * @param ctx - The current render context.
+ * @param data - Expression data containing the expression string.
+ */
+export function renderExpr(ctx: RenderContext, data: ExprData): void {
+  const result = evaluateExpression(data.expression);
+  if (result.success) {
+    ctx.pushEscaped(formatExprValue(result.value));
+  } else if (result.error !== "empty expression") {
+    ctx.pushEscaped(`run-time error: ${result.error}`);
+  }
+  // Empty expression outputs nothing
+}
+
+/**
+ * Render a `[[#if]]` conditional element.
+ *
+ * The condition is treated as a string: values `"false"`, `"null"`,
+ * `""`, and `"0"` are falsy; everything else is truthy. The selected
+ * branch's elements are rendered with trailing whitespace trimmed.
+ *
+ * @param ctx - The current render context.
+ * @param data - If-condition data with condition string and then/else branches.
+ */
+export function renderIf(ctx: RenderContext, data: IfCondData): void {
+  const elements = isTruthy(data.condition) ? data.then : data.else;
+  renderBranchElements(ctx, elements);
+}
+
+/**
+ * Render a `[[#ifexpr]]` conditional expression element.
+ *
+ * Evaluates the mathematical expression; a result of 0 selects the
+ * `else` branch, any non-zero result selects the `then` branch.
+ * On evaluation error, a Wikidot-compatible error message is displayed
+ * and neither branch is rendered.
+ *
+ * @param ctx - The current render context.
+ * @param data - If-expression data with expression string and then/else branches.
+ */
+export function renderIfExpr(ctx: RenderContext, data: IfExprData): void {
+  const result = evaluateExpression(data.expression);
+  if (!result.success) {
+    // ifexpr: error outputs error message (Wikidot-compatible)
+    ctx.pushEscaped(`run-time error: ${result.error}`);
+    return;
+  }
+  // 0 selects else branch, non-zero selects then branch
+  const elements = result.value !== 0 ? data.then : data.else;
+  renderBranchElements(ctx, elements);
+}
+
+/**
+ * Render a branch's elements, trimming trailing whitespace-only text nodes.
+ *
+ * Wikidot strips trailing whitespace from `#if` / `#ifexpr` branch output.
+ * This function finds the last non-whitespace element and renders only
+ * up to that point.
+ *
+ * @param ctx - The current render context.
+ * @param elements - The branch's element array.
+ */
+function renderBranchElements(ctx: RenderContext, elements: Element[]): void {
+  // Find the last non-whitespace element
+  let lastIdx = elements.length - 1;
+  while (lastIdx >= 0) {
+    const el = elements[lastIdx]!;
+    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
+      lastIdx--;
+    } else {
+      break;
+    }
+  }
+  // Render only up to the last non-whitespace element
+  renderElements(ctx, elements.slice(0, lastIdx + 1));
+}

package/src/elements/footnote.ts

@@ -0,0 +1,76 @@
+/**
+ *
+ * Renderers for Wikidot footnote markup.
+ *
+ * - `[[footnote]]...[[/footnote]]` -- inline footnote reference that renders
+ *   as a superscript number linking to the footnote body.
+ * - `[[footnoteblock]]` -- block element that lists all footnote bodies
+ *   collected during the render pass.
+ *
+ * The runtime `footnote` module adds hover tooltips and click-to-scroll
+ * behavior to these elements.
+ *
+ * @module
+ */
+
+import type { FootnoteBlockData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeHtml } from "../escape";
+import { renderElements } from "../render";
+
+/**
+ * Render an inline footnote reference as a superscript link.
+ *
+ * Produces `<sup class="footnoteref"><a id="footnoteref-N" ...>N</a></sup>`.
+ * The ID is used by the runtime module for bidirectional scroll navigation
+ * between the reference and its footnote body.
+ *
+ * @param ctx - The current render context.
+ * @param index - The 1-based footnote number.
+ */
+export function renderFootnoteRef(ctx: RenderContext, index: number): void {
+  const id = ctx.generateId("footnoteref-", index);
+  ctx.push(`<sup class="footnoteref">`);
+  ctx.push(`<a id="${id}" href="javascript:;" class="footnoteref">${index}</a>`);
+  ctx.push("</sup>");
+}
+
+/**
+ * Render a `[[footnoteblock]]` element that lists all footnote bodies.
+ *
+ * Produces a Wikidot-compatible structure:
+ * ```html
+ * <div class="footnotes-footer">
+ *   <div class="title">Footnotes</div>
+ *   <div class="footnote-footer" id="footnote-1">
+ *     <a href="javascript:;">1</a>. ...content...
+ *   </div>
+ * </div>
+ * ```
+ *
+ * If there are no footnotes, the block is not rendered at all.
+ *
+ * @param ctx - The current render context.
+ * @param data - Footnote block data with optional custom title.
+ */
+export function renderFootnoteBlock(ctx: RenderContext, data: FootnoteBlockData): void {
+  if (ctx.footnotes.length === 0) return;
+  const title = data.title ?? "Footnotes";
+
+  ctx.push(`<div class="footnotes-footer">`);
+  ctx.push(`<div class="title">${escapeHtml(title)}</div>`);
+
+  // Render each footnote
+  for (let i = 0; i < ctx.footnotes.length; i++) {
+    const index = i + 1;
+    const elements = ctx.footnotes[i] ?? [];
+
+    const fnId = ctx.generateId("footnote-", index);
+    ctx.push(`<div class="footnote-footer" id="${fnId}">`);
+    ctx.push(`<a href="javascript:;">${index}</a>. `);
+    renderElements(ctx, elements);
+    ctx.push("</div>");
+  }
+
+  ctx.push("</div>");
+}