Add mongodb crud auth backend

Author: Hein

images/usage/tools/CloudCode-tasks.png

@@ -225,7 +225,8 @@
             "usage/tools/powersync-dashboard",
             "usage/tools/cli",
             "usage/tools/diagnostic-app",
-            "usage/tools/monitoring-and-alerting"
+            "usage/tools/monitoring-and-alerting",
+            "usage/tools/mongodb-crud-auth-backend"
           ]
         }
       ]

images/usage/tools/CloudCode.png

@@ -9,4 +9,5 @@ mode: wide
 <Card title="CLI (Beta)" icon="terminal" href="/usage/tools/cli" horizontal/>
 <Card title="Diagnostics App" icon="stethoscope" href="https://github.com/powersync-ja/powersync-js/tree/main/tools/diagnostics-app" horizontal/>
 <Card title="Monitoring and Alerting" icon="bell" href="/usage/tools/monitoring-and-alerting" horizontal/>
+<Card title="MongoDB CRUD Auth Backend" icon="database" href="/usage/tools/mongodb-crud-auth-backend" horizontal/>
 </CardGroup>

images/usage/tools/cloudcode-envvar.png

@@ -0,0 +1,151 @@
+---
+title: MongoDB CRUD Auth Backend
+description:
+---
+
+This project provides a serverless backend API for a client application using PowerSync.
+
+For more information about CloudCode serverless functions, please visit [this page](https://docs.journeyapps.com/reference/cloudcode/triggering-a-cloudcode-task/trigger-cc-via-http).
+
+To view the serverless functions, select the **CloudCode** option at the top of the IDE.
+
+<Frame>
+    <img src="/images/usage/tools/CloudCode.png" />
+</Frame>
+
+Here you will find four CloudCode tasks:
+<Frame>
+    <img src="/images/usage/tools/CloudCode-tasks.png" />
+</Frame>
+
+1. `generate_keys` - This is a task that can be used to generate a private/public key pair which the `jwks` and `token` tasks require.
+This task does not expose an HTTP endpoint and should only be used for development and getting started.
+2. `jwks` - This exposes an HTTP endpoint which has a `GET` function which returns the public JWKS details.
+3. `token` - This task exposes an HTTP endpoint which has a `GET` function. This tasks is used by a PowerSync client to generate a token to validate against the PowerSync Service.
+For more information about custom authentication setups for PowerSync, please see [this page](https://docs.powersync.com/installation/authentication-setup/custom) from the PowerSync docs.
+4. `upload` - This task exposes an HTTP endpoint which has a `POST` function which is used to process the write events from a PowerSync client and writes it back to the source MongoDB database.
+
+## Setup
+
+### 1. Generate key pair
+Before using the serverless functions you need to generate a public/private key pair. Do the following to generate the key pair:
+1. Open the `generate_keys` CloudCode task.
+2. Select the **Test CloudCode Task** button at the top right. This will print the public and private key in the task logs window.
+<Frame>
+    <img src="/images/usage/tools/test-cloudcode-task.png" />
+</Frame>
+3. Copy and paste the `POWERSYNC_PUBLIC_KEY` and `POWERSYNC_PRIVATE_KEY` to a file — we'll need this in the next step.
+
+<Note>
+    This step is only meant for testing and development because the keys are shown in the logs files.
+    For production, [generate a key pair locally](https://github.com/powersync-ja/powersync-jwks-example?tab=readme-ov-file#1-generate-a-key-pair) and move onto step 2 and 3.
+</Note>
+
+### 2. Configure a deployment
+Before using the tasks, we need to configure a deployment.
+1. At the top of the IDE, select the `Deployments` option.
+2. Create a new deployment by selecting the `+` icon at the top right, _or_ use the default `Testing` deployment. You can configure different deployments for different environments.
+3. Now select the `Deployment settings` button for the instance.
+4. In the `Deployment settings` - `General` tab, capture a `Domain` value in the text field. The application will validate the domain name to make sure it's available.
+5. Select `Save`.
+6. Deploy the deployment: you can do so by selecting the `Deploy app` button, which can be found on the far right for each of the deployments you have configured. After the deployment is completed, it will take a few minutes for the domain to be available.
+7. Your new domain will be available at `<domain_name>.poweredbyjourney.com`. Open the browser and navigate to the new domain. You should be presented with `Cannot GET /`, because there is no index route.
+
+### 3. Configure environment variables
+To add a new variable, do the following:
+1. Head over to the `Deployment settings` option again.
+2. Select the `Environment Variables` tab.
+<Frame>
+    <img src="/images/usage/tools/cloudcode-envvar.png" />
+</Frame>
+3. Capture the variable name in the `Name` text field.
+4. Capture the variable value in the `Value` text field.
+5. (Suggested) Check the `Masked` checkbox to obfuscate the variable value for security purposes.
+6. Repeat until all the variables are added.
+
+To finalize the setup, do the following:
+1. Select the `Save` button. This is important, otherwise the variables will not save.
+2. Deploy the deployment: you can do so by selecting the `Deploy app` button.
+
+To wrap up the deployment, we need to configure the environment variables. The following variables need to be set on the deployment:
+* `POWERSYNC_PUBLIC_KEY` - This is the `POWERSYNC_PUBLIC_KEY` from the values generated in step 1.
+* `POWERSYNC_PRIVATE_KEY` - This is the `POWERSYNC_PRIVATE_KEY` from the values generated in step 1.
+* `MONGO_URI` - This is the MongoDB URI e.g. `mongodb+srv://<username>:<password>@<database_domain>/<database>`
+* `POWERSYNC_URL` - This is the public PowerSync URL that is provided after creating a new PowerSync instance.
+
+### 4. Test
+Open your browser and navigate to `<domain_name>.poweredbyjourney.com/jwks`.
+You must set the JWKS url during to configure the PowerSync instance.
+If the setup was successful, the `jwks` task will render the keys in JSON format. Make sure the format of your JWKS keys matches the format [in this example](https://hlstmcktecziostiaplz.supabase.co/functions/v1/powersync-jwks) JWKS endpoint.
+
+## Usage
+Make sure you've configured a deployment and set up environment variables as described in the **Setup** steps before before using the API.
+
+### Token
+You would call the `token` HTTP API endpoint when you implement the `fetchCredentials()` function on the client application.
+Send a HTTP GET request to `<domain_name>.poweredbyjourney.com/token?user_id=<user_id>` to fetch a JWT for a user. You must provide a `user_id` in the query string of the request, as this is included in the JWT that is generated.
+
+The response of the request would look like this:
+```json
+{"token":"..."}
+```
+
+### JWKS
+The `jwks` HTTP API endpoint is used by PowerSync to validate the token returned from the `<domain_name>.poweredbyjourney.com/token` endpoint. This URL must be set in the configuration of your PowerSync instance.
+Send an HTTP GET request to `<domain_name>.poweredbyjourney.com/jwks`.
+
+An example of the format can be found using [this link](https://hlstmcktecziostiaplz.supabase.co/functions/v1/powersync-jwks).
+
+### Upload
+You would call the `upload` HTTP API endpoint when you implement the `uploadData()` function on the client application.
+Send an HTTP POST request to `<domain_name>.poweredbyjourney.com/upload`.
+The body of the payload should look like this:
+```
+{
+  "op": "PUT",
+  "table": "lists",
+  "id": "61d19021-0565-4686-acc4-3ea4f8c48839",
+  "data": {
+    "created_at": "2024-10-31 10:33:24",
+    "name": "Name",
+    "owner_id": "8ea4310a-b7c0-4dd7-ae54-51d6e1596b83"
+  }
+}
+```
+
+The API will respond with HTTP status `200` if the write was successful.
+
+## Modifying and making changes
+
+If you need to make changes to the way the `upload` task writes data to the source MongoDB database, do the following:
+
+1. Open the `CloudCode` section at the top of the IDE.
+2. Select and expand the `upload` task in the panel on the left.
+3. The `index.ts` contains the entry point function that accepts the HTTP request.
+4. The `persister.ts` file connects to the MongoDB database and writes the data to the MongoDB database. You can update this file to introduce your database schema, etc.
+
+Example MongoDB database schema setup:
+```typescript
+/**
+* Line 13 in upload/persister.ts
+* Sample schema using to-do list demo. Update this based on your DB schema.
+*/
+export const schema = {
+    lists: {
+        _id: types.string,
+        created_at: types.date,
+        name: types.string,
+        owner_id: types.string
+    },
+    todos: {
+        _id: types.string,
+        completed: types.boolean,
+        created_at: types.date,
+        created_by: types.string,
+        description: types.string,
+        list_id: types.string,
+        completed_at: types.date,
+        completed_by: types.string
+    }
+};
+```