apexauthlib 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

apexauthlib/entities/auth.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Any, Generic, TypeVar
 from uuid import uuid4
 
@@ -48,3 +51,30 @@ class ServiceUserInfo(Generic[ItemT]):
     user: User
     is_service_admin: bool
     metadata: ItemT
+
+
+@dataclass(frozen=True)
+class ServicePermission:
+    name: str
+    label: str
+    description: str
+    type: FieldType
+    default: str | int | bool
+
+    values: list[str] | list[int] = field(default_factory=list)
+    id: str = field(default_factory=lambda: str(uuid4()))
+
+
+class FieldType(str, Enum):
+    string = "string"
+    integer = "integer"
+    boolean = "boolean"
+
+    def valid_type(self) -> type:
+        if self.value == FieldType.string:
+            return str
+        if self.value == FieldType.integer:
+            return int
+        if self.value == FieldType.boolean:
+            return bool
+        raise ValueError(f"Invalid type {self.value}")

apexauthlib/integration/api.py

@@ -7,7 +7,8 @@ from apexdevkit.formatter import DataclassFormatter, Formatter
 from apexdevkit.http import FluentHttp, JsonDict
 
 from apexauthlib.entities import User
-from apexauthlib.entities.auth import ItemT, ServiceUserInfo
+from apexauthlib.entities.auth import ItemT, ServicePermission, ServiceUserInfo
+from apexauthlib.integration.formatter import ServicePermissionFormatter
 
 
 @dataclass(frozen=True)
@@ -118,6 +119,59 @@ class AuthApi(Generic[ItemT]):
                 metadata=self.formatter.load(raw_user["metadata"]),
             )
 
+    def update_permissions(
+        self, permissions: list[ServicePermission]
+    ) -> list[ServicePermission]:
+        existing = {
+            permission.name: permission
+            for permission in self._retrieve_existing_permissions()
+        }
+        new = {new_permission.name: new_permission for new_permission in permissions}
+
+        for current, current_permission in existing.items():
+            if current not in new.keys():
+                self._delete_permission(current_permission.id)
+
+        for current, current_permission in new.items():
+            if current not in existing.keys():
+                self._create_permission(current_permission)
+
+        return self._retrieve_existing_permissions()
+
+    def _retrieve_existing_permissions(self) -> list[ServicePermission]:
+        existing = list(
+            JsonDict(
+                (
+                    self.http.with_header("Authorization", f"Bearer {self.token}")
+                    .get()
+                    .on_endpoint(f"/services/{self.service_name}/permissions")
+                    .on_failure(raises=RuntimeError)
+                    .json()
+                )
+            )["data"]["permissions"]
+        )
+
+        return [ServicePermissionFormatter().load(item) for item in existing]
+
+    def _delete_permission(self, permission_id: str) -> None:
+        (
+            self.http.with_header("Authorization", f"Bearer {self.token}")
+            .delete()
+            .on_endpoint(f"/services/{self.service_name}/permissions/{permission_id}")
+            .on_failure(raises=RuntimeError)
+            .json()
+        )
+
+    def _create_permission(self, permission: ServicePermission) -> None:
+        (
+            self.http.with_header("Authorization", f"Bearer {self.token}")
+            .with_json(JsonDict(ServicePermissionFormatter().dump(permission)))
+            .post()
+            .on_endpoint(f"/services/{self.service_name}/permissions")
+            .on_failure(raises=RuntimeError)
+            .json()
+        )
+
 
 @dataclass
 class AuthCodeApi:

apexauthlib/integration/formatter.py

@@ -0,0 +1,58 @@
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from apexauthlib.entities.auth import FieldType, ServicePermission
+
+
+@dataclass(frozen=True)
+class ServicePermissionFormatter:
+    def dump(self, permission: ServicePermission) -> Mapping[str, Any]:
+        raw = {
+            "name": permission.name,
+            "description": permission.description,
+            "label": permission.label,
+            "type": permission.type.value,
+            "values": permission.values,
+            "default": permission.default,
+        }
+
+        if permission.id.isdigit():
+            raw["id"] = permission.id
+
+        return raw
+
+    def load(self, raw: Mapping[str, Any]) -> ServicePermission:
+        permission_type = FieldType[str(raw["type"])]
+
+        return ServicePermission(
+            id=str(raw["id"]),
+            name=str(raw["name"]),
+            label=str(raw["label"]),
+            description=str(raw["description"]),
+            type=permission_type,
+            values=self._load_combos(permission_type, raw),
+            default=self._load_default(permission_type, raw),
+        )
+
+    def _load_combos(
+        self, permission_type: FieldType, raw: Mapping[str, Any]
+    ) -> list[str] | list[int]:
+        if permission_type == FieldType.boolean:
+            return []
+        if permission_type == FieldType.string:
+            return [str(item) for item in list(raw["values"])]
+        if permission_type == FieldType.integer:
+            return [int(item) for item in list(raw["values"])]
+
+        raise ValueError(f"Unexpected type: {permission_type}")
+
+    def _load_default(
+        self, permission_type: FieldType, raw: Mapping[str, Any]
+    ) -> str | int | bool:
+        if permission_type == FieldType.string:
+            return str(raw["default"])
+        if permission_type == FieldType.integer:
+            return int(raw["default"])
+        if permission_type == FieldType.boolean:
+            return bool(raw["default"])
+        raise ValueError(f"Unexpected type: {permission_type}")

apexauthlib-0.1.11.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: apexauthlib
+Version: 0.1.11
+Summary: Apex authorization library for services
+License-File: LICENSE
+Author: Apex Dev
+Author-email: dev@apex.ge
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: apexdevkit
+Requires-Dist: fastapi (==0.120.*)
+Requires-Dist: httpx
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+# apexauthlib
+
+Private Python library for integrating backend services with the company auth-service.
+
+This library provides:
+- **Entities** used across services (user, service, client, service metadata, permissions).
+- A **FastAPI router** (`auth_api`) with login endpoints and dependency helpers that inject the current user + metadata from JWT.
+- A small **HTTP client wrapper** (`AuthApiProvider` / `AuthApi`) for services to:
+  - obtain a token (password login or OAuth code exchange),
+  - fetch current user and service-scoped metadata,
+  - list users for a service,
+  - and register/update service permissions.
+
+> Notes
+> - This documentation is best used along with the documentation for auth-service.
+> - This is a **private library**. If you change it, you should push to GitHub and then update downstream usage by running `make install` wherever it’s consumed (per team workflow).
+
+---
+
+## Concepts at a glance
+
+### Users
+The `User` entity includes:
+- `hashed_password`: **must never expose an actual password** through APIs (except in create/update requests handled elsewhere).
+- `is_admin`: indicates whether the user is a “superadmin”.
+
+### Service-scoped auth model
+The auth model used by services is service-centric:
+- Services have a name (`service_name`) and service admins.
+- Each service can define **permissions** (schema) and **per-user metadata** values that should align with those permissions.
+
+See: [`docs/concepts.md`](docs/concepts.md)
+
+---
+
+## Usage pattern (high-level)
+
+### 1) Create an `AuthApiProvider`
+
+Example (from service code):
+
+```python
+provider = AuthApiProvider[HaccpPermissions](
+    http=FluentHttp(
+        Httpx.Builder().with_url(AUTH_SERVICE_API).build(),
+    ),
+    service_name=SERVICE_NAME,
+    formatter=DataclassFormatter(HaccpPermissions),
+)
+```
+
+### 2) Register permissions (service schema)
+
+Example:
+
+```python
+provider.for_token(
+    provider.login(ADMIN_USERNAME, ADMIN_PASSWORD)
+).update_permissions(
+    [
+        ServicePermission(
+            # ...
+        )
+    ]
+)
+```
+
+### 3) Add FastAPI auth routes + dependencies
+
+Example:
+
+```python
+FastApiBuilder()
+.with_title(TITLE)
+.with_description(DESCRIPTION)
+.with_version(VERSION)
+.with_route(auth_api)
+.with_dependency(
+    auth=provider,
+    auth_code=AuthCodeApi(
+        http=FluentHttp(
+            Httpx.Builder()
+            .with_url(AUTH_SERVICE_API)
+            .build(),
+        ),
+        client_id=CLIENT_ID,
+        client_secret=CLIENT_SECRET,
+    ),
+)
+.build()
+```
+
+See: [`docs/fastapi.md`](docs/fastapi.md)
+
+## Known Limitations
+
+### Permission sync is name-based only
+
+AuthApi.update_permissions() compares permissions by name and only creates/deletes.
+If a permission keeps the same name but changes type, default, label, etc., 
+it currently won’t be updated automatically.
+
+### Admin password dependency for permission registration
+
+The example uses provider.login(ADMIN_USERNAME, ADMIN_PASSWORD) to obtain a token for updating permissions.
+If the admin password changes, downstream services must update their configuration, or a more proper flow should
+be introduced (e.g., service-to-service auth or code-based admin auth).
+
+### Refresh tokens are not currently handled in this library
+
+Current flow assumes a bearer access token is provided/used. Supporting refresh tokens would enable
+longer-lived sessions with automatic token renewal.
+
+

apexauthlib-0.1.11.dist-info/RECORD

@@ -0,0 +1,12 @@
+apexauthlib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+apexauthlib/entities/__init__.py,sha256=KghMo6a2QWdPzWlMqdGAKOaVvRmTCOIVhXtIHrX7A_M,149
+apexauthlib/entities/auth.py,sha256=AY34GnOhVhu0WCrpp0LoJ__r6ou-hORFiVExvCyCzmE,1566
+apexauthlib/fastapi/__init__.py,sha256=G77C3ZIqjsXdh4fiH5FZyF_hyzVtS3waJJGa_TBGMWE,103
+apexauthlib/fastapi/auth.py,sha256=hkvG2BougydElkYbEpwsuSgRoLOLANe6DbVSoa-zBRM,3917
+apexauthlib/integration/__init__.py,sha256=f2lGbyoGct4kpZ2CUTExHhtQHs-1YR_xanvrj9Y4GiI,87
+apexauthlib/integration/api.py,sha256=iSjaq6FrLOvnC86Y4DtV8O2fNqy09Tt5HjyAp707C4I,6478
+apexauthlib/integration/formatter.py,sha256=DyVRMWYkZErZBeP_f4aYdSbe9g9zck-x2ONFPxwVNfY,2037
+apexauthlib-0.1.11.dist-info/METADATA,sha256=2iH1MMTn76woy7R_XuungNbggbxFuhkuBv8bBf00mik,3922
+apexauthlib-0.1.11.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+apexauthlib-0.1.11.dist-info/licenses/LICENSE,sha256=iai0ILQTDgUXV1cIXl0UzSeOdFpMFK3shn5aqnz_Uro,1065
+apexauthlib-0.1.11.dist-info/RECORD,,

{apexauthlib-0.1.9.dist-info → apexauthlib-0.1.11.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.3.1
 Root-Is-Purelib: true
 Tag: py3-none-any

apexauthlib-0.1.9.dist-info/METADATA

@@ -1,19 +0,0 @@
-Metadata-Version: 2.3
-Name: apexauthlib
-Version: 0.1.9
-Summary: Apex authorization library for services
-Author: Apex Dev
-Author-email: dev@apex.ge
-Requires-Python: >=3.11
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: apexdevkit
-Requires-Dist: fastapi
-Requires-Dist: httpx
-Requires-Dist: uvicorn
-Description-Content-Type: text/markdown
-
-# apexauthlib
-Central authorization library for apex services
-

apexauthlib-0.1.9.dist-info/RECORD

@@ -1,11 +0,0 @@
-apexauthlib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-apexauthlib/entities/__init__.py,sha256=KghMo6a2QWdPzWlMqdGAKOaVvRmTCOIVhXtIHrX7A_M,149
-apexauthlib/entities/auth.py,sha256=Zyme1bgQEW1SHLeHSjTaY8E4yd12EIZOEOE3cICZOAo,843
-apexauthlib/fastapi/__init__.py,sha256=G77C3ZIqjsXdh4fiH5FZyF_hyzVtS3waJJGa_TBGMWE,103
-apexauthlib/fastapi/auth.py,sha256=hkvG2BougydElkYbEpwsuSgRoLOLANe6DbVSoa-zBRM,3917
-apexauthlib/integration/__init__.py,sha256=f2lGbyoGct4kpZ2CUTExHhtQHs-1YR_xanvrj9Y4GiI,87
-apexauthlib/integration/api.py,sha256=c94T9Z7IPM0K1zKDjex6fr9TNOtE3ZLHnjT2x8kOodY,4372
-apexauthlib-0.1.9.dist-info/LICENSE,sha256=iai0ILQTDgUXV1cIXl0UzSeOdFpMFK3shn5aqnz_Uro,1065
-apexauthlib-0.1.9.dist-info/METADATA,sha256=jTSqo4KFSZGv2Ew58Dm52xQq6myqcAp7vbfTS667C64,518
-apexauthlib-0.1.9.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-apexauthlib-0.1.9.dist-info/RECORD,,