rendall / simple-comment

Simple Comment is a commenting platform for any website. Free, flexible, source-available, secure, private, and scalable.

Simple Comment

Simple Comment is a commenting platform for any website. Free, flexible, open-source, private, and scalable.

See the demo: https://simple-comment.netlify.app

Status

NB: Moderation tools are not yet adequate. There is no notification when a user has posted a comment, nor any way to hold it in moderation before approval. If you like this project and would like to see it developed further on a specific timeline, contact me. Otherwise, this project is still on the road, but on the slow road.

MVP is complete!

The minimum functionality is up and running!

Completed tasks: (click to open)

• Cross-origin capability
• Script with frontend
• All API endpoint respond as expected
  • Access-Control-Allow-Origin responds to .env variables
• Authentication and Identification works as expected
• Authenticated users and admins can interact with Simple Comment as expected
• Anonymous user can create topics
  • This is useful for sites with lots of pages
  • For security reasons, restrictions apply:
    • The Referer header and the topicId must map properly
    • The Origin must be on the Access-Control-Allow-Origin list
• Server-side validation of user-posted data
• Setup instructions
  • Are complicated but work when followed
• Visitor can post anonymously
  • Comment includes guest user
• Designed a beautiful badge!
  • 
• Visitors can read and reply to comments

Top priority after MVP

• Optional user authentication and identification
• Moderator holds posts for approval
• Spam prevention measures
• Integration with 3rd party authentication
• Email notification & integration
• Framework-friendly frontends
• Extensive helpful comments!
• E2E tests

Nice to haves

• Moderator change policy on holding posts for approval
• Visitor can claim ownership over anonymous posts
• Edit button
• Delete / edit time windows in policy
• User profiles
  • See comments
  • Avatar

Features

• Easy to use anywhere
• Industry-standard security
• Designed to be fully customizable
• Scalable, from free-tier to enterprise!
• Takes advantage of free-tier offerings from DBaaS and website hosts
• Fully documented API
  • Open API 3
• Ethical, no-track, visitor control over data
• Friendly and welcoming developer community

Upcoming features

• CLI (command-line interface) for
  • installation and setup
  • content moderation
  • user admininstration
• GraphQL endpoint
• GDPR compliance
  • Users can view and delete their own data without moderator
• Moderators can restrict visitor read and write access
  • IP whitelists, graylists and blacklists
  • User whitelists, graylists and blacklists
• User self-verification
• Optional connection to the Fediverse
• Support for other databases (PostgreSQL, Firestore, CockroachDB, etc) and hosting services (Heroku, AWS Lambda, GCS)
• Support Web Authentication API https://w3c.github.io/webauthn/
• User profiles
• Upvoting / Reactions

Setup

Simple Comment can be run on the same server as your website or on a separate, cross-domain server

It is necessary that Simple Comment is served via https:

Follow these instructions. If anything is unclear, please create a new issue

1. Fork this repository to your own account
2. Clone your fork
3. Copy example.env into the same, project root directory and rename it to be .env
4. In .env, enter your own (made up or randomly generated), secret values for these entries (i.e. replace everything to the right of = in each line).
   • SIMPLE_COMMENT_MODERATOR_CONTACT_EMAIL
   • SIMPLE_COMMENT_MODERATOR_ID
   • SIMPLE_COMMENT_MODERATOR_PASSWORD
   • JWT_SECRET
5. sign up for a free MongoDB Atlas account
   1. Follow these instructions
   2. In .env add the proper DB_CONNECION_STRING
6. Sign up for a Netlify account, begin a new website, and link your repository to the new website
   1. Review Netlify's Build environment variables page
   2. Navigate to 'Build & Deploy => Environment`
   3. Under Environmental Variables click the button Edit Variables
   4. For each entry in .env add the key and corresponding value for all variables
   5. For IS_CROSS_SITE add the value true if the comment system is hosted in its own domain and false if it is the same domain.
7. Modify your website. These are simple instructions, but feel free to hack away
   1. In the HTML for each page on your website where you want Simple Comment to run, add these two tags:
      1. <script src="[path-to]/simple-comment.js" defer></script> (src must point to the simple-comment.js file)
      2. <div id="simple-comment-display"></div>
   2. Upload the simple-comment.js file to your website's script folder
8. It should now be possible to leave and read comments on your website

Troubleshooting

• Error: Refused to connect to 'api/auth' because it violates the following Content Security Policy directive: connect-src 'self'
  • Add https://<your-comment-app>.netlify.app to your Content Security Policy header next to connect-src (q.v. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src)
• Error: Access to fetch at 'https://<your-comment-app>.netlify.app/.netlify/functions/' from origin '<your-website>' has been blocked by CORS policy...
  • Add <your-website> to the ALLOW_ORIGIN key in .env and as a Netlify environmental variable

Moderating

1. Visit the login.html page you uploaded in Setup and
2. Log in using the SIMPLE_COMMENT_MODERATOR_ID and SIMPLE_COMMENT_MODERATOR_PASSWORD values in your .env file

Default build

The default stack uses Netlify + MongoDB for the backend, and a minimal fetch based client for the frontend, but it can be readily adapted to use any technology stack, as long as the tests pass and the API conforms to the Open API 3 schema file

You can get your own free-tier MongoDB-in-the-cloud by following these instructions

Local development

Assumes a unix-like environment, like Ubuntu.

Installation

1. Install nvm
2. nvm install
3. npm install -g yarn
4. yarn install
5. yarn run build
6. Install and run MongoDB Community Edition

Test

1. yarn run test
2. yarn run test:e2e

Usage

1. sudo systemctl start mongod (q.v. Linux)
2. yarn run start
3. open http://localhost:7070/

API

The API specification is described by the file simple-comment-openapi3.json in Open API 3 format and is designed to be interchangeable with any backend, frontend and identification system

This is an overview of the Simple Comment API endpoints

/comment

A comment is text that a user posts in reply to either another comment or a topic, and presenting these replies is the sole reason this project exists!

The comment endpoint is for the creation, reading, updating and deleting (CRUD) of individual comments. All comments must have a parent, that is, something it replies to, whether a topic or comment

/topic

A topic is a special kind of comment that by default can only be created by admin users, and forms an organizational bucket for comments that reply. It is a kind of root comment, and therefore has no parent

The /topic endpoint handles CRUD for these root comments. A GET operation of /topic will get a list of topics and GET on /topic/{topicId} will get all comments in reply to that topic and their descendents

/user

By default, comments can be posted by anonymous users, but Simple Comment does have a minimal identification scheme so that commenters who choose to do so can have control over their comments after the are posted, according to policy

/auth

Auth is the endpoint for the authentication and identification scheme. A user submits their username and password to the auth endpoint, and receives a JSON Web Token (JWT) that authenticates them as that user for other CRUD operations

/verify

Returns the logged-in user id or 401

policy

policy is an object holding key-value pairs that governs how Simple Comment behaves, determining for instance maximum comment length or whether ordinary users can delete themselves.

{
  isGuestAccountAllowed : boolean, // if true, a visitor can post anonymously using a guest account. if false, only authenticated users can comment.
  canFirstVisitCreateTopic : boolean, // if a discussion does not exist for a page, shall it be created when visited for the first time, or does admin create all topics?
  canGuestCreateUser : boolean, // can a user with guest credentials create (their own) user profile? if 'canPublicCreateUser' is set to 'true' this setting is ignored
  canGuestReadDiscussion : boolean, // can a user with guest credentials browse and read discussions? if 'canPublicReadDiscussion' is set to 'true' this setting is ignored
  canGuestReadUser : boolean, // can a user with guest credentials view user profiles? if 'canPublicReadUser' is true, this setting is ignored
  canPublicCreateUser : boolean, // can a user with no credentials create (their own) user profile?
  canPublicReadDiscussion : boolean, // can a user with no credentials browse and read discussions?
  canPublicReadUser : boolean, // can an anonymous visitor view any user's profile?
  canUserDeleteSelf : boolean, // can a user delete their own profile?
  maxCommentLengthChars : number, // Attempting to post a comment longer than this number of characters will be rejected by the API
}

Alternatives

There are 34 solutions that are not Simple Comment listed here. Nearly all of these are more mature than Simple Comment, and I would recommend considering one if you are not looking specifically for a serverless, open-source, self-hosted solution. Listed below each are pros and cons that distinguish it from Simple Comment. If Trust is required is listed, it means that using the service requires trust in the company, because they will be serving closed-source code to your users that you do not control and cannot easily inspect; as well, user data will be held on servers they control. This list is based on public documentation, not experience. If anything is incorrect or missing, please let me know.

• Comment Box https://commentbox.io/
  • Free tier
  • Privacy focused
  • Data is held on 3rd party server
    • "No lock-in"
  • Trust is required
• Commentics https://www.commentics.org/
  • Open Source: GPL
  • Free tier with logo
  • Requires a server running PHP and MySQL
• Commento https://commento.io/
  • Privacy focused
  • Open Source: MIT
  • Self-host OR pay-to-host
• Discourse https://www.discourse.org/
  • Open source: GPL
  • Fully featured
  • Self-host OR paid version
  • No free tier
• Disqus https://disqus.com/ - The 400 pound gorilla of e
  • Free tier
  • Fully featured
  • Closed Source
  • Data is held on 3rd party server
  • Requires user login
  • Sells user data
  • Trust is required
• Facebook Comments Plugin https://developers.facebook.com/docs/plugins/comments/
  • Free tier
  • Fully featured
  • Closed Source
  • Data is held on 3rd party server
  • Requires Facebook
  • Requires user login
  • Sells user data
  • Trust is required
• FastComments https://fastcomments.com/
  • Fully featured
  • Privacy focused
  • Real-time chatting
  • HMAC authentication
  • No free tier
  • Trust is required
• GraphComment https://graphcomment.com/
  • Fully featured
  • Free tier
  • Closed Source
  • Data is held on 3rd party server
    • Guarantees "full and complete ownership" of data
    • Servers in Europe (France)
  • Requires user login
  • Trust is required
• HTML Comment Box https://www.htmlcommentbox.com/
  • Free tier
  • Closed Source
  • Data is held on 3rd party server
  • Trust is required
  • Privacy policy? Unknown.
• HashOver https://www.barkdull.org/software/hashover
  • Open Source: AGPL
  • Requires a server running PHP and MySQL
• Hyvor Talk https://talk.hyvor.com/
  • Privacy focused
  • No free tier
  • Requires user login
  • Trust is required
• IntenseDebate https://intensedebate.com/
  • Fully featured
  • Closed Source
  • Data is held on 3rd party server
  • Requires user login
  • Trust is required
• Isso https://posativ.org/isso/
  • Documentation is extensive
  • Open source: MIT
  • Requires a Linux server running Python and SQLite3
• Just Comments https://just-comments.com/
  • Defunct https://just-comments.com/blog/2020-03-06-just-comments-is-shutting-down.html
• Muut https://muut.com
  • Developer-friendly https://muut.io
  • Fully featured
  • No free tier
  • Trust is required
• Remark42 https://remark42.com/
  • Fully featured
  • Open source: MIT
  • Requires a server
    • Runs a self-contained executable written in Go
• Talkyard https://www.talkyard.io/
  • Open source: AGPL
  • Self-host OR paid hosting
  • Almost free tier (€1.90/mo + optional add-ons)
  • Discounts for non-profits and developing countries
• Valine https://valine.js.org/en/index.html
  • Open source: GPL
  • Serverless
  • Requires a leancloud account
  • Servers are in China
  • Data safety / privacy is unclear
• schnack! https://schnack.cool/
  • Open source: Lil License v1
  • Requires a server running Node and SQLite3

• More: a list of commenting systems that I have not evaluated
  • Cactus comments https://gitlab.com/cactus-comments
  • Commentator https://github.com/mcorbin/commentator
  • Comntr https://github.com/comntr
  • Coral Project https://github.com/coralproject/talk
  • Github comments http://donw.io/post/github-comments/
  • Glosa https://github.com/glosa
  • Hypercomments https://www.hypercomments.com/
  • Mastadon https://carlschwan.eu/2020/12/29/adding-comments-to-your-static-blog-with-mastodon/
  • Netlify forms https://bsdnerds.org/comments-static-site/
  • Remarkbox https://www.remarkbox.com/
  • ReplyBox https://getreplybox.com/
  • Social media https://brid.gy/
  • Staticman https://github.com/eduardoboucas/staticman
  • Webmention https://webmention.io/
    • more detail https://news.ycombinator.com/item?id=25571253
  • utterances https://github.com/utterance/utterances

simple-comment's Issues

"Topic 'https---simple-comment-netlify-app-' not found" error

https://simple-comment.netlify.app displays a "Topic 'https---simple-comment-netlify-app-' not found" error

Guest user cannot log in

Currently the guest user does not have access to the log in button, since it is hidden for all logged-in users, including guests.

Guest users should be able to log in.

Twitter card logo has black background

The png logo should have a transparent background with a drop-shadow or stroked outline. This will let it show up clearly no matter the background color.

https://simple-comment.netlify.app/img/twitter-card-logo.png

401 must return WWW-Authenticate header

./verify endpoint returns a 401 error without a WWW-Authenticate header

A server generating a 401 (Unauthorized) response MUST send a WWW-Authenticate header field containing at least one challenge.

per https://tools.ietf.org/html/rfc7235#section-4.1

Add "All comments" page

Create a page that will show all comments across the simple-comment instance.

For now, no pagination, but this will be necessary in future.

`ALLOW_ORIGIN` key in .env update

ALLOW_ORIGIN in .env is confusing and needs fixes.

1. Currently, policy.refererRestrictions set to false completely bypasses this check.
   • Enable wildcards in the ALLOW_ORIGIN value, so a value of https://o.net/blog/* would allow any page, e.g. ../blog/topic.html
   • Remove the policy flag entirely, and a simple * glob value would be effectively the same.
2. ALLOW_ORIGIN is not intuitive.
   • It can hold multiple origins as a value, maybe ALLOW_ORIGINS, plural?
   • ORIGIN is not immediately clear. Maybe URL? Or something more intuitive?
   • ALLOW_something implies a boolean. Perhaps ALLOWED...?

Update front page copy

Rambling. Let's make it easier to read and recommend.

Email notification

Right now if there is a comment by a user, the administrator does not receive a notification.

The administrator should receive a notification.

Guest user unable to submit comment

Two issues:

1. When guest user submits comment, the new validation rule applies to password. Guest user will never be able to submit a comment, because guest users do not have passwords
2. This fails silently with no notification

IS_CROSS_SITE=production?

README instruction For IS_CROSS_SITE add the value production is confusing, as IS_ implies boolean. This should be changed to values true or false or the name should change to CROSS_SITE_MODE

Client framework

Currently the frontend client is a series of document.append calls. Update the client with a modern framework.

UserId validation rejects *all* userIds

package.json does not exist error

https://simple-comment.netlify.app errors with the following:

{
  "errorType": "Error",
  "errorMessage": "package.json does not exist at /package.json",
  "trace": [
    "Error: package.json does not exist at /package.json",
    " at Object.t.find (/var/task/src/verify.js:3:443031)",
    " at Object. (/var/task/src/verify.js:135:333456)",
    " at Object. (/var/task/src/verify.js:135:336547)",
    " at r (/var/task/src/verify.js:1:158)",
    " at Object. (/var/task/src/verify.js:135:333068)",
    " at r (/var/task/src/verify.js:1:158)",
    " at Object. (/var/task/src/verify.js:135:78445)",
    " at r (/var/task/src/verify.js:1:158)",
    " at Object. (/var/task/src/verify.js:245:253032)",
    " at r (/var/task/src/verify.js:1:158)"
  ]
}

Expired JWT still validate / verify

Two issues, here:

1. The Cookie and the JWT expirations should correspond, but right now the Cookie expires in over 1000 years, and the JWT expires in 24 hours
2. When the JWT is expired, the /user endpoint fails with a "User not authenticated" error.

• The endpoint should issue a more detailed "User authentication expired" error message
• The frontend should redirect to login

Update project hierarchy

Currently each sub-project shares the same, project root directory for tsconfig and webpack. This creates conflicts.

For instance, vscode uses tsconfig.json to understand TypeScript highlighting, but Svelte and vanilla js and netlify.functions each use their own config file. This requires quite a bit of fiddling to get each to behave well during writing and building.

Break each project into its own sub directory, something roughly like:

├── svelte/
│   ├── tsconfig.json
│   ├── webpack.ts
│   ├── src/
│   ├──── main.ts
│   ├──── ...
├── shared/
│   ├── tsconfig.json
│   ├── webpack.ts
├── netlify.functions/
│   ├── tsconfig.json
│   ├── webpack.ts
├── project.json

Creating new topic for guest fails with "unknown referer" error

When a new page is created, Simple Comment is supposed to allow the first visitor to create a topic if it follows a specific format. However, it fails with "unknown referer".

This requires a work-around of the admin creating these topics by hand in the database.

Frontend testing with Cypress

Currently there are no frontend tests, so altering or creating new functionality is a crapshoot. Add cypress to the testing suite to drive TDD for frontend

Update code where promise executor functions are async

Currently the linter is no-async-promise-executor: "warn". Let's change that to "error" and update code where it happens.

`login.html` does not exist

README instructions Upload the login.html page on the root of your website (or somewhere accessible). login.html exists nowhere. Either include login.html or remove the instruction.

Guest users should (optionally?) be authenticated for some time longer than just one session

Currently the auth cookie has no expiration, which means that guest users authentication ends at the end of the session.