auth 3.2.0__tar.gz → 3.4.0__tar.gz

{auth-3.2.0 → auth-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth
-Version: 3.2.0
+Version: 3.4.0
 Summary: Authorization for humans
 Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
 License-Expression: MIT
@@ -16,13 +16,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: flask<4,>=2.0.0

{auth-3.2.0 → auth-3.4.0}/auth/__init__.py

@@ -56,6 +56,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 +65,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()

{auth-3.2.0 → auth-3.4.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.2.0 → auth-3.4.0}/auth/database.py

@@ -7,17 +7,18 @@ 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_reconcile import (
     GRANDFATHER_MARKER,  # noqa: F401  - re-exported; tests and embedded callers import it from here
     _apply_tenant_rls,
+    _ensure_audit_partition_runway,
     _grandfather_strict_users,
     _reconcile_text_columns,
 )
@@ -46,6 +47,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
@@ -82,35 +124,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,
@@ -137,10 +160,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
@@ -160,16 +183,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,
@@ -199,10 +222,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):
@@ -350,6 +376,7 @@ def create_tables(raise_on_error: bool = False):
         # is how a fresh database came up with the junction tables unprotected
         # -- grandfathering raised, and the RLS step below it never ran.
         _apply_tenant_rls(engine)
+        _ensure_audit_partition_runway(engine)
         _reconcile_text_columns(engine)
         _grandfather_strict_users(engine)
         logger.info("Tables created successfully.")

{auth-3.2.0 → auth-3.4.0}/auth/routes/public.py

@@ -19,6 +19,26 @@ _COMMIT_PROBE_LOCK = threading.Lock()
 _last_commit_verdict = ["ready"]
 
 
+
+def _audit_partitions():
+    """What the boot-time runway check saw, for /readyz.
+
+    Reported as a FIELD, never as the verdict: rows stranded in the default
+    partition are a retention problem, and pulling a healthy node out of the
+    load balancer over one would turn a slow leak into an outage.
+
+    It exists at all because logging is not a channel everywhere -- vm-2
+    captures no application log line, so the CRITICAL this condition also emits
+    is unreachable there.
+    """
+    try:
+        from auth.schema_reconcile import audit_partition_state
+
+        return dict(audit_partition_state)
+    except Exception:
+        return {"checked": False, "stranded": None, "newest": None}
+
+
 def _pool_depth():
     """Connection-pool saturation. Needs no database round trip.
 
@@ -146,6 +166,7 @@ def register(app):
                 "status": _last_commit_verdict[0],
                 "reason": "commit probe already in flight",
                 "pool": pool_depth,
+                "audit_partitions": _audit_partitions(),
             }
             return jsonify(body), (200 if _last_commit_verdict[0] == "ready" else 503)
         try:
@@ -160,7 +181,16 @@ def register(app):
         except Exception:
             logger.exception("readiness check failed: commit path unavailable")
             _last_commit_verdict[0] = "unready"
-            return jsonify({"status": "unready", "reason": "commit path", "pool": pool_depth}), 503
+            return jsonify({
+                "status": "unready",
+                "reason": "commit path",
+                "pool": pool_depth,
+                "audit_partitions": _audit_partitions(),
+            }), 503
         finally:
             _COMMIT_PROBE_LOCK.release()
-        return jsonify({"status": "ready", "pool": pool_depth})
+        return jsonify({
+            "status": "ready",
+            "pool": pool_depth,
+            "audit_partitions": _audit_partitions(),
+        })

{auth-3.2.0 → auth-3.4.0}/auth/schema_reconcile.py

@@ -15,6 +15,7 @@ junction tables holding every tenant's authorization edges under no policy.
 """
 
 import logging
+from typing import Any
 
 from sqlalchemy.engine import Engine
 
@@ -22,6 +23,11 @@ from auth.config import DatabaseType, get_settings
 
 logger = logging.getLogger(__name__)
 
+#: What the last audit-partition runway check saw, so /readyz can report it.
+#: Logging is not a channel on every deployment -- vm-2 captures no application
+#: log line at all, which makes a CRITICAL there unreachable by anyone.
+audit_partition_state: dict = {"checked": False, "stranded": None, "newest": None}
+
 def _apply_tenant_rls(target_engine: Engine) -> None:
     """Secure any tenant-scoped table that ``create_all`` has just created.
 
@@ -50,7 +56,7 @@ def _apply_tenant_rls(target_engine: Engine) -> None:
     schema = settings.database_schema or "public"
     try:
         with target_engine.begin() as conn:
-            result = conn.execute(
+            result: Any = conn.execute(
                 text(f'SELECT {schema}.apply_tenant_rls()')  # noqa: S608
             ).scalar_one()
         logger.info("apply_tenant_rls: %s", result)
@@ -62,6 +68,92 @@ def _apply_tenant_rls(target_engine: Engine) -> None:
         )
 
 
+def _ensure_audit_partition_runway(target_engine: Engine, months: int = 6) -> None:
+    """Keep monthly audit_log partitions provisioned ahead of now.
+
+    Partitions are finite and nothing renewed them. When they run out, rows do
+    not fail -- they land in audit_log_default, which
+    drop_audit_log_partitions_before deliberately skips, so retention can never
+    reclaim them and the growth problem partitioning solved returns with no
+    visible symptom (issuedb #15; production runway ended 2027-08).
+
+    Called here rather than scheduled in-process: create_tables runs pre-fork
+    under preload_app, so this executes once per service start, not once per
+    worker, and holds no thread across fork. A cron on the database-adjacent
+    host is still the durable answer for a deployment that runs longer than its
+    runway without restarting; this removes the cliff for one that restarts.
+
+    Non-raising, like everything beside it. A deployment whose role cannot
+    create partitions still starts, and rows in the default partition are
+    reported loudly below rather than silently absorbed.
+    """
+    from sqlalchemy import text
+
+    settings = get_settings()
+    if settings.database_type != DatabaseType.POSTGRESQL:
+        return
+    schema = settings.database_schema or "public"
+    try:
+        with target_engine.begin() as conn:
+            if conn.execute(
+                text("SELECT to_regproc(:fn) IS NULL"),
+                {"fn": f"{schema}.provision_audit_log_partition"},
+            ).scalar():
+                logger.info(
+                    "audit partition runway: provisioner absent, skipping"
+                )
+                return
+            created = []
+            for ahead in range(months + 1):
+                result: Any = conn.execute(
+                    text(
+                        f"SELECT {schema}.provision_audit_log_partition("  # noqa: S608
+                        "(date_trunc('month', now()) + make_interval(months => :n))::date)"
+                    ),
+                    {"n": ahead},
+                ).scalar_one()
+                if "created" in str(result):
+                    created.append(str(result))
+            stranded: int = conn.execute(
+                text(f"SELECT count(*) FROM {schema}.audit_log_default")  # noqa: S608
+            ).scalar_one()
+            newest = conn.execute(
+                text(
+                    "SELECT c.relname FROM pg_class c "
+                    "JOIN pg_inherits i ON i.inhrelid = c.oid "
+                    "WHERE i.inhparent = to_regclass(:p) "
+                    "AND c.relname <> 'audit_log_default' "
+                    "ORDER BY c.relname DESC LIMIT 1"
+                ),
+                {"p": f"{schema}.audit_log"},
+            ).scalar()
+    except Exception as exc:
+        logger.warning(
+            "audit partition runway could not be ensured (%s); "
+            "if partitions run out, rows land in audit_log_default and "
+            "retention cannot reclaim them",
+            exc.__class__.__name__,
+        )
+        return
+
+    audit_partition_state.update(
+        {"checked": True, "stranded": int(stranded), "newest": newest}
+    )
+    logger.info(
+        "audit partition runway: %d month(s) ahead, %d created this start",
+        months,
+        len(created),
+    )
+    if stranded:
+        logger.critical(
+            "AUDIT PARTITION RUNWAY WAS EXHAUSTED: %d row(s) are in "
+            "audit_log_default. Retention skips that partition, so they can "
+            "never be reclaimed. They must be moved into a real partition by "
+            "hand once one covers their timestamps.",
+            stranded,
+        )
+
+
 def _reconcile_text_columns(target_engine: Engine) -> None:
     """Widen live ``character varying`` columns to TEXT where the current models
     declare :class:`~sqlalchemy.Text` (issuedb #21).

{auth-3.2.0 → auth-3.4.0}/auth/services/rbac.py

@@ -1,7 +1,7 @@
 """Roles, memberships and permissions — the mutating RBAC core."""
 
 import logging
-from typing import Optional
+from typing import Any, Optional
 
 from sqlalchemy import func, select
 
@@ -139,7 +139,7 @@ class RbacMixin(QueryMixin):
                 set_={"is_active": True, "modified": func.now()},
             )
             self.db.execute(stmt)
-            membership_id = self.db.execute(
+            membership_id: Any = self.db.execute(
                 select(m_table.c.id).where(
                     m_table.c.creator == self.client,
                     m_table.c.user == encrypted_user,
@@ -258,7 +258,7 @@ class RbacMixin(QueryMixin):
                 )
             )
             self.db.execute(stmt)
-            perm_id = self.db.execute(
+            perm_id: Any = self.db.execute(
                 select(p_table.c.id).where(
                     p_table.c.creator == self.client,
                     p_table.c.name == encrypted_name,

{auth-3.2.0 → auth-3.4.0}/auth/services/tenant.py

@@ -4,6 +4,8 @@ import json
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple, cast
 
+from sqlalchemy import desc, or_
+
 from auth.api_keys import generate_rotate_key
 from auth.audit import AuditLog, client_fingerprint
 from auth.models.sql import (
@@ -12,6 +14,8 @@ from auth.models.sql import (
 )
 from auth.services.base import ServiceBase, _utcnow
 
+_api_key_table = AuthApiKey.__table__
+
 
 class TenantMixin(ServiceBase):
     """Per-tenant settings, strict-identity checks and audit reads."""
@@ -112,7 +116,7 @@ class TenantMixin(ServiceBase):
         if action:
             query = query.filter(AuditLog.action == action.upper())
         total = query.count()
-        rows = query.order_by(AuditLog.id.desc()).offset(offset).limit(limit).all()
+        rows: List[Any] = query.order_by(desc(AuditLog.id)).offset(offset).limit(limit).all()
         entries = [
             {
                 "id": row.id,
@@ -131,15 +135,23 @@ class TenantMixin(ServiceBase):
 
     def user_is_key_backed(self, user: str) -> bool:
         """True when the user holds ≥1 active, unexpired API key here."""
-        row = (
+        row: Any = (
             self.db.query(AuthApiKey.id)
             .filter(
                 AuthApiKey.creator == self.client,
                 AuthApiKey._user == self._get_encrypted_user(user),
-                AuthApiKey.is_active,
+                # Core column rather than the mapped attribute. SQLAlchemy 2.1's
+                # stubs resolve a legacy `x = Column(...)` attribute to Never, so
+                # the bare `AuthApiKey.is_active` poisons the whole chain and every
+                # statement after it reads as unreachable. __table__.c types as a
+                # KeyedColumnElement and emits byte-identical SQL, verified.
+                _api_key_table.c.is_active.is_(True),
             )
             .filter(
-                (AuthApiKey.expires_at.is_(None)) | (AuthApiKey.expires_at > _utcnow())
+                or_(
+                    _api_key_table.c.expires_at.is_(None),
+                    _api_key_table.c.expires_at > _utcnow(),
+                )
             )
             .first()
         )

{auth-3.2.0 → auth-3.4.0}/auth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth
-Version: 3.2.0
+Version: 3.4.0
 Summary: Authorization for humans
 Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
 License-Expression: MIT
@@ -16,13 +16,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: flask<4,>=2.0.0

{auth-3.2.0 → auth-3.4.0}/auth.egg-info/SOURCES.txt

@@ -65,11 +65,14 @@ tests/test_api_keys.py
 tests/test_api_keys_encryption.py
 tests/test_audit_integrity.py
 tests/test_client.py
+tests/test_client_exceptions_do_not_render_payload.py
 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
 tests/test_encryption.py
 tests/test_encryption_integration.py
@@ -79,10 +82,12 @@ tests/test_key_rotation.py
 tests/test_log_redaction.py
 tests/test_no_bundled_libpq.py
 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_self_service_audit.py
 tests/test_server.py
 tests/test_service_lifecycle.py
+tests/test_settings_do_not_echo_secrets.py
 tests/test_strict_default.py
 tests/test_strict_users.py

{auth-3.2.0 → auth-3.4.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auth"
-version = "3.2.0"
+version = "3.4.0"
 description = "Authorization for humans"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = "MIT"
 authors = [
     {name = "Farshid Ashouri", email = "farsheed.ashouri@gmail.com"}
@@ -25,7 +25,6 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -185,7 +184,7 @@ line_length = 88
 
 [tool.mypy]
 # Lowest version current mypy can target; the service deploys on 3.11 and CI
-# also runs 3.12. (Package metadata still advertises >=3.9 for older installs.)
+# also runs 3.12. (Package metadata advertises >=3.10.)
 python_version = "3.10"
 # `python -m build` leaves a copy of the package under build/lib/, which mypy
 # would otherwise report as a duplicate module — so `make build` broke the next

auth-3.4.0/tests/test_client_exceptions_do_not_render_payload.py

@@ -0,0 +1,52 @@
+import pytest
+
+from auth.client._transport import AuthRefused, AuthTransportError
+
+SENTINEL = "Zq7SentinelCredential9xK"
+PAYLOAD = {"message": "denied", "details": {"echoed": SENTINEL}}
+
+
+def test_refusal_renders_only_its_message():
+    """auth ships this client; other platforms run it and log its exceptions.
+
+    A three-argument exception normally renders its whole args tuple through
+    Exception.__str__, which would put the upstream response body into every
+    ``log.error(e)`` a consumer writes. AuthRefused passes only the message to
+    super().__init__ and keeps status and payload as attributes, so the safe
+    rendering is the default one and the body is opt-in.
+    """
+    exc = AuthRefused("auth refused the request: HTTP 401", 401, PAYLOAD)
+
+    assert SENTINEL not in str(exc)
+    assert SENTINEL not in repr(exc)
+    assert SENTINEL not in str(exc.args)
+    assert str(exc) == "auth refused the request: HTTP 401"
+
+
+def test_the_payload_is_still_reachable_deliberately():
+    """The other direction: redaction must not cost the caller the detail.
+
+    A guard that only proved the body is absent would pass equally if payload
+    were dropped entirely, which would break the 409 hints this argument exists
+    to carry.
+    """
+    exc = AuthRefused("auth refused the request: HTTP 409", 409, PAYLOAD)
+    assert exc.payload == PAYLOAD
+    assert exc.status == 409
+
+
+def test_the_detector_would_see_a_leak():
+    """Known-positive control.
+
+    If Exception.__str__ ever stopped rendering extra args, the assertions
+    above would hold for a reason that has nothing to do with AuthRefused, and
+    the guard would be protecting nothing.
+    """
+    leaky = AuthTransportError("upstream said", PAYLOAD)
+    assert SENTINEL in str(leaky)
+
+
+def test_refusal_is_still_a_transport_error_subclass():
+    assert issubclass(AuthRefused, AuthTransportError)
+    with pytest.raises(AuthTransportError):
+        raise AuthRefused("m", 400, None)