chore: update docs

Author: damlayildiz

docs/postgresql/SELF_HOSTING_POSTGRES_FLYIO.md

@@ -5,7 +5,9 @@ This guide deploys a standalone PostgreSQL instance with CloudSync on Fly.io, pl
 By the end you will have:
 
 - A Fly.io VM running PostgreSQL with the CloudSync CRDT extension
-- A simple JWT auth server (Node.js) that issues tokens using a shared secret
+- A JWT auth server (Node.js) — choose between:
+  - **HS256 (shared secret)** — simplest setup, signs tokens with a base64-encoded secret
+  - **RS256 (JWKS)** — production-ready, signs with a private key and exposes a public JWKS endpoint
 - A custom Postgres image published to Docker Hub
 
 ## Prerequisites
@@ -27,7 +29,7 @@ Since this is just PostgreSQL + a small auth server (not a full Supabase stack),
 |----------|---------|-------------|
 | RAM | 1 GB | 2 GB |
 | CPU | 1 core | 2 cores |
-| Disk | 10 GB SSD | 20 GB+ |
+| Disk | 4 GB SSD | 10 GB+ |
 
 ---
 
@@ -89,7 +91,7 @@ fly apps create <your-app-name>
 ### 4b. Create a persistent volume
 
 ```bash
-fly volumes create pg_data --app <your-app-name> --region <region> --size 10
+fly volumes create pg_data --app <your-app-name> --region <region> --size 4
 ```
 
 ### 4c. Create a Fly Machine
@@ -256,13 +258,16 @@ const http = require("http");
 const jwt = require("jsonwebtoken");
 
 const PORT = process.env.PORT || 3001;
-const JWT_SECRET = process.env.JWT_SECRET;
+const JWT_SECRET_RAW = process.env.JWT_SECRET;
 
-if (!JWT_SECRET) {
+if (!JWT_SECRET_RAW) {
   console.error("JWT_SECRET environment variable is required");
   process.exit(1);
 }
 
+// Decode base64 secret to raw bytes — must match how CloudSync verifies tokens
+const JWT_SECRET = Buffer.from(JWT_SECRET_RAW, "base64");
+
 function parseBody(req) {
   return new Promise((resolve, reject) => {
     let data = "";
@@ -297,7 +302,7 @@ const server = http.createServer(async (req, res) => {
       const claims = body.claims || {};
 
       const token = jwt.sign(
-        { sub, role, ...claims },
+        { sub, role, aud: "authenticated", ...claims },
         JWT_SECRET,
         { expiresIn, algorithm: "HS256" }
       );
@@ -312,20 +317,149 @@ const server = http.createServer(async (req, res) => {
 });
 
 server.listen(PORT, () => {
-  console.log(`Auth server listening on port ${PORT}`);
+  console.log("Auth server listening on port " + PORT);
 });
 AUTHEOF
 ```
 
 Install dependencies:
 
 ```bash
-cd /data/cloudsync-postgres/auth-server
-# Install node if not available
-apt-get install -y nodejs npm 2>/dev/null || true
-docker run --rm -v $(pwd):/app -w /app node:22-alpine npm install
+docker run --rm -v $(pwd)/auth-server:/app -w /app node:22-alpine npm install
 ```
 
+### 6e. (Optional) Create the JWKS auth server
+
+If you need RS256/JWKS-based authentication instead of (or in addition to) the shared secret approach, create a second auth server that generates an RSA key pair on startup and exposes a JWKS endpoint.
+
+```bash
+mkdir -p auth-server-jwks
+
+cat > auth-server-jwks/package.json << 'EOF'
+{
+  "name": "cloudsync-auth-jwks",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0",
+    "jose": "^5.0.0"
+  }
+}
+EOF
+
+cat > auth-server-jwks/server.js << 'EOF'
+const http = require("http");
+const jwt = require("jsonwebtoken");
+const crypto = require("crypto");
+const { exportJWK } = require("jose");
+
+const PORT = process.env.PORT || 3002;
+const ISSUER = process.env.ISSUER || "cloudsync-auth-jwks";
+const KID = "cloudsync-key-1";
+
+let privateKey, publicKey, jwksResponse;
+
+async function init() {
+  const pair = crypto.generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  });
+  privateKey = pair.privateKey;
+  publicKey = pair.publicKey;
+
+  const publicKeyObject = crypto.createPublicKey(publicKey);
+  const jwk = await exportJWK(publicKeyObject);
+  jwk.kid = KID;
+  jwk.alg = "RS256";
+  jwk.use = "sig";
+  jwksResponse = JSON.stringify({ keys: [jwk] });
+
+  console.log("RSA key pair generated (kid: " + KID + ")");
+}
+
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", (chunk) => (data += chunk));
+    req.on("end", () => {
+      try { resolve(JSON.parse(data)); }
+      catch { reject(new Error("Invalid JSON")); }
+    });
+    req.on("error", reject);
+  });
+}
+
+function respond(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(typeof body === "string" ? body : JSON.stringify(body));
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.method === "GET" && req.url === "/healthz") {
+    return respond(res, 200, { status: "ok" });
+  }
+
+  // JWKS endpoint — CloudSync server fetches this to verify tokens
+  if (req.method === "GET" && req.url === "/.well-known/jwks.json") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    return res.end(jwksResponse);
+  }
+
+  // POST /token { "sub": "user-id", "role": "authenticated", "expiresIn": "24h" }
+  if (req.method === "POST" && req.url === "/token") {
+    try {
+      const body = await parseBody(req);
+      const sub = body.sub || "anonymous";
+      const role = body.role || "authenticated";
+      const expiresIn = body.expiresIn || "24h";
+      const claims = body.claims || {};
+
+      const token = jwt.sign(
+        { sub, role, aud: "authenticated", iss: ISSUER, ...claims },
+        privateKey,
+        { expiresIn, algorithm: "RS256", keyid: KID }
+      );
+
+      return respond(res, 200, { token, expiresIn });
+    } catch (err) {
+      return respond(res, 400, { error: err.message });
+    }
+  }
+
+  respond(res, 404, { error: "Not found" });
+});
+
+init().then(() => {
+  server.listen(PORT, () => {
+    console.log("JWKS Auth server listening on port " + PORT);
+  });
+});
+EOF
+
+docker run --rm -v $(pwd)/auth-server-jwks:/app -w /app node:22-alpine npm install
+```
+
+Add the JWKS auth service to `docker-compose.yml`:
+
+```yaml
+  auth-jwks:
+    image: node:22-alpine
+    container_name: cloudsync-auth-jwks
+    environment:
+      PORT: 3002
+      ISSUER: cloudsync-auth-jwks
+    ports:
+      - "3002:3002"
+    volumes:
+      - ./auth-server-jwks:/app
+    working_dir: /app
+    command: ["node", "server.js"]
+    restart: unless-stopped
+```
+
+> **Note:** The JWKS server generates a new RSA key pair each time it starts. For production, persist the key pair to a volume so tokens remain valid across restarts.
+
 ---
 
 ## Step 7: Start the stack
@@ -339,27 +473,39 @@ Verify:
 
 ```bash
 docker compose ps
-# Both db and auth should be running
 
 # Test Postgres
 docker compose exec db psql -U postgres -c "SELECT cloudsync_version();"
 
-# Test auth server
+# Test HS256 auth server
 curl http://localhost:3001/healthz
+
+# Test JWKS auth server (if enabled)
+curl http://localhost:3002/healthz
+curl http://localhost:3002/.well-known/jwks.json
 ```
 
 ---
 
 ## Step 8: Generate a JWT token
 
+**HS256 (shared secret):**
+
 ```bash
-# Generate a token for a user
 curl -X POST http://localhost:3001/token \
   -H "Content-Type: application/json" \
   -d '{"sub": "user-1", "role": "authenticated"}'
 ```
 
-Response:
+**RS256 (JWKS):**
+
+```bash
+curl -X POST http://localhost:3002/token \
+  -H "Content-Type: application/json" \
+  -d '{"sub": "user-1", "role": "authenticated"}'
+```
+
+Response (both):
 
 ```json
 {"token":"eyJhbG...","expiresIn":"24h"}
@@ -467,17 +613,35 @@ docker compose exec db psql -U postgres -c "SELECT * FROM todos;"
 
 ## Step 11: CloudSync server JWT configuration
 
-The CloudSync server needs to validate tokens from your auth server. Configure these environment variables on the CloudSync server:
+The CloudSync server needs to validate tokens from your auth server. Configuration depends on which auth method you chose.
+
+### Option A: HS256 (shared secret)
+
+Configure these environment variables on the CloudSync server:
 
 ```env
-# Use the same JWT_SECRET as your auth server
+# Use the same JWT_SECRET as your auth server (base64-encoded)
 JWT_SECRET=<your-jwt-secret>
 
 # For development/testing, set the development issuer override
 JWT_DEVELOPMENT_ISSUER_PROJECT_ID=cloudsync-postgres-flyio
 ```
 
-This allows the CloudSync server to verify HS256 tokens signed with your shared secret.
+Both the auth server and CloudSync must decode the base64 secret to the same raw bytes before signing/verifying.
+
+### Option B: RS256 (JWKS)
+
+Configure the CloudSync server to fetch the public key from your JWKS endpoint:
+
+```env
+# JWKS endpoint URL — CloudSync fetches public keys from here to verify RS256 tokens
+JWKS_URL=http://cloudsync-postgres-test.internal:3002/.well-known/jwks.json
+
+# Must match the ISSUER env var on the JWKS auth server
+JWT_ISSUER=cloudsync-auth-jwks
+```
+
+No shared secret is needed — the CloudSync server fetches the public key from the JWKS endpoint and uses it to verify token signatures. This is how production auth systems (Auth0, Supabase, Firebase) work.
 
 ---
 
@@ -486,13 +650,16 @@ This allows the CloudSync server to verify HS256 tokens signed with your shared
 | Service | URL |
 |---------|-----|
 | **PostgreSQL** | `postgres://postgres:<password>@<your-app-name>.internal:5432/postgres` |
-| **Auth Server** | `http://<your-app-name>.internal:3001` |
+| **Auth Server (HS256)** | `http://<your-app-name>.internal:3001` |
+| **Auth Server (JWKS)** | `http://<your-app-name>.internal:3002` |
+| **JWKS Endpoint** | `http://<your-app-name>.internal:3002/.well-known/jwks.json` |
 
 From your local machine, use `fly proxy`:
 
 ```bash
 fly proxy 5432:5432 -a <your-app-name>   # Postgres
-fly proxy 3001:3001 -a <your-app-name>   # Auth server
+fly proxy 3001:3001 -a <your-app-name>   # Auth server (HS256)
+fly proxy 3002:3002 -a <your-app-name>   # Auth server (JWKS)
 ```
 
 ---
@@ -585,7 +752,9 @@ docker compose logs -f auth   # Auth server only
 | `fractional_indexing.h: No such file or directory` | Run `git submodule update --init --recursive` before building |
 | `cloudsync_version()` not found | Init scripts only run on first start. Run `CREATE EXTENSION IF NOT EXISTS cloudsync;` manually |
 | Auth server won't start | Check `docker compose logs auth`. Ensure `npm install` was run in `auth-server/` |
-| Token verification fails on CloudSync server | Ensure `JWT_SECRET` matches between auth server and CloudSync server |
+| Token verification fails (HS256) | Ensure `JWT_SECRET` matches and both sides base64-decode it before use |
+| Token verification fails (JWKS) | Ensure CloudSync can reach the JWKS endpoint and `JWT_ISSUER` matches the `ISSUER` env var |
+| JWKS keys lost after restart | The JWKS server generates new keys on each start. For production, persist keys to a volume |
 | Docker commands not found after VM restart | Run `/data/startup.sh` — Fly VM root filesystem resets on stop/start |
 | `fuse-overlayfs` not working | Install it: `apt-get install -y fuse-overlayfs` |
 | Can't connect to Postgres from outside Fly | Use `fly proxy 5432:5432 -a <your-app-name>` |