Metadata-Version: 2.4
Name: generate-gizmosql-token
Version: 1.1.0
Summary: A package which generates a GizmoSQL token (JWT) for auth testing
Author-email: Philip Moore <philip@gizmodata.com>
Project-URL: Homepage, https://github.com/gizmodata/generate-gizmosql-token
Keywords: gizmosql,auth,token,bearer,jwt
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click==8.2.*
Requires-Dist: pyjwt==2.10.*
Requires-Dist: cryptography==45.0.*
Requires-Dist: python-dotenv==1.1.*
Provides-Extra: dev
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: pip-tools; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: integration
Requires-Dist: gizmosql<2,>=1.26.0; extra == "integration"
Requires-Dist: adbc-driver-gizmosql; extra == "integration"
Requires-Dist: pyarrow; extra == "integration"

# Generate [GizmoSQL](https://gizmodata.com/gizmosql) (JWT) Token - by [GizmoData](https://gizmodata.com)™

[<img src="https://img.shields.io/badge/GitHub-gizmodata%2Fgenerate--gizmosql--token-blue.svg?logo=Github">](https://github.com/gizmodata/generate-gizmosql-token)
[![generate-gizmosql-token-ci](https://github.com/gizmodata/generate-gizmosql-token/actions/workflows/ci.yml/badge.svg)](https://github.com/gizmodata/generate-gizmosql-token/actions/workflows/ci.yml)
[![Supported Python Versions](https://img.shields.io/pypi/pyversions/generate-gizmosql-token)](https://pypi.org/project/generate-gizmosql-token/)
[![PyPI version](https://badge.fury.io/py/generate-gizmosql-token.svg)](https://badge.fury.io/py/generate-gizmosql-token)
[![PyPI Downloads](https://img.shields.io/pepy/dt/generate-gizmosql-token.svg)](https://pypi.org/project/generate-gizmosql-token/)

A utility for generating Bearer Authentication Tokens (Javascript Web Tokens - JWTs) for testing [GizmoSQL](https://github.com/gizmodata/gizmosql) (JWT) token authentication.

# Setup (to run locally)

## Install Python package
### from PyPi
```shell
# Create the virtual environment
python3 -m venv .venv

# Activate the virtual environment
. .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install the package
pip install generate-gizmosql-token
```

### from source - for development
```shell
git clone https://github.com/gizmodata/generate-gizmosql-token

cd generate-gizmosql-token

# Create the virtual environment
python3 -m venv .venv

# Activate the virtual environment
. .venv/bin/activate

# Upgrade pip, setuptools, and wheel
pip install --upgrade pip setuptools wheel

# Install the package (in editable mode)
pip install --editable .[dev]
```

### Note
For the following commands - if you are running from source and using `--editable` mode (for development purposes) - you will need to set the PYTHONPATH environment variable as follows:
```shell
export PYTHONPATH=$(pwd)/src
```

### Usage Example
```shell
generate-gizmosql-token \
  --issuer "GizmoData LLC" \
  --audience "GizmoSQL Server" \
  --subject "philip@summation.com" \
  --role "admin" \
  --token-lifetime-seconds 86400 \
  --output-file-format "output/gizmosql_token_{issuer}_{audience}_{subject}_{role}.jwt" \
  --private-key-file keys/summation_private_key.pem
```

> [!TIP]
> If you use: `--role "readonly"` - you can generate a token that has read-only privileges in GizmoSQL (for the DuckDB backend only)

### Catalog-Level Access Control
You can specify fine-grained catalog-level access controls using the `--catalog-access` option. This allows you to grant different access levels (none, read, write) to specific catalogs.

> [!IMPORTANT]
> Catalog-level access control requires **GizmoSQL Enterprise Edition** (version >= v1.15.0).
> This feature is not available in GizmoSQL Core.
> Contact [sales@gizmodata.com](mailto:sales@gizmodata.com) for Enterprise licensing information.

```shell
generate-gizmosql-token \
  --issuer "GizmoData LLC" \
  --audience "GizmoSQL Server" \
  --subject "philip@gizmodata.com" \
  --role "user" \
  --catalog-access '[{"catalog": "memory", "access": "write"}, {"catalog": "my_ducklake", "access": "none"}]' \
  --token-lifetime-seconds 86400 \
  --output-file-format "output/gizmosql_token_{issuer}_{audience}_{subject}_{role}.jwt" \
  --private-key-file keys/private_key.pem
```

**Access Levels:**
- `none` - No access to the catalog
- `read` - Read-only access (SELECT queries only)
- `write` - Full access (SELECT, INSERT, UPDATE, DELETE, DDL)

**Rules:**
- Rules are evaluated in order; **first match wins**
- The `catalog` field is matched using **AWS IAM-style glob patterns** (GizmoSQL Enterprise v1.27.0+):
  - `*` matches any sequence of characters (including none)
  - `?` matches exactly one character
  - A pattern with no wildcards matches the catalog name **exactly** (case-sensitive)
- So `"catalog": "*"` matches all catalogs, and `"catalog": "prod_*"` matches `prod_sales`, `prod_finance`, etc.
- If no `--catalog-access` is specified, full access is granted to all catalogs (backward compatible)

> [!NOTE]
> Wildcard matching is performed by the **GizmoSQL server**, not this generator. Patterns are written verbatim into the token's `catalog_access` claim, so this tool works with any pattern your server version supports.

**Example configurations:**

```shell
# Read-only access to everything
--catalog-access '[{"catalog": "*", "access": "read"}]'

# Write access to staging, read-only to everything else
--catalog-access '[{"catalog": "staging", "access": "write"}, {"catalog": "*", "access": "read"}]'

# Access only to specific catalogs, deny all others
--catalog-access '[{"catalog": "allowed_db", "access": "write"}, {"catalog": "*", "access": "none"}]'

# Wildcard: write to all prod_* catalogs, read all analytics_* catalogs, deny the rest
--catalog-access '[{"catalog": "prod_*", "access": "write"}, {"catalog": "analytics_*", "access": "read"}, {"catalog": "*", "access": "none"}]'
```

> [!NOTE]
> The `_gizmosql_instr` instrumentation database has special protection: only admin users can read it, and no one can write to it via client connections (it's system-managed). Token-based catalog_access rules do not override this protection

### Using the generated token with [GizmoSQL](https://github.com/gizmodata/gizmosql)

#### Server setup
In order to use the JWT generated by this package, you must start the GizmoSQL server using the public certificate associated with the private key you signed the JWT with using this utility.

Below is an example of starting the GizmoSQL server with TLS and JWT authentication enabled.

Please note - you MUST use the issuer, audience, and the public certificate that matches the private key you used to sign the JWT using this utility in order for the token to be accepted by the server.
```bash
gizmosql_server                                         \
   --database-filename data/tpch.db                     \
   --username gizmosql_user                             \
   --print-queries                                      \
   --tls tls/cert0.pem tls/cert0.key                    \
   --token-allowed-issuer "GizmoData LLC"               \
   --token-allowed-audience "GizmoSQL Server"           \
   --token-signature-verify-cert-path tls/jwt.pem       \
   --log-format json                                    \
   --access-log off                                     \
   --log-level info
```

#### JDBC
You can use the generated token with GizmoSQL via JDBC by using "token" as the username, and putting the JWT in the password value:
```text
jdbc:arrow-flight-sql://hostname:port?useEncryption=true&user=token&password=JWT_TOKEN_HERE&disableCertificateVerification=true
```

#### ADBC
You can use the generated token with GizmoSQL via ADBC using the [`adbc-driver-gizmosql`](https://pypi.org/project/adbc-driver-gizmosql/) package as follows - if you have set the environment variable `GIZMOSQL_TOKEN` to the generated token:
```python
import os

from adbc_driver_gizmosql import dbapi as gizmosql

token = os.getenv("GIZMOSQL_TOKEN")

with gizmosql.connect(
    "grpc+tls://localhost:31337",
    username="token",
    password=token,
    tls_skip_verify=True,
) as conn:
    with conn.cursor() as cur:
        print(f"Catalog: {conn.adbc_current_catalog}")
        print(f"Schema: {conn.adbc_current_db_schema}")

        cur.execute("SELECT * FROM region")
        x = cur.fetch_arrow_table()
        print(x)
```

### Handy development commands
#### Generate self-signed certificate and private key for testing purposes
There is a handy shell script (if you clone the repo) in [scripts/gen-certs.sh](scripts/gen-certs.sh) that you can use to generate a self-signed certificate and private key for testing purposes.   
```bash
scripts/gen-certs.sh
```

#### Running tests
The test suite uses [pytest](https://pytest.org) and is wired into CI. To run the unit tests locally (after installing with the `[dev]` extras):
```bash
pytest -v -m "not integration"
```

#### Running integration tests
The integration tests spin up a real GizmoSQL container (via Docker) configured with TLS + JWT auth, then verify that a token generated by this utility successfully authenticates against the server. They require Docker to be running locally, plus the `[integration]` extras:
```bash
pip install --editable ".[dev,integration]"

pytest -v -m integration
```

#### Version management

##### Bump the version of the application - (you must have installed from source with the [dev] extras)
```bash
bumpver update --patch
```
