Metadata-Version: 2.4
Name: semql-auth
Version: 0.4.0
Summary: Credential→identity adapters for semql: bearer-token verifiers (HMAC, JWKS, introspection) and mappers (dict, mTLS x509) that produce a semql AuthContext.
Author: Nikhil Pallamreddy
Author-email: Nikhil Pallamreddy <nikhil.pallamreddy+git@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: semql>=0.4.0,<0.5
Requires-Dist: httpx>=0.27 ; extra == 'introspect'
Requires-Dist: pyjwt[crypto]>=2.8 ; extra == 'jwks'
Requires-Dist: httpx>=0.27 ; extra == 'jwks'
Requires-Dist: cryptography>=42 ; extra == 'x509'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/npalladium/semql
Project-URL: Repository, https://github.com/npalladium/semql
Project-URL: Issues, https://github.com/npalladium/semql/issues
Provides-Extra: introspect
Provides-Extra: jwks
Provides-Extra: x509
Description-Content-Type: text/markdown

# semql-auth

Credential→identity adapters for [semql](https://github.com/npalladium/semql).

`semql` threads an `AuthContext` (identity + roles) through
`Catalog.compile(viewer=...)` to enforce `required_roles` cube/field
visibility and `security_sql` row-level scoping. This package turns a
transport credential into that `AuthContext`:

- **`TokenVerifier`** — verify a bearer token and return its claims.
  - `HMACVerifier` — symmetric HS256/384/512.
  - `JWKSVerifier` — asymmetric RS/ES, fetching keys from a JWKS URL
    (needs the `jwks` extra: `pip install semql-auth[jwks]`).
- **`TokenMapper`** — map a verified credential to an `AuthContext`.
  - `DictMapper` — static, in-memory `token → AuthContext` table.
  - `IntrospectMapper` — OAuth2 token introspection (`introspect` extra).
  - `X509Mapper` — derive identity from an mTLS client cert subject / SAN
    (the reference cryptography decoder needs the `x509` extra).

`AuthContext` itself lives in `semql.model` — the compiler depends on it,
so it stays in the pure core. This package holds only the adapters, which
carry optional third-party dependencies (PyJWT, httpx, cryptography) that
the core shouldn't.

## Install

```sh
pip install semql-auth
pip install semql-auth[jwks]        # JWKS verifier (httpx)
pip install semql-auth[introspect]  # OAuth2 introspection
pip install semql-auth[x509]        # mTLS client cert decoder
```

## Quick start

```python
from semql import Catalog
from semql_auth import HMACVerifier, DictMapper

verifier = HMACVerifier(secret="...")
mapper = DictMapper({"tok-abc": ...})
# In your transport: verify the token, map to AuthContext, then
#   catalog.compile(query, viewer=auth_context)
```

See [API reference](../../docs/api/semql_auth.md) for the full adapter
surface.

## License

BSD-3-Clause.
