HHostingByteSoftware
Ctrl K
ComunidadGuías…

ClipmanCli/WebPreview.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# Clipman browser history

Clipman Server 2.7.0 includes an opt-in HTTPS browser interface at `/web/`. See the [server manual](https://onjlouis.github.io/Clipman/server/manual.html#browser-history) for setup and security limits. Native apps and the database format are unchanged.

The Go browser program runs the existing encrypted-container codec and channel-aware sync engine in a dedicated WebAssembly worker. Browser-native PBKDF2 uses exactly the existing database parameters; native CLI behavior is unchanged. Text, links and existing Rich Text can be displayed. Secrets, file history and templates are excluded. This does not expand the separate CLI agent's plain-text/link permissions.

The local helper binds only to `127.0.0.1`. Its relay forwards authentication and encrypted blobs to one fixed server. History passwords and decrypted content do not enter the helper. It rejects cross-origin requests, unexpected Host headers, redirects, plaintext uploads, unconditional writes, arbitrary paths and deletions. An optional private connection document can be supplied through stdin to prefill the server token; this does not supply the history password.

Build the release assets with Python's `ClipmanServer/build_web.py --output <empty-external-folder> --go <go-executable> --server-output <new-external-script>`, from the repository root. Use patched Go 1.26.8 or newer. This builds `cmd/clipman-web` for WebAssembly and copies the matching Go runtime. The generated script embeds the versioned, hash-checked assets for compatibility with older updaters. Keep generated files outside source. The native `cmd/clipman-web-preview` helper remains available for isolated development; it is not needed by visiting devices and is not shipped as a separate CLI release.

## Test workflow

1. Enable HTTPS browser access on a disposable server and open its `/web/` address on a trusted computer.
2. Supply the server token or import its connection file, enter the existing history password and choose Connect. The preview refuses to create a missing history bucket.
3. Search and copy a familiar entry. If clipboard permission is denied, use the selected text in the Copy entry dialog with the browser's normal Copy command.
   Select Text, Links, Rich Text, or the combined Text and Links area. Area changes and page navigation filter already-loaded history without network requests. Numbered page controls show the first and last three pages plus the current page and its neighbours, with at most nine numbers. The bottom controls have a Page navigation heading and landmark; the status footer is named Clipman status.
   Complete HTTP/HTTPS entries also offer a link beside Copy, in Links and the combined area. Its name is the entry name (or URL if unnamed), followed by (opens in new tab), so screen-reader link navigation starts with the destination rather than a repeated action phrase. The destination cannot access the Clipman tab through its opener and receives no Clipman-page referrer. The Clipman page stays connected; the existing five-minute inactivity limit still applies while you are away. Truncated previews and other URL schemes do not offer this action.
   In Rich Text, choose View entry or Copy formatted. Headings, emphasis, lists, tables and supported embedded images are retained. The viewer is read-only; Escape or Close returns focus to the entry. Safe HTTP/HTTPS hyperlinks are retained when copying but are not clickable in the viewer. RTF-only entries explicitly offer a plain-text preview and copy, not RTF conversion. If formatted clipboard access is denied, the entry's Copy button offers selected plain text instead.
4. Add a clearly marked disposable Quick Clip and verify that the regular clients receive it. Quick Clip creates plain text or links, not formatted content. Delete the test entry using a regular client; deletion is intentionally not offered here.
   Enter inserts a new line. Control+Enter sends the clip; Command+Enter also works on Mac browsers. Held-key repeats are ignored, and normal required-field validation still applies.
5. Add a clip in a regular client, then choose Refresh in the browser. There is no automatic polling.
6. Choose Disconnect. Verify that the history and draft are gone. Closing the tab also terminates its worker. Five minutes without interaction disconnects automatically.

The optional `ui_test/links.browser.test.cjs` regression requires Playwright and the synthetic `TestBrowserFixture` helper. Set `CLIPMAN_PREVIEW_FIXTURE_URL` to that helper's address and optionally `CLIPMAN_TEST_BROWSER` to a Chromium executable. Without the fixture variable it explicitly skips; a skip is not browser coverage. It checks entry-first accessible link names, keyboard opening and retained history without contacting a real destination.

## Security and compatibility limits

- Rich HTML is parsed with Go's HTML5 parser and sanitized in the browser with vendored DOMPurify 3.4.16 (dual Apache-2.0/MPL-2.0 license in `cmd/clipman-web-preview/ui/DOMPurify-LICENSE.txt`). Scripts, forms, frames, SVG, external images, event handlers, IDs and inline styling are removed. This deliberately does not promise pixel-perfect formatting. No website is contacted to render or copy an entry.
- Rich previews accept at most 768 KiB HTML and 4096 parsed nodes. Embedded PNG/JPEG images must be at most 512 KiB and 2048 pixels per dimension; image headers are checked before browser rendering. Unsupported images are omitted without modifying stored history. Standalone images copy HTML with the original image bytes and filename marker, plus a PNG clipboard flavor; JPEG may be converted for that PNG flavor only.
- Nothing is stored in cookies, local/session storage, IndexedDB or a service worker, and responses request no caching. This does not guarantee erasure from browser memory, the OS clipboard, extensions, crash reports or a compromised computer. Disconnect cannot retract an already delivered upload.
- Production hosting is same-origin HTTPS, disabled by default. It requires an existing encrypted bucket and manually entered credentials. Reverse-proxy headers are accepted only from explicitly configured proxy peer IPs, with an exact advertised Host. Users must trust the delivered browser code and the server/proxy administrators. This does not bypass a restricted network or an employer's policies.
- Browser clipboard permission and gesture behavior differ. Normal text-field paste and manual copy remain fallbacks. Browser history sync being off does not make the computer trustworthy.
- Full encrypted blobs are downloaded before filtering. Display pages contain up to 100 entries, previews up to 4096 characters, and copied/added text up to 1 MiB. Concurrent writes use the existing conditional-write and merge behavior.
- No third-party security review or universal browser compatibility is claimed. Tests use disposable synthetic history. The opt-in `ui_test/server.browser.test.cjs` exercises real HTTPS with an isolated test-certificate pin, encrypted history and no native clipboard changes. The optional local fixture tests remain useful for browser differences. Skipped optional tests are not passes.