⚡ PowerSync Node.js Backend — Deterministic Offline-First Data Replication

A production-ready offline-first data synchronization and replication backend engineered in Node.js & Express. It bridges edge-native client SQLite databases with cloud-hosted PostgreSQL instances, implementing asymmetric RS256 token issuance and public JWKS verification.

---

🏛️ System Architecture Topology

┌────────────────────────────────────────────────────────────────────────────────┐
│                             CLIENT / EDGE DEVICE                               │
│              Local SQLite Embedded Database (PowerSync Client SDK)             │
└───────────────────────────────────────┬────────────────────────────────────────┘
                                        │
                         Bidirectional Streaming Sync
                                        ▼
┌────────────────────────────────────────────────────────────────────────────────┐
│                            POWERSYNC CLOUD RUNTIME                             │
│                  Replication Stream Engine & State Synchronizer                │
└───────────────────┬────────────────────────────────────────┬───────────────────┘
                    │                                        │
           Validate Token via JWKS                  Sync Reads & Writes
                    ▼                                        ▼
┌───────────────────────────────────────┐ ┌───────────────────────────────────────┐
│     Node.js Authentication Engine     │ │      PostgreSQL Production DB         │
│   • /api/auth/token (RS256 JWT)       │ │   • Normalized relational schema      │
│   • /api/auth/keys  (Public JWKS)     │ │   • Write-ahead logging & replication │
└───────────────────────────────────────┘ └───────────────────────────────────────┘

---

⚡ Key Capabilities

1. Cryptographic RS256 Token Authority

• Generates short-lived, cryptographically signed JSON Web Tokens (5m expiry) using the jose cryptographic library.
• Signs payloads with asymmetric private keys containing specific key identifier (kid) and algorithm (RS256) claims.

2. Standard Public JWKS Key Server

• Exposes a public JSON Web Key Set (/api/auth/keys) containing public exponent (e), modulus (n), and thumbprint (kid).
• Allows the PowerSync replication engine to autonomously verify client identity without sharing symmetric secrets.

3. Bidirectional Sync Routing

• /api/data: Batch ingestion endpoint supporting optimistic client writes, conflict resolution, and relational database transactions.
• Sub-50ms query latency on indexed lookups.

---

🚀 Quickstart

Prerequisites

• Node.js 18+
• PostgreSQL instance (local or hosted)

Installation

# Clone the repository
git clone https://github.com/gurumaan/powersync-nodejs-backend.git
cd powersync-nodejs-backend

# Install dependencies
npm install

# Configure environment variables
cp .env.template .env

Running the Server

# Start backend in development mode
npm start

Default server runs on http://localhost:8000.

---

📡 API Endpoints

Method	Endpoint	Description
GET	/api/auth/token	Generates a signed PowerSync RS256 JWT for the authenticated client
GET	/api/auth/keys	Returns public JWKS key set for replication engine verification
POST	/api/data	Batch writes sync events into PostgreSQL relational storage
GET	/api/data	Retrieves delta changesets for client catch-up sync

---

🛡️ License

Distributed under the MIT License. Built with ❤️ by Gursharan Singh.