feat: sanitize rich clipboard HTML

.github/workflows/ci.yml

@@ -13,11 +13,17 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   build-and-test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
       # pnpm version comes from the package.json "packageManager" field
       # (pnpm 10+), which is required to read `overrides` from
       # pnpm-workspace.yaml consistently with the committed lockfile.
@@ -40,7 +46,7 @@ jobs:
 
   office:
     name: Office / Python ${{ matrix.python-version }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix:
@@ -51,7 +57,10 @@ jobs:
     env:
       PYTHONPATH: src
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: ${{ matrix.python-version }}

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,53 @@ 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()`
+- Nested clipboard policy objects are preserved without accessor evaluation during editor construction and use accessor-safe paste-time configuration validation at the exact rich-paste boundary
+- 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
+- Closed `details` elements preserve only their first rendered summary, closed `dialog` subtrees are removed, and open variants are unwrapped through the ordinary sanitizer so source-only interactive content cannot become visible editor text
+- Native `progress` and `meter` widget subtrees and obsolete `noframes` and `noembed` fallback subtrees are removed so stripping their wrappers cannot promote source fallback text into ordinary visible editor prose
+- Hidden `datalist` suggestion and down-level fallback subtrees are removed so stripping the suggestion-source wrapper cannot promote non-rendered descendants into ordinary visible editor prose
+- Raw `mso-hide` declarations are parsed with exact case-insensitive property/value matching, closed and EOF-terminated CSS-comment removal, optional terminal `!important`, and false-positive guards instead of relying on browser CSSOM support for the proprietary Office property
+- CSS-escaped property and keyword forms of `mso-hide: all` are decoded for exact comparison, while invalid code points, escaped newlines, prefixes, and longer look-alike values remain visible instead of producing false-positive subtree removal
+- SafeClipboard uses the lowest-practical extension priority as the final ordinary TipTap paste transform, with an integration regression proving a prior host transform cannot reintroduce scripts or tracking images before parsing
+- A host-installed lower-priority transform or post-parse mutation is explicitly outside the supported safety contract and requires an independently verified equivalent validation boundary
+- 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 raw Office hidden-style variants including EOF-terminated CSS comments, false-positive cases, structural removed-element assertions, real TipTap transform-chain ordering, and standalone/Yjs regressions proving configuration accessors are not evaluated before paste
+- Added a test-first closed/open `details` and `dialog` regression that proves hidden additional or dialog content does not enter the sanitized fragment while rendered content remains
+- Added a test-first native-widget and obsolete-fallback regression proving ordinary visible text remains while `progress`, `meter`, `noframes`, and `noembed` descendants cannot surface after wrapper removal
+- Added a test-first `datalist` regression proving ordinary neighboring content remains while hidden suggestion and down-level fallback descendants cannot surface after wrapper removal
+- 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
+- Recorded that current jsdom results are not cross-engine browser evidence; version-pinned Chromium, Firefox, and WebKit differential fixtures are a publication gate for 0.6.0
+
+### Documentation
+- Documented preserved and removed clipboard content, Base64Image handoff, SSR behavior, error codes, modular ownership, performance bounds, rollback, and buyer integration
+- Documented closed interactive content against the WHATWG HTML Living Standard, including the source-rendering, accessibility, host-ownership, rollback, and cross-engine uncertainty boundaries
+- Documented native progress/gauge widgets and obsolete fallback elements against the WHATWG HTML Living Standard, including the fail-closed conversion decision, test-first evidence, residual risk, and rollback boundary
+- Documented hidden `datalist` suggestion and down-level fallback content against the WHATWG HTML Living Standard, including the linked-control, accessibility, host-ownership, rollback, and cross-engine uncertainty boundaries
+- Documented OWASP's DOMPurify recommendation, the bespoke sanitizer's vulnerability-response obligation, final-transform composition limits, and the current browser-assurance boundary
+- Added Mermaid architecture and trust-boundary diagrams to `ARCHITECTURE.md`
+
 ## [0.5.29] — 2026-08-05
 
 ### Added