domain-security 0.1.0__py3-none-any.whl

domain_security/__init__.py

@@ -0,0 +1,40 @@
+"""Cross-cutting security concerns: authorization, tenancy, secrets, context management."""
+
+from domain_security.config._version import __version__
+from domain_security.context.security_context.security_context_client import (
+    SecurityContextManager,
+)
+from domain_security.context.security_context.security_context_objects import (
+    Principal,
+    SecurityContext,
+)
+from domain_security.decorators.requires.requires_client import requires
+from domain_security.decorators.tenant_scoped.tenant_scoped_client import tenant_scoped
+from domain_security.errors.security_errors import (
+    AuthzError,
+    SecretError,
+    SecurityError,
+    TenancyError,
+)
+from domain_security.services.authz.authz_client import Authorizer
+from domain_security.services.authz.authz_objects import Permission, PolicyDecision
+from domain_security.services.secrets.secrets_client import SecretRef
+from domain_security.services.secrets.secrets_objects import SecretValue
+
+__all__ = [
+    "Authorizer",
+    "AuthzError",
+    "Permission",
+    "PolicyDecision",
+    "Principal",
+    "SecretError",
+    "SecretRef",
+    "SecretValue",
+    "SecurityContext",
+    "SecurityContextManager",
+    "SecurityError",
+    "TenancyError",
+    "__version__",
+    "requires",
+    "tenant_scoped",
+]

domain_security/config/__init__.py

@@ -0,0 +1 @@
+"""Package configuration."""

domain_security/config/_version.py

@@ -0,0 +1,3 @@
+"""Single-source package version."""
+
+__version__ = "0.1.0"

domain_security/context/__init__.py

@@ -0,0 +1 @@
+"""Security context concern."""

domain_security/context/constants/security_context.py

@@ -0,0 +1,10 @@
+"""Security context constants. Imported as const."""
+
+from __future__ import annotations
+
+from typing import Final
+
+"""Ambient context variable name."""
+
+
+CONTEXT_VAR_NAME: Final = "domain_security_context"

domain_security/context/security_context/__init__.py

@@ -0,0 +1,11 @@
+"""Ambient security context: principal and tenant identity with set/get/bind/clear management."""
+
+from domain_security.context.security_context.security_context_client import (
+    SecurityContextManager,
+)
+from domain_security.context.security_context.security_context_objects import (
+    Principal,
+    SecurityContext,
+)
+
+__all__ = ["Principal", "SecurityContext", "SecurityContextManager"]

domain_security/context/security_context/security_context_client.py

@@ -0,0 +1,51 @@
+"""Ambient security context management across call boundaries."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import AbstractContextManager, contextmanager
+from contextvars import ContextVar, Token
+from typing import ClassVar
+
+from domain_security.context.constants import security_context as const
+from domain_security.context.security_context import security_context_objects as objs
+
+
+class SecurityContextManager:
+    """Set, read, bind, and clear the ambient security context."""
+
+    _context: ClassVar[ContextVar[objs.SecurityContext | None]] = ContextVar(
+        const.CONTEXT_VAR_NAME, default=None
+    )
+
+    def set(self, ctx: objs.SecurityContext) -> Token[objs.SecurityContext | None]:
+        """Store the context and return the reset token."""
+        return self._context.set(ctx)
+
+    def get(self) -> objs.SecurityContext | None:
+        """Return the current context, or None when unset."""
+        return self._context.get()
+
+    def bind(
+        self,
+        *,
+        principal: objs.Principal | None = None,
+        tenant_id: str | None = None,
+    ) -> AbstractContextManager[None]:
+        """Temporarily bind a fresh context, restoring the prior one on exit."""
+        return self._bound(
+            objs.SecurityContext(principal=principal, tenant_id=tenant_id)
+        )
+
+    def clear(self, token: Token[objs.SecurityContext | None]) -> None:
+        """Reset the context to its state before the matching set call."""
+        self._context.reset(token)
+
+    @contextmanager
+    def _bound(self, ctx: objs.SecurityContext) -> Generator[None, None, None]:
+        """Set the context for the with-block and reset it afterward."""
+        token = self.set(ctx)
+        try:
+            yield
+        finally:
+            self.clear(token)

domain_security/context/security_context/security_context_objects.py

@@ -0,0 +1,22 @@
+"""Security context value objects: principal identity and the context pairing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """Authenticated identity with role and scope membership."""
+
+    id: str
+    roles: frozenset[str] = frozenset()
+    scopes: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True, slots=True)
+class SecurityContext:
+    """Immutable pairing of acting principal and tenant boundary."""
+
+    principal: Principal | None
+    tenant_id: str | None

domain_security/decorators/__init__.py

@@ -0,0 +1 @@
+"""Declarative security enforcement decorators."""

domain_security/decorators/constants/tenant_scoped.py

@@ -0,0 +1,15 @@
+"""Tenant-scoped decorator constants. Imported as const."""
+
+from __future__ import annotations
+
+from typing import Final
+
+"""Sentinel selecting the instance attribute as the tenant source."""
+
+SELF_TENANT_ID: Final = "self.tenant_id"
+
+
+"""Error messages raised during tenant argument extraction (source-side; tests match against these via const.ERR_*)."""
+
+ERR_TENANT_SCOPED_UNBOUND_SELF: Final = "self.tenant_id requires a bound method call"
+ERR_TENANT_SCOPED_PARAM_MISSING: Final = "tenant parameter missing from call"

domain_security/decorators/requires/__init__.py

@@ -0,0 +1,5 @@
+"""Permission enforcement decorator."""
+
+from domain_security.decorators.requires.requires_client import Requires, requires
+
+__all__ = ["Requires", "requires"]

domain_security/decorators/requires/requires_client.py

@@ -0,0 +1,54 @@
+"""Declarative permission enforcement for service methods."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+from domain_security.context.security_context.security_context_client import (
+    SecurityContextManager,
+)
+from domain_security.context.security_context.security_context_objects import (
+    SecurityContext,
+)
+from domain_security.services.authz.authz_client import Authorizer
+from domain_security.services.authz.authz_objects import Permission
+
+Params = ParamSpec("Params")
+Return = TypeVar("Return")
+
+
+class Requires:
+    """Decorator factory enforcing a permission from the ambient security context."""
+
+    def __init__(self, authorizer: Authorizer | None = None) -> None:
+        """Store the authorizer, defaulting to the scope-based Authorizer."""
+        self._authorizer = authorizer or Authorizer()
+
+    def __call__(
+        self,
+        permission: str,
+    ) -> Callable[[Callable[Params, Return]], Callable[Params, Return]]:
+        """Return a decorator that enforces the permission before each call."""
+
+        def decorate(func: Callable[Params, Return]) -> Callable[Params, Return]:
+            @functools.wraps(func)
+            def wrapper(*args: Params.args, **kwargs: Params.kwargs) -> Return:
+                self._authorizer.require(
+                    self._current_context(), Permission(permission)
+                )
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorate
+
+    @staticmethod
+    def _current_context() -> SecurityContext:
+        """Return the ambient context, or an anonymous one when unset."""
+        current = SecurityContextManager().get()
+        return current or SecurityContext(principal=None, tenant_id=None)
+
+
+requires = Requires()

domain_security/decorators/tenant_scoped/__init__.py

@@ -0,0 +1,8 @@
+"""Tenant-boundary enforcement decorator."""
+
+from domain_security.decorators.tenant_scoped.tenant_scoped_client import (
+    TenantScoped,
+    tenant_scoped,
+)
+
+__all__ = ["TenantScoped", "tenant_scoped"]

domain_security/decorators/tenant_scoped/tenant_scoped_client.py

@@ -0,0 +1,75 @@
+"""Declarative tenant-boundary enforcement for service methods."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from domain_security.context.security_context.security_context_client import (
+    SecurityContextManager,
+)
+from domain_security.context.security_context.security_context_objects import (
+    SecurityContext,
+)
+from domain_security.decorators.constants import tenant_scoped as const
+from domain_security.errors.security_errors import TenancyError
+from domain_security.services.tenancy.tenancy_client import TenancyGuard
+
+Params = ParamSpec("Params")
+Return = TypeVar("Return")
+
+
+class TenantScoped:
+    """Decorator factory enforcing the tenant boundary from the ambient security context."""
+
+    def __init__(self, guard: TenancyGuard | None = None) -> None:
+        """Store the tenancy guard, defaulting to the standard TenancyGuard."""
+        self._guard = guard or TenancyGuard()
+
+    def __call__(
+        self,
+        param_name: str,
+    ) -> Callable[[Callable[Params, Return]], Callable[Params, Return]]:
+        """Return a decorator that checks the named tenant argument before each call."""
+
+        def decorate(func: Callable[Params, Return]) -> Callable[Params, Return]:
+            @functools.wraps(func)
+            def wrapper(*args: Params.args, **kwargs: Params.kwargs) -> Return:
+                tenant_id = self._tenant_argument(func, param_name, args, kwargs)
+                self._guard.check(self._current_context(), tenant_id)
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorate
+
+    @staticmethod
+    def _tenant_argument(
+        func: Callable[..., Any],
+        param_name: str,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> str:
+        """Extract the tenant id from the call arguments or the instance attribute."""
+        if param_name == const.SELF_TENANT_ID:
+            if not args:
+                raise TenancyError(message=const.ERR_TENANT_SCOPED_UNBOUND_SELF)
+            return str(args[0].tenant_id)
+        bound = inspect.signature(func).bind(*args, **kwargs)
+        if param_name not in bound.arguments:
+            raise TenancyError(
+                message=const.ERR_TENANT_SCOPED_PARAM_MISSING,
+                param_name=param_name,
+            )
+        return str(bound.arguments[param_name])
+
+    @staticmethod
+    def _current_context() -> SecurityContext:
+        """Return the ambient context, or an anonymous one when unset."""
+        current = SecurityContextManager().get()
+        return current or SecurityContext(principal=None, tenant_id=None)
+
+
+tenant_scoped = TenantScoped()

domain_security/errors/__init__.py

@@ -0,0 +1 @@
+"""Security error hierarchy."""

domain_security/errors/security_errors.py

@@ -0,0 +1,37 @@
+"""Typed security error hierarchy for authorization, tenancy, and secret failures."""
+
+from __future__ import annotations
+
+from domain_errors import DomainError
+
+
+class SecurityError(DomainError):
+    """Base error for all security-domain failures."""
+
+    domain = "security"
+    code = "security_error"
+    http_status = 403
+    retryable = False
+    default_message = "Security constraint violated."
+
+
+class AuthzError(SecurityError):
+    """Permission denied by authorization policy."""
+
+    code = "authz_denied"
+    default_message = "Permission denied."
+
+
+class TenancyError(SecurityError):
+    """Operation crossed or lacked a tenant boundary."""
+
+    code = "tenant_boundary_violation"
+    default_message = "Tenant boundary violation."
+
+
+class SecretError(SecurityError):
+    """Secret resolution or access failure."""
+
+    code = "secret_access_failed"
+    http_status = 500
+    default_message = "Secret access failed."

domain_security/services/__init__.py

@@ -0,0 +1 @@
+"""Security services: authorization, tenancy, secrets."""

domain_security/services/authz/__init__.py

@@ -0,0 +1,6 @@
+"""Authorization: scope-based policy evaluation over permissions and decisions."""
+
+from domain_security.services.authz.authz_client import Authorizer
+from domain_security.services.authz.authz_objects import Permission, PolicyDecision
+
+__all__ = ["Authorizer", "Permission", "PolicyDecision"]

domain_security/services/authz/authz_client.py

@@ -0,0 +1,40 @@
+"""Scope-based authorization policy evaluation."""
+
+from __future__ import annotations
+
+from domain_security.context.security_context.security_context_objects import (
+    SecurityContext,
+)
+from domain_security.errors.security_errors import AuthzError
+from domain_security.services.authz import authz_objects as objs
+from domain_security.services.constants import authz as const
+
+
+class Authorizer:
+    """Scope-based policy evaluation; subclasses override check for richer policy sources."""
+
+    def check(
+        self,
+        ctx: SecurityContext,
+        permission: objs.Permission,
+    ) -> objs.PolicyDecision:
+        """Evaluate the permission against the context and return the decision."""
+        if ctx.principal is None:
+            return objs.PolicyDecision(
+                allowed=False, reason=const.ERR_AUTHZ_NO_PRINCIPAL
+            )
+        if permission.value not in ctx.principal.scopes:
+            return objs.PolicyDecision(
+                allowed=False,
+                reason=const.ERR_AUTHZ_MISSING_SCOPE.format(scope=permission.value),
+            )
+        return objs.PolicyDecision(allowed=True)
+
+    def require(self, ctx: SecurityContext, permission: objs.Permission) -> None:
+        """Enforce the permission, raising AuthzError when denied."""
+        decision = self.check(ctx, permission)
+        if not decision.allowed:
+            raise AuthzError(
+                message=decision.reason,
+                permission=permission.value,
+            )

domain_security/services/authz/authz_objects.py

@@ -0,0 +1,20 @@
+"""Authorization value objects: permissions and policy decisions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Permission:
+    """Named permission evaluated against a principal's scopes."""
+
+    value: str
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyDecision:
+    """Allow-or-deny outcome with an optional denial rationale."""
+
+    allowed: bool
+    reason: str | None = None

domain_security/services/constants/authz.py

@@ -0,0 +1,10 @@
+"""Authorization constants. Imported as const."""
+
+from __future__ import annotations
+
+from typing import Final
+
+"""Denial reasons returned in PolicyDecision and raised via AuthzError (source-side; tests match against these via const.ERR_*)."""
+
+ERR_AUTHZ_NO_PRINCIPAL: Final = "no authenticated principal"
+ERR_AUTHZ_MISSING_SCOPE: Final = "missing scope {scope}"

domain_security/services/constants/secrets.py

@@ -0,0 +1,14 @@
+"""Secrets constants. Imported as const."""
+
+from __future__ import annotations
+
+from typing import Final
+
+"""Masked repr token for resolved secrets."""
+
+SECRET_VALUE_MASKED_REPR: Final = "<SecretValue ***>"
+
+
+"""Error messages raised during secret resolution (source-side; tests match against these via const.ERR_*)."""
+
+ERR_SECRETS_NO_BACKEND: Final = "no secrets backend provided"

domain_security/services/constants/tenancy.py

@@ -0,0 +1,10 @@
+"""Tenancy constants. Imported as const."""
+
+from __future__ import annotations
+
+from typing import Final
+
+"""Error messages raised at the tenancy boundary (source-side; tests match against these via const.ERR_*)."""
+
+ERR_TENANCY_NO_TENANT_BOUND: Final = "no tenant bound in security context"
+ERR_TENANCY_BOUNDARY_VIOLATION: Final = "tenant boundary violation"

domain_security/services/secrets/__init__.py

@@ -0,0 +1,6 @@
+"""Secrets: lazy secret resolution through a pluggable backend."""
+
+from domain_security.services.secrets.secrets_client import SecretRef
+from domain_security.services.secrets.secrets_objects import SecretsBackend, SecretValue
+
+__all__ = ["SecretRef", "SecretValue", "SecretsBackend"]

domain_security/services/secrets/secrets_client.py

@@ -0,0 +1,27 @@
+"""Secret references resolved at call time through a pluggable backend."""
+
+from __future__ import annotations
+
+from domain_errors import wrap_errors
+
+from domain_security.errors.security_errors import SecretError
+from domain_security.services.constants import secrets as const
+from domain_security.services.secrets import secrets_objects as objs
+
+
+class SecretRef:
+    """Named reference to a secret, resolved lazily against a backend."""
+
+    def __init__(self, name: str) -> None:
+        """Store the secret name for later resolution."""
+        self.name = name
+
+    @wrap_errors(SecretError, capture=False)
+    def resolve(self, backend: objs.SecretsBackend | None = None) -> objs.SecretValue:
+        """Fetch the named secret from the backend and wrap it in a SecretValue."""
+        if backend is None:
+            raise SecretError(
+                message=const.ERR_SECRETS_NO_BACKEND,
+                secret_name=self.name,
+            )
+        return objs.SecretValue(backend.fetch(self.name))

domain_security/services/secrets/secrets_objects.py

@@ -0,0 +1,29 @@
+"""Secret value objects: the backend contract and the masked resolved value."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from domain_security.services.constants import secrets as const
+
+
+class SecretsBackend(Protocol):
+    """Contract for fetching a secret's plaintext value by name."""
+
+    def fetch(self, name: str) -> str: ...
+
+
+@dataclass(frozen=True, slots=True)
+class SecretValue:
+    """Resolved secret whose value never appears in repr output."""
+
+    _value: str
+
+    def get(self) -> str:
+        """Return the plaintext secret value."""
+        return self._value
+
+    def __repr__(self) -> str:
+        """Mask the secret value."""
+        return const.SECRET_VALUE_MASKED_REPR

domain_security/services/tenancy/__init__.py

@@ -0,0 +1,5 @@
+"""Tenancy: tenant-boundary enforcement."""
+
+from domain_security.services.tenancy.tenancy_client import TenancyGuard
+
+__all__ = ["TenancyGuard"]

domain_security/services/tenancy/tenancy_client.py

@@ -0,0 +1,27 @@
+"""Tenant-boundary enforcement against the ambient security context."""
+
+from __future__ import annotations
+
+from domain_security.context.security_context.security_context_objects import (
+    SecurityContext,
+)
+from domain_security.errors.security_errors import TenancyError
+from domain_security.services.constants import tenancy as const
+
+
+class TenancyGuard:
+    """Verify that an operation stays inside the context's tenant boundary."""
+
+    def check(self, ctx: SecurityContext, tenant_id: str) -> None:
+        """Raise TenancyError unless the context is bound to the given tenant."""
+        if ctx.tenant_id is None:
+            raise TenancyError(
+                message=const.ERR_TENANCY_NO_TENANT_BOUND,
+                tenant_id=tenant_id,
+            )
+        if ctx.tenant_id != tenant_id:
+            raise TenancyError(
+                message=const.ERR_TENANCY_BOUNDARY_VIOLATION,
+                tenant_id=tenant_id,
+                context_tenant_id=ctx.tenant_id,
+            )

domain_security-0.1.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: domain-security
+Version: 0.1.0
+Summary: Cross-cutting security concerns: authorization, tenancy, secrets, context management
+Project-URL: Homepage, https://pypi.org/project/domain-security/
+Project-URL: Repository, https://github.com/jekhator/domain-security
+Project-URL: Issues, https://github.com/jekhator/domain-security/issues
+Project-URL: Changelog, https://github.com/jekhator/domain-security/blob/main/CHANGELOG.md
+Author: James Ekhator
+License: Apache-2.0
+License-File: LICENSE
+Keywords: authorization,context,secrets,security,tenancy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: domain-errors>=0.1.0
+Description-Content-Type: text/markdown
+
+# domain-security
+
+[![PyPI](https://img.shields.io/pypi/v/domain-security)](https://pypi.org/project/domain-security/)
+[![CI](https://github.com/jekhator/domain-security/actions/workflows/ci.yml/badge.svg)](https://github.com/jekhator/domain-security/actions)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+
+Ambient security context management, scope-based authorization, tenant isolation, and secrets resolution for Python services. Provides a composable foundation for authorization, tenancy enforcement, and secret handling across asynchronous and synchronous code.
+
+## Why domain-security?
+
+Authorization policies, tenant boundaries, and secret handling cut across every service. domain-security provides a single, testable foundation: bind a Principal and tenant_id once, then enforce them declaratively with decorators (`@requires`, `@tenant_scoped`) and inline checks. Context is stored in Python's ContextVar, flowing automatically through async tasks, thread pools, and call stacks. Error types inherit from domain-errors, integrating with structured logging. Secrets are resolved lazily at call time, never stored as literals. Immutable frozen dataclasses mean no accidental mutation.
+
+## Installation
+
+```bash
+pip install domain-security
+```
+
+Or with uv:
+
+```bash
+uv add domain-security
+```
+
+Requires Python 3.11+. Depends on domain-errors >= 0.1.0.
+
+## Quick Start
+
+### 1. Bind the ambient security context
+
+```python
+from domain_security import Principal, SecurityContext, SecurityContextManager
+
+# Create a principal with scopes.
+principal = Principal(id="user123", roles=frozenset(["admin"]), scopes=frozenset(["docs:read", "docs:write"]))
+ctx = SecurityContext(principal=principal, tenant_id="acme-corp")
+
+# Bind it for the duration of a request or async task.
+manager = SecurityContextManager()
+with manager.bind(principal=principal, tenant_id="acme-corp"):
+    # Context is now ambient; decorators and manual checks see it.
+    pass
+```
+
+### 2. Enforce permissions with @requires
+
+```python
+from domain_security import requires, AuthzError
+
+@requires("docs:write")
+def create_document(title: str) -> dict:
+    return {"id": "doc1", "title": title}
+
+# With context bound and the principal has the "docs:write" scope, the call succeeds.
+# Without context or if the principal lacks the scope, AuthzError is raised.
+```
+
+### 3. Enforce tenant boundaries with @tenant_scoped
+
+```python
+from domain_security import tenant_scoped, TenancyError
+
+@tenant_scoped("tenant_id")
+def delete_document(doc_id: str, tenant_id: str) -> None:
+    pass
+
+# The call succeeds only if the ambient context's tenant_id matches the argument.
+# Mismatch raises TenancyError.
+```
+
+You can also bind tenant_id to a class instance:
+
+```python
+class DocumentService:
+    def __init__(self, tenant_id: str):
+        self.tenant_id = tenant_id
+    
+    @tenant_scoped("self.tenant_id")
+    def list_documents(self) -> list:
+        return []
+```
+
+### 4. Resolve secrets at call time
+
+```python
+from domain_security import SecretRef, SecretValue, SecretError
+
+class MySecretsBackend:
+    def fetch(self, name: str) -> str:
+        if name == "api_key":
+            return "secret123"
+        raise ValueError(f"Unknown secret: {name}")
+
+ref = SecretRef("api_key")
+backend = MySecretsBackend()
+
+try:
+    secret = ref.resolve(backend)
+    # secret is a SecretValue; its repr is masked.
+    print(repr(secret))  # <SecretValue ***>
+    plaintext = secret.get()  # "secret123"
+except SecretError as e:
+    # Backend errors are wrapped as SecretError with __cause__ preserved.
+    print(f"Secret access failed: {e}")
+```
+
+### 5. Manually check permissions
+
+```python
+from domain_security import Authorizer, Permission, SecurityContext, Principal
+
+principal = Principal(id="user1", scopes=frozenset(["admin"]))
+ctx = SecurityContext(principal=principal, tenant_id="tenant1")
+
+authorizer = Authorizer()
+decision = authorizer.check(ctx, Permission("admin"))
+if not decision.allowed:
+    print(f"Denied: {decision.reason}")
+
+# If you call require() instead of check(), it raises AuthzError on denial.
+authorizer.require(ctx, Permission("admin"))
+```
+
+## Public API
+
+### SecurityContext and Principal
+
+```python
+from domain_security import SecurityContext, Principal
+
+# Frozen dataclasses; immutable after creation.
+principal = Principal(
+    id: str,                               # Principal identifier
+    roles: frozenset[str] = frozenset(),  # Role memberships
+    scopes: frozenset[str] = frozenset()  # Delegated scopes
+)
+
+ctx = SecurityContext(
+    principal: Principal | None,  # Authenticated principal (None = anonymous)
+    tenant_id: str | None         # Tenant isolation boundary
+)
+```
+
+### SecurityContextManager
+
+```python
+from domain_security import SecurityContextManager
+
+manager = SecurityContextManager()
+
+# Store context and return a reset token.
+token = manager.set(ctx)
+
+# Retrieve the current ambient context (or None).
+ctx = manager.get()
+
+# Temporarily bind a context, restoring the prior one on exit.
+with manager.bind(principal=principal, tenant_id="tenant1"):
+    # Code here runs with the bound context.
+    pass
+
+# Reset the context to the state before a matching set() call.
+manager.clear(token)
+```
+
+### Authorizer and Permission
+
+```python
+from domain_security import Authorizer, Permission, PolicyDecision
+
+authorizer = Authorizer()
+
+# Evaluate a permission against the context. Returns PolicyDecision.
+decision = authorizer.check(ctx, Permission("scope_name"))
+# decision.allowed: bool
+# decision.reason: str | None
+
+# Enforce the permission, raising AuthzError if denied.
+authorizer.require(ctx, Permission("scope_name"))  # May raise AuthzError.
+```
+
+Subclass `Authorizer` and override `check()` to implement richer policy sources (databases, external services).
+
+### SecretRef and SecretValue
+
+```python
+from domain_security import SecretRef, SecretValue, SecretError, SecretsBackend
+
+# Create a reference to a secret by name.
+ref = SecretRef(name: str)
+
+# Resolve it against a backend at call time.
+secret = ref.resolve(backend: SecretsBackend | None = None)
+# Returns: SecretValue
+# Raises: SecretError if backend is None or fetch() fails
+
+# Read the plaintext secret.
+plaintext = secret.get() -> str
+
+# repr() masks the value to prevent accidental logging.
+repr(secret)  # <SecretValue ***>
+```
+
+Implement `SecretsBackend` as a Protocol:
+
+```python
+class MySecretsBackend:
+    def fetch(self, name: str) -> str:
+        # Return the plaintext secret or raise any exception.
+        # Exceptions are wrapped as SecretError.
+        ...
+```
+
+### Decorators
+
+```python
+from domain_security import requires, tenant_scoped
+
+# Enforce a permission before the decorated method runs.
+@requires("permission_name")
+def my_method() -> None:
+    pass
+
+# Enforce a tenant boundary using a named argument or self.tenant_id.
+@tenant_scoped("tenant_id")
+def another_method(tenant_id: str) -> None:
+    pass
+
+@tenant_scoped("self.tenant_id")  # Binds to the instance's tenant_id attribute.
+def instance_method(self) -> None:
+    pass
+```
+
+Both decorators read the ambient context. No principal or missing scope/tenant raises the corresponding error.
+
+### Error Types
+
+```python
+from domain_security import SecurityError, AuthzError, TenancyError, SecretError
+
+# Base error for all security-domain failures.
+# Subclasses DomainError; code="security_error", http_status=403
+class SecurityError(DomainError):
+    pass
+
+# Permission denied by authorization policy.
+# code="authz_denied", http_status=403
+class AuthzError(SecurityError):
+    pass
+
+# Operation crossed or lacked a tenant boundary.
+# code="tenant_boundary_violation", http_status=403
+class TenancyError(SecurityError):
+    pass
+
+# Secret resolution or access failure.
+# code="secret_access_failed", http_status=500
+class SecretError(SecurityError):
+    pass
+```
+
+All errors preserve `__cause__` when wrapping exceptions, integrate with domain-errors' structured logging, and carry typed context parameters.
+
+## Documentation
+
+For detailed documentation on each feature, see:
+
+- [SecurityContext and SecurityContextManager](docs/apps/security_context.md)
+- [Authorization with Authorizer and @requires](docs/apps/authz.md)
+- [Tenant Isolation with TenancyGuard and @tenant_scoped](docs/apps/tenancy.md)
+- [Secrets Management with SecretRef and SecretValue](docs/apps/secrets.md)
+- [@requires decorator](docs/apps/requires.md)
+- [@tenant_scoped decorator](docs/apps/tenant_scoped.md)
+- [Error Types and Semantics](docs/apps/security_errors.md)
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+This library is maintained by [James Ekhator](https://github.com/jekhator). Contributions welcome via pull requests. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.

domain_security-0.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+domain_security/__init__.py,sha256=8abW5yj7FwxNQM8DmPinpkPjoYyX2YkC3KiB2UnEsDE,1269
+domain_security/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+domain_security/config/__init__.py,sha256=GIjb9cYcaJ1Q9vRzF7_daH_S5KLOeg_oLGfPIhmn7A0,29
+domain_security/config/_version.py,sha256=GtsljaQReBaQusaK0Zmip2AM7BWtdesXvaMQz35Aiic,60
+domain_security/context/__init__.py,sha256=jBc3lgcpZcinvzyWX24GWzGdHUF48v3vbM-Lnppegi8,32
+domain_security/context/constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+domain_security/context/constants/security_context.py,sha256=mL-pmG_n8KLaGhd6-17P2eRq1qGB5Qvp4-4O5K2zQDU,207
+domain_security/context/security_context/__init__.py,sha256=Qa-yH2VN4FT962eN8mS5ls51k9f-LRRhT8rnFVC8l4U,396
+domain_security/context/security_context/security_context_client.py,sha256=SyoDRhRaqMFsgW5-7tNXJzKSR56FOTlkepkAIkZtUIw,1817
+domain_security/context/security_context/security_context_objects.py,sha256=4lELYDRCxrUMoED-Hy3QrsbqWXzsTgc47zEIa7jYRgw,556
+domain_security/decorators/__init__.py,sha256=cpiruiIb4KAbSUlbtmShjLu4MPFGMVqKHbwhkZfxbpI,51
+domain_security/decorators/constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+domain_security/decorators/constants/tenant_scoped.py,sha256=zzJM2dB4JI_tzgDAou5jz91J2pSOWTrhXMIzsXdKbKY,522
+domain_security/decorators/requires/__init__.py,sha256=Ffm1q29OK2YOpAZiPfVbCsPhFuMQ6jTdULA7iKz8ZoY,160
+domain_security/decorators/requires/requires_client.py,sha256=B0SeRJc0mzoS6cWAkm3AHkZEWN9MTOA3zR9sIi-BJ6E,1825
+domain_security/decorators/tenant_scoped/__init__.py,sha256=2EMfqnL1dcRUlkPn7TIp_abUYjJxLNyjcoaczEdgzk4,206
+domain_security/decorators/tenant_scoped/tenant_scoped_client.py,sha256=uQVpAee5Mow35xeMwEo1LfMlTNRTvYiaTdnOw8JoWuo,2735
+domain_security/errors/__init__.py,sha256=yREQYr5oTV--15hlU56oj8nGMFu_s8WvW50zhecKGqE,32
+domain_security/errors/security_errors.py,sha256=Ih_GMPHNF8LnbWOvyN00wXeVrxzXmVhqAPyRBo8UBeM,932
+domain_security/services/__init__.py,sha256=6T1lDshJOmkmVZ1Ik-RwKMpsMY0wSt62FRJbGw34le8,58
+domain_security/services/authz/__init__.py,sha256=kg1hzJnB8H7k3DQRq3C4SN2HijVHFhJO_CTcR_2MlN8,293
+domain_security/services/authz/authz_client.py,sha256=I7_tWK5PhcMwTXk0dQHdWPnsoEqnVxVoD_8C6jZ4SyU,1498
+domain_security/services/authz/authz_objects.py,sha256=3Qy67LrQhHez8LRxDIsT-zSXyAdiQquhwO2DFre4WfE,455
+domain_security/services/constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+domain_security/services/constants/authz.py,sha256=yk887RfA1G6EkBgzNzLY8yx7alozZPabZ-EtvyzN_RA,364
+domain_security/services/constants/secrets.py,sha256=ZytAFYnRMVVtMllAYRImI0yZVFuaz7_SyLZqmCmHQsI,384
+domain_security/services/constants/tenancy.py,sha256=6k8g2eXgXieg-JWdzAiLnZ2bfbt_HLHxAPWGC_GAp64,361
+domain_security/services/secrets/__init__.py,sha256=JmY85LYKguaQcUBaLkc_D7NcifgRfwG7_ngeMfcROVk,285
+domain_security/services/secrets/secrets_client.py,sha256=bsNiCe-InFj4YDMumDxTnR8r_JtCasn3GOm-ri9xz_k,1008
+domain_security/services/secrets/secrets_objects.py,sha256=HiT_vF3czmaEPVaeAh2ikxOotCcOMB6P4GzTr3a7e_o,750
+domain_security/services/tenancy/__init__.py,sha256=-UOJdAQrJWvefkby-H5KwDazdygijzZa0b-KgR29NH4,146
+domain_security/services/tenancy/tenancy_client.py,sha256=vnvBy4O2OKWcxlwgBhxuh6IZ8MliiSbuCs3SYrf3ltI,1000
+domain_security-0.1.0.dist-info/METADATA,sha256=ZhsItmQRhq3wwlsgfkaUE-0SIPdAk0F76vN13--P0X0,9995
+domain_security-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+domain_security-0.1.0.dist-info/licenses/LICENSE,sha256=afJnNvtqk-WIQDM8aNaqfuYQifp27Wa0Q5j5P_Aj_gQ,11343
+domain_security-0.1.0.dist-info/RECORD,,

domain_security-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

domain_security-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 James Ekhator
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.