# 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, fr}` — append a message; `msg` is the Markdown-subset
  source, `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`), or `{type: "contact-error", detail}`.

## 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: raster images through
the usual AVIF/WebP/JPEG derivative pipeline, **anything else as-is**,
rendering as a download chip in the thread. The one exclusion is script
carriers (svg/html/xhtml/js/xml…) — an attachment URL can always be
opened directly in the site's origin, where such a file would execute.
Gates today: a session-shaped `x-contact-token` header, a 20 MB size cap
and the type blocklist. Admin uploads from the same composer go to the
admin-gated `/_api/files` instead. Files uploaded but never referenced by
a sent message currently linger (no orphan 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; payloads cap at 100
  threads × last 200 messages.
- **No proof-of-work yet**: the send and upload paths are the two seams
  where the PoW stamp plugs in (challenge on token registration, verify on
  `msg`/upload; one stamp may cover several messages).
- No thread moderation (delete/block), no orphan-upload GC, panel strings
  are English-only, and the admin inbox lists threads by token-hash prefix
  rather than enriched visitor identity.