Username access, web dashboard and coach chat

.env.example

@@ -11,12 +11,31 @@ TELEGRAM_BOT_TOKEN=
 # Generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))"
 TELEGRAM_WEBHOOK_SECRET=
 
-# Comma-separated Telegram numeric user IDs allowed to use the bot.
-# Leave EMPTY to allow nobody (safe default -- the bot replies with a refusal
-# and tells the sender their id, so you can read your own id off the reply).
-# Ignored when OPEN_ACCESS=true.
+# Comma-separated Telegram @handles allowed to use the bot, with or without the
+# @. This is the friendly way to configure access.
+#
+# Handles are matched case-insensitively. Note they are MUTABLE and can be
+# recycled to a different person, so they gate access only -- your ledger is
+# keyed on Telegram's immutable numeric id, which means renaming your handle
+# never loses your history.
+#
+# Leave both lists EMPTY to allow nobody (safe default). Ignored when
+# OPEN_ACCESS=true.
+ALLOWED_TELEGRAM_USERNAMES=
+
+# Numeric ids still work, and are the only option for users who have not set a
+# @username at all.
 ALLOWED_TELEGRAM_USER_IDS=
 
+# --- Web dashboard ---------------------------------------------------------
+# Public origin used to build /dashboard sign-in links. Derived from SPACE_HOST
+# on a Space; set explicitly when self-hosting.
+PUBLIC_BASE_URL=
+
+# How long a dashboard link stays valid. Short on purpose: the token rides in
+# the URL, and URLs end up in history, referrers and screenshots.
+DASHBOARD_LINK_MINUTES=30
+
 # Let ANYONE on Telegram use the bot. Each user gets their own isolated ledger,
 # so this makes the bot multi-tenant -- it does NOT expose your spending to
 # other people. What it does expose is your wallet: every stranger's receipt

README.md

@@ -102,7 +102,10 @@ they stay out of your shell history):
 | `TELEGRAM_WEBHOOK_SECRET` | ✅ | Any random string; rejects forged webhook calls |
 | `HF_DATASET_REPO` | ✅ | `<you>/finbot-data` — **without this your data is lost on restart** |
 | `HF_TOKEN` | ✅ | **Write**-scoped token. Needed to mirror the ledger; also used for remote inference if you pick that backend |
-| `ALLOWED_TELEGRAM_USER_IDS` | ✅ | Your numeric Telegram ID (comma-separated for more). Not needed if `OPEN_ACCESS=true` |
+| `ALLOWED_TELEGRAM_USERNAMES` | ✅ | Your Telegram @handle (comma-separated for more). Not needed if `OPEN_ACCESS=true` |
+| `ALLOWED_TELEGRAM_USER_IDS` | | Numeric IDs — the only option for users with no @handle set |
+| `PUBLIC_BASE_URL` | | Origin for dashboard links. Derived from `SPACE_HOST` on a Space |
+| `DASHBOARD_LINK_MINUTES` | | Sign-in link lifetime. Default `30` |
 | `OPEN_ACCESS` | | `true` lets anyone use the bot, each with their own ledger. Default `false` |
 | `UPLOADS_PER_USER_PER_DAY` | | Caps model-backed uploads per user. Default `20`, `0` disables |
 | `LLM_BACKEND` | | `auto` (default), `local`, `remote`, `off`. See below |

app.py

@@ -38,6 +38,7 @@ from finbot.advice import Advisor
 from finbot.analytics import today_in
 from finbot.backend import make_llm
 from finbot.config import get_settings
+from finbot.dashboard import build_ui
 from finbot.features import default_features
 from finbot.features.base import Attachment, BotContext, Services
 from finbot.ingest import Ingestor
@@ -74,8 +75,14 @@ class Runtime:
     limiter: RateLimiter
 
 
+#: Set by build_runtime so the Gradio UI, which is constructed at import time,
+#: can reach the services once they exist.
+_runtime: Optional["Runtime"] = None
+
+
 def build_runtime() -> Runtime:
     """Synchronous construction, so it works from any startup path."""
+    global _runtime
     settings = get_settings()
     registry = FeatureRegistry()
     llm = make_llm(settings)
@@ -100,12 +107,13 @@ def build_runtime() -> Runtime:
             settings.uploads_per_user_per_day or "unlimited",
         )
 
-    return Runtime(
+    _runtime = Runtime(
         services=services,
         telegram=TelegramClient(settings.telegram_bot_token),
         seen=SeenUpdates(),
         limiter=RateLimiter(settings.uploads_per_user_per_day),
     )
+    return _runtime
 
 
 def space_webhook_url() -> str:
@@ -279,17 +287,32 @@ async def handle_update(rt: Runtime, parsed: ParsedUpdate) -> None:
     telegram = rt.telegram
     settings = services.settings
 
-    if not settings.is_authorised(parsed.user_id):
-        log.warning("Unauthorised user %s attempted access", parsed.user_id)
+    if not settings.is_authorised(parsed.user_id, parsed.username):
+        log.warning(
+            "Unauthorised access attempt from %s (@%s)",
+            parsed.user_id,
+            parsed.username or "no-handle",
+        )
+        who = (
+            f"@{parsed.username}"
+            if parsed.username
+            else f"id <code>{parsed.user_id}</code> (you have no @username set)"
+        )
         await telegram.send_message(
             parsed.chat_id,
             "This is a private bot and you're not on its allowlist.\n\n"
-            f"If it's yours, add <code>{parsed.user_id}</code> to "
-            "<code>ALLOWED_TELEGRAM_USER_IDS</code> in the Space secrets "
+            f"If it's yours, add {who} to "
+            "<code>ALLOWED_TELEGRAM_USERNAMES</code> in the Space secrets "
             "and restart it.",
         )
         return
 
+    # Refresh the handle registry on every message, so a rename is picked up
+    # without anything else needing to change.
+    await run_in_threadpool(
+        services.store.record_user, parsed.user_id, parsed.username, parsed.first_name
+    )
+
     try:
         attachment = None
         if parsed.has_file:
@@ -327,6 +350,7 @@ async def handle_update(rt: Runtime, parsed: ParsedUpdate) -> None:
             chat_id=parsed.chat_id,
             services=services,
             today=today_in(settings.timezone),
+            username=parsed.username,
             text=parsed.text or parsed.caption,
             command=parsed.command,
             args=parsed.args,
@@ -370,43 +394,16 @@ async def handle_update(rt: Runtime, parsed: ParsedUpdate) -> None:
 # ----------------------------------------------------------------- gradio UI
 
 
-def build_ui() -> gr.Blocks:
-    """The Space's visible page.
+def _get_services() -> Optional[Services]:
+    """Late-bound accessor for the dashboard.
 
-    Deliberately stateless: this Space is public, and transaction counts,
-    configuration gaps and sync state are personal operational detail. The
-    owner reads those over Telegram via /status, or from /admin/diagnostics
-    behind the webhook secret.
+    The UI object is built at import time, before any runtime exists, so it
+    reaches for services through this rather than capturing them.
     """
-    with gr.Blocks(title="Oracle") as demo:
-        gr.Markdown(
-            f"""
-            # 💸 Oracle
-
-            An expense-tracking and budget-coaching bot. **It runs on Telegram** —
-            there is nothing to operate on this page.
-
-            Tell it what you spent (`coffee 250`), send it a receipt photo, or
-            forward a bank statement as PDF/CSV/XLSX. Ask it `/month`,
-            `/recurring` or `/advice`.
-
-            Each Telegram user gets their own separate ledger.
-
-            <sub>Built with <code>coco-finbot</code> v{__version__}.</sub>
-            """
-        )
-
-        # Hidden, but real: binding a @spaces.GPU function into the Gradio app
-        # is how ZeroGPU discovers that this Space uses its GPU. It warms the
-        # model cache rather than doing nothing.
-        with gr.Row(visible=False):
-            warm_in = gr.Textbox(label="model")
-            warm_out = gr.Textbox(label="status")
-            gr.Button("warm").click(local_llm.warmup, warm_in, warm_out)
-    return demo
+    return _runtime.services if _runtime is not None else None
 
 
-demo = build_ui()
+demo = build_ui(_get_services, local_llm.warmup)
 
 
 # ------------------------------------------------------------------- wiring

finbot/auth.py

@@ -0,0 +1,108 @@
+"""Signed, expiring tokens for the web dashboard.
+
+The Space is public, so the dashboard cannot simply trust a user id in a query
+string -- anyone could type someone else's. Instead the bot issues a token in
+Telegram (where identity is already established) and the page verifies it.
+
+Signed with ``TELEGRAM_WEBHOOK_SECRET``, so there is no additional secret to
+manage or leak. Tokens are short-lived because a URL leaks easily: browser
+history, referrer headers, a screenshot in a chat.
+
+Nothing here can mutate the ledger. A stolen token, within its window, exposes
+one person's spending summary and coach chat -- bad, but bounded, and the
+window is minutes.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import NamedTuple, Optional
+
+#: Long enough to open the link and read it, short enough that a leaked URL in
+#: browser history is stale by the time anyone finds it.
+DEFAULT_TTL_SECONDS = 30 * 60
+
+_SIG_BYTES = 16
+
+
+class TokenError(ValueError):
+    """The token was malformed, tampered with, or expired."""
+
+
+class Claims(NamedTuple):
+    user_id: int
+    expires_at: int
+
+    @property
+    def seconds_left(self) -> int:
+        return max(0, self.expires_at - int(time.time()))
+
+
+def _b64encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _b64decode(text: str) -> bytes:
+    padding = "=" * (-len(text) % 4)
+    return base64.urlsafe_b64decode(text + padding)
+
+
+def _sign(payload: bytes, secret: str) -> bytes:
+    return hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).digest()[
+        :_SIG_BYTES
+    ]
+
+
+def issue(
+    user_id: int,
+    secret: str,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    now: Optional[int] = None,
+) -> str:
+    """Mint a dashboard token for ``user_id``."""
+    if not secret:
+        raise TokenError("cannot issue tokens without a signing secret")
+
+    now = now if now is not None else int(time.time())
+    payload = f"{int(user_id)}.{now + int(ttl_seconds)}".encode("utf-8")
+    return f"{_b64encode(payload)}.{_b64encode(_sign(payload, secret))}"
+
+
+def verify(token: str, secret: str, now: Optional[int] = None) -> Claims:
+    """Validate a token and return its claims, or raise :class:`TokenError`."""
+    if not secret:
+        raise TokenError("no signing secret configured")
+    if not token or "." not in token:
+        raise TokenError("malformed token")
+
+    encoded_payload, _, encoded_sig = token.rpartition(".")
+    try:
+        payload = _b64decode(encoded_payload)
+        signature = _b64decode(encoded_sig)
+    except Exception as exc:
+        raise TokenError("malformed token") from exc
+
+    # Constant-time: a timing-variable comparison would leak the signature
+    # byte by byte to anyone willing to measure.
+    if not hmac.compare_digest(signature, _sign(payload, secret)):
+        raise TokenError("bad signature")
+
+    try:
+        user_part, _, expiry_part = payload.decode("utf-8").partition(".")
+        claims = Claims(user_id=int(user_part), expires_at=int(expiry_part))
+    except Exception as exc:
+        raise TokenError("malformed payload") from exc
+
+    now = now if now is not None else int(time.time())
+    if claims.expires_at < now:
+        raise TokenError("token expired")
+
+    return claims
+
+
+def dashboard_url(base_url: str, token: str) -> str:
+    base = (base_url or "").rstrip("/")
+    return f"{base}/?t={token}"

finbot/config.py

@@ -9,6 +9,7 @@ what it is missing.
 
 from __future__ import annotations
 
+import os
 from functools import lru_cache
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -23,6 +24,11 @@ class Settings(BaseSettings):
     telegram_bot_token: str = ""
     telegram_webhook_secret: str = ""
     allowed_telegram_user_ids: str = ""
+    #: Comma-separated @handles, with or without the @. Friendlier to configure
+    #: than numeric ids, but note that handles are mutable and recyclable, so
+    #: they gate *access* only -- the ledger itself is keyed on the immutable
+    #: numeric id (see finbot.store).
+    allowed_telegram_usernames: str = ""
     #: Let anyone message the bot. Each Telegram user still gets their own
     #: isolated ledger -- open access makes this multi-tenant, it does not
     #: expose one user's spending to another. It does mean strangers spend the
@@ -60,6 +66,18 @@ class Settings(BaseSettings):
     # --- Behaviour ---
     default_currency: str = "INR"
     timezone: str = "Asia/Kolkata"
+    #: Public origin for dashboard links. Derived from SPACE_HOST when unset.
+    public_base_url: str = ""
+    #: How long a dashboard link stays usable, in minutes.
+    dashboard_link_minutes: int = 30
+
+    @property
+    def base_url(self) -> str:
+        if self.public_base_url:
+            return self.public_base_url.rstrip("/")
+        if host := os.environ.get("SPACE_HOST"):
+            return f"https://{host.rstrip('/')}"
+        return ""
 
     @property
     def allowed_user_ids(self) -> frozenset[int]:
@@ -80,8 +98,22 @@ class Settings(BaseSettings):
                 continue
         return frozenset(ids)
 
-    def is_authorised(self, user_id: int) -> bool:
-        return self.open_access or user_id in self.allowed_user_ids
+    @property
+    def allowed_usernames(self) -> frozenset[str]:
+        """Lower-cased handles without the leading @."""
+        handles: set[str] = set()
+        for chunk in self.allowed_telegram_usernames.split(","):
+            handle = chunk.strip().lstrip("@").lower()
+            if handle:
+                handles.add(handle)
+        return frozenset(handles)
+
+    def is_authorised(self, user_id: int, username: str = "") -> bool:
+        if self.open_access:
+            return True
+        if user_id in self.allowed_user_ids:
+            return True
+        return bool(username) and username.strip().lstrip("@").lower() in self.allowed_usernames
 
     @property
     def llm_enabled(self) -> bool:
@@ -98,8 +130,10 @@ class Settings(BaseSettings):
             gaps.append("TELEGRAM_BOT_TOKEN (bot cannot send or receive)")
         if not self.telegram_webhook_secret:
             gaps.append("TELEGRAM_WEBHOOK_SECRET (webhook cannot be verified)")
-        if not self.open_access and not self.allowed_user_ids:
-            gaps.append("ALLOWED_TELEGRAM_USER_IDS (nobody is authorised yet)")
+        if not self.open_access and not self.allowed_user_ids and not self.allowed_usernames:
+            gaps.append(
+                "ALLOWED_TELEGRAM_USERNAMES (nobody is authorised yet)"
+            )
         if not self.hf_dataset_repo:
             gaps.append("HF_DATASET_REPO (data will be lost when the Space restarts)")
         if not self.hf_token:

finbot/dashboard.py

@@ -0,0 +1,408 @@
+"""The web dashboard and coach chat.
+
+Served at ``/`` by Gradio. The Space is public, so **nothing renders without a
+valid signed token** -- a visitor with no token sees only an explanation of what
+the bot is. Tokens are minted by ``/dashboard`` in Telegram, where identity is
+already established (see :mod:`finbot.auth`).
+
+Data assembly is separated from rendering so the numbers can be tested without
+standing up a browser.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any, Callable, Optional
+
+import gradio as gr
+
+from .analytics import (
+    BudgetStatus,
+    Recurring,
+    budget_status,
+    by_category,
+    detect_recurring,
+    dominant_currency,
+    month_bounds,
+    previous_month_bounds,
+    project_month_end,
+    today_in,
+    total_minor,
+)
+from .auth import TokenError, verify
+from .categories import label as category_label
+from .models import Expense
+from .money import format_money, from_minor
+
+log = logging.getLogger(__name__)
+
+RECENT_LIMIT = 25
+
+
+@dataclass
+class DashboardData:
+    display_name: str = ""
+    currency: str = "INR"
+    today: date = field(default_factory=date.today)
+    month_total: int = 0
+    month_count: int = 0
+    last_month_total: int = 0
+    projected: int = 0
+    by_category: list[tuple[str, int]] = field(default_factory=list)
+    recent: list[Expense] = field(default_factory=list)
+    budgets: list[BudgetStatus] = field(default_factory=list)
+    recurring: list[Recurring] = field(default_factory=list)
+
+    @property
+    def delta_pct(self) -> Optional[float]:
+        if not self.last_month_total:
+            return None
+        return (self.month_total - self.last_month_total) / self.last_month_total * 100
+
+
+def load_dashboard(services: Any, user_id: int) -> DashboardData:
+    """Gather everything the page shows, for one user."""
+    store = services.store
+    settings = services.settings
+    today = today_in(settings.timezone)
+
+    start, _ = month_bounds(today)
+    month = store.list_expenses(user_id, start, today)
+
+    prev_start, prev_end = previous_month_bounds(today)
+    # Same elapsed slice, so the comparison is like-for-like.
+    clipped = min(prev_end, prev_start + (today - start))
+    previous = store.list_expenses(user_id, prev_start, clipped)
+
+    everything = store.list_expenses(user_id)
+    currency = dominant_currency(month or everything, settings.default_currency)
+
+    scoped = [e for e in month if e.currency.upper() == currency]
+
+    return DashboardData(
+        display_name=store.display_name_for(user_id),
+        currency=currency,
+        today=today,
+        month_total=total_minor(scoped),
+        month_count=len(scoped),
+        last_month_total=total_minor(
+            [e for e in previous if e.currency.upper() == currency]
+        ),
+        projected=project_month_end(scoped, today),
+        by_category=by_category(scoped),
+        recent=store.list_expenses(user_id, limit=RECENT_LIMIT),
+        budgets=budget_status(store.get_budgets(user_id), month),
+        recurring=detect_recurring(everything),
+    )
+
+
+# ------------------------------------------------------------------ rendering
+
+
+def render_header(data: DashboardData) -> str:
+    return (
+        f"### {data.display_name}\n"
+        f"{data.today.strftime('%B %Y')} · showing {data.currency}"
+    )
+
+
+def render_kpis(data: DashboardData) -> str:
+    if not data.month_count:
+        return (
+            "**Nothing logged this month yet.**\n\n"
+            "Send the bot something like `coffee 250` on Telegram and it will "
+            "appear here."
+        )
+
+    lines = [
+        f"**{format_money(data.month_total, data.currency)}** "
+        f"this month · {data.month_count} transactions",
+    ]
+
+    if (delta := data.delta_pct) is not None:
+        arrow = "▲" if delta > 0 else "▼"
+        lines.append(
+            f"{arrow} {abs(delta):.0f}% vs the same point last month "
+            f"({format_money(data.last_month_total, data.currency)})"
+        )
+
+    lines.append(
+        f"Projected month end: **{format_money(data.projected, data.currency)}**"
+    )
+
+    if data.by_category:
+        name, amount = data.by_category[0]
+        share = amount / data.month_total * 100 if data.month_total else 0
+        lines.append(
+            f"Biggest category: **{category_label(name)}** "
+            f"({format_money(amount, data.currency)}, {share:.0f}%)"
+        )
+
+    return "\n\n".join(lines)
+
+
+def category_frame(data: DashboardData):
+    import pandas as pd
+
+    rows = [
+        {
+            "Category": category_label(name),
+            "Amount": round(from_minor(amount, data.currency), 2),
+        }
+        for name, amount in data.by_category[:10]
+    ]
+    return pd.DataFrame(rows or [{"Category": "—", "Amount": 0.0}])
+
+
+def recent_frame(data: DashboardData):
+    import pandas as pd
+
+    rows = [
+        {
+            "Date": e.occurred_on.isoformat(),
+            "Amount": format_money(e.amount_minor, e.currency),
+            "Description": (e.merchant or e.description or "")[:48],
+            "Category": category_label(e.category),
+        }
+        for e in data.recent
+    ]
+    return pd.DataFrame(
+        rows or [{"Date": "—", "Amount": "—", "Description": "Nothing yet", "Category": "—"}]
+    )
+
+
+def render_budgets(data: DashboardData) -> str:
+    if not data.budgets:
+        return "**Budgets**\n\nNone set. Send `/budget groceries 12000` on Telegram."
+
+    lines = ["**Budgets**", ""]
+    for status in data.budgets:
+        mark = "🔴" if status.over else ("🟡" if status.pct >= 80 else "🟢")
+        lines.append(
+            f"{mark} {category_label(status.category)} — "
+            f"{format_money(status.spent_minor, status.currency)} of "
+            f"{format_money(status.limit_minor, status.currency)} "
+            f"({status.pct:.0f}%)"
+        )
+    return "\n".join(lines)
+
+
+def render_recurring(data: DashboardData) -> str:
+    if not data.recurring:
+        return (
+            "**Recurring**\n\nNothing detected yet — this needs a few months of "
+            "history to spot a pattern."
+        )
+
+    lines = ["**Recurring**", ""]
+    for item in data.recurring[:8]:
+        lines.append(
+            f"• {format_money(item.typical_minor, item.currency)}/mo — {item.label} "
+            f"_(seen in {item.months} months)_"
+        )
+    annual = sum(r.annualised_minor for r in data.recurring if r.currency == data.currency)
+    if annual:
+        lines.append("")
+        lines.append(f"≈ **{format_money(annual, data.currency)}/year** if all continue.")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------- coach
+
+
+def coach_reply(services: Any, user_id: int, question: str) -> str:
+    """One coach turn, grounded in this user's own numbers."""
+    store = services.store
+    settings = services.settings
+    today = today_in(settings.timezone)
+
+    start, _ = month_bounds(today)
+    this_month = store.list_expenses(user_id, start, today)
+    prev_start, prev_end = previous_month_bounds(today)
+    last_month = store.list_expenses(user_id, prev_start, prev_end)
+    everything = store.list_expenses(user_id)
+
+    return services.advisor.advise(
+        expenses_this_month=this_month,
+        expenses_last_month=last_month,
+        recurring=detect_recurring(everything),
+        budgets=budget_status(store.get_budgets(user_id), this_month),
+        default_currency=settings.default_currency,
+        today=today,
+        question=question or None,
+    )
+
+
+# ------------------------------------------------------------------- the page
+
+_LANDING = """
+# 💸 Oracle
+
+An expense-tracking and budget-coaching bot that lives on **Telegram**.
+
+Tell it what you spent (`coffee 250`), send a receipt photo, or forward a bank
+statement as PDF/CSV/XLSX. Then ask it `/month`, `/recurring` or `/advice`.
+
+To see this dashboard, send **`/dashboard`** to the bot — it will send you a
+private sign-in link.
+"""
+
+_EXPIRED = """
+### Link expired or invalid
+
+Dashboard links are short-lived on purpose. Send **`/dashboard`** to the bot
+again for a fresh one.
+"""
+
+
+def build_ui(
+    get_services: Callable[[], Optional[Any]],
+    gpu_probe: Optional[Callable[..., str]] = None,
+) -> gr.Blocks:
+    """Assemble the page.
+
+    ``get_services`` is a callable rather than a value because the UI object is
+    built at import time, before the runtime exists.
+    """
+
+    def _authenticate(request: gr.Request) -> Optional[int]:
+        services = get_services()
+        if services is None:
+            return None
+        token = (request.query_params or {}).get("t", "")
+        if not token:
+            return None
+        try:
+            return verify(token, services.settings.telegram_webhook_secret).user_id
+        except TokenError as exc:
+            log.info("Rejected dashboard token: %s", exc)
+            return None
+
+    def on_load(request: gr.Request):
+        user_id = _authenticate(request)
+        has_token = bool((request.query_params or {}).get("t"))
+
+        if user_id is None:
+            return (
+                None,
+                gr.update(visible=True, value=_EXPIRED if has_token else _LANDING),
+                gr.update(visible=False),
+                "", "", None, None, "", "",
+            )
+
+        return (user_id, gr.update(visible=False), gr.update(visible=True), *_panels(user_id))
+
+    def _panels(user_id: int):
+        services = get_services()
+        data = load_dashboard(services, user_id)
+        return (
+            render_header(data),
+            render_kpis(data),
+            category_frame(data),
+            recent_frame(data),
+            render_budgets(data),
+            render_recurring(data),
+        )
+
+    def on_refresh(user_id):
+        if not user_id:
+            return "", "", None, None, "", ""
+        return _panels(int(user_id))
+
+    def on_chat(message: str, history: list, user_id):
+        history = list(history or [])
+        if not message or not message.strip():
+            return history, ""
+        if not user_id:
+            history.append({"role": "user", "content": message})
+            history.append(
+                {
+                    "role": "assistant",
+                    "content": "Your session expired. Send /dashboard to the bot again.",
+                }
+            )
+            return history, ""
+
+        history.append({"role": "user", "content": message})
+        try:
+            answer = coach_reply(get_services(), int(user_id), message.strip())
+        except Exception:
+            log.exception("Coach reply failed")
+            answer = "Something went wrong working that out. Try again in a moment."
+        history.append({"role": "assistant", "content": answer})
+        return history, ""
+
+    with gr.Blocks(title="Oracle", fill_height=True) as demo:
+        user_state = gr.State(None)
+
+        landing = gr.Markdown(_LANDING, visible=True)
+
+        with gr.Column(visible=False) as panel:
+            header = gr.Markdown()
+
+            with gr.Row():
+                with gr.Column(scale=3):
+                    kpis = gr.Markdown()
+                    chart = gr.BarPlot(
+                        x="Category",
+                        y="Amount",
+                        title="Where it went this month",
+                        height=280,
+                    )
+                    recent = gr.Dataframe(
+                        headers=["Date", "Amount", "Description", "Category"],
+                        interactive=False,
+                        wrap=True,
+                        label="Recent transactions",
+                    )
+                    with gr.Row():
+                        budgets_md = gr.Markdown()
+                        recurring_md = gr.Markdown()
+                    refresh = gr.Button("Refresh", size="sm")
+
+                with gr.Column(scale=2):
+                    gr.Markdown("### 🧭 Coach")
+                    chat = gr.Chatbot(
+                        type="messages",
+                        height=460,
+                        show_label=False,
+                        # Model output is rendered as text, never markup.
+                        allow_tags=False,
+                        placeholder=(
+                            "Ask about your own spending — "
+                            "\"what changed this month?\", \"where can I cut back?\""
+                        ),
+                    )
+                    question = gr.Textbox(
+                        placeholder="Ask about your spending…",
+                        show_label=False,
+                        submit_btn=True,
+                    )
+                    gr.Markdown(
+                        "<sub>Budgeting observations from your own logged data. "
+                        "Not financial advice.</sub>"
+                    )
+
+        # Hidden: binding a @spaces.GPU function into the app graph is how
+        # ZeroGPU discovers this Space uses its GPU.
+        if gpu_probe is not None:
+            with gr.Row(visible=False):
+                warm_in = gr.Textbox(label="model")
+                warm_out = gr.Textbox(label="status")
+                gr.Button("warm").click(gpu_probe, warm_in, warm_out)
+
+        panel_outputs = [header, kpis, chart, recent, budgets_md, recurring_md]
+
+        demo.load(
+            on_load,
+            inputs=None,
+            outputs=[user_state, landing, panel, *panel_outputs],
+        )
+        refresh.click(on_refresh, inputs=user_state, outputs=panel_outputs)
+        question.submit(
+            on_chat, inputs=[question, chat, user_state], outputs=[chat, question]
+        )
+
+    return demo

finbot/features/__init__.py

@@ -19,6 +19,7 @@ from .base import (
 from .budgets import BudgetsFeature
 from .coaching import CoachingFeature
 from .core import CoreFeature
+from .dashboard import DashboardFeature
 from .expenses import ExpensesFeature
 
 __all__ = [
@@ -42,6 +43,7 @@ def default_features() -> list[Feature]:
     return [
         ExpensesFeature(),
         BudgetsFeature(),
+        DashboardFeature(),
         CoachingFeature(),
         CoreFeature(),
     ]

finbot/features/base.py

@@ -82,6 +82,9 @@ class BotContext:
     chat_id: int
     services: Services
     today: date
+    #: Current @handle without the @, empty if unset. Display and access only --
+    #: everything stored is keyed on the immutable user_id.
+    username: str = ""
     text: str = ""
     command: str = ""
     args: str = ""

finbot/features/dashboard.py

@@ -0,0 +1,52 @@
+"""The /dashboard command: hands out a signed link to the web view."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .. import render
+from ..auth import TokenError, dashboard_url, issue
+from .base import BotContext, CommandSpec, Reply, SimpleFeature
+
+
+class DashboardFeature(SimpleFeature):
+    name = "dashboard"
+    description = "📊 Dashboard"
+    priority = 25
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (CommandSpec("dashboard", "Open your web dashboard and coach"),)
+
+    def cmd_dashboard(self, ctx: BotContext) -> Reply:
+        settings = ctx.settings
+
+        if not settings.telegram_webhook_secret:
+            return Reply(
+                "The dashboard needs <code>TELEGRAM_WEBHOOK_SECRET</code> set "
+                "(it signs the login link)."
+            )
+        if not settings.base_url:
+            return Reply(
+                "I don't know my own public address. Set "
+                "<code>PUBLIC_BASE_URL</code> in the Space settings."
+            )
+
+        try:
+            token = issue(
+                ctx.user_id,
+                settings.telegram_webhook_secret,
+                ttl_seconds=settings.dashboard_link_minutes * 60,
+            )
+        except TokenError as exc:
+            return Reply(f"Couldn't create a login link: {render.escape(str(exc))}")
+
+        url = dashboard_url(settings.base_url, token)
+        minutes = settings.dashboard_link_minutes
+
+        return Reply(
+            f'📊 <a href="{render.escape(url)}">Open your dashboard</a>\n\n'
+            f"<i>This link signs you in and works for {minutes} minutes. "
+            "It's personal — anyone with it can see your spending until it "
+            "expires, so don't forward it.</i>",
+            disable_preview=True,
+        )

finbot/store.py

@@ -29,7 +29,7 @@ from .models import Budget, Expense
 log = logging.getLogger(__name__)
 
 DB_FILENAME = "finbot.db"
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2  # 2 adds the users table
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS expenses (
@@ -69,6 +69,21 @@ CREATE TABLE IF NOT EXISTS budgets (
     PRIMARY KEY (user_id, category, period)
 );
 
+-- Handle registry. The ledger is keyed on user_id and never on username,
+-- because Telegram handles are mutable and can be recycled to a different
+-- person: keying on one would orphan a history on rename, or hand it to
+-- whoever claimed the old name. Username is stored for display and lookup
+-- only, refreshed on every message.
+CREATE TABLE IF NOT EXISTS users (
+    user_id    INTEGER PRIMARY KEY,
+    username   TEXT NOT NULL DEFAULT '',
+    first_name TEXT NOT NULL DEFAULT '',
+    first_seen TEXT NOT NULL,
+    last_seen  TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
+
 CREATE TABLE IF NOT EXISTS meta (
     key   TEXT PRIMARY KEY,
     value TEXT NOT NULL
@@ -353,6 +368,61 @@ class Store:
                 ).fetchone()
         return int(row["n"])
 
+    # ----------------------------------------------------------------- users
+
+    def record_user(
+        self, user_id: int, username: str = "", first_name: str = ""
+    ) -> None:
+        """Note that we have seen this person, refreshing their handle.
+
+        Called on every message so a renamed handle is picked up without any
+        migration -- the id is what everything else hangs off.
+        """
+        handle = (username or "").lstrip("@")
+        now = utc_now().isoformat()
+        with self._lock:
+            self._conn.execute(
+                """INSERT INTO users (user_id, username, first_name, first_seen, last_seen)
+                   VALUES (?,?,?,?,?)
+                   ON CONFLICT(user_id) DO UPDATE SET
+                     username   = excluded.username,
+                     first_name = excluded.first_name,
+                     last_seen  = excluded.last_seen""",
+                (user_id, handle, first_name or "", now, now),
+            )
+            self._conn.commit()
+
+    def username_for(self, user_id: int) -> str:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT username FROM users WHERE user_id = ?", (user_id,)
+            ).fetchone()
+        return row["username"] if row else ""
+
+    def display_name_for(self, user_id: int) -> str:
+        """Handle if we know one, else first name, else the bare id."""
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT username, first_name FROM users WHERE user_id = ?",
+                (user_id,),
+            ).fetchone()
+        if not row:
+            return str(user_id)
+        if row["username"]:
+            return f"@{row['username']}"
+        return row["first_name"] or str(user_id)
+
+    def user_id_for(self, username: str) -> Optional[int]:
+        """Resolve a handle to its id. Case-insensitive; None if unknown."""
+        handle = (username or "").strip().lstrip("@").lower()
+        if not handle:
+            return None
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT user_id FROM users WHERE LOWER(username) = ?", (handle,)
+            ).fetchone()
+        return int(row["user_id"]) if row else None
+
     # --------------------------------------------------------------- budgets
 
     def set_budget(self, budget: Budget) -> Budget:

finbot/telegram.py

@@ -29,6 +29,10 @@ class ParsedUpdate:
     update_id: int
     user_id: int
     chat_id: int
+    #: Current @handle without the @, empty if the user has not set one.
+    #: Mutable -- never use as a storage key, only for access checks and display.
+    username: str = ""
+    first_name: str = ""
     text: str = ""
     command: str = ""
     args: str = ""
@@ -59,6 +63,8 @@ def parse_update(update: dict[str, Any], bot_username: str = "") -> Optional[Par
         update_id=int(update.get("update_id", 0)),
         user_id=int(sender["id"]),
         chat_id=int(chat["id"]),
+        username=(sender.get("username") or "").lstrip("@"),
+        first_name=(sender.get("first_name") or "").strip(),
         caption=(message.get("caption") or "").strip(),
     )
 

tests/test_app.py

@@ -110,6 +110,13 @@ class TestEndpoints:
         for leak in ("mirroring", "not configured", "hf_dataset_repo", "telegram_bot_token"):
             assert leak not in text
 
+    def test_public_page_shows_only_the_landing_copy(self, client):
+        # No token: a visitor must see the explainer, never anyone's numbers.
+        send(client, "coffee 250")
+        text = client.get("/").text
+        assert "sign-in link" in text
+        assert "₹250.00" not in text
+
     def test_diagnostics_requires_the_secret(self, client):
         assert client.get("/admin/diagnostics").status_code == 403
         assert client.get(

tests/test_auth.py

@@ -0,0 +1,72 @@
+import time
+
+import pytest
+
+from finbot.auth import Claims, TokenError, dashboard_url, issue, verify
+
+SECRET = "a-test-signing-secret"
+
+
+class TestRoundTrip:
+    def test_issue_and_verify(self):
+        token = issue(42, SECRET)
+        claims = verify(token, SECRET)
+        assert claims.user_id == 42
+
+    def test_large_user_ids(self):
+        # Telegram ids are well past 32-bit.
+        assert verify(issue(7_000_000_123, SECRET), SECRET).user_id == 7_000_000_123
+
+    def test_tokens_are_url_safe(self):
+        token = issue(42, SECRET)
+        assert "/" not in token and "+" not in token and "=" not in token
+
+    def test_seconds_left(self):
+        claims = Claims(user_id=1, expires_at=int(time.time()) + 60)
+        assert 55 <= claims.seconds_left <= 60
+
+
+class TestRejection:
+    def test_wrong_secret(self):
+        token = issue(42, SECRET)
+        with pytest.raises(TokenError, match="bad signature"):
+            verify(token, "a-different-secret")
+
+    def test_tampered_payload(self):
+        # Swap the user id for someone else's and the signature must fail.
+        token = issue(42, SECRET)
+        forged = issue(99, SECRET).split(".")[0] + "." + token.split(".")[1]
+        with pytest.raises(TokenError):
+            verify(forged, SECRET)
+
+    def test_expired(self):
+        past = int(time.time()) - 100
+        token = issue(42, SECRET, ttl_seconds=1, now=past)
+        with pytest.raises(TokenError, match="expired"):
+            verify(token, SECRET)
+
+    def test_still_valid_just_before_expiry(self):
+        now = int(time.time())
+        token = issue(42, SECRET, ttl_seconds=60, now=now)
+        assert verify(token, SECRET, now=now + 59).user_id == 42
+
+    @pytest.mark.parametrize("bad", ["", "nonsense", "no-dot", "a.b.c.d", "...."])
+    def test_malformed(self, bad):
+        with pytest.raises(TokenError):
+            verify(bad, SECRET)
+
+    def test_no_secret_configured(self):
+        with pytest.raises(TokenError):
+            verify(issue(42, SECRET), "")
+
+    def test_cannot_issue_without_a_secret(self):
+        with pytest.raises(TokenError):
+            issue(42, "")
+
+
+class TestURL:
+    def test_builds_a_query_url(self):
+        assert dashboard_url("https://x.hf.space/", "abc") == "https://x.hf.space/?t=abc"
+
+    def test_handles_missing_trailing_slash(self):
+        assert dashboard_url("https://x.hf.space", "abc") == "https://x.hf.space/?t=abc"

tests/test_dashboard.py

@@ -0,0 +1,232 @@
+from datetime import timedelta
+from types import SimpleNamespace
+
+import pytest
+
+from finbot.analytics import today_in
+from finbot.config import Settings
+from finbot.dashboard import (
+    category_frame,
+    coach_reply,
+    load_dashboard,
+    recent_frame,
+    render_budgets,
+    render_header,
+    render_kpis,
+    render_recurring,
+)
+from finbot.models import Budget, Expense
+from finbot.store import Store
+
+
+def make_settings(tmp_path, **overrides):
+    base = dict(
+        data_dir=str(tmp_path),
+        hf_dataset_repo="",
+        hf_token="",
+        telegram_bot_token="",
+        telegram_webhook_secret="sekrit",
+        allowed_telegram_user_ids="",
+        allowed_telegram_usernames="",
+        default_currency="INR",
+        timezone="Asia/Kolkata",
+    )
+    base.update(overrides)
+    return Settings(**base)
+
+
+@pytest.fixture
+def services(tmp_path):
+    settings = make_settings(tmp_path)
+    store = Store(settings)
+    advisor = SimpleNamespace(advise=lambda **kw: f"advice about: {kw.get('question')}")
+    yield SimpleNamespace(store=store, settings=settings, advisor=advisor)
+    store.close()
+
+
+def add(store, amount, category="food_dining", day=None, merchant="", currency="INR"):
+    store.add_expense(
+        Expense(
+            user_id=1,
+            amount_minor=amount,
+            currency=currency,
+            description=merchant or "thing",
+            category=category,
+            occurred_on=day or today_in("Asia/Kolkata"),
+            merchant=merchant,
+        )
+    )
+
+
+class TestUserRegistry:
+    def test_records_and_reads_back(self, services):
+        services.store.record_user(1, "alice", "Alice")
+        assert services.store.username_for(1) == "alice"
+        assert services.store.display_name_for(1) == "@alice"
+
+    def test_strips_the_at_sign(self, services):
+        services.store.record_user(1, "@bob")
+        assert services.store.username_for(1) == "bob"
+
+    def test_rename_updates_in_place(self, services):
+        services.store.record_user(1, "alice")
+        services.store.record_user(1, "alice2")
+        assert services.store.username_for(1) == "alice2"
+        # Crucially the id is unchanged, so the ledger is not orphaned.
+        assert services.store.user_id_for("alice2") == 1
+
+    def test_lookup_is_case_insensitive(self, services):
+        services.store.record_user(1, "Alice")
+        assert services.store.user_id_for("@ALICE") == 1
+
+    def test_unknown_handle(self, services):
+        assert services.store.user_id_for("nobody") is None
+        assert services.store.user_id_for("") is None
+
+    def test_falls_back_to_first_name_then_id(self, services):
+        services.store.record_user(2, "", "Bob")
+        assert services.store.display_name_for(2) == "Bob"
+        assert services.store.display_name_for(999) == "999"
+
+
+class TestUsernameAuthorisation:
+    def test_username_allowlist(self, tmp_path):
+        s = make_settings(tmp_path, allowed_telegram_usernames="alice, @bob")
+        assert s.is_authorised(111, "alice")
+        assert s.is_authorised(222, "@bob")
+        assert not s.is_authorised(333, "carol")
+
+    def test_case_insensitive(self, tmp_path):
+        s = make_settings(tmp_path, allowed_telegram_usernames="Alice")
+        assert s.is_authorised(1, "ALICE")
+
+    def test_numeric_ids_still_work(self, tmp_path):
+        s = make_settings(tmp_path, allowed_telegram_user_ids="42")
+        assert s.is_authorised(42, "")
+
+    def test_no_username_and_not_in_id_list(self, tmp_path):
+        s = make_settings(tmp_path, allowed_telegram_usernames="alice")
+        assert not s.is_authorised(1, "")
+
+    def test_open_access_overrides(self, tmp_path):
+        s = make_settings(tmp_path, open_access=True)
+        assert s.is_authorised(999, "stranger")
+
+    def test_missing_required_mentions_usernames(self, tmp_path):
+        gaps = make_settings(tmp_path).missing_required()
+        assert any("ALLOWED_TELEGRAM_USERNAMES" in g for g in gaps)
+
+    def test_username_allowlist_satisfies_the_check(self, tmp_path):
+        gaps = make_settings(
+            tmp_path, allowed_telegram_usernames="alice"
+        ).missing_required()
+        assert not any("ALLOWED" in g for g in gaps)
+
+
+class TestLoadDashboard:
+    def test_empty_ledger(self, services):
+        data = load_dashboard(services, 1)
+        assert data.month_total == 0
+        assert data.month_count == 0
+        assert data.recent == []
+
+    def test_totals_this_month(self, services):
+        add(services.store, 25000)
+        add(services.store, 15000, "transport")
+        data = load_dashboard(services, 1)
+        assert data.month_total == 40000
+        assert data.month_count == 2
+
+    def test_uses_the_display_name(self, services):
+        services.store.record_user(1, "alice")
+        assert load_dashboard(services, 1).display_name == "@alice"
+
+    def test_category_breakdown_is_sorted(self, services):
+        add(services.store, 10000, "food_dining")
+        add(services.store, 50000, "rent")
+        data = load_dashboard(services, 1)
+        assert data.by_category[0][0] == "rent"
+
+    def test_only_counts_the_dominant_currency(self, services):
+        add(services.store, 10000, currency="INR")
+        add(services.store, 20000, currency="INR")
+        add(services.store, 999999, currency="USD")
+        data = load_dashboard(services, 1)
+        assert data.currency == "INR"
+        assert data.month_total == 30000  # never sums across currencies
+
+    def test_is_scoped_to_one_user(self, services):
+        add(services.store, 25000)
+        other = Expense(
+            user_id=2, amount_minor=99999, currency="INR", description="x",
+            category="other", occurred_on=today_in("Asia/Kolkata"),
+        )
+        services.store.add_expense(other)
+        assert load_dashboard(services, 1).month_total == 25000
+
+    def test_budgets_included(self, services):
+        services.store.set_budget(Budget(1, "food_dining", 100000, "INR"))
+        add(services.store, 25000)
+        data = load_dashboard(services, 1)
+        assert len(data.budgets) == 1
+        assert data.budgets[0].spent_minor == 25000
+
+
+class TestRendering:
+    def test_header(self, services):
+        services.store.record_user(1, "alice")
+        assert "@alice" in render_header(load_dashboard(services, 1))
+
+    def test_kpis_empty_state_is_helpful(self, services):
+        assert "Nothing logged" in render_kpis(load_dashboard(services, 1))
+
+    def test_kpis_show_the_total(self, services):
+        add(services.store, 25000)
+        assert "₹250.00" in render_kpis(load_dashboard(services, 1))
+
+    def test_kpis_show_the_top_category(self, services):
+        add(services.store, 25000, "groceries")
+        assert "Groceries" in render_kpis(load_dashboard(services, 1))
+
+    def test_category_frame_has_expected_columns(self, services):
+        add(services.store, 25000)
+        frame = category_frame(load_dashboard(services, 1))
+        assert list(frame.columns) == ["Category", "Amount"]
+
+    def test_category_frame_survives_an_empty_ledger(self, services):
+        assert len(category_frame(load_dashboard(services, 1))) == 1
+
+    def test_recent_frame(self, services):
+        add(services.store, 25000, merchant="Blue Tokai")
+        frame = recent_frame(load_dashboard(services, 1))
+        assert "Blue Tokai" in frame["Description"].tolist()
+
+    def test_recent_frame_empty(self, services):
+        frame = recent_frame(load_dashboard(services, 1))
+        assert "Nothing yet" in frame["Description"].tolist()
+
+    def test_budgets_empty_state(self, services):
+        assert "None set" in render_budgets(load_dashboard(services, 1))
+
+    def test_budgets_rendered(self, services):
+        services.store.set_budget(Budget(1, "rent", 100000, "INR"))
+        assert "Rent" in render_budgets(load_dashboard(services, 1))
+
+    def test_recurring_empty_state(self, services):
+        assert "Nothing detected" in render_recurring(load_dashboard(services, 1))
+
+    def test_recurring_rendered(self, services):
+        today = today_in("Asia/Kolkata")
+        for months_back in (0, 1, 2):
+            day = (today.replace(day=1) - timedelta(days=31 * months_back)).replace(day=5)
+            add(services.store, 64900, "subscriptions", day=day, merchant="Netflix")
+        assert "Netflix" in render_recurring(load_dashboard(services, 1))
+
+
+class TestCoach:
+    def test_passes_the_question_through(self, services):
+        add(services.store, 25000)
+        assert "where can I cut back" in coach_reply(services, 1, "where can I cut back")
+
+    def test_works_with_no_data(self, services):
+        assert coach_reply(services, 1, "hello")