loom-kernel 2.17.3__tar.gz → 2.18.0__tar.gz

{loom_kernel-2.17.3 → loom_kernel-2.18.0}/CHANGELOG.md

@@ -179,6 +179,13 @@
 
 ### rest
 
+- **rest:** a `403` can say why and what is missing. `Forbidden` takes two
+  optional keyword arguments, `reason` (a machine-readable cause such as
+  `"mfa_required"`) and `missing` (the permissions the caller lacks, kept as a
+  tuple); `HttpErrorMapper` adds `reason` and `missing` to the body only when the
+  refusal carries them, so existing 403 bodies do not change. Both are public:
+  never put token claims or tenant data in them. An empty `reason`, a single
+  string as `missing` or an empty permission raise `ValueError`.
 - **rest:** a single `RuleViolation(field, message)` now answers its `field`.
   `HttpErrorMapper` dropped it, so two `rule_violation` 422s could only be
   told apart by their message text. The body adds `field` (`ErrorField.FIELD`,

{loom_kernel-2.17.3 → loom_kernel-2.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.17.3
+Version: 2.18.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.17.3 → loom_kernel-2.18.0}/src/loom/core/errors/errors.py

@@ -97,10 +97,37 @@ class Forbidden(DomainError):
 
     Args:
         message: Description of the access restriction.
+        reason: Optional machine-readable cause a client can act on, such as
+            ``"mfa_required"``. ``None`` when the refusal has no specific cause.
+        missing: The permissions the caller lacks, in the order given; empty when
+            the authorizer does not tell them.
+
+    Both are keyword-only and public: the REST adapter puts them in the 403 body.
+    Never put token claims, tenant data or anything the caller may not learn in them;
+    leave them out where the refusal must not become an oracle for the policy.
+
+    Raises:
+        ValueError: If ``reason`` is empty, ``missing`` is a single string, or an item
+            of ``missing`` is not a non-empty string.
     """
 
-    def __init__(self, message: str = "Forbidden") -> None:
+    def __init__(
+        self,
+        message: str = "Forbidden",
+        *,
+        reason: str | None = None,
+        missing: Sequence[str] = (),
+    ) -> None:
+        if reason is not None and (not isinstance(reason, str) or not reason.strip()):
+            raise ValueError("Forbidden.reason must be a non-empty string or None")
+        if isinstance(missing, (str, bytes)):
+            raise ValueError("Forbidden.missing takes a sequence of permissions, not one string")
+        permissions = tuple(missing)
+        if any(not isinstance(item, str) or not item.strip() for item in permissions):
+            raise ValueError("Forbidden.missing items must be non-empty strings")
         super().__init__(message, code=ErrorCode.FORBIDDEN)
+        self.reason = reason
+        self.missing: tuple[str, ...] = permissions
 
 
 class Conflict(DomainError):

{loom_kernel-2.17.3 → loom_kernel-2.18.0}/src/loom/rest/errors.py

@@ -9,7 +9,7 @@ from typing import Any, ClassVar
 from fastapi import HTTPException
 
 from loom.core.engine.post_commit import PostCommitError
-from loom.core.errors import LoomError, NotFound, RuleViolation, RuleViolations
+from loom.core.errors import Forbidden, LoomError, NotFound, RuleViolation, RuleViolations
 from loom.core.errors.codes import ErrorCode
 from loom.core.model import BoundaryValidationError
 from loom.core.tracing import get_trace_id
@@ -41,6 +41,8 @@ class ErrorField(StrEnum):
     VIOLATIONS = "violations"
     FIELD = "field"
     COMMITTED = "committed"
+    REASON = "reason"
+    MISSING = "missing"
 
 
 class HttpErrorMapper:
@@ -52,6 +54,8 @@ class HttpErrorMapper:
     per error type:
 
     - :class:`~loom.core.errors.NotFound` → ``entity``, ``id``
+    - :class:`~loom.core.errors.Forbidden` → ``reason`` and ``missing``, each only
+      when the refusal carries it
     - :class:`~loom.core.errors.RuleViolation` → ``field``
     - :class:`~loom.core.errors.RuleViolations` → ``violations``
     - :class:`~loom.core.model.BoundaryValidationError` → ``violations``
@@ -109,6 +113,12 @@ class HttpErrorMapper:
             detail[ErrorField.ENTITY] = error.entity
             detail[ErrorField.ID] = error.id
 
+        if isinstance(error, Forbidden):
+            if error.reason is not None:
+                detail[ErrorField.REASON] = error.reason
+            if error.missing:
+                detail[ErrorField.MISSING] = list(error.missing)
+
         if isinstance(error, RuleViolation):
             detail[ErrorField.FIELD] = error.field