privacy-first


📁 server/README.md

# 📄 `privacy-first-server`

@indoscient/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).


Table of Contents


Installation

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

Running Locally

  1. Start the development server with hot-reload:
    npm run dev
    
  2. The server will listen on http://localhost:4000, For production:
     npm run build
     npm start
    

API Endpoints

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-Key header.


Error Responses

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

Security Controls

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

Scripts Overview

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

Privacy

See our Privacy Design Decisions for details on how this client handles encryption and data minimization.

Key highlights:


Contributing

We love contributions! Follow these steps:

  1. Fork the repository.
  2. Create a feature branch
     git checkout -b feat/awesome-feature
    
  3. Implement your change and run the test suite and lint to ensure TypeScript compiles:
     npm test && npm run lint && npm run typecheck
    
  4. Open a Pull Request against main. Please keep the API surface stable and add documentation for any new endpoints.

License

MIT © Suman Jangili. See the LICENSE file for full terms.