From 7982b68b83f8d397aa463d619f143ca96c61d5e8 Mon Sep 17 00:00:00 2001 From: Christopher Astfalk Date: Fri, 18 Sep 2020 22:44:03 +0200 Subject: [PATCH] docs(pouchdb-server): update documentation --- docs/general.md | 4 ++-- docs/index.md | 10 +++++----- docs/network.md | 6 ++++-- docs/synchronizing.md | 41 +++++++++++++++++++++++++++++++++-------- server/README.md | 4 ++-- 5 files changed, 46 insertions(+), 19 deletions(-) diff --git a/docs/general.md b/docs/general.md index b1943b0..ada4007 100644 --- a/docs/general.md +++ b/docs/general.md @@ -23,9 +23,9 @@ The server then adds its own MAC-address and translates the JSON-data to the [XM The server translates the XML-RPC response to JSON and send and sends it back to the client as the response of its request. -The client will the open a WebSocket back to the server. The server acts as a WebSocket to UDP bridge. For every WebSocket-connection the server listen on a new UDP-Port, to differentiate clients. A lot of Packet types have no way of identifying the target client. Having a port per client fixes this. +The client will then open a WebSocket back to the server. The server acts as a WebSocket to UDP bridge. For every WebSocket-connection the server listen on a new UDP-Port, to differentiate clients. A lot of Packet types have no way off identifying the target client. Having a port per client fixes this. **The server keeps no log of the network-data** ## Client View -The client uses the [FLUX](http://facebook.github.io/flux/) model. Where [redux](https://redux.js.org/) manages the state and the view-components are using [React](https://facebook.github.io/react/). And they styled with [styled-components](https://www.styled-components.com/). +The client uses the [FLUX](http://facebook.github.io/flux/) model. Where [redux](https://redux.js.org/) manages the state and the view-components are using [React](https://facebook.github.io/react/). And they styled with [Tailwind CSS](https://tailwindcss.com/). diff --git a/docs/index.md b/docs/index.md index ac666b5..b708f55 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,9 @@ You can view the development documentation here. - [Network documentation](./network.html) documents the protocol between client and server! -- For the data layout in hoodie visit the [synchronizing documentation](./synchronizing.html)! +- For the data layout visit the [synchronizing documentation](./synchronizing.html)! + +Most directories also have their own **Readme**. They document what that directory is for, and more. ## How to get started @@ -25,7 +27,7 @@ If you would like to use the viewer or help developing it, you need to run it yo What you need is: - A [Git](https://git-scm.com/) client. [How to set it up](https://help.github.com/articles/set-up-git/). -- [node.js](https://nodejs.org/) version 8.9.0 or higher. +- [node.js](https://nodejs.org/) version 12 or higher. - [npm](https://npmjs.org/) (Included in node.js). - And a modern web-browser. @@ -42,6 +44,4 @@ With `npm start` you start a server, which will run the backend of this viewer. When the server runs, you can access the viewer in your browser under http://127.0.0.1:8000/. -There is also a live reload mode! Run `npm run watch` and whenever you save a changed file, the viewer/client updates. Without reloading the viewer-state! - -`npm run startDev` is a combination of the last two commands. +There is also a live reload mode! Run `npm run dev` and whenever you save a changed file, the viewer/client updates. Without reloading the viewer-state! diff --git a/docs/network.md b/docs/network.md index 355acf3..1357965 100644 --- a/docs/network.md +++ b/docs/network.md @@ -101,11 +101,13 @@ circuit.send('TestMessage', { ## LLSD -More and more UDP packages get obsoleted in favor of HTTP(S) based messages. They get encoded using LindenLabs [LLSD](http://wiki.secondlife.com/wiki/LLSD) format. `src/llsd.js` is a complete Javascript implementation from LindenLab. It supports all encodings: XML, Binary and JSON. The XML encoding is the default one. +More and more UDP packages get obsoleted in favour of HTTP(S) based messages. They get encoded using LindenLabs [LLSD](http://wiki.secondlife.com/wiki/LLSD) format. `src/llsd.js` is a complete Javascript implementation from LindenLab. It supports all encodings: XML, Binary and JSON. The XML encoding is the default one. The http endpoints get revered as capabilities. Their URL change for every session and sometimes also when changing the SIM. The login result will contain the `SeedCapabilities`. it will result a list of all capability-urls. -A LLSD-List with all capabilities-names gets pushed to the SeedCapabilities. Resulting to a LLSD-Dictionary ({ cap-name: URL }). +A LLSD-List with all capabilities-names gets pushed to the SeedCapabilities. +The names are in **src/actions/capabilities.json**. +The server returns then a LLSD-Dictionary ({ cap-name: URL }). ### EventQueueGet diff --git a/docs/synchronizing.md b/docs/synchronizing.md index 242eb2e..1c3f9c2 100644 --- a/docs/synchronizing.md +++ b/docs/synchronizing.md @@ -1,30 +1,55 @@ -# Synchronizing +# Synchronising ## General -Andromeda is a [Hoodie](https://hood.ie) ([GitHub](https://github.com/hoodiehq)) web-app. Hoodie handles the server, accounts, and synchronizing of user data. +Andromeda is an [Express](https://expressjs.com/), [CouchDB](https://couchdb.apache.org/) & [PouchDB](https://pouchdb.com/) web-app. + +PouchDB handles the storing and synchronising of user data. +Server side CouchDB handles accounts, syncing sessions, and storing user data. +While Express gets used for account creation, updating and more. ## Account -An account of the viewer is a hoodie-account. Hoodies account module handles sign up, sign in and sign out. Look at its [readme.md](https://github.com/hoodiehq/hoodie-account-client/blob/master/README.md) and [documentation](http://docs.hood.ie/en/latest/api/client/hoodie.account.html) of it. -An account name is always an email-address. +An account of the viewer is a [CouchDB-account](https://docs.couchdb.org/en/stable/intro/security.html). To create, update, delete and password reset, the methods in __account.js__ must get used. + +An account name is always an UUID. The login-name is an email-address. +The email get stored in an `email` field. + +To get the UUID/name a GET request gets made to `/api/session/account` with a basic login. The result contains the account infos. With them the client can login to CouchDB. + +The account data will get stored in `_local/account`. +It is a [local doc](https://docs.couchdb.org/en/stable/api/local.html) that isn't synchronised. + +## Password + +The users password gets hashed on the client. First with `PBKDF2` and then with `HKDF`. +Using them the password gets hashed into 64 byte. The first 32 bytes are the server password, +while the last 32 bytes are the encryption password. + +__The encryption password and users password will never leave the client!__ ## Store -All synchronizing data, must get stored in hoodies user store. [hoodie-plugin-store-crypto](https://github.com/Terreii/hoodie-plugin-store-crypto) must get used for it! It builds on top of [hoodie-store-client](https://github.com/hoodiehq/hoodie-store-client/). -[Hoodies store](https://github.com/hoodiehq/hoodie-store-client/) ([documentation](http://docs.hood.ie/en/latest/api/client/hoodie.store.html)) is a NoSQL database based on PouchDB and CouchDB. Documents (doc) are the data unit of CouchDB. A doc is a JSON-Object. No Array as base! Every doc has an ID-string (`_id` key) that is unique for a database. It is the way to find a doc. +All synchronising data, must get stored in a local PouchDB database. +[hoodie-plugin-store-crypto](https://github.com/Terreii/hoodie-plugin-store-crypto) must get used to encrypt the users data! + +PouchDB and CouchDB are NoSQL databases. Documents (doc) are the data unit of CouchDB. +A doc is a JSON-Object. No Array as base! + +Every doc has an ID-string (`_id` key) that is unique for a database. It is the primary way to find a doc. + Every user has their own database. ## Encryption Andromeda uses [hoodie-plugin-store-crypto](https://github.com/Terreii/hoodie-plugin-store-crypto) to encrypt and decrypt user data. It uses `pbkdf2` with `sha256` to generate a key and `AES-GCM` for data encryption. -The salt gets synced, but the encryption password and key are not synchronized! +The salt gets synced, but the encryption password and key are not synchronised! Because the `_id` can't get encrypted, most data uses some random generated UUIDs in their names. ## Store Layout -Docs get organized using prefixes on their IDs, separated with `/`. View it as folders with JSON-files in it. +Docs get organised using prefixes on their IDs, separated with `/`. View it as folders with JSON-files in it. Data from an avatar (chats) have `dataSaveId` as prefix. This is a random generated UUID unique to that avatar! - [`avatars/`](#avatars) - [`grids/`](#grids) diff --git a/server/README.md b/server/README.md index 491270d..0827a95 100644 --- a/server/README.md +++ b/server/README.md @@ -26,7 +26,7 @@ File | Description ## Development -In normal development (`npm run dev`), the server-components are loaded into the create-react-app-dev-server ([src/setupProxy.js](../src/setupProxy.js)). +`npm run dev` loads the server-components into the create-react-app-dev-server. Read more in [src/setupProxy.js](../src/setupProxy.js). When developing the server, run `npm run dev-server`. It is a variant of `npm run dev`, that proxies API-requests to a separate running server. Then also run the *server* in development with `npm run start-server-dev`. @@ -35,7 +35,7 @@ Then also run the *server* in development with `npm run start-server-dev`. PouchDB-Server is accessible under [http://127.0.0.1:5984/_utils](http://127.0.0.1:5984/_utils). -If you want to use CouchDB, then all scripts must be run separately: +If you want to use CouchDB, then all scripts must get run separately: - `npm run dev:app` for building the client. - If you need a separate server, then `cross-env SERVER=debug npm run dev:app`. - `npm run dev:style` for building TailwindCSS.