auth 3.1.1__tar.gz → 3.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth
-Version: 3.1.1
+Version: 3.2.0
 Summary: Authorization for humans
 Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
 License-Expression: MIT
@@ -31,12 +31,14 @@ Requires-Dist: sqlalchemy<3,>=2.0.0
 Requires-Dist: waitress<4,>=2.0.0
 Requires-Dist: cryptography>=3.0.0
 Requires-Dist: APScheduler<4,>=3.0.0
-Requires-Dist: psycopg[binary]<4,>=3.0.0
+Requires-Dist: psycopg<4,>=3.0.0
 Requires-Dist: pydantic<3,>=2.0.0
 Requires-Dist: pydantic-settings<3,>=2.0.0
 Requires-Dist: requests<3,>=2.25.0
 Requires-Dist: bleach<7,>=5.0.0
 Requires-Dist: python-json-logger<4,>=3.1.0
+Provides-Extra: c
+Requires-Dist: psycopg[c]<4,>=3.0.0; extra == "c"
 Provides-Extra: ratelimit
 Requires-Dist: flask-limiter>=3.0.0; extra == "ratelimit"
 Provides-Extra: migrations

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

@@ -4,6 +4,7 @@ from importlib.metadata import PackageNotFoundError, version
 from typing import Optional
 
 from auth.client import (  # Import the new client
+    AuthRefused,
     AuthTransportError,
     Client,
     EnhancedAuthClient,
@@ -140,6 +141,7 @@ class Authorization:
 # Export the new client for users who want enhanced features
 __all__ = [
     "Authorization",
+    "AuthRefused",
     "AuthTransportError",
     "Client",
     "EnhancedAuthClient",

{auth-3.1.1 → auth-3.2.0}/auth/api_keys.py

@@ -15,7 +15,11 @@ import uuid
 from typing import Tuple
 
 API_KEY_PREFIX = "rak_"
+#: Recovery ("rotate") keys. A different prefix so a credential is never
+#: mistaken for the other kind, and so a leaked one is identifiable on sight.
+ROTATE_KEY_PREFIX = "rrk_"
 API_KEY_PATTERN = re.compile(r"^rak_[0-9A-Za-z]{43}$")
+ROTATE_KEY_PATTERN = re.compile(r"^rrk_[0-9A-Za-z]{43}$")
 
 # "rak_" + first 8 payload chars — safe to store and display in listings.
 KEY_PREFIX_LEN = 12
@@ -48,3 +52,21 @@ def generate_api_key() -> Tuple[str, str, str, str]:
 def hash_api_key(secret: str) -> str:
     """SHA-256 hex digest of the full secret string (equality-queryable)."""
     return hashlib.sha256(secret.encode()).hexdigest()
+
+
+def generate_rotate_key() -> Tuple[str, str]:
+    """Mint a recovery key: returns ``(secret, secret_hash)``.
+
+    Same construction and entropy as a user API key -- 256 bits from
+    ``secrets.token_bytes(32)`` -- because it guards more, not less: whoever
+    holds it can take over the namespace without the client key. Only the hash
+    is stored, and the secret is disclosed exactly once.
+    """
+    payload = _base62(secrets.token_bytes(32)).rjust(_PAYLOAD_LEN, _ALPHABET[0])
+    secret = ROTATE_KEY_PREFIX + payload
+    return secret, hash_api_key(secret)
+
+
+def validate_rotate_key_format(secret: str) -> bool:
+    """Shape check before any database work."""
+    return bool(ROTATE_KEY_PATTERN.match(secret))

{auth-3.1.1 → auth-3.2.0}/auth/audit.py

@@ -46,6 +46,8 @@ class AuditAction(Enum):
     GET_SETTINGS = "GET_SETTINGS"
     UPDATE_SETTINGS = "UPDATE_SETTINGS"
     GET_AUDIT = "GET_AUDIT"
+    GET_ROTATE_KEY = "GET_ROTATE_KEY"
+    RECOVER_KEY = "RECOVER_KEY"
 
 
 class AuditLog(Base):
@@ -176,6 +178,23 @@ def _emit_structured_log(
     audit_logger.info(json.dumps(log_msg))
 
 
+def _bind_audit(session, client_id: str) -> None:
+    """Bind the audit tenant so RLS admits the row (no-op off PostgreSQL).
+
+    audit_log's policy compares ``client_id`` against a session variable, and
+    the value is bound VERBATIM: every caller already passes a fingerprint (see
+    ``client_ref`` in auth/decorators.py), and ``_build_audit_entry`` stores it
+    unchanged. Fingerprinting it again here would bind a fingerprint OF a
+    fingerprint, which matches no row and rejects every audit write.
+    """
+    try:
+        from auth.rls import AUDIT_GUC, bind_session
+
+        bind_session(session, **{AUDIT_GUC: client_id})
+    except Exception:  # pragma: no cover - binding must never break an audit write
+        pass
+
+
 def record_audit(
     session,
     *,
@@ -196,6 +215,7 @@ def record_audit(
     surrounding request (fail-closed), never leave a committed mutation
     unaudited.
     """
+    _bind_audit(session, client_id)
     session.add(
         _build_audit_entry(
             client_id, user, action, resource, details, ip_address, user_agent, success
@@ -224,6 +244,7 @@ def log_audit_event(
     """
     session = SessionLocal()
     try:
+        _bind_audit(session, client_id)
         session.add(
             _build_audit_entry(
                 client_id, user, action, resource, details, ip_address, user_agent, success

{auth-3.1.1 → auth-3.2.0}/auth/client/__init__.py

@@ -13,6 +13,7 @@ their ``__module__``.
 from auth.circuit_breaker import circuit_breaker
 from auth.client._transport import (
     _RETRY_METHODS,
+    AuthRefused,
     AuthTransportError,
     RetryableHTTPAdapter,
     _build_retry,
@@ -44,6 +45,7 @@ class Client(EnhancedAuthClient):
 
 __all__ = [
     "ApiKeyMixin",
+    "AuthRefused",
     "AuthTransportError",
     "Client",
     "ClientBase",

{auth-3.1.1 → auth-3.2.0}/auth/client/_transport.py

@@ -11,14 +11,37 @@ _RETRY_METHODS = ["HEAD", "GET", "OPTIONS", "POST", "PUT", "DELETE"]
 class AuthTransportError(Exception):
     """The client could not get an answer from the auth service.
 
-    Raised by every client method on transport failure (connection failure,
-    exhausted retries, open circuit breaker, non-2xx status) since 3.0.0.
+    Raised by every client method when no answer could be obtained:
+    connection failure, exhausted retries, open circuit breaker, or a 5xx.
+    A 4xx raises :class:`AuthRefused`, a subclass — the service DID answer,
+    it refused the request.
     Distinguishes "we could not ask" from a genuine negative answer such as
     ``has_permission: false`` — map it to your unavailable/503 path, never
     to a denial.
     """
 
 
+class AuthRefused(AuthTransportError):
+    """The auth service answered and refused the request (a 4xx).
+
+    Subclasses :class:`AuthTransportError` so existing handlers keep working,
+    but lets a caller tell "auth would not accept this" from "auth could not be
+    reached". Reported by a consumer whose platform-admin check logged "auth
+    unreachable at login" while auth was up, answering, and simply rejecting a
+    subject containing ``|``: that sends whoever reads the log to the health
+    endpoint and the network when the cause is the shape of a string.
+
+    ``status`` is the HTTP status; ``payload`` is the decoded body when there
+    was one, so actionable errors (such as the 409 ``user_not_key_backed`` hint)
+    survive instead of being flattened into a transport message.
+    """
+
+    def __init__(self, message: str, status: int, payload=None):
+        super().__init__(message)
+        self.status = status
+        self.payload = payload
+
+
 def _build_retry(total, backoff_factor, status_forcelist) -> Retry:
     """Build a Retry that works on both urllib3 1.x and 2.x.
 

{auth-3.1.1 → auth-3.2.0}/auth/client/base.py

@@ -11,6 +11,7 @@ from requests.exceptions import ConnectionError
 
 from auth.circuit_breaker import circuit_breaker
 from auth.client._transport import (
+    AuthRefused,
     AuthTransportError,
     RetryableHTTPAdapter,
     _build_retry,
@@ -168,6 +169,20 @@ class ClientBase:
                     return text_response
 
             except requests.exceptions.RequestException as e:
+                # A 4xx means the service ANSWERED and refused. Collapsing that
+                # into a transport failure sends the reader to the health
+                # endpoint and the network when the cause is the request itself.
+                resp = getattr(e, "response", None)
+                if resp is not None and 400 <= resp.status_code < 500:
+                    try:
+                        payload = resp.json()
+                    except Exception:
+                        payload = None
+                    raise AuthRefused(
+                        f"auth refused the request: HTTP {resp.status_code}",
+                        resp.status_code,
+                        payload,
+                    ) from e
                 # Convert to our expected exception type
                 raise ConnectionError(f"Request failed: {str(e)}") from e
 
@@ -176,6 +191,8 @@ class ClientBase:
             try:
                 cb_result: Dict[str, Any] = circuit_breaker("api_call")(request_func)()
                 return cb_result
+            except AuthRefused:
+                raise  # a refusal is an answer; it is not a breaker event
             except Exception as e:
                 raise ConnectionError(
                     f"Circuit breaker prevented request: {str(e)}"
@@ -195,6 +212,8 @@ class ClientBase:
         compatibility and intentionally unused: inputs like key material must
         never ride on an exception.
         """
+        if isinstance(exc, AuthRefused):
+            raise exc
         raise AuthTransportError(str(exc)) from exc
 
     def ping(self) -> Dict[str, Any]:

{auth-3.1.1 → auth-3.2.0}/auth/database.py

@@ -15,6 +15,12 @@ from sqlalchemy.orm import Session, sessionmaker
 from sqlalchemy.pool import Pool
 
 from auth.config import DatabaseType, 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,
+    _grandfather_strict_users,
+    _reconcile_text_columns,
+)
 
 
 def _forced_sslmode(database_url: str) -> Optional[str]:
@@ -92,8 +98,12 @@ class DatabaseEngine(metaclass=SingletonMeta):
         settings = get_settings()
 
         if settings.database_type == DatabaseType.POSTGRESQL:
-            # Conservative sizing for production with multiple workers
-            return (5, 5)  # 10 max connections per worker
+            # 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)
@@ -106,7 +116,17 @@ class DatabaseEngine(metaclass=SingletonMeta):
             "connect_timeout": 30,
             "application_name": "auth_server",
             # Set statement timeout to prevent long-running queries
-            "options": "-c statement_timeout=30000",  # 30 seconds
+            # 10s: the slowest legitimate operation is a key rotation, measured
+            # at ~0.12 ms/row (~1s for the largest namespace on this deployment),
+            # so this leaves 10x headroom.
+            #
+            # NOTE: statement_timeout does NOT bound COMMIT. A commit stall is
+            # therefore unaffected by this value, which is why worker
+            # concurrency -- not this timeout -- is the mitigation for a stalled
+            # database. tcp_user_timeout would bound it at the socket, but
+            # dropping a connection mid-COMMIT leaves the outcome ambiguous, and
+            # an ambiguous permission grant is a worse failure than a slow one.
+            "options": "-c statement_timeout=10000",  # 10 seconds
         }
 
         forced = _forced_sslmode(database_url)
@@ -119,7 +139,7 @@ class DatabaseEngine(metaclass=SingletonMeta):
             poolclass=pool.QueuePool,  # Explicitly use QueuePool
             pool_size=pool_size,
             max_overflow=max_overflow,
-            pool_timeout=30,  # Wait up to 30s for a connection
+            pool_timeout=10,  # Fail fast rather than queueing behind a stalled DB
             pool_recycle=3600,  # Recycle connections after 1 hour
             pool_pre_ping=True,  # Verify connections before using them
             # Performance settings
@@ -325,6 +345,11 @@ def create_tables(raise_on_error: bool = False):
                     text(f'CREATE SCHEMA IF NOT EXISTS "{settings.database_schema}"')
                 )
         Base.metadata.create_all(bind=engine, checkfirst=True)
+        # Row level security first, and each step separately: these are
+        # independent reconciliations, and letting one exception abort the rest
+        # 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)
         _reconcile_text_columns(engine)
         _grandfather_strict_users(engine)
         logger.info("Tables created successfully.")
@@ -334,148 +359,6 @@ def create_tables(raise_on_error: bool = False):
             raise
 
 
-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).
-
-    ``create_all(checkfirst=True)`` creates missing tables but never ALTERs an
-    existing one, so an embedded database created by a pre-2.x version keeps the
-    narrow ``varchar`` widths those versions declared. Encryption made several of
-    those columns hold ciphertext far longer than the plaintext they used to, so
-    the mismatch surfaces as ``StringDataRightTruncation`` on write — highway hit
-    exactly this on ``auth_membership.user`` (varchar(64)) when a longer email
-    was encrypted, inside ``add_membership`` (agent-mail thr-d99bb6c79b894ff69f16).
-
-    Only columns the models declare as Text are touched. A bounded ``String`` is
-    a deliberate width — ``audit_log.user`` is a 64-char fingerprint, not a user
-    identifier — and is left alone. PostgreSQL only: SQLite does not enforce
-    varchar length, so there is nothing to reconcile there.
-
-    Non-raising, like everything else in ``create_tables``: a runtime role
-    without DDL rights must still be able to start the app.
-    """
-    from sqlalchemy import Text, inspect, text
-
-    import auth.audit  # noqa: F401  (registers AuditLog in Base.metadata)
-    from auth.models.sql import Base
-
-    if target_engine.dialect.name != "postgresql":
-        return
-
-    settings = get_settings()
-    schema = settings.database_schema or None
-    inspector = inspect(target_engine)
-    try:
-        existing_tables = set(inspector.get_table_names(schema=schema))
-    except Exception:
-        logger.exception("text-column reconciliation could not list tables")
-        return
-
-    widened: list[str] = []
-    for table in Base.metadata.sorted_tables:
-        if table.name not in existing_tables:
-            continue
-        wanted = {c.name for c in table.columns if isinstance(c.type, Text)}
-        if not wanted:
-            continue
-        try:
-            live = inspector.get_columns(table.name, schema=schema)
-        except Exception:
-            logger.exception(
-                "text-column reconciliation could not inspect %s", table.name
-            )
-            continue
-        for col in live:
-            if col["name"] not in wanted:
-                continue
-            # VARCHAR carries a length; TEXT does not. Anything already
-            # unbounded needs no ALTER, which keeps this pass a no-op on a
-            # database that already matches the models.
-            if getattr(col["type"], "length", None) is None:
-                continue
-            qualified = f'"{schema}".' if schema else ""
-            stmt = (
-                f'ALTER TABLE {qualified}"{table.name}" '
-                f'ALTER COLUMN "{col["name"]}" TYPE TEXT'
-            )
-            try:
-                with target_engine.begin() as conn:
-                    conn.execute(text(stmt))
-                widened.append(f"{table.name}.{col['name']}")
-            except Exception:
-                logger.exception(
-                    "could not widen %s.%s to TEXT; a pre-2.x column width "
-                    "remains and long encrypted values may fail to write",
-                    table.name,
-                    col["name"],
-                )
-
-    if widened:
-        logger.warning(
-            "widened %d pre-2.x varchar column(s) to TEXT to match the current "
-            "models: %s",
-            len(widened),
-            ", ".join(widened),
-        )
-
-
-# Marker creator recording that the one-shot 3.0.0 grandfathering pass ran on
-# this database. Reserved — never use it as a real tenant identifier.
-GRANDFATHER_MARKER = "__meta:grandfathered-3.0__"
-
-
-def _grandfather_strict_users(target_engine: Engine) -> None:
-    """One-shot 3.0.0 flip protection (SPEC 0012): write explicit
-    ``strict_users = false`` rows for every creator that exists on this
-    database, then record a marker so the pass never runs again.
-
-    3.0.0 makes no-settings-row tenants strict by default; this pass is what
-    guarantees that flip reaches ONLY tenants created after it ran — every
-    pre-existing tenant keeps its behavior as an explicit, auditable opt-out
-    it can change later. Runs inside create_tables so embedded consumers get
-    the same protection our deployment gets from the migretti migration
-    (both are marker-guarded, so they compose idempotently).
-    """
-    from typing import cast
-
-    from sqlalchemy import Table, literal, select, union
-
-    from auth.models.sql import (
-        AuthApiKey,
-        AuthGroup,
-        AuthMembership,
-        AuthPermission,
-        AuthTenantSettings,
-    )
-
-    settings_t = cast(Table, AuthTenantSettings.__table__)
-    with target_engine.begin() as conn:
-        marker_exists = conn.execute(
-            select(settings_t.c.id).where(settings_t.c.creator == GRANDFATHER_MARKER)
-        ).first()
-        if marker_exists:
-            return
-        creators = union(
-            *(
-                select(t.__table__.c.creator)
-                for t in (AuthGroup, AuthMembership, AuthPermission, AuthApiKey)
-            )
-        ).subquery()
-        already = select(settings_t.c.creator)
-        conn.execute(
-            settings_t.insert().from_select(
-                ["creator", "strict_users"],
-                select(creators.c.creator, literal(False)).where(
-                    creators.c.creator.notin_(already)
-                ),
-            )
-        )
-        conn.execute(
-            settings_t.insert().values(creator=GRANDFATHER_MARKER, strict_users=False)
-        )
-    logger.info("strict_users grandfathering pass completed (one-shot).")
-
-
 def log_pool_stats():
     """Log current connection pool statistics"""
     stats = get_pool_status()

auth-3.2.0/auth/keycheck.py

@@ -0,0 +1,233 @@
+"""Boot-time verification that the configured encryption key matches stored data.
+
+Field encryption is deterministic and used for equality lookups, so
+encrypt-to-store and encrypt-to-query share one key derivation. If the key
+changes, both sides move together into a namespace where nothing matches: every
+membership lookup misses, every authorization answer becomes "denied", and each
+one is returned with HTTP 200. Nothing in the request path can notice, because
+the query path never decrypts — it compares ciphertext.
+
+This module samples rows that are actually encrypted and decrypts them. A wrong
+key fails authentication in ``DeterministicEncryption._open`` (the IV is an HMAC
+of the plaintext, re-derived and constant-time compared), so the failure is
+loud here even though it is silent everywhere else.
+
+The states are distinguished deliberately:
+
+``ok``
+    Encrypted rows exist and decrypt, or nothing is encrypted yet.
+``mismatch``
+    Encrypted rows exist and this key cannot read them. Serving would answer
+    every authorization question wrongly, so ``/api`` is refused instead.
+``unverified``
+    The check could not run (database unavailable at boot). Not an assertion
+    that the key is good — the service starts, because refusing to boot on a
+    transient database problem turns a blip into a restart loop.
+"""
+
+import logging
+from typing import Optional
+
+import auth.encryption as _encryption
+
+logger = logging.getLogger(__name__)
+
+OK = "ok"
+MISMATCH = "mismatch"
+UNVERIFIED = "unverified"
+
+_V2_PREFIX = "v2:"
+
+#: Reserved tenant for the canary row. The client-key validator requires a real
+#: UUID4, so the nil UUID is refused at the door and can never be a caller's
+#: namespace -- which is what makes it safe to reserve.
+SENTINEL_TENANT = "00000000-0000-0000-0000-000000000000"
+_CANARY_PLAINTEXT = "auth-encryption-canary-v1"
+
+#: Tables that must be protected once the RLS migration has run.
+_RLS_TABLES = (
+    "auth_group",
+    "auth_membership",
+    "auth_permission",
+    "auth_api_key",
+    "auth_tenant_settings",
+    "membership_groups",
+    "permission_groups",
+)
+
+#: Checked the same way, but only when present. audit_log is created by
+#: ``setup_audit_tables`` rather than by create_all, so a deployment with audit
+#: logging switched off legitimately has no such table -- while one that DOES
+#: have it is holding tenant data and must protect it like any other.
+_RLS_OPTIONAL_TABLES = ("audit_log",)
+
+_state = OK
+_detail = "not yet checked"
+
+
+def state() -> str:
+    """Current verdict: ``ok``, ``mismatch`` or ``unverified``."""
+    return _state
+
+
+def detail() -> str:
+    """Human-readable reason behind :func:`state`."""
+    return _detail
+
+
+def is_degraded() -> bool:
+    """True when this deployment cannot safely answer authorization questions."""
+    return _state == MISMATCH
+
+
+def _set(new_state: str, why: str) -> str:
+    global _state, _detail
+    # A later OK must never clear an earlier failure. Boot runs several checks
+    # in sequence and the last one would otherwise decide the verdict for all
+    # of them -- which is how the RLS check silently stopped mattering the first
+    # time this ran: it reported a problem and the encryption check overwrote it.
+    if _state == MISMATCH and new_state != MISMATCH:
+        return _state
+    if _state == UNVERIFIED and new_state == OK:
+        return _state
+    _state, _detail = new_state, why
+    if new_state == MISMATCH:
+        logger.critical("STARTUP CHECK FAILED: %s", why)
+    elif new_state == UNVERIFIED:
+        logger.warning("startup check inconclusive: %s", why)
+    else:
+        logger.info("startup check: %s", why)
+    return new_state
+
+
+def verify_encryption_key(db) -> str:
+    """Check the configured key against this deployment's canary.
+
+    The canary lives under :data:`SENTINEL_TENANT` so it can be read with Row
+    Level Security in force -- the previous implementation sampled rows across
+    tenants, which RLS would reduce to "nothing to verify against", passing
+    vacuously and silently disabling this check.
+
+    Never raises: a database problem yields ``unverified`` rather than
+    preventing startup, because refusing to boot on a transient outage turns a
+    blip into a restart loop.
+    """
+    from auth.models.sql import AuthTenantSettings
+    from auth.rls import bind_tenant
+
+    fe = _encryption.field_encryption
+    try:
+        bind_tenant(db, SENTINEL_TENANT)
+        row = (
+            db.query(AuthTenantSettings)
+            .filter(AuthTenantSettings.creator == SENTINEL_TENANT)
+            .first()
+        )
+    except Exception as exc:
+        return _set(UNVERIFIED, f"could not read the canary: {exc.__class__.__name__}")
+
+    stored = getattr(row, "canary", None) if row is not None else None
+
+    if not stored:
+        if not fe.enabled or fe.encryptor is None:
+            return _set(OK, "encryption disabled and no canary stored")
+        try:
+            value = fe.encryptor.encrypt(_CANARY_PLAINTEXT, SENTINEL_TENANT)
+            if row is None:
+                row = AuthTenantSettings(creator=SENTINEL_TENANT, strict_users=False)
+                db.add(row)
+            row.canary = value
+            db.commit()
+            return _set(OK, "canary written for this deployment")
+        except Exception as exc:
+            db.rollback()
+            return _set(UNVERIFIED, f"could not write the canary: {exc.__class__.__name__}")
+
+    if not fe.enabled:
+        return _set(
+            MISMATCH,
+            "this deployment has an encryption canary but field encryption is "
+            "disabled - every authorization lookup would miss and answer "
+            "negatively",
+        )
+    try:
+        recovered = fe.encryptor.decrypt(str(stored), SENTINEL_TENANT)  # type: ignore[union-attr]
+    except Exception:
+        return _set(
+            MISMATCH,
+            "the configured AUTH_ENCRYPTION_KEY cannot decrypt this "
+            "deployment's canary - every authorization lookup would miss and "
+            "answer negatively",
+        )
+    if recovered != _CANARY_PLAINTEXT:
+        return _set(MISMATCH, "the canary decrypted to an unexpected value")
+    return _set(OK, "encryption key verified against the deployment canary")
+
+
+def verify_row_level_security(db) -> str:
+    """Confirm RLS is actually in force, not merely enabled.
+
+    The application owns these tables and PostgreSQL does not apply RLS to a
+    table's owner, so ``ENABLE`` without ``FORCE`` protects nothing while every
+    casual check looks correct. That is the one way this feature fails silently,
+    so it is asserted at boot rather than assumed.
+
+    Skipped on SQLite, which has no RLS.
+    """
+    from sqlalchemy import text
+
+    try:
+        if db.get_bind().dialect.name != "postgresql":
+            return OK
+        from auth.config import get_settings
+
+        # The configured schema, NOT current_schema(): search_path rarely points
+        # at it, so current_schema() matched no tables and the check reported
+        # "nothing to check" -- passing while RLS was off.
+        schema = get_settings().database_schema or "public"
+        rows = db.execute(
+            text(
+                "SELECT c.relname, c.relrowsecurity, c.relforcerowsecurity, "
+                "(SELECT count(*) FROM pg_policy p WHERE p.polrelid = c.oid) "
+                "FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace "
+                "WHERE c.relname = ANY(:names) AND n.nspname = :schema"
+            ),
+            {"names": list(_RLS_TABLES + _RLS_OPTIONAL_TABLES), "schema": schema},
+        ).fetchall()
+    except Exception as exc:
+        return _set(UNVERIFIED, f"could not read RLS state: {exc.__class__.__name__}")
+
+    if not rows:
+        return _set(UNVERIFIED, "no tenant tables found to check RLS on")
+
+    # A table that is absent is not a table that is safe. The junction tables
+    # are created by the ORM rather than by a migration, so on a fresh database
+    # they appeared after the RLS migration had run -- and a check that only
+    # inspects the rows it happens to find reports every remaining table forced
+    # and calls that a pass.
+    missing = sorted(set(_RLS_TABLES) - {r[0] for r in rows})
+    if missing:
+        return _set(
+            MISMATCH,
+            "expected tenant tables are absent, so nothing protects them: "
+            + ", ".join(missing),
+        )
+
+    unprotected = [
+        r[0] for r in rows if not (r[1] and r[2] and r[3] > 0)
+    ]
+    if unprotected:
+        return _set(
+            MISMATCH,
+            "row level security is not in force on: "
+            + ", ".join(sorted(unprotected))
+            + " - tenant isolation would rest on query convention alone",
+        )
+    return _set(OK, f"row level security forced on {len(rows)} tables")
+
+
+def reset_for_tests(new_state: Optional[str] = None) -> None:
+    """Test hook: force the recorded verdict, bypassing the sticky rule."""
+    global _state, _detail
+    _state = new_state or OK
+    _detail = "set by test"