otpguard 0.1.0__tar.gz

otpguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Tanzil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

otpguard-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: otpguard
+Version: 0.1.0
+Summary: Decide whether an OTP SMS should be sent: SMS pumping, bombing and enumeration checks for any provider
+Author-email: Muhammad Tanzil <mtanzil666@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mtanzil6/otpguard
+Project-URL: Issues, https://github.com/mtanzil6/otpguard/issues
+Keywords: otp,sms,sms pumping,fraud,rate limiting,security
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phonenumbers>=8.13
+Requires-Dist: PyYAML>=6
+Requires-Dist: tzdata; platform_system == "Windows"
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == "redis"
+Provides-Extra: sql
+Requires-Dist: SQLAlchemy>=2.0; extra == "sql"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: fakeredis[lua]>=2.20; extra == "dev"
+Requires-Dist: redis>=5; extra == "dev"
+Requires-Dist: SQLAlchemy>=2.0; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# otpguard
+
+Decide whether an OTP SMS should go out before you pay for it.
+
+`otpguard` sits between your app and your SMS provider. You call `check()` before
+sending a one-time password; it answers **allow**, **challenge** or **block**, with the
+reasons. It is aimed at SMS pumping (artificially inflated traffic), SMS bombing and
+account enumeration through the password-reset flow.
+
+It works with any SMS provider and any framework (there is an HTTP service for
+non-Python apps), and it does not rely on the client IP: most checks look at where the
+messages are going and at the shape of the traffic, which attackers can't rotate as
+cheaply as addresses.
+
+## Install
+
+```bash
+pip install git+https://github.com/mtanzil6/otpguard.git                    # core, in-memory store
+pip install "otpguard[redis,sql] @ git+https://github.com/mtanzil6/otpguard.git"  # shared state in Redis, audit trail in SQL
+pip install "otpguard[server] @ git+https://github.com/mtanzil6/otpguard.git"     # HTTP service
+```
+
+Not yet on PyPI — install straight from GitHub. Python 3.10+.
+
+## Use
+
+```python
+from otpguard import OtpRequest, Sentinel
+
+guard = Sentinel.from_config("policy.yaml",
+                             redis_url="redis://localhost:6379/0",
+                             sql_url="postgresql://otp@db/otp")
+
+d = guard.check(OtpRequest(phone="+966512345678", purpose="register",
+                           ip=client_ip, session_id=sid, session_age_ms=age))
+if d.allowed:
+    provider.send(phone, code)
+elif d.action == "challenge":
+    ...  # CAPTCHA, then check again with challenge_passed=True
+else:
+    ...  # generic error, wait d.retry_after seconds
+
+# later, when the user types the right code
+guard.report_verified(d.request_id)
+```
+
+`d.allowed` is always `True` in shadow mode, so you can run it in production and
+watch what it would have done before you let it block anything.
+
+Feedback makes it much better. `report_verified()` feeds the verification-ratio and
+resend checks; `report_event("order", ts)` (or logins, or whatever should follow an
+OTP) feeds the conversion check.
+
+For asyncio apps, `AsyncSentinel.from_config(...)` has the same methods as coroutines.
+
+### HTTP
+
+```bash
+otpguard serve --policy policy.yaml --redis redis://localhost:6379/0 --port 8080
+```
+
+```
+POST /v1/check     {"phone": "...", "purpose": "login", "ip": "..."}  -> {"action": "allow", "allowed": true, "request_id": "...", ...}
+POST /v1/sent      {"request_id": "...", "cost": 0.04}
+POST /v1/verified  {"request_id": "..."}
+POST /v1/event     {"kind": "order", "phone": "..."}
+GET  /health
+```
+
+Reasons are not returned to the client unless you start the server with
+`--show-reasons`; they go to the SQL audit log.
+
+## What it checks
+
+| | detector | looks at |
+|---|---|---|
+| D1 | purpose cap | codes per number per purpose, 1 h and 24 h (hard block) |
+| D2 | destination risk | country / number-range rules from the policy |
+| D3 | resend without verify | several codes to one number, none entered |
+| D4 | verification ratio | share of codes entered, per country and purpose |
+| D5 | country share | a country's share of traffic against its usual share for that hour of the week |
+| D6 | prefix burst | never-seen numbers piling up in one number range |
+| D7 | pacing | requests arriving at a steady, machine-like pace |
+| D8 | network concentration | requests per IP, /24 (/48), ASN; hosting networks |
+| D9 | IP rotation | far more never-seen IPs than usual in a country/purpose bucket |
+| D10 | client integrity | session token age and reuse, device attestation |
+| D11 | conversion mismatch | e.g. password resets rising while logins don't |
+| D12 | spend budget | spend per country and in total, per hour and per day (challenge, then block) |
+
+Each detector returns a score between 0 and 1. Scores are combined with a weighted
+noisy-OR (`risk = 1 - Π(1 - wᵢ·sᵢ)`); hard rules (caps, deny lists, exhausted budgets)
+set a floor. Thresholds, weights, caps, country rules and budgets all live in the
+policy file, see [`examples/policy.yaml`](examples/policy.yaml).
+
+D8–D10 only run when you pass an IP or session data. Nothing breaks without them.
+
+## Storage
+
+- **Redis** for live counters (1-minute and 1-hour buckets, HyperLogLog for distinct
+  IPs). Shared by all app servers. The hard rules (per-number caps, spend budgets) are
+  checked and taken in one Lua script, so concurrent requests on different servers
+  cannot pass a cap together; the other detectors read counters with plain MGETs.
+- **SQL** (anything SQLAlchemy supports) for the audit trail: one row per decision,
+  outcomes, policy versions and grouped alerts. `otpguard prune --sql URL --days 90`
+  deletes old rows (run it from cron).
+- **Memory** for tests, replay and single-process setups.
+
+Phone numbers are stored only as an HMAC under your secret (`OTPGUARD_SECRET`);
+only the country code and a short prefix are kept in clear. IPs are kept as their
+network.
+
+If Redis is unreachable, `fail_mode: open` keeps serving with per-process limits;
+`closed` blocks.
+
+## Replay your own logs
+
+Most teams already have an SMS log with a timestamp, a number and a message type.
+That is enough to see what a policy would have done:
+
+```bash
+otpguard replay sms_log.csv --mapping mapping.yaml --policy policy.yaml \
+    --incidents incidents.yaml --out report/
+```
+
+The log can be CSV or JSON Lines, optionally gzipped. The mapping file says which
+columns to read, the time zone of the timestamps, which message types are OTPs (and for
+which purpose), which are follow-up events for D11 (`events`) and which mark a real
+customer for the collateral figure (`customer_events`; keep these different from
+`events`, or D11 is graded on its own input). See
+[`examples/mapping-case-study.yaml`](examples/mapping-case-study.yaml) and
+[`examples/incidents-case-study.yaml`](examples/incidents-case-study.yaml). The report lists
+what would have been challenged or blocked, per day and per detector, how many likely
+customers (numbers that got an order or delivery message within a week) were caught,
+and, for windows you label in the incidents file, how quickly and how much was caught.
+
+## Simulate attacks
+
+```bash
+otpguard simulate baseline --days 28 --out base.csv
+otpguard simulate inject --base base.csv --scenario A2 --start 2026-01-26T10:00 --out mixed.csv
+otpguard replay mixed.csv --mapping examples/mapping-synthetic.yaml --policy examples/policy.yaml
+```
+
+To inject attacks into your own log instead of synthetic traffic:
+
+```bash
+otpguard simulate import sms_log.csv --mapping mapping.yaml --out base.csv   # also writes base.mapping.yaml
+otpguard simulate assign-ips --base base.csv --mix examples/asn-mix.yaml --out base_ip.csv   # optional, for A2/D8/D9
+otpguard simulate inject --base base_ip.csv --scenario A2 --start 2022-05-10T10:00 --volume 0.05 --out mixed.csv
+otpguard replay mixed.csv --mapping base.mapping.yaml --policy policy.yaml
+```
+
+`--volume` sets the attack rate as a fraction of the log's average OTP rate.
+
+Scenarios: A1 pumping to one country from a few IPs, A2 the same with a fresh IP per
+request, A3 sequential numbers from one prefix, A4 low and slow, A5 one reset to each of
+many existing customers, A6 resend loops, A7 A1 during a sale.
+`python benchmarks/run_scenarios.py` runs all of them; add `--seeds 10`, `--volumes 0.01
+0.05 0.1 0.2`, `--designs full limiter without-L1 without-L3 without-L4` (a conventional
+per-number + per-IP limiter and layer ablations) and `--base`/`--mapping` for your own
+imported log. `python benchmarks/latency.py --redis redis://localhost:6379/1` measures
+decision latency. Results from the current version are in
+[`benchmarks/results`](benchmarks/results/scenarios.md). They come from synthetic
+traffic, so treat them as a sanity check rather than a promise.
+
+## Limits
+
+- A decision makes several Redis round trips (one per counter family); only the hard
+  rules are atomic. Soft scores can be off by a request or two under heavy concurrency.
+- Baselines need a few days of traffic. Until then the caps, country rules and
+  budgets do most of the work.
+- An attacker who spreads traffic thinly over many countries, each below its usual
+  share, is mostly stopped by the budgets, not by detection.
+- Set `timezone` in the mapping and the policy to the zone your log is written in;
+  naive timestamps and campaign dates are read in that zone.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

otpguard-0.1.0/README.md

@@ -0,0 +1,186 @@
+# otpguard
+
+Decide whether an OTP SMS should go out before you pay for it.
+
+`otpguard` sits between your app and your SMS provider. You call `check()` before
+sending a one-time password; it answers **allow**, **challenge** or **block**, with the
+reasons. It is aimed at SMS pumping (artificially inflated traffic), SMS bombing and
+account enumeration through the password-reset flow.
+
+It works with any SMS provider and any framework (there is an HTTP service for
+non-Python apps), and it does not rely on the client IP: most checks look at where the
+messages are going and at the shape of the traffic, which attackers can't rotate as
+cheaply as addresses.
+
+## Install
+
+```bash
+pip install git+https://github.com/mtanzil6/otpguard.git                    # core, in-memory store
+pip install "otpguard[redis,sql] @ git+https://github.com/mtanzil6/otpguard.git"  # shared state in Redis, audit trail in SQL
+pip install "otpguard[server] @ git+https://github.com/mtanzil6/otpguard.git"     # HTTP service
+```
+
+Not yet on PyPI — install straight from GitHub. Python 3.10+.
+
+## Use
+
+```python
+from otpguard import OtpRequest, Sentinel
+
+guard = Sentinel.from_config("policy.yaml",
+                             redis_url="redis://localhost:6379/0",
+                             sql_url="postgresql://otp@db/otp")
+
+d = guard.check(OtpRequest(phone="+966512345678", purpose="register",
+                           ip=client_ip, session_id=sid, session_age_ms=age))
+if d.allowed:
+    provider.send(phone, code)
+elif d.action == "challenge":
+    ...  # CAPTCHA, then check again with challenge_passed=True
+else:
+    ...  # generic error, wait d.retry_after seconds
+
+# later, when the user types the right code
+guard.report_verified(d.request_id)
+```
+
+`d.allowed` is always `True` in shadow mode, so you can run it in production and
+watch what it would have done before you let it block anything.
+
+Feedback makes it much better. `report_verified()` feeds the verification-ratio and
+resend checks; `report_event("order", ts)` (or logins, or whatever should follow an
+OTP) feeds the conversion check.
+
+For asyncio apps, `AsyncSentinel.from_config(...)` has the same methods as coroutines.
+
+### HTTP
+
+```bash
+otpguard serve --policy policy.yaml --redis redis://localhost:6379/0 --port 8080
+```
+
+```
+POST /v1/check     {"phone": "...", "purpose": "login", "ip": "..."}  -> {"action": "allow", "allowed": true, "request_id": "...", ...}
+POST /v1/sent      {"request_id": "...", "cost": 0.04}
+POST /v1/verified  {"request_id": "..."}
+POST /v1/event     {"kind": "order", "phone": "..."}
+GET  /health
+```
+
+Reasons are not returned to the client unless you start the server with
+`--show-reasons`; they go to the SQL audit log.
+
+## What it checks
+
+| | detector | looks at |
+|---|---|---|
+| D1 | purpose cap | codes per number per purpose, 1 h and 24 h (hard block) |
+| D2 | destination risk | country / number-range rules from the policy |
+| D3 | resend without verify | several codes to one number, none entered |
+| D4 | verification ratio | share of codes entered, per country and purpose |
+| D5 | country share | a country's share of traffic against its usual share for that hour of the week |
+| D6 | prefix burst | never-seen numbers piling up in one number range |
+| D7 | pacing | requests arriving at a steady, machine-like pace |
+| D8 | network concentration | requests per IP, /24 (/48), ASN; hosting networks |
+| D9 | IP rotation | far more never-seen IPs than usual in a country/purpose bucket |
+| D10 | client integrity | session token age and reuse, device attestation |
+| D11 | conversion mismatch | e.g. password resets rising while logins don't |
+| D12 | spend budget | spend per country and in total, per hour and per day (challenge, then block) |
+
+Each detector returns a score between 0 and 1. Scores are combined with a weighted
+noisy-OR (`risk = 1 - Π(1 - wᵢ·sᵢ)`); hard rules (caps, deny lists, exhausted budgets)
+set a floor. Thresholds, weights, caps, country rules and budgets all live in the
+policy file, see [`examples/policy.yaml`](examples/policy.yaml).
+
+D8–D10 only run when you pass an IP or session data. Nothing breaks without them.
+
+## Storage
+
+- **Redis** for live counters (1-minute and 1-hour buckets, HyperLogLog for distinct
+  IPs). Shared by all app servers. The hard rules (per-number caps, spend budgets) are
+  checked and taken in one Lua script, so concurrent requests on different servers
+  cannot pass a cap together; the other detectors read counters with plain MGETs.
+- **SQL** (anything SQLAlchemy supports) for the audit trail: one row per decision,
+  outcomes, policy versions and grouped alerts. `otpguard prune --sql URL --days 90`
+  deletes old rows (run it from cron).
+- **Memory** for tests, replay and single-process setups.
+
+Phone numbers are stored only as an HMAC under your secret (`OTPGUARD_SECRET`);
+only the country code and a short prefix are kept in clear. IPs are kept as their
+network.
+
+If Redis is unreachable, `fail_mode: open` keeps serving with per-process limits;
+`closed` blocks.
+
+## Replay your own logs
+
+Most teams already have an SMS log with a timestamp, a number and a message type.
+That is enough to see what a policy would have done:
+
+```bash
+otpguard replay sms_log.csv --mapping mapping.yaml --policy policy.yaml \
+    --incidents incidents.yaml --out report/
+```
+
+The log can be CSV or JSON Lines, optionally gzipped. The mapping file says which
+columns to read, the time zone of the timestamps, which message types are OTPs (and for
+which purpose), which are follow-up events for D11 (`events`) and which mark a real
+customer for the collateral figure (`customer_events`; keep these different from
+`events`, or D11 is graded on its own input). See
+[`examples/mapping-case-study.yaml`](examples/mapping-case-study.yaml) and
+[`examples/incidents-case-study.yaml`](examples/incidents-case-study.yaml). The report lists
+what would have been challenged or blocked, per day and per detector, how many likely
+customers (numbers that got an order or delivery message within a week) were caught,
+and, for windows you label in the incidents file, how quickly and how much was caught.
+
+## Simulate attacks
+
+```bash
+otpguard simulate baseline --days 28 --out base.csv
+otpguard simulate inject --base base.csv --scenario A2 --start 2026-01-26T10:00 --out mixed.csv
+otpguard replay mixed.csv --mapping examples/mapping-synthetic.yaml --policy examples/policy.yaml
+```
+
+To inject attacks into your own log instead of synthetic traffic:
+
+```bash
+otpguard simulate import sms_log.csv --mapping mapping.yaml --out base.csv   # also writes base.mapping.yaml
+otpguard simulate assign-ips --base base.csv --mix examples/asn-mix.yaml --out base_ip.csv   # optional, for A2/D8/D9
+otpguard simulate inject --base base_ip.csv --scenario A2 --start 2022-05-10T10:00 --volume 0.05 --out mixed.csv
+otpguard replay mixed.csv --mapping base.mapping.yaml --policy policy.yaml
+```
+
+`--volume` sets the attack rate as a fraction of the log's average OTP rate.
+
+Scenarios: A1 pumping to one country from a few IPs, A2 the same with a fresh IP per
+request, A3 sequential numbers from one prefix, A4 low and slow, A5 one reset to each of
+many existing customers, A6 resend loops, A7 A1 during a sale.
+`python benchmarks/run_scenarios.py` runs all of them; add `--seeds 10`, `--volumes 0.01
+0.05 0.1 0.2`, `--designs full limiter without-L1 without-L3 without-L4` (a conventional
+per-number + per-IP limiter and layer ablations) and `--base`/`--mapping` for your own
+imported log. `python benchmarks/latency.py --redis redis://localhost:6379/1` measures
+decision latency. Results from the current version are in
+[`benchmarks/results`](benchmarks/results/scenarios.md). They come from synthetic
+traffic, so treat them as a sanity check rather than a promise.
+
+## Limits
+
+- A decision makes several Redis round trips (one per counter family); only the hard
+  rules are atomic. Soft scores can be off by a request or two under heavy concurrency.
+- Baselines need a few days of traffic. Until then the caps, country rules and
+  budgets do most of the work.
+- An attacker who spreads traffic thinly over many countries, each below its usual
+  share, is mostly stopped by the budgets, not by detection.
+- Set `timezone` in the mapping and the policy to the zone your log is written in;
+  naive timestamps and campaign dates are read in that zone.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

otpguard-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "otpguard"
+version = "0.1.0"
+description = "Decide whether an OTP SMS should be sent: SMS pumping, bombing and enumeration checks for any provider"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Muhammad Tanzil", email = "mtanzil666@gmail.com" }]
+keywords = ["otp", "sms", "sms pumping", "fraud", "rate limiting", "security"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+  "Topic :: Communications :: Telephony",
+]
+dependencies = ["phonenumbers>=8.13", "PyYAML>=6", "tzdata; platform_system == \"Windows\""]
+
+[project.optional-dependencies]
+redis = ["redis>=5"]
+sql = ["SQLAlchemy>=2.0"]
+server = ["fastapi>=0.110", "uvicorn>=0.29"]
+dev = ["pytest>=7", "fakeredis[lua]>=2.20", "redis>=5", "SQLAlchemy>=2.0", "fastapi>=0.110", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/mtanzil6/otpguard"
+Issues = "https://github.com/mtanzil6/otpguard/issues"
+
+[project.scripts]
+otpguard = "otpguard.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

otpguard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

otpguard-0.1.0/src/otpguard/__init__.py

@@ -0,0 +1,9 @@
+"""otpguard: decide whether an OTP SMS should be sent, before you pay for it."""
+from .model import Action, Decision, OtpRequest, Signal
+from .policy import Policy
+from .sentinel import AsyncSentinel, Sentinel
+from .store import MemoryStore, StoreError
+
+__version__ = "0.1.0"
+__all__ = ["Action", "Decision", "OtpRequest", "Signal", "Policy", "Sentinel", "AsyncSentinel", "MemoryStore",
+           "StoreError", "__version__"]

otpguard-0.1.0/src/otpguard/baselines.py

@@ -0,0 +1,81 @@
+"""Hourly baselines (EWMA mean and variance) that the population detectors compare against.
+
+Each key keeps an overall estimate and, once there is enough history, one per hour of
+the week. Hours with no traffic count as zeros; for sparse keys such as prefixes the
+zeros are applied lazily when the key is next touched."""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from .store.base import Store
+
+
+def hour_of_week(hour_index: int) -> int:
+    # hour_index is hours since the epoch; 1970-01-01 was a Thursday
+    return (hour_index + 3 * 24) % 168
+
+
+@dataclass
+class Estimate:
+    mean: float
+    std: float
+    n: int            # hours of history behind the key
+    weekly: bool = False
+
+
+class Baselines:
+    def __init__(self, store: Store, alpha: float = 0.05, how_min_samples: int = 3):
+        self.store = store
+        self.alpha = alpha
+        self.how_min = how_min_samples
+
+    def _key(self, dim: str, key: str) -> str:
+        return f"base:{dim}:{key}"
+
+    def update(self, dim: str, key: str, hour_index: int, value: float, alpha: float | None = None,
+               by_hour_of_week: bool = True) -> None:
+        a = alpha or self.alpha
+        k = self._key(dim, key)
+        rec: dict[str, Any] = self.store.get_json(k) or {"m": None, "v": 0.0, "n": 0, "h": None, "w": {}}
+        # decay for the hours we did not see (sparse keys)
+        if rec["m"] is not None and rec["h"] is not None and hour_index - rec["h"] > 1:
+            gap = hour_index - rec["h"] - 1
+            f = (1 - a) ** gap
+            rec["v"] = rec["v"] * f + (1 - f) * rec["m"] ** 2 * a   # rough: zeros add spread
+            rec["m"] *= f
+            rec["n"] += gap
+        rec["m"], rec["v"] = _ewma(rec["m"], rec["v"], value, a)
+        rec["n"] += 1
+        rec["h"] = hour_index
+        if by_hour_of_week:
+            how = str(hour_of_week(hour_index))
+            w = rec["w"].get(how) or [None, 0.0, 0]
+            # weekly series are short, so they adapt faster
+            w[0], w[1] = _ewma(w[0], w[1], value, min(0.5, a * 6))
+            w[2] += 1
+            rec["w"][how] = w
+        self.store.set_json(k, rec, ttl_s=60 * 86400)
+
+    def get(self, dim: str, key: str, hour_index: int) -> Estimate | None:
+        rec = self.store.get_json(self._key(dim, key))
+        if not rec or rec["m"] is None:
+            return None
+        w = rec["w"].get(str(hour_of_week(hour_index)))
+        if w and w[2] >= self.how_min and w[0] is not None:
+            return Estimate(w[0], math.sqrt(max(w[1], 0.0)), rec["n"], weekly=True)
+        m, v = rec["m"], rec["v"]
+        if rec["h"] is not None and hour_index - rec["h"] > 1:
+            f = (1 - self.alpha) ** (hour_index - rec["h"] - 1)
+            m *= f
+        return Estimate(m, math.sqrt(max(v, 0.0)), rec["n"])
+
+
+def _ewma(mean: float | None, var: float, x: float, a: float) -> tuple[float, float]:
+    if mean is None:
+        return x, 0.0
+    d = x - mean
+    mean = mean + a * d
+    var = (1 - a) * (var + a * d * d)
+    return mean, var