This backend service can be used to filter the replication between a PouchDB and a CouchDB instance based on permission rules. It does this by overriding some of CouchDB`s endpoints where permissions are checked on the transmitted entities. The permission rules are defined through CASL.
This API functions as a proxy layer between a client (PouchDB) and a standard CouchDB instance. The backend can either be run as a docker container
> docker run aamdigital/replication-ms:latest
or directly through npm (see below: --> "Development")
> npm install && npm start
In both cases the following environment variables should be defined:
DATABASE_URL
the URL where the CouchDB instance can be accessedDATABASE_USER
the name of a user that is amember
of all databases inside the CouchDB instance. In case the proxy is also used to create new entries in the_users
database, then this user needs to beadmin
in this database.DATABASE_PASSWORD
the password for theDATABASE_USER
PERMISSION_DB
the database name where the permissions definition document is storedJWT_SECRET
a secret to create JWT tokens. They are used in the JWT auth which works similar to CouchDB'sPOST /_session
endpoint. This should be changed to prevent others to create fake JWT tokens.JWT_PUBLIC_KEY
the public key which can be used to validate a JWT in the authorization header (bearer). The structure is the same as and compatible with CouchDB JWT auth.SENTRY_DSN
(optional) the Sentry DSN. If defined, error messages are sent to the sentry.io application monitoring & logging service.
In case the backend is run through Docker, the args can be provided like this
> docker run -e DATABASE_URL=https://test.com/couchdb -e DATABASE_USER=replicator -e DATABASE_PASSWORD=securePassword -e JWT_SECRET=myJWTSecret -e JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nSomePublicKey\n-----END PUBLIC KEY-----" aamdigital/replication-ms:latest
In case the backend is run through npm, the .env
file can be adjusted.
See our Developer Documentation
Besides the CouchDB endpoints, the backend also provides some additional endpoints that are necessary to be used at times.
A swagger / OpenAPI interface can be visited at /api/
which shows all endpoints that are available.
/admin/clear_local/{db}
needs to be executed whenever a rule or a permission change might give a user more permission than the user previously had. This will restart the synchronization process for each client which makes them fetch all the documents for which they now have gained permissions.- The endpoints of the real CouchDB are available through a reverse proxy at
/couchdb/
. This can be used to visit the developer interface at/couchdb/_utils/
.
Additionally, a separate check on the client side is necessary that cleans up the local database whenever a client looses read permissions for a document. A example for how this could look can be found here.
This system is Node.js application built with the NestJS framework.
To run and test this project locally:
npm install
to download and set up all dependenciesnpm start
to run the application locally (see above for required environment variables)npm test
to execute unit tests
Use the dockerized local environment to run a fully synced app including backend services on your machine: https://github.com/Aam-Digital/aam-services/tree/main/docs/developer