auth 3.1.1__tar.gz → 3.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth
-Version: 3.1.1
+Version: 3.3.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
@@ -31,12 +30,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.3.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.3.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.3.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.3.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.3.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.3.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.3.0}/auth/database.py

@@ -15,6 +15,13 @@ 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,
+    _ensure_audit_partition_runway,
+    _grandfather_strict_users,
+    _reconcile_text_columns,
+)
 
 
 def _forced_sslmode(database_url: str) -> Optional[str]:
@@ -92,8 +99,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 +117,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 +140,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 +346,12 @@ 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)
+        _ensure_audit_partition_runway(engine)
         _reconcile_text_columns(engine)
         _grandfather_strict_users(engine)
         logger.info("Tables created successfully.")
@@ -334,148 +361,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()