Metadata-Version: 2.4
Name: gcl_iam
Version: 1.4.0
Author-email: Genesis Corporation <eugene@frolov.net.ru>
License: Apache-2.0
Project-URL: homepage, https://github.com/infraguys/gcl_iam/
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bazooka<2.0.0,>=1.1.0
Requires-Dist: restalchemy<17.0.0,>=16.0.1
Requires-Dist: izulu<1.0.0,>=0.50.0
Requires-Dist: pyjwt<3.0.0,>=2.9.0
Requires-Dist: cryptography<50.0.0,>=45.0.5
Provides-Extra: dev
Requires-Dist: tox>=4.0.0; extra == "dev"
Requires-Dist: tox-uv; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: coverage>=4.0; extra == "test"
Requires-Dist: mock<4.0.0,>=3.0.5; extra == "test"
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "test"
Requires-Dist: pytest-xdist[psutil]<4.0.0,>=3.6.1; extra == "test"
Requires-Dist: pytest-timer<2.0.0,>=1.0.0; extra == "test"
Provides-Extra: mypy
Requires-Dist: mypy; extra == "mypy"
Provides-Extra: ruff
Requires-Dist: ruff; extra == "ruff"
Provides-Extra: shellcheck
Requires-Dist: shellcheck-py; extra == "shellcheck"
Dynamic: license-file

# gcl_iam

`gcl_iam` is a Python library for adding JWT authentication and policy-based
authorization to RESTAlchemy services. It provides:

- HS256 and RS256 token verification, including previous-key fallback during
  key rotation;
- remote JWKS discovery and token introspection through an IAM service;
- request-scoped identity, project and permission data;
- wildcard permissions in the `service.resource.action` format;
- project-aware, nested, projectless and OTP-aware RESTAlchemy controllers;
- permission-driven field visibility; and
- OAuth-style HTTP error responses.

The library requires Python 3.10 or newer and is licensed under Apache 2.0.

## Documentation

The complete documentation is available in four languages. Every language has
the same files, section order and code examples:

- [English](docs/en/index.md)
- [Русский](docs/ru/index.md)
- [Deutsch](docs/de/index.md)
- [中文](docs/zh/index.md)

New users should start with [installation](docs/en/installation.md) and the
[getting-started guide](docs/en/getting-started.md).

## Quick example

```python
from gcl_iam import drivers
from gcl_iam import middlewares as iam_middlewares
from restalchemy.api import middlewares

iam_driver = drivers.HttpDriver(
    iam_endpoint="https://iam.example.com/v1/iam/clients/my-service",
    audience="my-service",
    hs256_jwks_decryption_key="<32-byte A256GCM key>",
)

application = middlewares.attach_middlewares(
    application,
    [
        middlewares.configure_middleware(
            iam_middlewares.GenesisCoreAuthMiddleware,
            iam_engine_driver=iam_driver,
        ),
        iam_middlewares.ErrorsHandlerMiddleware,
    ],
)
```

Use real secret management for IAM credentials and encryption keys. Never put
them in source code.

## Development

Create the standard development environment and run the unit tests:

```bash
tox -e develop
tox -e py310
```

Additional checks are available as `tox -e ruff-check` and `tox -e mypy`.
