parad 2.2.3__tar.gz → 2.2.6__tar.gz

{parad-2.2.3 → parad-2.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parad
-Version: 2.2.3
+Version: 2.2.6
 Summary: Drop-in encrypted database with cloud sync — connect() and go
 Author-email: nexuss0781 <nexuss0781@gmail.com>
 Project-URL: Homepage, https://github.com/nexuss0781/Paradox-DB
@@ -46,9 +46,9 @@ sync daemon version-stores your changes automatically. No manual push needed.
 ```python
 from parad import connect
 
-# Auto-login (email:password), auto-provision project + database on the
-# gateway, open/create the local encrypted SQLite file.
-db = connect(url="parad://alice@example.com:secretpw@local/myproj/mydb?passphrase=secret")
+# Exchange a Nexuss API key once for a Paradox key, then use the Paradox key
+# in the connection URL to auto-provision the project and database.
+db = connect(url="parad://pk_example@local/myproj/mydb?passphrase=secret")
 
 # Build SQL offline like any SQLite database ...
 db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
@@ -75,10 +75,15 @@ db = connect("mydb", passphrase="secret", auto_sync=False)
 ### CLI
 
 ```bash
-# Create an encrypted database
-parad init mydb
-
+# Create a new encrypted database and print the canonical URL deliberately
+parad auth login --api-key "$PARADOX_API_KEY"
+parad init mydb --project myproject --print-database-url
+# Retrieve the existing canonical URL; local values are checked first,
+# then the owner-authenticated gateway recovery endpoint is used
+parad url
+parad url --print-database-url
 # Push to cloud
+
 parad push
 
 # Pull latest
@@ -108,32 +113,43 @@ parad shell
 | `parad update <table> <set> <where>` | Update rows |
 | `parad delete <table> <where>` | Delete rows |
 | `parad shell` | Interactive SQL REPL |
-| `parad config show/set` | Manage config |
-
-## Canonical DATABASE_URL
-
-After `parad init` successfully provisions the project and database, Parad persists the complete connection URL in `config.json` as `database_url` and prints a redacted form:
-
+| `parad config show/set` | Manage config; secret-bearing fields are redacted |
+| `parad url [name]` | Retrieve the canonical database_url using local values, owner-authenticated server recovery, then legacy fallback |
+| `parad url register <url>` | Explicitly store a known canonical URL on the gateway without snapshot mutation |
+| `parad database-url [name]` | Alias for `parad url` |
+## Canonical DATABASE_URL first
+Use one canonical connection value for new applications and deployments. After `parad init` provisions the project/database, it persists `database_url` in `~/.paradox/config.json` and prints a redacted URL by default:
 ```bash
+parad auth login --api-key "$PARADOX_API_KEY"
 parad init mydb --project myproject
 ```
-
-Use `--print-database-url` only when intentionally copying the complete secret-bearing URL into a secret manager:
-
+Print the complete secret-bearing value only when intentionally copying it into a secret manager:
 ```bash
 parad init mydb --project myproject --print-database-url
 ```
+For an existing database, retrieve the saved canonical value. If local values are unavailable, the CLI resolves the owned project/database and calls the read-only owner-authenticated gateway recovery endpoint:
+```bash
+parad url
+parad url --print-database-url
+```
+Retrieval checks `DATABASE_URL`, then persisted `database_url`, then server recovery, then reconstructs and persists a canonical URL from legacy split fields when a passphrase is available. Project-scoped connections register the canonical URL with the gateway, which stores it encrypted at rest. The full value is returned only with `--print-database-url`; ordinary output is redacted. If the server has no stored URL and the passphrase is missing, it stops instead of inventing a replacement. New projects should use only `DATABASE_URL`; split fields remain supported for legacy applications.
 
+For a database created before server URL storage existed, provide the already-known URL once with `parad url register '<url>'`. This updates only the encrypted server field; it does not run `init`, push, pull, or overwrite snapshots. A URL that was never previously stored cannot be recovered from server metadata alone.
 Applications can use the same single value:
-
 ```python
 import os
 from parad import connect
-
 db = connect(url=os.environ["DATABASE_URL"])
 ```
 
-An explicit `url`, `name`, or `db_path` argument takes precedence over an ambient `DATABASE_URL`. Existing connection strings and config-based workflows remain supported.
+For a pre-feature database whose canonical URL is already known, register it explicitly without opening or syncing the database:
+```python
+from parad import register_canonical_database_url
+register_canonical_database_url(os.environ["DATABASE_URL"])
+```
+
+An explicit `url` argument is strongest. Explicit `name` or `db_path` options remain available for legacy target selection.
+
 
 ## SQLAlchemy
 
@@ -156,6 +172,8 @@ Config lives at `~/.paradox/config.json`:
 
 ## Security
 
+The gateway stores the canonical `database_url` encrypted at rest in `paradox_dbs.database_url_encrypted`. Set a stable `DATABASE_URL_ENCRYPTION_KEY` on the gateway. The redacted endpoint is safe for metadata checks; full recovery requires the owner API key and an explicit reveal command.
+
 - AES-256-CBC encryption at rest
 - PBKDF2-HMAC-SHA512 key derivation (256k iterations)
 - Your passphrase never leaves your machine

parad-2.2.6/README.md

@@ -0,0 +1,153 @@
+# parad
+
+Encrypted local-first SQLite with Telegram cloud sync — a git-like, zero-cost
+workflow database. Telegram is the disk: every change you commit becomes a
+version-stored snapshot you can revert to anytime.
+
+## Install
+
+```bash
+pip install parad
+```
+
+## Quick Start
+
+### Python SDK (developer workflow — auto-sync on by default)
+
+Connect with a postgres-like connection string, write SQL offline, and the
+sync daemon version-stores your changes automatically. No manual push needed.
+
+```python
+from parad import connect
+
+# Exchange a Nexuss API key once for a Paradox key, then use the Paradox key
+# in the connection URL to auto-provision the project and database.
+db = connect(url="parad://pk_example@local/myproj/mydb?passphrase=secret")
+
+# Build SQL offline like any SQLite database ...
+db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
+db.execute("INSERT INTO users (name) VALUES (?)", ("alice",))
+db.commit()
+
+# ... and it's already pushed to the cloud as a new snapshot version (~2s).
+# Revert anytime (from the CLI):
+# !parad rollback 1
+
+db.close()
+```
+
+Offline? Keep writing — changes are flagged `dirty` and batch-pushed as new
+versions the moment you reconnect. On conflicts your local data always wins
+(never silently dropped).
+
+Local-only is just as easy:
+
+```python
+db = connect("mydb", passphrase="secret", auto_sync=False)
+```
+
+### CLI
+
+```bash
+# Create a new encrypted database and print the canonical URL deliberately
+parad auth login --api-key "$PARADOX_API_KEY"
+parad init mydb --project myproject --print-database-url
+# Retrieve the existing canonical URL; local values are checked first,
+# then the owner-authenticated gateway recovery endpoint is used
+parad url
+parad url --print-database-url
+# 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; emit canonical DATABASE_URL |
+| `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; secret-bearing fields are redacted |
+| `parad url [name]` | Retrieve the canonical database_url using local values, owner-authenticated server recovery, then legacy fallback |
+| `parad url register <url>` | Explicitly store a known canonical URL on the gateway without snapshot mutation |
+| `parad database-url [name]` | Alias for `parad url` |
+## Canonical DATABASE_URL first
+Use one canonical connection value for new applications and deployments. After `parad init` provisions the project/database, it persists `database_url` in `~/.paradox/config.json` and prints a redacted URL by default:
+```bash
+parad auth login --api-key "$PARADOX_API_KEY"
+parad init mydb --project myproject
+```
+Print the complete secret-bearing value only when intentionally copying it into a secret manager:
+```bash
+parad init mydb --project myproject --print-database-url
+```
+For an existing database, retrieve the saved canonical value. If local values are unavailable, the CLI resolves the owned project/database and calls the read-only owner-authenticated gateway recovery endpoint:
+```bash
+parad url
+parad url --print-database-url
+```
+Retrieval checks `DATABASE_URL`, then persisted `database_url`, then server recovery, then reconstructs and persists a canonical URL from legacy split fields when a passphrase is available. Project-scoped connections register the canonical URL with the gateway, which stores it encrypted at rest. The full value is returned only with `--print-database-url`; ordinary output is redacted. If the server has no stored URL and the passphrase is missing, it stops instead of inventing a replacement. New projects should use only `DATABASE_URL`; split fields remain supported for legacy applications.
+
+For a database created before server URL storage existed, provide the already-known URL once with `parad url register '<url>'`. This updates only the encrypted server field; it does not run `init`, push, pull, or overwrite snapshots. A URL that was never previously stored cannot be recovered from server metadata alone.
+Applications can use the same single value:
+```python
+import os
+from parad import connect
+db = connect(url=os.environ["DATABASE_URL"])
+```
+
+For a pre-feature database whose canonical URL is already known, register it explicitly without opening or syncing the database:
+```python
+from parad import register_canonical_database_url
+register_canonical_database_url(os.environ["DATABASE_URL"])
+```
+
+An explicit `url` argument is strongest. Explicit `name` or `db_path` options remain available for legacy target selection.
+
+
+## SQLAlchemy
+
+Install the optional integration with `pip install "parad[sqlalchemy]"`, then use the same canonical URL with `create_engine("parad://...")`. The ORM, Core, DB-API, and encrypted lifecycle examples are documented in [`docs/SQLALCHEMY.md`](docs/SQLALCHEMY.md).
+
+## Configuration
+
+Config lives at `~/.paradox/config.json`:
+
+```json
+{
+  "database_url": "parad://<api-key>@local/project/mydb?gateway=https%3A%2F%2F...&passphrase=...",
+  "database_path": "~/.paradox/data.db",
+  "sync": {
+    "gateway_url": "https://paradox-db.onrender.com/v1",
+    "api_key": "pk_..."
+  }
+}
+```
+
+## Security
+
+The gateway stores the canonical `database_url` encrypted at rest in `paradox_dbs.database_url_encrypted`. Set a stable `DATABASE_URL_ENCRYPTION_KEY` on the gateway. The redacted endpoint is safe for metadata checks; full recovery requires the owner API key and an explicit reveal command.
+
+- AES-256-CBC encryption at rest
+- PBKDF2-HMAC-SHA512 key derivation (256k iterations)
+- Your passphrase never leaves your machine

{parad-2.2.3 → parad-2.2.6}/parad/__init__.py

@@ -2,7 +2,7 @@
 
 from parad.connection import connect, ParadConnection, parse_url, generate_url, redact_url, db_state_key, generate_passphrase
 from parad.engine import Engine
-from parad.config import load_config, get_passphrase, get_connection_url
+from parad.config import load_config, get_passphrase, get_canonical_database_url, recover_canonical_database_url, register_canonical_database_url, get_connection_url
 
-__version__ = "2.2.3"
-__all__ = ["connect", "ParadConnection", "parse_url", "generate_url", "redact_url", "db_state_key", "generate_passphrase", "Engine", "load_config"]
+__version__ = "2.2.6"
+__all__ = ["connect", "ParadConnection", "parse_url", "generate_url", "redact_url", "db_state_key", "generate_passphrase", "Engine", "load_config", "get_passphrase", "get_canonical_database_url", "recover_canonical_database_url", "register_canonical_database_url", "get_connection_url"]

{parad-2.2.3 → parad-2.2.6}/parad/cli.py

@@ -24,6 +24,7 @@ from parad.commands.projects import project_group
 from parad.commands.databases import db_group
 from parad.commands.versions import version_group
 from parad.commands.backups import backup_group
+from parad.commands.url import url_command, database_url_command
 
 main.add_command(connect)
 main.add_command(init)
@@ -46,3 +47,5 @@ main.add_command(project_group)
 main.add_command(db_group)
 main.add_command(version_group)
 main.add_command(backup_group)
+main.add_command(url_command)
+main.add_command(database_url_command)

parad-2.2.6/parad/commands/auth.py

@@ -0,0 +1,110 @@
+"""parad auth — authenticate with Paradox or Nexuss Auth API keys."""
+
+import click
+from click import ClickException
+from parad.config import load_config, save_config, set_config_value
+from parad.gateway import GatewayClient, GatewayError
+
+
+@click.group("auth")
+def auth_group():
+    """Manage authentication."""
+    pass
+
+
+def authenticate_api_key(config, api_key: str) -> tuple[GatewayClient, dict]:
+    """Validate a Paradox key or exchange a Nexuss key without persisting nxa_."""
+    supplied = api_key.strip()
+    if not supplied:
+        raise ClickException("Provide a Paradox pk_ key or a Nexuss Auth nxa_ key")
+    gateway = GatewayClient(config.sync.gateway_url)
+    if supplied.startswith("nxa_"):
+        result = gateway.exchange_nexuss_api_key(supplied)
+        resolved_key = result.get("api_key", "")
+        if not resolved_key.startswith("pk_"):
+            raise ClickException("Nexuss Auth exchange did not return a Paradox API key")
+        gateway.api_key = resolved_key
+    else:
+        gateway.api_key = supplied
+        result = {"api_key": supplied, **gateway.get_me()}
+    set_config_value("sync.api_key", gateway.api_key)
+    config.sync.api_key = gateway.api_key
+    return gateway, result
+
+
+@auth_group.command("register")
+def register():
+    """Explain the passwordless Nexuss Auth registration flow."""
+    raise ClickException(
+        "Paradox accounts are created through Nexuss Auth. Sign in with Google in the Paradox web flow, "
+        "then run 'parad auth login --api-key <nexuss nxa_ key>'."
+    )
+
+
+@auth_group.command("login")
+@click.option("--api-key", envvar="PARADOX_API_KEY", help="Paradox pk_ key or Nexuss Auth nxa_ key")
+def login(api_key: str | None):
+    """Authenticate using a Paradox key or exchange a Nexuss Auth key."""
+    config = load_config()
+    supplied = api_key or click.prompt("Paradox or Nexuss API key", hide_input=True)
+    try:
+        _, result = authenticate_api_key(config, supplied)
+        click.echo(f"✓ Logged in as {result.get('username', '')}")
+    except GatewayError as e:
+        click.echo(f"✗ Login failed: {e}")
+        raise SystemExit(1)
+
+
+def _ensure_auth(gw):
+    """Ensure user is authenticated. Prompt for an API key if needed.
+
+    In non-interactive mode (CI/cloud), raises an error instead of prompting.
+    """
+    if gw.api_key:
+        try:
+            gw.get_me()
+            return
+        except GatewayError:
+            pass
+
+    # Non-interactive mode: raise clear error
+    import sys
+    if not sys.stdin.isatty():
+        raise ClickException(
+            "Not authenticated. Set PARADOX_API_KEY environment variable or run 'parad auth login' first."
+        )
+
+    click.echo("Authentication required.")
+    api_key = click.prompt("Paradox or Nexuss API key", hide_input=True)
+
+    try:
+        config = load_config()
+        resolved, _ = authenticate_api_key(config, api_key)
+        gw.api_key = resolved.api_key
+        if gw.api_key:
+            click.echo("✓ Authentication successful")
+        else:
+            raise ClickException("Authentication succeeded but no Paradox API key was received")
+    except GatewayError as e:
+        raise ClickException(f"Authentication failed: {e}")
+
+
+def _require_auth(gw):
+    """Require authentication. Raises ClickException if auth fails."""
+    _ensure_auth(gw)
+
+
+@auth_group.command("status")
+def auth_status():
+    """Show current authentication status."""
+    config = load_config()
+    if not config.sync.api_key:
+        click.echo("Not logged in.")
+        return
+    gw = GatewayClient(config.sync.gateway_url, config.sync.api_key)
+    try:
+        me = gw.get_me()
+        click.echo(f"Logged in as: {me.get('username', 'unknown')} ({me.get('email', '')})")
+        click.echo(f"User ID: {me.get('id', 'unknown')}")
+    except GatewayError:
+        click.echo("API key invalid. Run: parad auth login")

parad-2.2.6/parad/commands/config_cmd.py

@@ -0,0 +1,32 @@
+"""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 with secret-bearing fields redacted."""
+    import json
+
+    config = load_config().model_dump()
+    config["database_url"] = "<redacted>" if config.get("database_url") else ""
+    config.setdefault("encryption", {})["passphrase"] = "<redacted>" if config.get("encryption", {}).get("passphrase") else ""
+    config.setdefault("sync", {})["api_key"] = "<redacted>" if config.get("sync", {}).get("api_key") else ""
+    click.echo(json.dumps(config, 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)
+    shown = "<redacted>" if any(part.lower() in {"database_url", "api_key", "passphrase", "password", "token"} for part in key.split(".")) else value
+    click.echo(f"✓ Set {key} = {shown}")

{parad-2.2.3 → parad-2.2.6}/parad/commands/connect.py

@@ -6,12 +6,13 @@ from parad.config import load_config, save_config, config_dir, gateway_db_name,
 from parad.connection import db_state_key
 from parad.engine import Engine
 from parad.gateway import GatewayClient, GatewayError
+from parad.commands.auth import authenticate_api_key
 from parad.state import get_remote_version, set_remote_version, set_last_local_hash
 from parad.watcher import is_running, get_daemon_pid, start_daemon
 
 
 def _ensure_auth(config):
-    """Auto-authenticate: prompt for credentials if no valid token.
+    """Auto-authenticate: prompt for an API key if no valid token.
 
     In non-interactive mode (CI/cloud), raises an error instead of prompting.
     """
@@ -32,18 +33,16 @@ def _ensure_auth(config):
         )
 
     click.echo("Authentication required.")
-    email = click.prompt("Email")
-    password = click.prompt("Password", hide_input=True)
+    api_key = click.prompt("Paradox or Nexuss API key", hide_input=True)
 
     try:
-        result = gw.login(email, password)
-        token = result.get("access_token") or result.get("api_key")
-        if token:
-            set_config_value("sync.api_key", token)
-            config.sync.api_key = token
+        resolved, _ = authenticate_api_key(config, api_key)
+        gw.api_key = resolved.api_key
+        if gw.api_key:
+            config.sync.api_key = gw.api_key
             click.echo("✓ Authentication successful")
         else:
-            raise click.ClickException("Login succeeded but no token received")
+            raise click.ClickException("Authentication succeeded but no Paradox API key was received")
     except GatewayError as e:
         raise click.ClickException(f"Authentication failed: {e}")
 

{parad-2.2.3 → parad-2.2.6}/parad/commands/init.py

@@ -6,12 +6,13 @@ from parad.config import load_config, save_config, config_dir, gateway_db_name,
 from parad.connection import db_state_key, generate_url, redact_url
 from parad.engine import Engine
 from parad.gateway import GatewayClient, GatewayError
+from parad.commands.auth import authenticate_api_key
 from parad.state import set_remote_version, set_last_local_hash
 from parad.watcher import is_running
 
 
 def _ensure_auth(config):
-    """Auto-authenticate: prompt for credentials if no valid token.
+    """Auto-authenticate: prompt for an API key if no valid token.
 
     In non-interactive mode (CI/cloud), raises an error instead of prompting.
     """
@@ -32,18 +33,16 @@ def _ensure_auth(config):
         )
 
     click.echo("Authentication required.")
-    email = click.prompt("Email")
-    password = click.prompt("Password", hide_input=True)
+    api_key = click.prompt("Paradox or Nexuss API key", hide_input=True)
 
     try:
-        result = gw.login(email, password)
-        token = result.get("access_token") or result.get("api_key")
-        if token:
-            set_config_value("sync.api_key", token)
-            config.sync.api_key = token
+        resolved, _ = authenticate_api_key(config, api_key)
+        gw.api_key = resolved.api_key
+        if gw.api_key:
+            config.sync.api_key = gw.api_key
             click.echo("✓ Authentication successful")
         else:
-            raise click.ClickException("Login succeeded but no token received")
+            raise click.ClickException("Authentication succeeded but no Paradox API key was received")
     except GatewayError as e:
         raise click.ClickException(f"Authentication failed: {e}")
 

parad-2.2.6/parad/commands/url.py

@@ -0,0 +1,62 @@
+"""Canonical database URL retrieval commands."""
+
+import json
+
+import click
+
+from parad.config import recover_canonical_database_url, register_canonical_database_url
+from parad.connection import redact_url
+
+
+def _emit_url(name: str | None, print_database_url: bool, json_mode: bool) -> None:
+    database_url = recover_canonical_database_url(name)
+    displayed = database_url if print_database_url else redact_url(database_url)
+    if json_mode:
+        click.echo(json.dumps({"database_url": displayed}))
+    else:
+        click.echo(f"DATABASE_URL: {displayed}")
+
+
+def _register_url(database_url: str, print_database_url: bool, json_mode: bool) -> None:
+    registered = register_canonical_database_url(database_url)
+    displayed = registered if print_database_url else redact_url(registered)
+    if json_mode:
+        click.echo(json.dumps({"registered": True, "database_url": displayed}))
+    else:
+        click.echo(f"Registered DATABASE_URL: {displayed}")
+
+
+def _handle_url_command(
+    name: str | None,
+    database_url: str | None,
+    print_database_url: bool,
+    json_mode: bool,
+) -> None:
+    if name == "register":
+        if not database_url:
+            raise click.UsageError("Usage: parad url register <canonical-url>")
+        _register_url(database_url, print_database_url, json_mode)
+        return
+    if database_url:
+        raise click.UsageError("Only `register` accepts a second argument")
+    _emit_url(name, print_database_url, json_mode)
+
+
+@click.command("url")
+@click.argument("name", required=False)
+@click.argument("database_url", required=False)
+@click.option("--print-database-url", is_flag=True, help="Print the full secret-bearing DATABASE_URL")
+@click.option("--json", "json_mode", is_flag=True, help="Print JSON output")
+def url_command(name: str | None, database_url: str | None, print_database_url: bool, json_mode: bool) -> None:
+    """Retrieve or explicitly register the canonical database_url."""
+    _handle_url_command(name, database_url, print_database_url, json_mode)
+
+
+@click.command("database-url")
+@click.argument("name", required=False)
+@click.argument("database_url", required=False)
+@click.option("--print-database-url", is_flag=True, help="Print the full secret-bearing DATABASE_URL")
+@click.option("--json", "json_mode", is_flag=True, help="Print JSON output")
+def database_url_command(name: str | None, database_url: str | None, print_database_url: bool, json_mode: bool) -> None:
+    """Alias for ``parad url``."""
+    _handle_url_command(name, database_url, print_database_url, json_mode)