fix(reliability): harden public Markdown and local serialization boundaries

docs/doctoring/html-to-markdown-resource-bounds.md

@@ -0,0 +1,82 @@
+# HTML-to-Markdown resource bounds
+
+Status: Implemented on active PR
+
+## Purpose
+
+Inkspan's standalone `htmlToMarkdown()` boundary accepts caller-provided HTML and
+parses it through either a detached browser template or Turndown's browserless
+parser. Protected shipped truth is currently
+`main@3b38ead2d00f44eb578d0689087b9293b3dabe1e`; this active PR carries the
+next-release bounded reliability contract and remains unintegrated. The contract
+does not change transport, persistence, credentials, models, tenancy,
+authorization, collaboration-provider, or network authority.
+
+## Active-PR contract
+
+`HtmlToMarkdownOptions.maxHtmlBytes` is an optional positive safe integer. The
+active implementation defaults to 16 MiB and rejects configured values above a
+64 MiB hard maximum. The public runtime option bag is snapshotted before source
+sizing or parser work: only ordinary/null-prototype enumerable data properties
+for `includeImageAlt` and `maxHtmlBytes` are accepted. Accessor-backed options
+are rejected without invoking their getters. Exotic prototypes, symbol or
+unknown keys, non-enumerable properties, malformed `includeImageAlt`, and
+hostile reflection failures also fail closed through the stable resource error.
+
+JavaScript Proxy meta-object traps are a distinct boundary: inspecting an
+untrusted option object's prototype/descriptors necessarily performs language
+reflection and can execute a Proxy `getPrototypeOf`, `ownKeys`, or
+`getOwnPropertyDescriptor` trap. Inkspan does not claim otherwise. A thrown or
+malformed reflection result is normalized to the payload-redacted
+`HtmlToMarkdownResourceError` contract and is never reflected to diagnostics;
+callers that require a no-caller-code boundary must pass ordinary or
+null-prototype data objects rather than Proxies.
+
+The HTML source itself must be a primitive string. Non-string runtime input is
+rejected before reading caller properties, `TextEncoder` coercion, browser DOM
+materialization, or browserless parsing. For accepted strings, Inkspan first
+compares JavaScript UTF-16 code-unit length to the selected byte ceiling. Because
+each code unit contributes at least one UTF-8 byte, that check can reject inputs
+that are certainly oversized without allocating a complete encoded buffer.
+Inputs not rejected by that lower bound receive an exact UTF-8 byte-length check
+before any browser DOM or browserless Turndown parser is reached.
+
+Oversized input raises a stable redacted error with name
+`HtmlToMarkdownResourceError`, code `input_too_large`, and no caller-controlled
+HTML in its message. Non-string input uses code `invalid_input`; malformed
+runtime options/resource-limit configuration use code `invalid_configuration`.
+Accepted safe-link, strict inline-raster, image-alt, normalization,
+browserless-package, and deterministic conversion semantics remain unchanged.
+
+## Verification
+
+The active PR carries machine tests that prove:
+
+- obvious oversize does not invoke `TextEncoder.encode()` or browser template
+  creation;
+- hostile non-string input is rejected before caller property access, encoding,
+  or parser work and without leaking caller-thrown values;
+- non-ASCII input still uses exact UTF-8 byte accounting;
+- exact-boundary input remains accepted;
+- accessor-backed option properties are rejected without executing their
+  getters, while a hostile Proxy prototype-reflection trap is explicitly proven
+  to execute once and its private thrown value is normalized/redacted;
+- malformed option bags and wrong-type, fractional, zero, and above-maximum
+  limits fail closed without reflecting input content; and
+- the packed ESM runtime and strict TypeScript consumer exercise the public
+  resource-bound surface while retaining the no-network/no-credential package
+  authority check.
+
+This document is active-PR truth only. It must not be represented as protected
+behavior until the implementation is integrated into protected `main`. Issue
+#118 continues to own the exact `0.6.0` protected release-candidate operational
+boundary, so this next-release lane remains Draft and unmerged while that
+identity is active.
+
+## Rollback
+
+Before protected integration, rollback removes this active-PR option, resource
+policy module, regression tests, packed-consumer assertions, and this doctoring
+record together. After integration, reducing the documented hard ceiling or
+changing error codes/messages is a public compatibility decision and requires
+versioned release treatment.

docs/plain-text-projection.md

@@ -54,6 +54,30 @@ default policy. Informative image alternatives remain in reading order, which
 allows indexing and AI workflows to retain author-supplied non-visual meaning
 without receiving image bytes.
 
+## Next-release parser resource bounds
+
+Status: `implemented_on_active_pr` in #174. Protected `main` does not yet expose
+these plain-text-specific options, so this section is not a shipped-release
+claim.
+
+The active contract accepts `maxMarkdownBytes` on `markdownToPlainText()` and
+checks the exact UTF-8 byte size before the Marked lexer materializes tokens.
+The inherited Markdown parser policy defaults to 16 MiB and rejects configured
+limits above the 64 MiB hard maximum. Invalid configuration and oversized input
+fail closed through the same stable, payload-redacted Markdown resource errors
+used by the shared Markdown package boundary.
+
+`htmlToPlainText()` additionally accepts `maxHtmlBytes`. That ceiling is checked
+before HTML normalization, and `maxMarkdownBytes` is checked again on the
+normalized Markdown before it enters the plain-text lexer. The two bounds are
+intentionally independent because HTML normalization can change representation
+size. Accepted-input reading-order, list/table/code, image-alt, link-label and
+raw-HTML omission semantics remain unchanged.
+
+These local parser bounds are defense in depth, not transport or persistence
+authority. Hosts still own request/ingress limits, authorization, tenancy,
+durable storage, retention and operational admission control.
+
 ## Runtime and interoperability boundary
 
 `markdownToPlainText` uses Marked's lexer and does not execute raw HTML, open a

scripts/verify-markdown-subpath-package.mjs

@@ -108,26 +108,75 @@ Object.defineProperty(globalThis, 'document', {
   configurable: true,
   get() { throw new Error('ambient document access is forbidden'); },
 });
+Object.defineProperty(globalThis, 'window', {
+  configurable: true,
+  get() { throw new Error('ambient window access is forbidden'); },
+});
 const markdown = await import('${packageJson.name}/markdown');
 const {
+  DEFAULT_HTML_TO_MARKDOWN_MAX_BYTES,
+  DEFAULT_MARKDOWN_TO_HTML_MAX_BYTES,
+  MAXIMUM_HTML_TO_MARKDOWN_MAX_BYTES,
+  MAXIMUM_MARKDOWN_TO_HTML_MAX_BYTES,
+  HtmlToMarkdownResourceError,
+  MarkdownToHtmlResourceError,
   htmlToMarkdown,
   markdownToEmailHtml,
   markdownToHtml,
   markdownToPlainText,
   normalizeMarkdown,
 } = markdown;
+assert.equal(DEFAULT_HTML_TO_MARKDOWN_MAX_BYTES, 16_777_216);
+assert.equal(MAXIMUM_HTML_TO_MARKDOWN_MAX_BYTES, 67_108_864);
+assert.equal(DEFAULT_MARKDOWN_TO_HTML_MAX_BYTES, 16_777_216);
+assert.equal(MAXIMUM_MARKDOWN_TO_HTML_MAX_BYTES, 67_108_864);
 const safeHtml = markdownToHtml('[safe](https://example.com)');
 assert.equal(safeHtml.includes('href="https://example.com"'), true);
 assert.doesNotMatch(markdownToHtml('[unsafe](javascript:alert(1))'), /href=/u);
+let markdownBoundedFailure;
+try {
+  markdownToHtml('oversized', { maxMarkdownBytes: 4 });
+} catch (error) {
+  markdownBoundedFailure = error;
+}
+assert.equal(markdownBoundedFailure instanceof MarkdownToHtmlResourceError, true);
+assert.equal(markdownBoundedFailure?.name, 'MarkdownToHtmlResourceError');
+assert.equal(markdownBoundedFailure?.code, 'input_too_large');
+assert.equal(
+  markdownBoundedFailure?.message,
+  'Markdown-to-HTML input exceeds the configured byte limit.',
+);
 assert.equal(htmlToMarkdown('<p>Alpha <strong>Beta</strong></p>'), 'Alpha **Beta**');
+let htmlBoundedFailure;
+try {
+  htmlToMarkdown('<p>oversized</p>', { maxHtmlBytes: 4 });
+} catch (error) {
+  htmlBoundedFailure = error;
+}
+assert.equal(htmlBoundedFailure instanceof HtmlToMarkdownResourceError, true);
+assert.equal(htmlBoundedFailure?.name, 'HtmlToMarkdownResourceError');
+assert.equal(htmlBoundedFailure?.code, 'input_too_large');
+assert.equal(
+  htmlBoundedFailure?.message,
+  'HTML-to-Markdown input exceeds the configured byte limit.',
+);
 assert.equal(markdownToPlainText('**Alpha** [Beta](https://example.com)'), 'Alpha Beta');
 assert.equal(normalizeMarkdown('**Alpha**').includes('**Alpha**'), true);
+assert.throws(
+  () => normalizeMarkdown('oversized', { maxMarkdownBytes: 4 }),
+  (error) => error instanceof MarkdownToHtmlResourceError && error.code === 'input_too_large',
+);
 const email = markdownToEmailHtml('Hello', {
   fullDocument: true,
   languageTag: 'ko-kr',
   textDirection: 'ltr',
 });
 assert.equal(email.includes('<html lang="ko-KR" dir="ltr">'), true);
+assert.throws(
+  () => markdownToEmailHtml('oversized', { maxMarkdownBytes: 4 }),
+  (error) => error instanceof MarkdownToHtmlResourceError && error.code === 'input_too_large',
+);
+delete globalThis.window;
 delete globalThis.document;
 `,
     'utf8',
@@ -141,11 +190,34 @@ Object.defineProperty(globalThis, 'document', {
   configurable: true,
   get() { throw new Error('ambient document access is forbidden'); },
 });
+Object.defineProperty(globalThis, 'window', {
+  configurable: true,
+  get() { throw new Error('ambient window access is forbidden'); },
+});
 const markdown = require('${packageJson.name}/markdown');
 assert.equal(typeof markdown.markdownToHtml, 'function');
 assert.equal(markdown.htmlToMarkdown('<p>Gamma</p>'), 'Gamma');
+assert.equal(markdown.DEFAULT_HTML_TO_MARKDOWN_MAX_BYTES, 16_777_216);
+assert.equal(markdown.MAXIMUM_HTML_TO_MARKDOWN_MAX_BYTES, 67_108_864);
+assert.equal(typeof markdown.HtmlToMarkdownResourceError, 'function');
+assert.equal(markdown.DEFAULT_MARKDOWN_TO_HTML_MAX_BYTES, 16_777_216);
+assert.equal(markdown.MAXIMUM_MARKDOWN_TO_HTML_MAX_BYTES, 67_108_864);
+assert.equal(typeof markdown.MarkdownToHtmlResourceError, 'function');
+assert.throws(
+  () => markdown.markdownToHtml('oversized', { maxMarkdownBytes: 4 }),
+  (error) => error instanceof markdown.MarkdownToHtmlResourceError && error.code === 'input_too_large',
+);
+assert.throws(
+  () => markdown.normalizeMarkdown('oversized', { maxMarkdownBytes: 4 }),
+  (error) => error instanceof markdown.MarkdownToHtmlResourceError && error.code === 'input_too_large',
+);
 assert.equal(typeof markdown.markdownToEmailHtml, 'function');
+assert.throws(
+  () => markdown.markdownToEmailHtml('oversized', { maxMarkdownBytes: 4 }),
+  (error) => error instanceof markdown.MarkdownToHtmlResourceError && error.code === 'input_too_large',
+);
 assert.equal(markdown.markdownToPlainText('# Title'), 'Title');
+delete globalThis.window;
 delete globalThis.document;
 `,
     'utf8',
@@ -162,27 +234,53 @@ function verifyDeclarationConsumer() {
   writeFileSync(
     sourcePath,
     `import {
+  DEFAULT_HTML_TO_MARKDOWN_MAX_BYTES,
+  DEFAULT_MARKDOWN_TO_HTML_MAX_BYTES,
+  MAXIMUM_HTML_TO_MARKDOWN_MAX_BYTES,
+  MAXIMUM_MARKDOWN_TO_HTML_MAX_BYTES,
+  HtmlToMarkdownResourceError,
+  MarkdownToHtmlResourceError,
   htmlToMarkdown,
   htmlToPlainText,
   markdownToEmailHtml,
   markdownToHtml,
   markdownToPlainText,
   normalizeMarkdown,
   type HtmlToMarkdownOptions,
+  type HtmlToMarkdownResourceErrorCode,
   type MarkdownToEmailHtmlOptions,
+  type MarkdownToHtmlOptions,
+  type MarkdownToHtmlResourceErrorCode,
+  type NormalizeMarkdownOptions,
   type PlainTextOptions,
 } from '${packageJson.name}/markdown';
-const htmlOptions: HtmlToMarkdownOptions = { includeImageAlt: false };
+const htmlOptions: HtmlToMarkdownOptions = {
+  includeImageAlt: false,
+  maxHtmlBytes: 1024,
+};
+const markdownOptions: MarkdownToHtmlOptions = { maxMarkdownBytes: 1024 };
+const normalizeOptions: NormalizeMarkdownOptions = { maxMarkdownBytes: 1024 };
+const htmlErrorCode: HtmlToMarkdownResourceErrorCode = 'input_too_large';
+const htmlResourceError = new HtmlToMarkdownResourceError(htmlErrorCode);
+const markdownErrorCode: MarkdownToHtmlResourceErrorCode = 'input_too_large';
+const markdownResourceError = new MarkdownToHtmlResourceError(markdownErrorCode);
 const emailOptions: MarkdownToEmailHtmlOptions = {
   fullDocument: true,
   languageTag: 'en-US',
   textDirection: 'ltr',
+  maxMarkdownBytes: 1024,
 };
 const plainOptions: PlainTextOptions = { includeImageAlt: true };
 void [
-  markdownToHtml('x'),
+  DEFAULT_HTML_TO_MARKDOWN_MAX_BYTES,
+  MAXIMUM_HTML_TO_MARKDOWN_MAX_BYTES,
+  DEFAULT_MARKDOWN_TO_HTML_MAX_BYTES,
+  MAXIMUM_MARKDOWN_TO_HTML_MAX_BYTES,
+  htmlResourceError.code,
+  markdownResourceError.code,
+  markdownToHtml('x', markdownOptions),
   htmlToMarkdown('<p>x</p>', htmlOptions),
-  normalizeMarkdown('x'),
+  normalizeMarkdown('x', normalizeOptions),
   markdownToEmailHtml('x', emailOptions),
   markdownToPlainText('x', plainOptions),
   htmlToPlainText('<p>x</p>', plainOptions),

src/components/editorSerialization.ts

@@ -1,15 +1,23 @@
 import type { EditorMode } from '../types.js';
-import {
-  htmlToMarkdown,
-  markdownToEditorHtml,
-} from '../markdown/serializer.js';
+import { htmlToMarkdown } from '../markdown/serializer.js';
+import { markdownToEditorHtml } from '../markdown/resourceBoundMarkdown.js';
+
+const INVALID_MODE_ERROR = 'Editor mode must be markdown or html.';
+
+function assertEditorMode(mode: EditorMode): void {
+  if (mode !== 'markdown' && mode !== 'html') {
+    throw new RangeError(INVALID_MODE_ERROR);
+  }
+}
 
 /** Convert a host value in the selected editor mode into TipTap HTML. */
 export function editorValueToHtml(value: string, mode: EditorMode): string {
+  assertEditorMode(mode);
   return mode === 'markdown' ? markdownToEditorHtml(value) : value;
 }
 
 /** Convert TipTap HTML into the serialization selected by the host. */
 export function editorHtmlToValue(html: string, mode: EditorMode): string {
+  assertEditorMode(mode);
   return mode === 'markdown' ? htmlToMarkdown(html) : html;
 }

src/components/editorSerializationRuntime.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import {
+  editorHtmlToValue,
+  editorValueToHtml,
+} from './editorSerialization.js';
+
+const INVALID_MODE_ERROR = 'Editor mode must be markdown or html.';
+
+describe('editor serialization runtime mode contract', () => {
+  it('rejects an invalid runtime mode before converting a host value', () => {
+    expect(() => editorValueToHtml('# Heading', 'md' as never)).toThrowError(
+      new RangeError(INVALID_MODE_ERROR),
+    );
+  });
+
+  it('rejects an invalid runtime mode before converting editor HTML', () => {
+    expect(() => editorHtmlToValue('<p>Body</p>', 'rich' as never)).toThrowError(
+      new RangeError(INVALID_MODE_ERROR),
+    );
+  });
+});