Metadata-Version: 2.4
Name: auth
Version: 0.10.3
Summary: Authorization for humans
Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
License-Expression: Apache-2.0
Keywords: authorization,role,auth,groups,membership,ensure,ldap
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: flask>=2.0.0
Requires-Dist: flask-cors>=3.0.0
Requires-Dist: sqlalchemy>=1.4.0
Requires-Dist: waitress>=2.0.0
Requires-Dist: PyJWT>=2.0.0
Requires-Dist: cryptography>=3.0.0
Requires-Dist: APScheduler>=3.0.0
Requires-Dist: psycopg3[binary]>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: ruff>=0.0.260; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Dynamic: license-file

Auth | Enterprise Authorization System
======================================

A comprehensive, production-ready authorization system with role-based access control, audit logging, encryption, and high availability features.

**📚 For detailed documentation, see the project repository.**

**✅ Fully Tested:** 152/152 tests passing (100% pass rate)

Features
--------
**Core Features:**

- Role-based access control (RBAC) with hierarchical permissions
- Multiple storage backends (SQLite for development, PostgreSQL for production)
- Dual interface: REST API and Python library
- JWT-based authentication and authorization
- Optional field-level encryption for sensitive data
- Comprehensive audit logging for security compliance
- Workflow permission checking with APScheduler

**Security Features:**

- UUID4-based client authentication
- JWT token-based authorization
- Field-level encryption with Fernet
- Input validation and sanitization
- Configurable CORS settings

**Production Features:**

- Connection pooling with retry logic
- Circuit breaker pattern for fault tolerance
- Health check endpoint
- Consistent API response formats
- Extensive test coverage

Requirements
------------
- Python 3.9+
- PostgreSQL (for production) or SQLite (for development/testing)

Installation
------------
.. code:: bash

    pip install -r requirements.txt

Quick Start
-----------
**Start the server** (default SQLite on port 4000):

.. code:: bash

    python -m auth.main

**Test the API:**

.. code:: bash

    bash showcase_api.sh

Production Deployment
---------------------
For production with PostgreSQL:

.. code:: bash

    export AUTH_DB_TYPE=postgresql
    export POSTGRESQL_URL=postgresql://user:pass@localhost:5432/authdb
    export JWT_SECRET_KEY=your-secret-key
    export ENABLE_ENCRYPTION=true
    export ENCRYPTION_KEY=your-encryption-key

    # Using Waitress (recommended)
    pip install waitress
    waitress-serve --host=0.0.0.0 --port=4000 --threads=10 auth.main:app

    # Or using Gunicorn
    pip install gunicorn
    gunicorn -w 4 -b 0.0.0.0:4000 auth.main:app

Python Library Usage
--------------------
.. code:: python

    import uuid
    from auth import Authorization

    # Create authorization instance
    client_key = str(uuid.uuid4())
    auth = Authorization(client_key)

    # Create roles and permissions
    auth.add_role('admin', 'Administrator role')
    auth.add_permission('admin', 'manage_users')

    # Add user to role
    auth.add_membership('alice@example.com', 'admin')

    # Check permission
    if auth.user_has_permission('alice@example.com', 'manage_users'):
        print("Alice can manage users")

For detailed Python examples, see the project documentation.

REST API Usage
--------------
.. code:: bash

    # Generate client key
    CLIENT_KEY=$(uuidgen)

    # Create role
    curl -X POST \
      -H "Authorization: Bearer $CLIENT_KEY" \
      http://localhost:4000/api/role/admin

    # Add permission
    curl -X POST \
      -H "Authorization: Bearer $CLIENT_KEY" \
      http://localhost:4000/api/permission/admin/manage_users

    # Check user permission
    curl -X GET \
      -H "Authorization: Bearer $CLIENT_KEY" \
      http://localhost:4000/api/has_permission/alice@example.com/manage_users

For complete API reference, see the project documentation.

Key Endpoints
-------------
- ``GET /ping`` - Health check
- ``POST /api/role/{role}`` - Create role
- ``POST /api/permission/{role}/{name}`` - Add permission to role
- ``POST /api/membership/{user}/{role}`` - Add user to role
- ``GET /api/has_permission/{user}/{name}`` - Check user permission
- ``GET /api/user_permissions/{user}`` - Get all user permissions
- ``GET /api/which_users_can/{name}`` - Find users with permission

*See the project documentation for complete endpoint details*

Configuration
-------------
Environment variables (or use .env file):

- ``AUTH_DB_TYPE`` - Database type (sqlite or postgresql) [default: sqlite]
- ``POSTGRESQL_URL`` - PostgreSQL connection string
- ``SQLITE_PATH`` - SQLite database path [default: ~/.auth.sqlite3]
- ``JWT_SECRET_KEY`` - Secret key for JWT tokens
- ``ENABLE_ENCRYPTION`` - Enable data encryption [default: false]
- ``ENCRYPTION_KEY`` - Encryption key [required if encryption enabled]
- ``SERVER_HOST`` - Server host [default: 0.0.0.0]
- ``SERVER_PORT`` - Server port [default: 4000]
- ``ALLOW_CORS`` - Enable CORS [default: true]
- ``CORS_ORIGINS`` - Allowed CORS origins [default: \*]

Testing
-------
Run the complete test suite:

.. code:: bash

    # All tests (152 tests)
    python -m pytest tests/ -v

    # With coverage
    python -m pytest tests/ --cov=auth --cov-report=html

    # Run showcase script
    bash showcase_api.sh

Architecture
------------
The system follows a layered architecture:

- **API Layer:** Flask-based REST endpoints with validation
- **Service Layer:** Business logic with authorization rules
- **Data Access Layer:** SQLAlchemy ORM with encryption support
- **Database Layer:** PostgreSQL (production) or SQLite (development)

Documentation
-------------
Complete documentation including API reference and Python examples is available in the project repository.

License
-------
Apache-2.0 License

Copyright (c) Farshid Ashouri
