Problem reports on guides, with optional email to the owner (#99) #148

Merged
miko merged 3 commits from feature/99-problem-reports into development 2026-11-06 14:00:00 +01:00
Owner

Closes #99.

  • Report a problem from a step's heading (flag) or the end of a guide, for everyone who can read it, guests included: text up to 1000 characters, optional step, signed-in reporters named
  • Spam protection: honeypot field and an in-memory limit of 5 reports per 15 minutes per user or guest address (last X-Forwarded-For entry)
  • /reports: admins see all reports, authors those on guides they may edit; Open/Resolved tabs, "Mark as resolved" records who and when. Badge with open reports in the admin menu (admins) and the user menu (authors). Guests get a 404
  • Email (optional): admins set the SMTP server under Settings → Email (host, port, TLS/STARTTLS/none, user, password, sender) and can send themselves a test email. The owner is emailed in their locale, or the admins once the owner is no longer an author. Failures are logged, the report is kept
  • SMTP password stored with AES-256-GCM under a key derived from AUTH_SECRET, never sent back to the browser; after a restore with another AUTH_SECRET the settings ask for it again
  • Backups include reports; older backups still restore. Not part of guide packages or duplicates
  • New ProblemReport model and migration; /reports is now a reserved address (changelog)
  • ADR-0025, GLOSSARY, CHANGELOG, user and admin handbook (email settings, reverse proxy); three new handbook screenshots, others regenerated

Dependency: nodemailer 10.3.1. It makes npm nest @auth/core under next-auth, so the JWT type augmentation in src/auth/auth.ts now targets next-auth/jwt.

Tests: unit tests for report validation, rate limiter, recipients and email text, older backups, password sealing, the SMTP form and transport options; e2e/problemReports.spec.ts for the report flow and permissions, e2e/settings.spec.ts for the email settings and a failing test email. Typecheck, lint, 610/610 unit, 90/90 e2e, handbook zensical build --strict clean.

After merging: restart the dev server (new migration, Prisma client, dependency).

🤖 Generated with Claude Code

Closes #99. - **Report a problem** from a step's heading (flag) or the end of a guide, for everyone who can read it, guests included: text up to 1000 characters, optional step, signed-in reporters named - **Spam protection:** honeypot field and an in-memory limit of 5 reports per 15 minutes per user or guest address (last `X-Forwarded-For` entry) - **`/reports`:** admins see all reports, authors those on guides they may edit; Open/Resolved tabs, "Mark as resolved" records who and when. Badge with open reports in the admin menu (admins) and the user menu (authors). Guests get a 404 - **Email (optional):** admins set the SMTP server under Settings → Email (host, port, TLS/STARTTLS/none, user, password, sender) and can send themselves a test email. The owner is emailed in their locale, or the admins once the owner is no longer an author. Failures are logged, the report is kept - **SMTP password** stored with AES-256-GCM under a key derived from `AUTH_SECRET`, never sent back to the browser; after a restore with another `AUTH_SECRET` the settings ask for it again - **Backups** include reports; older backups still restore. Not part of guide packages or duplicates - New `ProblemReport` model and migration; `/reports` is now a reserved address (changelog) - ADR-0025, GLOSSARY, CHANGELOG, user and admin handbook (email settings, reverse proxy); three new handbook screenshots, others regenerated Dependency: `nodemailer` 10.3.1. It makes npm nest `@auth/core` under `next-auth`, so the JWT type augmentation in `src/auth/auth.ts` now targets `next-auth/jwt`. Tests: unit tests for report validation, rate limiter, recipients and email text, older backups, password sealing, the SMTP form and transport options; `e2e/problemReports.spec.ts` for the report flow and permissions, `e2e/settings.spec.ts` for the email settings and a failing test email. Typecheck, lint, 610/610 unit, 90/90 e2e, handbook `zensical build --strict` clean. After merging: restart the dev server (new migration, Prisma client, dependency). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Readers, guests included, report that a guide or one of its steps is
wrong or unclear; owners and wiki-mode authors see the reports on their
guides at /reports, admins all of them, with a badge of the open ones,
and mark them resolved. A honeypot and an in-memory rate limit keep spam
out; with SMTP_URL set, the owner (or the admins) get an email. Reports
are part of instance backups. Decisions in ADR-0025.

nodemailer 10 makes npm nest @auth/core under next-auth (its optional
nodemailer peer range stops at 8), so the JWT augmentation now targets
next-auth/jwt, as Auth.js v5 documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Admins set the SMTP server under Settings → Email: host, port, security
(TLS, STARTTLS, none), user, password and sender, and send themselves a
test email that shows the server's error if it fails. Without a host,
kataba sends no emails, as before.

The password is stored beside the other settings, and so in backups,
sealed with AES-256-GCM under a key derived from AUTH_SECRET, and never
sent back to the browser; an empty field keeps it. After a restore into an
instance with another AUTH_SECRET it cannot be opened, and the settings
ask for it again (ADR-0025).

SMTP_URL and SMTP_FROM are gone from .env.example, the Compose file and
the handbook; they were never released.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit 6d295def68 into development 2026-11-06 14:00:00 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!148
No description provided.