jevmod 0.2.0__tar.gz → 0.2.1__tar.gz

{jevmod-0.2.0 → jevmod-0.2.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: jevmod
-Version: 0.2.0
+Version: 0.2.1
 Summary: Moderation for communities and apps, powered by Jev: spam, scams, harassment, adult, off-topic and your own plain-language rules, with a probability per category and thresholds you own.
 Author: Omar Hernandez
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/ohernandezdev/jevmod
+Project-URL: Homepage, https://jevmod.dev
+Project-URL: Repository, https://github.com/ohernandezdev/jevmod
 Keywords: moderation,discord,telegram,reddit,content-moderation,typesafe,jev
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3
@@ -22,6 +23,8 @@ Provides-Extra: telegram
 Requires-Dist: python-telegram-bot>=21; extra == "telegram"
 Provides-Extra: reddit
 Requires-Dist: praw>=7.7; extra == "reddit"
+Provides-Extra: billing
+Requires-Dist: stripe>=12; extra == "billing"
 Provides-Extra: mcp
 Requires-Dist: mcp>=2; extra == "mcp"
 Provides-Extra: keys
@@ -32,6 +35,7 @@ Requires-Dist: python-telegram-bot>=21; extra == "all"
 Requires-Dist: praw>=7.7; extra == "all"
 Requires-Dist: mcp>=2; extra == "all"
 Requires-Dist: keyring>=25; extra == "all"
+Requires-Dist: stripe>=12; extra == "all"
 Provides-Extra: examples
 Requires-Dist: langchain-core>=0.3; extra == "examples"
 Requires-Dist: httpx; extra == "examples"
@@ -51,6 +55,8 @@ You set the thresholds and the actions. Every decision is logged with its number
 It runs on [Jev](https://typesafe.ai), TypeSafe's System One model: you ask yes/no questions about a message and
 get probabilities back, no text generation. About **$0.04 per 1,000 messages** with all categories on.
 
+Site: **https://jevmod.dev** (community owners) and **https://jevmod.dev/developers/** (packages, API, MCP, benchmark, cost calculator)
+
 ![jevmod check and the HTTP API in a terminal](docs/jevmod.gif)
 
 ```
@@ -174,7 +180,7 @@ hold the TypeSafe key. Express middleware in `packages/jevmod-js/examples/`. Det
 ### HTTP API
 
 ```bash
-JEVMOD_ADMIN_TOKEN=... jevmod api                     # or: docker compose up -d
+JEVMOD_ADMIN_TOKEN=... jevmod api                     # binds 127.0.0.1; JEVMOD_HOST=0.0.0.0 to expose (Docker does)
 curl -X POST localhost:8080/v1/keys -H "Authorization: Bearer $JEVMOD_ADMIN_TOKEN" \
      -H "Content-Type: application/json" -d '{"tenant":"my-app"}'          # {"api_key":"jm_...", shown once}
 curl -X POST localhost:8080/v1/moderate -H "Authorization: Bearer jm_..." -H "Content-Type: application/json" \
@@ -190,7 +196,7 @@ curl -X POST localhost:8080/v1/moderate -H "Authorization: Bearer jm_..." -H "Co
 | `POST /v1/keys` (admin) | mint a tenant key, stored hashed |
 | `GET /v1/health`, `GET /metrics` | liveness, Prometheus counters |
 
-OpenAPI at `/docs`, a Postman collection in `postman/`. Any chatbot, forum or comment system that can make an HTTP
+OpenAPI at `/docs` on a running server (a static copy at [docs/openapi.json](docs/openapi.json)), a Postman collection at [postman/jevmod.postman_collection.json](postman/jevmod.postman_collection.json). Any chatbot, forum or comment system that can make an HTTP
 call can use it; the bots are adapters over the same service.
 
 ### Examples, one folder per surface

{jevmod-0.2.0 → jevmod-0.2.1}/README.md

@@ -7,6 +7,8 @@ You set the thresholds and the actions. Every decision is logged with its number
 It runs on [Jev](https://typesafe.ai), TypeSafe's System One model: you ask yes/no questions about a message and
 get probabilities back, no text generation. About **$0.04 per 1,000 messages** with all categories on.
 
+Site: **https://jevmod.dev** (community owners) and **https://jevmod.dev/developers/** (packages, API, MCP, benchmark, cost calculator)
+
 ![jevmod check and the HTTP API in a terminal](docs/jevmod.gif)
 
 ```
@@ -130,7 +132,7 @@ hold the TypeSafe key. Express middleware in `packages/jevmod-js/examples/`. Det
 ### HTTP API
 
 ```bash
-JEVMOD_ADMIN_TOKEN=... jevmod api                     # or: docker compose up -d
+JEVMOD_ADMIN_TOKEN=... jevmod api                     # binds 127.0.0.1; JEVMOD_HOST=0.0.0.0 to expose (Docker does)
 curl -X POST localhost:8080/v1/keys -H "Authorization: Bearer $JEVMOD_ADMIN_TOKEN" \
      -H "Content-Type: application/json" -d '{"tenant":"my-app"}'          # {"api_key":"jm_...", shown once}
 curl -X POST localhost:8080/v1/moderate -H "Authorization: Bearer jm_..." -H "Content-Type: application/json" \
@@ -146,7 +148,7 @@ curl -X POST localhost:8080/v1/moderate -H "Authorization: Bearer jm_..." -H "Co
 | `POST /v1/keys` (admin) | mint a tenant key, stored hashed |
 | `GET /v1/health`, `GET /metrics` | liveness, Prometheus counters |
 
-OpenAPI at `/docs`, a Postman collection in `postman/`. Any chatbot, forum or comment system that can make an HTTP
+OpenAPI at `/docs` on a running server (a static copy at [docs/openapi.json](docs/openapi.json)), a Postman collection at [postman/jevmod.postman_collection.json](postman/jevmod.postman_collection.json). Any chatbot, forum or comment system that can make an HTTP
 call can use it; the bots are adapters over the same service.
 
 ### Examples, one folder per surface

jevmod-0.2.1/jevmod/__main__.py

@@ -0,0 +1,72 @@
+"""`python -m jevmod` / `jevmod`: `check` judges text from the terminal, `init` stores the key, `mcp` serves the
+MCP tools over stdio; `api`, `discord`, `telegram`, `reddit` start that role (default role from JEVMOD_ROLE, then
+`api`)."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+REQUIRED_TOKEN = {"discord": "DISCORD_TOKEN", "telegram": "TELEGRAM_TOKEN", "reddit": "REDDIT_CLIENT_ID"}
+TOKEN_HINT = {
+    "DISCORD_TOKEN": "Developer Portal → Bot → Reset Token",
+    "TELEGRAM_TOKEN": "@BotFather → /newbot",
+    "REDDIT_CLIENT_ID": "https://www.reddit.com/prefs/apps (script app)",
+}
+
+
+def run_role(role: str) -> None:
+    role = role.lower()
+    needed = REQUIRED_TOKEN.get(role)
+    if needed and not os.environ.get(needed):  # before the adapter imports and creates its SQLite file
+        raise SystemExit(f"set {needed} ({TOKEN_HINT[needed]})")
+    if role == "api":
+        import uvicorn
+
+        uvicorn.run(
+            "jevmod.api.server:app",
+            host=os.environ.get("JEVMOD_HOST", "127.0.0.1"),
+            port=int(os.environ.get("PORT", "8080")),
+            log_level="info",
+        )
+    elif role == "discord":
+        from .adapters.discord_bot import main as run
+
+        run()
+    elif role == "telegram":
+        from .adapters.telegram_bot import main as run
+
+        run()
+    elif role == "reddit":
+        from .adapters.reddit_bot import run
+
+        run()
+    elif role in ("demo", "hosted"):
+        import uvicorn
+
+        uvicorn.run(
+            "jevmod.api.demo:app" if role == "demo" else "jevmod.api.hosted:app",
+            host=os.environ.get("JEVMOD_HOST", "127.0.0.1"),
+            port=int(os.environ.get("PORT", "8080")),
+            log_level="info",
+        )
+    elif role == "mcp":
+        from .mcp_server import main as run
+
+        run()
+    else:
+        raise SystemExit(
+            f"unknown role {role!r}; use check | init | mcp | api | demo | hosted | discord | telegram | reddit"
+        )
+
+
+def main() -> None:
+    if len(sys.argv) > 1:
+        from .cli import main as cli
+
+        sys.exit(cli(sys.argv[1:]))
+    run_role(os.environ.get("JEVMOD_ROLE", "api"))
+
+
+if __name__ == "__main__":
+    main()

{jevmod-0.2.0 → jevmod-0.2.1}/jevmod/adapters/discord_bot.py

@@ -16,7 +16,7 @@ from datetime import timedelta
 import discord
 from discord import app_commands
 
-from ..core import FREE_MONTHLY, RULE_THRESHOLD, Batcher, Decision, ModerationService, Store
+from ..core import RULE_THRESHOLD, Batcher, Decision, ModerationService, Store
 from ..judge import CATEGORIES, Message
 
 log = logging.getLogger("jevmod.discord")
@@ -84,27 +84,37 @@ async def on_message(msg: discord.Message) -> None:
     batcher.add(tenant, msg)
 
 
+@bot.event
+async def on_message_edit(_before: discord.Message, after: discord.Message) -> None:
+    """Judge edits too: otherwise a member posts a harmless line and edits it into whatever they wanted."""
+    if after.content != _before.content:
+        await on_message(after)
+
+
 async def act(guild: discord.Guild, m: discord.Message, d: Decision) -> None:
     tenant = tenant_of(guild.id)
     policy = service.policy(tenant)
     note = ""
+    # `timeout` times the author out and leaves the message; only `delete` removes it. They used to be the same
+    # branch, so a category set to timeout silently deleted as well, which the site does not promise.
     try:
-        if d.action in ("delete", "timeout"):
+        if d.action == "delete":
             await m.delete()
             note = "deleted"
-        if d.action == "timeout" and isinstance(m.author, discord.Member):
+        elif d.action == "timeout" and isinstance(m.author, discord.Member):
             await m.author.timeout(
                 timedelta(minutes=policy.timeout_minutes), reason=f"jevmod: {d.category} p={d.probability:.2f}"
             )
-            note = f"deleted, timed out {policy.timeout_minutes} min"
+            note = f"timed out {policy.timeout_minutes} min"
     except discord.Forbidden:
         note = "missing permissions to act"
-    if d.action in ("delete", "timeout") and "missing" not in note:
+    if note and "missing" not in note:
+        what = "was removed" if d.action == "delete" else f"led to a {policy.timeout_minutes} minute timeout for you"
         with contextlib.suppress(Exception):  # DMs closed
             await m.author.send(
-                f"Your message in **{guild.name}** #{m.channel} was removed by an automated moderation system "
-                f"(reason: {d.category}, confidence {d.probability:.0%}). If you think this was a mistake, contact the "
-                "server's moderators; they can review the decision and adjust the rules."
+                f"Your message in **{guild.name}** #{m.channel} {what} because an automated moderation system "
+                f"rated it {d.category} with confidence {d.probability:.0%}. If you think this was a mistake, contact "
+                "the server's moderators; they can review the decision and adjust the rules."
             )
     channel = await log_channel(guild, tenant)
     if channel:
@@ -133,9 +143,25 @@ async def log_channel(guild: discord.Guild, tenant: str) -> discord.TextChannel
         store.set_meta(tenant, log_channel=existing.id)
         return existing
     try:
+        # Channel overwrites beat guild-level permissions, so the bot needs an explicit one or it cannot read,
+        # post or react in the channel it just created, which breaks the log and the feedback reactions.
         overwrites: dict[discord.Role | discord.Member | discord.Object, discord.PermissionOverwrite] = {
-            guild.default_role: discord.PermissionOverwrite(read_messages=False)
+            guild.default_role: discord.PermissionOverwrite(read_messages=False),
+            guild.me: discord.PermissionOverwrite(
+                read_messages=True,
+                send_messages=True,
+                embed_links=True,
+                add_reactions=True,
+                read_message_history=True,
+            ),
         }
+        # Denying @everyone leaves the channel visible only to Administrators, so a plain Moderator role could
+        # not read the flags or use the reactions. Every role that can already moderate messages gets access.
+        for role in guild.roles:
+            if role.permissions.manage_messages or role.permissions.manage_guild:
+                overwrites[role] = discord.PermissionOverwrite(
+                    read_messages=True, send_messages=True, add_reactions=True, read_message_history=True
+                )
         ch = await guild.create_text_channel("jevmod-log", overwrites=overwrites, reason="jevmod decisions log")
         store.set_meta(tenant, log_channel=ch.id)
         return ch
@@ -149,8 +175,9 @@ async def _notify_quota_once(guild: discord.Guild, tenant: str) -> None:
     ch = await log_channel(guild, tenant)
     if ch:
         await ch.send(
-            f"jevmod paused for this month: the monthly quota of {FREE_MONTHLY:,} judged messages was reached "
-            "(JEVMOD_MONTHLY_QUOTA). Messages are not being judged until next month. Nothing is deleted while paused."
+            f"jevmod paused for this month: the {store.plan(tenant)} plan covers {store.quota_for(tenant):,} judged "
+            "messages. Messages are not being judged until next month. Nothing is deleted while paused."
+            + (" `/mod upgrade` lifts the limit." if store.plan(tenant) == "free" and _billing_enabled() else "")
         )
 
 
@@ -202,11 +229,8 @@ async def status(itx: discord.Interaction) -> None:
     lines = [f"**{c}**: {p.actions.get(c, 'off')} at p ≥ {p.thresholds.get(c, 0.9):.2f}" for c in CATEGORIES]
     lines += [f'**rule {n}**: {p.rule_actions.get(n, "flag")} · "{r}"' for n, r in p.rules.items()]
     plan = store.plan(tenant)
-    quota = (
-        f"{judged:,}/{FREE_MONTHLY:,} judged this month (quota)"
-        if plan == "free" and FREE_MONTHLY
-        else f"{judged:,} judged this month"
-    )
+    q = store.quota_for(tenant)
+    quota = f"{judged:,}/{q:,} judged this month ({plan})" if q else f"{judged:,} judged this month ({plan}, unlimited)"
     lines.append(f"\n{quota} · {requests} Jev requests · {tokens:,} tokens")
     await itx.response.send_message("\n".join(lines), ephemeral=True)
 
@@ -291,18 +315,52 @@ async def recent_cmd(itx: discord.Interaction) -> None:
         await itx.response.send_message("no decisions yet", ephemeral=True)
         return
     await itx.response.send_message(
-        "\n".join(f"`{r['category']} {r['p']:.2f} {r['action']}` {r['text'][:80]}" for r in rows), ephemeral=True
+        "\n".join(
+            f"`{r['category']} {r['p']:.2f} {r['action']}` {r['text'][:80] or 'message ' + str(r['message_id'])}"
+            for r in rows
+        ),
+        ephemeral=True,
     )
 
 
-@mod.command(name="forget", description="Delete everything jevmod stored about this server (GDPR)")
-async def forget_cmd(itx: discord.Interaction) -> None:
-    store.delete_tenant(tenant_of(itx.guild_id or 0))
+@mod.command(name="upgrade", description="Payment link for the Pro plan of this server, or the billing portal")
+async def upgrade_cmd(itx: discord.Interaction) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    if not _billing_enabled():
+        await itx.response.send_message(
+            "This copy of jevmod is self-hosted: there is nothing to pay. Raise JEVMOD_MONTHLY_QUOTA on the server.",
+            ephemeral=True,
+        )
+        return
+    from ..api.billing import checkout_url
+
+    plan = store.plan(tenant)
+    what = "manage or cancel the subscription" if plan != "free" else "upgrade this server to Pro"
     await itx.response.send_message(
-        "all settings, usage and decision logs for this server were deleted", ephemeral=True
+        f"Link to {what} (valid for this server only, opens Stripe): {checkout_url(tenant)}", ephemeral=True
     )
 
 
+def _billing_enabled() -> bool:
+    return bool(os.environ.get("STRIPE_PRICE_ID") and os.environ.get("JEVMOD_PUBLIC_URL"))
+
+
+@mod.command(name="forget", description="Delete everything jevmod stored about this server (GDPR)")
+async def forget_cmd(itx: discord.Interaction) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    # Deleting the local rows does not cancel anything at Stripe, so a paying owner would keep being charged
+    # with no record left here to explain it. Say so before deleting, and leave the portal link in reach.
+    paying = store.plan(tenant) != "free"
+    store.delete_tenant(tenant)
+    note = "all settings, usage and decision logs for this server were deleted"
+    if paying:
+        note += (
+            ". This did not cancel your Pro subscription: Stripe will keep charging the card until you cancel "
+            "it in Stripe's billing portal."
+        )
+    await itx.response.send_message(note, ephemeral=True)
+
+
 @mod.command(name="forget_user", description="Delete this member's entries from the decision log (erasure request)")
 async def forget_user_cmd(itx: discord.Interaction, member: discord.Member) -> None:
     n = store.delete_user(tenant_of(itx.guild_id or 0), str(member.id))

jevmod-0.2.1/jevmod/api/admin.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>jevmod admin</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="robots" content="noindex">
+<style>
+  body { margin: 0; background: #FAFAFA; color: #0A0A0A; font: 15px/1.5 Inter, system-ui, sans-serif; padding: 32px 16px; }
+  .wrap { max-width: 1100px; margin: 0 auto; }
+  h1 { font-size: 28px; margin: 0 0 4px; }
+  .sub { color: #3F3F46; margin: 0 0 32px; }
+  .figs { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 0;
+          border-top: 1px solid #D4D4D8; border-bottom: 1px solid #D4D4D8; margin-bottom: 32px; }
+  .figs div { padding: 20px 16px; border-right: 1px solid #E5E5E5; }
+  .figs b { display: block; font-size: 28px; font-weight: 700; }
+  .figs span { color: #71717A; font-size: 13px; }
+  table { width: 100%; border-collapse: collapse; font-size: 14px; }
+  th { text-align: left; color: #71717A; font-weight: 400; font-family: "IBM Plex Mono", monospace; font-size: 12px;
+       padding: 8px 12px; border-bottom: 1px solid #D4D4D8; }
+  td { padding: 10px 12px; border-bottom: 1px solid #E5E5E5; }
+  td.m { font-family: "IBM Plex Mono", monospace; font-size: 13px; }
+  td.n { font-variant-numeric: tabular-nums; }
+  select { border: 1px solid #D4D4D8; background: #fff; padding: 6px 8px; font: inherit; border-radius: 0; }
+  .ok { color: #16A34A; } .err { color: #DC2626; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>jevmod admin</h1>
+  <p class="sub">$month · plans $plans · quotas: free $free_quota, pro $pro_quota</p>
+  <div class="figs">
+    <div><b>$active</b><span>tenants with usage this month</span></div>
+    <div><b>$judged</b><span>judged messages</span></div>
+    <div><b>$$$usd</b><span>Jev spend, list price</span></div>
+    <div><b>$$$demo</b><span>demo spend this month</span></div>
+  </div>
+  <table>
+    <thead><tr><th>tenant</th><th>plan</th><th>judged / quota</th><th>tokens</th><th>subscription</th><th>set plan</th></tr></thead>
+    <tbody>$rows</tbody>
+  </table>
+  <p id="msg" class="sub" style="margin-top:16px"></p>
+</div>
+<script>
+  const TOKEN = new URLSearchParams(location.search).get("token") || "";
+  document.querySelectorAll("select[data-t]").forEach(s => s.addEventListener("change", async () => {
+    const r = await fetch("/admin/api/plan?token=" + encodeURIComponent(TOKEN), {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ tenant: s.dataset.t, plan: s.value })
+    });
+    const m = document.getElementById("msg");
+    m.className = r.ok ? "sub ok" : "sub err";
+    m.textContent = r.ok ? `$${s.dataset.t} -> $${s.value}` : `failed: $${r.status}`;
+  }));
+</script>
+</body>
+</html>

jevmod-0.2.1/jevmod/api/billing.py

@@ -0,0 +1,235 @@
+"""Hosted plans: Stripe Checkout, webhook and a small admin panel. Mounted by the `hosted` role next to the demo.
+
+    STRIPE_SECRET_KEY=sk_live_...  STRIPE_WEBHOOK_SECRET=whsec_...  STRIPE_PRICE_ID=price_...  JEVMOD_ADMIN_TOKEN=...
+    JEVMOD_PUBLIC_URL=https://jevmod.dev  jevmod hosted
+
+Flow: a server manager types `/mod upgrade` in Discord → the bot answers with
+`{PUBLIC_URL}/billing/checkout?tenant=discord:<guild>&sig=<hmac>` → Stripe Checkout (subscription, one price) →
+`checkout.session.completed` webhook → `Store.set_plan(tenant, "pro")` and the subscription row → the bot sees
+the new quota on its next batch. `customer.subscription.deleted` (or a non-active status on `updated`) puts the
+tenant back on `free`. The checkout link is signed so nobody can start a checkout for a guild they do not manage.
+
+Admin: `GET /admin` (HTML, Bearer token or `?token=`) lists tenants, plans, usage, subscriptions, demo spend,
+and lets the operator comp or revoke a plan. Everything the panel does is also JSON under `/admin/api/*`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import html
+import json
+import os
+import time
+from pathlib import Path
+from string import Template
+from typing import Any
+
+from fastapi import APIRouter, Header, HTTPException, Query, Request
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse
+
+from ..core import PLAN_QUOTAS, Store
+
+PUBLIC_URL = os.environ.get("JEVMOD_PUBLIC_URL", "https://jevmod.dev").rstrip("/")
+PRICE_ID = os.environ.get("STRIPE_PRICE_ID", "")
+JEV_USD_PER_M = 0.042
+PLANS = ("free", "pro", "unlimited")
+ADMIN_TEMPLATE = Template(Path(__file__).with_name("admin.html").read_text(encoding="utf-8"))
+
+
+def _secret(name: str) -> str:
+    return os.environ.get(name, "")
+
+
+def sign_tenant(tenant: str) -> str:
+    """HMAC over the tenant id with the admin token, so `/mod upgrade` links cannot be forged for another guild.
+
+    There is deliberately no default key: with a constant fallback anyone could compute a valid signature for any
+    guild id and open that owner's Stripe portal, which lists their invoices and can cancel their subscription."""
+    key = _secret("JEVMOD_ADMIN_TOKEN")
+    if not key:
+        raise RuntimeError("JEVMOD_ADMIN_TOKEN must be set to sign billing links")
+    return hmac.new(key.encode(), tenant.encode(), hashlib.sha256).hexdigest()[:24]
+
+
+def checkout_url(tenant: str) -> str:
+    return f"{PUBLIC_URL}/billing/checkout?tenant={tenant}&sig={sign_tenant(tenant)}"
+
+
+def make_router(store: Store, demo_spend: Any = None) -> APIRouter:
+    r = APIRouter()
+
+    # ------------------------------------------------------------------ Stripe
+    def stripe_client() -> Any:
+        import stripe
+
+        key = _secret("STRIPE_SECRET_KEY")
+        if not key:
+            raise HTTPException(503, "billing is not configured on this server")
+        stripe.api_key = key
+        return stripe
+
+    @r.get("/billing/checkout")
+    def checkout(tenant: str = Query(..., min_length=3, max_length=80), sig: str = Query(..., min_length=8)) -> Any:
+        if not hmac.compare_digest(sig, sign_tenant(tenant)):
+            raise HTTPException(403, "invalid link; ask for a new one with /mod upgrade")
+        if not PRICE_ID:
+            raise HTTPException(503, "billing is not configured on this server")
+        if store.plan(tenant) != "free":
+            return RedirectResponse(f"{PUBLIC_URL}/billing/portal?tenant={tenant}&sig={sig}", status_code=303)
+        stripe = stripe_client()
+        session = stripe.checkout.Session.create(
+            mode="subscription",
+            line_items=[{"price": PRICE_ID, "quantity": 1}],
+            client_reference_id=tenant,
+            metadata={"tenant": tenant},
+            subscription_data={"metadata": {"tenant": tenant}},
+            success_url=f"{PUBLIC_URL}/thanks.html",
+            cancel_url=f"{PUBLIC_URL}/cancelled.html",
+            allow_promotion_codes=True,
+        )
+        return RedirectResponse(session.url, status_code=303)
+
+    @r.get("/billing/portal")
+    def portal(tenant: str = Query(...), sig: str = Query(...)) -> Any:
+        if not hmac.compare_digest(sig, sign_tenant(tenant)):
+            raise HTTPException(403, "invalid link")
+        sub = store.subscription(tenant)
+        if not sub or not sub.get("customer_id"):
+            raise HTTPException(404, "no subscription for this server")
+        stripe = stripe_client()
+        ps = stripe.billing_portal.Session.create(customer=sub["customer_id"], return_url=f"{PUBLIC_URL}/")
+        return RedirectResponse(ps.url, status_code=303)
+
+    @r.post("/billing/stripe/webhook")
+    async def webhook(request: Request, stripe_signature: str = Header(default="", alias="Stripe-Signature")) -> Any:
+        secret = _secret("STRIPE_WEBHOOK_SECRET")
+        if not secret:
+            raise HTTPException(503, "webhook secret not configured")
+        payload = await request.body()
+        event = verify_stripe_signature(payload, stripe_signature, secret)
+        kind = event.get("type", "")
+        obj = event.get("data", {}).get("object", {})
+        if kind == "checkout.session.completed":
+            tenant = obj.get("client_reference_id") or (obj.get("metadata") or {}).get("tenant")
+            if tenant:
+                store.set_plan(tenant, "pro")
+                store.set_subscription(
+                    tenant,
+                    customer_id=obj.get("customer"),
+                    subscription_id=obj.get("subscription"),
+                    price_id=PRICE_ID or None,
+                    status="active",
+                    current_period_end=None,
+                )
+        elif kind in ("customer.subscription.updated", "customer.subscription.deleted"):
+            sub_id = obj.get("id")
+            tenant = (obj.get("metadata") or {}).get("tenant") or (
+                store.tenant_for_subscription(sub_id) if sub_id else None
+            )
+            if tenant:
+                status = "canceled" if kind.endswith("deleted") else str(obj.get("status", ""))
+                # past_due keeps Pro: Stripe is still retrying the card, and Stripe moves the subscription
+                # to `unpaid` or `canceled` when it gives up, which is where access actually ends.
+                active = status in ("active", "trialing", "past_due")
+                store.set_plan(tenant, "pro" if active else "free")
+                item = ((obj.get("items") or {}).get("data") or [{}])[0]
+                store.set_subscription(
+                    tenant,
+                    customer_id=obj.get("customer"),
+                    subscription_id=sub_id,
+                    price_id=(item.get("price") or {}).get("id") or PRICE_ID or None,
+                    status=status,
+                    current_period_end=obj.get("current_period_end") or item.get("current_period_end"),
+                )
+        return {"received": True}
+
+    # ------------------------------------------------------------------ admin
+    def admin(authorization: str, token: str) -> None:
+        want = _secret("JEVMOD_ADMIN_TOKEN")
+        given = authorization[7:].strip() if authorization.startswith("Bearer ") else token
+        if not want or not hmac.compare_digest(given, want):
+            raise HTTPException(403, "admin token required")
+
+    @r.get("/admin/api/tenants")
+    def api_tenants(authorization: str = Header(default=""), token: str = "") -> list[dict[str, Any]]:
+        admin(authorization, token)
+        return store.tenants_overview()
+
+    @r.get("/admin/api/totals")
+    def api_totals(authorization: str = Header(default=""), token: str = "") -> dict[str, Any]:
+        admin(authorization, token)
+        t = store.totals()
+        t["usd"] = round(t["tokens"] * JEV_USD_PER_M / 1e6, 4)
+        if demo_spend is not None:
+            t["demo_spent_usd"] = round(demo_spend(), 4)
+        t["quotas"] = {"free": store.monthly_quota, **{k: v for k, v in PLAN_QUOTAS.items() if k != "free"}}
+        return t
+
+    @r.post("/admin/api/plan")
+    def api_plan(body: dict[str, str], authorization: str = Header(default=""), token: str = "") -> dict[str, str]:
+        admin(authorization, token)
+        tenant, plan = body.get("tenant", ""), body.get("plan", "")
+        if plan not in PLANS or not tenant:
+            raise HTTPException(422, f"plan must be one of {PLANS}")
+        store.set_plan(tenant, plan)
+        return {"tenant": tenant, "plan": plan}
+
+    @r.get("/admin", response_class=HTMLResponse)
+    def panel(authorization: str = Header(default=""), token: str = "") -> str:
+        admin(authorization, token)
+        rows = store.tenants_overview()
+        totals = store.totals()
+        tr = []
+        for x in rows:
+            quota = "unlimited" if not x["quota"] else f"{x['quota']:,}"
+            end = time.strftime("%Y-%m-%d", time.gmtime(x["current_period_end"])) if x["current_period_end"] else ""
+            opts = "".join(f'<option value="{p}"{" selected" if p == x["plan"] else ""}>{p}</option>' for p in PLANS)
+            t = html.escape(x["tenant"])
+            tr.append(
+                f"<tr><td class=m>{t}</td><td>{x['plan']}</td><td class=n>{x['judged']:,} / {quota}</td>"
+                f"<td class=n>{x['tokens']:,}</td><td>{html.escape(str(x['subscription_status'] or ''))} {end}</td>"
+                f'<td><select data-t="{t}">{opts}</select></td></tr>'
+            )
+        return ADMIN_TEMPLATE.substitute(
+            month=totals["month"],
+            plans=html.escape(json.dumps(totals["plans"])),
+            free_quota=store.monthly_quota or "unlimited",
+            pro_quota=PLAN_QUOTAS.get("pro") or "unlimited",
+            active=totals["active_tenants"],
+            judged=f"{totals['judged']:,}",
+            usd=f"{totals['tokens'] * JEV_USD_PER_M / 1e6:.4f}",
+            demo=f"{demo_spend():.4f}" if demo_spend is not None else "n/a",
+            rows="".join(tr) or '<tr><td colspan=6 style="color:#71717A">no tenants yet</td></tr>',
+        )
+
+    return r
+
+
+def verify_stripe_signature(payload: bytes, header: str, secret: str, tolerance_s: int = 300) -> dict[str, Any]:
+    """Stripe's scheme: header `t=<ts>,v1=<hmac>`; hmac = HMAC-SHA256(secret, f"{ts}.{payload}")."""
+    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
+    ts = parts.get("t", "")
+    sigs = [v for k, v in (kv.split("=", 1) for kv in header.split(",") if "=" in kv) if k == "v1"]
+    if not ts or not sigs:
+        raise HTTPException(400, "bad signature header")
+    expected = hmac.new(secret.encode(), f"{ts}.{payload.decode()}".encode(), hashlib.sha256).hexdigest()
+    if not any(hmac.compare_digest(expected, s) for s in sigs):
+        raise HTTPException(400, "signature mismatch")
+    if abs(time.time() - int(ts)) > tolerance_s:
+        raise HTTPException(400, "timestamp outside tolerance")
+    try:
+        return json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise HTTPException(400, "bad json") from exc
+
+
+def sign_for_test(payload: bytes, secret: str, ts: int | None = None) -> str:
+    """Build a Stripe-Signature header the way Stripe does (used by tests and the local smoke script)."""
+    ts = ts or int(time.time())
+    sig = hmac.new(secret.encode(), f"{ts}.{payload.decode()}".encode(), hashlib.sha256).hexdigest()
+    return f"t={ts},v1={sig}"
+
+
+def json_error(status: int, detail: str) -> JSONResponse:
+    return JSONResponse({"detail": detail}, status_code=status)