Metadata-Version: 2.4
Name: gitnix
Version: 1.1.0
Summary: Use GitHub repos as an encrypted, high-performance database
Project-URL: Homepage, https://github.com/Quilonix/gitnix
Project-URL: Repository, https://github.com/Quilonix/gitnix
Project-URL: Issues, https://github.com/Quilonix/gitnix/issues
Project-URL: Documentation, https://github.com/Quilonix/gitnix/tree/main/docs
Author-email: Mithun Gowda B <mithungowda.b7411@gmail.com>
License-Expression: MIT
Keywords: database,e2e-encryption,encrypted,git,github,local-first,nosql,sdk,zero-knowledge
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: msgpack>=1.0.8
Requires-Dist: pynacl>=1.5.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Gitnix

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

[![PyPI](https://img.shields.io/pypi/v/gitnix)](https://pypi.org/project/gitnix/)
[![Python](https://img.shields.io/pypi/pyversions/gitnix)](https://pypi.org/project/gitnix/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Quilonix/gitnix/blob/main/LICENSE)

Gitnix is a Python 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

```bash
pip install gitnix
```

## Quick Start

```python
import os
from gitnix import Gitnix
from gitnix.types import GitnixConfig

db = Gitnix(GitnixConfig(
    repo="your-username/my-database",
    token=os.environ["GITHUB_TOKEN"],
    password="my-secret-encryption-key",
))

async with db:
    users = db.collection("users")

    # Insert
    await users.insert({"name": "Alice", "age": 30, "email": "alice@example.com"})

    # Query (MongoDB-style)
    adults = await users.find({"age": {"$gte": 18}})

    # Update
    await users.update({"name": "Alice"}, {"$set": {"age": 31}})

    # Delete
    await users.delete({"name": "Alice"})

    # Sync encrypted data to GitHub
    await db.sync()
```

## 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
- **Async-Native** — Built on `asyncio` with full `async/await` support
- **Fully Typed** — Complete type annotations, strict mypy compatible
- **Rate Limit Aware** — Built-in rate limiter with queue and backpressure

## 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.

## Query Operators

```python
# Comparison
await users.find({"age": {"$gt": 18}})
await users.find({"status": {"$in": ["active", "pending"]}})

# Logical
await users.find({"$or": [{"city": "NYC"}, {"city": "LA"}]})

# String
await users.find({"name": {"$contains": "alice"}})
await users.find({"email": {"$regex": "^admin@"}})

# Options
await users.find(query, sort={"age": -1}, skip=0, limit=20)
```

## Also Available

- **JavaScript/TypeScript SDK**: `npm install gitnix` — [npm](https://www.npmjs.com/package/gitnix)
- **Full Example App**: Event registration platform with admin panel, auth, and 45 E2E tests

## Documentation

- [GitHub Repository](https://github.com/Quilonix/gitnix)
- [JavaScript API Reference](https://github.com/Quilonix/gitnix/blob/main/docs/API-JS.md)
- [Python API Reference](https://github.com/Quilonix/gitnix/blob/main/docs/API-PYTHON.md)
- [Security & Threat Model](https://github.com/Quilonix/gitnix/blob/main/docs/SECURITY.md)
- [Usage Guide & Examples](https://github.com/Quilonix/gitnix/blob/main/docs/GUIDE.md)
- [Architecture Deep Dive](https://github.com/Quilonix/gitnix/blob/main/ARCHITECTURE.md)
- [Example App (Event Registration)](https://github.com/Quilonix/gitnix/tree/main/examples)
- [npm (JavaScript SDK)](https://www.npmjs.com/package/gitnix)

## License

MIT — [Quilonix](https://github.com/Quilonix)
