@bendyline/squisq 2.1.0 → 2.2.0

package/src/markdown/sanitize.ts

@@ -1,318 +0,0 @@
-import type { HtmlElement, HtmlNode } from './types.js';
-
-export type HtmlPolicy = 'strip' | 'sanitize' | 'trusted';
-
-export type UrlKind = 'link' | 'media';
-
-const SAFE_LINK_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
-const SAFE_MEDIA_SCHEMES = new Set(['http', 'https', 'blob']);
-
-/** Schemes that can execute script — never allowed, even via extraLinkSchemes. */
-const NEVER_ALLOWED_SCHEMES = new Set(['javascript', 'vbscript', 'data']);
-
-export interface SanitizeUrlOptions {
-  /**
-   * Extra lowercase schemes allowed for `kind: 'link'` — the host-app escape
-   * hatch for custom link protocols it intercepts itself (e.g. an app-internal
-   * navigation scheme). Executable schemes are refused regardless.
-   */
-  extraLinkSchemes?: readonly string[];
-}
-
-const SAFE_DATA_MEDIA_RE =
-  /^data:(?:image\/(?!svg\+xml)[a-z0-9.+-]+|audio\/[a-z0-9.+-]+|video\/[a-z0-9.+-]+);/i;
-
-const SAFE_TAGS = new Set([
-  'a',
-  'abbr',
-  'b',
-  'blockquote',
-  'br',
-  'caption',
-  'cite',
-  'code',
-  'col',
-  'colgroup',
-  'data',
-  'dd',
-  'del',
-  'details',
-  'dfn',
-  'div',
-  'dl',
-  'dt',
-  'em',
-  'figcaption',
-  'figure',
-  'h1',
-  'h2',
-  'h3',
-  'h4',
-  'h5',
-  'h6',
-  'hr',
-  'i',
-  'img',
-  'kbd',
-  'li',
-  'mark',
-  'ol',
-  'p',
-  'pre',
-  'q',
-  's',
-  'samp',
-  'small',
-  'source',
-  'span',
-  'strong',
-  'sub',
-  'summary',
-  'sup',
-  'table',
-  'tbody',
-  'td',
-  'tfoot',
-  'th',
-  'thead',
-  'time',
-  'tr',
-  'track',
-  'u',
-  'ul',
-  'var',
-  'video',
-  'audio',
-]);
-
-const DROP_WITH_CONTENT_TAGS = new Set([
-  'base',
-  'button',
-  'embed',
-  'form',
-  'iframe',
-  'input',
-  'link',
-  'meta',
-  'object',
-  'option',
-  'script',
-  'select',
-  'style',
-  'svg',
-  'template',
-  'textarea',
-]);
-
-const GLOBAL_ATTRS = new Set(['class', 'id', 'title', 'role']);
-
-const TAG_ATTRS: Record<string, Set<string>> = {
-  a: new Set(['href', 'target', 'rel']),
-  audio: new Set(['src', 'controls', 'preload', 'muted', 'loop']),
-  col: new Set(['span', 'width']),
-  colgroup: new Set(['span']),
-  data: new Set(['value']),
-  img: new Set(['src', 'alt', 'width', 'height', 'loading', 'decoding']),
-  li: new Set(['value']),
-  ol: new Set(['start', 'type']),
-  q: new Set(['cite']),
-  source: new Set(['src', 'type', 'media']),
-  td: new Set(['colspan', 'rowspan', 'align']),
-  th: new Set(['colspan', 'rowspan', 'align', 'scope']),
-  time: new Set(['datetime']),
-  track: new Set(['src', 'kind', 'label', 'srclang', 'default']),
-  video: new Set([
-    'src',
-    'poster',
-    'width',
-    'height',
-    'controls',
-    'preload',
-    'muted',
-    'loop',
-    'playsinline',
-  ]),
-};
-
-const SAFE_ATTR_NAME_RE = /^[a-z][a-z0-9:_.-]*$/;
-const SAFE_OL_TYPES = new Set(['1', 'a', 'A', 'i', 'I']);
-const SAFE_PRELOAD_VALUES = new Set(['none', 'metadata', 'auto']);
-const SAFE_TRACK_KINDS = new Set(['subtitles', 'captions', 'descriptions', 'chapters', 'metadata']);
-
-/**
- * Sanitize a URL for a rendered link or media attribute.
- *
- * Relative URLs are allowed. Absolute URLs are restricted to schemes that
- * cannot execute script in a document context. Media URLs additionally allow
- * `blob:` and image/audio/video `data:` URLs because Squisq uses both for
- * browser-local media previews and self-contained exports.
- */
-export function sanitizeUrl(
-  url: string | null | undefined,
-  kind: UrlKind = 'link',
-  options?: SanitizeUrlOptions,
-): string | null {
-  if (typeof url !== 'string') return null;
-
-  const trimmed = url.trim();
-  if (!trimmed) return null;
-
-  const compact = stripUrlSchemeNoise(trimmed);
-  const colon = compact.indexOf(':');
-  const firstPathChar = firstIndexOfAny(compact, ['/', '?', '#']);
-  const hasScheme = colon >= 0 && (firstPathChar < 0 || colon < firstPathChar);
-
-  if (!hasScheme) return trimmed;
-
-  const scheme = compact.slice(0, colon).toLowerCase();
-  if (kind === 'media') {
-    if (scheme === 'data') return SAFE_DATA_MEDIA_RE.test(compact) ? trimmed : null;
-    return SAFE_MEDIA_SCHEMES.has(scheme) ? trimmed : null;
-  }
-
-  if (SAFE_LINK_SCHEMES.has(scheme)) return trimmed;
-  if (options?.extraLinkSchemes?.includes(scheme) && !NEVER_ALLOWED_SCHEMES.has(scheme)) {
-    return trimmed;
-  }
-  return null;
-}
-
-/**
- * Return a sanitized copy of an HtmlNode tree. The original parsed tree is left
- * untouched so markdown stringify can still preserve source fidelity.
- */
-export function sanitizeHtmlNodes(nodes: HtmlNode[]): HtmlNode[] {
-  const out: HtmlNode[] = [];
-  for (const node of nodes) {
-    out.push(...sanitizeHtmlNode(node));
-  }
-  return out;
-}
-
-function sanitizeHtmlNode(node: HtmlNode): HtmlNode[] {
-  switch (node.type) {
-    case 'htmlText':
-      return [node];
-    case 'htmlComment':
-      return [];
-    case 'htmlElement':
-      return sanitizeHtmlElement(node);
-  }
-}
-
-function sanitizeHtmlElement(node: HtmlElement): HtmlNode[] {
-  const tag = node.tagName.toLowerCase();
-
-  if (DROP_WITH_CONTENT_TAGS.has(tag)) return [];
-
-  const children = sanitizeHtmlNodes(node.children);
-  if (!SAFE_TAGS.has(tag)) return children;
-
-  return [
-    {
-      type: 'htmlElement',
-      tagName: tag,
-      attributes: sanitizeAttrs(tag, node.attributes),
-      children,
-      selfClosing: node.selfClosing,
-    },
-  ];
-}
-
-function sanitizeAttrs(tag: string, attrs: Record<string, string>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [rawName, rawValue] of Object.entries(attrs)) {
-    const name = rawName.toLowerCase();
-    if (!isAllowedAttr(tag, name)) continue;
-
-    const value = String(rawValue);
-    const safeValue = sanitizeAttrValue(tag, name, value);
-    if (safeValue === null) continue;
-    out[name] = safeValue;
-  }
-  if (tag === 'a' && out.target === '_blank') {
-    out.rel = ensureRelTokens(out.rel, ['noopener', 'noreferrer']);
-  }
-  return out;
-}
-
-function isAllowedAttr(tag: string, name: string): boolean {
-  if (!SAFE_ATTR_NAME_RE.test(name)) return false;
-  if (name.startsWith('on')) return false;
-  if (name.startsWith('aria-') || name.startsWith('data-')) return true;
-  if (GLOBAL_ATTRS.has(name)) return true;
-  return TAG_ATTRS[tag]?.has(name) ?? false;
-}
-
-function sanitizeAttrValue(tag: string, name: string, value: string): string | null {
-  if (name === 'href') return sanitizeUrl(value, 'link');
-  if (name === 'src' || name === 'poster') return sanitizeUrl(value, 'media');
-  if (
-    (name === 'width' ||
-      name === 'height' ||
-      name === 'span' ||
-      name === 'colspan' ||
-      name === 'rowspan' ||
-      name === 'value') &&
-    !isNonNegativeInteger(value)
-  ) {
-    return null;
-  }
-  if (name === 'start' && !isInteger(value)) return null;
-  if (name === 'type' && tag === 'ol' && !SAFE_OL_TYPES.has(value)) return null;
-  if (name === 'preload' && !SAFE_PRELOAD_VALUES.has(value)) return null;
-  if (name === 'kind' && tag === 'track' && !SAFE_TRACK_KINDS.has(value)) return null;
-  if (name === 'align' && value !== 'left' && value !== 'right' && value !== 'center') return null;
-  if (name === 'target')
-    return value === '_blank' || value === '_self' || value === '_parent' || value === '_top'
-      ? value
-      : null;
-  if (name === 'rel') return sanitizeRel(value);
-  return value;
-}
-
-function sanitizeRel(value: string): string {
-  return relTokens(value).join(' ');
-}
-
-function ensureRelTokens(value: string | undefined, required: string[]): string {
-  const tokens = new Set(value ? relTokens(value) : []);
-  for (const token of required) tokens.add(token);
-  return Array.from(tokens).join(' ');
-}
-
-function relTokens(value: string): string[] {
-  const tokens = value
-    .split(/\s+/)
-    .map((token) => token.trim().toLowerCase())
-    .filter(Boolean)
-    .filter((token) => /^[a-z0-9_-]+$/.test(token));
-  return Array.from(new Set(tokens));
-}
-
-function isInteger(value: string): boolean {
-  return /^-?\d+$/.test(value.trim());
-}
-
-function isNonNegativeInteger(value: string): boolean {
-  return /^\d+$/.test(value.trim());
-}
-
-function firstIndexOfAny(value: string, needles: string[]): number {
-  let result = -1;
-  for (const needle of needles) {
-    const index = value.indexOf(needle);
-    if (index >= 0 && (result < 0 || index < result)) result = index;
-  }
-  return result;
-}
-
-function stripUrlSchemeNoise(value: string): string {
-  let out = '';
-  for (const char of value) {
-    const code = char.charCodeAt(0);
-    if (code <= 0x20 || code === 0x7f || char.trim() === '') continue;
-    out += char;
-  }
-  return out;
-}

package/src/markdown/stringify.ts

@@ -1,207 +0,0 @@
-/**
- * JSON → Markdown Serializer
- *
- * Converts a MarkdownDocument JSON structure back to a markdown string
- * using the unified/remark ecosystem with GFM, math, and directive extensions.
- */
-
-import { unified } from 'unified';
-import remarkStringify from 'remark-stringify';
-import remarkGfm from 'remark-gfm';
-import remarkMath from 'remark-math';
-import remarkDirective from 'remark-directive';
-import type { MarkdownDocument, StringifyOptions } from './types.js';
-import { toMdast } from './convert.js';
-import { formatFrontmatterValue } from './utils.js';
-
-// Cache the default processor (all extensions, default formatting) to avoid rebuilding on every call.
-let defaultProcessor: any;
-
-// ============================================
-// Annotation-span unescaping
-// ============================================
-
-// Quoted runs as they appear in remark-stringify output. Backslashes inside
-// the span are doubled by remark (a literal `\` before punctuation becomes
-// `\\`), so `\\.` covers both authored escapes and remark's own.
-const DQ_RUN = `"(?:[^"\\\\]|\\\\.)*"`;
-const SQ_RUN = `'(?:[^'\\\\]|\\\\.)*'`;
-
-/**
- * A `{[…]}` template-annotation (or inline-icon) span as it appears in
- * remark output: `{\[inner]}`, where `inner` may contain backslash escapes
- * and quoted runs (which may themselves contain `]`).
- */
-const ESCAPED_TEMPLATE_SPAN_RE = new RegExp(
-  `\\{\\\\\\[((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^\\]\\\\])*)\\]\\}`,
-  'g',
-);
-
-/** A heading line (annotations are only emitted trailing on headings). */
-const HEADING_LINE_RE = /^#{1,6} .*$/gm;
-
-/**
- * The trailing Pandoc `{…}` span on a heading line, possibly followed by an
- * already-unescaped `{[…]}` template span (canonical emit order).
- */
-const TRAILING_ESCAPED_PANDOC_SPAN_RE = new RegExp(
-  `\\{(?!\\\\?\\[)((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^}\\\\])*)\\}(?=\\s*(?:\\{\\[.*)?$)`,
-);
-
-/**
- * Backslash+punctuation pairs that are safe to unescape inside an
- * annotation span: the bare character re-parses as literal text in
- * trailing-heading position, so removing the backslash is purely
- * cosmetic and round-trips.
- *
- * Deliberately EXCLUDED (left escaped in the emitted markdown): emphasis
- * and other inline-construct openers (`*`, `_`, `` ` ``, `~`, `<`, `>`,
- * `&`, `!`, `|`, `^`). Unescaping those could make remark-parse split the
- * heading's text run into inline nodes on reparse, which would hide the
- * annotation from the extractor. remark-parse resolves the surviving
- * `\X` escapes back to bare characters, so values still round-trip —
- * the escapes are a cosmetic cost only.
- *
- * Pairs are consumed left to right, so an authored `\"` that remark
- * doubled to `\\"` correctly comes back as `\"`.
- */
-const UNESCAPE_PUNCT_RE = /\\([\\[\]:#.,+=/?;@%$(){}'"-])/g;
-
-function unescapeMarkdownPunct(text: string): string {
-  return text.replace(UNESCAPE_PUNCT_RE, '$1');
-}
-
-/**
- * Serialize a MarkdownDocument back to a markdown string.
- *
- * All extensions (GFM, math, directives) are enabled by default.
- * Use the `options` parameter to control formatting and disable extensions.
- *
- * @param doc - The MarkdownDocument to serialize
- * @param options - Serialization options (formatting, extensions)
- * @returns A markdown string
- *
- * @example
- * ```ts
- * const doc: MarkdownDocument = {
- *   type: 'document',
- *   children: [
- *     { type: 'heading', depth: 1, children: [{ type: 'text', value: 'Hello' }] },
- *     { type: 'paragraph', children: [{ type: 'text', value: 'World' }] },
- *   ],
- * };
- * const md = stringifyMarkdown(doc);
- * // '# Hello\n\nWorld\n'
- * ```
- */
-export function stringifyMarkdown(doc: MarkdownDocument, options?: StringifyOptions): string {
-  // Convert MarkdownDocument → mdast tree
-  const mdastTree = toMdast(doc);
-
-  // Use cached default processor when all extensions and default formatting are used.
-  const useDefaults =
-    !options ||
-    (options.gfm !== false &&
-      options.math !== false &&
-      options.directive !== false &&
-      !options.bullet &&
-      !options.bulletOrdered &&
-      !options.emphasis &&
-      !options.strong &&
-      !options.rule &&
-      !options.fence &&
-      options.setext == null);
-
-  let processor: any;
-
-  if (useDefaults) {
-    if (!defaultProcessor) {
-      defaultProcessor = unified()
-        .use(remarkGfm)
-        .use(remarkMath)
-        .use(remarkDirective)
-        .use(remarkStringify, {
-          bullet: '-',
-          bulletOrdered: '.',
-          emphasis: '*',
-          strong: '*',
-          rule: '-',
-          fence: '`',
-          setext: false,
-        });
-    }
-    processor = defaultProcessor;
-  } else {
-    // Build a custom processor with requested options.
-    // unified's .use() chaining changes the generic signature each time,
-    // making strict typing impractical — use a widened Processor type.
-    processor = unified();
-
-    if (options?.gfm !== false) {
-      processor = processor.use(remarkGfm);
-    }
-    if (options?.math !== false) {
-      processor = processor.use(remarkMath);
-    }
-    if (options?.directive !== false) {
-      processor = processor.use(remarkDirective);
-    }
-
-    processor = processor.use(remarkStringify, {
-      bullet: options?.bullet ?? '-',
-      bulletOrdered: options?.bulletOrdered ?? '.',
-      emphasis: options?.emphasis ?? '*',
-      strong: options?.strong ?? '*',
-      rule: options?.rule ?? '-',
-      fence: options?.fence ?? '`',
-      setext: options?.setext ?? false,
-    });
-  }
-
-  // Stringify mdast → markdown string
-  const result = processor.stringify(mdastTree) as string;
-
-  // remark-stringify backslash-escapes markdown-significant characters in
-  // text nodes (`[` to prevent link syntax, `:` for directives, `*`/`_` for
-  // emphasis, a literal `\` before punctuation, …). Our annotations are
-  // injected as plain text, so their interiors come back escaped. Undo that
-  // inside `{[…]}` template-annotation spans: removing one backslash from
-  // each backslash+punctuation pair (left to right) exactly inverts
-  // remark's escaping — including restoring an authored `\"` that remark
-  // doubled to `\\"`. The span regex understands quoted values, so a
-  // quoted `]` doesn't terminate the span.
-  let cleaned = result.replace(
-    ESCAPED_TEMPLATE_SPAN_RE,
-    (_m, inner: string) => `{[${unescapeMarkdownPunct(inner)}]}`,
-  );
-
-  // Same treatment for the trailing Pandoc `{…}` attribute block on heading
-  // lines (canonical emit order is Pandoc block then template annotation,
-  // so the span sits at end-of-line or just before a `{[…]}` span).
-  cleaned = cleaned.replace(HEADING_LINE_RE, (line) =>
-    line.replace(
-      TRAILING_ESCAPED_PANDOC_SPAN_RE,
-      (_m, inner: string) => `{${unescapeMarkdownPunct(inner)}}`,
-    ),
-  );
-
-  // remark-directive escapes `:` in text (since `:name` would round-trip as
-  // a text directive). Inside any other Pandoc-style `{…}` brace span, `:`
-  // is purely a value separator (e.g. `connectsTo=foo:flow`), so unescape
-  // it to keep round-trips lossless. The negative lookahead skips `{[…]}`
-  // template annotations — those are handled above.
-  cleaned = cleaned.replace(/\{(?!\\?\[)[^}]*\}/g, (match) => match.replace(/\\:/g, ':'));
-
-  // Prepend YAML frontmatter if present
-  if (doc.frontmatter && Object.keys(doc.frontmatter).length > 0) {
-    const yamlLines = Object.entries(doc.frontmatter).map(([k, v]) => {
-      if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
-        return `${k}: ${formatFrontmatterValue(v)}`;
-      }
-      return `${k}: ${JSON.stringify(v)}`;
-    });
-    return `---\n${yamlLines.join('\n')}\n---\n\n${cleaned}`;
-  }
-
-  return cleaned;
-}