Security & Moderation

Opening up your website to public comments invites engagement, but it also invites spam and malicious actors. Diskus is built with security and moderation as first-class citizens, providing you with robust tools to keep your community safe.

Security Architecture

Role-Based Access Control (RBAC)

Diskus strictly separates privileges:

• Commenters: Standard users who can register, post comments, and edit/delete their own comments.
• Administrators: Super-users who have access to the Dashboard. Administrators can manage websites, delete any comment, mark users as spammers, and adjust global settings.

Server-Side Sanitization

We never trust client input. The Diskus Backend utilizes isomorphic-dompurify to aggressively sanitize all incoming HTML and Markdown content on the server.

• XSS Prevention: Malicious <script> tags, dangerous href links, and inline execution attempts are stripped out before the data is ever saved to the SQLite database.
• Client Safety: Because sanitization happens on the backend, the widget client bundle remains incredibly small and viewers are permanently protected.

Spam Prevention

To combat automated bot spam without relying on intrusive, privacy-invading CAPTCHAs, Diskus employs two mechanisms:

1. Invisible Honeypots: Registration and comment forms contain hidden fields (_diskus_trap). If an automated bot fills out these fields, the backend silently intercepts the request and returns a fake success response, discarding the spam payload.
2. Rate Limiting: The API enforces strict rate limits per IP address to prevent brute-force attacks and comment flooding.
   • Comment Posting: Maximum 30 comments per minute per IP.
   • User Login: Maximum 10 attempts per 15 minutes per IP.
   • Registration: Maximum 5 accounts per hour per IP.

Domain Verification (Embed Tokens)

To prevent unauthorized websites from embedding your widget and spamming your database, Diskus utilizes a strict embed token flow.

When the widget initializes, it requests a short-lived Embed Token. The backend verifies that the Origin and Referer headers of the request exactly match the domain registered to the provided App ID. Only if they match will the backend issue the JWT embed token. All subsequent API calls made by the widget must include this token to be processed.

Session Revocation (Token Versioning)

Authentication relies on JWTs (JSON Web Tokens). A common flaw with stateless JWTs is that they cannot be revoked before they expire if an account is compromised.

Diskus solves this using Token Versioning. Every user record in the database has a tokenVersion integer. Whenever an admin changes their password, this version is incremented. The authentication middleware validates the token version against the database on every request, ensuring that a password change instantly invalidates all previously issued JWTs across all devices.

Soft vs Hard Deletion

Diskus distinguishes between user deletions and admin deletions to preserve context and database integrity:

• Commenter Deletion (Soft Delete): When a user deletes their own comment, the comment is not removed from the database. Instead, its content is replaced with a tombstone (e.g., [Comment deleted]). This ensures that threaded replies beneath it are not orphaned.
• Admin Deletion (Hard Delete): When an admin deletes a comment permanently from the Trash queue, it is a hard database deletion. Due to SQLite’s CASCADE rules, deleting a parent comment will permanently obliterate all child replies beneath it.

Moderation Workflow

Administrators have access to a comprehensive Dashboard tailored for rapid moderation.

• Approval System: You can configure domains to require manual approval for all new comments before they are visible to the public.
• Spam Flagging: If a spammer bypasses the automated traps, you can manually mark their comment as spam.
• Data Deletion: Clean up threads by permanently deleting offensive or irrelevant comments.
• User Auditing: View the registration details and comment history of specific users across all your integrated domains.

Contributing to Diskus

We believe open-source thrives on community input. Pull requests are highly welcome!

How to Contribute

1. Discuss Major Changes: For significant architectural shifts or major new features, please open an Issue first to discuss your proposal with the maintainers.
2. Setup Local Dev: Follow the Quick Start guide to get the monorepo running locally.
3. Run Tests: Ensure you add or update tests for any new logic you introduce. We use Bun’s lightning-fast native test runner.

License

Diskus is open-source software licensed under the GPL-3.0 License. This ensures that the core software remains free and open for everyone.