aws-python-helper 1.1.0__tar.gz → 1.3.0__tar.gz

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.1.0
+Version: 1.3.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/aws_python_helper/api/base.py

@@ -186,6 +186,28 @@ class API(ABC):
         """
         return self._is_authenticated
     
+    async def granted_permissions(self):
+        """Which permissions the caller holds, or None when this API does not know.
+
+        Override it to turn on permission checking for a service. Where the list
+        comes from is the service's business: its own database, a map cached from
+        core, whatever fits.
+
+        Returning None with AUTHORIZATION=permission is refused, not waved
+        through. An endpoint that cannot say what its caller may do has to be a
+        closed door: the alternative is that forgetting to wire this up leaves it
+        open to anyone holding a token, which is the failure this whole mechanism
+        exists to prevent.
+        """
+        return None
+
+    @property
+    def service_code(self) -> str:
+        """Names this service inside a permission, as in `core:GET /users`."""
+        import os
+
+        return os.getenv('SERVICE_CODE', os.getenv('NAMESPACE', 'service'))
+
     @property
     def auth_data(self) -> Optional[Dict[str, Any]]:
         """

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/aws_python_helper/api/dispatcher.py

@@ -78,13 +78,20 @@ class Dispatcher:
             
             # 2. Authorization based on mode
             authorization = os.getenv('AUTHORIZATION', '').lower()
-            requires_user = authorization in ('user', 'full')
+            requires_user = authorization in ('user', 'full', 'permission')
             requires_state = authorization in ('state', 'full')
+            requires_permission = authorization == 'permission' 
 
             # 2a. Authenticate (if mode requires user)
             if requires_user:
                 await self._authenticate(api)
 
+            # 2a-bis. Check what the caller is allowed to do
+            if requires_permission:
+                denial = await self._authorize(api)
+                if denial:
+                    return denial
+
             # 2b. Validate state header (if mode requires state)
             if requires_state:
                 state = self.headers.get('constitution-state')
@@ -236,6 +243,43 @@ class Dispatcher:
         
         return api
     
+    async def _authorize(self, api: API):
+        """Refuse the request when the caller lacks the permission it needs.
+
+        Returns the response to send back, or None to carry on.
+        """
+        from ..permissions import allows, required_for
+
+        granted = await api.granted_permissions()
+        if granted is None:
+            logger.error(
+                "AUTHORIZATION=permission but %s does not implement "
+                "granted_permissions(); refusing the request",
+                type(api).__name__,
+            )
+            return {
+                'code': 403,
+                'body': {
+                    'error': 'Forbidden',
+                    'message': 'Permission checking is not configured for this endpoint',
+                },
+                'headers': {},
+            }
+
+        required = required_for(api.service_code, self.method, self.endpoint)
+        if allows(granted, required):
+            return None
+
+        logger.warning("Denied: %s lacks %r", self.headers.get('x-caller', 'caller'), required)
+        return {
+            'code': 403,
+            'body': {
+                'error': 'Forbidden',
+                'message': f"Te falta el permiso '{required}'",
+            },
+            'headers': {},
+        }
+
     async def _authenticate(self, api: API):
         """
         Execute authentication middleware

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/aws_python_helper/model_query/base.py

@@ -40,7 +40,7 @@ Response (via Lambda base run()):
     {"success": True, "data": [...]}
 """
 
-from typing import Any, List, Optional
+from typing import Any, Dict, List, Optional, Union
 from bson import ObjectId
 from pydantic import BaseModel, ConfigDict, model_validator
 
@@ -111,6 +111,36 @@ class _ModelQuerySchema(BaseModel):
         return self
 
 
+def _enforce_exclusions(
+    fields: Optional[dict], excluded: List[str]
+) -> dict:
+    """The projection the owner allows, whatever the caller asked for.
+
+    Mongo reads a projection as inclusive or exclusive, never both, so the
+    forbidden fields are dropped from an inclusive one and added to an exclusive
+    one. `_id` is ignored when deciding which it is: it may appear in either.
+    """
+    projection = dict(fields or {})
+    if not excluded:
+        return projection
+
+    inclusive = any(value for key, value in projection.items() if key != "_id")
+    if not inclusive:
+        for name in excluded:
+            projection[name] = 0
+        return projection
+
+    for name in excluded:
+        projection.pop(name, None)
+
+    # Pedir sólo el campo prohibido dejaría la proyección vacía, y una
+    # proyección vacía en Mongo devuelve el documento entero: exactamente lo
+    # contrario de lo buscado. Sin nada legítimo que pedir, sólo el id.
+    if not any(value for key, value in projection.items() if key != "_id"):
+        return {"_id": 1}
+    return projection
+
+
 class ModelQueryLambda(Lambda):
     """
     Base class for cross-service MongoDB query Lambdas.
@@ -120,19 +150,35 @@ class ModelQueryLambda(Lambda):
     """
 
     @property
-    def allowed_collections(self) -> List[str]:
+    def allowed_collections(self) -> Union[List[str], Dict[str, dict]]:
         """
         Whitelist of collection names this Lambda is allowed to query.
 
         Must be overridden — an empty list rejects all requests.
 
-        Example:
+        A list exposes each collection whole:
+
             @property
             def allowed_collections(self):
                 return ["dockets", "tax_sales"]
+
+        A dict lets the owner keep fields in, whatever the caller projects. This
+        is not `fields`: that one is the caller saying what it wants, this one is
+        the owner saying what never leaves.
+
+            @property
+            def allowed_collections(self):
+                return {"dockets": {}, "users": {"exclude": ["password"]}}
         """
         return []
 
+    def excluded_fields(self, collection: str) -> List[str]:
+        """Fields this collection never returns. Empty for list-style whitelists."""
+        allowed = self.allowed_collections
+        if not isinstance(allowed, dict):
+            return []
+        return list((allowed.get(collection) or {}).get("exclude") or [])
+
     @property
     def schema(self):
         return _ModelQuerySchema
@@ -151,6 +197,16 @@ class ModelQueryLambda(Lambda):
                 f"Collection '{collection}' is not allowed. Allowed: {allowed}"
             )
 
+        # Una pipeline puede renombrar un campo antes de que lo quitemos
+        # ($addFields, $replaceRoot, $lookup), así que no hay forma honesta de
+        # garantizar la exclusión sobre ella. Un $unset final daría una falsa
+        # sensación de seguridad, que es peor que no tener la función.
+        if self.excluded_fields(collection) and self.data.get("pipeline") is not None:
+            raise ValueError(
+                f"Collection '{collection}' hides fields, so it cannot be queried "
+                f"with a pipeline. Use 'filter' instead."
+            )
+
     async def process(self) -> Any:
         collection_name: str = self.data["collection"]
         database: str = self.data.get("database") or self.session.state
@@ -167,7 +223,10 @@ class ModelQueryLambda(Lambda):
             limit: int = self.data.get("limit") or 0
             skip: int = self.data.get("skip") or 0
 
-            cursor = collection.find(mongo_filter, fields or {})
+            projection = _enforce_exclusions(
+                fields, self.excluded_fields(collection_name)
+            )
+            cursor = collection.find(mongo_filter, projection)
 
             if skip:
                 cursor = cursor.skip(skip)

aws_python_helper-1.3.0/aws_python_helper/permissions/__init__.py

@@ -0,0 +1,9 @@
+from .catalog import ALL, allows, discover, required_for, service_wildcard
+
+__all__ = [
+    "ALL",
+    "allows",
+    "discover",
+    "required_for",
+    "service_wildcard",
+]

aws_python_helper-1.3.0/aws_python_helper/permissions/catalog.py

@@ -0,0 +1,105 @@
+"""Derives a service's permissions from the API files it actually has.
+
+The endpoints are already declared twice — in the terraform routes and in the
+file convention the dispatcher resolves on. A hand-written list would be a third
+copy, and the first endpoint added without touching it would be an unguarded
+hole nobody notices.
+
+Mirrors `aws_python_helper.api.fetcher` in reverse: that one turns a request into
+a file, this one turns the files into the requests they answer. It lives beside
+the fetcher so the two cannot drift: a routing rule that changes in one would
+otherwise silently stop matching in the other, and an access check that never
+matches fails open or shut without anyone noticing.
+"""
+
+import os
+from typing import Dict, List
+
+from ..api.fetcher import Fetcher
+
+# Cómo se llama el archivo según el método. `list` y `get` son ambos GET: uno
+# responde la colección, el otro un elemento.
+FILE_METHODS = {
+    "list": "GET",
+    "get": "GET",
+    "post": "POST",
+    "put": "PUT",
+    "patch": "PATCH",
+    "delete": "DELETE",
+}
+
+ALL = "*"
+
+
+def discover(api_root: str, service: str) -> List[Dict[str, str]]:
+    """Every endpoint this service answers, as permission records.
+
+    The `{id}` of a route is left out on purpose: holding an id does not change
+    who may call the endpoint, and leaving it out makes the mapping between a
+    file and a permission exact.
+    """
+    found: List[Dict[str, str]] = []
+
+    for current, _, files in os.walk(api_root):
+        for filename in sorted(files):
+            stem, extension = os.path.splitext(filename)
+            if extension != ".py" or stem not in FILE_METHODS:
+                continue
+
+            relative = os.path.relpath(current, api_root)
+            parts = [] if relative == "." else relative.split(os.sep)
+            path = "/" + "/".join(parts)
+            method = FILE_METHODS[stem]
+
+            # `list` responde la colección y `get` un elemento: mismo método
+            # sobre rutas distintas, así que son dos permisos, no uno.
+            if stem == "get":
+                path = f"{path.rstrip('/')}/{{id}}"
+
+            found.append({
+                "code": f"{service}:{method} {path}",
+                "service": service,
+                "method": method,
+                "path": path,
+                "scope": "item" if stem == "get" else "collection",
+            })
+
+    return sorted(found, key=lambda item: item["code"])
+
+
+def service_wildcard(service: str) -> str:
+    return f"{service}:*"
+
+
+def required_for(service: str, method: str, endpoint: str, api_root: str = "api") -> str:
+    """The permission a request needs.
+
+    Asks the framework which file will answer, and names the permission after it.
+    Reimplementing the routing rules here would be a second copy that drifts, and
+    a permission that never matches fails open or shut without anyone noticing —
+    which is the worst way for an access check to be wrong.
+    """
+    resolved = Fetcher(endpoint, method.lower()).file_path
+    marker = os.sep + api_root + os.sep
+    if marker not in resolved:
+        return ""
+
+    relative = resolved.split(marker, 1)[1]
+    directory, filename = os.path.split(relative)
+    stem = os.path.splitext(filename)[0]
+    if stem not in FILE_METHODS:
+        return ""
+
+    path = "/" + directory.replace(os.sep, "/") if directory else "/"
+    if stem == "get":
+        path = f"{path.rstrip('/')}/{{id}}"
+    return f"{service}:{FILE_METHODS[stem]} {path}"
+
+
+def allows(granted: List[str], required: str) -> bool:
+    """Whether a set of granted permissions covers the one an endpoint needs."""
+    if not required:
+        return False
+    if ALL in granted or required in granted:
+        return True
+    return service_wildcard(required.split(":", 1)[0]) in granted

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/aws_python_helper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.1.0
+Version: 1.3.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/aws_python_helper.egg-info/SOURCES.txt

@@ -39,6 +39,8 @@ aws_python_helper/model_index_sync/__init__.py
 aws_python_helper/model_index_sync/base.py
 aws_python_helper/model_query/__init__.py
 aws_python_helper/model_query/base.py
+aws_python_helper/permissions/__init__.py
+aws_python_helper/permissions/catalog.py
 aws_python_helper/repository/__init__.py
 aws_python_helper/repository/base.py
 aws_python_helper/sns/__init__.py

{aws_python_helper-1.1.0 → aws_python_helper-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aws-python-helper"
-version = "1.1.0"
+version = "1.3.0"
 description = "AWS Python Helper Framework"
 readme = "README.md"
 requires-python = ">=3.9"