LeoVasanko
e3080d70c0
Move the PoW state from a module-level dict keyed by WebSocket in
messages.py to a plain per-connection local in tracking.activity_ws,
making PoW a WS-level concern instead of being buried in the message
handler:
- activity_ws validates and burns the solution (raw.pop('pow')) before
forwarding a message frame, and issues a fresh challenge after every
registration and every vetted message frame; a failed validation is
answered with a 'required' challenge and the frame never reaches
messages.py.
- messages.py loses the _pow dict, _issue_pow and the disconnect
cleanup for it; visitor_frame needs no return value since a vetted
frame always triggers a fresh challenge (a too-long message simply
comes with contact-error and required=false, so the client does not
retry it).
The wire protocol and the frontend are unchanged.
160 lines
8.5 KiB
Markdown
160 lines
8.5 KiB
Markdown
# 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 are a per-connection local in the
|
||
`/_ws` handler (RAM 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 `href`s);
|
||
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.
|