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

svc_infra/security/models.py

@@ -6,7 +6,17 @@ import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
-from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Index, String, Text, UniqueConstraint
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    text,
+)
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from svc_infra.db.sql.base import ModelBase
@@ -34,7 +44,9 @@ class AuthSession(ModelBase):
     )
 
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
 
@@ -51,10 +63,14 @@ class RefreshToken(ModelBase):
     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)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True), index=True
+    )
 
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
     __table_args__ = (UniqueConstraint("token_hash", name="uq_refresh_token_hash"),)
@@ -65,7 +81,9 @@ 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)
+    revoked_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False
+    )
     reason: Mapped[Optional[str]] = mapped_column(Text)
 
 
@@ -78,7 +96,9 @@ class FailedAuthAttempt(ModelBase):
     )
     ip_hash: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     ts: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc)
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
     )
     success: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
 
@@ -126,7 +146,9 @@ class Organization(ModelBase):
     slug: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
 
@@ -139,7 +161,9 @@ class Team(ModelBase):
     )
     name: Mapped[str] = mapped_column(String(128), nullable=False)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
 
@@ -155,11 +179,15 @@ class OrganizationMembership(ModelBase):
     )
     role: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
     deactivated_at: Mapped[Optional[datetime]] = 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):
@@ -172,12 +200,16 @@ 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)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True), index=True
+    )
     created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
         GUID(), ForeignKey("users.id", ondelete="SET NULL"), index=True
     )
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
     last_sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
     resend_count: Mapped[int] = mapped_column(default=0)
@@ -185,6 +217,11 @@ class OrganizationInvitation(ModelBase):
     revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
 
 
+# ------------------------ OAuth Provider Accounts -----------------------------
+# MOVED to svc_infra.security.oauth_models for opt-in OAuth support
+# Projects that enable OAuth should import ProviderAccount from there
+
+
 # ------------------------ Utilities -------------------------------------------
 
 
@@ -238,6 +275,11 @@ __all__ = [
     "FailedAuthAttempt",
     "RolePermission",
     "AuditLog",
+    "Organization",
+    "Team",
+    "OrganizationMembership",
+    "OrganizationInvitation",
+    # ProviderAccount moved to svc_infra.security.oauth_models (opt-in)
     "generate_refresh_token",
     "hash_refresh_token",
     "compute_audit_hash",

svc_infra/security/oauth_models.py

@@ -0,0 +1,73 @@
+"""
+OAuth provider account models (opt-in).
+
+These models are only registered when a project explicitly enables OAuth.
+Import this module only when enable_oauth=True is passed to add_auth_users.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from svc_infra.db.sql.base import ModelBase
+from svc_infra.db.sql.types import GUID
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    # User model is application-specific; this is a forward reference for type hints
+    User = Any
+
+
+class ProviderAccount(ModelBase):
+    """OAuth provider account linking (Google, GitHub, etc.)."""
+
+    __tablename__ = "provider_accounts"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    provider_account_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    access_token: Mapped[Optional[str]] = mapped_column(Text)
+    refresh_token: Mapped[Optional[str]] = mapped_column(Text)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    raw_claims: Mapped[Optional[dict]] = mapped_column(JSON)
+
+    # Bidirectional relationship to User model
+    user: Mapped["User"] = relationship(back_populates="provider_accounts")
+
+    created_at = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+    updated_at = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("provider", "provider_account_id", name="uq_provider_account"),
+        Index("ix_provider_accounts_user_provider", "user_id", "provider"),
+    )
+
+
+__all__ = ["ProviderAccount"]

svc_infra/security/org_invites.py

@@ -9,8 +9,8 @@ try:
     from sqlalchemy import select
     from sqlalchemy.ext.asyncio import AsyncSession
 except Exception:  # pragma: no cover
-    AsyncSession = object  # type: ignore
-    select = None  # type: ignore
+    AsyncSession = object  # type: ignore[misc,assignment]
+    select = None  # type: ignore[assignment]
 
 from .models import OrganizationInvitation, OrganizationMembership
 
@@ -113,7 +113,9 @@ async def accept_invitation(
     invitation.used_at = now
 
     # create membership (upsert-like enforced by DB unique constraint)
-    mem = OrganizationMembership(org_id=invitation.org_id, user_id=user_id, role=invitation.role)
+    mem = OrganizationMembership(
+        org_id=invitation.org_id, user_id=user_id, role=invitation.role
+    )
     if hasattr(db, "add"):
         db.add(mem)
         if hasattr(db, "flush"):

svc_infra/security/passwords.py

@@ -60,7 +60,9 @@ def validate_password(pw: str, policy: PasswordPolicy | None = None) -> None:
     if policy.forbid_common:
         lowered = pw.lower()
         # Reject if whole password matches a common one or contains it as a substring
-        if lowered in COMMON_PASSWORDS or any(term in lowered for term in COMMON_PASSWORDS):
+        if lowered in COMMON_PASSWORDS or any(
+            term in lowered for term in COMMON_PASSWORDS
+        ):
             reasons.append("common_password")
     if policy.forbid_breached and not HIBP_DISABLED:
         if _breached_checker and _breached_checker(pw):

svc_infra/security/permissions.py

@@ -1,12 +1,16 @@
 from __future__ import annotations
 
 import inspect
+import threading
 from typing import Any, Awaitable, Callable, Dict, Iterable, Set
 
 from fastapi import Depends, HTTPException
 
 from svc_infra.api.fastapi.auth.security import Identity
 
+# Thread-safe permission registry
+_PERMISSION_LOCK = threading.Lock()
+
 # Central role -> permissions mapping. Projects can extend at startup.
 PERMISSION_REGISTRY: Dict[str, Set[str]] = {
     "admin": {
@@ -16,16 +20,33 @@ PERMISSION_REGISTRY: Dict[str, Set[str]] = {
         "billing.write",
         "security.session.revoke",
         "security.session.list",
+        "admin.impersonate",
     },
     "support": {"user.read", "billing.read"},
     "auditor": {"user.read", "billing.read", "audit.read"},
 }
 
 
+def register_role(role: str, permissions: Set[str]) -> None:
+    """Thread-safe registration of a role and its permissions."""
+    with _PERMISSION_LOCK:
+        PERMISSION_REGISTRY[role] = permissions
+
+
+def extend_role(role: str, permissions: Set[str]) -> None:
+    """Thread-safe extension of an existing role's permissions."""
+    with _PERMISSION_LOCK:
+        if role in PERMISSION_REGISTRY:
+            PERMISSION_REGISTRY[role] |= permissions
+        else:
+            PERMISSION_REGISTRY[role] = permissions
+
+
 def get_permissions_for_roles(roles: Iterable[str]) -> Set[str]:
     perms: Set[str] = set()
-    for r in roles:
-        perms |= PERMISSION_REGISTRY.get(r, set())
+    with _PERMISSION_LOCK:
+        for r in roles:
+            perms |= PERMISSION_REGISTRY.get(r, set())
     return perms
 
 
@@ -137,6 +158,8 @@ def RequireABAC(
 
 __all__ = [
     "PERMISSION_REGISTRY",
+    "register_role",
+    "extend_role",
     "get_permissions_for_roles",
     "principal_permissions",
     "has_permission",

svc_infra/security/session.py

@@ -7,7 +7,7 @@ from typing import Optional
 try:
     from sqlalchemy.ext.asyncio import AsyncSession
 except Exception:  # pragma: no cover
-    AsyncSession = object  # type: ignore
+    AsyncSession = object  # type: ignore[misc,assignment]
 
 from svc_infra.security.models import (
     AuthSession,

svc_infra/security/signed_cookies.py

@@ -30,15 +30,24 @@ def sign_cookie(
     *,
     key: str,
     expires_in: Optional[int] = None,
+    path: Optional[str] = None,
+    domain: Optional[str] = None,
 ) -> str:
-    """Produce a compact signed cookie value with optional expiry.
+    """Produce a compact signed cookie value with optional expiry and scope binding.
 
     Format: base64url(json).base64url(hmac)
     If expires_in is provided, 'exp' epoch seconds is injected into payload prior to signing.
+    If path or domain is provided, they are included in the signed payload to prevent
+    cookie replay attacks across different paths/domains.
     """
     body = dict(payload)
     if expires_in is not None:
         body.setdefault("exp", _now() + int(expires_in))
+    # Include scope in signature to prevent replay across paths/domains
+    if path is not None:
+        body.setdefault("_path", path)
+    if domain is not None:
+        body.setdefault("_domain", domain)
     data = json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
     sig = _sign(data, key.encode())
     return f"{_b64e(data)}.{sig}"
@@ -49,11 +58,15 @@ def verify_cookie(
     *,
     key: str,
     old_keys: Optional[List[str]] = None,
+    expected_path: Optional[str] = None,
+    expected_domain: Optional[str] = None,
 ) -> Tuple[bool, Optional[Dict[str, Any]]]:
     """Verify a signed cookie against the primary key or any old key.
 
     Returns (ok, payload). If ok is False, payload will be None.
     Rejects if exp is present and in the past.
+    If expected_path or expected_domain is provided, verifies the cookie was signed
+    for that scope (prevents replay attacks across paths/domains).
     """
     if not value or "." not in value:
         return False, None
@@ -72,6 +85,13 @@ def verify_cookie(
         # Expire when current time reaches or exceeds exp
         if "exp" in payload and _now() >= int(payload["exp"]):
             return False, None
+        # Verify scope binding if expected
+        if expected_path is not None:
+            if payload.get("_path") != expected_path:
+                return False, None
+        if expected_domain is not None:
+            if payload.get("_domain") != expected_domain:
+                return False, None
         return True, payload
     except Exception:
         return False, None

svc_infra/storage/__init__.py

@@ -0,0 +1,93 @@
+"""
+Generic file storage system for svc-infra.
+
+Provides backend-agnostic file storage with support for multiple providers:
+- Local filesystem (Railway volumes, Render, development)
+- S3-compatible (AWS S3, DigitalOcean Spaces, Wasabi, Backblaze B2, Minio)
+- Google Cloud Storage (coming soon)
+- Cloudinary (coming soon)
+- In-memory (testing)
+
+Quick Start:
+    >>> from svc_infra.storage import add_storage, easy_storage
+    >>> from fastapi import FastAPI
+    >>>
+    >>> app = FastAPI()
+    >>>
+    >>> # Auto-detect backend from environment
+    >>> storage = add_storage(app)
+    >>>
+    >>> # Or explicit backend
+    >>> backend = easy_storage(backend="s3", bucket="my-uploads")
+    >>> storage = add_storage(app, backend)
+
+Usage in Routes:
+    >>> from svc_infra.storage import get_storage, StorageBackend
+    >>> from fastapi import Depends, UploadFile
+    >>>
+    >>> @router.post("/upload")
+    >>> async def upload_file(
+    ...     file: UploadFile,
+    ...     storage: StorageBackend = Depends(get_storage),
+    ... ):
+    ...     content = await file.read()
+    ...     url = await storage.put(
+    ...         key=f"uploads/{file.filename}",
+    ...         data=content,
+    ...         content_type=file.content_type or "application/octet-stream",
+    ...         metadata={"user_id": "user_123"}
+    ...     )
+    ...     return {"url": url}
+
+Environment Variables:
+    STORAGE_BACKEND: Backend type (local, s3, gcs, cloudinary, memory)
+
+    Local:
+        STORAGE_BASE_PATH: Directory for files (default: /data/uploads)
+        STORAGE_BASE_URL: URL for file serving (default: http://localhost:8000/files)
+
+    S3:
+        STORAGE_S3_BUCKET: Bucket name (required)
+        STORAGE_S3_REGION: AWS region (default: us-east-1)
+        STORAGE_S3_ENDPOINT: Custom endpoint for S3-compatible services
+        STORAGE_S3_ACCESS_KEY: Access key (falls back to AWS_ACCESS_KEY_ID)
+        STORAGE_S3_SECRET_KEY: Secret key (falls back to AWS_SECRET_ACCESS_KEY)
+
+See Also:
+    - ADR-0012: Generic File Storage System design
+    - docs/storage.md: Comprehensive storage guide
+"""
+
+from .add import add_storage, get_storage, health_check_storage
+from .backends import LocalBackend, MemoryBackend, S3Backend
+from .base import (
+    FileNotFoundError,
+    InvalidKeyError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    StorageBackend,
+    StorageError,
+)
+from .easy import easy_storage
+from .settings import StorageSettings
+
+__all__ = [
+    # Main API
+    "add_storage",
+    "easy_storage",
+    "get_storage",
+    "health_check_storage",
+    # Base types
+    "StorageBackend",
+    "StorageSettings",
+    # Backends
+    "LocalBackend",
+    "MemoryBackend",
+    "S3Backend",
+    # Exceptions
+    "StorageError",
+    "FileNotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "InvalidKeyError",
+]