explico 0.7.0 → 0.11.0

package/src/components/notation/render-notation-math.ts

@@ -1,5 +1,8 @@
 import rehypeKatex from 'rehype-katex';
-import { createNotationKatexOptions } from '../../reference/katex-options.mjs';
+import {
+  createNotationKatexOptions,
+  trustNotationMarker,
+} from '../../reference/katex-options.mjs';
 import { NOTATION_KEY_PATTERN } from '../../reference/remark-notation.mjs';
 import {
   GlyphResolutionError,
@@ -81,32 +84,96 @@ const allowedTags = new Set([
   'line',
 ]);
 
+/**
+ * Every inert presentation attribute KaTeX's MathML builder can set, sorted.
+ *
+ * This list is deliberately KaTeX's whole surface rather than the attributes
+ * the corpus happens to have hit: anything missing here is a hard build error
+ * on valid, ordinary math, and the author has no way to work around it. `\Bigl`
+ * (`minsize`/`maxsize`), `\boxed` (`notation`), and `\colorbox`
+ * (`voffset`/`mathbackground`) each used to fail that way.
+ * `tests/notation/render-notation-math.test.ts` scans KaTeX's own
+ * `setAttribute` calls and fails when a release adds a name that is in neither
+ * this set nor {@link deniedAttributeNames}, so a KaTeX upgrade cannot quietly
+ * reintroduce the gap.
+ */
 const simpleAttributeNames = new Set([
   'accent',
   'accentunder',
   'columnalign',
+  'columnlines',
   'columnspacing',
+  'depth',
+  'display',
   'displaystyle',
   'fence',
   'height',
+  'largeop',
+  'linebreak',
+  'linethickness',
   'lspace',
+  'mathbackground',
+  'mathcolor',
+  'mathsize',
   'mathvariant',
+  'maxsize',
+  'minsize',
+  'notation',
   'preserveaspectratio',
+  'rowlines',
   'rowspacing',
   'rspace',
   'scriptlevel',
   'separator',
   'stretchy',
+  'valign',
   'viewbox',
+  'voffset',
   'width',
 ]);
 
-const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%]*$/;
+/**
+ * The attributes KaTeX can set that must never reach the page, each one a
+ * navigation or external-resource target: `href` (`\href`), `src`/`alt`
+ * (`\includegraphics`), and `title` (`\htmlTitle`). Every command that
+ * produces one already needs KaTeX's `trust` callback and is refused earlier by
+ * {@link unsafeExtensionCommand}, so this set is the second line — and the
+ * reason the completeness scan above can tell "KaTeX added an attribute nobody
+ * classified" apart from "we decided against this one".
+ */
+const deniedAttributeNames = new Set(['alt', 'href', 'src', 'title']);
+
+// `#` is here for `mathcolor` / `mathbackground` / a `background-color:` style,
+// which KaTeX writes as a hex literal. No attribute reaching this point can
+// carry a URL — `href` and `src` are denied above — so it opens no target.
+const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%#]*$/;
 const safeClassName = /^[A-Za-z0-9_-]+$/;
-const safeStyle = /^(?:[a-z-]+:[ A-Za-z0-9+.,()\-/%]*;)*$/;
+const safeDeclaration = /^\s*[a-z-]+:[ A-Za-z0-9+.,()\-/%#]*$/;
 const safePathData = /^[\sA-Za-z0-9+.,\-]*$/;
 const unsafeExtensionCommand =
   /\\(?:href|url|includegraphics|htmlClass|htmlData|htmlId|htmlStyle)\b/;
+// `\explain{key}{latex}` and `\slot{name}{latex}`, the two macros that expand
+// to a trusted `\htmlData` marker. Only the first argument is captured.
+const MARKER_MACRO = /\\(explain|slot)\{([^{}]*)\}/g;
+
+/**
+ * A declaration list KaTeX generated: inert properties only, and no
+ * `url(...)`/`expression(...)` to fetch or evaluate anything.
+ *
+ * Validated per declaration rather than with one regex over the whole string,
+ * because KaTeX does not always terminate the last one — `\vec` emits
+ * `style="width:0.471em"` with no trailing `;`, which a
+ * `(?:declaration;)*`-shaped pattern rejects outright.
+ */
+function isSafeStyle(value: string): boolean {
+  if (/(?:expression|url)\s*\(/i.test(value)) return false;
+  return value
+    .split(';')
+    .every(
+      (declaration) =>
+        declaration.trim().length === 0 || safeDeclaration.test(declaration),
+    );
+}
 
 function attributeValue(value: unknown, propertyName: string): string {
   if (typeof value === 'boolean') return String(value);
@@ -170,22 +237,27 @@ function safeProperties(
       continue;
     }
 
-    if (
-      name === 'style' &&
-      typeof value === 'string' &&
-      safeStyle.test(value) &&
-      !/(?:expression|url)\s*\(/i.test(value)
-    ) {
+    if (name === 'style') {
+      if (typeof value !== 'string' || !isSafeStyle(value)) {
+        throw new Error('Unsafe KaTeX style value.');
+      }
       properties.style = value;
       continue;
     }
 
-    if (name === 'd' && typeof value === 'string' && safePathData.test(value)) {
+    if (name === 'd') {
+      if (typeof value !== 'string' || !safePathData.test(value)) {
+        throw new Error('Unsafe KaTeX path data.');
+      }
       properties.d = value;
       continue;
     }
 
     const normalizedName = name.toLowerCase();
+    if (deniedAttributeNames.has(normalizedName)) {
+      throw new Error(`Disallowed KaTeX property: ${name}.`);
+    }
+
     if (simpleAttributeNames.has(normalizedName)) {
       const outputName =
         normalizedName === 'viewbox'
@@ -228,6 +300,34 @@ function sanitizeNode(node: HastNode): SafeMathNode {
 // this module already imports from `remark-notation.mjs`.
 export { stripNotationMarkers };
 
+/**
+ * Refuse a marker argument the trust callback would reject, before KaTeX sees
+ * it.
+ *
+ * KaTeX does not treat a denied `trust` as a parse error: it renders the
+ * command name in `errorColor` and carries on, so `\explain{Not A Key}{\Omega}`
+ * would otherwise reach a reader as red `\htmlData` text with the build still
+ * green. `\htmlData` itself is already refused by {@link
+ * unsafeExtensionCommand}, so the two marker macros are the only way into that
+ * callback and this check covers all of them. It asks
+ * {@link trustNotationMarker} rather than re-deriving the key patterns, so the
+ * answer here cannot drift from the answer KaTeX gets.
+ */
+function assertTrustedMarkers(latex: string): void {
+  for (const [, macro, argument] of latex.matchAll(MARKER_MACRO)) {
+    const attribute =
+      macro === 'explain' ? 'data-notation-key' : 'data-lab-slot';
+    if (
+      !trustNotationMarker({
+        command: '\\htmlData',
+        attributes: { [attribute]: argument },
+      })
+    ) {
+      throw new Error(`Notation LaTeX has an invalid \\${macro} key: ${argument}`);
+    }
+  }
+}
+
 /**
  * Render repository-authored LaTeX through the same build-time KaTeX adapter
  * as lesson math, then expose a constrained structured tree to Astro. No HTML
@@ -240,6 +340,7 @@ export function renderNotationMath(latex: string): readonly SafeMathNode[] {
   if (unsafeExtensionCommand.test(latex)) {
     throw new Error('Notation LaTeX cannot use a trust-requiring extension.');
   }
+  assertTrustedMarkers(latex);
 
   const root: HastRoot = {
     type: 'root',