auth 3.3.0__tar.gz → 3.5.0__tar.gz

{auth-3.3.0 → auth-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth
-Version: 3.3.0
+Version: 3.5.0
 Summary: Authorization for humans
 Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
 License-Expression: MIT

{auth-3.3.0 → auth-3.5.0}/auth/__init__.py

@@ -10,6 +10,7 @@ from auth.client import (  # Import the new client
     EnhancedAuthClient,
 )
 from auth.database import SessionLocal
+from auth.schema_check import SchemaMismatchError, check_schema
 from auth.services.service import AuthorizationService
 
 try:
@@ -56,6 +57,7 @@ class Authorization:
 
         self.client = client
         # Use provided session or create a new one
+        self._owns_session = not db_session
         self.db = db_session if db_session else SessionLocal()
         # Use legacy mode (no client validation) for backward compatibility.
         # strict_users: None reads the tenant's stored setting (identical
@@ -64,6 +66,16 @@ class Authorization:
             self.db, client, validate_client=False, strict_users=strict_users
         )
 
+    def close(self) -> None:
+        if self._owns_session:
+            self.db.close()
+
+    def __enter__(self) -> "Authorization":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
     @property
     def roles(self):
         return self.service.get_roles()
@@ -146,5 +158,7 @@ __all__ = [
     "Client",
     "EnhancedAuthClient",
     "SessionLocal",
+    "SchemaMismatchError",
+    "check_schema",
     "__version__",
 ]

{auth-3.3.0 → auth-3.5.0}/auth/config.py

@@ -5,6 +5,7 @@ Centralized configuration management for the authorization system
 import os
 from enum import Enum
 from functools import lru_cache
+from typing import Optional
 
 from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -89,6 +90,19 @@ class Settings(BaseSettings):
     # Schema settings (for PostgreSQL multi-tenancy)
     database_schema: str = ""  # Optional schema name (e.g., "auth_rbac" for Highway)
 
+    database_pool_size: Optional[int] = Field(default=None, ge=1)
+    database_max_overflow: Optional[int] = Field(default=None, ge=0)
+    database_pool_timeout: Optional[float] = Field(default=None, gt=0)
+    database_pool_recycle: Optional[int] = Field(default=None, ge=-1)
+
+    @model_validator(mode="after")
+    def _reject_zero_pool_recycle(self):
+        if self.database_pool_recycle == 0:
+            raise ValueError(
+                "database_pool_recycle must be -1 (never recycle) or >= 1 second"
+            )
+        return self
+
     @model_validator(mode="after")
     def assemble_db_connection(self) -> "Settings":
         # If database_url is not explicitly set, construct it from other fields

{auth-3.3.0 → auth-3.5.0}/auth/database.py

@@ -7,14 +7,15 @@ import os
 import sqlite3
 import threading
 from contextlib import contextmanager
-from typing import Generator, Optional
+from typing import Generator, NamedTuple, Optional
 
 from sqlalchemy import create_engine, event, pool
 from sqlalchemy.engine import Engine, make_url
 from sqlalchemy.orm import Session, sessionmaker
 from sqlalchemy.pool import Pool
 
-from auth.config import DatabaseType, get_settings, warn_on_weak_secrets
+from auth.config import DatabaseType, Settings, get_settings, warn_on_weak_secrets
+from auth.schema_check import check_schema
 from auth.schema_reconcile import (
     GRANDFATHER_MARKER,  # noqa: F401  - re-exported; tests and embedded callers import it from here
     _apply_tenant_rls,
@@ -47,6 +48,47 @@ def _forced_sslmode(database_url: str) -> Optional[str]:
 logger = logging.getLogger(__name__)
 
 
+class PoolSettings(NamedTuple):
+    pool_size: int
+    max_overflow: int
+    pool_timeout: float
+    pool_recycle: int
+
+
+_POSTGRESQL_POOL_DEFAULTS = PoolSettings(2, 2, 10.0, 3600)
+_SQLITE_POOL_DEFAULTS = PoolSettings(5, 10, 30.0, 300)
+
+
+def resolve_pool_settings(settings: Settings) -> PoolSettings:
+    defaults = (
+        _POSTGRESQL_POOL_DEFAULTS
+        if settings.database_type == DatabaseType.POSTGRESQL
+        else _SQLITE_POOL_DEFAULTS
+    )
+    return PoolSettings(
+        pool_size=(
+            defaults.pool_size
+            if settings.database_pool_size is None
+            else settings.database_pool_size
+        ),
+        max_overflow=(
+            defaults.max_overflow
+            if settings.database_max_overflow is None
+            else settings.database_max_overflow
+        ),
+        pool_timeout=(
+            defaults.pool_timeout
+            if settings.database_pool_timeout is None
+            else settings.database_pool_timeout
+        ),
+        pool_recycle=(
+            defaults.pool_recycle
+            if settings.database_pool_recycle is None
+            else settings.database_pool_recycle
+        ),
+    )
+
+
 class SingletonMeta(type):
     """
     Thread-safe Singleton metaclass for database engine
@@ -83,35 +125,16 @@ class DatabaseEngine(metaclass=SingletonMeta):
         self._initialize_engine()
         self._setup_pool_monitoring()
 
-    def _calculate_pool_size(self) -> tuple[int, int]:
-        """
-        Calculate optimal pool size for Gunicorn workers
-
-        For 8 workers with PostgreSQL:
-        - pool_size=5 per worker = 40 base connections
-        - max_overflow=5 per worker = 80 total max connections
-        - Leaves headroom for PostgreSQL default max_connections (100)
-        - Also accounts for other services using the database
-
-        Returns:
-            tuple: (pool_size, max_overflow)
-        """
-        settings = get_settings()
+    def _pool_settings(self) -> PoolSettings:
+        return resolve_pool_settings(get_settings())
 
-        if settings.database_type == DatabaseType.POSTGRESQL:
-            # Sized for ONE request per worker, because the workers are sync.
-            # A request can hold two connections at once: its own session, and
-            # the separate committed session `audit.py` opens on the decorator's
-            # failure path. Two plus two spare, so 8 workers reach at most 32
-            # connections against max_connections=200.
-            return (2, 2)
-        else:
-            # SQLite - smaller pool since it's file-based
-            return (5, 10)
+    def _calculate_pool_size(self) -> tuple[int, int]:
+        pool_settings = self._pool_settings()
+        return (pool_settings.pool_size, pool_settings.max_overflow)
 
     def _create_postgresql_engine(self, database_url: str) -> Engine:
         """Create optimized PostgreSQL engine with enterprise pooling"""
-        pool_size, max_overflow = self._calculate_pool_size()
+        pool_settings = self._pool_settings()
 
         connect_args = {
             "connect_timeout": 30,
@@ -138,10 +161,10 @@ class DatabaseEngine(metaclass=SingletonMeta):
             database_url,
             # Connection pool settings
             poolclass=pool.QueuePool,  # Explicitly use QueuePool
-            pool_size=pool_size,
-            max_overflow=max_overflow,
-            pool_timeout=10,  # Fail fast rather than queueing behind a stalled DB
-            pool_recycle=3600,  # Recycle connections after 1 hour
+            pool_size=pool_settings.pool_size,
+            max_overflow=pool_settings.max_overflow,
+            pool_timeout=pool_settings.pool_timeout,
+            pool_recycle=pool_settings.pool_recycle,
             pool_pre_ping=True,  # Verify connections before using them
             # Performance settings
             echo=False,  # Disable SQL logging in production
@@ -161,16 +184,16 @@ class DatabaseEngine(metaclass=SingletonMeta):
                 connect_args={"check_same_thread": False},
             )
 
-        pool_size, max_overflow = self._calculate_pool_size()
+        pool_settings = self._pool_settings()
 
         return create_engine(
             database_url,
             poolclass=pool.QueuePool,
-            pool_size=pool_size,
-            max_overflow=max_overflow,
+            pool_size=pool_settings.pool_size,
+            max_overflow=pool_settings.max_overflow,
             pool_pre_ping=True,
-            pool_recycle=300,  # 5 minutes for SQLite
-            pool_timeout=30,
+            pool_recycle=pool_settings.pool_recycle,
+            pool_timeout=pool_settings.pool_timeout,
             connect_args={
                 "check_same_thread": False,
                 "timeout": 60,
@@ -200,10 +223,13 @@ class DatabaseEngine(metaclass=SingletonMeta):
             expire_on_commit=False,  # Prevent unnecessary queries
         )
 
-        pool_size, max_overflow = self._calculate_pool_size()
+        pool_settings = self._pool_settings()
         logger.info(
-            f"Database engine initialized: pool_size={pool_size}, "
-            f"max_overflow={max_overflow}, max_connections={pool_size + max_overflow}"
+            f"Database engine initialized: pool_size={pool_settings.pool_size}, "
+            f"max_overflow={pool_settings.max_overflow}, "
+            f"max_connections={pool_settings.pool_size + pool_settings.max_overflow}, "
+            f"pool_timeout={pool_settings.pool_timeout}, "
+            f"pool_recycle={pool_settings.pool_recycle}"
         )
 
     def _setup_pool_monitoring(self):
@@ -354,6 +380,7 @@ def create_tables(raise_on_error: bool = False):
         _ensure_audit_partition_runway(engine)
         _reconcile_text_columns(engine)
         _grandfather_strict_users(engine)
+        check_schema(engine)
         logger.info("Tables created successfully.")
     except Exception:
         logger.exception("create_tables failed")

auth-3.5.0/auth/schema_check.py

@@ -0,0 +1,61 @@
+from typing import List, Optional, Sequence, Tuple, Union
+
+from sqlalchemy import Table, inspect
+from sqlalchemy.engine import Connection, Engine
+
+Bind = Union[Engine, Connection]
+
+
+class SchemaMismatchError(RuntimeError):
+    def __init__(
+        self, missing_tables: Sequence[str], missing_columns: Sequence[str]
+    ) -> None:
+        self.missing_tables = list(missing_tables)
+        self.missing_columns = list(missing_columns)
+        parts = []
+        if self.missing_tables:
+            parts.append("missing tables: " + ", ".join(self.missing_tables))
+        if self.missing_columns:
+            parts.append("missing columns: " + ", ".join(self.missing_columns))
+        super().__init__(
+            "the live database is behind the installed auth models ("
+            + "; ".join(parts)
+            + "). The auth changelog lists the DDL each release needs."
+        )
+
+
+def _qualified(table: Table) -> str:
+    return f"{table.schema}.{table.name}" if table.schema else table.name
+
+
+def find_schema_drift(bind: Bind) -> Tuple[List[str], List[str]]:
+    import auth.audit  # noqa: F401
+    from auth.models.sql import Base
+
+    inspector = inspect(bind)
+    missing_tables: List[str] = []
+    missing_columns: List[str] = []
+    for table in sorted(Base.metadata.tables.values(), key=_qualified):
+        if not inspector.has_table(table.name, schema=table.schema):
+            missing_tables.append(_qualified(table))
+            continue
+        live = {
+            column["name"]
+            for column in inspector.get_columns(table.name, schema=table.schema)
+        }
+        missing_columns.extend(
+            f"{_qualified(table)}.{column.name}"
+            for column in table.columns
+            if column.name not in live
+        )
+    return missing_tables, missing_columns
+
+
+def check_schema(bind: Optional[Bind] = None) -> None:
+    if bind is None:
+        from auth.database import engine
+
+        bind = engine
+    missing_tables, missing_columns = find_schema_drift(bind)
+    if missing_tables or missing_columns:
+        raise SchemaMismatchError(missing_tables, missing_columns)

{auth-3.3.0 → auth-3.5.0}/auth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth
-Version: 3.3.0
+Version: 3.5.0
 Summary: Authorization for humans
 Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
 License-Expression: MIT

{auth-3.3.0 → auth-3.5.0}/auth.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ auth/main.py
 auth/response_format.py
 auth/rls.py
 auth/sanitizer.py
+auth/schema_check.py
 auth/schema_reconcile.py
 auth/server.py
 auth/validation.py
@@ -70,6 +71,7 @@ tests/test_client_rest.py
 tests/test_cmd_server.py
 tests/test_config.py
 tests/test_correctness_hardening.py
+tests/test_database_pool_settings.py
 tests/test_database_sslmode.py
 tests/test_degraded_response_is_a_contract.py
 tests/test_docs_page.py
@@ -84,6 +86,7 @@ tests/test_phase_a_hardening.py
 tests/test_provision_script_no_dsn_leak.py
 tests/test_reencryption.py
 tests/test_routes_errors.py
+tests/test_schema_check.py
 tests/test_self_service_audit.py
 tests/test_server.py
 tests/test_service_lifecycle.py

{auth-3.3.0 → auth-3.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auth"
-version = "3.3.0"
+version = "3.5.0"
 description = "Authorization for humans"
 readme = "README.md"
 requires-python = ">=3.10"

auth-3.5.0/tests/test_database_pool_settings.py

@@ -0,0 +1,340 @@
+import logging
+import os
+import subprocess
+import sys
+import threading
+import time
+
+import pytest
+from pydantic import ValidationError
+from sqlalchemy import exc, text
+
+import auth
+from auth.config import Settings
+from auth.database import DatabaseEngine, PoolSettings, resolve_pool_settings
+
+PG_URL = "postgresql+psycopg://app:s3cr3t-pw@db.example:5432/x"
+POOL_ENV = (
+    "AUTH_DATABASE_POOL_SIZE",
+    "AUTH_DATABASE_MAX_OVERFLOW",
+    "AUTH_DATABASE_POOL_TIMEOUT",
+    "AUTH_DATABASE_POOL_RECYCLE",
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean_pool_env(monkeypatch):
+    for name in POOL_ENV:
+        monkeypatch.delenv(name, raising=False)
+
+
+def _bare_engine_manager():
+    return object.__new__(DatabaseEngine)
+
+
+def _use_settings(monkeypatch, **env):
+    for name, value in env.items():
+        monkeypatch.setenv(name, value)
+    monkeypatch.setattr(
+        "auth.database.get_settings", lambda: Settings()  # type: ignore[call-arg]
+    )
+
+
+def test_unset_postgresql_pool_keeps_3_3_0_values():
+    settings = Settings(database_url=PG_URL)
+    assert resolve_pool_settings(settings) == PoolSettings(2, 2, 10, 3600)
+
+
+def test_unset_sqlite_pool_keeps_3_3_0_values(tmp_path):
+    settings = Settings(database_url=f"sqlite:///{tmp_path}/a.db")
+    assert resolve_pool_settings(settings) == PoolSettings(5, 10, 30, 300)
+
+
+def test_env_overrides_every_pool_parameter(monkeypatch):
+    _use_settings(
+        monkeypatch,
+        AUTH_DATABASE_URL=PG_URL,
+        AUTH_DATABASE_POOL_SIZE="1",
+        AUTH_DATABASE_MAX_OVERFLOW="0",
+        AUTH_DATABASE_POOL_TIMEOUT="3.5",
+        AUTH_DATABASE_POOL_RECYCLE="120",
+    )
+    engine = _bare_engine_manager()._create_postgresql_engine(PG_URL)
+    try:
+        assert engine.pool.size() == 1
+        assert engine.pool._max_overflow == 0
+        assert engine.pool._timeout == 3.5
+        assert engine.pool._recycle == 120
+    finally:
+        engine.dispose()
+
+
+def test_partial_override_keeps_remaining_defaults(monkeypatch):
+    _use_settings(
+        monkeypatch, AUTH_DATABASE_URL=PG_URL, AUTH_DATABASE_POOL_SIZE="1"
+    )
+    engine = _bare_engine_manager()._create_postgresql_engine(PG_URL)
+    try:
+        assert engine.pool.size() == 1
+        assert engine.pool._max_overflow == 2
+        assert engine.pool._timeout == 10
+        assert engine.pool._recycle == 3600
+    finally:
+        engine.dispose()
+
+
+def test_recycle_minus_one_is_accepted_as_never():
+    settings = Settings(
+        database_url=PG_URL, database_pool_recycle=-1
+    )
+    assert resolve_pool_settings(settings).pool_recycle == -1
+
+
+@pytest.mark.parametrize(
+    "name,value",
+    [
+        ("AUTH_DATABASE_POOL_SIZE", "0"),
+        ("AUTH_DATABASE_POOL_SIZE", "-1"),
+        ("AUTH_DATABASE_MAX_OVERFLOW", "-1"),
+        ("AUTH_DATABASE_POOL_TIMEOUT", "0"),
+        ("AUTH_DATABASE_POOL_TIMEOUT", "-5"),
+        ("AUTH_DATABASE_POOL_RECYCLE", "0"),
+        ("AUTH_DATABASE_POOL_RECYCLE", "-2"),
+        ("AUTH_DATABASE_POOL_SIZE", "two"),
+    ],
+)
+def test_invalid_pool_value_is_refused_without_echoing_dsn(monkeypatch, name, value):
+    monkeypatch.setenv("AUTH_DATABASE_URL", PG_URL)
+    monkeypatch.setenv(name, value)
+    with pytest.raises(ValidationError) as caught:
+        Settings()  # type: ignore[call-arg]
+    message = str(caught.value)
+    field = name.removeprefix("AUTH_").lower()
+    assert field in message
+    assert "s3cr3t-pw" not in message
+
+
+def test_valid_boundary_values_are_accepted(monkeypatch):
+    monkeypatch.setenv("AUTH_DATABASE_URL", PG_URL)
+    monkeypatch.setenv("AUTH_DATABASE_POOL_SIZE", "1")
+    monkeypatch.setenv("AUTH_DATABASE_MAX_OVERFLOW", "0")
+    monkeypatch.setenv("AUTH_DATABASE_POOL_TIMEOUT", "0.1")
+    monkeypatch.setenv("AUTH_DATABASE_POOL_RECYCLE", "1")
+    settings = Settings()  # type: ignore[call-arg]
+    assert resolve_pool_settings(settings) == PoolSettings(1, 0, 0.1, 1)
+
+
+def _import_auth_database(tmp_path, **pool_env):
+    env = {
+        key: value
+        for key, value in os.environ.items()
+        if not key.startswith("AUTH_") and key != "PGSSLMODE"
+    }
+    package_root = os.path.dirname(os.path.dirname(os.path.abspath(auth.__file__)))
+    env.update(
+        PYTHONPATH=package_root,
+        AUTH_DATABASE_URL=f"sqlite:///{tmp_path}/start.db",
+        AUTH_JWT_SECRET_KEY="pool-settings-test-secret-0001",
+        **pool_env,
+    )
+    return subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import auth, auth.database; print(auth.__file__)",
+        ],
+        env=env,
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+
+
+def test_process_refuses_to_start_on_invalid_pool_size(tmp_path):
+    good = _import_auth_database(tmp_path, AUTH_DATABASE_POOL_SIZE="1")
+    assert good.returncode == 0, good.stderr
+    assert good.stdout.strip() == os.path.abspath(auth.__file__)
+    bad = _import_auth_database(tmp_path, AUTH_DATABASE_POOL_SIZE="0")
+    assert bad.returncode != 0
+    assert "database_pool_size" in bad.stderr
+    assert "ValidationError" in bad.stderr
+
+
+def test_effective_values_are_logged(monkeypatch, tmp_path, caplog):
+    url = f"sqlite:///{tmp_path}/log.db"
+    _use_settings(
+        monkeypatch,
+        AUTH_DATABASE_URL=url,
+        AUTH_DATABASE_POOL_SIZE="3",
+        AUTH_DATABASE_MAX_OVERFLOW="1",
+        AUTH_DATABASE_POOL_TIMEOUT="7",
+        AUTH_DATABASE_POOL_RECYCLE="90",
+    )
+    manager = _bare_engine_manager()
+    with caplog.at_level(logging.INFO, logger="auth.database"):
+        manager._initialize_engine()
+    try:
+        logged = " ".join(r.getMessage() for r in caplog.records)
+        assert "pool_size=3" in logged
+        assert "max_overflow=1" in logged
+        assert "max_connections=4" in logged
+        assert "pool_timeout=7.0" in logged
+        assert "pool_recycle=90" in logged
+    finally:
+        manager.engine.dispose()
+
+
+def test_exhausted_pool_times_out_then_resumes_on_release(monkeypatch, tmp_path):
+    url = f"sqlite:///{tmp_path}/cap.db"
+    _use_settings(
+        monkeypatch,
+        AUTH_DATABASE_URL=url,
+        AUTH_DATABASE_POOL_SIZE="1",
+        AUTH_DATABASE_MAX_OVERFLOW="0",
+        AUTH_DATABASE_POOL_TIMEOUT="0.5",
+    )
+    engine = _bare_engine_manager()._create_sqlite_engine(url)
+    try:
+        held = engine.connect()
+        assert held.execute(text("SELECT 1")).scalar() == 1
+        started = time.monotonic()
+        with pytest.raises(exc.TimeoutError):
+            engine.connect()
+        waited = time.monotonic() - started
+        assert 0.4 <= waited <= 1.5, waited
+
+        result = {}
+
+        def waiter():
+            with engine.connect() as conn:
+                result["value"] = conn.execute(text("SELECT 2")).scalar()
+
+        thread = threading.Thread(target=waiter)
+        thread.start()
+        time.sleep(0.1)
+        held.close()
+        thread.join(timeout=5)
+        assert result == {"value": 2}
+    finally:
+        engine.dispose()
+
+
+def test_tls_url_parameters_reach_psycopg_unchanged(monkeypatch):
+    monkeypatch.delenv("PGSSLMODE", raising=False)
+    tls_url = (
+        PG_URL
+        + "?sslmode=verify-full&sslrootcert=/etc/tls/root.crt"
+        + "&sslcert=/etc/tls/client.crt&sslkey=/etc/tls/client.key"
+    )
+    _use_settings(monkeypatch, AUTH_DATABASE_URL=tls_url)
+    captured = {}
+
+    def fake_connect(*args, **kwargs):
+        captured.update(kwargs)
+        raise RuntimeError("stop before network")
+
+    engine = _bare_engine_manager()._create_postgresql_engine(tls_url)
+    monkeypatch.setattr(engine.dialect.loaded_dbapi, "connect", fake_connect)
+    try:
+        with pytest.raises(RuntimeError, match="stop before network"):
+            engine.connect()
+    finally:
+        engine.dispose()
+    assert captured["sslmode"] == "verify-full"
+    assert captured["sslrootcert"] == "/etc/tls/root.crt"
+    assert captured["sslcert"] == "/etc/tls/client.crt"
+    assert captured["sslkey"] == "/etc/tls/client.key"
+
+
+def test_capture_sees_forced_sslmode_when_url_has_none(monkeypatch):
+    monkeypatch.delenv("PGSSLMODE", raising=False)
+    _use_settings(monkeypatch, AUTH_DATABASE_URL=PG_URL)
+    captured = {}
+
+    def fake_connect(*args, **kwargs):
+        captured.update(kwargs)
+        raise RuntimeError("stop before network")
+
+    engine = _bare_engine_manager()._create_postgresql_engine(PG_URL)
+    monkeypatch.setattr(engine.dialect.loaded_dbapi, "connect", fake_connect)
+    try:
+        with pytest.raises(RuntimeError, match="stop before network"):
+            engine.connect()
+    finally:
+        engine.dispose()
+    assert captured["sslmode"] == "require"
+    assert "sslrootcert" not in captured
+
+
+def _embedded_env(tmp_path):
+    package_root = os.path.dirname(os.path.dirname(os.path.abspath(auth.__file__)))
+    env = {
+        key: value
+        for key, value in os.environ.items()
+        if not key.startswith("AUTH_") and key != "PGSSLMODE"
+    }
+    env.update(
+        PYTHONPATH=package_root,
+        AUTH_DATABASE_URL=f"sqlite:///{tmp_path}/embedded.db",
+        AUTH_JWT_SECRET_KEY="pool-settings-test-secret-0001",
+        AUTH_STRICT_USERS_DEFAULT="false",
+        AUTH_DATABASE_POOL_SIZE="1",
+        AUTH_DATABASE_MAX_OVERFLOW="0",
+        AUTH_DATABASE_POOL_TIMEOUT="0.5",
+    )
+    return env
+
+
+EMBEDDED_SCRIPT = """
+import logging, sys
+logging.disable(logging.CRITICAL)
+import auth
+from sqlalchemy import exc
+from auth.database import create_tables, engine, SessionLocal
+create_tables(raise_on_error=True)
+tenant = "11111111-1111-4111-8111-111111111111"
+seed = auth.Authorization(tenant)
+seed.add_role("viewer"); seed.add_permission("viewer", "read")
+seed.add_membership("alice", "viewer")
+seed.close()
+
+held = auth.Authorization(tenant)
+assert held.user_has_permission("alice", "read") is True
+assert engine.pool.checkedout() == 1
+try:
+    auth.Authorization(tenant).user_has_permission("alice", "read")
+    print("UNBLOCKED")
+    sys.exit(3)
+except exc.TimeoutError:
+    pass
+held.close()
+assert engine.pool.checkedout() == 0
+
+with auth.Authorization(tenant) as scoped:
+    assert scoped.user_has_permission("alice", "read") is True
+    assert engine.pool.checkedout() == 1
+assert engine.pool.checkedout() == 0
+
+caller_session = SessionLocal()
+borrowed = auth.Authorization(tenant, db_session=caller_session)
+assert borrowed.user_has_permission("alice", "read") is True
+borrowed.close()
+assert engine.pool.checkedout() == 1
+caller_session.close()
+assert engine.pool.checkedout() == 0
+print("OK", auth.__file__)
+"""
+
+
+def test_embedded_read_holds_one_connection_until_close(tmp_path):
+    result = subprocess.run(
+        [sys.executable, "-c", EMBEDDED_SCRIPT],
+        env=_embedded_env(tmp_path),
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert result.stdout.strip() == f"OK {os.path.abspath(auth.__file__)}"

auth-3.5.0/tests/test_schema_check.py

@@ -0,0 +1,134 @@
+import logging
+
+import pytest
+from sqlalchemy import create_engine, event, text
+
+import auth
+import auth.audit  # noqa: F401
+import auth.database
+from auth.models.sql import Base
+from auth.schema_check import SchemaMismatchError, check_schema, find_schema_drift
+
+V310_TENANT_SETTINGS = (
+    "CREATE TABLE auth_tenant_settings ("
+    "id INTEGER PRIMARY KEY, creator VARCHAR(64) NOT NULL, "
+    "strict_users BOOLEAN NOT NULL, date_created DATETIME, modified DATETIME)"
+)
+V340_ADDED = [
+    "auth_tenant_settings.rotate_key_hash",
+    "auth_tenant_settings.rotate_key_issued_at",
+    "auth_tenant_settings.canary",
+]
+
+pytestmark = pytest.mark.skipif(
+    any(t.schema for t in Base.metadata.tables.values()),
+    reason="SQLite drift tests build unqualified tables",
+)
+
+
+@pytest.fixture
+def current_engine(tmp_path):
+    engine = create_engine(f"sqlite:///{tmp_path / 'current.sqlite3'}")
+    Base.metadata.create_all(engine)
+    yield engine
+    engine.dispose()
+
+
+@pytest.fixture
+def v310_engine(current_engine):
+    with current_engine.begin() as conn:
+        conn.execute(text("DROP TABLE auth_tenant_settings"))
+        conn.execute(text(V310_TENANT_SETTINGS))
+    return current_engine
+
+
+def _statements(engine):
+    seen = []
+    event.listen(
+        engine,
+        "before_cursor_execute",
+        lambda conn, cursor, statement, *a: seen.append(statement),
+    )
+    return seen
+
+
+def test_current_schema_passes(current_engine):
+    assert find_schema_drift(current_engine) == ([], [])
+    check_schema(current_engine)
+
+
+def test_v310_tenant_settings_names_the_three_missing_columns(v310_engine):
+    assert find_schema_drift(v310_engine) == ([], V340_ADDED)
+    with pytest.raises(SchemaMismatchError) as caught:
+        check_schema(v310_engine)
+    assert caught.value.missing_columns == V340_ADDED
+    assert caught.value.missing_tables == []
+    for name in V340_ADDED:
+        assert name in str(caught.value)
+
+
+def test_missing_table_is_named(current_engine):
+    with current_engine.begin() as conn:
+        conn.execute(text("DROP TABLE auth_tenant_settings"))
+    with pytest.raises(SchemaMismatchError) as caught:
+        check_schema(current_engine)
+    assert caught.value.missing_tables == ["auth_tenant_settings"]
+    assert caught.value.missing_columns == []
+    assert "missing tables: auth_tenant_settings" in str(caught.value)
+
+
+def test_extra_live_columns_are_allowed(current_engine):
+    with current_engine.begin() as conn:
+        conn.execute(text("ALTER TABLE auth_tenant_settings ADD COLUMN creator_fp TEXT"))
+    check_schema(current_engine)
+
+
+def test_check_issues_no_ddl_or_writes(v310_engine):
+    seen = _statements(v310_engine)
+    with v310_engine.begin() as conn:
+        conn.execute(text("ALTER TABLE auth_tenant_settings ADD COLUMN probe TEXT"))
+    assert any(s.startswith("ALTER TABLE") for s in seen)
+    seen.clear()
+    with pytest.raises(SchemaMismatchError):
+        check_schema(v310_engine)
+    assert seen
+    writes = ("CREATE", "ALTER", "DROP", "INSERT", "UPDATE", "DELETE")
+    assert [s for s in seen if s.lstrip().upper().startswith(writes)] == []
+
+
+def test_message_does_not_carry_the_database_location(v310_engine):
+    with pytest.raises(SchemaMismatchError) as caught:
+        check_schema(v310_engine)
+    assert str(v310_engine.url.database) not in str(caught.value)
+    assert "sqlite" not in str(caught.value)
+
+
+def test_create_tables_raises_on_drift_when_asked(v310_engine, monkeypatch):
+    monkeypatch.setattr(auth.database, "engine", v310_engine)
+    with pytest.raises(SchemaMismatchError) as caught:
+        auth.database.create_tables(raise_on_error=True)
+    assert caught.value.missing_columns == V340_ADDED
+
+
+def test_create_tables_logs_drift_by_default(v310_engine, monkeypatch, caplog):
+    monkeypatch.setattr(auth.database, "engine", v310_engine)
+    with caplog.at_level(logging.ERROR, logger=auth.database.logger.name):
+        auth.database.create_tables()
+    logged = "\n".join(r.getMessage() + (r.exc_text or "") for r in caplog.records)
+    assert "create_tables failed" in logged
+    for name in V340_ADDED:
+        assert name in logged
+    assert "Tables created successfully." not in caplog.text
+
+
+def test_create_tables_on_current_schema_reports_success(current_engine, monkeypatch, caplog):
+    monkeypatch.setattr(auth.database, "engine", current_engine)
+    with caplog.at_level(logging.INFO, logger=auth.database.logger.name):
+        auth.database.create_tables(raise_on_error=True)
+    assert "Tables created successfully." in caplog.text
+
+
+def test_public_exports():
+    assert auth.check_schema is check_schema
+    assert auth.SchemaMismatchError is SchemaMismatchError
+    assert {"check_schema", "SchemaMismatchError"} <= set(auth.__all__)