cctally 1.90.1 → 1.92.0

package/bin/_cctally_config.py

@@ -307,6 +307,7 @@ ALLOWED_CONFIG_KEYS = (
     "dashboard.expose_transcripts",
     "dashboard.cache_failure_markers",
     "dashboard.live_tail",
+    "dashboard.lan_auth",
     "update.check.enabled",
     "update.check.ttl_hours",
     "update.channel",
@@ -1028,6 +1029,22 @@ def _config_known_value(config: dict, key: str) -> "object":
             except ValueError:
                 return True
         return True
+    if key == "dashboard.lan_auth":
+        # Boolean opt-OUT (issue #282). Default TRUE — non-loopback dashboard
+        # runs require their per-run access token unless the user explicitly
+        # disables the gate. Invalid hand edits fail safe to authentication ON.
+        block = config.get("dashboard") if isinstance(config, dict) else None
+        if not isinstance(block, dict):
+            block = {}
+        stored = block.get("lan_auth")
+        if stored is None:
+            return True
+        if isinstance(stored, bool):
+            return stored
+        # The config command normalizes accepted text spellings before write.
+        # A persisted string is therefore a hand edit, not an explicit opt-out;
+        # accept only the JSON boolean false at this security boundary.
+        return True
     if key == "telemetry.enabled":
         # Boolean opt-OUT (anonymous install-count telemetry, spec 2026-07-07).
         # Default TRUE — absence is ON. A hand-edited junk value surfaces the
@@ -1623,6 +1640,34 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"dashboard.live_tail={'true' if canonical else 'false'}")
         return 0
+    if key == "dashboard.lan_auth":
+        try:
+            canonical = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for dashboard.lan_auth: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("dashboard")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: dashboard config error: dashboard must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["lan_auth"] = canonical
+            config["dashboard"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"dashboard": {"lan_auth": canonical}}, indent=2))
+        else:
+            print(f"dashboard.lan_auth={'true' if canonical else 'false'}")
+        return 0
     if key == "telemetry.enabled":
         # Anonymous install-count telemetry opt-out (spec 2026-07-07). Mirror
         # dashboard.live_tail exactly: validate the bool first, then
@@ -2237,6 +2282,18 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "dashboard.lan_auth":
+        # Restart-only opt-out. Removing the leaf restores the safe True
+        # default while preserving all sibling dashboard preferences.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("dashboard")
+            if isinstance(block, dict) and "lan_auth" in block:
+                del block["lan_auth"]
+                if not block:
+                    config.pop("dashboard", None)
+                save_config(config)
+        return 0
     if key == "telemetry.enabled":
         # Mirror the dashboard.live_tail unset branch: drop only the enabled
         # leaf; if the telemetry block ends up empty, drop the parent too.

package/bin/_cctally_core.py

@@ -364,9 +364,26 @@ STATS_WAL_SIZE_LIMIT_BYTES = 16 * 1024 * 1024  # 16777216
 # full pass is measured against. Same mechanical reason as 1005 — an
 # epoch-current open returns before any schema work — so it is a second bump
 # rather than an amendment to the first.
-STATS_INDEX_EPOCH = 1006
+# 1006 -> 1007 (#460): scheduled quota-alert ownership. Adds the per-root
+# future-capture schedule that lets a matured boundary widen to its owning root
+# instead of deferring forever on a quiet hook-only install.
+STATS_INDEX_EPOCH = 1007
 LEGACY_STATS_HEAD = 13
 
+#: #496 S1 F1. A NEW branch, for a state that cannot occur before the
+#: publication transaction exists: a replacement index was published and then
+#: failed validation on a fresh connection. The existing corrupt-stats text
+#: says the database was "Not auto-recreated", which would be false here, so
+#: this path gets its own wording. It does not alter the heal message or any
+#: other corruption path.
+STATS_PUBLICATION_FAILED_MSG = (
+    "stats.db published a rebuilt index that then FAILED validation, so the "
+    "live index is known bad and cctally refuses to use it. path: {path}. "
+    "The rebuild record naming the failing check is at {record}. The damaged "
+    "predecessor was preserved under quarantine/ with a forensics bundle in "
+    "logs/. Recovery: run `cctally db rebuild --db stats`."
+)
+
 
 # === Telemetry constants (non-path; see spec 2026-07-07) =============
 #
@@ -1369,6 +1386,9 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
         -- that are not functions of window dirtiness — a delivery-gate
         -- transition, and a future-clocked observation that becomes eligible
         -- when wall time passes it with no row mutation at all.
+        -- `next_evaluation_by_root_json` owns that scalar minimum: one earliest
+        -- future capture per root, so a due hook tick can reconcile only the
+        -- roots whose instants matured.
         --
         -- `last_full_pass_at` is the periodic verification's deadline. Two
         -- cases a scoped sweep structurally cannot see — a block whose physical
@@ -1386,6 +1406,7 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
             alerts_enabled         INTEGER,
             next_evaluation_at_utc TEXT,
             last_full_pass_at      TEXT,
+            next_evaluation_by_root_json TEXT NOT NULL DEFAULT '{}',
             PRIMARY KEY(source)
         );
 
@@ -1417,14 +1438,19 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
     }
     if "account_key" not in _proj_cols:
         conn.execute("DROP TABLE quota_projection_state")
+        # SQLite stores `sqlite_schema.sql` verbatim apart from stripping
+        # `IF NOT EXISTS`, and `_stats_schema_fingerprint` hashes that text, so
+        # this body must stay character-for-character equal to the fresh-path
+        # definition above (#496 S1 F18).
         conn.execute(
-            "CREATE TABLE quota_projection_state ("
-            " source_root_key TEXT NOT NULL,"
-            " account_key TEXT NOT NULL DEFAULT 'unattributed',"
-            " generation TEXT NOT NULL,"
-            " physical_signature TEXT NOT NULL,"
-            " completed_at_utc TEXT NOT NULL,"
-            " PRIMARY KEY(source_root_key, account_key))"
+            "CREATE TABLE quota_projection_state (\n"
+            "            source_root_key    TEXT NOT NULL,\n"
+            "            account_key        TEXT NOT NULL DEFAULT 'unattributed',\n"
+            "            generation         TEXT NOT NULL,\n"
+            "            physical_signature TEXT NOT NULL,\n"
+            "            completed_at_utc   TEXT NOT NULL,\n"
+            "            PRIMARY KEY(source_root_key, account_key)\n"
+            "        )"
         )
     if add_column_if_missing is not None:
         for _tbl in ("quota_window_blocks", "quota_percent_milestones",
@@ -1445,6 +1471,11 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
         # no-op over the table it already has.
         add_column_if_missing(
             conn, "quota_projection_ledger_state", "last_full_pass_at", "TEXT")
+        # Epoch 1007 / #460: same legacy-cutover seam. Current-epoch indexes
+        # rebuild; a legacy index cuts over in place and needs the column added.
+        add_column_if_missing(
+            conn, "quota_projection_ledger_state",
+            "next_evaluation_by_root_json", "TEXT NOT NULL DEFAULT '{}'")
 
 
 def open_db(*, _target_path=None) -> sqlite3.Connection:
@@ -1648,6 +1679,20 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
     # at `_uv == STATS_INDEX_EPOCH` above and never reaches here, so the hot
     # path takes no exclusive lock at all.
     with _cctally_store.stats_open_time_guard(live=_target_path is None):
+        # Another opener can win the exclusive guard after this connection's
+        # pre-lock epoch read, initialize/cut over the index, and stamp the
+        # current epoch while this opener waits. Recheck under the guard before
+        # acting on that stale legacy/fresh decision; otherwise the loser enters
+        # the frozen migration dispatcher with user_version=1006 and reports a
+        # false downgrade against legacy head 13.
+        if _epoch_engaged and conn.execute(
+            "PRAGMA user_version"
+        ).fetchone()[0] == STATS_INDEX_EPOCH:
+            if _target_path is None:
+                _reconcile_durable_applied_migration_errors(
+                    conn, _STATS_MIGRATIONS, "stats.db"
+                )
+            return conn
         _fixups_current = _cctally_store.stats_open_fixups_current(conn)
         conn.execute(
             """

package/bin/_cctally_dashboard.py

@@ -265,12 +265,14 @@ import bisect
 import contextlib
 import dataclasses
 import datetime as dt
+import hmac
 import io
 import json
 import os
 import pathlib
 import queue
 import re
+import secrets
 import shutil
 import signal as _signal
 import socket
@@ -1773,6 +1775,33 @@ def _format_url(host: str, port: int) -> str:
     return f"http://{host}:{port}/"
 
 
+def _dashboard_auth_url(url: str, token: "str | None") -> str:
+    """Append a per-run token as a fragment, never as a server-visible query."""
+    if token is None:
+        return url
+    return f"{url}#token={urllib.parse.quote(token, safe='')}"
+
+
+def _dashboard_lan_auth_token(
+        bind_host: str, enabled: bool, *,
+        token_factory=secrets.token_urlsafe) -> "str | None":
+    """Mint one process-local token only for authenticated non-loopback binds."""
+    gate = sys.modules["cctally"]._load_sibling("_lib_transcript_access")
+    if not enabled or gate.is_loopback(gate.authority_host(bind_host)):
+        return None
+    return token_factory(32)
+
+
+def _dashboard_token_from_cookie(raw_cookie: str) -> "str | None":
+    """Return the sole dashboard session-token cookie, rejecting duplicates."""
+    values = []
+    for part in (raw_cookie or "").split(";"):
+        name, separator, value = part.strip().partition("=")
+        if separator and name == "cctally_dashboard_token":
+            values.append(value)
+    return values[0] if len(values) == 1 and values[0] else None
+
+
 def _discover_lan_ip() -> "str | None":
     """Return the kernel's chosen IPv4 source address for off-host traffic.
 
@@ -4530,6 +4559,7 @@ _GET_ROUTES = (
 )
 
 _POST_ROUTES = (
+    ("exact", "/api/auth", "_handle_post_auth", None, False),
     ("exact", "/api/sync", "_handle_post_sync", None, False),
     ("exact", "/api/settings", "_handle_post_settings", None, False),
     ("exact", "/api/alerts/test", "_handle_post_alerts_test", None, False),
@@ -4599,6 +4629,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     # cmd_dashboard before serve_forever; the per-request gate
     # (`_require_transcripts_allowed`) ANDs this with the request Host.
     cctally_expose_transcripts: bool = False
+    # Per-process LAN API token. None preserves the byte-stable loopback and
+    # explicit opt-out behavior; a value gates every /api/* request.
+    cctally_api_token: "str | None" = None
 
     # Access log stays silent (deliberate — noisy in the parent terminal),
     # but server errors are REAL as of #279 S2: log_error routes through
@@ -4678,7 +4711,43 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return True
         return False
 
+    def _require_api_auth(self) -> bool:
+        """Authenticate an API request before any route or method dispatch."""
+        if not self.path.split("?", 1)[0].startswith("/api/"):
+            return True
+        token = type(self).cctally_api_token
+        if token is None:
+            return True
+
+        authorization = self.headers.get_all("Authorization", [])
+        supplied = None
+        if authorization:
+            if (len(authorization) == 1
+                    and authorization[0].startswith("Bearer ")):
+                candidate = authorization[0][len("Bearer "):]
+                if candidate:
+                    supplied = candidate
+        else:
+            supplied = _dashboard_token_from_cookie(
+                self.headers.get("Cookie", "")
+            )
+        if (supplied is not None and supplied.isascii()
+                and hmac.compare_digest(supplied, token)):
+            return True
+
+        encoded = encode_dashboard_json_bytes({"error": "unauthorized"})
+        self.send_response(401)
+        self.send_header("WWW-Authenticate", "Bearer")
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(encoded)
+        return False
+
     def do_GET(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
         if self._method_not_allowed_for_settings():
             return
         path = self.path.split("?", 1)[0]
@@ -4716,6 +4785,8 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self.send_error(404, "not found")
 
     def do_POST(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
         # No _method_not_allowed_for_settings() guard here (gate P1-3): POST
         # /api/settings must route to _handle_post_settings, not 405.
         if not self._dispatch(_POST_ROUTES):
@@ -4728,21 +4799,55 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     # For other paths we fall through to send_error(501) so the rest of
     # the surface keeps stdlib semantics.
     def do_PUT(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
         if self._method_not_allowed_for_settings():
             return
         self.send_error(501, "Unsupported method ('PUT')")
 
     def do_DELETE(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
         if self._method_not_allowed_for_settings():
             return
         if not self._dispatch(_DELETE_ROUTES):
             self.send_error(501, "Unsupported method ('DELETE')")
 
     def do_PATCH(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
         if self._method_not_allowed_for_settings():
             return
         self.send_error(501, "Unsupported method ('PATCH')")
 
+    def do_HEAD(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
+        if self._method_not_allowed_for_settings():
+            return
+        self.send_error(501, "Unsupported method ('HEAD')")
+
+    def do_OPTIONS(self) -> None:  # noqa: N802 — stdlib API
+        if not self._require_api_auth():
+            return
+        if self._method_not_allowed_for_settings():
+            return
+        self.send_error(501, "Unsupported method ('OPTIONS')")
+
+    def _handle_post_auth(self) -> None:
+        """Bridge an accepted Bearer token to a browser-native session cookie."""
+        token = type(self).cctally_api_token
+        if token is None:
+            self.send_error(404, "not found")
+            return
+        self.send_response(204)
+        self.send_header(
+            "Set-Cookie",
+            f"cctally_dashboard_token={token}; Path=/api; "
+            "HttpOnly; SameSite=Strict",
+        )
+        self.end_headers()
+
     def _handle_post_sync(self) -> None:
         """Trigger refresh-usage + snapshot rebuild on user demand.
 
@@ -5256,7 +5361,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                          "field": f"dashboard.{leaf}"},
                     )
                     return
-                if leaf not in ("cache_failure_markers", "live_tail"):
+                if leaf not in (
+                    "cache_failure_markers", "live_tail", "lan_auth"
+                ):
                     self._respond_json(
                         400,
                         {"error": f"unknown dashboard settings key: {leaf}",
@@ -5264,7 +5371,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     )
                     return
             dashboard_validated = {}
-            for _leaf in ("cache_failure_markers", "live_tail"):
+            for _leaf in ("cache_failure_markers", "live_tail", "lan_auth"):
                 if _leaf in dashboard_block:
                     if not isinstance(dashboard_block[_leaf], bool):
                         self._respond_json(
@@ -5659,12 +5766,20 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # + live_tail) so the SettingsOverlay can repaint without a
             # follow-up GET. Default true (opt-out) when nothing is persisted.
             persisted_dash = merged.get("dashboard") or {}
+            persisted_lan_auth = persisted_dash.get("lan_auth", True)
             out["dashboard"] = {
                 "cache_failure_markers": bool(
                     persisted_dash.get("cache_failure_markers", True)
                 ),
                 "live_tail": bool(persisted_dash.get("live_tail", True)),
+                "lan_auth": (
+                    persisted_lan_auth
+                    if isinstance(persisted_lan_auth, bool)
+                    else True
+                ),
             }
+            if "lan_auth" in dashboard_validated:
+                out["restart_required"] = ["dashboard.lan_auth"]
         out["saved_at"] = (
             dt.datetime.now(dt.timezone.utc)
             .strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -7266,6 +7381,10 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
             stored = "loopback"
         resolved_bind_stored = stored
     args.host = _resolve_dashboard_bind_for_runtime(resolved_bind_stored)
+    lan_auth_enabled = bool(
+        _config_known_value(config, "dashboard.lan_auth")
+    )
+    api_token = _dashboard_lan_auth_token(args.host, lan_auth_enabled)
 
     # F3: capture the canonical tz token from `--tz` (NOT the ZoneInfo
     # — the override needs to flow through `load_config()`-style readers
@@ -7365,6 +7484,7 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     # in the doctor SSE block + /api/doctor reflects the actual --host
     # the process is serving, not just the config-only view the CLI sees.
     DashboardHTTPHandler.cctally_host = args.host
+    DashboardHTTPHandler.cctally_api_token = api_token
     # Conversation viewer (Plan 2, spec §5): the resolved
     # `dashboard.expose_transcripts` opt-in. Read off the already-loaded
     # `config` the same way `dashboard.bind` is resolved above (the
@@ -7490,20 +7610,40 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     is_loopback = bind_host in ("127.0.0.1", "localhost", "::1")
 
     if is_all_interfaces:
-        local_url = _format_url("localhost", bind_port)
+        local_url = _dashboard_auth_url(
+            _format_url("localhost", bind_port), api_token
+        )
         lan_ip = _discover_lan_ip()
         print("dashboard: serving on all interfaces:", flush=True)
         print(f"  - {local_url}      (this machine)", flush=True)
         if lan_ip:
-            lan_url = _format_url(lan_ip, bind_port)
+            lan_url = _dashboard_auth_url(
+                _format_url(lan_ip, bind_port), api_token
+            )
             print(f"  - {lan_url}   (LAN)", flush=True)
+        if api_token is not None:
+            print(f"dashboard: LAN access token: {api_token}", flush=True)
+        elif not lan_auth_enabled:
+            print(
+                "warning: LAN authentication disabled by "
+                "dashboard.lan_auth=false; restart after enabling it",
+                flush=True,
+            )
         print("Ctrl-C to stop", flush=True)
     elif is_loopback:
         url = _format_url("localhost", bind_port)
         print(f"dashboard: serving {url} — Ctrl-C to stop", flush=True)
     else:
-        url = _format_url(bind_host, bind_port)
+        url = _dashboard_auth_url(_format_url(bind_host, bind_port), api_token)
         print(f"dashboard: serving {url} — Ctrl-C to stop", flush=True)
+        if api_token is not None:
+            print(f"dashboard: LAN access token: {api_token}", flush=True)
+        elif not lan_auth_enabled:
+            print(
+                "warning: LAN authentication disabled by "
+                "dashboard.lan_auth=false; restart after enabling it",
+                flush=True,
+            )
 
     http_thread = threading.Thread(target=srv.serve_forever, daemon=True,
                                    name="dashboard-http")
@@ -7528,6 +7668,7 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
             browser_url = _format_url("localhost", bind_port)
         else:
             browser_url = _format_url(bind_host, bind_port)
+        browser_url = _dashboard_auth_url(browser_url, api_token)
         try:
             _wb.open(browser_url)
         except Exception as exc: