server/README.md# 📄 `privacy-first-server`
A minimal privacy-first backend built with Express, TypeScript, and libsodium-wrappers.
It provides a secure API for receiving encrypted ciphertext and decrypting data—perfect for pairing with the companion client package (@indoscient/privacy-first-client).
From npm:
npm install @indoscient/privacy-first-server
clone the repo and install dev dependencies:
git clone https://github.com/indoscient/privacy-first.git
cd privacy-first/server
npm ci # installs exact versions from lockfile
npm run dev
npm run build
npm start
| Method | Path | Auth Required | Description |
|---|---|---|---|
GET |
/ |
❌ No | Welcome message |
GET |
/health |
❌ No | Health check { status: 'ok' } |
GET |
/public-key |
✅ Yes | Returns server’s public key (Base64) |
POST |
/decrypt |
✅ Yes | Body: { ciphertext } → Response: { plaintext } |
Note: All authenticated endpoints require the
X-API-Keyheader.
| Status | Body | Meaning |
|---|---|---|
400 |
{ error: 'Missing or invalid ciphertext' } |
Malformed request |
401 |
{ error: 'Unauthorized' } |
Invalid or missing API key |
429 |
{ error: 'Too many requests...' } |
Rate limit exceeded |
500 |
{ error: 'Failed to decrypt' } |
Decryption error |
| Control | Implementation |
|---|---|
| Authentication | API key middleware with constant-time comparison |
| Rate Limiting | 100 req/15min global, 20 req/15min on /decrypt |
| CORS Restrictions | Origin whitelist via ALLOWED_ORIGINS env var |
| Security Headers | Helmet.js (HSTS, X-Frame-Options, etc.) |
| Payload Validation | JSON body cap at 64KB, ciphertext length validation |
| Script | Description |
|---|---|
| dev | Runs ts-node-dev for live reload while developing |
| build | Compiles TypeScript to dist/ (tsc) |
| start | Executes the compiled server (node dist/index.js) |
| gen:keypair | Utility script to generate a Curve25519 key pair from CLI |
Generate a new key pair:
npm run gen:keypair
See our Privacy Design Decisions for details on how this client handles encryption and data minimization.
Key highlights:
We love contributions! Follow these steps:
git checkout -b feat/awesome-feature
npm test && npm run lint && npm run typecheck
MIT © Suman Jangili. See the LICENSE file for full terms.