keepup-admin 0.1.0__py3-none-any.whl

keepup/auth/login_throttle.py

@@ -0,0 +1,151 @@
+"""Counting failed logins, so a password cannot be guessed at full speed.
+
+The counter lives in the database rather than in the process. The application is
+meant to run as several replicas against one database, and a counter held in
+memory is one the next attempt walks around simply by landing on another replica.
+
+Attempts are counted per username, not per address. An address behind a shared
+uplink belongs to many people, and locking it out shuts the door on everyone who
+happens to share it. The trade is that somebody can keep a known name locked for
+the length of the window; that window is short, and the alternative is worse.
+"""
+
+import logging
+import os
+from datetime import datetime, timedelta
+from typing import Optional
+
+from sqlalchemy import Column, DateTime, Integer, String, Text
+
+from keepup import tables
+from keepup.db import DatabaseManagerV2
+
+logger = logging.getLogger(__name__)
+
+#: How many failures in a row close the door, and for how long.
+MAX_ATTEMPTS_ENV = "LOGIN_MAX_ATTEMPTS"
+LOCKOUT_MINUTES_ENV = "LOGIN_LOCKOUT_MINUTES"
+DEFAULT_MAX_ATTEMPTS = 10
+DEFAULT_LOCKOUT_MINUTES = 15
+
+
+def max_attempts(environ=None) -> int:
+    """Failures tolerated before the lockout window starts."""
+    environ = environ if environ is not None else os.environ
+    try:
+        value = int(environ.get(MAX_ATTEMPTS_ENV, DEFAULT_MAX_ATTEMPTS))
+    except (TypeError, ValueError):
+        return DEFAULT_MAX_ATTEMPTS
+    return value if value > 0 else DEFAULT_MAX_ATTEMPTS
+
+
+def lockout_window(environ=None) -> timedelta:
+    """How long the door stays closed once the attempts are spent."""
+    environ = environ if environ is not None else os.environ
+    try:
+        minutes = int(environ.get(LOCKOUT_MINUTES_ENV, DEFAULT_LOCKOUT_MINUTES))
+    except (TypeError, ValueError):
+        minutes = DEFAULT_LOCKOUT_MINUTES
+    return timedelta(minutes=minutes if minutes > 0 else DEFAULT_LOCKOUT_MINUTES)
+
+
+LOGIN_ATTEMPTS = tables.table(
+    "login_attempts",
+    Column("username", String(255).with_variant(Text(), "sqlite"), primary_key=True, nullable=True),
+    Column("failures", Integer, nullable=False, server_default=tables.sql_text("0")),
+    Column("last_failure_at", DateTime),
+)
+
+
+def init_login_attempts_table() -> None:
+    """Create the table this module keeps its count in.
+
+    There are no migrations: each start creates what is missing.
+    """
+    tables.ensure_tables(LOGIN_ATTEMPTS)
+
+
+def _row(username: str) -> Optional[dict]:
+    return DatabaseManagerV2.execute_one(
+        "SELECT username, failures, last_failure_at FROM login_attempts WHERE username = :username",
+        {"username": username}
+    )
+
+
+def _as_datetime(value) -> Optional[datetime]:
+    if value is None or isinstance(value, datetime):
+        return value
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return None
+
+
+def locked_until(username: str, now: Optional[datetime] = None) -> Optional[datetime]:
+    """When this name may try again, or None when it may try now."""
+    if not username:
+        return None
+
+    now = now or datetime.utcnow()
+    try:
+        row = _row(username)
+    except Exception as error:
+        # A throttle that cannot read its own table must not become the reason
+        # nobody can log in.
+        logger.warning(f"Could not read the login attempts of {username}: {error}")
+        return None
+
+    if not row or (row.get("failures") or 0) < max_attempts():
+        return None
+
+    last_failure = _as_datetime(row.get("last_failure_at"))
+    if last_failure is None:
+        return None
+
+    until = last_failure + lockout_window()
+    return until if until > now else None
+
+
+def record_failure(username: str, now: Optional[datetime] = None) -> None:
+    """Count one failed attempt against this name."""
+    if not username:
+        return
+
+    now = now or datetime.utcnow()
+    try:
+        row = _row(username)
+        if row is None:
+            DatabaseManagerV2.execute_commit(
+                "INSERT INTO login_attempts (username, failures, last_failure_at) "
+                "VALUES (:username, 1, :now)",
+                {"username": username, "now": now}
+            )
+            return
+
+        # A name whose window has already passed starts its count again, so old
+        # failures do not add up to a lockout weeks later.
+        failures = (row.get("failures") or 0)
+        last_failure = _as_datetime(row.get("last_failure_at"))
+        if last_failure is not None and last_failure + lockout_window() <= now:
+            failures = 0
+
+        DatabaseManagerV2.execute_commit(
+            "UPDATE login_attempts SET failures = :failures, last_failure_at = :now "
+            "WHERE username = :username",
+            {"failures": failures + 1, "now": now, "username": username}
+        )
+    except Exception as error:
+        logger.warning(f"Could not record a failed login of {username}: {error}")
+
+
+def record_success(username: str) -> None:
+    """Forget the failures of a name that has just got in."""
+    if not username:
+        return
+    try:
+        DatabaseManagerV2.execute_commit(
+            "DELETE FROM login_attempts WHERE username = :username",
+            {"username": username}
+        )
+    except Exception as error:
+        logger.warning(f"Could not clear the login attempts of {username}: {error}")

keepup/auth/oidc.py

@@ -0,0 +1,245 @@
+"""Signing in through an external identity provider, over OpenID Connect.
+
+The person proves who they are to their provider, and this application never
+sees their password. What comes back is a code, which is exchanged for an
+``id_token`` -- a signed statement by the provider about who just signed in.
+
+Two things are worth knowing before reading further.
+
+**Everything is checked before anybody is believed.** The order is: the state
+we issued, then the exchange, then the signature against the provider's keys,
+then issuer, audience, expiry and nonce. A failure at any point answers exactly
+like a failure at any other; the reason goes to the log. Different answers for
+different failures would tell whoever is probing which check they got past.
+
+**Nothing of the provider's is kept.** The access and refresh tokens are not
+stored: they are keys to somebody's account at the provider, and this
+application has no business holding them. The ``id_token`` is read once and
+dropped. What is kept is the pair (issuer, subject) -- who this is -- and that
+is the whole point of the exchange.
+"""
+
+import base64
+import hashlib
+import logging
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urlencode
+
+import httpx
+from jose import JWTError, jwt
+
+from keepup.auth.signing_key import resolve_signing_key
+
+logger = logging.getLogger(__name__)
+
+#: The cookie carrying the state of one sign-in attempt. SameSite=Lax rather
+#: than Strict on purpose: the return from the provider is a navigation from
+#: another site, and Strict would withhold the cookie exactly then -- that is,
+#: always.
+FLOW_COOKIE = "ss_oidc"
+FLOW_COOKIE_MAX_AGE = 600
+
+#: Symmetric algorithms and "none" are never accepted for an id_token: the
+#: provider signs with its private key, and anything else means the token was
+#: signed by whoever handed it to us.
+ALLOWED_ALGORITHMS = ("RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256")
+
+#: The one answer every refusal gives. See the module docstring.
+REFUSAL = "Sign-in failed"
+
+
+class SignInRefused(Exception):
+    """Raised for every failed check; the reason is for the log, not the caller."""
+
+
+@dataclass
+class ProviderMetadata:
+    """What the provider says about itself, from its discovery document."""
+
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    jwks_uri: str
+
+
+class ProviderDirectory:
+    """The provider's metadata and signing keys, kept for the process.
+
+    Held in memory rather than in the database: none of it is secret, losing it
+    costs one request, and a shared copy would need invalidating across
+    replicas -- which costs more than it saves. Keys are re-read when a token
+    arrives signed by a key id we do not know, because providers rotate keys
+    without telling anyone and sign-in must not stay broken until a restart.
+    """
+
+    def __init__(self, settings, client_factory=None):
+        self._settings = settings
+        self._client_factory = client_factory or self._default_client
+        self._metadata: Optional[ProviderMetadata] = None
+        self._keys: Dict[str, Dict[str, Any]] = {}
+
+    def _default_client(self):
+        return httpx.AsyncClient(timeout=self._settings.timeout_seconds)
+
+    async def _get_json(self, url: str) -> Dict[str, Any]:
+        async with self._client_factory() as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            return response.json()
+
+    async def metadata(self) -> ProviderMetadata:
+        """The discovery document, fetched once."""
+        if self._metadata is None:
+            url = self._settings.issuer.rstrip("/") + "/.well-known/openid-configuration"
+            document = await self._get_json(url)
+            self._metadata = ProviderMetadata(
+                issuer=document["issuer"],
+                authorization_endpoint=document["authorization_endpoint"],
+                token_endpoint=document["token_endpoint"],
+                jwks_uri=document["jwks_uri"],
+            )
+            logger.info(f"OIDC provider discovered: {self._metadata.issuer}")
+        return self._metadata
+
+    async def key_for(self, kid: Optional[str], refresh: bool = False) -> Dict[str, Any]:
+        """The signing key with this id, re-reading the key set if it is new."""
+        if refresh or not self._keys:
+            metadata = await self.metadata()
+            document = await self._get_json(metadata.jwks_uri)
+            self._keys = {key.get("kid"): key for key in document.get("keys", [])}
+            logger.debug(f"OIDC keys loaded: {sorted(k for k in self._keys if k)}")
+
+        if kid in self._keys:
+            return self._keys[kid]
+        if not refresh:
+            # A key we have not seen: the provider has rotated, not lied.
+            return await self.key_for(kid, refresh=True)
+        raise SignInRefused(f"the provider has no signing key {kid!r}")
+
+    def forget(self):
+        """Drop what is cached; for tests and for a changed configuration."""
+        self._metadata = None
+        self._keys = {}
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def make_pkce_pair() -> Tuple[str, str]:
+    """A verifier that stays here and the challenge that goes to the provider."""
+    verifier = _b64url(secrets.token_bytes(32))
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+def issue_flow_token(state: str, nonce: str, verifier: str, now: Optional[int] = None) -> str:
+    """Pack one sign-in attempt into a short-lived signed value.
+
+    In a cookie rather than a row: a table of unfinished sign-ins would need a
+    row per attempt and a sweep for the abandoned ones, to hold what a signed
+    value holds by itself. One-time use is enforced by clearing the cookie at
+    the return.
+    """
+    issued = now if now is not None else int(time.time())
+    return jwt.encode(
+        {"state": state, "nonce": nonce, "verifier": verifier,
+         "iat": issued, "exp": issued + FLOW_COOKIE_MAX_AGE},
+        resolve_signing_key(),
+        algorithm="HS256",
+    )
+
+
+def read_flow_token(token: Optional[str]) -> Dict[str, Any]:
+    """Unpack the attempt, refusing anything expired or not ours."""
+    if not token:
+        raise SignInRefused("no sign-in attempt cookie")
+    try:
+        return jwt.decode(token, resolve_signing_key(), algorithms=["HS256"])
+    except JWTError as error:
+        raise SignInRefused(f"sign-in attempt cookie rejected: {error}")
+
+
+def authorization_url(metadata: ProviderMetadata, settings, state: str, nonce: str,
+                      challenge: str) -> str:
+    """Where to send the browser to have the person identified."""
+    query = {
+        "response_type": "code",
+        "client_id": settings.client_id,
+        "redirect_uri": settings.redirect_uri,
+        "scope": " ".join(settings.scopes),
+        "state": state,
+        "nonce": nonce,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    return f"{metadata.authorization_endpoint}?{urlencode(query)}"
+
+
+async def exchange_code(directory: ProviderDirectory, settings, code: str,
+                        verifier: str) -> Dict[str, Any]:
+    """Trade the code for tokens, proving we started this attempt.
+
+    The verifier proves it: it never left this server, and only the party that
+    began the attempt can produce it.
+    """
+    metadata = await directory.metadata()
+    form = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": settings.redirect_uri,
+        "client_id": settings.client_id,
+        "client_secret": settings.client_secret,
+        "code_verifier": verifier,
+    }
+    async with directory._client_factory() as client:
+        response = await client.post(metadata.token_endpoint, data=form)
+    if response.status_code != 200:
+        raise SignInRefused(f"the provider refused the code: {response.status_code}")
+    tokens = response.json()
+    if "id_token" not in tokens:
+        raise SignInRefused("the provider returned no id_token")
+    return tokens
+
+
+async def verify_id_token(directory: ProviderDirectory, settings, id_token: str,
+                          nonce: str) -> Dict[str, Any]:
+    """Check the provider's statement, and refuse it on any doubt.
+
+    Checked here rather than trusted: an id_token is a bearer statement, and
+    the only thing making it worth anything is that the signature belongs to
+    the issuer we were configured with.
+    """
+    try:
+        header = jwt.get_unverified_header(id_token)
+    except JWTError as error:
+        raise SignInRefused(f"unreadable id_token: {error}")
+
+    algorithm = header.get("alg")
+    if algorithm not in ALLOWED_ALGORITHMS:
+        raise SignInRefused(f"id_token signed with {algorithm!r}")
+
+    key = await directory.key_for(header.get("kid"))
+    metadata = await directory.metadata()
+
+    try:
+        claims = jwt.decode(
+            id_token,
+            key,
+            algorithms=[algorithm],
+            audience=settings.client_id,
+            issuer=metadata.issuer,
+            options={"verify_at_hash": False},
+        )
+    except JWTError as error:
+        raise SignInRefused(f"id_token rejected: {error}")
+
+    if claims.get("nonce") != nonce:
+        raise SignInRefused("id_token carries another attempt's nonce")
+    if not claims.get("sub"):
+        raise SignInRefused("id_token names no subject")
+
+    return claims

keepup/auth/oidc_policy.py

@@ -0,0 +1,111 @@
+"""What to do with somebody the application has never seen before.
+
+The provider has just proved who this person is. It has not said anything
+about whether they may use this product -- that is not a question an identity
+provider can answer, and the framework cannot answer it either: for one
+application everyone at the provider is welcome, for another access is by
+invitation and the provider is only a way of proving a name.
+
+So the decision belongs to the application, and the framework's default is to
+refuse. The opposite default would turn switching a provider on into open
+registration for a product that never asked for it -- and it would do so
+quietly, which is the worst way for it to happen.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterable, Optional
+
+from keepup.roles import ROLE_CLIENT
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AccountDecision:
+    """Either "no", or the account to create."""
+
+    admit: bool
+    role: str = ROLE_CLIENT
+    status: str = "active"
+    #: Why, for the log. Never shown to whoever is signing in.
+    reason: str = ""
+
+    @classmethod
+    def refuse(cls, reason: str) -> "AccountDecision":
+        return cls(admit=False, reason=reason)
+
+    @classmethod
+    def create(cls, role: str = ROLE_CLIENT, status: str = "active",
+               reason: str = "") -> "AccountDecision":
+        return cls(admit=True, role=role, status=status, reason=reason)
+
+
+def refuse_unknown() -> Callable[[Dict[str, Any]], AccountDecision]:
+    """The default: prove who you are all you like, there is no account here."""
+
+    def decide(claims: Dict[str, Any]) -> AccountDecision:
+        return AccountDecision.refuse("the application admits nobody it does not already know")
+
+    return decide
+
+
+def create_account(role: str = ROLE_CLIENT,
+                   status: str = "active") -> Callable[[Dict[str, Any]], AccountDecision]:
+    """Anyone the provider vouches for gets an account.
+
+    Reasonable when the provider is the company's own directory and everybody
+    behind it is staff. Open registration when the provider is a public one --
+    which is the application's call to make, deliberately.
+    """
+
+    def decide(claims: Dict[str, Any]) -> AccountDecision:
+        return AccountDecision.create(role=role, status=status,
+                                      reason="the application admits everyone the provider vouches for")
+
+    return decide
+
+
+def create_if_email_domain(domains: Iterable[str], role: str = ROLE_CLIENT,
+                           status: str = "active") -> Callable[[Dict[str, Any]], AccountDecision]:
+    """An account for staff, nothing for everyone else at the same provider.
+
+    The email is compared only when the provider says it verified it: an
+    unverified address is a string the person typed, and several public
+    providers will hand it over unchecked.
+    """
+    allowed = {domain.lower().lstrip("@") for domain in domains}
+
+    def decide(claims: Dict[str, Any]) -> AccountDecision:
+        email = (claims.get("email") or "").lower()
+        if not email or "@" not in email:
+            return AccountDecision.refuse("no email in the provider's claims")
+        if claims.get("email_verified") is False:
+            return AccountDecision.refuse("the provider did not verify this email")
+        domain = email.rsplit("@", 1)[1]
+        if domain not in allowed:
+            return AccountDecision.refuse(f"email domain {domain!r} is not admitted")
+        return AccountDecision.create(role=role, status=status,
+                                      reason=f"email domain {domain!r} is admitted")
+
+    return decide
+
+
+def decide(policy: Optional[Callable], claims: Dict[str, Any]) -> AccountDecision:
+    """Ask the application, and refuse if it has not said anything.
+
+    A policy that raises is a refusal too: an application whose rule fell over
+    has not admitted anybody, and treating the failure as consent is how a door
+    opens by accident.
+    """
+    if policy is None:
+        return refuse_unknown()(claims)
+    try:
+        decision = policy(claims)
+    except Exception as error:
+        logger.error(f"The account policy raised; refusing: {error}")
+        return AccountDecision.refuse("the application's policy failed")
+    if not isinstance(decision, AccountDecision):
+        logger.error(f"The account policy returned {type(decision).__name__}, not a decision; refusing")
+        return AccountDecision.refuse("the application's policy answered nothing usable")
+    return decision