pagerite/docs/messages.md

Contact messages

Visitor→admin messaging built into the site: a {contact: Label} directive in article Markdown renders a button that opens a chat-style panel; messages are stored in the kanta database and answered from the admin inbox on /_a. Visitors are anonymous — a localStorage session token identifies their thread — and everything realtime rides the two existing WebSockets; there is no REST polling anywhere.

• pagerite/messages.py — the feature's core: the strict message renderer, thread store ops, wire payloads, both socket protocols and the /_contact/files upload route.
• pagerite/data.py — Data.contact (ContactThread/ContactMessage).
• pagerite/tracking.py — the sockets the protocol rides (see below).
• pagerite/views.py — the {contact:} directive (_contact_tag) and the on-demand bundle's asset config.
• frontend/src/contact-main.js + ContactPanel.vue — the visitor panel, imported on demand by pagerite.js on trigger clicks.
• frontend/src/Composer.vue + richtext.js — the shared composer and its DOM→Markdown serializer.
• frontend/src/MessagesView.vue — the admin inbox (the messages tab of AnalyticsView.vue on /_a).

Trigger

A lone {contact: Label} line in article Markdown (the block-directive machinery of markdown.py) renders <button class="contact-trigger">Label</button> ("Contact us" when the label is empty). pagerite.js click-delegates these buttons and lazy-loads the contact bundle; the editor preview renders the same button inert, and description/card mining resolves the tag to nothing. The label lives in the chunk, so translated pages localize it like any other text. Feeds render the tag as its literal source (no directive context).

Visitor side

The token is crypto.randomUUID() in localStorage (pagerite-contact-token), generated on first use; the server stores only its blake3 hash as the thread key. Pages are shared/cached renders, so the thread UI is entirely client-side. A per-browser "seen" timestamp (pagerite-contact-seen) drives the unread dot on trigger buttons when an admin reply arrives while the panel is closed.

The panel rides the public /_ws activity socket via a bridge in pagerite.js (register/send, sharing its queue and reconnect pacing — no extra connection). Frames to the server:

• {token} — register/resync; the current thread state is pushed back. pagerite.js re-sends this on every socket (re)connect, which is the resync mechanism (the socket idle-closes after 5 min and reconnects on activity).
• {token, msg, pow, fr} — append a message; msg is the Markdown-subset source, pow the solved proof-of-work (below), fr the page path it was sent from (stored for context).

Frames from the server: {type: "thread", id, created, unread, messages: [{id, t, admin, html, page}]} — a full thread snapshot (replace/upsert by id); {type: "pow", challenge, required} — a fresh single-use PoW challenge (required means the last message was rejected for a missing/stale solution and should be re-sent once solved); or {type: "contact-error", detail}.

Proof of work (anti-spam)

Sends are gated by easypow (PBKDF2 challenges, ~5 s solving cost). The server hands a fresh single-use challenge with every registration/resync and after every accepted message; the panel solves it in the background with the bundled solver module (served from the installed package at /_contact/easypow.js, so client and validator versions always match), typically finishing while the user is still writing. Each message burns one solution — a send with a missing, stale or already-spent solution is dropped and answered with a fresh required challenge, which the client solves and retries once. Challenges live in per-socket RAM state only.

Admin side

Admins watch the inbox as the messages tab on /_a, served by the existing /_api/ws/analytics socket (admin-gated like all of /_api). Analytics payloads keep their type-less snapshot shape; messaging frames always carry a type field, and that is how the client tells them apart. On connect the server sends {type: "threads", threads: [...]} (100 most recently active); new messages and replies push single-thread updates. Admin→server frames: {type: "reply", id, text} and {type: "read", id}. Replies are authored with the SSO remote-user name and mark the thread read; unread on a thread means its last message is the visitor's and newer than the admin's last read.

Message format and the XSS model

Bodies are a Markdown subset — emphasis, links, lists, code, plus /_f/ image and file references — serialized client-side from a constrained contenteditable composer (plain-text paste only; formatting via toolbar; uploads insert image/attachment-chip nodes).

No user HTML is ever rendered or sanitized. Sanitizing arbitrary HTML is unwinnable, so the design never attempts it: the composer serializes to text, and the server re-renders that text with a strict MarkdownIt instance (messages.py): html=False (the page renderer's trusted-author raw passthrough does not apply here), no plugins. Every byte of the stored html is markdown-it output from the constrained grammar. markdown-it also validates link protocols (javascript: & co. never become hrefs); the link rule adds rel="nofollow ugc noopener" + target="_blank" (and download + a chip class for /_f/ attachment links); images are restricted to /_f/ store names, anything else collapses to its alt text. Both panels inject this server-rendered HTML verbatim (v-html) — the one injection point, fed only by the strict renderer.

Uploads

PUT /_contact/files/{name} (public, like the messaging socket) stores panel uploads in the content-addressed file store. Images (raster and SVG) go through the usual AVIF/WebP/JPEG derivative pipeline and inline in the message — SVGs included: the extension-less link negotiates raster derivatives, and even an as-is-served .svg is script-inert inside an <img>. Everything else (videos, archives, html, exe…) is stored as an inert {hash}.file blob — the original extension is dropped on disk, so the store can never be double-click-executed — and linked as /_f/{hash}/{original-name}; the .file suffix exists only on the filesystem and is rejected in URLs. Serving is strictly separated: /_f/{name} serves media only (hash with or without extension), .orig. originals stay blocked, and the filename-carrying route serves only {name}.file blobs (never media, never by hash). Every /_f/ response carries content-disposition: attachment (no filename needed — the URL's last segment names the download) and x-content-type-options: nosniff, so a store file can never be rendered or sniffed into something executable in the site's origin; subresource fetches (<img>, <video>, favicons) ignore the disposition, so inline media is unaffected. The chip anchors additionally carry a download attribute. Uploads are deliberately not PoW-gated (the transfer rate is the real cost there); the gates are a session-shaped x-contact-token header, a 20 MB size cap, and a pending-upload quota — 10 un-sent files per session, answered 429 (not 403, which could trip auth flows). Every upload stays pending per session: a sent message strikes the files it references off the pending set, and when the session's last socket closes the remaining pending files are deleted from the store. Admin uploads from the same composer go to the admin-gated /_api/files instead. Files left behind by a server restart (the pending set is RAM-only) still linger — no GC.

Storage

Data.contact: dict[bytes, ContactThread] in the kanta database, keyed by the 12-byte blake3 hash of the session token (never the token itself). A thread is created, admin_read, and messages: dict[str, ContactMessage] keyed by a sortable timestamp-random id (dict-keyed, so a save's database diff touches only the appended message). Each message stores t, the Markdown source md, its strict rendering html, admin ("" = visitor, else the SSO name) and page. Appends are single transactions (contact / contact:reply / contact:read).

Limits and deliberate gaps (MVP)

• Message source ≤ 8000 chars; uploads ≤ 20 MB and ≤ 10 pending per session; payloads cap at 100 threads × last 200 messages.
• No thread moderation (delete/block), no orphan-upload GC for files orphaned by a server restart, panel strings are English-only, and the admin inbox lists threads by token-hash prefix rather than enriched visitor identity.