Gitnix

Turn any GitHub repository into a fast, encrypted, zero-knowledge database.

Gitnix is a JavaScript/TypeScript SDK that uses GitHub repos as a database backend. All data is end-to-end encrypted client-side — GitHub never sees your plaintext data.

Install

npm install gitnix

Quick Start

import { Gitnix } from 'gitnix';

const db = new Gitnix({
  repo: 'your-username/my-database',
  token: process.env.GITHUB_TOKEN,
  password: 'my-secret-encryption-key',
});

await db.connect();

const users = db.collection('users');

// Insert
await users.insert({ name: 'Alice', age: 30, email: '[email protected]' });

// Query (MongoDB-style)
const adults = await users.find({ age: { $gte: 18 } }, { sort: { age: -1 } });

// Update
await users.update({ name: 'Alice' }, { $set: { age: 31 } });

// Delete
await users.delete({ name: 'Alice' });

// Sync encrypted data to GitHub
await db.sync();

await db.disconnect();

Features

• Zero-Knowledge Encryption — XSalsa20-Poly1305 + Argon2id key derivation
• MongoDB-Style Queries — $eq, $gt, $in, $or, $regex, $contains, and more
• Sub-millisecond Operations — Local-first with encrypted disk cache
• GitHub Sync — On-demand push/pull to GitHub (encrypted blobs only)
• Binary/Image Storage — Chunked upload/download with MIME detection
• Transactions — Optimistic locking with conflict detection
• Schema Validation — Optional type checking and constraints
• Rate Limit Aware — Built-in rate limiter with queue and backpressure
• TypeScript First — Full type definitions included

Performance

| Operation | Avg Latency | Throughput | |-----------|-------------|-----------| | Create record | 1.2ms | 813 req/s | | Read single | 0.98ms | 1,021 req/s | | List all (50 docs) | 1.0ms | 995 req/s | | Filtered query | 0.65ms | 1,531 req/s | | Update record | 1.0ms | 1,000 req/s | | Delete (+ cascade) | 0.66ms | 1,526 req/s | | Push to GitHub | ~3.0s | 6 API calls | | Pull from GitHub | ~1.2s | 3 API calls |

Security

| Property | Implementation | |----------|---------------| | Algorithm | XSalsa20-Poly1305 (256-bit key) | | Key derivation | Argon2id (memory-hard, GPU-resistant) | | Per-record nonces | Random 24-byte nonce per encryption | | Filename obfuscation | SHA-256 hashed names | | Zero plaintext | GitHub only receives encrypted blobs |

Security audit: A+ (49/49 tests passed across 11 categories)

Who Should Use This?

✅ Solo developers, side projects, MVPs, hackathons, privacy-focused apps, students, note-taking apps, config management, small teams (< 10), IoT/edge devices.

❌ Not for: high-traffic production (1000+ concurrent users), real-time apps, complex SQL joins, high-frequency writes (100+/sec), or data > 100GB.

GitHub Rate Limits

| Pattern | API Calls/hr | Works? | |---------|-------------|--------| | Sync every 5 min | 72 | ✅ (1.4% of budget) | | Sync every 1 min | 360 | ✅ (7%) | | 100 users (cached reads) | 0 | ✅ | | Real-time sync (every sec) | 21,600 | ❌ |

Recommended: Write locally (sub-ms), sync to GitHub periodically.

Query Operators

// Comparison
{ age: { $gt: 18 } }
{ status: { $in: ['active', 'pending'] } }
{ score: { $gte: 90, $lte: 100 } }

// Logical
{ $or: [{ city: 'NYC' }, { city: 'LA' }] }
{ $and: [{ age: { $gte: 18 } }, { verified: true }] }

// String
{ name: { $contains: 'alice' } }
{ email: { $regex: '^admin@' } }

// Options
await users.find(query, {
  sort: { age: -1 },
  skip: 0,
  limit: 20,
  fields: ['name', 'email'],
});

Also Available

• Python SDK: pip install gitnix — PyPI
• Full Example App: Event registration platform with admin panel, auth, and 45 E2E tests

Links

• GitHub Repository
• JavaScript API Reference
• Python API Reference
• Security & Threat Model
• Usage Guide & Examples
• Architecture Deep Dive
• Example App (Event Registration)
• Python SDK on PyPI

License

MIT — Quilonix