runlight 0.1.0__py3-none-any.whl

runlight/__init__.py

@@ -0,0 +1,55 @@
+"""Runlight: privacy friendly web analytics that lives inside your Python app.
+
+    from runlight import Runlight
+    from runlight.store import Stores
+
+    rl = Runlight(store=Stores.sqlite("./data/runlight.db"), site={"name": "example.com", "hostnames": ["example.com"]})
+    routes = rl.routes()          # routes.handle(request) answers /runlight/*
+    # or mount it: runlight.wsgi, runlight.asgi, runlight.django, runlight.flask, runlight.fastapi
+
+Then add <script defer src="/runlight/s.js"></script> to your pages.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .http import Headers, Request, Response, Url
+
+__all__ = [
+    "API_VERSION",
+    "LINK_DOMAIN_CHECK",
+    "SESSION_IDLE_MS",
+    "VERSION",
+    "Headers",
+    "Request",
+    "Response",
+    "Runlight",
+    "SettingsError",
+    "Stores",
+    "Url",
+    "runlight",
+]
+
+
+def runlight(options: Any = None, **kwargs: Any) -> Any:
+    """A Runlight, as runlight() in the TypeScript SDK makes one."""
+    from .core import Runlight
+
+    return Runlight(options, **kwargs)
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("Runlight", "SettingsError", "SESSION_IDLE_MS", "LINK_DOMAIN_CHECK"):
+        from . import core
+
+        return getattr(core, name)
+    if name == "Stores":
+        from .store import Stores
+
+        return Stores
+    if name in ("VERSION", "API_VERSION"):
+        from . import version
+
+        return getattr(version, name)
+    raise AttributeError(name)

runlight/_aesgcm.py

@@ -0,0 +1,202 @@
+"""AES-GCM, as Web Crypto's AES-GCM seals and opens: the ciphertext with its 16 byte tag at the end.
+
+The standard library has no AES, so this uses the `cryptography` package's AESGCM when it is installed, and
+otherwise a plain Python AES and GHASH. Runlight seals short things (two-factor secrets, a mail service's keys,
+an assistant's key), so the plain one is quick enough, and both give the same bytes.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - depends on what is installed
+    from cryptography.exceptions import InvalidTag as _InvalidTag
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM as _AESGCM
+except ImportError:  # pragma: no cover
+    _AESGCM = None
+    _InvalidTag = None
+
+
+class InvalidTag(ValueError):
+    """The ciphertext, IV, or key is not the one sealed: Web Crypto rejects with an OperationError then."""
+
+
+def encrypt(key: bytes, iv: bytes, data: bytes, aad: bytes = b"") -> bytes:
+    """The ciphertext followed by its 16 byte tag."""
+    _check(key, iv)
+    if _AESGCM is not None:
+        return _AESGCM(key).encrypt(iv, data, aad or None)
+    return _Gcm(key).seal(iv, data, aad)
+
+
+def decrypt(key: bytes, iv: bytes, data: bytes, aad: bytes = b"") -> bytes:
+    """The plaintext. Raises InvalidTag when the tag does not check out."""
+    _check(key, iv)
+    if len(data) < 16:
+        raise InvalidTag("The data is shorter than its tag")
+    if _AESGCM is not None:
+        try:
+            return _AESGCM(key).decrypt(iv, data, aad or None)
+        except _InvalidTag:  # type: ignore[misc]
+            raise InvalidTag("The tag does not match") from None
+    return _Gcm(key).open(iv, data, aad)
+
+
+def _check(key: bytes, iv: bytes) -> None:
+    if len(key) not in (16, 24, 32):
+        raise ValueError("An AES key is 16, 24, or 32 bytes")
+    # Node's Web Crypto refuses an IV under 12 bytes.
+    if len(iv) < 12:
+        raise ValueError("An AES-GCM IV is at least 12 bytes")
+
+
+# AES (FIPS 197), with the round function in four tables of 32-bit words.
+
+_SBOX: list[int] = []
+_T0: list[int] = []
+_T1: list[int] = []
+_T2: list[int] = []
+_T3: list[int] = []
+
+
+def _tables() -> None:
+    def xtime(a: int) -> int:
+        a <<= 1
+        return a ^ 0x11B if a & 0x100 else a
+
+    # Powers and logs of 3 in GF(2^8), for the inverses.
+    exp = [0] * 256
+    log = [0] * 256
+    x = 1
+    for i in range(255):
+        exp[i] = x
+        log[x] = i
+        x ^= xtime(x)
+    for a in range(256):
+        inv = 0 if a == 0 else exp[(255 - log[a]) % 255]
+        s = inv
+        for shift in range(1, 5):
+            s ^= ((inv << shift) | (inv >> (8 - shift))) & 0xFF
+        _SBOX.append(s ^ 0x63)
+    for s in _SBOX:
+        s2 = xtime(s)
+        s3 = s2 ^ s
+        word = (s2 << 24) | (s << 16) | (s << 8) | s3
+        _T0.append(word)
+        _T1.append(((word >> 8) | (word << 24)) & 0xFFFFFFFF)
+        _T2.append(((word >> 16) | (word << 16)) & 0xFFFFFFFF)
+        _T3.append(((word >> 24) | (word << 8)) & 0xFFFFFFFF)
+
+
+_tables()
+
+
+def _expand(key: bytes) -> list[int]:
+    nk = len(key) // 4
+    rounds = nk + 6
+    words = [int.from_bytes(key[i * 4 : i * 4 + 4], "big") for i in range(nk)]
+    rcon = 1
+    sbox = _SBOX
+    for i in range(nk, 4 * (rounds + 1)):
+        t = words[i - 1]
+        if i % nk == 0:
+            t = ((t << 8) | (t >> 24)) & 0xFFFFFFFF
+            t = (sbox[t >> 24] << 24) | (sbox[(t >> 16) & 255] << 16) | (sbox[(t >> 8) & 255] << 8) | sbox[t & 255]
+            t ^= rcon << 24
+            rcon <<= 1
+            if rcon & 0x100:
+                rcon ^= 0x11B
+        elif nk > 6 and i % nk == 4:
+            t = (sbox[t >> 24] << 24) | (sbox[(t >> 16) & 255] << 16) | (sbox[(t >> 8) & 255] << 8) | sbox[t & 255]
+        words.append(words[i - nk] ^ t)
+    return words
+
+
+def _encrypt_block(w: list[int], block: int) -> int:
+    """One 128-bit block, as an integer, through AES with the expanded key `w`."""
+    t0, t1, t2, t3, sbox = _T0, _T1, _T2, _T3, _SBOX
+    a = (block >> 96) ^ w[0]
+    b = ((block >> 64) & 0xFFFFFFFF) ^ w[1]
+    c = ((block >> 32) & 0xFFFFFFFF) ^ w[2]
+    d = (block & 0xFFFFFFFF) ^ w[3]
+    rounds = len(w) // 4 - 1
+    k = 4
+    for _ in range(rounds - 1):
+        a, b, c, d = (
+            t0[a >> 24] ^ t1[(b >> 16) & 255] ^ t2[(c >> 8) & 255] ^ t3[d & 255] ^ w[k],
+            t0[b >> 24] ^ t1[(c >> 16) & 255] ^ t2[(d >> 8) & 255] ^ t3[a & 255] ^ w[k + 1],
+            t0[c >> 24] ^ t1[(d >> 16) & 255] ^ t2[(a >> 8) & 255] ^ t3[b & 255] ^ w[k + 2],
+            t0[d >> 24] ^ t1[(a >> 16) & 255] ^ t2[(b >> 8) & 255] ^ t3[c & 255] ^ w[k + 3],
+        )
+        k += 4
+
+    def last(p: int, q: int, r: int, s: int, key: int) -> int:
+        return ((sbox[p >> 24] << 24) | (sbox[(q >> 16) & 255] << 16) | (sbox[(r >> 8) & 255] << 8) | sbox[s & 255]) ^ key
+
+    return (last(a, b, c, d, w[k]) << 96) | (last(b, c, d, a, w[k + 1]) << 64) | (last(c, d, a, b, w[k + 2]) << 32) | last(d, a, b, c, w[k + 3])
+
+
+# GCM (NIST SP 800-38D).
+
+_R = 0xE1 << 120
+_MASK = (1 << 128) - 1
+
+
+class _Gcm:
+    def __init__(self, key: bytes) -> None:
+        self.w = _expand(key)
+        h = _encrypt_block(self.w, 0)
+        # H times x^i for i in 0..127, so a product is the XOR of the rows its bits pick.
+        rows = []
+        v = h
+        for _ in range(128):
+            rows.append(v)
+            v = (v >> 1) ^ _R if v & 1 else v >> 1
+        self.rows = rows
+
+    def _mul(self, x: int) -> int:
+        out = 0
+        rows = self.rows
+        for i in range(128):
+            if x >> (127 - i) & 1:
+                out ^= rows[i]
+        return out
+
+    def _ghash(self, aad: bytes, data: bytes) -> int:
+        y = 0
+        for part in (aad, data):
+            for at in range(0, len(part), 16):
+                y = self._mul(y ^ int.from_bytes(part[at : at + 16].ljust(16, b"\0"), "big"))
+        return self._mul(y ^ ((len(aad) * 8) << 64) ^ (len(data) * 8))
+
+    def _j0(self, iv: bytes) -> int:
+        if len(iv) == 12:
+            return (int.from_bytes(iv, "big") << 32) | 1
+        return self._ghash(b"", iv)
+
+    def _ctr(self, j0: int, data: bytes) -> bytes:
+        out = bytearray()
+        counter = j0
+        for at in range(0, len(data), 16):
+            counter = (counter & ~0xFFFFFFFF) | ((counter + 1) & 0xFFFFFFFF)
+            stream = _encrypt_block(self.w, counter).to_bytes(16, "big")
+            chunk = data[at : at + 16]
+            out += (int.from_bytes(chunk, "big") ^ int.from_bytes(stream[: len(chunk)], "big")).to_bytes(len(chunk), "big")
+        return bytes(out)
+
+    def _tag(self, j0: int, aad: bytes, ciphertext: bytes) -> bytes:
+        return ((_encrypt_block(self.w, j0) ^ self._ghash(aad, ciphertext)) & _MASK).to_bytes(16, "big")
+
+    def seal(self, iv: bytes, data: bytes, aad: bytes) -> bytes:
+        j0 = self._j0(iv)
+        ciphertext = self._ctr(j0, data)
+        return ciphertext + self._tag(j0, aad, ciphertext)
+
+    def open(self, iv: bytes, data: bytes, aad: bytes) -> bytes:
+        ciphertext, tag = data[:-16], data[-16:]
+        j0 = self._j0(iv)
+        expected = self._tag(j0, aad, ciphertext)
+        diff = 0
+        for x, y in zip(expected, tag):
+            diff |= x ^ y
+        if diff:
+            raise InvalidTag("The tag does not match")
+        return self._ctr(j0, ciphertext)

runlight/_intl.py

@@ -0,0 +1,202 @@
+"""The pieces of JavaScript's Intl the email reports use, for the dashboard's languages (en, de, es, fr, and
+pt): Intl.NumberFormat for counts, percents, one decimal place, and money, Intl.DateTimeFormat for a month and
+year or a short day, and Intl.DisplayNames for a region's name. Python has no ICU, so region names, currency
+symbols, and currency fraction digits come from data/intl.json, which scripts/python-intl.mts writes from
+Node's own ICU.
+
+Numbers round as ICU does, half away from zero on the number's shortest decimal form, so 2.05 to one
+place is 2.1, though the double just under it is what is stored.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from functools import cache
+from pathlib import Path
+from typing import Any
+
+from . import _js
+
+_GROUP = {"en": ",", "de": ".", "es": ".", "fr": " ", "pt": "."}
+_DECIMAL = {"en": ".", "de": ",", "es": ",", "fr": ",", "pt": ","}
+_PERCENT = {"en": "{}%", "de": "{} %", "es": "{} %", "fr": "{} %", "pt": "{}%"}
+
+_MONTHS = {
+    "en": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October",
+           "November", "December"],
+    "de": ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November",
+           "Dezember"],
+    "es": ["enero", "febrero", "marzo", "abril", "mayo", "junio", "julio", "agosto", "septiembre", "octubre",
+           "noviembre", "diciembre"],
+    "fr": ["janvier", "février", "mars", "avril", "mai", "juin", "juillet", "août", "septembre", "octobre",
+           "novembre", "décembre"],
+    "pt": ["janeiro", "fevereiro", "março", "abril", "maio", "junho", "julho", "agosto", "setembro", "outubro",
+           "novembro", "dezembro"],
+}  # fmt: skip
+_SHORT_MONTHS = {
+    "en": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+    "de": ["Jan.", "Feb.", "März", "Apr.", "Mai", "Juni", "Juli", "Aug.", "Sept.", "Okt.", "Nov.", "Dez."],
+    "es": ["ene", "feb", "mar", "abr", "may", "jun", "jul", "ago", "sept", "oct", "nov", "dic"],
+    "fr": ["janv.", "févr.", "mars", "avr.", "mai", "juin", "juil.", "août", "sept.", "oct.", "nov.", "déc."],
+    "pt": ["jan.", "fev.", "mar.", "abr.", "mai.", "jun.", "jul.", "ago.", "set.", "out.", "nov.", "dez."],
+}
+# { month: "long", year: "numeric" }, then { month: "short", day: "numeric" } without and with the year.
+_DATE_PATTERNS = {
+    "en": ["{M} {y}", "{m} {d}", "{m} {d}, {y}"],
+    "de": ["{M} {y}", "{d}. {m}", "{d}. {m} {y}"],
+    "es": ["{M} de {y}", "{d} {m}", "{d} {m} {y}"],
+    "fr": ["{M} {y}", "{d} {m}", "{d} {m} {y}"],
+    "pt": ["{M} de {y}", "{d} de {m}", "{d} de {m} de {y}"],
+}
+
+_THREES = re.compile(r"\B(?=(\d{3})+\Z)", re.ASCII)
+
+
+@cache
+def _data() -> dict[str, Any]:
+    return json.loads((Path(__file__).parent / "data" / "intl.json").read_text("utf-8"))
+
+
+def _lang(lang: str) -> str:
+    return lang if lang in _GROUP else "en"
+
+
+def number(lang: str, n: int | float, min_fraction: int = 0, max_fraction: int = 3) -> str:
+    """new Intl.NumberFormat(lang, { minimumFractionDigits, maximumFractionDigits }).format(n); the defaults are 0
+    and 3."""
+    lang = _lang(lang)
+    if isinstance(n, float) and math.isnan(n):
+        return "NaN"
+    if isinstance(n, float) and math.isinf(n):
+        return ("-" if n < 0 else "") + "∞"
+    negative, whole, fraction = _rounded(n, min_fraction, max_fraction)
+    # Spanish groups only from five digits on (CLDR's minimum grouping digits of 2).
+    if not (lang == "es" and len(whole) < 5):
+        whole = _THREES.sub(_GROUP[lang], whole)
+    return ("-" if negative else "") + whole + (_DECIMAL[lang] + fraction if fraction else "")
+
+
+def percent(lang: str, n: int | float) -> str:
+    """new Intl.NumberFormat(lang, { style: "percent", maximumFractionDigits: 0 }).format(n)."""
+    lang = _lang(lang)
+    if isinstance(n, float) and not math.isfinite(n):
+        return _PERCENT[lang].format(number(lang, n))
+    return _PERCENT[lang].format(number(lang, _times100(n), 0, 0))
+
+
+_CODE = re.compile(r"[A-Za-z]{3}\Z")
+
+
+def currency(lang: str, n: int | float, code: str, max_fraction: int) -> str:
+    """new Intl.NumberFormat(lang, { style: "currency", currency, maximumFractionDigits }).format(n), or
+    `${n} ${currency}` where Intl throws (a currency code that is not three letters)."""
+    lang = _lang(lang)
+    if not _CODE.match(code):
+        return f"{_js.string(n)} {code}"
+    code = code.upper()
+    data = _data()
+    own = data["currencies"][lang].get(code)
+    if own is None:
+        before, after = (part.replace("{c}", code) for part in data["unknown"][lang])
+    else:
+        before, after = own
+    min_fraction = min(data["digits"].get(code, 2), max_fraction)
+    amount = number(lang, abs(n) if _js.is_finite(n) else n, min_fraction, max_fraction)
+    negative = n < 0 or (isinstance(n, float) and n == 0 and math.copysign(1, n) < 0)
+    if amount.startswith("-"):
+        amount = amount[1:]
+    return ("-" if negative else "") + before + amount + after
+
+
+def month_year(lang: str, date: str) -> str:
+    """A date, YYYY-MM-DD, as { month: "long", year: "numeric" } writes it."""
+    return _date(lang, date, 0)
+
+
+def short_day(lang: str, date: str, with_year: bool) -> str:
+    """A date as { month: "short", day: "numeric" } writes it, with `year: "numeric"` too when asked."""
+    return _date(lang, date, 2 if with_year else 1)
+
+
+def _date(lang: str, date: str, pattern: int) -> str:
+    lang = _lang(lang)
+    y, m, d = (int(part) for part in date.split("-"))
+    return (
+        _DATE_PATTERNS[lang][pattern]
+        .replace("{M}", _MONTHS[lang][m - 1])
+        .replace("{m}", _SHORT_MONTHS[lang][m - 1])
+        .replace("{d}", str(d))
+        .replace("{y}", str(y))
+    )
+
+
+_REGION = re.compile(r"([A-Z]{2}|[0-9]{3})\Z")
+
+
+def region(lang: str, code: str) -> str:
+    """new Intl.DisplayNames(lang, { type: "region" }).of(code), or the code where that throws. Only an upper case
+    code is looked up; Intl gives any other back as it came."""
+    if not _REGION.match(code):
+        return code
+    return _data()["regions"][_lang(lang)].get(code, code)
+
+
+def _times100(n: int | float) -> int | float:
+    """n * 100, worked out on the decimal digits, as ICU scales a percent, so 0.135 is 13.5 and not
+    13.500000000000002."""
+    if isinstance(n, int):
+        return n * 100
+    negative, digits, point = _decimal(n)
+    return float(("-" if negative else "") + _plain(digits, point + 2))
+
+
+def _rounded(n: int | float, min: int, max: int) -> tuple[bool, str, str]:
+    """The number's sign, whole digits, and fraction digits, rounded half away from zero to at most `max` places
+    and padded to at least `min`."""
+    if isinstance(n, int):
+        return n < 0, str(abs(n)), "0" * min
+    negative, digits, point = _decimal(n)
+    # Digits as a whole number of units of 10^-max.
+    keep = point + max
+    if keep < 0:
+        units = "0"
+    elif len(digits) > keep:
+        units = "0" if keep == 0 else digits[:keep]
+        if int(digits[keep]) >= 5:
+            units = str(int(units) + 1)
+    else:
+        units = digits.ljust(keep, "0")
+    units = units.rjust(max + 1, "0")
+    whole = units[: len(units) - max].lstrip("0")
+    fraction = (units[-max:] if max > 0 else "").rstrip("0")
+    fraction = fraction.ljust(min, "0")
+    return negative, whole or "0", fraction
+
+
+def _decimal(n: float) -> tuple[bool, str, int]:
+    """The shortest decimal form of a double: its sign, its significant digits, and where the point goes (the
+    number of digits before it, which may be zero or negative)."""
+    negative = n < 0 or (n == 0 and math.copysign(1, n) < 0)
+    text = repr(abs(n))
+    exponent = 0
+    if "e" in text:
+        text, power = text.split("e")
+        exponent = int(power)
+    whole, _, fraction = text.partition(".")
+    digits = whole + fraction
+    point = len(whole) + exponent
+    trimmed = digits.lstrip("0")
+    point -= len(digits) - len(trimmed)
+    trimmed = trimmed.rstrip("0")
+    return negative, trimmed or "0", point if trimmed else 1
+
+
+def _plain(digits: str, point: int) -> str:
+    """Digits with the point after `point` of them, written out in full."""
+    if point <= 0:
+        return "0." + "0" * -point + digits
+    if point >= len(digits):
+        return digits + "0" * (point - len(digits))
+    return digits[:point] + "." + digits[point:]