jeremyckahn/chitchatter

Secure peer-to-peer chat that is serverless, decentralized, and ephemeral

Chitchatter

_{Logo provided by @ramyashreeshetty}

Chitchatter is a free (as in both price and freedom) communication tool. Designed to be the simplest way to connect with others privately and securely, it is:

• Fully open source (licensed under GPL v2)
• Peer-to-peer
  • Whenever possible, otherwise a TURN server is used to ensure reliable peer connection
• End-to-end encrypted (via WebRTC)
• Ephemeral
  • Message content is never persisted to disk on either the client or server
• Decentralized
  • There is no API server. All that's required for Chitchatter to function is availability of GitHub for static assets, and public WebTorrent and STUN/TURN relay servers for establishing peer-to-peer communication.
• Embeddable
• Self-hostable

Chitchatter uses Vite. The secure networking and streaming magic would not be possible without Trystero. File transfer functionality is powered by secure-file-transfer.

Status

• 

How to use it

Open https://chitchatter.im/ and join a room to start chatting with anyone else who is in the room. By default, room names are random UUIDs that are generated client-side. To privately communicate with someone, it is recommended to join one of these randomly-generated rooms and share the URL (via the "🔗" button at the top of the page) to whomever you wish to communicate with via a secure medium of your choosing (such as Burner Note or Yopass). Your user name will be presented to you, and it would be good to share that with who you will be chatting with beforehand so they know they're talking to you.

Features

• Multiple peers per room (limited only by the number of peer connections your browser supports).
• Public and private rooms.
• Video and audio chatting.
• Screen sharing.
• File sharing:
  • Unlimited file size transfers.
  • Files are encrypted prior to sending and decrypted by the receiver (the key is the room name).
• Embedding into other web apps via iframe.
• Markdown support via react-markdown.
  • Includes support for syntax highlighting of code.
• Conversation backfilling from peers when a new participant joins.
• Multiline message support (hold shift and press enter).
• Dark and light themes.
• Automatic peer verification via client-side public-key cryptography.

Anti-features

• Messages are never persisted to disk. When you leave a peer room, messages are cleared from memory and cannot be retrieved.
• Chitchatter is an entirely client-side communication app. It uses public WebTorrent servers to establish peer connections and STUN/TURN relay servers when direct peer-to-peer connections cannot be established, but there is no Chitchatter API server.
• No analytics, tracking, or telemetry of any kind.
• This is a community-driven and unfunded project that makes no money. The users come first and there is no corporate influence or financial interest involved.

Why another chat app?

There is no shortage of user-friendly chat apps available, but they rely on a central service to facilitate communication. It is difficult to trust these central services, as commercial interests and government pressure can compel service operators to work against the best interest of the users. Even when user data is handled in good faith by service operators, the possibility remains that encrypted data held at rest may be decrypted against the user's will.

Chitchatter designs around these risks with a web meshe architecture. There is no central service operator that stores or potentially mishandles communication data. Some services are required to establish an initial connection between peers, but otherwise the app uses direct peer-to-peer communication for everything. Any services that are used by Chitchatter have no association with the project and are publicly available for all to use.

Use cases

Chitchatter offers a private and secure solution for:

• Organizing groups of people, such as unions or political movements
• Conveniently moving text or data from one device to another
• Video chatting with friends and family across operating systems (such as Android and iOS)
• IT troubleshooting via screen sharing
• Livestreaming
• Sharing sensitive information such as passwords
• Much more!

---

Note from the developer

💻️ Project status

I consider Chitchatter feature-complete inasmuch it does all the things I personally need it to do. I don't have specific plans to add significant functionality in the future, but I may do so if it seems fun to me at the time. I am committed to fixing any significant bugs that are reported, so please open an issue if you discover one! Aside from that, Chitchatter is effectively in maintenance mode for the foreseeable future.

If you would like a feature to be implemented and are willing to pay a development cost to ensure it gets done, please file a GitHub issue describing the feature and indicate that you are willing to compensate for the work. If you are not willing to pay, please open a GitHub issue regardless. I may implement it if it seems fun to do so, but other members of the community may also step up to implement it via Pull Requests.

I will always make time support Pull Requests from others. If you're willing to put in the work to improve Chitchatter, I am willing to help shepherd that work along and get it shipped.

If you don't agree with the direction of the project, you are welcome to fork Chitchatter and take it in another one.

🏗️ Support and custom development

I'm willing to do paid installations and customizations of Chitchatter for your needs. If you'd like to contract me to make a version of Chitchatter that is custom built for you, please email me at [email protected] and let me know what you have in mind to get started.

---

Veracity

The core of Chitchatter's security model is the fact that it is fully open source. You are free (and encouraged) to fully audit the project source code and infrastructure. Not only is the source code available under the terms of the GPL, but all build logs are publicly accessible as well.

If you would like to verify that the app hosted at https://chitchatter.im/ is the one that is hosted on GitHub, you can use dig:

$ dig chitchatter.im

; <<>> DiG 9.18.1-1ubuntu1.1-Ubuntu <<>> chitchatter.im
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 61332
;; flags: qr rd ra; QUERY: 1, ANSWER: 5, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;chitchatter.im.                        IN      A

;; ANSWER SECTION:
chitchatter.im.         231     IN      CNAME   jeremyckahn.github.io.
jeremyckahn.github.io.  231     IN      A       185.199.111.153
jeremyckahn.github.io.  231     IN      A       185.199.110.153
jeremyckahn.github.io.  231     IN      A       185.199.109.153
jeremyckahn.github.io.  231     IN      A       185.199.108.153

To examine the static assets that are served to end users, you can audit the gh-pages branch.

Project roadmap

See the full ticket backlog here.

Environments

• Production environment: https://chitchatter.im/
  • Mirror: https://chitchatter.vercel.app/ (note that peers cannot connect across domains)
• Staging: https://chitchatter-git-develop-jeremyckahn.vercel.app/

SDK

You can use the official Chitchatter SDK to embed the app as a Web Component called <chat-room />.

<script src="https://chitchatter.im/sdk.js"></script>

<chat-room />

The <chat-room /> component supports the following optional attributes:

• room: The name of the Chitchatter room the user should join. The default value is the URL of the embedding page.
• user-name: The friendly name of the user (which they can change).
• user-id: The static ID of the user. The default value is a random UUID.
• root-url: The URL of the Chitchatter instance to use. The default value is https://chitchatter.im/.
• color-mode: light or dark. The default value is dark.
• play-message-sound: Whether or not to play a sound when a user receives a message while the window is not in focus. The default value is false.

As well as the following standard <iframe /> attributes:

• height
• width
• style
• referrerpolicy
• sandbox

Developing Chitchatter

Important

Presently Chitchatter can only be developed on *NIX systems such as Linux and macOS. If you are using Windows, you can use WSL to set up a Linux environment.

To make changes to Chitchatter, clone the source code from GitHub. Ensure you have Node and NPM installed. Then in the project directory, run:

npm install

This will install all of the dependencies.

Available Scripts

In the project directory, you can run:

npm dev

Runs the entire stack (client + WebTorrent tracker) locally.

npm start

Runs the front end app in the development mode. Uses public WebTorrent trackers. Open http://localhost:3000 to view it in your browser.

The page will reload when you make changes. You may also see any lint errors in the console.

npm test

Launches the test runner in the interactive watch mode.

npm run build

Builds the app for production to the dist folder. It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.

Self-hosting

Chitchatter is designed to be forked and self-hosted. If you would like to change pairing or relay server configuration, or you simply prefer to control your own builds and versions, just fork this repo and follow the steps below.

Caveats

Chitchatter peer connections are bound to the instance's domain. So, a user of Chitchatter at https://chitchatter.im/ would not be able to connect to a user of a Chitchatter instance on another domain (such as a personal GitHub Pages-hosted fork).

Necessary steps after forking

Assuming you are hosting Chitchatter on GitHub Pages:

1. Change the homepage property in package.json to whatever URL your Chitchatter instance will be hosted from. This will be something like https://github_user_or_org_name.github.io/chitchatter/.
2. Define a DEPLOY_KEY GitHub Action secret (at https://github.com/github_user_or_org_name/chitchatter/settings/secrets/actions). See the docs for peaceiris/actions-gh-pages for more information.
3. If you're using GitHub Pages without a custom domain, you'll need to define the repo name as the base property in vite.config.ts. Here's an example of how that might look:

const config = () => {
   return defineConfig({
      base: '/chitchatter/',
      build: {
       ...
}

Deployment

On GitHub

When hosted on GitHub Pages and the configuration above has been done, the Production environment is updated when the remote main branch is updated (once GitHub Actions are enabled).

On non-GitHub hosts

Build the app with npm pkg set homepage="https://your-domain-here.com" && npm run build (with https://your-domain-here.com substituted for the root URL that Chitchatter will be served from), and then serve the dist directory. Any static file serving solution should work provided it is using a secure context.

Runtime configuration

Explore the files in src/config to modify pairing and relay server configuration.

Troubleshooting

If you run into any issues with a custom Chitchatter installation, first ensure that you are using the latest version of the code. If you are hosting your installation with GitHub Pages, sync your main branch and not your gh-pages branch. Updating your main branch will trigger a proper rebuild of your gh-pages branch.

• https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Peers won't connect

This could happen for a variety of reasons. The most likely of which is that one or more peers cannot connect directly and must use the configured STUN/TURN relay as a fallback. The standard relay is free and does not guarantee any level of service, so it may simply be unavailable for some time (or just not work at all for some users). There's not much to do other than wait until it becomes available again, or possibly try from another device or location.

Issues specific to browsers with ad blocking extensions

Some ad blockers (such as uBlock Origin) prevent connections to certain WebTorrent servers. This prevents Chitchatter peers from connecting. To work around this, you can either disable your ad blocker or self-host your own Chitchatter instance.

Issues specific to iOS Safari

Chitchatter works on iOS Safari, but browser-level bugs often prevent peers from rejoining the room when the browser is closed and later reopened (for instance, when switching applications). The suggested workaround for this issue is to refresh the page to rejoin the room.

Issues specific to Firefox

Per #36, check your about:config settings and ensure that media.peerconnection.enabled is enabled.

Security

Chitchatter undergoes weekly security audits to identify and address potential vulnerabilities. Reports from all audits can be found in Issues.

Contributors

⚠️ Disclaimer

By using Chitchatter, you agree to accept full responsibility for your actions related to its use. Additionally, you agree not to hold any contributors to the Chitchatter project responsible for any result of your use of it. The developers of Chitchatter do not endorse illegal activity.

chitchatter's Issues

Display peer list

The usernames for all of the currently-connected peers should be displayed as a list.

Private Rooms not working on Firefox on Android (but work on Brave mobile browser)

I have tried multiple times with the same result. I cannot see the other user when I join a private room from Firefox on Android. When trying the Brave mobile browser on the same Android phone (Samsung S21), it works.

Public rooms do work on Firefox mobile.

Embeddable Chitchatter

Chitchatter should be embeddable within another app.

QR code support

Users should be able to request a QR code to be presented that links to the current room.

Message grouping

A series of messages from one peer should appear grouped under the author's user name header, rather than one user name header per each message.

File sharing

Users should be able to send files to peers.

Message recalling

Users should have the ability to request sent messages to be deleted on all peers devices (provided that there is still an active peer connection).

Nextjs implementation

Great work so far!

I'm trying to migrate this from CRA to nextjs, any clue if this is possible at all? Currently it's showing "Error: Trystero: already joined room".

Disable WebRTC relays

Allow the user to disable TURN server relays.

Notes

• It should be communicated to the user that this may prevent peers from being connected.

Limit transcript size

To ensure stability and performance, message transcript size should be limited.

[Community Room Request]: Template test

Room URL

https://chitchatter.im/public/template-test

Room Subject

Just testing

Linux and Windows native apps

Linux and Windows native apps should be produced when Chitchatter is deployed.

This can be achieved with electron-builder. Here's an example of how this can be achieved:

• https://github.com/jeremyckahn/farmhand/blob/fefa45a03c22c6dac04c3ff85f72cb1f18fbed4f/.github/workflows/run-release.yml#L114-L133
• https://github.com/jeremyckahn/farmhand/blob/fefa45a03c22c6dac04c3ff85f72cb1f18fbed4f/package.json#L135-L177

Note: MacOS builds are out of scope and not likely to be supported. This is because it will cost money to enable app auto-updating for that platform:

Code signing is required on macOS

macOS application must be signed in order for auto updating to work.

Message sound effects don't work on Android or iOS

Message sounds effects (#7) don't appear to be working on Android or iOS.

Private rooms

Users should be able to create private rooms that require a password to access.

Acceptance Criteria

Room Creator flow

• There is a new toggle on the home page to select between "Public" and "Private" (see mock below). "Public" is selected by default.
• When the user (Room Creator) flips the toggle to "Private", a "Password" entry field appears below the "Room name" field.
• When the Room Creator flips the toggle back to "Public," the "Password entry field disappears.
• The "Password" field is shown in plain text and is prefilled with a random UUID.
• If the "Password" field is emptied out, the "Go to chat room" button is disabled until some content is entered again.
• When there is both a room name and password provided and the Room Creator clicks the "Go to chat room" button, they are redirected to a chat room via a new /private/:roomId route (example: https://chitchatter.im/private/666e3a53-cdf9-4add-b8be-cd9853ba8885)

Room Participant flow

• When a user who is not the Room Creator (Room Participant) navigates to a /private/:roomId route, they are presented with a Form Dialog that prompts the Room Participant to enter the room password.
• When the Room Participant submits a password, the Form Dialog is dismissed.
• If the password matches what the Room Creator specified, the Room Participant is connected to the room.
• If the password does not match what the Room Creator specified, the Room Participant is not connected to room participants.
  • It is acceptable for Room Participants who provided an incorrect password to be connected to a room, they just cannot be connected to other peers who entered the correct password.

Technical notes

Trystero's encryption functionality should be used to password-protect peer rooms.

Limit the size of messages

Chat messages should be limited to 10,000 characters.

Request: Emoji reactions to chat messages

Image sharing

Users should be able to upload image files to each other.

[Community Room Request]:

Room URL

https://chitchatter.im/public/chitchatter-dev

Room Subject

Meta community room for chitchatter users to discuss chitchatter development.

OTP feature for room links

Chitchatter needs an integrated OTP feature for securely sharing room links with peers. Something like https://burnernote.com/, but entirely client-side and built directly into Chitchatter.

Acceptance Criteria

Sharer experience

• There is a new menu item called "Secure Invite"
• When the user (Sharer) clicks "Secure Invite," they are redirected to a new route called /otp
• The /otp route presents the user with a form that accepts a room name
• When Sharer submits the form, the form is replaced with:
  • A Chitchatter Secure Link that can be shared with someone (a Sharee)
    • The Secure Link should direct users to a new /otp/:otpId route (example: https://chitchatter.im/otp/3b5ac1ff-e1c0-4797-9988-21a3e70302f2)
  • A message informing Sharer that they must keep their tab open until Sharee has accessed the Secure Link
  • When Sharee successfully accepts the invite and accesses the chat room, Sharer is automatically redirected to the chat room as well

Sharee experience

• When a user (Sharee) navigates to the /otp/:otpId Secure Link as provided by Sharer (see above), they are presented with a button to accept the invite
• When Sharee accepts the invite, they are redirected to the room that the Sharer specified

Notes

This is just the first iteration of this feature. In the future, we should add the following enhancements:

• Password-protected OTP links
• Capability to share Secure Links with more than one person

Screen sharing

Users should be able to share their screen with a room.

[Request]: Allow YouTube links to preview in chat

I believe this would make a cool addition to the software! So you know what the video is before you click!

Set up preview deployment environments

Use something like Vercel to set up preview deployment URLs for testing.

Is there a way to set my username?

File sharing is broken on Android

file sharing doesn't seem to work from/to my android device. I tested it on 4 different browsers (Chrome, Brave, Duckduckgo, Firefox).

Originally posted by @butera-simone in #72 (comment)

Support ad-hoc networks

Per u/Bassfaceapollo on Reddit:

I hope you consider adding support for messaging over ad-hoc networks at some point.

This might give you some direction -

• https://berty.tech/blog/bluetooth-low-energy
• https://en.m.wikipedia.org/wiki/Multicast_DNS
• https://en.m.wikipedia.org/wiki/Bluetooth_Low_Energy

Request: Include commit hash on main page so you know what version you are using

I think this would be really cool!

Video calling

Users should able to make video calls to peers.

Ability to adjust volume of other users

Please!!!

Having problem on firefox browser

Discussed in #35

^{Originally posted by MohammadTaseenKhan October 9, 2022}

Recently I am facing a new problems like when i use Firefox browser i cant send any message, even cant receive any message even no notification coming to me

Sending Message:

Receiving message:

It doesn't even showing how many numbers of peers are connected

same as well this also

https://chitchatter.im/public/85ccdfc7-b992-411d-9d98-0a5c2781138e

Voice calling

Users should be able to make voice calls to peers.

Show notifications for new messages

When a user receives a message and the Chitchatter room is not in focus, present an operating system-level notification to inform the user that there is a new message. This functionality should be off by default, but able to be enabled via a persisted user setting.

Height of room window too high

When in safari on an iPhone 11, the content when I'm in a room does not fit the screen. I can either scroll down to the input field it up to the first message. I cant see both at the same time

Active typing indicators

It should be indicated to peers when any other peer is actively typing.

Easier sharing of private rooms

Should be able to send a private room URL which includes the password, such that one doesn't need to type in the room password. This is already an established pattern with zoom calls.

This can be contained purely in the local javascript layer by putting the password in the part of the URL after the hash #, since anything after hash is not sent to the server in the HTTP request.

If there's a concern about the URL being too readable, potentially a hash of the password is in the URL, rather than the password itself, and manually entered passwords are internally hashed to the same value before being passed to Trystero api call.

Design logo

Currently Chitchatter uses the default Create React App logo: https://github.com/jeremyckahn/chitchatter/blob/develop/public/logo512.png

The project needs something more distinctive and unique.

Empty room id in URL displays empty page

If you remove the room ID, such as https://chitchatter.im/private/, or https://chitchatter.im/public/, the page displays nothing

Request: Some sort of file upload progress

This would be especially good for larger files being sent over a chat room. Possibly a percentage and/or data progress counter when you hover over the icon.

Play a sound for new messages

When a user receives a message and the Chitchatter room is not in focus, play a sound to inform the user that there is a new message. This functionality should be off by default, but able to be enabled via a persisted user setting.

Indicate when relay is being used

Indicate when peer communication is being done over a TURN server relay.

Technical notes

• This StackOverflow post suggests how relayed communication might be detected: https://stackoverflow.com/questions/53133745/how-to-check-if-webrtc-peers-communicated-in-p2p-mode-or-relay-mode/53138581#53138581

Display messge timestamps

Each message should present its timestamp to the user.

Indicate Markdown support

It should be clearly indicated to the user that they can use Markdown in their messages.

Add disclaimer

Implement a "disclaimer" page with content adapted from what @MohammadTaseenKhan provided in #39.

Transcript backfilling

Peers who join a room after there has already been text chatting should be shown the transcript of conversation that has already taken place (based on what's stored in memory on other peers' devices).

Combine audio/video streams

Currently, audio and video streams are handled separately. This comes at a possible performance cost and blocks #77. The streams should be combined so that audio is outputted via <video /> elements that provide audio UI controls.

Settings UI

Users should have a Settings UI from which they can set their application preferences and delete their persisted Settings data.

[Community Room Request]:

Room URL

https://chitchatter.im/public/chitchatter

Room Subject

Meta community room for chitchatter users.

Inform users when an update is available

As an installed Progressive Web Application, available updates get automatically installed in the background after the page is loaded. When an updated version of the app is available, notify the user.

Encrypted file transfers

Chitchatter should end-to-end encrypt file transfers for greater security.

Message editing

Users should be able to edit their messages after they've been sent.

Android native app

Adding Android .apk support is a distinct effort from Windows/Linux, so I'll break that out into a new issue.

Originally posted by @jeremyckahn in #44 (comment)

Generate and provide installable Android .apk files as part of the build process.