jevmod 0.2.0__py3-none-any.whl

jevmod/cli.py

@@ -0,0 +1,97 @@
+"""Command line for developers and scripts: judge text from the terminal, no server, no database.
+
+    jevmod check "FREE NITRO claim at discord-gifts.ru"          # one message
+    jevmod check -  < messages.txt                                # one message per line, one Jev request per 50
+    jevmod check --topic "support" --rule "No politics" -- "..."  # context and a plain-language rule
+    jevmod check --json ...                                       # machine-readable, one object per line
+    jevmod init                                                   # store the TypeSafe key (keyring, or .env)
+    jevmod mcp                                                    # MCP server over stdio for coding agents
+
+Exit code 0 when no message triggers an action, 1 when at least one does, 2 on an error. Pipe-friendly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Iterable
+
+from . import Moderator, Policy
+from .judge import CATEGORIES
+
+
+def _read_texts(args: argparse.Namespace) -> list[str]:
+    if args.text == ["-"] or not args.text:
+        return [line.rstrip("\n") for line in sys.stdin if line.strip()]
+    return [" ".join(args.text)]
+
+
+def _chunks(items: list[str], n: int) -> Iterable[list[str]]:
+    for i in range(0, len(items), n):
+        yield items[i : i + n]
+
+
+def check(args: argparse.Namespace) -> int:
+    policy = Policy()
+    for c in CATEGORIES:
+        policy.set_category(c, "off" if c == "offtopic" and not args.topic else "flag", args.threshold)
+    for i, rule in enumerate(args.rule or []):
+        policy.set_rule(f"rule{i + 1}", rule)
+    mod = Moderator(policy=policy)
+    texts = _read_texts(args)
+    if not texts:
+        print("nothing to check", file=sys.stderr)
+        return 2
+    hit = False
+    for batch in _chunks(texts, 50):
+        for text, d in zip(batch, mod.check_many(batch, channel_topic=args.topic), strict=True):
+            hit = hit or d.action != "none"
+            if args.json:
+                print(json.dumps({"text": text, **d.to_dict()}, ensure_ascii=False))
+            else:
+                top = ", ".join(f"{k} {v:.2f}" for k, v in sorted(d.scores.items(), key=lambda kv: -kv[1])[:3])
+                verdict = f"{d.category} {d.probability:.2f}" if d.action != "none" else "ok"
+                if not d.judged:
+                    verdict = f"skipped ({d.reason})"
+                print(f"{verdict:<28} {text[:70]!r}  [{top}]")
+    return 1 if hit else 0
+
+
+def init(args: argparse.Namespace) -> int:
+    from .keys import forget
+    from .keys import init as store_key
+
+    if args.forget:
+        return forget()
+    return store_key(prefer_env_file=args.env_file)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="jevmod", description="Moderation decisions powered by Jev.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("check", help="judge one message (argument) or many (stdin, one per line with '-')")
+    p.add_argument("text", nargs="*", help="the message; '-' or nothing reads stdin")
+    p.add_argument("--topic", default="", help="what the channel is about (enables the offtopic check)")
+    p.add_argument("--rule", action="append", help="a rule in plain language; repeatable, up to 5")
+    p.add_argument("--threshold", type=float, default=None, help="one threshold for every category (0.5-0.99)")
+    p.add_argument("--json", action="store_true", help="one JSON object per line")
+    p.set_defaults(func=check)
+    p = sub.add_parser("init", help="ask for the TypeSafe key (hidden input), verify it, store it in the OS keyring")
+    p.add_argument("--env-file", action="store_true", help="write .env in the current directory instead of the keyring")
+    p.add_argument("--forget", action="store_true", help="remove the key from the OS keyring")
+    p.set_defaults(func=init)
+    sub.add_parser("mcp", help="MCP server over stdio (tools: moderate, categories)")
+    for role in ("api", "demo", "discord", "telegram", "reddit"):
+        sub.add_parser(role, help=f"run the {role} role (same as JEVMOD_ROLE={role})")
+    args = parser.parse_args(argv)
+    if args.cmd in ("check", "init"):
+        try:
+            return int(args.func(args))
+        except Exception as exc:  # network, key, quota: say it in one line, exit 2
+            print(f"error: {type(exc).__name__}: {exc}", file=sys.stderr)
+            return 2
+    from .__main__ import run_role
+
+    run_role(args.cmd)
+    return 0

jevmod/core/__init__.py

@@ -0,0 +1,17 @@
+from .policy import ACTIONS, DEFAULT_ACTIONS, DEFAULT_THRESHOLDS, RULE_THRESHOLD, Decision, Policy, decide
+from .service import Batcher, ModerationService
+from .store import FREE_MONTHLY, Store
+
+__all__ = [
+    "ACTIONS",
+    "DEFAULT_ACTIONS",
+    "DEFAULT_THRESHOLDS",
+    "FREE_MONTHLY",
+    "RULE_THRESHOLD",
+    "Batcher",
+    "Decision",
+    "ModerationService",
+    "Policy",
+    "Store",
+    "decide",
+]

jevmod/core/policy.py

@@ -0,0 +1,155 @@
+"""Policy: turn a Verdict (probabilities) into a Decision (what to do), per tenant. Pure code, offline-testable."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..judge import CATEGORIES, Verdict
+
+ACTIONS = ("off", "flag", "delete", "timeout")  # ordered by severity
+DEFAULT_THRESHOLDS = {
+    "spam": 0.85,
+    "scam": 0.75,
+    "harassment": 0.75,
+    "nsfw": 0.8,
+    "offtopic": 0.9,
+    "selfharm": 0.8,
+    "doxxing": 0.8,
+    "minors": 0.7,
+}
+# selfharm is flag-only by design: moderators should reach out, not punish. doxxing/minors flag by default;
+# communities that want automatic removal set delete/timeout explicitly.
+DEFAULT_ACTIONS = {
+    "spam": "flag",
+    "scam": "flag",
+    "harassment": "flag",
+    "nsfw": "flag",
+    "offtopic": "off",
+    "selfharm": "flag",
+    "doxxing": "flag",
+    "minors": "flag",
+}
+RULE_THRESHOLD = 0.8
+POLICY_VERSION = 1
+
+
+@dataclass
+class Policy:
+    thresholds: dict[str, float] = field(default_factory=lambda: dict(DEFAULT_THRESHOLDS))
+    actions: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_ACTIONS))
+    rules: dict[str, str] = field(default_factory=dict)  # name -> natural-language rule
+    rule_actions: dict[str, str] = field(default_factory=dict)  # name -> action (default flag)
+    rule_thresholds: dict[str, float] = field(default_factory=dict)
+    timeout_minutes: int = 10
+
+    def enabled_categories(self) -> list[str]:
+        return [c for c in CATEGORIES if self.actions.get(c, "off") != "off"]
+
+    def active(self) -> bool:
+        return bool(self.enabled_categories() or self.rules)
+
+    def set_category(self, category: str, action: str, threshold: float | None = None) -> None:
+        if category not in CATEGORIES:
+            raise ValueError(f"unknown category {category!r}; one of {', '.join(CATEGORIES)}")
+        if action not in ACTIONS:
+            raise ValueError(f"unknown action {action!r}; one of {', '.join(ACTIONS)}")
+        self.actions[category] = action
+        if threshold is not None:
+            self.thresholds[category] = _clamp(threshold)
+
+    def set_rule(self, name: str, text: str | None, action: str = "flag", threshold: float | None = None) -> None:
+        name = name.strip().lower().replace(" ", "_")[:30]
+        if text is None or not text.strip():
+            self.rules.pop(name, None)
+            self.rule_actions.pop(name, None)
+            self.rule_thresholds.pop(name, None)
+            return
+        if len(self.rules) >= 5 and name not in self.rules:
+            raise ValueError("up to 5 custom rules")
+        if action not in ACTIONS:
+            raise ValueError(f"unknown action {action!r}")
+        self.rules[name] = text.strip()[:200]
+        self.rule_actions[name] = action
+        if threshold is not None:
+            self.rule_thresholds[name] = _clamp(threshold)
+
+    def nudge(self, category: str, delta: float = 0.03) -> float:
+        """False-positive feedback: raise that category's threshold a notch."""
+        if category.startswith("rule:"):
+            name = category[5:]
+            cur = self.rule_thresholds.get(name, RULE_THRESHOLD)
+            self.rule_thresholds[name] = _clamp(cur + delta)
+            return self.rule_thresholds[name]
+        cur = self.thresholds.get(category, 0.9)
+        self.thresholds[category] = _clamp(cur + delta)
+        return self.thresholds[category]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "thresholds": self.thresholds,
+            "actions": self.actions,
+            "rules": self.rules,
+            "rule_actions": self.rule_actions,
+            "rule_thresholds": self.rule_thresholds,
+            "timeout_minutes": self.timeout_minutes,
+            "version": POLICY_VERSION,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Policy:
+        p = cls()
+        for k in ("thresholds", "actions", "rules", "rule_actions", "rule_thresholds"):
+            if isinstance(d.get(k), dict):
+                getattr(p, k).update(d[k])
+        if "timeout_minutes" in d:
+            p.timeout_minutes = int(d["timeout_minutes"])
+        return p
+
+
+@dataclass
+class Decision:
+    message_id: str
+    action: str  # "none" | "flag" | "delete" | "timeout"
+    category: str | None  # winning category or "rule:<name>"
+    probability: float
+    scores: dict[str, float]  # everything Jev returned, for the audit log
+    judged: bool
+    reason: str  # "jev" | "cache" | pre-filter reason | "quota" | "error_open"
+    policy_version: int = POLICY_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "message_id": self.message_id,
+            "action": self.action,
+            "category": self.category,
+            "probability": round(self.probability, 4),
+            "scores": {k: round(v, 4) for k, v in self.scores.items()},
+            "judged": self.judged,
+            "reason": self.reason,
+            "policy_version": self.policy_version,
+        }
+
+
+def decide(policy: Policy, v: Verdict) -> Decision:
+    """The most severe action whose threshold is crossed wins; ties go to the higher probability."""
+    scores = {**v.scores, **{f"rule:{n}": p for n, p in v.custom.items()}}
+    if not v.judged:
+        return Decision(v.message_id, "none", None, 0.0, scores, False, v.reason)
+    hits: list[tuple[str, float, str]] = []
+    for c, p in v.scores.items():
+        action = policy.actions.get(c, "off")
+        if action != "off" and p >= policy.thresholds.get(c, 1.0):
+            hits.append((c, p, action))
+    for n, p in v.custom.items():
+        action = policy.rule_actions.get(n, "flag")
+        if action != "off" and p >= policy.rule_thresholds.get(n, RULE_THRESHOLD):
+            hits.append((f"rule:{n}", p, action))
+    if not hits:
+        return Decision(v.message_id, "none", None, 0.0, scores, True, v.reason)
+    category, p, action = max(hits, key=lambda h: (ACTIONS.index(h[2]), h[1]))
+    return Decision(v.message_id, action, category, p, scores, True, v.reason)
+
+
+def _clamp(x: float) -> float:
+    return max(0.5, min(0.99, round(float(x), 2)))

jevmod/core/service.py

@@ -0,0 +1,117 @@
+"""ModerationService: one entry point for every adapter and for the HTTP API.
+
+    svc = ModerationService(store)
+    decisions = svc.moderate(tenant_id, messages)   # applies policy, quota, audit log, fail-open
+
+Tenant = a Discord guild, a Telegram chat, a subreddit or an API key. The service never knows which.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from typesafe_sdk import TypeSafeError
+
+from ..judge import Judge, Message
+from .policy import Decision, Policy, decide
+from .store import Store
+
+log = logging.getLogger("jevmod")
+
+JEV_USD_PER_M_INPUT = 0.042
+
+
+class ModerationService:
+    def __init__(self, store: Store, judge: Judge | None = None, fail_open: bool = True) -> None:
+        self.store = store
+        self._judge = judge
+        self.fail_open = fail_open
+
+    @property
+    def judge(self) -> Judge:
+        if self._judge is None:
+            self._judge = Judge()
+        return self._judge
+
+    def policy(self, tenant: str) -> Policy:
+        return self.store.get_policy(tenant)
+
+    def save_policy(self, tenant: str, policy: Policy) -> None:
+        self.store.save_policy(tenant, policy)
+
+    def moderate(self, tenant: str, messages: list[Message], request_id: str | None = None) -> list[Decision]:
+        rid = request_id or uuid.uuid4().hex[:12]
+        policy = self.policy(tenant)
+        if not policy.active():
+            return [Decision(m.id, "none", None, 0.0, {}, False, "policy inactive") for m in messages]
+        self.store.purge_expired()
+        if self.store.over_quota(tenant):
+            self.store.note_quota_hit(tenant)
+            return [Decision(m.id, "none", None, 0.0, {}, False, "quota") for m in messages]
+        j = self.judge
+        before = (j.requests, j.input_tokens, j.judged_messages)
+        t0 = time.perf_counter()
+        try:
+            verdicts = j.judge(messages, policy.enabled_categories(), policy.rules)
+        except TypeSafeError as exc:
+            log.warning(
+                {"event": "judge_error", "tenant": tenant, "rid": rid, "error": f"{type(exc).__name__}: {exc}"[:200]}
+            )
+            if not self.fail_open:
+                raise
+            return [Decision(m.id, "none", None, 0.0, {}, False, "error_open") for m in messages]
+        ms = int((time.perf_counter() - t0) * 1000)
+        judged = j.judged_messages - before[2]
+        reqs = j.requests - before[0]
+        toks = j.input_tokens - before[1]
+        self.store.add_usage(tenant, judged, reqs, toks)
+        decisions = [decide(policy, v) for v in verdicts]
+        for m, d in zip(messages, decisions, strict=True):
+            if d.action != "none":
+                self.store.log_decision(tenant, m, d, rid)
+        log.info(
+            {
+                "event": "moderate",
+                "tenant": tenant,
+                "rid": rid,
+                "messages": len(messages),
+                "judged": judged,
+                "requests": reqs,
+                "input_tokens": toks,
+                "usd": round(toks * JEV_USD_PER_M_INPUT / 1e6, 6),
+                "ms": ms,
+                "actions": {a: sum(1 for d in decisions if d.action == a) for a in ("flag", "delete", "timeout")},
+            }
+        )
+        return decisions
+
+
+class Batcher:
+    """Collects messages per tenant for `window_s`, then hands the batch to `handler` (async). One Jev request per
+    tenant per window instead of one per message."""
+
+    def __init__(self, window_s: float, handler: Callable[[str, list[Any]], Any]) -> None:
+        self.window = window_s
+        self.handler = handler
+        self.pending: dict[str, list[Any]] = {}
+        self.tasks: dict[str, asyncio.Task] = {}
+
+    def add(self, tenant: str, item: Any) -> None:
+        self.pending.setdefault(tenant, []).append(item)
+        t = self.tasks.get(tenant)
+        if t is None or t.done():
+            self.tasks[tenant] = asyncio.create_task(self._flush(tenant))
+
+    async def _flush(self, tenant: str) -> None:
+        await asyncio.sleep(self.window)
+        batch = self.pending.pop(tenant, [])
+        if batch:
+            try:
+                await self.handler(tenant, batch)
+            except Exception as exc:  # an adapter bug must not stop future batches
+                log.exception({"event": "batch_handler_error", "tenant": tenant, "error": str(exc)[:200]})

jevmod/core/store.py

@@ -0,0 +1,215 @@
+"""Tenant policies, usage counters, an optional monthly quota and the audit log, in SQLite."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from ..judge import Message
+from .policy import Decision, Policy
+
+# Optional cost guard per tenant per month. 0 (the default) means unlimited; set JEVMOD_MONTHLY_QUOTA=5000 to pause
+# judging for a tenant after 5,000 judged messages in a calendar month (nothing is deleted while paused).
+FREE_MONTHLY = int(os.environ.get("JEVMOD_MONTHLY_QUOTA", "0") or 0)
+
+
+class Store:
+    def __init__(
+        self,
+        path: str | Path = "jevmod.sqlite",
+        keep_text_chars: int = 300,
+        retention_days: int = 30,
+        monthly_quota: int | None = None,
+    ) -> None:
+        """keep_text_chars=0 stores no message text at all. Decisions older than retention_days are purged on
+        every write and by `purge_expired()`, which the service also calls on every batch."""
+        self.db = sqlite3.connect(str(path), check_same_thread=False)
+        self.lock = threading.Lock()
+        self.keep_text_chars = keep_text_chars
+        self.retention_days = retention_days
+        self.monthly_quota = FREE_MONTHLY if monthly_quota is None else monthly_quota  # 0 = unlimited
+        with self.lock:
+            self.db.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS tenants (
+                    id TEXT PRIMARY KEY, policy TEXT NOT NULL, plan TEXT NOT NULL DEFAULT 'free',
+                    meta TEXT NOT NULL DEFAULT '{}', quota_notified TEXT DEFAULT '');
+                CREATE TABLE IF NOT EXISTS usage (
+                    tenant TEXT, month TEXT, judged INTEGER, requests INTEGER, tokens INTEGER,
+                    PRIMARY KEY (tenant, month));
+                CREATE TABLE IF NOT EXISTS decisions (
+                    ts REAL, tenant TEXT, rid TEXT, message TEXT, author TEXT, channel TEXT,
+                    category TEXT, p REAL, action TEXT, scores TEXT, text TEXT);
+                CREATE INDEX IF NOT EXISTS decisions_tenant_ts ON decisions (tenant, ts);
+                CREATE TABLE IF NOT EXISTS api_keys (
+                    key_hash TEXT PRIMARY KEY, tenant TEXT NOT NULL, created REAL, label TEXT);
+                """
+            )
+            self.db.commit()
+
+    # ---- policy
+    def get_policy(self, tenant: str) -> Policy:
+        with self.lock:
+            row = self.db.execute("SELECT policy FROM tenants WHERE id=?", (tenant,)).fetchone()
+        return Policy.from_dict(json.loads(row[0])) if row else Policy()
+
+    def save_policy(self, tenant: str, policy: Policy) -> None:
+        with self.lock:
+            self.db.execute(
+                "INSERT INTO tenants (id, policy) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET policy=excluded.policy",
+                (tenant, json.dumps(policy.to_dict())),
+            )
+            self.db.commit()
+
+    def get_meta(self, tenant: str) -> dict[str, Any]:
+        with self.lock:
+            row = self.db.execute("SELECT meta FROM tenants WHERE id=?", (tenant,)).fetchone()
+        return json.loads(row[0]) if row else {}
+
+    def set_meta(self, tenant: str, **kw: Any) -> None:
+        meta = {**self.get_meta(tenant), **kw}
+        with self.lock:
+            self.db.execute(
+                "INSERT INTO tenants (id, policy, meta) VALUES (?, ?, ?) "
+                "ON CONFLICT(id) DO UPDATE SET meta=excluded.meta",
+                (tenant, json.dumps(Policy().to_dict()), json.dumps(meta)),
+            )
+            self.db.commit()
+
+    def plan(self, tenant: str) -> str:
+        with self.lock:
+            row = self.db.execute("SELECT plan FROM tenants WHERE id=?", (tenant,)).fetchone()
+        return row[0] if row else "free"
+
+    def set_plan(self, tenant: str, plan: str) -> None:
+        with self.lock:
+            self.db.execute(
+                "INSERT INTO tenants (id, policy, plan) VALUES (?, ?, ?) "
+                "ON CONFLICT(id) DO UPDATE SET plan=excluded.plan",
+                (tenant, json.dumps(Policy().to_dict()), plan),
+            )
+            self.db.commit()
+
+    # ---- usage and quota
+    @staticmethod
+    def month() -> str:
+        return time.strftime("%Y-%m")
+
+    def add_usage(self, tenant: str, judged: int, requests: int, tokens: int) -> None:
+        with self.lock:
+            self.db.execute(
+                "INSERT INTO usage (tenant, month, judged, requests, tokens) VALUES (?, ?, ?, ?, ?) "
+                "ON CONFLICT(tenant, month) DO UPDATE SET judged=judged+excluded.judged, "
+                "requests=requests+excluded.requests, tokens=tokens+excluded.tokens",
+                (tenant, self.month(), judged, requests, tokens),
+            )
+            self.db.commit()
+
+    def usage(self, tenant: str) -> tuple[int, int, int]:
+        with self.lock:
+            row = self.db.execute(
+                "SELECT judged, requests, tokens FROM usage WHERE tenant=? AND month=?", (tenant, self.month())
+            ).fetchone()
+        return tuple(row) if row else (0, 0, 0)
+
+    def over_quota(self, tenant: str) -> bool:
+        return self.monthly_quota > 0 and self.plan(tenant) == "free" and self.usage(tenant)[0] >= self.monthly_quota
+
+    def note_quota_hit(self, tenant: str) -> bool:
+        """True the first time this month the tenant hits the quota (so the adapter can notify the owner once)."""
+        with self.lock:
+            row = self.db.execute("SELECT quota_notified FROM tenants WHERE id=?", (tenant,)).fetchone()
+            if row and row[0] == self.month():
+                return False
+            self.db.execute(
+                "INSERT INTO tenants (id, policy, quota_notified) VALUES (?, ?, ?) "
+                "ON CONFLICT(id) DO UPDATE SET quota_notified=excluded.quota_notified",
+                (tenant, json.dumps(Policy().to_dict()), self.month()),
+            )
+            self.db.commit()
+            return True
+
+    # ---- audit
+    def purge_expired(self) -> int:
+        cutoff = time.time() - self.retention_days * 86400
+        with self.lock:
+            cur = self.db.execute("DELETE FROM decisions WHERE ts < ?", (cutoff,))
+            self.db.commit()
+            return cur.rowcount
+
+    def delete_user(self, tenant: str, author: str) -> int:
+        """Right to erasure for one member of a community."""
+        with self.lock:
+            cur = self.db.execute("DELETE FROM decisions WHERE tenant=? AND author=?", (tenant, author))
+            self.db.commit()
+            return cur.rowcount
+
+    def log_decision(self, tenant: str, m: Message, d: Decision, rid: str) -> None:
+        self.purge_expired()
+        with self.lock:
+            self.db.execute(
+                "INSERT INTO decisions VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    time.time(),
+                    tenant,
+                    rid,
+                    m.id,
+                    m.author,
+                    m.channel_topic[:80],
+                    d.category,
+                    d.probability,
+                    d.action,
+                    json.dumps({k: round(v, 3) for k, v in d.scores.items()}),
+                    m.text[: self.keep_text_chars],
+                ),
+            )
+            self.db.commit()
+
+    def recent_decisions(self, tenant: str, n: int = 10) -> list[dict[str, Any]]:
+        with self.lock:
+            rows = self.db.execute(
+                "SELECT ts, message, category, p, action, scores, text FROM decisions "
+                "WHERE tenant=? ORDER BY ts DESC LIMIT ?",
+                (tenant, n),
+            ).fetchall()
+        return [
+            {
+                "ts": r[0],
+                "message_id": r[1],
+                "category": r[2],
+                "p": r[3],
+                "action": r[4],
+                "scores": json.loads(r[5]),
+                "text": r[6],
+            }
+            for r in rows
+        ]
+
+    def export_decisions(self, tenant: str) -> list[dict[str, Any]]:
+        return self.recent_decisions(tenant, 100000)
+
+    def delete_tenant(self, tenant: str) -> None:
+        """GDPR: forget everything about a community or API tenant."""
+        with self.lock:
+            for table, col in (("tenants", "id"), ("usage", "tenant"), ("decisions", "tenant"), ("api_keys", "tenant")):
+                self.db.execute(f"DELETE FROM {table} WHERE {col}=?", (tenant,))
+            self.db.commit()
+
+    # ---- API keys (developers)
+    def create_api_key(self, tenant: str, key_hash: str, label: str = "") -> None:
+        with self.lock:
+            self.db.execute(
+                "INSERT OR REPLACE INTO api_keys (key_hash, tenant, created, label) VALUES (?, ?, ?, ?)",
+                (key_hash, tenant, time.time(), label),
+            )
+            self.db.commit()
+
+    def tenant_for_key(self, key_hash: str) -> str | None:
+        with self.lock:
+            row = self.db.execute("SELECT tenant FROM api_keys WHERE key_hash=?", (key_hash,)).fetchone()
+        return row[0] if row else None