hexastack-auth 0.0.0__py3-none-any.whl

hexastack_auth/__init__.py

@@ -0,0 +1,8 @@
+from hexastack_auth import adapters, domain, infra, ports
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+    "ports",
+]

hexastack_auth/adapters/__init__.py

@@ -0,0 +1,21 @@
+from hexastack_auth.adapters.grpc import AuthServerInterceptor
+from hexastack_auth.adapters.in_memory import (
+    InMemoryPasswordHasher,
+    InMemorySecurityService,
+)
+from hexastack_auth.adapters.jwt import JwtSecurityAdapter
+from hexastack_auth.adapters.opa import OpaPolicyAdapter
+from hexastack_auth.adapters.openfga import OpenFgaPolicyAdapter
+from hexastack_auth.adapters.password import Pbkdf2PasswordHasher
+from hexastack_auth.adapters.spiffe import SpiffeWorkloadAdapter
+
+__all__ = [
+    "AuthServerInterceptor",
+    "InMemoryPasswordHasher",
+    "InMemorySecurityService",
+    "JwtSecurityAdapter",
+    "OpaPolicyAdapter",
+    "OpenFgaPolicyAdapter",
+    "Pbkdf2PasswordHasher",
+    "SpiffeWorkloadAdapter",
+]

hexastack_auth/adapters/fastapi.py

@@ -0,0 +1,136 @@
+"""FastAPI route guard dependencies for hexastack-auth (OPA & OpenFGA).
+
+Notes/Architectural Intent:
+    Provides direct HTTP route-level policy and relationship guards for FastAPI.
+    FastAPI is an optional dependency of hexastack-auth[fastapi].
+"""
+
+import importlib.util
+from typing import Any
+
+from hexastack_auth.domain.models import Identity
+from hexastack_auth.ports.policy import AuthorizationPolicyPort
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.utils.context import get_user_context
+
+__all__ = [
+    "require_policy",
+    "require_relation",
+]
+
+
+def _require_fastapi() -> None:
+    if importlib.util.find_spec("fastapi") is None:
+        raise MissingDependencyError(
+            "fastapi is required for FastAPI auth dependencies. "
+            "Install with 'pip install hexastack-auth[fastapi]'."
+        )
+
+
+def require_policy(
+    policy_path: str,
+    *,
+    resource: str = "http_request",
+    status_code: int = 403,
+    detail: str | None = None,
+) -> Any:
+    """FastAPI route guard dependency enforcing an OPA or custom policy check.
+
+    Args:
+        policy_path: OPA policy endpoint (e.g. 'v1/data/reports/view').
+        resource: Target resource string.
+        status_code: HTTP status code to return when denied (defaults to 403).
+        detail: Custom error detail message.
+
+    Returns:
+        FastAPI async dependency callable.
+    """
+    _require_fastapi()
+    from fastapi import HTTPException, Request
+
+    async def _dependency(request: Request) -> None:
+        container = getattr(request.app.state, "container", None)
+        if container is None or AuthorizationPolicyPort not in container:
+            raise HTTPException(
+                status_code=500,
+                detail="AuthorizationPolicyPort is not configured in DI container.",
+            )
+
+        policy_port = container.resolve(AuthorizationPolicyPort)
+        user_ctx = get_user_context()
+        identity = Identity(
+            user_id=user_ctx.user_id if user_ctx else "anonymous",
+            roles=frozenset(user_ctx.roles if user_ctx else ()),
+            tenant_id=user_ctx.tenant_id if user_ctx else None,
+            is_authenticated=bool(user_ctx and user_ctx.user_id),
+        )
+
+        allowed = policy_port.is_authorized(
+            identity=identity,
+            action=policy_path,
+            resource=resource,
+            context={"url": str(request.url), "method": request.method},
+        )
+        if not allowed:
+            raise HTTPException(
+                status_code=status_code,
+                detail=detail or f"Access denied by policy '{policy_path}'.",
+            )
+
+    return _dependency
+
+
+def require_relation(
+    relation: str,
+    object_type: str,
+    object_id: str | None = None,
+    *,
+    status_code: int = 403,
+    detail: str | None = None,
+) -> Any:
+    """FastAPI route guard dependency enforcing an OpenFGA relationship check.
+
+    Args:
+        relation: OpenFGA relationship name (e.g. 'can_edit', 'viewer').
+        object_type: Target object type (e.g. 'document', 'project').
+        object_id: Explicit object identifier or None.
+        status_code: HTTP status code to return when denied (defaults to 403).
+        detail: Custom error detail message.
+
+    Returns:
+        FastAPI async dependency callable.
+    """
+    _require_fastapi()
+    from fastapi import HTTPException, Request
+
+    async def _dependency(request: Request) -> None:
+        container = getattr(request.app.state, "container", None)
+        if container is None or AuthorizationPolicyPort not in container:
+            raise HTTPException(
+                status_code=500,
+                detail="AuthorizationPolicyPort is not configured in DI container.",
+            )
+
+        policy_port = container.resolve(AuthorizationPolicyPort)
+        user_ctx = get_user_context()
+        identity = Identity(
+            user_id=user_ctx.user_id if user_ctx else "anonymous",
+            roles=frozenset(user_ctx.roles if user_ctx else ()),
+            tenant_id=user_ctx.tenant_id if user_ctx else None,
+            is_authenticated=bool(user_ctx and user_ctx.user_id),
+        )
+
+        target_obj = f"{object_type}:{object_id or 'default'}"
+        allowed = policy_port.is_authorized(
+            identity=identity,
+            action=relation,
+            resource=target_obj,
+        )
+        if not allowed:
+            raise HTTPException(
+                status_code=status_code,
+                detail=detail
+                or f"Access denied: missing '{relation}' on '{target_obj}'.",
+            )
+
+    return _dependency

hexastack_auth/adapters/grpc.py

@@ -0,0 +1,100 @@
+"""gRPC Server Interceptors and security helpers for hexastack-auth.
+
+Notes/Architectural Intent:
+    Extracts Bearer tokens or SPIFFE JWT-SVIDs from gRPC invocation metadata,
+    validates them against SecurityPort or WorkloadIdentityPort, and establishes
+    the ambient UserContext for the duration of the RPC.
+"""
+
+import importlib.util
+from collections.abc import Callable
+from typing import Any
+
+from hexastack_auth.ports.security import SecurityPort
+from hexastack_auth.ports.workload import WorkloadIdentityPort
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.utils.context import UserContext, set_user_context
+
+__all__ = [
+    "AuthServerInterceptor",
+]
+
+
+class AuthServerInterceptor:
+    """gRPC server interceptor extracting credentials from metadata into UserContext."""
+
+    def __init__(
+        self,
+        security_port: SecurityPort | None = None,
+        workload_port: WorkloadIdentityPort | None = None,
+        *,
+        auth_header: str = "authorization",
+        spiffe_header: str = "x-spiffe-id",
+        required: bool = False,
+    ) -> None:
+        _require_grpc()
+        self._security_port = security_port
+        self._workload_port = workload_port
+        self._auth_header = auth_header.lower()
+        self._spiffe_header = spiffe_header.lower()
+        self._required = required
+
+    def intercept_service(
+        self,
+        continuation: Callable[[Any], Any],
+        handler_call_details: Any,
+    ) -> Any:
+        """Inspect invocation metadata and populate ambient UserContext."""
+        import grpc
+
+        metadata = dict(getattr(handler_call_details, "invocation_metadata", ()))
+        token = metadata.get(self._auth_header)
+        spiffe_id = metadata.get(self._spiffe_header)
+
+        user_ctx: UserContext | None = None
+
+        if token and self._security_port:
+            raw_token = token.removeprefix("Bearer ").strip()
+            try:
+                identity = self._security_port.verify_token(raw_token)
+                user_ctx = UserContext(
+                    user_id=identity.user_id,
+                    roles=list(identity.roles),
+                    tenant_id=identity.tenant_id,
+                )
+            except Exception:
+                if self._required:
+                    return grpc.unary_unary_rpc_method_handler(
+                        lambda _req, ctx: ctx.abort(
+                            grpc.StatusCode.UNAUTHENTICATED,
+                            "Invalid or expired security token",
+                        )
+                    )
+
+        elif spiffe_id and self._workload_port:
+            user_ctx = UserContext(
+                user_id=spiffe_id,
+                roles=["workload"],
+                tenant_id=None,
+            )
+
+        elif self._required:
+            return grpc.unary_unary_rpc_method_handler(
+                lambda _req, ctx: ctx.abort(
+                    grpc.StatusCode.UNAUTHENTICATED,
+                    "Authentication credentials are required",
+                )
+            )
+
+        if user_ctx is not None:
+            set_user_context(user_ctx)
+
+        return continuation(handler_call_details)
+
+
+def _require_grpc() -> None:
+    if importlib.util.find_spec("grpc") is None:
+        raise MissingDependencyError(
+            "grpc is required for gRPC auth interceptor. "
+            "Install with 'pip install hexastack-auth[grpc]'."
+        )

hexastack_auth/adapters/in_memory.py

@@ -0,0 +1,101 @@
+import secrets
+import time
+from datetime import timedelta
+
+from hexastack_auth.domain.exceptions import (
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from hexastack_auth.domain.models import Identity
+from hexastack_auth.ports.password import PasswordHasherPort
+from hexastack_auth.ports.security import SecurityPort
+
+
+class InMemorySecurityService(SecurityPort):
+    """In-memory security service implementation for fast, isolated testing.
+
+    Notes/Architectural Intent:
+        Stores issued tokens in a local dictionary with expiration timestamps.
+        Eliminates cryptographic overhead in unit and property tests.
+    """
+
+    def __init__(self, default_ttl_seconds: int = 3600) -> None:
+        """Initialize in-memory token store."""
+        self._default_ttl_seconds = default_ttl_seconds
+        self._tokens: dict[str, tuple[Identity, float | None]] = {}
+
+    def clear(self) -> None:
+        """Clear all stored tokens."""
+        self._tokens.clear()
+
+    def create_token(
+        self,
+        identity: Identity,
+        *,
+        ttl: timedelta | int | None = None,
+    ) -> str:
+        """Store identity and return a unique token key.
+
+        Args:
+            identity: Identity to associate with token.
+            ttl: Optional TTL duration or seconds.
+
+        Returns:
+            Opaque token string.
+        """
+        token = f"mem_token_{secrets.token_urlsafe(24)}"
+        if ttl is None:
+            ttl_secs = self._default_ttl_seconds
+        elif isinstance(ttl, timedelta):
+            ttl_secs = int(ttl.total_seconds())
+        else:
+            ttl_secs = ttl
+
+        exp_time = time.time() + ttl_secs if ttl_secs is not None else None
+        self._tokens[token] = (identity, exp_time)
+        return token
+
+    def verify_token(self, token: str) -> Identity:
+        """Look up identity by token key and check expiration.
+
+        Args:
+            token: Opaque token string.
+
+        Returns:
+            Associated Identity.
+
+        Raises:
+            InvalidTokenError: If token does not exist.
+            TokenExpiredError: If token has expired.
+        """
+        if not token or token not in self._tokens:
+            raise InvalidTokenError(f"Token '{token}' not recognized.")
+
+        identity, exp_time = self._tokens[token]
+        if exp_time is not None and time.time() > exp_time:
+            del self._tokens[token]
+            raise TokenExpiredError("In-memory token has expired.")
+
+        return identity
+
+
+class InMemoryPasswordHasher(PasswordHasherPort):
+    """In-memory password hasher for rapid unit testing without key derivation delay.
+
+    Notes/Architectural Intent:
+        Prefixes plain password with 'mock_hash:' for instantaneous test execution.
+    """
+
+    def hash_password(self, plain_password: str) -> str:
+        """Return a mock hashed password string."""
+        return f"mock_hash:{plain_password}"
+
+    def verify_password(self, plain_password: str, hashed_password: str) -> bool:
+        """Verify plain password matches mock hash."""
+        return hashed_password == f"mock_hash:{plain_password}"
+
+
+__all__ = [
+    "InMemoryPasswordHasher",
+    "InMemorySecurityService",
+]

hexastack_auth/adapters/jwt.py

@@ -0,0 +1,159 @@
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+
+from hexastack_auth.domain.exceptions import (
+    AuthError,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from hexastack_auth.domain.models import Identity
+from hexastack_auth.ports.security import SecurityPort
+
+
+class JwtSecurityAdapter(SecurityPort):
+    """Concrete token security adapter implementing SecurityPort using PyJWT.
+
+    Notes/Architectural Intent:
+        Implements industry-standard JSON Web Token encoding and cryptographic signature
+        validation. Maps PyJWT exception hierarchies into clean Hexastack domain errors.
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        algorithm: str = "HS256",
+        default_ttl_seconds: int = 3600,
+        issuer: str | None = None,
+        audience: str | None = None,
+    ) -> None:
+        """Initialize JWT security adapter.
+
+        Args:
+            secret_key: Secret key or private key for signing tokens.
+            algorithm: Cryptographic algorithm (default 'HS256').
+            default_ttl_seconds: Default expiration lifespan in seconds (default 3600).
+            issuer: Optional expected token issuer string ('iss').
+            audience: Optional expected token audience string ('aud').
+        """
+        self._secret_key = secret_key
+        self._algorithm = algorithm
+        self._default_ttl = timedelta(seconds=default_ttl_seconds)
+        self._issuer = issuer
+        self._audience = audience
+
+    def create_token(
+        self,
+        identity: Identity,
+        *,
+        ttl: timedelta | int | None = None,
+    ) -> str:
+        """Issue a signed JWT token for the given identity.
+
+        Args:
+            identity: Identity to encode into claims.
+            ttl: Optional TTL duration or seconds override.
+
+        Returns:
+            Signed JWT string.
+
+        Raises:
+            AuthError: If encoding fails.
+        """
+        now = datetime.now(UTC)
+        if ttl is None:
+            effective_ttl = self._default_ttl
+        elif isinstance(ttl, int):
+            effective_ttl = timedelta(seconds=ttl)
+        else:
+            effective_ttl = ttl
+
+        exp = now + effective_ttl
+        payload: dict[str, Any] = {
+            "sub": identity.user_id,
+            "roles": sorted(identity.roles),
+            "permissions": sorted(identity.permissions),
+            "iat": int(now.timestamp()),
+            "exp": int(exp.timestamp()),
+        }
+
+        if identity.tenant_id is not None:
+            payload["tenant_id"] = identity.tenant_id
+
+        if self._issuer is not None:
+            payload["iss"] = self._issuer
+
+        if self._audience is not None:
+            payload["aud"] = self._audience
+
+        # Merge custom claims without overwriting standard registered claims
+        for k, v in identity.claims.items():
+            if k not in payload:
+                payload[k] = v
+
+        try:
+            return jwt.encode(payload, self._secret_key, algorithm=self._algorithm)
+        except Exception as exc:
+            raise AuthError(f"JWT signing failed: {exc}") from exc
+
+    def verify_token(self, token: str) -> Identity:
+        """Decode and verify a JWT token, reconstructing the Identity.
+
+        Args:
+            token: The raw JWT string.
+
+        Returns:
+            Verified Identity domain instance.
+
+        Raises:
+            TokenExpiredError: If the token has expired.
+            InvalidTokenError: If the signature or structure is invalid.
+            AuthError: If general verification fails.
+        """
+        if not token:
+            raise InvalidTokenError("Token string cannot be empty.")
+
+        options = {"verify_exp": True}
+        kwargs: dict[str, Any] = {
+            "key": self._secret_key,
+            "algorithms": [self._algorithm],
+            "options": options,
+        }
+
+        if self._issuer is not None:
+            kwargs["issuer"] = self._issuer
+        if self._audience is not None:
+            kwargs["audience"] = self._audience
+
+        try:
+            claims: dict[str, Any] = jwt.decode(token, **kwargs)
+        except jwt.ExpiredSignatureError as exc:
+            raise TokenExpiredError(f"JWT token expired: {exc}") from exc
+        except jwt.PyJWTError as exc:
+            raise InvalidTokenError(f"Invalid JWT token: {exc}") from exc
+        except Exception as exc:
+            raise AuthError(f"JWT token verification failed: {exc}") from exc
+
+        sub = claims.get("sub")
+        if not sub:
+            raise InvalidTokenError("JWT token missing required 'sub' claim.")
+
+        roles = frozenset(claims.get("roles", []))
+        permissions = frozenset(claims.get("permissions", []))
+        tenant_id = claims.get("tenant_id")
+
+        return Identity(
+            user_id=str(sub),
+            roles=roles,
+            permissions=permissions,
+            tenant_id=str(tenant_id) if tenant_id is not None else None,
+            claims=claims,
+            is_authenticated=True,
+        )
+
+
+__all__ = [
+    "JwtSecurityAdapter",
+]

hexastack_auth/adapters/opa/__init__.py

@@ -0,0 +1,5 @@
+from hexastack_auth.adapters.opa.policy import OpaPolicyAdapter
+
+__all__ = [
+    "OpaPolicyAdapter",
+]

hexastack_auth/adapters/opa/policy.py

@@ -0,0 +1,88 @@
+"""Open Policy Agent (OPA) policy evaluation adapter.
+
+Notes/Architectural Intent:
+    Evaluates policy queries against OPA's HTTP Data API (v1/data/{policy_path}).
+    Passes user identity, roles, permissions, tenant_id, action, resource, and extra context.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from hexastack_auth.domain.models import Identity
+from hexastack_auth.ports.policy import AuthorizationPolicyPort
+from hexastack_core.domain.exceptions import MissingDependencyError
+
+__all__ = [
+    "OpaPolicyAdapter",
+]
+
+
+class OpaPolicyAdapter(AuthorizationPolicyPort):
+    """AuthorizationPolicyPort implementation querying Open Policy Agent (OPA)."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8181",
+        default_policy_path: str = "v1/data/authz/allow",
+        timeout: float = 3.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.default_policy_path = default_policy_path.strip("/")
+        self.timeout = timeout
+
+    def is_authorized(
+        self,
+        identity: Identity,
+        action: str,
+        resource: str,
+        *,
+        context: Mapping[str, Any] | None = None,
+    ) -> bool:
+        """Evaluate policy rule against OPA REST Data API."""
+        try:
+            import httpx
+        except ImportError as e:
+            raise MissingDependencyError(
+                "httpx is required for OpaPolicyAdapter. "
+                "Install with 'pip install hexastack-auth[opa]'."
+            ) from e
+
+        # Determine target policy path (use action if it starts with 'v1/data/' or 'policies/')
+        policy_path = (
+            action.strip("/")
+            if action.startswith("v1/data/") or action.startswith("policies/")
+            else self.default_policy_path
+        )
+        url = f"{self.base_url}/{policy_path}"
+
+        input_payload = {
+            "input": {
+                "identity": {
+                    "user_id": identity.user_id,
+                    "tenant_id": identity.tenant_id,
+                    "roles": list(identity.roles),
+                    "permissions": list(identity.permissions),
+                    "claims": dict(identity.claims),
+                    "is_authenticated": identity.is_authenticated,
+                },
+                "action": action,
+                "resource": resource,
+                "context": dict(context or {}),
+            }
+        }
+
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.post(url, json=input_payload)
+                if response.status_code != 200:
+                    return False
+
+                data = response.json()
+                result = data.get("result")
+                if isinstance(result, bool):
+                    return result
+                if isinstance(result, dict):
+                    return bool(result.get("allow", False))
+                return bool(result)
+        except Exception:
+            return False

hexastack_auth/adapters/openfga/__init__.py

@@ -0,0 +1,5 @@
+from hexastack_auth.adapters.openfga.policy import OpenFgaPolicyAdapter
+
+__all__ = [
+    "OpenFgaPolicyAdapter",
+]