auth 2.0.0__tar.gz → 2.4.0__tar.gz

auth-2.4.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: auth
+Version: 2.4.0
+Summary: Authorization for humans
+Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
+License-Expression: MIT
+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/markdown
+License-File: LICENSE
+Requires-Dist: flask<4,>=2.0.0
+Requires-Dist: flask-cors<7,>=3.0.0
+Requires-Dist: sqlalchemy<3,>=2.0.0
+Requires-Dist: waitress<4,>=2.0.0
+Requires-Dist: cryptography<48,>=3.0.0
+Requires-Dist: APScheduler<4,>=3.0.0
+Requires-Dist: psycopg[binary]<4,>=3.0.0
+Requires-Dist: pydantic<3,>=2.0.0
+Requires-Dist: pydantic-settings<3,>=2.0.0
+Requires-Dist: requests<3,>=2.25.0
+Requires-Dist: bleach<7,>=5.0.0
+Requires-Dist: python-json-logger<4,>=3.1.0
+Provides-Extra: ratelimit
+Requires-Dist: flask-limiter>=3.0.0; extra == "ratelimit"
+Provides-Extra: migrations
+Requires-Dist: migretti>=0.10.0; extra == "migrations"
+Requires-Dist: alembic>=1.13.0; extra == "migrations"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: alembic>=1.13.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: types-waitress; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# auth — RBAC authorization service
+
+[![CI](https://github.com/ourway/auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ourway/auth/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Role-based access control over HTTP. `auth` answers one question — **may user X
+do Y** — so your services don't reinvent roles and permissions.
+
+It is **authorization, not authentication**: it does not log anyone in, store
+passwords, or issue tokens. It trusts that the caller already knows *who* the
+user is, and decides *what they may do*. Model:
+`user → (member of) → role → (holds) → permission`.
+
+## Quickstart
+
+Your **client key is any UUID4** — it is also your private, isolated namespace.
+Generate one, keep it secret, and reuse it for every call. A role must exist
+before you add members or permissions to it.
+
+```bash
+KEY=$(python3 -c "import uuid; print(uuid.uuid4())")
+BASE=https://auth.rodmena.app
+
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/role/engineers
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/permission/engineers/deploy
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/membership/alice/engineers
+curl        -H "Authorization: Bearer $KEY" $BASE/api/has_permission/alice/deploy
+# -> {"success": true, "data": {"has_permission": true}, ...}
+```
+
+With the Python client (`pip install auth`):
+
+```python
+from auth import Client
+
+with Client(api_key=KEY, service_url="https://auth.rodmena.app") as c:
+    c.create_role("engineers")
+    c.add_permission("engineers", "deploy")
+    c.add_membership("alice", "engineers")
+    c.user_has_permission("alice", "deploy")   # -> {... "has_permission": true}
+```
+
+## Things to know before you write code
+
+- **Writes can return HTTP 200 with `{"result": false}`** (e.g. adding to a
+  missing role). Check the `result`/`data` field, not just the status code.
+- **Two response shapes** — bare `{"result": ...}` and wrapped
+  `{"success", "data", ...}`. The API reference says which per endpoint.
+- **Errors below 2xx are HTML**, not JSON. Branch on the status code first.
+- **Python client: check `success` before reading `data`.** On transport
+  failure the client does not raise by default — it returns
+  `{"error", "success": False, "transport_error": True, "data": {...}}` where
+  `data` only echoes your inputs and does NOT contain the answer field
+  (`has_permission`, `count`, ...). Reading `data` blindly turns an outage into
+  a false "no". Pass `Client(..., raise_on_error=True)` to get an
+  `AuthTransportError` exception instead of the error dict.
+- **Reuse one key.** A new key is a new empty namespace, not an error. Keep the
+  key out of source control, logs, and URLs — it is the only thing protecting
+  your data. Rotate it with `POST /api/keys/rotate` if it leaks.
+- **Per-user API keys** (2.4.0): `/api/apikeys/user/<user>` (create/list),
+  `/api/apikeys/user/<user>/<key_id>` (revoke), `/api/apikeys/validate`. auth
+  mints `rak_...` secrets for *your users*, shows each exactly once, stores only
+  a hash, and validates them inside your namespace — an identity UI fronts the
+  lifecycle, backends validate then use the RBAC checks. Client methods:
+  `create_api_key`, `list_api_keys`, `revoke_api_key`, `validate_api_key`.
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| **Live API reference** — [`/docs`](https://auth.rodmena.app/docs) · [`/llms.txt`](https://auth.rodmena.app/llms.txt) | Every endpoint and exact response shape, served by the app (agent-friendly). |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design, components, request lifecycle, data model, permission-check and key-rotation flows, diagrams. |
+| [SECURITY.md](SECURITY.md) | Security model (tenant isolation, encryption, audit, rotation), threat notes, reporting. |
+| [MIGRATIONS.md](MIGRATIONS.md) | Schema creation vs migrations, upgrade/rollback runbook. |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Local setup, tests (sqlite + postgres), lint/type-check, CI. |
+| [docs/](docs/) | Full Sphinx docs (concepts, configuration, encryption, deployment, REST & Python usage). |
+
+## When to use — and not
+
+**Use it** for RBAC: named roles, permissions, group membership, and boolean
+"can user X do Y" gates for a service, CLI, or workflow engine.
+
+**Not** for authentication (login/passwords/sessions/OAuth/JWT), fine-grained /
+attribute-based rules (owner-of-*this*-record, time-of-day, row-level tenancy —
+reach for an ABAC/policy engine), or air-gapped hot loops where a network hop per
+check is too costly (cache, or use the library in-process).
+
+## Development
+
+```bash
+python3.11 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,ratelimit,migrations]"
+make check   # ruff + mypy
+make test    # sqlite suite
+make test-postgres   # postgres integration (Docker), encryption on
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. Licensed under the
+[MIT License](LICENSE).

auth-2.4.0/README.md

@@ -0,0 +1,100 @@
+# auth — RBAC authorization service
+
+[![CI](https://github.com/ourway/auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ourway/auth/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Role-based access control over HTTP. `auth` answers one question — **may user X
+do Y** — so your services don't reinvent roles and permissions.
+
+It is **authorization, not authentication**: it does not log anyone in, store
+passwords, or issue tokens. It trusts that the caller already knows *who* the
+user is, and decides *what they may do*. Model:
+`user → (member of) → role → (holds) → permission`.
+
+## Quickstart
+
+Your **client key is any UUID4** — it is also your private, isolated namespace.
+Generate one, keep it secret, and reuse it for every call. A role must exist
+before you add members or permissions to it.
+
+```bash
+KEY=$(python3 -c "import uuid; print(uuid.uuid4())")
+BASE=https://auth.rodmena.app
+
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/role/engineers
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/permission/engineers/deploy
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/membership/alice/engineers
+curl        -H "Authorization: Bearer $KEY" $BASE/api/has_permission/alice/deploy
+# -> {"success": true, "data": {"has_permission": true}, ...}
+```
+
+With the Python client (`pip install auth`):
+
+```python
+from auth import Client
+
+with Client(api_key=KEY, service_url="https://auth.rodmena.app") as c:
+    c.create_role("engineers")
+    c.add_permission("engineers", "deploy")
+    c.add_membership("alice", "engineers")
+    c.user_has_permission("alice", "deploy")   # -> {... "has_permission": true}
+```
+
+## Things to know before you write code
+
+- **Writes can return HTTP 200 with `{"result": false}`** (e.g. adding to a
+  missing role). Check the `result`/`data` field, not just the status code.
+- **Two response shapes** — bare `{"result": ...}` and wrapped
+  `{"success", "data", ...}`. The API reference says which per endpoint.
+- **Errors below 2xx are HTML**, not JSON. Branch on the status code first.
+- **Python client: check `success` before reading `data`.** On transport
+  failure the client does not raise by default — it returns
+  `{"error", "success": False, "transport_error": True, "data": {...}}` where
+  `data` only echoes your inputs and does NOT contain the answer field
+  (`has_permission`, `count`, ...). Reading `data` blindly turns an outage into
+  a false "no". Pass `Client(..., raise_on_error=True)` to get an
+  `AuthTransportError` exception instead of the error dict.
+- **Reuse one key.** A new key is a new empty namespace, not an error. Keep the
+  key out of source control, logs, and URLs — it is the only thing protecting
+  your data. Rotate it with `POST /api/keys/rotate` if it leaks.
+- **Per-user API keys** (2.4.0): `/api/apikeys/user/<user>` (create/list),
+  `/api/apikeys/user/<user>/<key_id>` (revoke), `/api/apikeys/validate`. auth
+  mints `rak_...` secrets for *your users*, shows each exactly once, stores only
+  a hash, and validates them inside your namespace — an identity UI fronts the
+  lifecycle, backends validate then use the RBAC checks. Client methods:
+  `create_api_key`, `list_api_keys`, `revoke_api_key`, `validate_api_key`.
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| **Live API reference** — [`/docs`](https://auth.rodmena.app/docs) · [`/llms.txt`](https://auth.rodmena.app/llms.txt) | Every endpoint and exact response shape, served by the app (agent-friendly). |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design, components, request lifecycle, data model, permission-check and key-rotation flows, diagrams. |
+| [SECURITY.md](SECURITY.md) | Security model (tenant isolation, encryption, audit, rotation), threat notes, reporting. |
+| [MIGRATIONS.md](MIGRATIONS.md) | Schema creation vs migrations, upgrade/rollback runbook. |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Local setup, tests (sqlite + postgres), lint/type-check, CI. |
+| [docs/](docs/) | Full Sphinx docs (concepts, configuration, encryption, deployment, REST & Python usage). |
+
+## When to use — and not
+
+**Use it** for RBAC: named roles, permissions, group membership, and boolean
+"can user X do Y" gates for a service, CLI, or workflow engine.
+
+**Not** for authentication (login/passwords/sessions/OAuth/JWT), fine-grained /
+attribute-based rules (owner-of-*this*-record, time-of-day, row-level tenancy —
+reach for an ABAC/policy engine), or air-gapped hot loops where a network hop per
+check is too costly (cache, or use the library in-process).
+
+## Development
+
+```bash
+python3.11 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,ratelimit,migrations]"
+make check   # ruff + mypy
+make test    # sqlite suite
+make test-postgres   # postgres integration (Docker), encryption on
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. Licensed under the
+[MIT License](LICENSE).

{auth-2.0.0 → auth-2.4.0}/auth/__init__.py

@@ -3,7 +3,11 @@ __author__ = "Farshid Ashouri"
 from importlib.metadata import PackageNotFoundError, version
 from typing import Optional
 
-from auth.client import Client, EnhancedAuthClient  # Import the new client
+from auth.client import (  # Import the new client
+    AuthTransportError,
+    Client,
+    EnhancedAuthClient,
+)
 from auth.database import SessionLocal
 from auth.services.service import AuthorizationService
 
@@ -94,6 +98,7 @@ class Authorization:
 # Export the new client for users who want enhanced features
 __all__ = [
     "Authorization",
+    "AuthTransportError",
     "Client",
     "EnhancedAuthClient",
     "SessionLocal",

auth-2.4.0/auth/api_keys.py

@@ -0,0 +1,50 @@
+"""Per-user API key generation and hashing (SPEC 0004).
+
+Secrets are ``rak_`` + 43 base62 characters carrying the full 256 bits of
+``secrets.token_bytes(32)``. Only the SHA-256 hex digest is stored; the raw
+secret is returned once at creation and never persisted, logged, or audited.
+The digest deliberately excludes the tenant and any server pepper: at this
+entropy an offline attack on a leaked hash is not a threat, and neither a
+client-key rotation nor a pepper change may invalidate issued keys.
+"""
+
+import hashlib
+import re
+import secrets
+import uuid
+from typing import Tuple
+
+API_KEY_PREFIX = "rak_"
+API_KEY_PATTERN = re.compile(r"^rak_[0-9A-Za-z]{43}$")
+
+# "rak_" + first 8 payload chars — safe to store and display in listings.
+KEY_PREFIX_LEN = 12
+
+_PAYLOAD_LEN = 43
+_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+
+def _base62(data: bytes) -> str:
+    number = int.from_bytes(data, "big")
+    chars = []
+    while number:
+        number, rem = divmod(number, 62)
+        chars.append(_ALPHABET[rem])
+    return "".join(reversed(chars)) or _ALPHABET[0]
+
+
+def generate_api_key() -> Tuple[str, str, str, str]:
+    """Mint a fresh key: returns ``(secret, key_id, key_hash, key_prefix)``.
+
+    ``secret`` is shown to the caller exactly once; ``key_id`` is the public
+    UUID4 handle used in revoke paths; ``key_hash``/``key_prefix`` are what
+    gets stored.
+    """
+    payload = _base62(secrets.token_bytes(32)).rjust(_PAYLOAD_LEN, _ALPHABET[0])
+    secret = API_KEY_PREFIX + payload
+    return secret, str(uuid.uuid4()), hash_api_key(secret), secret[:KEY_PREFIX_LEN]
+
+
+def hash_api_key(secret: str) -> str:
+    """SHA-256 hex digest of the full secret string (equality-queryable)."""
+    return hashlib.sha256(secret.encode()).hexdigest()

{auth-2.0.0 → auth-2.4.0}/auth/audit.py

@@ -37,6 +37,11 @@ class AuditAction(Enum):
     LIST_PERMISSIONS = "LIST_PERMISSIONS"
     LIST_MEMBERSHIPS = "LIST_MEMBERSHIPS"
     USER_PERMISSIONS = "USER_PERMISSIONS"
+    ROTATE_KEY = "ROTATE_KEY"
+    CREATE_API_KEY = "CREATE_API_KEY"
+    LIST_API_KEYS = "LIST_API_KEYS"
+    REVOKE_API_KEY = "REVOKE_API_KEY"
+    VALIDATE_API_KEY = "VALIDATE_API_KEY"
 
 
 class AuditLog(Base):
@@ -111,7 +116,65 @@ def client_fingerprint(token: Optional[str]) -> str:
     return "fpr_" + digest[:32]
 
 
-def log_audit_event(
+def _build_audit_entry(
+    client_id: str,
+    user: Optional[str],
+    action: AuditAction,
+    resource: Optional[str],
+    details: Optional[Dict[str, Any]],
+    ip_address: Optional[str],
+    user_agent: Optional[str],
+    success: bool,
+) -> "AuditLog":
+    # The managed user is a human identifier (often an email) — store a
+    # non-reversible fingerprint, never plaintext, matching how the client key is
+    # handled. Auditors correlate by fingerprint and can confirm a known user by
+    # computing its fingerprint. Role/permission/workflow names (the `resource`)
+    # are application identifiers, not PII, and stay readable — except the caller
+    # is responsible for fingerprinting any user embedded in `resource`.
+    user_fp = client_fingerprint(user) if user else None
+    return AuditLog(
+        client_id=_fit(client_id, "client_id"),
+        user=_fit(user_fp, "user"),
+        action=_fit(action.value, "action"),
+        resource=_fit(resource, "resource"),
+        details=json.dumps(details) if details else None,
+        ip_address=_fit(ip_address, "ip_address"),
+        user_agent=_fit(user_agent, "user_agent"),
+        success=1 if success else 0,
+    )
+
+
+def _emit_structured_log(
+    client_id: str,
+    user: Optional[str],
+    action: AuditAction,
+    resource: Optional[str],
+    details: Optional[Dict[str, Any]],
+    ip_address: Optional[str],
+    success: bool,
+) -> None:
+    # The DB row is the system of record. The log STREAM (journald / SIEM /
+    # shipping) is more widely exposed, so it carries no PII: no raw user and no
+    # resource string (which may embed a user). Only the non-reversible client
+    # fingerprint, the action, and the outcome.
+    log_msg: Dict[str, Any] = {
+        "type": "audit",
+        "client_id": client_id,
+        "action": action.value,
+        "success": success,
+        "timestamp": _utcnow().isoformat(),
+    }
+    if details:
+        log_msg["details"] = details
+    if ip_address:
+        log_msg["ip"] = ip_address
+    audit_logger.info(json.dumps(log_msg))
+
+
+def record_audit(
+    session,
+    *,
     client_id: str,
     user: Optional[str],
     action: AuditAction,
@@ -121,45 +184,52 @@ def log_audit_event(
     user_agent: Optional[str] = None,
     success: bool = True,
 ) -> None:
+    """Add an audit row to an EXISTING session so it commits atomically with the
+    caller's transaction (the mutation and its audit land together, or not at
+    all). The caller is responsible for committing.
+
+    This does NOT swallow errors: a failure to stage the audit row must fail the
+    surrounding request (fail-closed), never leave a committed mutation
+    unaudited.
     """
-    Log an audit event to the database and to structured logs
+    session.add(
+        _build_audit_entry(
+            client_id, user, action, resource, details, ip_address, user_agent, success
+        )
+    )
+    _emit_structured_log(client_id, user, action, resource, details, ip_address, success)
+
+
+def log_audit_event(
+    client_id: str,
+    user: Optional[str],
+    action: AuditAction,
+    resource: Optional[str] = None,
+    details: Optional[Dict[str, Any]] = None,
+    ip_address: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    success: bool = True,
+) -> None:
+    """Write an audit event on its OWN committed session.
+
+    For contexts with no request transaction to join: in-process/library
+    callers, and the *failure* path of the request decorator (where the request
+    transaction is being rolled back and must not carry the audit row). This one
+    is best-effort — a failure is logged, not raised, so it cannot mask the
+    original error it is recording.
     """
     session = SessionLocal()
     try:
-        # Create audit log entry
-        audit_entry = AuditLog(
-            client_id=_fit(client_id, "client_id"),
-            user=_fit(user, "user"),
-            action=_fit(action.value, "action"),
-            resource=_fit(resource, "resource"),
-            details=json.dumps(details) if details else None,
-            ip_address=_fit(ip_address, "ip_address"),
-            user_agent=_fit(user_agent, "user_agent"),
-            success=1 if success else 0,
+        session.add(
+            _build_audit_entry(
+                client_id, user, action, resource, details, ip_address, user_agent, success
+            )
         )
-
-        session.add(audit_entry)
         session.commit()
-
-        # Also log to structured logger
-        log_msg: Dict[str, Any] = {
-            "type": "audit",
-            "client_id": client_id,
-            "user": user,
-            "action": action.value,
-            "resource": resource,
-            "success": success,
-            "timestamp": _utcnow().isoformat(),
-        }
-        if details:
-            log_msg["details"] = details
-        if ip_address:
-            log_msg["ip"] = ip_address
-
-        audit_logger.info(json.dumps(log_msg))
+        _emit_structured_log(
+            client_id, user, action, resource, details, ip_address, success
+        )
     except Exception:
-        # If audit logging fails, we don't want to break the main operation
-        # But log the failure for monitoring
         audit_logger.error(
             f"Failed to log audit event: client_id={client_id}, action={action.value}"
         )