220 lines
11 KiB
Markdown
220 lines
11 KiB
Markdown
# RemnantChat
|
|
|
|
|
|
|
|
RemnantChat is a free (as in both price and freedom) communication tool. It is forked from the platform ChitChatter [see the upstream project](https://github.com/jeremyckahn/chitchatter/blob/develop/README.md). Designed to be the simplest way to connect with others privately and securely, it is:
|
|
|
|
- Fully open source (licensed under [GPL v2](./LICENSE))
|
|
- Peer-to-peer
|
|
- Whenever possible, otherwise a TURN server is used to ensure reliable peer connection
|
|
- End-to-end encrypted (via [WebRTC](https://webrtc-security.github.io/))
|
|
- 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 RemnantChat 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](#self-hosting)
|
|
|
|
RemnantChat uses the [Create React App](https://github.com/facebook/create-react-app) toolchain. The secure networking and streaming magic would not be possible without [Trystero](https://github.com/dmotz/trystero). File transfer functionality is powered by [`secure-file-transfer`](https://github.com/jeremyckahn/secure-file-transfer).
|
|
|
|
## Status
|
|
|
|
TBA
|
|
|
|
## How to use it
|
|
|
|
Open https://remnant.chat/ and join a room to start chatting with anyone else who is in the room. By default, room names are random [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s 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](https://burnernote.com/) or [Yopass](https://yopass.se/)). 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`](https://github.com/remarkjs/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](https://en.wikipedia.org/wiki/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.
|
|
- RemnantChat 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 RemnantChat API server.
|
|
- No analytics, tracking, or telemetry of any kind.
|
|
- This is a Christian community-driven project.
|
|
|
|
## 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. 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.
|
|
|
|
RemnantChat designs around these risks with a web mesh 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 RemnantChat have no association with the project and are publicly available for all to use.
|
|
|
|
## Use cases
|
|
|
|
RemnantChat offers a private and secure solution for:
|
|
|
|
- Churches
|
|
- 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
|
|
|
|
Please [open an issue](https://githaven.org/shiloh/RemnantChat/issues/new) if you discover a bug.
|
|
|
|
If you would like a feature to be implemented please file a GitHaven issue describing the feature. If you are not able to work on it yourself other members of the community may step up to implement it via Pull Requests.
|
|
|
|
We will always make time to support Pull Requests from others. If you're willing to put in the work to improve RemnantChat, we are 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 RemnantChat and take it in another one.
|
|
|
|
## Veracity
|
|
|
|
The core of RemnantChat'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.
|
|
|
|
If you would like to verify that the app hosted at https://remnant.chat/ is the one that is hosted on GitHaven, you can use `dig`:
|
|
|
|
```
|
|
$ dig RemnantChat.im
|
|
|
|
; <<>> DiG 9.18.1-1ubuntu1.1-Ubuntu <<>> RemnantChat.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:
|
|
;RemnantChat.im. IN A
|
|
|
|
;; ANSWER SECTION:
|
|
RemnantChat.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
|
|
```
|
|
|
|
## Project roadmap
|
|
|
|
TBA
|
|
|
|
## Environments
|
|
|
|
- Production environment: https://remnant.chat
|
|
- Staging:
|
|
|
|
## SDK
|
|
|
|
You can use the official RemnantChat SDK to embed the app as a [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) called `<chat-room />`.
|
|
|
|
```html
|
|
<script src="https://remnant.chat/sdk.js"></script>
|
|
|
|
<chat-room />
|
|
```
|
|
|
|
The `<chat-room />` component supports the following optional attributes:
|
|
|
|
- `room`: The name of the RemnantChat 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 RemnantChat instance to use. The default value is `https://RemnantChat.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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attributes):
|
|
|
|
- `height`
|
|
- `width`
|
|
- `style`
|
|
- `referrerpolicy`
|
|
- `sandbox`
|
|
|
|
## Available Scripts
|
|
|
|
Note: make sure to run 'npm install' after cloning the repo.
|
|
|
|
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](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. See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
|
|
|
|
### `npm run build`
|
|
|
|
Builds the app for production to the `build` 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
|
|
|
|
RemnantChat 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](https://githaven.org/repo/fork/57) and follow the steps below.
|
|
|
|
#### Caveats
|
|
|
|
RemnantChat peer connections are bound to the instance's domain. So, a user of RemnantChat at https://remnant.chat/ would not be able to connect to a user of a RemnantChat instance on another domain.
|
|
|
|
#### Deployment After Forking
|
|
|
|
##### On non-GitHub hosts
|
|
|
|
Build the app with `PUBLIC_URL="https://your-domain-here.com" npm run build`, and then serve the `build` directory. Any static file serving solution should work provided it is using a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
|
|
|
|
#### 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 RemnantChat installation, first ensure that you are using [the latest version of the code](https://githaven.org/shiloh/RemnantChat/tree/main).
|
|
|
|
#### 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 RemnantChat peers from connecting. To work around this, you can either disable your ad blocker or [self-host your own RemnantChat instance](#self-hosting).
|
|
|
|
##### Issues specific to iOS Safari
|
|
|
|
RemnantChat 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
|
|
|
|
check your `about:config` settings and ensure that `media.peerconnection.enabled` is **enabled**.
|
|
|
|
##### Security
|
|
|
|
### Contributors
|
|
|
|
## ⚠️ [Disclaimer](https://remnant.chat/disclaimer)
|
|
|
|
By using RemnantChat, you agree to accept **full responsibility** for your actions related to its use. Additionally, you agree **not** to hold any contributors to the RemnantChat project responsible for any result of your use of it. The developers of RemnantChat do not endorse illegal activity.
|