svc-infra 0.1.706__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/security/__init__.py

@@ -0,0 +1,167 @@
+"""Security module providing authentication, authorization, and protection utilities.
+
+This module provides comprehensive security primitives:
+
+- **Middleware**: Security headers (CSP, HSTS, etc.) and CORS configuration
+- **Lockout**: Account lockout with exponential backoff for brute force protection
+- **Passwords**: Password policy validation with HIBP breach checking
+- **Sessions**: Session and refresh token management
+- **Audit**: Hash-chain audit logging for tamper detection
+- **JWT Rotation**: Seamless JWT key rotation support
+- **Permissions**: RBAC and ABAC authorization helpers
+- **Signed Cookies**: Cryptographically signed cookies with expiry
+
+Example:
+    from fastapi import FastAPI
+    from svc_infra.security import add_security
+
+    app = FastAPI()
+
+    # Add security headers and CORS
+    add_security(app, cors_origins=["https://myapp.com"])
+
+    # Use password validation
+    from svc_infra.security import validate_password, PasswordPolicy
+
+    policy = PasswordPolicy(min_length=12, require_symbol=True)
+    validate_password("MyStr0ng!Pass", policy)
+
+    # Use lockout protection
+    from svc_infra.security import get_lockout_status, LockoutConfig
+
+    status = await get_lockout_status(session, user_id=user.id, ip_hash=ip_hash)
+    if status.locked:
+        raise HTTPException(429, "Too many attempts")
+
+Environment Variables:
+    CORS_ALLOW_ORIGINS: Comma-separated list of allowed origins
+    CORS_ALLOW_CREDENTIALS: Allow credentials in CORS (true/false)
+    CORS_ALLOW_METHODS: Comma-separated list of allowed methods
+    CORS_ALLOW_HEADERS: Comma-separated list of allowed headers
+
+See Also:
+    - docs/security.md for detailed documentation
+    - svc_infra.api.fastapi.auth for authentication routes
+"""
+
+from __future__ import annotations
+
+# FastAPI integration
+from .add import add_security
+
+# Audit logging
+from .audit import (
+    AuditEvent,
+    AuditLogStore,
+    InMemoryAuditLogStore,
+    append_audit_event,
+    verify_audit_chain,
+)
+from .audit_service import append_event, verify_chain_for_tenant
+
+# Security headers middleware
+from .headers import SECURE_DEFAULTS, SecurityHeadersMiddleware
+
+# HIBP breach checking
+from .hibp import HIBPClient
+
+# JWT rotation
+from .jwt_rotation import RotatingJWTStrategy
+
+# Account lockout
+from .lockout import (
+    LockoutConfig,
+    LockoutStatus,
+    compute_lockout,
+    get_lockout_status,
+    record_attempt,
+)
+
+# Models (for type hints and direct use)
+from .models import (
+    AuditLog,
+    AuthSession,
+    FailedAuthAttempt,
+    RefreshToken,
+    RefreshTokenRevocation,
+    compute_audit_hash,
+)
+
+# Password validation
+from .passwords import (
+    PasswordPolicy,
+    PasswordValidationError,
+    configure_breached_checker,
+    validate_password,
+)
+
+# RBAC/ABAC permissions
+from .permissions import (
+    PERMISSION_REGISTRY,
+    RequireABAC,
+    RequireAnyPermission,
+    RequirePermission,
+    enforce_abac,
+    extend_role,
+    get_permissions_for_roles,
+    has_permission,
+    owns_resource,
+    principal_permissions,
+    register_role,
+)
+
+# Signed cookies
+from .signed_cookies import sign_cookie, verify_cookie
+
+__all__ = [
+    # FastAPI integration
+    "add_security",
+    # Headers middleware
+    "SecurityHeadersMiddleware",
+    "SECURE_DEFAULTS",
+    # Lockout
+    "LockoutConfig",
+    "LockoutStatus",
+    "compute_lockout",
+    "record_attempt",
+    "get_lockout_status",
+    # Password validation
+    "PasswordPolicy",
+    "PasswordValidationError",
+    "validate_password",
+    "configure_breached_checker",
+    # HIBP
+    "HIBPClient",
+    # Signed cookies
+    "sign_cookie",
+    "verify_cookie",
+    # Audit logging
+    "AuditLogStore",
+    "AuditEvent",
+    "append_audit_event",
+    "verify_audit_chain",
+    "append_event",
+    "verify_chain_for_tenant",
+    "InMemoryAuditLogStore",
+    # JWT rotation
+    "RotatingJWTStrategy",
+    # Permissions (RBAC/ABAC)
+    "PERMISSION_REGISTRY",
+    "register_role",
+    "extend_role",
+    "get_permissions_for_roles",
+    "principal_permissions",
+    "has_permission",
+    "RequirePermission",
+    "RequireAnyPermission",
+    "RequireABAC",
+    "enforce_abac",
+    "owns_resource",
+    # Models
+    "AuthSession",
+    "RefreshToken",
+    "RefreshTokenRevocation",
+    "FailedAuthAttempt",
+    "AuditLog",
+    "compute_audit_hash",
+]

svc_infra/security/add.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import os
-from collections.abc import Mapping
-from typing import Iterable, Literal, cast
+from collections.abc import Iterable, Mapping
+from typing import Literal, cast
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -138,9 +138,7 @@ def _configure_session_middleware(
     )
     https_env = _parse_bool(env.get("SESSION_COOKIE_SECURE"))
     effective_https_only = (
-        https_only
-        if https_only is not None
-        else (https_env if https_env is not None else False)
+        https_only if https_only is not None else (https_env if https_env is not None else False)
     )
     same_site_env = env.get("SESSION_COOKIE_SAMESITE")
     same_site_raw = same_site_env.strip() if same_site_env else same_site
@@ -148,7 +146,7 @@ def _configure_session_middleware(
     same_site_value: Literal["lax", "strict", "none"] = (
         "lax"
         if same_site_raw not in ("lax", "strict", "none")
-        else cast(Literal["lax", "strict", "none"], same_site_raw)
+        else cast("Literal['lax', 'strict', 'none']", same_site_raw)
     )
 
     max_age_env = env.get("SESSION_COOKIE_MAX_AGE_SECONDS")
@@ -158,9 +156,7 @@ def _configure_session_middleware(
         max_age_value = max_age
 
     session_cookie_env = env.get("SESSION_COOKIE_NAME")
-    session_cookie_value = (
-        session_cookie_env.strip() if session_cookie_env else session_cookie
-    )
+    session_cookie_value = session_cookie_env.strip() if session_cookie_env else session_cookie
 
     app.add_middleware(
         SessionMiddleware,

svc_infra/security/audit.py

@@ -13,9 +13,10 @@ Design notes:
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Any, List, Optional, Protocol, Sequence, Tuple
+from datetime import UTC, datetime
+from typing import Any, Protocol
 
 try:  # SQLAlchemy may not be present in minimal test context
     from sqlalchemy import select
@@ -81,7 +82,7 @@ class InMemoryAuditLogStore:
         ts: datetime | None = None,
     ) -> AuditEvent:
         event = AuditEvent(
-            ts=ts or datetime.now(timezone.utc),
+            ts=ts or datetime.now(UTC),
             actor_id=actor_id,
             tenant_id=tenant_id,
             event_type=event_type,
@@ -91,9 +92,7 @@ class InMemoryAuditLogStore:
         self._events.append(event)
         return event
 
-    def list(
-        self, *, tenant_id: str | None = None, limit: int | None = None
-    ) -> list[AuditEvent]:
+    def list(self, *, tenant_id: str | None = None, limit: int | None = None) -> list[AuditEvent]:
         out = [e for e in self._events if tenant_id is None or e.tenant_id == tenant_id]
         if limit is not None:
             return out[-int(limit) :]
@@ -104,12 +103,12 @@ async def append_audit_event(
     db: Any,
     *,
     actor_id=None,
-    tenant_id: Optional[str] = None,
+    tenant_id: str | None = None,
     event_type: str,
-    resource_ref: Optional[str] = None,
+    resource_ref: str | None = None,
     metadata: dict | None = None,
-    ts: Optional[datetime] = None,
-    prev_event: Optional[AuditLog] = None,
+    ts: datetime | None = None,
+    prev_event: AuditLog | None = None,
 ) -> AuditLog:
     """Append an audit event returning the persisted row.
 
@@ -117,14 +116,12 @@ async def append_audit_event(
     the tenant (or global chain when tenant_id is None).
     """
     metadata = metadata or {}
-    ts = ts or datetime.now(timezone.utc)
+    ts = ts or datetime.now(UTC)
 
-    prev_hash: Optional[str] = None
+    prev_hash: str | None = None
     if prev_event is not None:
         prev_hash = prev_event.hash
-    elif select is not None and hasattr(
-        db, "execute"
-    ):  # attempt DB lookup for previous event
+    elif select is not None and hasattr(db, "execute"):  # attempt DB lookup for previous event
         try:
             stmt = (
                 select(AuditLog)
@@ -172,14 +169,14 @@ async def append_audit_event(
     return row
 
 
-def verify_audit_chain(events: Sequence[AuditLog]) -> Tuple[bool, List[int]]:
+def verify_audit_chain(events: Sequence[AuditLog]) -> tuple[bool, list[int]]:
     """Verify a sequence of audit events.
 
     Returns (ok, broken_indices). If any event's hash doesn't match the recomputed
     expected hash (based on previous event), its index is recorded. All events are
     checked so callers can analyze extent of tampering.
     """
-    broken: List[int] = []
+    broken: list[int] = []
     prev_hash = "0" * 64
     for idx, ev in enumerate(events):
         expected = compute_audit_hash(

svc_infra/security/audit_service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, List, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import Any
 
 try:  # optional SQLAlchemy import for environments without SA
     from sqlalchemy import select
@@ -15,11 +16,11 @@ async def append_event(
     db: Any,
     *,
     actor_id=None,
-    tenant_id: Optional[str] = None,
+    tenant_id: str | None = None,
     event_type: str,
-    resource_ref: Optional[str] = None,
+    resource_ref: str | None = None,
     metadata: dict | None = None,
-    prev_event: Optional[AuditLog] = None,
+    prev_event: AuditLog | None = None,
 ) -> AuditLog:
     """Append an AuditLog event using the shared append utility.
 
@@ -37,8 +38,8 @@ async def append_event(
 
 
 async def verify_chain_for_tenant(
-    db: Any, *, tenant_id: Optional[str] = None
-) -> Tuple[bool, List[int]]:
+    db: Any, *, tenant_id: str | None = None
+) -> tuple[bool, list[int]]:
     """Fetch all AuditLog events for a tenant and verify hash-chain integrity.
 
     Falls back to inspecting an in-memory 'added' list when SQLAlchemy is not available,
@@ -57,13 +58,12 @@ async def verify_chain_for_tenant(
             events = []
     elif hasattr(db, "added"):
         try:
-            pool = getattr(db, "added")
+            pool = db.added
             # Preserve insertion order for in-memory fake DBs where primary keys may be None
             events = [
                 e
                 for e in pool
-                if isinstance(e, AuditLog)
-                and (tenant_id is None or e.tenant_id == tenant_id)
+                if isinstance(e, AuditLog) and (tenant_id is None or e.tenant_id == tenant_id)
             ]
         except Exception:  # pragma: no cover
             events = []

svc_infra/security/hibp.py

@@ -4,7 +4,6 @@ import hashlib
 import logging
 import time
 from dataclasses import dataclass
-from typing import Dict, Optional
 
 from svc_infra.http import new_httpx_client
 
@@ -41,14 +40,14 @@ class HIBPClient:
         self.ttl_seconds = ttl_seconds
         self.timeout = timeout
         self.user_agent = user_agent
-        self._cache: Dict[str, CacheEntry] = {}
+        self._cache: dict[str, CacheEntry] = {}
         # Use central factory for consistent defaults; retain explicit timeout override
         self._http = new_httpx_client(
             timeout_seconds=self.timeout,
             headers={"User-Agent": self.user_agent},
         )
 
-    def _get_cached(self, prefix: str) -> Optional[str]:
+    def _get_cached(self, prefix: str) -> str | None:
         now = time.time()
         ent = self._cache.get(prefix)
         if ent and ent.expires_at > now:
@@ -56,9 +55,7 @@ class HIBPClient:
         return None
 
     def _set_cache(self, prefix: str, body: str) -> None:
-        self._cache[prefix] = CacheEntry(
-            body=body, expires_at=time.time() + self.ttl_seconds
-        )
+        self._cache[prefix] = CacheEntry(body=body, expires_at=time.time() + self.ttl_seconds)
 
     def range_query(self, prefix: str) -> str:
         cached = self._get_cached(prefix)

svc_infra/security/jwt_rotation.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Iterable, List, Optional, Union
+from collections.abc import Iterable
+from typing import Any
 
 import jwt
 from fastapi_users.authentication.strategy.jwt import JWTStrategy
@@ -19,8 +20,8 @@ class RotatingJWTStrategy(JWTStrategy):
         *,
         secret: str,
         lifetime_seconds: int,
-        old_secrets: Optional[Iterable[str]] = None,
-        token_audience: Optional[Union[str, List[str]]] = None,
+        old_secrets: Iterable[str] | None = None,
+        token_audience: str | list[str] | None = None,
     ):
         # Normalize token_audience to list as required by parent JWTStrategy
         aud_list: list[str] = (
@@ -30,10 +31,8 @@ class RotatingJWTStrategy(JWTStrategy):
             if token_audience
             else []
         ) or ["fastapi-users:auth"]
-        super().__init__(
-            secret=secret, lifetime_seconds=lifetime_seconds, token_audience=aud_list
-        )
-        self._verify_secrets: List[str] = [secret] + list(old_secrets or [])
+        super().__init__(secret=secret, lifetime_seconds=lifetime_seconds, token_audience=aud_list)
+        self._verify_secrets: list[str] = [secret, *list(old_secrets or [])]
         self._lifetime_seconds = lifetime_seconds
 
     async def read_token(
@@ -62,9 +61,7 @@ class RotatingJWTStrategy(JWTStrategy):
             else:
                 aud_list = audience
             try:
-                return decode_jwt(
-                    token, self.decode_key, aud_list, algorithms=[self.algorithm]
-                )
+                return decode_jwt(token, self.decode_key, aud_list, algorithms=[self.algorithm])
             except jwt.PyJWTError:
                 pass
 

svc_infra/security/lockout.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import uuid
+from collections.abc import Sequence
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-from typing import Any, Optional, Sequence
+from datetime import UTC, datetime, timedelta
+from typing import Any
 
 try:
     from sqlalchemy import or_, select
@@ -27,7 +28,7 @@ class LockoutConfig:
 @dataclass
 class LockoutStatus:
     locked: bool
-    next_allowed_at: Optional[datetime]
+    next_allowed_at: datetime | None
     failure_count: int
 
 
@@ -35,9 +36,9 @@ class LockoutStatus:
 
 
 def compute_lockout(
-    fail_count: int, *, cfg: LockoutConfig, now: Optional[datetime] = None
+    fail_count: int, *, cfg: LockoutConfig, now: datetime | None = None
 ) -> LockoutStatus:
-    now = now or datetime.now(timezone.utc)
+    now = now or datetime.now(UTC)
     if fail_count < cfg.threshold:
         return LockoutStatus(False, None, fail_count)
     # cooldown factor exponent = fail_count - threshold
@@ -54,8 +55,8 @@ def compute_lockout(
 async def record_attempt(
     session: AsyncSession,
     *,
-    user_id: Optional[uuid.UUID],
-    ip_hash: Optional[str],
+    user_id: uuid.UUID | None,
+    ip_hash: str | None,
     success: bool,
 ) -> None:
     attempt = FailedAuthAttempt(user_id=user_id, ip_hash=ip_hash, success=success)
@@ -66,12 +67,12 @@ async def record_attempt(
 async def get_lockout_status(
     session: AsyncSession,
     *,
-    user_id: Optional[uuid.UUID],
-    ip_hash: Optional[str],
-    cfg: Optional[LockoutConfig] = None,
+    user_id: uuid.UUID | None,
+    ip_hash: str | None,
+    cfg: LockoutConfig | None = None,
 ) -> LockoutStatus:
     cfg = cfg or LockoutConfig()
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
     window_start = now - timedelta(minutes=cfg.window_minutes)
 
     q = select(FailedAuthAttempt).where(

svc_infra/security/models.py

@@ -3,8 +3,7 @@ from __future__ import annotations
 import hashlib
 import json
 import uuid
-from datetime import datetime, timedelta, timezone
-from typing import Optional
+from datetime import UTC, datetime, timedelta
 
 from sqlalchemy import (
     JSON,
@@ -32,14 +31,14 @@ class AuthSession(ModelBase):
     user_id: Mapped[uuid.UUID] = mapped_column(
         GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True
     )
-    tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
-    user_agent: Mapped[Optional[str]] = mapped_column(String(512))
-    ip_hash: Mapped[Optional[str]] = mapped_column(String(64), index=True)
-    last_seen_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
-    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
-    revoke_reason: Mapped[Optional[str]] = mapped_column(Text)
-
-    refresh_tokens: Mapped[list["RefreshToken"]] = relationship(
+    tenant_id: Mapped[str | None] = mapped_column(String(64), index=True)
+    user_agent: Mapped[str | None] = mapped_column(String(512))
+    ip_hash: Mapped[str | None] = mapped_column(String(64), index=True)
+    last_seen_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    revoke_reason: Mapped[str | None] = mapped_column(Text)
+
+    refresh_tokens: Mapped[list[RefreshToken]] = relationship(
         back_populates="session", cascade="all, delete-orphan", lazy="selectin"
     )
 
@@ -60,12 +59,10 @@ class RefreshToken(ModelBase):
     session: Mapped[AuthSession] = relationship(back_populates="refresh_tokens")
 
     token_hash: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
-    rotated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
-    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
-    revoke_reason: Mapped[Optional[str]] = mapped_column(Text)
-    expires_at: Mapped[Optional[datetime]] = mapped_column(
-        DateTime(timezone=True), index=True
-    )
+    rotated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    revoke_reason: Mapped[str | None] = mapped_column(Text)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), index=True)
 
     created_at = mapped_column(
         DateTime(timezone=True),
@@ -81,24 +78,22 @@ class RefreshTokenRevocation(ModelBase):
 
     id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
     token_hash: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
-    revoked_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), nullable=False
-    )
-    reason: Mapped[Optional[str]] = mapped_column(Text)
+    revoked_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    reason: Mapped[str | None] = mapped_column(Text)
 
 
 class FailedAuthAttempt(ModelBase):
     __tablename__ = "failed_auth_attempts"
 
     id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
-    user_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+    user_id: Mapped[uuid.UUID | None] = mapped_column(
         GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=True
     )
-    ip_hash: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    ip_hash: Mapped[str | None] = mapped_column(String(64), index=True)
     ts: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),
         nullable=False,
-        default=lambda: datetime.now(timezone.utc),
+        default=lambda: datetime.now(UTC),
     )
     success: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
 
@@ -119,17 +114,17 @@ class AuditLog(ModelBase):
     ts: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),
         nullable=False,
-        default=lambda: datetime.now(timezone.utc),
+        default=lambda: datetime.now(UTC),
         index=True,
     )
-    actor_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+    actor_id: Mapped[uuid.UUID | None] = mapped_column(
         GUID(), ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
     )
-    tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    tenant_id: Mapped[str | None] = mapped_column(String(64), index=True)
     event_type: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
-    resource_ref: Mapped[Optional[str]] = mapped_column(String(255), index=True)
+    resource_ref: Mapped[str | None] = mapped_column(String(255), index=True)
     event_metadata: Mapped[dict] = mapped_column("metadata", JSON, default=dict)
-    prev_hash: Mapped[Optional[str]] = mapped_column(String(64))
+    prev_hash: Mapped[str | None] = mapped_column(String(64))
     hash: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
 
     __table_args__ = (Index("ix_audit_chain", "tenant_id", "id"),)
@@ -143,8 +138,8 @@ class Organization(ModelBase):
 
     id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
     name: Mapped[str] = mapped_column(String(128), nullable=False)
-    slug: Mapped[Optional[str]] = mapped_column(String(64), index=True)
-    tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    slug: Mapped[str | None] = mapped_column(String(64), index=True)
+    tenant_id: Mapped[str | None] = mapped_column(String(64), index=True)
     created_at = mapped_column(
         DateTime(timezone=True),
         server_default=text("CURRENT_TIMESTAMP"),
@@ -183,11 +178,9 @@ class OrganizationMembership(ModelBase):
         server_default=text("CURRENT_TIMESTAMP"),
         nullable=False,
     )
-    deactivated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    deactivated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
 
-    __table_args__ = (
-        UniqueConstraint("org_id", "user_id", name="uq_org_user_membership"),
-    )
+    __table_args__ = (UniqueConstraint("org_id", "user_id", name="uq_org_user_membership"),)
 
 
 class OrganizationInvitation(ModelBase):
@@ -200,10 +193,8 @@ class OrganizationInvitation(ModelBase):
     email: Mapped[str] = mapped_column(String(255), index=True)
     role: Mapped[str] = mapped_column(String(64), nullable=False)
     token_hash: Mapped[str] = mapped_column(String(64), index=True)
-    expires_at: Mapped[Optional[datetime]] = mapped_column(
-        DateTime(timezone=True), index=True
-    )
-    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), index=True)
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
         GUID(), ForeignKey("users.id", ondelete="SET NULL"), index=True
     )
     created_at = mapped_column(
@@ -211,10 +202,10 @@ class OrganizationInvitation(ModelBase):
         server_default=text("CURRENT_TIMESTAMP"),
         nullable=False,
     )
-    last_sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    last_sent_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     resend_count: Mapped[int] = mapped_column(default=0)
-    used_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
-    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
 
 
 # ------------------------ OAuth Provider Accounts -----------------------------
@@ -235,13 +226,13 @@ def hash_refresh_token(raw: str) -> str:
 
 
 def compute_audit_hash(
-    prev_hash: Optional[str],
+    prev_hash: str | None,
     *,
     ts: datetime,
-    actor_id: Optional[uuid.UUID],
-    tenant_id: Optional[str],
+    actor_id: uuid.UUID | None,
+    tenant_id: str | None,
     event_type: str,
-    resource_ref: Optional[str],
+    resource_ref: str | None,
     metadata: dict,
 ) -> str:
     """Compute SHA256 hash chaining previous hash + canonical event payload."""
@@ -264,7 +255,7 @@ def rotate_refresh_token(
     """Rotate: returns (new_raw, new_hash, expires_at)."""
     new_raw = generate_refresh_token()
     new_hash = hash_refresh_token(new_raw)
-    expires_at = datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    expires_at = datetime.now(UTC) + timedelta(minutes=ttl_minutes)
     return new_raw, new_hash, expires_at