cli-login 0.1.0__py3-none-any.whl

cli_login/__init__.py

@@ -0,0 +1,4 @@
+"""One CLI login for every Anthus product. See docs/design.md."""
+
+__version__ = "0.1.0"
+PROTOCOL_VERSION = 1

cli_login/broker/handler.py

@@ -0,0 +1,310 @@
+"""The broker Lambda: hands one authorization code to the one CLI that asked for it, and never holds a token.
+
+Two kinds of event reach it:
+
+- **Function URL requests**: only ``POST /start`` and ``POST /poll``, called by the CLI directly. Each caller is
+  rate-limited, and a CLI that polls one transaction too fast is told ``slow_down``.
+- **Direct invocations** with IAM, from the product's own approval pages: ``describe``, ``bind``, ``complete``
+  and ``deny``. They are never reachable through the function URL, so knowing a transaction id is not enough to
+  attach a sign-in to it.
+
+See docs/protocol.md for every request and answer.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import ipaddress
+import json
+import os
+import re
+import secrets
+import time
+import unicodedata
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+from .. import PROTOCOL_VERSION
+from . import throttle
+from .transactions import APPROVED, BOUND, DENIED, PENDING
+
+PRIVATE_MARKER = "private-v1"  # direct invocations from the product's pages carry {"cli_login": PRIVATE_MARKER}
+LIFETIME_SECONDS = 600
+INTERVAL_SECONDS = 5
+SLOW_DOWN_SECONDS = 5
+MATCHING_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ"  # no vowels, so no words; no 0/O or 1/I to confuse
+CHALLENGE = re.compile(r"[A-Za-z0-9_-]{43}")
+HEX64 = re.compile(r"[0-9a-f]{64}")
+NONCE = re.compile(r"[A-Za-z0-9_-]{16,128}")
+TRANSACTION = re.compile(r"[A-Za-z0-9_-]{22}")
+
+
+def sha256_hex(value: str) -> str:
+    # surrogatepass: a lone surrogate in caller input hashes to something that never matches, rather than raising
+    return hashlib.sha256(value.encode("utf-8", "surrogatepass")).hexdigest()
+
+
+def _https_url(value: str, name: str) -> str:
+    parts = urlsplit(value or "")
+    if parts.scheme != "https" or not parts.hostname or parts.username or parts.password or parts.query or parts.fragment:
+        raise ValueError(f"{name} must be an https URL")
+    return value
+
+
+@dataclass(frozen=True)
+class BrokerConfig:
+    client_id: str
+    targets: tuple[str, ...]
+    approval_url: str
+    callback_uri: str
+
+    def __post_init__(self):
+        if not self.client_id:
+            raise ValueError("the broker serves exactly one client id")
+        if not self.targets or not all(isinstance(t, str) and t for t in self.targets):
+            raise ValueError("the broker needs the targets it may sign in to")
+        _https_url(self.approval_url, "approval_url")
+        _https_url(self.callback_uri, "callback_uri")
+
+    @classmethod
+    def from_environment(cls, environ=os.environ) -> BrokerConfig:
+        return cls(
+            client_id=environ.get("BROKER_CLIENT_ID", ""),
+            targets=tuple(json.loads(environ.get("BROKER_TARGETS") or "[]")),
+            approval_url=environ.get("BROKER_APPROVAL_URL", ""),
+            callback_uri=environ.get("BROKER_CALLBACK_URI", ""),
+        )
+
+
+def _text(value: Any) -> str:
+    """Display text from the requester: control characters removed, so a label cannot forge page structure."""
+    if not isinstance(value, str):
+        raise TypeError("requester fields are text")
+    return "".join(ch for ch in value if unicodedata.category(ch)[0] != "C").strip()
+
+
+def matching_code(randbelow=secrets.randbelow) -> str:
+    letters = "".join(MATCHING_ALPHABET[randbelow(len(MATCHING_ALPHABET))] for _ in range(8))
+    return letters[:4] + "-" + letters[4:]
+
+
+class Broker:
+    def __init__(self, store, config: BrokerConfig, *, clock=time.time, token=secrets.token_urlsafe, randbelow=secrets.randbelow):
+        self.store, self.config = store, config
+        self.clock, self.token, self.randbelow = clock, token, randbelow
+
+    def now(self) -> int:
+        return int(self.clock())
+
+    # --- function URL ----------------------------------------------------------------------------------------
+
+    def start(self, body: dict[str, Any], caller: str) -> tuple[int, dict[str, Any]]:
+        if not throttle.allowed(self.store, "start", caller, throttle.START, self.now()):
+            return 429, {"error": "too_many_requests", "retry_after": throttle.START.window_seconds}
+        try:
+            if body.get("protocol") != PROTOCOL_VERSION:
+                return 400, {"error": "unsupported_protocol", "protocol": PROTOCOL_VERSION}
+            if body.get("client_id") != self.config.client_id:
+                return 400, {"error": "invalid_client"}
+            if body.get("target") not in self.config.targets:
+                return 400, {"error": "invalid_target"}
+            if body.get("code_challenge_method") != "S256" or not CHALLENGE.fullmatch(str(body.get("code_challenge", ""))):
+                return 400, {"error": "invalid_request", "field": "code_challenge"}
+            if not HEX64.fullmatch(str(body.get("poll_secret_hash", ""))):
+                return 400, {"error": "invalid_request", "field": "poll_secret_hash"}
+            if not NONCE.fullmatch(str(body.get("nonce", ""))):
+                return 400, {"error": "invalid_request", "field": "nonce"}
+            requester = body.get("requester")
+            if not isinstance(requester, dict) or set(requester) - {"host", "version", "note"}:
+                return 400, {"error": "invalid_request", "field": "requester"}
+            label = {key: _text(value) for key, value in requester.items()}
+            if not label.get("host") or not label.get("version"):
+                return 400, {"error": "invalid_request", "field": "requester"}
+        except (ValueError, TypeError):
+            return 400, {"error": "invalid_request"}
+        now = self.now()
+        item = {
+            "id": self.token(16),
+            "state": PENDING,
+            "client_id": self.config.client_id,
+            "target": body["target"],
+            "code_challenge": body["code_challenge"],
+            "poll_hash": body["poll_secret_hash"],
+            "nonce": body["nonce"],
+            "requester": label,
+            "matching_code": matching_code(self.randbelow),
+            "created_at": now,
+            "expires_at": now + LIFETIME_SECONDS,
+            "interval": INTERVAL_SECONDS,
+        }
+        try:
+            created = self.store.create(item)
+        except Exception as error:
+            if _too_large(error):  # DynamoDB's own 400 KB item limit, not one of ours
+                return 400, {"error": "invalid_request", "field": "requester"}
+            raise
+        if not created:
+            return 503, {"error": "temporarily_unavailable"}
+        return 200, {
+            "protocol": PROTOCOL_VERSION,
+            "transaction": item["id"],
+            "matching_code": item["matching_code"],
+            "approval_url": f"{self.config.approval_url}?t={item['id']}",
+            "interval": INTERVAL_SECONDS,
+            "expires_at": item["expires_at"],
+        }
+
+    def poll(self, body: dict[str, Any], caller: str) -> tuple[int, dict[str, Any]]:
+        now = self.now()
+        if not throttle.allowed(self.store, "poll", caller, throttle.POLL, now):
+            return 429, {"error": "too_many_requests", "retry_after": throttle.POLL.window_seconds}
+        transaction, secret = body.get("transaction"), body.get("poll_secret")
+        if not isinstance(transaction, str) or not TRANSACTION.fullmatch(transaction) or not isinstance(secret, str):
+            return 400, {"error": "invalid_request"}
+        item = self.store.get(transaction)
+        # A wrong poll secret reads exactly like a transaction that does not exist.
+        if item is None or not hmac.compare_digest(item["poll_hash"], sha256_hex(secret)):
+            return 400, {"error": "expired_token", "protocol": PROTOCOL_VERSION}
+        if item["expires_at"] <= now:
+            return 400, {"error": "expired_token", "protocol": PROTOCOL_VERSION}
+        last = item.get("last_poll_at")
+        if last is not None and now - last < item["interval"]:
+            slower = item["interval"] + SLOW_DOWN_SECONDS
+            self.store.transition(transaction, [PENDING, BOUND, APPROVED, DENIED], {"interval": slower, "last_poll_at": now},
+                                  expect={"last_poll_at": last})
+            return 400, {"error": "slow_down", "interval": slower, "protocol": PROTOCOL_VERSION}
+        if item["state"] == APPROVED:
+            taken = self.store.take(transaction)
+            if taken is None:
+                return 400, {"error": "expired_token", "protocol": PROTOCOL_VERSION}
+            return 200, {"protocol": PROTOCOL_VERSION, "code": taken["code"], "redirect_uri": self.config.callback_uri}
+        if item["state"] == DENIED:
+            return 400, {"error": "access_denied", "protocol": PROTOCOL_VERSION}
+        self.store.transition(transaction, [PENDING, BOUND], {"last_poll_at": now}, expect={"last_poll_at": last})
+        return 400, {"error": "authorization_pending", "interval": item["interval"], "protocol": PROTOCOL_VERSION}
+
+    # --- direct invocation (IAM) ------------------------------------------------------------------------------
+
+    def _live(self, transaction: Any, states) -> dict[str, Any] | None:
+        if not isinstance(transaction, str) or not TRANSACTION.fullmatch(transaction):
+            return None
+        item = self.store.get(transaction)
+        if item is None or item["state"] not in states or item["expires_at"] <= self.now():
+            return None
+        return item
+
+    def describe(self, event: dict[str, Any]) -> dict[str, Any]:
+        item = self._live(event.get("transaction"), [PENDING])
+        if item is None:
+            return {"ok": False, "error": "unavailable"}
+        return {
+            "ok": True,
+            "protocol": PROTOCOL_VERSION,
+            "client_id": item["client_id"],
+            "target": item["target"],
+            "requester": item["requester"],
+            "matching_code": item["matching_code"],
+            "code_challenge": item["code_challenge"],
+            "nonce": item["nonce"],
+            "redirect_uri": self.config.callback_uri,
+            "expires_at": item["expires_at"],
+        }
+
+    def bind(self, event: dict[str, Any]) -> dict[str, Any]:
+        nonce_hash = event.get("nonce_hash")
+        if self._live(event.get("transaction"), [PENDING]) is None or not HEX64.fullmatch(str(nonce_hash or "")):
+            return {"ok": False, "error": "unavailable"}
+        bound = self.store.transition(event["transaction"], [PENDING], {"state": BOUND, "nonce_hash": nonce_hash})
+        return {"ok": True} if bound else {"ok": False, "error": "unavailable"}
+
+    def complete(self, event: dict[str, Any]) -> dict[str, Any]:
+        item = self._live(event.get("transaction"), [BOUND])
+        nonce, code = event.get("nonce"), event.get("code")
+        if item is None or not isinstance(nonce, str) or not isinstance(code, str) or not code:
+            return {"ok": False, "error": "unavailable"}
+        if not hmac.compare_digest(item["nonce_hash"], sha256_hex(nonce)):
+            return {"ok": False, "error": "unavailable"}
+        done = self.store.transition(item["id"], [BOUND], {"state": APPROVED, "code": code}, expect={"nonce_hash": item["nonce_hash"]})
+        return {"ok": True} if done else {"ok": False, "error": "unavailable"}
+
+    def deny(self, event: dict[str, Any]) -> dict[str, Any]:
+        if self._live(event.get("transaction"), [PENDING, BOUND]) is None:
+            return {"ok": False, "error": "unavailable"}
+        denied = self.store.transition(event["transaction"], [PENDING, BOUND], {"state": DENIED})
+        return {"ok": True} if denied else {"ok": False, "error": "unavailable"}
+
+    # --- dispatch ---------------------------------------------------------------------------------------------
+
+    def handle(self, event: dict[str, Any]) -> dict[str, Any]:
+        # Anything shaped like a function URL request is only ever routed to /start or /poll. A private operation
+        # needs an explicit marker and no request context at all, which a function URL request always has.
+        if "requestContext" in event:
+            http = (event.get("requestContext") or {}).get("http")
+            return self._http(event, http) if isinstance(http, dict) else _response(404, {"error": "not_found"})
+        if event.get("cli_login") != PRIVATE_MARKER:
+            return {"ok": False, "error": "unknown_operation"}
+        operation = {"describe": self.describe, "bind": self.bind, "complete": self.complete, "deny": self.deny}.get(
+            event.get("operation")
+        )
+        return operation(event) if operation else {"ok": False, "error": "unknown_operation"}
+
+    def _http(self, event: dict[str, Any], http: dict[str, Any]) -> dict[str, Any]:
+        route = {"/start": self.start, "/poll": self.poll}.get(event.get("rawPath"))
+        if http.get("method") != "POST" or route is None:
+            return _response(404, {"error": "not_found"})
+        try:
+            raw = event.get("body") or ""
+            if event.get("isBase64Encoded"):
+                raw = base64.b64decode(raw).decode()
+            body = json.loads(raw)
+        except (ValueError, UnicodeDecodeError, RecursionError):
+            return _response(400, {"error": "invalid_request"})
+        if not isinstance(body, dict):
+            return _response(400, {"error": "invalid_request"})
+        try:
+            status, answer = route(body, caller_bucket(str(http.get("sourceIp") or "unknown")))
+        except (ValueError, TypeError, KeyError, RecursionError, UnicodeError):
+            return _response(400, {"error": "invalid_request"})
+        return _response(status, answer)
+
+
+def _too_large(error: Exception) -> bool:
+    detail = (getattr(error, "response", None) or {}).get("Error") or {}
+    return detail.get("Code") == "ValidationException" and "size" in str(detail.get("Message", "")).lower()
+
+
+def caller_bucket(address: str) -> str:
+    """The rate-limit bucket for a caller: an IPv4 address, or an IPv6 /64, which one host can fill freely."""
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return address
+    if ip.version == 6:
+        if ip.ipv4_mapped is not None:
+            return str(ip.ipv4_mapped)
+        return str(ipaddress.ip_network(f"{ip}/64", strict=False))
+    return str(ip)
+
+
+def _response(status: int, body: dict[str, Any]) -> dict[str, Any]:
+    headers = {"content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff"}
+    if status == 429:
+        headers["retry-after"] = str(body.get("retry_after", 60))
+    return {"statusCode": status, "headers": headers, "body": json.dumps(body)}
+
+
+_broker: Broker | None = None
+
+
+def lambda_handler(event, context):  # pragma: no cover - wiring only; Broker is specified directly
+    global _broker
+    if _broker is None:
+        import boto3
+
+        from .transactions import DynamoTransactions
+
+        _broker = Broker(DynamoTransactions(boto3.client("dynamodb"), os.environ["BROKER_TABLE"]), BrokerConfig.from_environment())
+    return _broker.handle(event)

cli_login/broker/pages.py

@@ -0,0 +1,175 @@
+"""The approval and callback pages a product serves on its own domain, framework-neutral.
+
+A product mounts ``ApprovalPages.approve`` at ``/cli/approve`` (GET and POST) and ``ApprovalPages.callback`` at
+``/cli/callback`` (GET), turning each ``Page`` into its framework's response. ``invoke`` calls the product's broker
+Lambda directly with IAM and returns its answer; the pages never reach the broker's function URL.
+
+- ``/cli/approve`` shows who is asking, the matching code, the target and what the session can do. Approving
+  needs the person to confirm the code matches, a CSRF check, and binds the transaction to a nonce N kept in a
+  first-party cookie before sending the browser to the sign-in provider.
+- ``/cli/callback`` checks that the state's N matches the cookie, then hands the code to the broker.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import html
+import secrets
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from urllib.parse import urlencode, urlsplit
+
+from .handler import PRIVATE_MARKER
+
+# __Secure-: browsers accept these cookies only over HTTPS with the Secure attribute, so a plain-HTTP page or a
+# sibling subdomain over HTTP cannot plant one.
+CSRF_COOKIE = "__Secure-cli_login_csrf"
+NONCE_COOKIE = "__Secure-cli_login_nonce"
+COOKIE_SECONDS = 600
+
+
+@dataclass
+class Page:
+    status: int
+    body: str = ""
+    headers: list[tuple[str, str]] = field(default_factory=list)
+
+
+def _cookie(name: str, value: str, path: str, *, same_site: str, max_age: int = COOKIE_SECONDS) -> tuple[str, str]:
+    return "Set-Cookie", f"{name}={value}; Path={path}; Max-Age={max_age}; HttpOnly; Secure; SameSite={same_site}"
+
+
+def _cleared(name: str, path: str) -> tuple[str, str]:
+    return _cookie(name, "", path, same_site="Lax", max_age=0)
+
+
+def _headers(form_action: str = "'self'") -> list[tuple[str, str]]:
+    # form-action also governs where the approve POST's 303 may go, so it must allow the sign-in provider's origin.
+    return [
+        ("Content-Type", "text/html; charset=utf-8"),
+        ("Cache-Control", "no-store"),
+        ("Referrer-Policy", "no-referrer"),
+        ("X-Frame-Options", "DENY"),
+        ("X-Content-Type-Options", "nosniff"),
+        ("Content-Security-Policy", f"default-src 'none'; style-src 'unsafe-inline'; form-action {form_action}; frame-ancestors 'none'"),
+    ]
+
+
+BASE_HEADERS = _headers()
+
+
+def _document(title: str, body: str) -> str:
+    return (
+        "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">"
+        "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
+        f"<title>{html.escape(title)}</title>"
+        "<style>body{font-family:system-ui,sans-serif;max-width:32rem;margin:2rem auto;padding:0 1rem;line-height:1.5}"
+        ".code{font-size:2rem;font-weight:700;letter-spacing:.15em;font-family:ui-monospace,monospace}"
+        "dt{font-weight:600}dd{margin:0 0 .75rem;overflow-wrap:anywhere}.note{max-height:6rem;overflow:auto}button{font-size:1rem;padding:.5rem 1rem;margin-right:.5rem}</style>"
+        f"</head><body>{body}</body></html>"
+    )
+
+
+def _message(status: int, title: str, text: str, headers=()) -> Page:
+    return Page(status, _document(title, f"<h1>{html.escape(title)}</h1><p>{html.escape(text)}</p>"), [*BASE_HEADERS, *headers])
+
+
+def _gone() -> Page:
+    return _message(410, "This sign-in link is no longer valid", "It expired, was already used, or was denied. Start the sign-in again from the CLI.")
+
+
+class ApprovalPages:
+    def __init__(
+        self,
+        invoke: Callable[[dict], Mapping],
+        *,
+        authorize_endpoint: str,
+        product: str,
+        privileges: str,
+        scope: str = "openid email profile",
+        identity_provider: str | None = None,
+        token=secrets.token_urlsafe,
+    ):
+        self.invoke, self.authorize_endpoint, self.product = (lambda payload: invoke({**payload, "cli_login": PRIVATE_MARKER})), authorize_endpoint, product
+        parts = urlsplit(authorize_endpoint)
+        self.form_action = f"'self' {parts.scheme}://{parts.netloc}"
+        self.privileges, self.scope, self.identity_provider, self.token = privileges, scope, identity_provider, token
+
+    def approve(self, method: str, query: Mapping[str, str], form: Mapping[str, str], cookies: Mapping[str, str]) -> Page:
+        if method == "GET":
+            return self._show(query.get("t", ""))
+        if method != "POST":
+            return _message(405, "Not allowed", "Use the approval page.")
+        csrf = form.get("csrf", "")
+        if not csrf or not hmac.compare_digest(csrf, cookies.get(CSRF_COOKIE, "")):
+            return _message(403, "This page expired", "Open the approval link again.")
+        transaction = form.get("t", "")
+        if form.get("action") == "deny":
+            self.invoke({"operation": "deny", "transaction": transaction})
+            return _message(200, "Sign-in denied", "The waiting CLI will not be signed in.", [_cleared(CSRF_COOKIE, "/cli/approve")])
+        if form.get("action") != "approve" or form.get("confirm") != "yes":
+            return _message(400, "Confirm the code", "Check that the code matches the one the CLI showed, then approve.")
+        described = self.invoke({"operation": "describe", "transaction": transaction})
+        if not described.get("ok"):
+            return _gone()
+        nonce = self.token(32)
+        if not self.invoke({"operation": "bind", "transaction": transaction, "nonce_hash": hashlib.sha256(nonce.encode()).hexdigest()}).get("ok"):
+            return _gone()
+        query_string = {
+            "client_id": described["client_id"],
+            "response_type": "code",
+            "redirect_uri": described["redirect_uri"],
+            "scope": self.scope,
+            "state": f"{transaction}.{nonce}",
+            "nonce": described["nonce"],
+            "code_challenge": described["code_challenge"],
+            "code_challenge_method": "S256",
+        }
+        if self.identity_provider:
+            query_string["identity_provider"] = self.identity_provider
+        return Page(303, "", [
+            *_headers(self.form_action),
+            ("Location", f"{self.authorize_endpoint}?{urlencode(query_string)}"),
+            _cookie(NONCE_COOKIE, nonce, "/cli/callback", same_site="Lax"),
+            _cleared(CSRF_COOKIE, "/cli/approve"),
+        ])
+
+    def _show(self, transaction: str) -> Page:
+        described = self.invoke({"operation": "describe", "transaction": transaction})
+        if not described.get("ok"):
+            return _gone()
+        csrf = self.token(32)
+        requester = described.get("requester") or {}
+        e = html.escape
+        note = f"<dt>Note</dt><dd class=\"note\">{e(requester['note'])}</dd>" if requester.get("note") else ""
+        body = (
+            f"<h1>Approve a {e(self.product)} CLI sign-in?</h1>"
+            "<p><strong>The CLI will be signed in as you.</strong> Approve only if you started this sign-in, or an agent "
+            "you run asked you to, and the code below matches the one it showed you.</p>"
+            f"<p>Code</p><p class=\"code\">{e(described['matching_code'])}</p>"
+            f"<dl><dt>Requested by</dt><dd>{e(requester.get('host', ''))}, CLI {e(requester.get('version', ''))}</dd>{note}"
+            f"<dt>Signs in to</dt><dd>{e(described['target'])}</dd>"
+            f"<dt>It will be able to</dt><dd>{e(self.privileges)}</dd></dl>"
+            "<form method=\"post\" action=\"/cli/approve\">"
+            f"<input type=\"hidden\" name=\"t\" value=\"{e(transaction)}\"><input type=\"hidden\" name=\"csrf\" value=\"{e(csrf)}\">"
+            "<p><label><input type=\"checkbox\" name=\"confirm\" value=\"yes\" required> "
+            "This code matches the one the CLI showed</label></p>"
+            "<button name=\"action\" value=\"approve\">Approve</button>"
+            "<button name=\"action\" value=\"deny\" formnovalidate>Deny</button></form>"
+        )
+        return Page(200, _document(f"Approve a {self.product} CLI sign-in", body),
+                    [*_headers(self.form_action), _cookie(CSRF_COOKIE, csrf, "/cli/approve", same_site="Strict")])
+
+    def callback(self, query: Mapping[str, str], cookies: Mapping[str, str]) -> Page:
+        transaction, _, nonce = query.get("state", "").partition(".")
+        clear = [_cleared(NONCE_COOKIE, "/cli/callback")]
+        if not transaction or not nonce or not hmac.compare_digest(nonce, cookies.get(NONCE_COOKIE, "")):
+            return _message(400, "This sign-in could not be checked",
+                            "Finish the sign-in in the same browser you approved it in, or start again from the CLI.", clear)
+        if query.get("error") or not query.get("code"):
+            self.invoke({"operation": "deny", "transaction": transaction})
+            return _message(200, "Sign-in cancelled", "The waiting CLI will not be signed in.", clear)
+        if not self.invoke({"operation": "complete", "transaction": transaction, "nonce": nonce, "code": query["code"]}).get("ok"):
+            return _gone()
+        return _message(200, "Sign-in approved", "You can close this page. The waiting CLI is signing in now.", clear)

cli_login/broker/throttle.py

@@ -0,0 +1,25 @@
+"""Per-caller rate limits for the broker's public routes.
+
+The broker's ``/start`` and ``/poll`` take calls from anyone who can reach the function URL, so each caller (its
+source address) gets a fixed number of calls per window. A CLI that polls one transaction faster than its
+interval is told ``slow_down`` separately, by the poll itself.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Limit:
+    calls: int
+    window_seconds: int
+
+
+START = Limit(calls=10, window_seconds=60)
+POLL = Limit(calls=120, window_seconds=60)
+
+
+def allowed(store, route: str, caller: str, limit: Limit, now: int) -> bool:
+    """Count this call and say whether the caller is still within the route's limit."""
+    return store.count(f"{route}#{caller}", now, limit.window_seconds) <= limit.calls