# RFC-0007: Reader comments - Status: Accepted (2026-10-12, PR #13 merged by Halil; ADR-0022) - Author: Halil (Madraka), drafted with Claude · Date: 2026-10-12 - Related: ADR-0002 (storage, batch-only), ADR-0008 (precompiled validators), ADR-0011 (agent layer, policy engine), ADR-0012 (Cloudflare deployment: Workers Cache, cache tags, purge through the site Worker's own `/__cloudhal/purge`, no Cloudflare API token), ADR-0014 (approvals bound to a state hash), ADR-0015 (agent modes), ADR-0016 (elevation), ADR-0018 / RFC-0005 (roles and scopes), ADR-0021 / RFC-0006 (site analytics: the pattern for visitor-facing, privacy-sensitive features outside the graph), RFC-0002 (slug changes keep ids), `docs/security/threat-model.md`, `docs/design/DESIGN.md` - Owner decisions: Halil, 2026-10-12 (§0.1). This RFC adopts them and does not reopen them. §0.2 lists the defaults this draft chose for the remaining questions; each is marked **[default]** and can change at review. - Background: the maintainer's private research note on comment systems (2026-10-12). Nothing from it is copied here; the public sources it checked are listed below. - Sources (as checked on 2026-10-12; claims not re-verified for this draft are marked **[verify]** and collected in §2): - Cloudflare: Workers Cache purge and invalidate — https://developers.cloudflare.com/workers/cache/purge/ · purge limits (Free: 5 requests/min, bucket 25, 100 tags per request) — https://developers.cloudflare.com/cache/how-to/purge-cache/ · Rate Limiting binding — https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/ · Turnstile plans, hostnames, CSP, server-side validation — https://developers.cloudflare.com/turnstile/plans/ · https://developers.cloudflare.com/turnstile/additional-configuration/hostname-management/ · https://developers.cloudflare.com/turnstile/reference/content-security-policy/ · https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ · Workers AI pricing and Llama Guard 3 — https://developers.cloudflare.com/workers-ai/platform/pricing/ · https://developers.cloudflare.com/workers-ai/models/llama-guard-3-8b/ · D1 limits, pricing (index writes count as rows), data location and jurisdictions — https://developers.cloudflare.com/d1/platform/limits/ · https://developers.cloudflare.com/d1/platform/pricing/ · https://developers.cloudflare.com/d1/configuration/data-location/ · Workers limits — https://developers.cloudflare.com/workers/platform/limits/ · Email Sending pricing — https://developers.cloudflare.com/email-service/platform/pricing/ · Queues on Free — https://developers.cloudflare.com/changelog/2026-02-04-queues-free-plan/ - Prior art: EmDash (Cloudflare's Astro CMS, MIT; SSR comments on Workers and D1, `pending` by default, honeypot with fake success, Turnstile before rate limiting, salted IP hash, CAS on status) — https://github.com/emdash-cms/emdash · Ghost native comments and moderation — https://ghost.org/changelog/native-comments · https://ghost.org/changelog/comment-moderation/ · WordPress discussion settings and personal-data eraser — https://wordpress.org/documentation/article/settings-discussion-screen/ · https://developer.wordpress.org/reference/functions/wp_comments_personal_data_eraser/ · WordPress 6.9 Notes (editorial comments in the same table, the cautionary tale) — https://make.wordpress.org/core/2025/11/15/notes-feature-in-wordpress-6-9/ · Substack Reply Rules — https://support.substack.com/hc/en-us/articles/49712271829012 · Isso (signed edit cookie, rate limits) — https://isso-comments.de/docs/reference/server-config/ · Remark42 v1.18 security fixes — https://github.com/umputun/remark42 · ALTCHA (MIT, first-party proof of work) — https://github.com/altcha-org/altcha · Google on UGC links — https://developers.google.com/search/docs/crawling-indexing/qualify-outbound-links · https://developers.google.com/search/docs/monitor-debug/prevent-abuse · NPR retiring comments — https://www.niemanlab.org/2016/08/npr-is-retiring-the-comments-section-on-its-story-pages-because-of-disuse-not-just-garbage-fires/ - Law (information, not legal advice): GDPR Art. 17, 20 — https://gdpr-info.eu/art-17-gdpr/ · https://gdpr-info.eu/art-20-gdpr/ · CJEU Breyer C-582/14 — https://curia.europa.eu/jcms/upload/docs/application/pdf/2016-10/cp160112en.pdf · EDPB Guidelines 1/2024 (legitimate interest) — https://www.edpb.europa.eu/system/files/2024-10/edpb_guidelines_202401_legitimateinterest_en.pdf · DSA Art. 16, 17 and Recital 13 — https://www.eu-digital-services-act.com/Digital_Services_Act_Article_16.html · https://www.eu-digital-services-act.com/Digital_Services_Act_Article_17.html · KVKK (Law 6698) — https://www.kvkk.gov.tr/Icerik/6649/Personal-Data-Protection-Law · KVKK standard contracts — https://www.kvkk.gov.tr/Icerik/7938/Standart-Sozlesmeler-ve-Baglayici-Sirket-Kurallarina-Iliskin-Dokumanlar-Hakkinda-Kamuoyu-Duyurusu · Law 5651 actors — https://www.erdem-erdem.av.tr/en/insights/internet-actors-in-law-no.-5651 - Contracts on this branch: `comment.schema.json` and `comment-submission.schema.json` (§5), generated and tested in both languages (`pnpm gen`, `pnpm drift`, contract tests, `cargo test --workspace`, `cargo clippy --workspace --all-targets -- -D warnings`). ## Summary Cloudhal sites get first-party reader comments that work on Workers Free, on workers.dev and on custom domains, without a third-party script by default. Comments live in D1 **outside the site graph**, keyed by entry id; approved comments are rendered into the article's cached HTML and tagged `cloudhal-comments-`, so reading costs no extra request, and moderation purges that tag through the site Worker's existing purge path, coalesced to fit the Free purge budget it shares with publishing. Guests post through a plain HTML form guarded by a pipeline that runs before any D1 write (same-origin and schema checks, a honeypot, a cookie-less first-party proof of work, rate limits, content rules and a per-site daily cap), every guest comment waits for a person, agents triage with labels and reversible hides, and approving comments or replying on the site's behalf always needs a person, in every mode. ## Motivation - **Problem.** Readers cannot answer an article anywhere in Cloudhal. Publishers who want discussion today must embed a third-party service, which breaks the site's CSP promise (`script-src 'self'`), sends readers' data to another company, keeps the conversation outside the deployment, and leaves agents blind to it. The Ghost gap analysis lists comments among the publishing features Cloudhal lacks. - **Why it is not a small feature.** Comments are the first **free text written by visitors** that Cloudhal stores, renders and hands to agents. RFC-0006 deliberately reduced every visitor string to routes, hostnames and enums; comments cannot be reduced that way. They also carry personal data (a name, an optional email, a network address), need erasure, and must not drain D1 Free's 100,000 written rows a day, which the CMS shares. - **Who is affected.** - Readers want to ask and answer without creating an account, and without being tracked. - Authors and editors want a queue they can clear in minutes, per-article control, and replies that read as the publication's. - Owners want comments off until they choose otherwise, a clear privacy story, and no surprise bills. - Agents are the leverage: pre-moderation is what makes guest comments safe, and it is also what burns moderators out (Cusdis was archived; NPR closed its comments for low participation). An agent that hides obvious spam, labels the rest and drafts answers to questions turns a queue into a review. - **Why now.** The pieces exist: the site Worker already writes to D1 and answers first-party endpoints (`/__cloudhal/e`); published pages already carry cache tags and are purged through `/__cloudhal/purge` (ADR-0012 addendum); the policy engine, modes, approvals and roles are settled (ADR-0014–0018); RFC-0006 set the pattern for settings outside the graph. EmDash, Cloudflare's own Astro CMS, ships comments on Workers and D1 with nearly the same storage and render model, which shows the approach holds on the platform. Cloudhal's difference is agent-native moderation behind policy, modes, approvals and audit. ## Non-goals - **No third-party script by default.** Turnstile is opt-in per site (§7.6); Disqus-style embeds are out (Alternatives). - **No reader accounts in the MVP.** Verified readers (email code or magic link) are v1.1 (§0.1, decision 1); site memberships and paid comments are a later RFC built on them. - **No editorial comments.** Notes on drafts inside Studio are a separate later RFC (**RFC-0009**, editorial notes; RFC-0008 became schedules). WordPress 6.9 put its Notes into the comments table and has been excluding them from counts and queries since; editorial notes will get their own tables. - **No federation in this RFC.** Webmention and ActivityPub replies are later RFCs. The `source` enum reserves `webmention` and `activitypub` so they can enter the same queue later; v1 writers refuse them. - **No reactions, likes, votes, pins or "best" sorting** in the MVP (v1.1 for likes and pins). - **No comments on pages or term archives.** Comments attach to content entries (articles). Pages may follow if asked for. - **No hard delete or bans over MCP**, and no agent ever approves a comment or publishes a reply without a person (§0.1, decision 3). - **No comments in snapshots, diffs, rollbacks or `cloudhal push/pull` bundles** (§3, §15.4). - **No built-in email sender** in the MVP **[default]** (§0.2). - **No implementation in this RFC** beyond the two contracts. Rollout is in Compatibility & migration. ## Proposal ### 0. Decisions #### 0.1 Owner decisions (Halil, 2026-10-12), adopted 1. **MVP identity: guest comments with moderation.** A name and an optional, private email. Every guest comment is held for moderation (`pending`). Verified readers come in v1.1 — email code or magic link through a **second Better Auth instance** on the site Worker, with host-only cookies and Better Auth ≥ 1.7.7 (the release that fixed the magic-link takeover GHSA-965c-763c-88jm) — as the base for future members. 2. **Default bot protection: our own first-party proof of work**, served from the site's origin, cookie-less, so the CSP stays `'self'`. Turnstile is opt-in per site; when it is on, the CSP widens **only on pages with an open comment form**. 3. **AI and agents: labels and reversible hides; approval stays with people.** AI moderation runs only when the owner turns it on. Approving comments and publishing replies on the site's behalf always need a person, in every mode (including `auto` and local `bypass`). Hard delete and bans are not available over MCP. 4. **Reader comments first.** Editorial notes are RFC-0009, mentioned here only as a non-goal. #### 0.2 Defaults for the remaining questions (this draft's decisions; changeable at review) | # | Question | Default chosen here | |---|---|---| | D1 | Email sender | **None in the MVP.** Reply notifications and verified readers (v1.1) use an optional `MailSender` adapter: Resend with the owner's own key, or Cloudflare Email Sending on Workers Paid with a domain in the account. | | D2 | Agent keys | New keys get **`comments:read`** in their default scopes. Existing keys are not widened (RFC-0005), and Studio offers a one-click "Allow comments" per key. No email address or IP hash is ever exposed to an agent: the contract has no field for them. | | D3 | Client scripts | RFC-0006's rule becomes **"only first-party Cloudhal scripts under `/_cloudhal/`"**; threat-model promise 4 is reworded (§Security). | | D4 | Defaults per site | Comments are **off** for new and existing sites, enabled per site and per collection. Threads **close 90 days** after the entry's first publication, with a per-entry override. | | D5 | Erasure requests | **Anonymise the identity by default**; the moderator may also delete the text, case by case (GDPR Art. 17(3)(a) freedom of expression). Both are audited. | | D6 | Roles | Authors moderate comments on their own entries (`comments:moderate:own`) and reply on them (`comments:reply:own`). Commenter emails are visible only to Editors and above, through the person-only scope `commenters:data`. Contributors get no comment scopes in v1. | | D7 | Data location | `cloudhal deploy` offers **`--jurisdiction eu`** when it first creates the D1 database (a jurisdiction cannot be changed later). The docs add a KVKK cross-border transfer note (not legal advice). | | D8 | Portability | Comments are **not** in push/pull bundles. `cloudhal comments export|import` moves them as JSON lines; idempotent Disqus XML and WordPress WXR importers are v1.1. | | D9 | Reactions | Likes and reactions are v1.1; Webmention and ActivityPub later. | | D10 | EU DSA | A **"Report comment"** flow (Art. 16 notice and action) and **statement-of-reasons records** for every hide, spam, delete and erase (Art. 17) are built in. | | D11 | JavaScript-less posting | Accepted, with stricter limits and a small separate daily cap (§6.5), and switchable off per site. With Turnstile on it is off unless the owner allows it there too (2026-10-12 review, item 5). | | D12 | Guest edits | **None in the MVP.** A guest who wants a comment changed or removed asks the site; v1.1 adds a 15-minute edit window for verified readers. | ### 1. Overview ``` reader ── GET /posts/x ─────────────▶ Workers Cache (hit: the Worker never runs) │ HTML: approved comments (SSR) ·
(open threads) │