@nsec/server

Zero-Knowledge REST API Server & Client-Side Decrypted Web Dashboard for NullSec / ZVault

Overview • Installation & Running • Architecture • Security & Access Control • Database Adapters • API Routes

Overview

@nsec/server is the backend orchestration and zero-knowledge synchronization service for NullSec (zVault). Built on top of Hono, it provides:

• Zero-Knowledge Architecture: All secrets stored and exchanged are encrypted on the client side with AES-256-GCM. The server never holds or receives private keys or plaintext secrets.
• Cryptographic Request Authentication: Validates Ed25519 digital signatures on incoming requests with anti-replay protection.
• Built-in Web Dashboard: Client-side single-page application that decrypts secrets directly in the browser using the WebCrypto API.
• Modern Storage Engine: Native SQLite support using Node.js built-in node:sqlite (zero compilation/native node-gyp dependencies), plus Cloudflare D1 and in-memory test adapters.
• Access Control & BOLA Protection: Strict Broken Object Level Authorization checks ensuring users can only read or mutate projects and environments they are explicitly granted access to.

Installation & Running

1. Run with npx / CLI

The package provides three executable CLI aliases: nsec-server, nullsec-server, and zvault-server.

# Start server with default port 4000
npx @nsec/server

# Custom port, host, and persistent SQLite database
PORT=8080 HOST=0.0.0.0 DATABASE_PATH=/var/data/nullsec.db npx @nsec/server

2. Global Installation

npm install -g @nsec/server
nsec-server

3. Docker Deployment

docker run -d \
  -p 4000:4000 \
  -v /var/nullsec-data:/data \
  -e DATABASE_PATH=/data/nullsec.db \
  ghcr.io/chamesh2019/nsec-server:latest

Architecture

                  ┌──────────────────────────────────────────────┐
                  │              Incoming Request                │
                  │   Headers: X-NullSec-Signature, Timestamp    │
                  └───────────────────────┬──────────────────────┘
                                          │
                                          ▼
                       ┌─────────────────────────────────────┐
                       │      Authentication Middleware      │
                       │   - Anti-Replay Sliding Window      │
                       │   - Ed25519 Signature Verification  │
                       │   - Resolve Authenticated User      │
                       └──────────────────┬──────────────────┘
                                          │
                                          ▼
                       ┌─────────────────────────────────────┐
                       │     Project & BOLA Authorization    │
                       │   - Verify Project Membership       │
                       │   - Check Environment Role Perms    │
                       └──────────────────┬──────────────────┘
                                          │
                        ┌─────────────────┴─────────────────┐
                        ▼                                   ▼
             ┌─────────────────────┐             ┌─────────────────────┐
             │ REST API Endpoints  │             │ Web Admin Dashboard │
             │  /api/v1/projects   │             │   Client-side SPA   │
             │  /api/v1/secrets    │             │   In-browser crypto │
             └──────────┬──────────┘             └─────────────────────┘
                        │
                        ▼
             ┌─────────────────────┐
             │  Database Adapter   │
             │ (node:sqlite / D1)  │
             └─────────────────────┘

Security & Access Control

1. Anti-Replay Attack Protection: All requests are timestamped. Signatures are verified and cached in a sliding time window (5-minute drift ceiling). Replayed requests with previously observed signatures are rejected immediately.
2. First-User Bootstrap: The first user to register on a new instance automatically receives the admin server role. Subsequent registrations require a single-use signed invite token generated by an administrator.
3. Environment-Level Scoping: Project members can be granted access to specific environments (e.g. ['development'] vs ['development', 'staging', 'production']) with read or admin permissions.
4. Hardened HTTP Headers: Uses Hono secureHeaders (X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Cross-Origin-Opener-Policy: same-origin).

Database Adapters

@nsec/server abstracts all persistence behind the DatabaseAdapter interface:

import { startServer, SqliteDatabaseAdapter, MemoryDatabaseAdapter } from '@nsec/server';

// 1. Persistent production storage using Node 22+ built-in node:sqlite
const db = new SqliteDatabaseAdapter('./data/nullsec.sqlite');
await startServer({ port: 4000, db });

// 2. Ephemeral in-memory database for testing
const testDb = new MemoryDatabaseAdapter();
await startServer({ port: 0, db: testDb });

API Routes Summary

| Method | Path | Description | |---|---|---| | GET | /health | Healthcheck and service version | | GET | / | Web Dashboard SPA entry point | | POST | /api/v1/auth/register | Register user identity (Ed25519 & RSA public keys) | | POST | /api/v1/auth/rotate-keys | Cryptographically rotate identity public keys | | GET | /api/v1/users | List users on server (admin only) | | PATCH | /api/v1/users/:id/role | Update user server role (admin only) | | POST | /api/v1/invites | Create invite token (admin only) | | GET | /api/v1/invites | List active invite tokens | | DELETE | /api/v1/invites/:id | Revoke invite token | | POST | /api/v1/projects | Create a new project | | GET | /api/v1/projects/:id | Get project details (members only) | | POST | /api/v1/projects/:id/members | Add member and upload user-specific wrapped key | | GET | /api/v1/projects/:id/environments/:env/secrets | Fetch encrypted payload & caller envelope key | | PUT | /api/v1/projects/:id/environments/:env/secrets | Upload updated encrypted ciphertext | | POST | /api/v1/projects/:id/tokens | Create CI/CD service token |

License

MIT © NullSec / zVault Contributors