parad 0.1.0__tar.gz

parad-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: parad
+Version: 0.1.0
+Summary: Encrypted local-first SQLite with Telegram cloud sync
+Author-email: nexuss0781 <nexuss0781@gmail.com>
+Project-URL: Homepage, https://github.com/nexuss0781/Paradox-DB
+Project-URL: Repository, https://github.com/nexuss0781/Paradox-DB
+Project-URL: Issues, https://github.com/nexuss0781/Paradox-DB/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pydantic>=2.0
+
+# parad
+
+Encrypted local-first SQLite with Telegram cloud sync.
+
+## Install
+
+```bash
+pip install parad
+```
+
+## Quick Start
+
+```bash
+# Create an encrypted database
+parad init mydb
+
+# Push to cloud
+parad push
+
+# Pull latest
+parad pull
+
+# Check status
+parad status
+
+# Interactive SQL
+parad shell
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `parad init <name>` | Create encrypted DB + register with gateway |
+| `parad push` | Push database to Telegram cloud |
+| `parad pull [version]` | Pull latest or specific version |
+| `parad sync` | Push then pull |
+| `parad status` | Local vs remote version |
+| `parad versions` | List all remote versions |
+| `parad rollback <ver>` | Rollback to previous version |
+| `parad exec <sql>` | Run raw SQL |
+| `parad insert <table> <json>` | Insert a row |
+| `parad select <table> [where]` | Query rows |
+| `parad update <table> <set> <where>` | Update rows |
+| `parad delete <table> <where>` | Delete rows |
+| `parad shell` | Interactive SQL REPL |
+| `parad config show/set` | Manage config |
+
+## Configuration
+
+Config lives at `~/.paradox/config.json`:
+
+```json
+{
+  "database_path": "~/.paradox/data.db",
+  "sync": {
+    "gateway_url": "https://paradox-db.onrender.com/v1",
+    "api_key": "pk_..."
+  }
+}
+```
+
+## Security
+
+- AES-256-CBC encryption at rest
+- PBKDF2-HMAC-SHA512 key derivation (256k iterations)
+- Your passphrase never leaves your machine

parad-0.1.0/README.md

@@ -0,0 +1,67 @@
+# parad
+
+Encrypted local-first SQLite with Telegram cloud sync.
+
+## Install
+
+```bash
+pip install parad
+```
+
+## Quick Start
+
+```bash
+# Create an encrypted database
+parad init mydb
+
+# Push to cloud
+parad push
+
+# Pull latest
+parad pull
+
+# Check status
+parad status
+
+# Interactive SQL
+parad shell
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `parad init <name>` | Create encrypted DB + register with gateway |
+| `parad push` | Push database to Telegram cloud |
+| `parad pull [version]` | Pull latest or specific version |
+| `parad sync` | Push then pull |
+| `parad status` | Local vs remote version |
+| `parad versions` | List all remote versions |
+| `parad rollback <ver>` | Rollback to previous version |
+| `parad exec <sql>` | Run raw SQL |
+| `parad insert <table> <json>` | Insert a row |
+| `parad select <table> [where]` | Query rows |
+| `parad update <table> <set> <where>` | Update rows |
+| `parad delete <table> <where>` | Delete rows |
+| `parad shell` | Interactive SQL REPL |
+| `parad config show/set` | Manage config |
+
+## Configuration
+
+Config lives at `~/.paradox/config.json`:
+
+```json
+{
+  "database_path": "~/.paradox/data.db",
+  "sync": {
+    "gateway_url": "https://paradox-db.onrender.com/v1",
+    "api_key": "pk_..."
+  }
+}
+```
+
+## Security
+
+- AES-256-CBC encryption at rest
+- PBKDF2-HMAC-SHA512 key derivation (256k iterations)
+- Your passphrase never leaves your machine

parad-0.1.0/parad/__init__.py

@@ -0,0 +1,3 @@
+"""parad — Encrypted local-first SQLite with Telegram cloud sync."""
+
+__version__ = "0.1.0"

parad-0.1.0/parad/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m parad`."""
+
+from parad.cli import main
+
+if __name__ == "__main__":
+    main()

parad-0.1.0/parad/cli.py

@@ -0,0 +1,34 @@
+"""parad CLI entry point."""
+
+import os
+import click
+
+@click.group()
+@click.version_option(package_name="parad")
+def main():
+    """parad — Encrypted local-first SQLite with Telegram cloud sync."""
+    pass
+
+
+# Import and register all commands
+from parad.commands.init import init
+from parad.commands.sync import push, pull, sync
+from parad.commands.status import status, versions, rollback
+from parad.commands.query import exec_cmd, insert, select, update, delete
+from parad.commands.shell import shell
+from parad.commands.config_cmd import config_group
+
+main.add_command(init)
+main.add_command(push)
+main.add_command(pull)
+main.add_command(sync)
+main.add_command(status)
+main.add_command(versions)
+main.add_command(rollback)
+main.add_command(exec_cmd, name="exec")
+main.add_command(insert)
+main.add_command(select)
+main.add_command(update)
+main.add_command(delete)
+main.add_command(shell)
+main.add_command(config_group)

parad-0.1.0/parad/commands/config_cmd.py

@@ -0,0 +1,27 @@
+"""parad config — View and update configuration."""
+
+import click
+from parad.config import load_config, set_config_value, save_config
+
+
+@click.group("config")
+def config_group():
+    """Manage parad configuration."""
+    pass
+
+
+@config_group.command("show")
+def config_show():
+    """Show current configuration."""
+    import json
+    config = load_config()
+    click.echo(json.dumps(config.model_dump(), indent=2))
+
+
+@config_group.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str):
+    """Set a config value: parad config set sync.api_key pk_xxx"""
+    set_config_value(key, value)
+    click.echo(f"✓ Set {key} = {value}")

parad-0.1.0/parad/commands/init.py

@@ -0,0 +1,48 @@
+"""parad init — Create a new encrypted database and register with gateway."""
+
+import click
+from pathlib import Path
+from parad.config import load_config, save_config, CONFIG_DIR
+from parad.engine import Engine
+from parad.gateway import GatewayClient
+
+
+@click.command()
+@click.argument("name")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+@click.option("--gateway", envvar="PARADOX_GATEWAY_URL", default=None)
+def init(name: str, passphrase: str, gateway: str | None):
+    """Create a new encrypted database and register with gateway."""
+    config = load_config()
+    
+    if gateway:
+        config.sync.gateway_url = gateway
+    
+    db_path = CONFIG_DIR / f"{name}.db"
+    config.database_path = str(db_path)
+    
+    # Create local encrypted database
+    engine = Engine(str(db_path), passphrase)
+    engine.open()
+    engine.create_tables()
+    engine.close()
+    
+    click.echo(f"✓ Created encrypted database: {db_path}")
+    
+    # Auto-register if no API key
+    if not config.sync.api_key:
+        gw = GatewayClient(config.sync.gateway_url)
+        try:
+            result = gw.register("0", config.sync.gateway_url)
+            config.sync.api_key = result.api_key
+            save_config(config)
+            click.echo(f"✓ Registered with gateway (user: {result.user_id})")
+            click.echo(f"  API key: {result.api_key}")
+        except Exception as e:
+            click.echo(f"⚠ Gateway registration failed: {e}")
+            click.echo("  You can register later with: parad config set sync.api_key <key>")
+    else:
+        click.echo("  Gateway already configured")
+    
+    save_config(config)
+    click.echo(f"\nDatabase ready at: {db_path}")

parad-0.1.0/parad/commands/query.py

@@ -0,0 +1,79 @@
+"""parad exec/insert/select/update/delete — Local SQL operations."""
+
+import json
+import click
+from parad.config import load_config
+from parad.engine import Engine
+
+
+@click.command("exec")
+@click.argument("sql")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def exec_cmd(sql: str, passphrase: str):
+    """Execute raw SQL on the local database."""
+    config = load_config()
+    with Engine(config.database_path, passphrase) as engine:
+        rows = engine.execute(sql)
+        if rows:
+            for row in rows:
+                click.echo(json.dumps(dict(row), default=str))
+        else:
+            click.echo("OK")
+
+
+@click.command("insert")
+@click.argument("table")
+@click.argument("data_json")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def insert(table: str, data_json: str, passphrase: str):
+    """Insert a row: parad insert <table> '{"col": "val"}'."""
+    config = load_config()
+    data = json.loads(data_json)
+    with Engine(config.database_path, passphrase) as engine:
+        rowid = engine.insert(table, data)
+        click.echo(f"Inserted rowid={rowid}")
+
+
+@click.command("select")
+@click.argument("table")
+@click.argument("where_json", required=False)
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def select(table: str, where_json: str | None, passphrase: str):
+    """Query rows: parad select <table> ['{"col": "val"}']."""
+    config = load_config()
+    where = json.loads(where_json) if where_json else None
+    with Engine(config.database_path, passphrase) as engine:
+        rows = engine.select(table, where)
+        if not rows:
+            click.echo("No rows found.")
+            return
+        for row in rows:
+            click.echo(json.dumps(dict(row), default=str))
+
+
+@click.command("update")
+@click.argument("table")
+@click.argument("set_json")
+@click.argument("where_json")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def update(table: str, set_json: str, where_json: str, passphrase: str):
+    """Update rows: parad update <table> '{"col":"val"}' '{"id":1}'."""
+    config = load_config()
+    set_data = json.loads(set_json)
+    where = json.loads(where_json)
+    with Engine(config.database_path, passphrase) as engine:
+        changes = engine.update(table, set_data, where)
+        click.echo(f"Updated {changes} row(s)")
+
+
+@click.command("delete")
+@click.argument("table")
+@click.argument("where_json")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def delete(table: str, where_json: str, passphrase: str):
+    """Delete rows: parad delete <table> '{"id":1}'."""
+    config = load_config()
+    where = json.loads(where_json)
+    with Engine(config.database_path, passphrase) as engine:
+        changes = engine.delete(table, where)
+        click.echo(f"Deleted {changes} row(s)")

parad-0.1.0/parad/commands/shell.py

@@ -0,0 +1,40 @@
+"""parad shell — Interactive SQL REPL."""
+
+import click
+from parad.config import load_config
+from parad.engine import Engine
+
+
+@click.command("shell")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def shell(passphrase: str):
+    """Interactive SQL shell for the local database."""
+    config = load_config()
+    
+    click.echo(f"parad shell — {config.database_path}")
+    click.echo("Type SQL commands, or 'quit' to exit.\n")
+    
+    with Engine(config.database_path, passphrase) as engine:
+        while True:
+            try:
+                line = input("parad> ").strip()
+            except (EOFError, KeyboardInterrupt):
+                click.echo("\nBye.")
+                break
+            
+            if not line:
+                continue
+            if line.lower() in ("quit", "exit", "\\q"):
+                click.echo("Bye.")
+                break
+            
+            try:
+                rows = engine.execute(line)
+                if rows:
+                    import json
+                    for row in rows:
+                        click.echo(json.dumps(dict(row), default=str))
+                else:
+                    click.echo("OK")
+            except Exception as e:
+                click.echo(f"Error: {e}")

parad-0.1.0/parad/commands/status.py

@@ -0,0 +1,91 @@
+"""parad status/versions/rollback — View sync status and manage versions."""
+
+import click
+from parad.config import load_config
+from parad.gateway import GatewayClient, GatewayError
+
+
+@click.command("status")
+def status():
+    """Show local vs remote sync status."""
+    config = load_config()
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    
+    try:
+        result = gw.status()
+    except GatewayError as e:
+        click.echo(f"✗ Status check failed: {e}")
+        raise SystemExit(1)
+    
+    click.echo(f"User: {result.user_id}\n")
+    if not result.databases:
+        click.echo("No databases found.")
+        return
+    
+    for db in result.databases:
+        click.echo(f"  {db.name}")
+        click.echo(f"    Version:    {db.latest_version}")
+        click.echo(f"    Message ID: {db.latest_message_id}")
+        if db.file_hash:
+            click.echo(f"    Hash:       {db.file_hash[:16]}...")
+        if db.uploaded_at:
+            click.echo(f"    Uploaded:   {db.uploaded_at}")
+        click.echo()
+
+
+@click.command("versions")
+@click.option("--name", "-n", default=None, help="Database name")
+def versions(name: str | None):
+    """List all remote versions."""
+    config = load_config()
+    if not name:
+        from pathlib import Path
+        name = Path(config.database_path).name
+    
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    
+    try:
+        result = gw.versions(name)
+    except GatewayError as e:
+        click.echo(f"✗ Versions query failed: {e}")
+        raise SystemExit(1)
+    
+    if not result.versions:
+        click.echo(f"No versions found for {name}.")
+        return
+    
+    click.echo(f"Versions for {name}:\n")
+    for v in result.versions:
+        size_str = f" ({v.file_size} bytes)" if v.file_size else ""
+        type_str = f" [{v.version_type}]" if v.version_type else ""
+        click.echo(f"  v{v.version}{type_str}{size_str}  msg={v.message_id}")
+        if v.uploaded_at:
+            click.echo(f"    {v.uploaded_at}")
+
+
+@click.command("rollback")
+@click.argument("version", type=int)
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def rollback(version: int, passphrase: str):
+    """Rollback to a previous version."""
+    config = load_config()
+    from pathlib import Path
+    db_name = Path(config.database_path).name
+    db_path = Path(config.database_path).expanduser()
+    
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    
+    try:
+        result = gw.rollback(db_name, version)
+        click.echo(f"✓ Rolled back to v{result.rolled_back_to} (new msg={result.new_message_id})")
+    except GatewayError as e:
+        click.echo(f"✗ Rollback failed: {e}")
+        raise SystemExit(1)
+    
+    # Pull the rolled-back version
+    try:
+        file_bytes = gw.download(db_name)
+        db_path.write_bytes(file_bytes)
+        click.echo(f"✓ Pulled rolled-back version")
+    except GatewayError as e:
+        click.echo(f"⚠ Pull after rollback failed: {e}")

parad-0.1.0/parad/commands/sync.py

@@ -0,0 +1,98 @@
+"""parad push/pull/sync — Upload and download databases."""
+
+import os
+import click
+from pathlib import Path
+from parad.config import load_config, CONFIG_DIR
+from parad.engine import Engine
+from parad.gateway import GatewayClient, GatewayError
+
+
+def _get_db_name(config) -> str:
+    return Path(config.database_path).name
+
+
+@click.command("push")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def push(passphrase: str):
+    """Push the local database to the gateway."""
+    config = load_config()
+    db_path = Path(config.database_path).expanduser()
+    
+    if not db_path.exists():
+        click.echo(f"✗ Database not found: {db_path}")
+        raise SystemExit(1)
+    
+    engine = Engine(str(db_path), passphrase)
+    engine.open()
+    raw = engine.get_raw_bytes()
+    engine.close()
+    
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    db_name = _get_db_name(config)
+    
+    try:
+        result = gw.upload(db_name, raw)
+        click.echo(f"✓ Pushed {db_name} v{result.version} (msg={result.message_id})")
+    except GatewayError as e:
+        click.echo(f"✗ Push failed: {e}")
+        raise SystemExit(1)
+
+
+@click.command("pull")
+@click.argument("version", required=False, type=int)
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def pull(version: int | None, passphrase: str):
+    """Pull database from gateway. Optionally specify a version."""
+    config = load_config()
+    db_path = Path(config.database_path).expanduser()
+    db_name = _get_db_name(config)
+    
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    
+    try:
+        file_bytes = gw.download(db_name, version)
+    except GatewayError as e:
+        click.echo(f"✗ Pull failed: {e}")
+        raise SystemExit(1)
+    
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    db_path.write_bytes(file_bytes)
+    
+    ver_str = f"v{version}" if version else "latest"
+    click.echo(f"✓ Pulled {db_name} {ver_str} ({len(file_bytes)} bytes)")
+
+
+@click.command("sync")
+@click.option("--passphrase", envvar="PARADOX_PASSPHRASE", default="default")
+def sync(passphrase: str):
+    """Push local changes, then pull latest from gateway."""
+    config = load_config()
+    db_path = Path(config.database_path).expanduser()
+    db_name = _get_db_name(config)
+    
+    if not db_path.exists():
+        click.echo(f"✗ Database not found: {db_path}")
+        raise SystemExit(1)
+    
+    # Push
+    engine = Engine(str(db_path), passphrase)
+    engine.open()
+    raw = engine.get_raw_bytes()
+    engine.close()
+    
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    
+    try:
+        result = gw.upload(db_name, raw)
+        click.echo(f"✓ Pushed v{result.version}")
+    except GatewayError as e:
+        click.echo(f"⚠ Push failed: {e}")
+    
+    # Pull
+    try:
+        file_bytes = gw.download(db_name)
+        db_path.write_bytes(file_bytes)
+        click.echo(f"✓ Pulled latest ({len(file_bytes)} bytes)")
+    except GatewayError as e:
+        click.echo(f"⚠ Pull failed: {e}")

parad-0.1.0/parad/config.py

@@ -0,0 +1,81 @@
+"""parad configuration management."""
+
+import json
+from pathlib import Path
+from parad.types import Config
+
+
+CONFIG_DIR = Path.home() / ".paradox"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+DEFAULT_CONFIG = {
+    "database_path": "~/.paradox/data.db",
+    "encryption": {
+        "cipher": "aes-256-cbc",
+        "kdf_iterations": 256000,
+        "page_size": 4096,
+    },
+    "sync": {
+        "gateway_url": "https://paradox-db.onrender.com/v1",
+        "api_key": "",
+        "trigger_timer_seconds": 30,
+        "trigger_ops_threshold": 50,
+        "max_file_size_mb": 50,
+        "auto_sync_on_shutdown": True,
+    },
+    "conflict": {
+        "strategy": "last-write-wins",
+        "log_conflicts": True,
+    },
+    "logging": {
+        "level": "info",
+        "path": "~/.paradox/logs",
+    },
+}
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Deep merge override into base."""
+    result = base.copy()
+    for k, v in override.items():
+        if k in result and isinstance(result[k], dict) and isinstance(v, dict):
+            result[k] = _deep_merge(result[k], v)
+        else:
+            result[k] = v
+    return result
+
+
+def load_config() -> Config:
+    """Load config from ~/.paradox/config.json, merged with defaults."""
+    user_config = {}
+    if CONFIG_FILE.exists():
+        try:
+            user_config = json.loads(CONFIG_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    merged = _deep_merge(DEFAULT_CONFIG, user_config)
+    return Config(**merged)
+
+
+def save_config(config: Config):
+    """Save config to ~/.paradox/config.json."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(config.model_dump(), indent=2))
+
+
+def set_config_value(key: str, value: str):
+    """Set a single config value using dot notation (e.g. sync.api_key)."""
+    config = load_config()
+    keys = key.split(".")
+    d = config.model_dump()
+    current = d
+    for k in keys[:-1]:
+        current = current[k]
+    # Try to parse as appropriate type
+    if value.lower() in ("true", "false"):
+        current[keys[-1]] = value.lower() == "true"
+    elif value.isdigit():
+        current[keys[-1]] = int(value)
+    else:
+        current[keys[-1]] = value
+    save_config(Config(**d))

parad-0.1.0/parad/crypto.py

@@ -0,0 +1,49 @@
+"""AES-256-CBC file encryption for parad local database."""
+
+import os
+import hashlib
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from cryptography.hazmat.primitives import hashes
+
+SALT = b"paradox-salt"
+KDF_ITERATIONS = 256_000
+KEY_LENGTH = 32  # 256 bits
+IV_LENGTH = 16  # 128 bits
+
+
+def derive_key(passphrase: str) -> bytes:
+    """Derive a 256-bit key from passphrase using PBKDF2-HMAC-SHA512."""
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA512(),
+        length=KEY_LENGTH,
+        salt=SALT,
+        iterations=KDF_ITERATIONS,
+    )
+    return kdf.derive(passphrase.encode("utf-8"))
+
+
+def encrypt_file(data: bytes, passphrase: str) -> bytes:
+    """Encrypt bytes with AES-256-CBC. Returns IV + ciphertext."""
+    key = derive_key(passphrase)
+    iv = os.urandom(IV_LENGTH)
+    cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
+    encryptor = cipher.encryptor()
+    # PKCS7 padding
+    pad_len = 16 - (len(data) % 16)
+    padded = data + bytes([pad_len] * pad_len)
+    ciphertext = encryptor.update(padded) + encryptor.finalize()
+    return iv + ciphertext
+
+
+def decrypt_file(data: bytes, passphrase: str) -> bytes:
+    """Decrypt AES-256-CBC data (IV + ciphertext). Returns original bytes."""
+    key = derive_key(passphrase)
+    iv = data[:IV_LENGTH]
+    ciphertext = data[IV_LENGTH:]
+    cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+    padded = decryptor.update(ciphertext) + decryptor.finalize()
+    # Remove PKCS7 padding
+    pad_len = padded[-1]
+    return padded[:-pad_len]

parad-0.1.0/parad/engine.py

@@ -0,0 +1,143 @@
+"""Local encrypted SQLite engine for parad."""
+
+import os
+import sqlite3
+import tempfile
+from pathlib import Path
+from parad.crypto import encrypt_file, decrypt_file
+
+
+class Engine:
+    """Encrypted SQLite database engine.
+    
+    Decrypts the file to a temp location, operates on it,
+    then re-encrypts and writes back.
+    """
+
+    def __init__(self, db_path: str, passphrase: str):
+        self.db_path = Path(db_path).expanduser()
+        self.passphrase = passphrase
+        self._conn: sqlite3.Connection | None = None
+        self._tmp_path: str | None = None
+
+    def _decrypt_to_temp(self) -> str:
+        """Decrypt DB to a temp file, return path."""
+        if not self.db_path.exists():
+            raise FileNotFoundError(f"Database not found: {self.db_path}")
+        encrypted = self.db_path.read_bytes()
+        decrypted = decrypt_file(encrypted, self.passphrase)
+        tmp = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+        tmp.write(decrypted)
+        tmp.close()
+        self._tmp_path = tmp.name
+        return self._tmp_path
+
+    def _encrypt_from_temp(self):
+        """Encrypt temp file back to db_path."""
+        if not self._tmp_path:
+            return
+        decrypted = Path(self._tmp_path).read_bytes()
+        encrypted = encrypt_file(decrypted, self.passphrase)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.db_path.write_bytes(encrypted)
+
+    def open(self) -> sqlite3.Connection:
+        """Open the encrypted database."""
+        tmp_path = self._decrypt_to_temp()
+        self._conn = sqlite3.connect(tmp_path)
+        self._conn.row_factory = sqlite3.Row
+        return self._conn
+
+    def close(self):
+        """Close and re-encrypt."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+        self._encrypt_from_temp()
+        if self._tmp_path:
+            os.unlink(self._tmp_path)
+            self._tmp_path = None
+
+    def __enter__(self):
+        self.open()
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def execute(self, sql: str, params: tuple = ()) -> list[dict]:
+        """Execute SQL and return rows as dicts."""
+        if not self._conn:
+            raise RuntimeError("Database not open")
+        cursor = self._conn.execute(sql, params)
+        if cursor.description:
+            return [dict(row) for row in cursor.fetchall()]
+        self._conn.commit()
+        return []
+
+    def insert(self, table: str, data: dict) -> int:
+        """Insert a row, return rowid."""
+        cols = ", ".join(data.keys())
+        placeholders = ", ".join(["?"] * len(data))
+        sql = f"INSERT INTO {table} ({cols}) VALUES ({placeholders})"
+        cursor = self._conn.execute(sql, tuple(data.values()))
+        self._conn.commit()
+        return cursor.lastrowid
+
+    def update(self, table: str, set_data: dict, where: dict) -> int:
+        """Update rows, return changes count."""
+        set_clause = ", ".join(f"{k} = ?" for k in set_data)
+        where_clause = " AND ".join(f"{k} = ?" for k in where)
+        sql = f"UPDATE {table} SET {set_clause} WHERE {where_clause}"
+        params = tuple(set_data.values()) + tuple(where.values())
+        cursor = self._conn.execute(sql, params)
+        self._conn.commit()
+        return cursor.rowcount
+
+    def delete(self, table: str, where: dict) -> int:
+        """Delete rows, return changes count."""
+        where_clause = " AND ".join(f"{k} = ?" for k in where)
+        sql = f"DELETE FROM {table} WHERE {where_clause}"
+        cursor = self._conn.execute(sql, tuple(where.values()))
+        self._conn.commit()
+        return cursor.rowcount
+
+    def select(self, table: str, where: dict | None = None) -> list[dict]:
+        """Query rows."""
+        sql = f"SELECT * FROM {table}"
+        params = ()
+        if where:
+            where_clause = " AND ".join(f"{k} = ?" for k in where)
+            sql += f" WHERE {where_clause}"
+            params = tuple(where.values())
+        return self.execute(sql, params)
+
+    def get_raw_bytes(self) -> bytes:
+        """Get the encrypted database as raw bytes (for push)."""
+        if self._tmp_path:
+            return Path(self._tmp_path).read_bytes()
+        if self.db_path.exists():
+            encrypted = self.db_path.read_bytes()
+            return decrypt_file(encrypted, self.passphrase)
+        raise FileNotFoundError(f"Database not found: {self.db_path}")
+
+    def create_tables(self):
+        """Create default tables for a new database."""
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS _meta (
+                key TEXT PRIMARY KEY,
+                value TEXT
+            )
+        """)
+        self._conn.commit()
+
+    def list_tables(self) -> list[str]:
+        """List all user tables."""
+        rows = self.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '_%' ORDER BY name"
+        )
+        return [r["name"] for r in rows]
+
+    def table_info(self, table: str) -> list[dict]:
+        """Get column info for a table."""
+        return self.execute(f"PRAGMA table_info({table})")

parad-0.1.0/parad/gateway.py

@@ -0,0 +1,127 @@
+"""HTTP client for the Paradox-DB Gateway REST API."""
+
+import base64
+from pathlib import Path
+from parad.types import (
+    RegisterResponse,
+    UploadResponse,
+    StatusResponse,
+    VersionsResponse,
+    RollbackResponse,
+)
+
+
+class GatewayError(Exception):
+    """Gateway API error."""
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class GatewayClient:
+    """Client for the Paradox-DB Gateway REST API."""
+
+    def __init__(self, gateway_url: str, api_key: str = ""):
+        self.gateway_url = gateway_url.rstrip("/")
+        self.api_key = api_key
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["X-API-Key"] = self.api_key
+        return h
+
+    def register(self, channel_id: str, bot_token_id: str = "") -> RegisterResponse:
+        """Register a new user with the gateway."""
+        import httpx
+        resp = httpx.post(
+            f"{self.gateway_url}/auth/register",
+            json={"channel_id": channel_id, "bot_token_id": bot_token_id},
+            headers=self._headers(),
+            timeout=30,
+        )
+        if resp.status_code != 200:
+            raise GatewayError(resp.status_code, resp.text)
+        data = resp.json()
+        self.api_key = data.get("api_key", self.api_key)
+        return RegisterResponse(**data)
+
+    def upload(
+        self,
+        database_name: str,
+        file_bytes: bytes,
+        version: int = 0,
+        version_type: str = "full",
+    ) -> UploadResponse:
+        """Upload a database file to the gateway."""
+        import httpx
+        file_b64 = base64.b64encode(file_bytes).decode()
+        resp = httpx.post(
+            f"{self.gateway_url}/upload",
+            json={
+                "database_name": database_name,
+                "file_data": file_b64,
+                "version_type": version_type,
+                "version": version,
+            },
+            headers=self._headers(),
+            timeout=120,
+        )
+        if resp.status_code != 200:
+            raise GatewayError(resp.status_code, resp.text)
+        return UploadResponse(**resp.json())
+
+    def download(self, database_name: str, version: int | None = None) -> bytes:
+        """Download a database file from the gateway."""
+        import httpx
+        params = {"database_name": database_name}
+        if version is not None:
+            params["version"] = version
+        resp = httpx.get(
+            f"{self.gateway_url}/download",
+            params=params,
+            headers=self._headers(),
+            timeout=120,
+        )
+        if resp.status_code != 200:
+            raise GatewayError(resp.status_code, resp.text)
+        return resp.content
+
+    def status(self) -> StatusResponse:
+        """Get sync status from the gateway."""
+        import httpx
+        resp = httpx.get(
+            f"{self.gateway_url}/status",
+            headers=self._headers(),
+            timeout=30,
+        )
+        if resp.status_code != 200:
+            raise GatewayError(resp.status_code, resp.text)
+        return StatusResponse(**resp.json())
+
+    def versions(self, database_name: str) -> VersionsResponse:
+        """List all versions for a database."""
+        import httpx
+        resp = httpx.get(
+            f"{self.gateway_url}/versions",
+            params={"database_name": database_name},
+            headers=self._headers(),
+            timeout=30,
+        )
+        if resp.status_code != 200:
+            raise GatewayError(resp.status_code, resp.text)
+        return VersionsResponse(**resp.json())
+
+    def rollback(self, database_name: str, target_version: int) -> RollbackResponse:
+        """Rollback a database to a target version."""
+        import httpx
+        resp = httpx.post(
+            f"{self.gateway_url}/rollback",
+            json={"database_name": database_name, "target_version": target_version},
+            headers=self._headers(),
+            timeout=120,
+        )
+        if resp.status_code != 200:
+            raise GatewayError(resp.status_code, resp.text)
+        return RollbackResponse(**resp.json())

parad-0.1.0/parad/types.py

@@ -0,0 +1,85 @@
+"""Pydantic models for parad types."""
+
+from datetime import datetime
+from pydantic import BaseModel
+
+
+# ── Config ──────────────────────────────────────────────────────
+
+class EncryptionConfig(BaseModel):
+    cipher: str = "aes-256-cbc"
+    kdf_iterations: int = 256000
+    page_size: int = 4096
+
+
+class SyncConfig(BaseModel):
+    gateway_url: str = "https://paradox-db.onrender.com/v1"
+    api_key: str = ""
+    trigger_timer_seconds: int = 30
+    trigger_ops_threshold: int = 50
+    max_file_size_mb: int = 50
+    auto_sync_on_shutdown: bool = True
+
+
+class ConflictConfig(BaseModel):
+    strategy: str = "last-write-wins"
+    log_conflicts: bool = True
+
+
+class LoggingConfig(BaseModel):
+    level: str = "info"
+    path: str = "~/.paradox/logs"
+
+
+class Config(BaseModel):
+    database_path: str = "~/.paradox/data.db"
+    encryption: EncryptionConfig = EncryptionConfig()
+    sync: SyncConfig = SyncConfig()
+    conflict: ConflictConfig = ConflictConfig()
+    logging: LoggingConfig = LoggingConfig()
+
+
+# ── API Responses ───────────────────────────────────────────────
+
+class RegisterResponse(BaseModel):
+    user_id: str
+    api_key: str
+    jwt: str
+
+
+class UploadResponse(BaseModel):
+    request_id: str
+    message_id: str
+    version: int
+    uploaded_at: str
+
+
+class DatabaseStatus(BaseModel):
+    name: str
+    latest_version: int
+    latest_message_id: str
+    file_hash: str | None = None
+    uploaded_at: str | None = None
+
+
+class StatusResponse(BaseModel):
+    user_id: str
+    databases: list[DatabaseStatus] = []
+
+
+class VersionEntry(BaseModel):
+    version: int
+    message_id: str
+    file_hash: str | None = None
+    file_size: int | None = None
+    version_type: str | None = None
+    uploaded_at: str | None = None
+
+
+class VersionsResponse(BaseModel):
+    versions: list[VersionEntry] = []
+
+
+class RollbackResponse(BaseModel):
+    rolled_back_to: int
+    new_message_id: str

parad-0.1.0/parad.egg-info/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: parad
+Version: 0.1.0
+Summary: Encrypted local-first SQLite with Telegram cloud sync
+Author-email: nexuss0781 <nexuss0781@gmail.com>
+Project-URL: Homepage, https://github.com/nexuss0781/Paradox-DB
+Project-URL: Repository, https://github.com/nexuss0781/Paradox-DB
+Project-URL: Issues, https://github.com/nexuss0781/Paradox-DB/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pydantic>=2.0
+
+# parad
+
+Encrypted local-first SQLite with Telegram cloud sync.
+
+## Install
+
+```bash
+pip install parad
+```
+
+## Quick Start
+
+```bash
+# Create an encrypted database
+parad init mydb
+
+# Push to cloud
+parad push
+
+# Pull latest
+parad pull
+
+# Check status
+parad status
+
+# Interactive SQL
+parad shell
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `parad init <name>` | Create encrypted DB + register with gateway |
+| `parad push` | Push database to Telegram cloud |
+| `parad pull [version]` | Pull latest or specific version |
+| `parad sync` | Push then pull |
+| `parad status` | Local vs remote version |
+| `parad versions` | List all remote versions |
+| `parad rollback <ver>` | Rollback to previous version |
+| `parad exec <sql>` | Run raw SQL |
+| `parad insert <table> <json>` | Insert a row |
+| `parad select <table> [where]` | Query rows |
+| `parad update <table> <set> <where>` | Update rows |
+| `parad delete <table> <where>` | Delete rows |
+| `parad shell` | Interactive SQL REPL |
+| `parad config show/set` | Manage config |
+
+## Configuration
+
+Config lives at `~/.paradox/config.json`:
+
+```json
+{
+  "database_path": "~/.paradox/data.db",
+  "sync": {
+    "gateway_url": "https://paradox-db.onrender.com/v1",
+    "api_key": "pk_..."
+  }
+}
+```
+
+## Security
+
+- AES-256-CBC encryption at rest
+- PBKDF2-HMAC-SHA512 key derivation (256k iterations)
+- Your passphrase never leaves your machine

parad-0.1.0/parad.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+README.md
+pyproject.toml
+parad/__init__.py
+parad/__main__.py
+parad/cli.py
+parad/config.py
+parad/crypto.py
+parad/engine.py
+parad/gateway.py
+parad/types.py
+parad.egg-info/PKG-INFO
+parad.egg-info/SOURCES.txt
+parad.egg-info/dependency_links.txt
+parad.egg-info/entry_points.txt
+parad.egg-info/requires.txt
+parad.egg-info/top_level.txt
+parad/commands/__init__.py
+parad/commands/config_cmd.py
+parad/commands/init.py
+parad/commands/query.py
+parad/commands/shell.py
+parad/commands/status.py
+parad/commands/sync.py

parad-0.1.0/parad.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

parad-0.1.0/parad.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+parad = parad.cli:main

parad-0.1.0/parad.egg-info/requires.txt

@@ -0,0 +1,4 @@
+click>=8.0
+httpx>=0.25
+cryptography>=41.0
+pydantic>=2.0

parad-0.1.0/parad.egg-info/top_level.txt

@@ -0,0 +1 @@
+parad

parad-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "parad"
+version = "0.1.0"
+description = "Encrypted local-first SQLite with Telegram cloud sync"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "nexuss0781", email = "nexuss0781@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "click>=8.0",
+    "httpx>=0.25",
+    "cryptography>=41.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nexuss0781/Paradox-DB"
+Repository = "https://github.com/nexuss0781/Paradox-DB"
+Issues = "https://github.com/nexuss0781/Paradox-DB/issues"
+
+[project.scripts]
+parad = "parad.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["parad*"]

parad-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+