feat: sanitize rich clipboard HTML

ARCHITECTURE.md

@@ -0,0 +1,121 @@
+# Inkspan Architecture
+
+Inkspan is a modular rich-document engine that can run as a standalone React
+editor or as a provider-neutral Yjs collaboration module. The repository keeps
+probabilistic, transport, persistence, identity, and tenant policy outside the
+editor while supplying deterministic document, safety, accessibility, and
+interoperability contracts.
+
+```mermaid
+flowchart TB
+    Host[Host application / naruon / CWL service]
+    React[Standalone CwlEditor]
+    Collab[CollaborativeCwlEditor]
+    Kit[Shared TipTap extension kit]
+    Clip[Safe rich clipboard boundary]
+    Link[SafeLink URI boundary]
+    Image[Base64Image binary-image boundary]
+    PM[TipTap / ProseMirror document]
+    Snap[Snapshots and versioned envelopes]
+    Rev[Canonical revision evidence]
+    Auto[Single-flight durable autosave session]
+    HostStore[Host transport, authorization, tenant isolation, persistence]
+    Office[Deterministic Office renderer]
+
+    Host --> React
+    Host --> Collab
+    React --> Kit
+    Collab --> Kit
+    Kit --> Clip
+    Kit --> Link
+    Kit --> Image
+    Clip --> PM
+    Link --> PM
+    Image --> PM
+    PM --> Snap
+    Snap --> Rev
+    Rev --> Auto
+    Auto --> HostStore
+    Snap --> Office
+```
+
+## Module boundaries
+
+### Interactive editor graph
+
+- `src/components/` owns standalone React lifecycle, form integration,
+  accessibility attributes, editor callbacks, and imperative handles.
+- `src/collaboration/` owns the provider-neutral Yjs editor and public presence
+  projection. Hosts own network/provider lifecycle and authorization.
+- `src/extensions/` owns shared ProseMirror ingress and transaction policies.
+
+### Deterministic document graph
+
+- `documentEnvelope*` owns versioned, resource-bounded, duplicate-name-safe
+  structural persistence.
+- `documentRevisionEvidence*` owns RFC 8785 canonical bytes and SHA-256 equality
+  evidence.
+- `autosave/` owns bounded process-local scheduling and server-validator handoff,
+  not durable storage or transport.
+- `office/` owns network-free JSON-to-DOCX/XLSX/PPTX rendering.
+
+### Trust boundaries
+
+```mermaid
+flowchart LR
+    U[Untrusted clipboard / host input / remote collaboration update]
+    V[Bounded validation and semantic reconstruction]
+    D[Validated ProseMirror document]
+    E[Detached envelope and revision evidence]
+    H[Host-authorized durable transaction]
+
+    U --> V --> D --> E --> H
+```
+
+Untrusted content never receives authority from its text or markup. Clipboard
+HTML is parsed into an inert tree and reconstructed through a positive allowlist;
+unsafe links, resource-bearing HTML images, active elements, hidden content,
+and unbounded structures fail closed. Direct document writes and collaboration
+updates remain protected by active-schema, SafeLink, and inline-image policies.
+
+## Ownership matrix
+
+| Concern | Inkspan | Host or integrating service |
+| --- | --- | --- |
+| Editor schema and deterministic serialization | Owns | Consumes |
+| Clipboard, link, and inline-image ingress policy | Owns | Chooses documented limits and UX |
+| Accessibility semantics and document callbacks | Owns | Supplies labels, errors, and workflow |
+| Local collaboration binding | Owns | Owns Yjs document/provider lifecycle |
+| Local single-flight autosave ordering | Owns | Chooses enqueue/debounce timing |
+| Network, credentials, authentication | Does not own | Owns |
+| Authorization and tenant isolation | Does not own | Owns |
+| Durable persistence and atomic compare/commit | Does not own | Owns |
+| Migration, retention, backup, residency, audit | Does not own | Owns |
+| LLM/provider selection and model-use policy | Does not own | Owns |
+
+## Compatibility requirements
+
+- Standalone operation must not require naruon or any central CWL service.
+- Integration surfaces must remain narrow enough for naruon compose, `ui.panel`,
+  contextual-orchestrator, and other repositories to provide host policy without
+  forking Inkspan.
+- Framework-independent package subpaths must remain free of React, TipTap UI,
+  ProseMirror UI, Yjs, DOM, provider SDK, network, and credential dependencies
+  unless their documented contract explicitly requires one.
+- Database objects are host-owned. New objects must use at least two descriptive
+  words and prefer `snake_case`.
+- Default behavior changes require a minor version and a verified release-only
+  pull request after feature integration.
+
+## Quality gates
+
+Every production change is expected to maintain:
+
+- 100% production statement, branch, function, and line coverage;
+- complete public module, type, class, method, function, and property docs;
+- realistic security, interoperability, concurrency, and package-consumer tests;
+- deterministic builds and package contents;
+- exact-current-head CI, SAST, security, automated review, independent approval,
+  and branch protection;
+- `CHANGELOG.md`, operator docs, and APA 7 doctoring where standards or research
+  materially inform the design.

CHANGELOG.md

@@ -6,6 +6,36 @@ Historical release entries from **0.1.0 through 0.5.27** are preserved verbatim
 
 ## [Unreleased]
 
+### Added
+- Added a default `SafeClipboard` TipTap extension and `sanitizeRichClipboardHtml()` API that reconstruct browser-provided `text/html` through a strict semantic allowlist before ProseMirror parsing
+- Added `clipboard` byte/node/depth limits and a live `onClipboardError` observer to standalone and provider-neutral Yjs editor surfaces
+- Added root architecture, operator guidance, design, implementation-plan, and APA 7th doctoring records for the clipboard trust boundary
+
+### Changed
+- Rich HTML pasted from Word, Google Docs, email, and web pages now keeps supported structure and narrowly mapped bold/italic/underline/strike semantics while discarding arbitrary source styling and proprietary metadata
+- Standalone and collaborative editors now use exactly one shared clipboard policy through `buildExtensions()`
+- Because default rich-HTML paste behavior changes, the integrated feature targets the next minor release, **0.6.0**, only after a separate verified release PR
+
+### Security
+- Active, embedded, form, metadata, media, SVG/MathML, template, resource-bearing, hidden, and HTML-image subtrees are removed before insertion
+- Unsafe and credential-bearing links are unwrapped while visible text remains; SafeLink-approved links retain only exact `href` and fixed `noopener noreferrer nofollow`
+- IDs, classes, styles, event handlers, `data-*`, arbitrary ARIA, `contenteditable`, remote resources, local-file references, and Office/Google attributes never reach the output fragment
+- UTF-8 bytes, traversed nodes, and source depth are bounded; configuration accessors, symbols, unknown fields, invalid numbers, and reflection failures fail closed with static redacted error codes
+- Host error observers cannot weaken the rejection result and no rejected source HTML, URL, attribute, document text, tenant identifier, or parser exception enters public errors
+
+### Performance
+- Accepted clipboard traversal is iterative and linear in the bounded source tree; defaults are 1 MiB, 10,000 nodes, and 64 levels with documented hard ceilings
+- The feature adds no runtime dependency and performs no network, storage, clipboard-permission, model, provider, credential, or database operation
+
+### Tests
+- Added realistic Word-like and Google-Docs-like fixtures, Office conditional comments, style-to-semantic conversion, tables and lists, malformed HTML, active/embedded/resource content, hidden data, remote images, unsafe links, UTF-8 byte limits, breadth/depth limits, hostile configuration, DOM-unavailable execution, callback failure, and error-redaction cases
+- Added standalone and Yjs collaborative integration tests proving identical sanitizer behavior and latest-callback routing without editor or provider recreation
+- Kept repository-wide 100% production statement, branch, function, and line coverage as the merge gate
+
+### Documentation
+- Documented preserved and removed clipboard content, Base64Image handoff, SSR behavior, error codes, modular ownership, performance bounds, rollback, and buyer integration
+- Added Mermaid architecture and trust-boundary diagrams to `ARCHITECTURE.md`
+
 ## [0.5.29] — 2026-08-05
 
 ### Added

docs/clipboard-security.md

@@ -0,0 +1,124 @@
+# Safe rich clipboard ingestion
+
+Inkspan sanitizes `text/html` clipboard content before TipTap/ProseMirror parses
+or inserts it. The same policy is active in `CwlEditor` and
+`CollaborativeCwlEditor`, so a host does not have to maintain separate paste
+rules for local and Yjs-backed documents.
+
+## Default behavior
+
+The default limits are:
+
+| Limit | Default |
+| --- | ---: |
+| UTF-8 HTML bytes | 1,048,576 |
+| Source nodes | 10,000 |
+| Source depth | 64 |
+
+```tsx
+<CwlEditor
+  clipboard={{
+    maxHtmlBytes: 1_048_576,
+    maxNodes: 10_000,
+    maxDepth: 64,
+  }}
+  onClipboardError={(error) => {
+    // Safe for bounded telemetry or an accessible host notification.
+    console.warn(error.code);
+  }}
+/>
+```
+
+Configuration is read when the editor instance is created. Error observers are
+live: replacing `onClipboardError` does not recreate the editor or Yjs binding.
+Invalid configuration fails closed when rich HTML is pasted.
+
+## Preserved structure
+
+Inkspan reconstructs a new fragment containing only:
+
+- paragraphs, divisions, headings, blockquotes, preformatted text, code, line
+  breaks, and horizontal rules;
+- bold/strong, italic/emphasis, underline, strike, superscript, and subscript;
+- ordered and unordered lists;
+- tables, table sections, rows, header cells, and data cells;
+- hyperlinks that pass Inkspan's existing SafeLink URI policy.
+
+Word and Google Docs often represent visible semantics only through inline
+styles. Inkspan converts four narrowly defined styles before discarding all
+style attributes:
+
+- bold font weight → `<strong>`;
+- italic or oblique font style → `<em>`;
+- underline → `<u>`;
+- line-through → `<s>`.
+
+No colors, fonts, sizes, backgrounds, positioning, hidden content, direction
+overrides, or layout styles survive.
+
+## Removed content
+
+The sanitizer discards complete active, embedded, form, metadata,
+resource-fetching, media, SVG, MathML, canvas, template, and hidden subtrees.
+It also removes comments, Office conditional metadata, event handlers, IDs,
+classes, arbitrary ARIA, proprietary Office/Google attributes, `data-*`,
+`contenteditable`, and unapproved link attributes.
+
+Rich HTML `<img>` elements are always removed. This prevents remote tracking
+pixels, local-file references, and unvalidated data URIs. A binary image copied
+through the clipboard remains supported by the existing Base64Image pipeline,
+which applies file type, byte, decode, dimension, and inline-source policies.
+
+Unsafe links are unwrapped while their visible text is retained. Safe links keep
+only the exact `href` and receive
+`rel="noopener noreferrer nofollow"`. Inkspan never trims or repairs an
+untrusted link into a different browser interpretation.
+
+## Errors
+
+`ClipboardSanitizationError.code` is one of:
+
+```text
+dom_unavailable
+input_too_large
+node_limit_exceeded
+depth_limit_exceeded
+invalid_configuration
+invalid_html
+```
+
+Messages are static and do not contain the source HTML, URLs, clipboard text,
+attribute values, private parser exceptions, tenant identifiers, or document
+content. On rejection, the rich fragment becomes empty; Inkspan never falls back
+to unsanitized HTML.
+
+## Direct sanitizer API
+
+Hosts can apply the exact same policy outside the React component:
+
+```ts
+import { sanitizeRichClipboardHtml } from '@contextualwisdomlab/cwl-editor';
+
+const safeHtml = sanitizeRichClipboardHtml(untrustedHtml);
+```
+
+The function needs a DOM-capable document at call time but does not touch DOM
+globals at module import time. SSR can import Inkspan safely; invoke this API in
+a browser, jsdom-like controlled environment, or pass an explicit `Document` as
+the third argument.
+
+## Ownership boundary
+
+Inkspan owns clipboard HTML validation, semantic reconstruction, shared editor
+integration, bounded errors, and deterministic tests. The host still owns:
+
+- clipboard permissions or custom clipboard APIs;
+- user notification and recovery UX;
+- authentication, authorization, and tenant isolation;
+- persistence, retention, audit storage, and data residency;
+- downstream HTML rendering and Content Security Policy;
+- model or AI use of pasted content;
+- legal, privacy, and information-governance policy.
+
+The feature introduces no network request, storage adapter, credential,
+database object, model call, or provider dependency.