admina-framework 0.12.0__tar.gz → 0.12.1__tar.gz

{admina_framework-0.12.0/admina_framework.egg-info → admina_framework-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina-framework
-Version: 0.12.0
+Version: 0.12.1
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -382,6 +382,10 @@ Real-time governance dashboard on port 3000:
 
 API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
 
+In `admina dev` local mode the dashboard asks for the API key (`admina password show`)
+and keeps a short-lived browser session that only the read-only dashboard API accepts.
+Set `ADMINA_DASHBOARD_ENABLED=false` to stop serving the bundled dashboard.
+
 ## Configuration
 
 Admina uses `admina.yaml` as the primary config file (with `.env` fallback for backward compatibility):

{admina_framework-0.12.0 → admina_framework-0.12.1}/README.md

@@ -305,6 +305,10 @@ Real-time governance dashboard on port 3000:
 
 API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
 
+In `admina dev` local mode the dashboard asks for the API key (`admina password show`)
+and keeps a short-lived browser session that only the read-only dashboard API accepts.
+Set `ADMINA_DASHBOARD_ENABLED=false` to stop serving the bundled dashboard.
+
 ## Configuration
 
 Admina uses `admina.yaml` as the primary config file (with `.env` fallback for backward compatibility):

{admina_framework-0.12.0 → admina_framework-0.12.1}/admina/__init__.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from admina.sdk import ComplianceKit, GovernedAgent, GovernedData, GovernedModel
 
-__version__ = "0.12.0"
+__version__ = "0.12.1"
 
 __all__ = [
     "__version__",

{admina_framework-0.12.0 → admina_framework-0.12.1}/admina/cli/main.py

@@ -643,6 +643,7 @@ def _run_local(
                 click.echo(f"    http://{ip}:{port}  ({label})")
         else:
             click.echo(f"  Ready → http://{display_host}:{port}")
+        click.echo("  Dashboard sign-in: the API key (show it with `admina password show`)")
         if not no_browser:
             webbrowser.open(f"http://{display_host}:{port}")
     else:

{admina_framework-0.12.0 → admina_framework-0.12.1}/admina/dashboard/static/index.html

@@ -330,6 +330,33 @@
   .link-card:hover { border-color: var(--teal); }
   .link-card .lc-label { font-size: 11px; text-transform: uppercase; color: var(--muted); margin-bottom: 6px; }
   .link-card .lc-title { font-size: 14px; font-weight: 600; }
+
+  /* ── Sign-in ─────────────────────────────────────────── */
+  .signin {
+    position: fixed; inset: 0; z-index: 300; background: var(--bg);
+    display: flex; align-items: center; justify-content: center; padding: 24px;
+  }
+  .signin-card {
+    width: 100%; max-width: 420px; background: var(--surface);
+    border: 1px solid var(--border2); border-radius: 12px; padding: 28px;
+  }
+  .signin-card .logo { display: flex; align-items: center; gap: 10px; font-size: 18px; font-weight: 700; margin-bottom: 16px; }
+  .signin-card .logo img { width: 32px; height: 32px; object-fit: contain; }
+  .signin-card .logo .accent { color: var(--teal); }
+  .signin-card p { font-size: 13px; color: var(--muted); line-height: 1.6; margin-bottom: 16px; }
+  .signin-card code { font-family: var(--mono); font-size: 12px; color: var(--text); }
+  .signin-card label { display: block; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); margin-bottom: 6px; }
+  .signin-card input {
+    width: 100%; padding: 9px 12px; border-radius: 6px; border: 1px solid var(--border2);
+    background: var(--surface2); color: var(--text); font-family: var(--mono); font-size: 13px;
+  }
+  .signin-card input:focus { outline: none; border-color: var(--teal); }
+  .signin-card button {
+    margin-top: 14px; width: 100%; padding: 9px 12px; border-radius: 6px; cursor: pointer;
+    background: var(--teal-dark); color: #fff; border: 1px solid var(--teal); font-size: 14px; font-weight: 600;
+  }
+  .signin-card button:disabled { opacity: 0.6; cursor: default; }
+  .signin-card .error { margin-top: 12px; font-size: 13px; color: var(--red); }
 </style>
 </head>
 <body>
@@ -339,6 +366,25 @@
      ════════════════════════════════════════════════════════ -->
 <div x-data="dashboard()" x-init="init()">
 
+  <!-- Sign-in: the API key is exchanged for a short-lived browser session -->
+  <div class="signin" x-show="needsLogin" x-cloak>
+    <form class="signin-card" @submit.prevent="login()">
+      <div class="logo">
+        <img src="heimdall.png" alt="">
+        <span><span class="accent">Admina</span> Governance Dashboard</span>
+      </div>
+      <p>
+        Sign in with this instance's API key. In an <code>admina dev</code> project,
+        run <code>admina password show</code> to display it.
+      </p>
+      <label for="admina-api-key">API key</label>
+      <input id="admina-api-key" type="password" x-model="loginKey" x-ref="loginKey"
+             autocomplete="off" autocapitalize="off" spellcheck="false" required>
+      <button type="submit" :disabled="loginBusy || !loginKey">Sign in</button>
+      <div class="error" x-show="loginError" x-text="loginError" role="alert"></div>
+    </form>
+  </div>
+
   <!-- Top Bar -->
   <div class="topbar">
     <div class="logo">
@@ -349,6 +395,9 @@
       <span class="ts" x-text="lastUpdate"></span>
       <div class="sep"></div>
       <button class="refresh-btn" @click="refresh()">Refresh</button>
+      <template x-if="sessionActive">
+        <button class="refresh-btn" @click="logout()">Sign out</button>
+      </template>
       <div class="sep"></div>
       <div class="status">
         <div class="dot" :style="{ background: healthy ? 'var(--green)' : 'var(--red)' }"></div>
@@ -807,7 +856,9 @@
  * Admina Governance Dashboard — Alpine.js application.
  *
  * Reads from the Phase 3.1 API endpoints. Does NOT write.
- * All API calls go through the nginx reverse proxy (/api/*).
+ * All API calls go to /api/* on the same origin: the proxy itself in
+ * `admina dev` local mode (browser session after sign-in), or the nginx
+ * reverse proxy of the Docker stack (which adds the API key).
  */
 function dashboard() {
   return {
@@ -824,6 +875,12 @@ function dashboard() {
     modelData: {},
     oisg: {},
     showAssessmentHelp: false,
+    needsLogin: false,
+    sessionActive: false,
+    loginKey: '',
+    loginError: '',
+    loginBusy: false,
+    _started: false,
     _ws: null,
     _feedId: 0,
     _refreshTimer: null,
@@ -920,17 +977,96 @@ function dashboard() {
 
     // ── Init ───────────────────────────────────────────
     async init() {
-      await this.refresh();
+      if (await this.checkSession()) this.start();
+    },
+
+    start() {
+      // Alpine calls init() both automatically and via x-init: start once.
+      if (this._started) return;
+      this._started = true;
+      this.refresh();
       this.connectWebSocket();
       // Auto-refresh every 10s
       this._refreshTimer = setInterval(() => this.refresh(), 10000);
     },
 
+    // ── Session ────────────────────────────────────────
+    // Serving this page never signs the browser in. The API key is exchanged
+    // once for a short-lived HttpOnly session cookie that only the read-only
+    // dashboard API accepts. Behind the Docker nginx the proxy already
+    // receives the key, so no sign-in is needed there.
+    async checkSession() {
+      try {
+        const r = await fetch('/api/dashboard/session', { cache: 'no-store' });
+        if (r.status === 401) { this.showLogin(''); return false; }
+        if (r.ok) this.sessionActive = !!(await r.json()).session;
+      } catch (e) { /* network error: start anyway and show Disconnected */ }
+      return true;
+    },
+
+    async login() {
+      if (!this.loginKey) return;
+      this.loginBusy = true;
+      this.loginError = '';
+      try {
+        const r = await fetch('/api/dashboard/session', {
+          method: 'POST',
+          headers: { 'X-API-Key': this.loginKey },
+          cache: 'no-store',
+        });
+        if (r.ok) {
+          this.loginKey = '';
+          this.needsLogin = false;
+          this.sessionActive = true;
+          this.start();
+        } else if (r.status === 401) {
+          this.loginError = 'Invalid API key.';
+        } else {
+          let detail = '';
+          try { detail = (await r.json()).detail || ''; } catch (e) { /* not JSON */ }
+          this.loginError = detail || `Sign-in failed (HTTP ${r.status}).`;
+        }
+      } catch (e) {
+        this.loginError = 'Admina is not reachable.';
+      } finally {
+        this.loginBusy = false;
+      }
+    },
+
+    async logout() {
+      try { await fetch('/api/dashboard/session', { method: 'DELETE', cache: 'no-store' }); }
+      catch (e) { /* cookie expires on its own */ }
+      this.showLogin('');
+    },
+
+    showLogin(message) {
+      clearInterval(this._refreshTimer);
+      this._refreshTimer = null;
+      this._started = false;
+      if (this._ws) {
+        const ws = this._ws;
+        this._ws = null;
+        ws.onclose = null;
+        ws.close();
+      }
+      this.wsConnected = false;
+      this.sessionActive = false;
+      this.feedEvents = [];
+      this.loginError = message;
+      this.needsLogin = true;
+      this.$nextTick(() => this.$refs.loginKey && this.$refs.loginKey.focus());
+    },
+
     // ── Fetch all data ─────────────────────────────────
     async refresh() {
       // allSettled so one failing endpoint never blanks the whole dashboard.
       const okJson = async (url) => {
         const r = await fetch(url);
+        if (r.status === 401) {
+          const err = new Error(`${url} -> 401`);
+          err.unauthorized = true;
+          throw err;
+        }
         if (!r.ok) throw new Error(`${url} -> ${r.status}`);
         return r.json();
       };
@@ -944,6 +1080,10 @@ function dashboard() {
         okJson('/api/dashboard/models'),
         okJson('/api/dashboard/oisg'),
       ]);
+      if (results.some(r => r.status === 'rejected' && r.reason && r.reason.unauthorized)) {
+        this.showLogin('Your session has expired. Sign in again.');
+        return;
+      }
       const [scoreRes, compRes, sovRes, statsRes, feedRes, infraRes, modelsRes, oisgRes] =
         results.map(r => r.status === 'fulfilled' ? r.value : null);
 
@@ -998,8 +1138,9 @@ function dashboard() {
 
         this._ws.onclose = () => {
           this.wsConnected = false;
+          if (this.needsLogin) return;
           console.log('[Admina] WebSocket disconnected, reconnecting in 3s...');
-          setTimeout(() => this.connectWebSocket(), 3000);
+          setTimeout(() => { if (!this.needsLogin) this.connectWebSocket(); }, 3000);
         };
 
         this._ws.onerror = () => {
@@ -1007,7 +1148,7 @@ function dashboard() {
         };
       } catch (e) {
         this.wsConnected = false;
-        setTimeout(() => this.connectWebSocket(), 5000);
+        setTimeout(() => { if (!this.needsLogin) this.connectWebSocket(); }, 5000);
       }
     },
 

{admina_framework-0.12.0 → admina_framework-0.12.1}/admina/plugins/builtin/auth/apikey.py

@@ -16,17 +16,17 @@
 
 Simple header-based authentication using constant-time comparison.
 Supports both ``X-API-Key`` and ``Authorization: Bearer`` headers.
+
+Cookies are never accepted here. The bundled dashboard's browser session is
+handled by the proxy itself, which admits it only on the read-only dashboard
+API (see ``admina.proxy.dashboard_session``).
 """
 
 from __future__ import annotations
 
-import base64
-import hashlib
-import hmac
 import logging
 import os
 import secrets
-import time
 from typing import Any
 
 from admina.plugins.base import BaseAuthProvider
@@ -94,12 +94,13 @@ class APIKeyAuthProvider(BaseAuthProvider):
         if path in self._exempt_paths:
             return {"user_id": "anonymous", "roles": ["public"], "metadata": {}}
 
-        # Accept a raw API key from headers/Bearer, or a signed session cookie.
+        # Accept only the raw API key from X-API-Key or Authorization: Bearer.
         provided = self._extract_key(request)
-        if provided and secrets.compare_digest(provided, self._api_key):
+        # Compare bytes: compare_digest raises TypeError on non-ASCII str.
+        if provided and secrets.compare_digest(
+            provided.encode("utf-8"), self._api_key.encode("utf-8")
+        ):
             return {"user_id": "api_key_user", "roles": ["authenticated"], "metadata": {}}
-        if self._verify_session_cookie(self._extract_session_cookie(request)):
-            return {"user_id": "dashboard_session", "roles": ["authenticated"], "metadata": {}}
         raise PermissionError("Invalid or missing API key")
 
     async def authorize(
@@ -128,12 +129,7 @@ class APIKeyAuthProvider(BaseAuthProvider):
 
     @staticmethod
     def _extract_key(request: Any) -> str:
-        """Extract the raw API key from request headers (X-API-Key or Bearer).
-
-        The admina_session cookie is NOT extracted here — it carries a signed
-        token, not the raw key, and is handled separately by
-        ``_extract_session_cookie`` + ``_verify_session_cookie``.
-        """
+        """Extract the raw API key from request headers (X-API-Key or Bearer)."""
         if isinstance(request, dict):
             headers = request.get("headers", {})
         else:
@@ -145,36 +141,3 @@ class APIKeyAuthProvider(BaseAuthProvider):
             if auth.startswith("Bearer "):
                 key = auth.removeprefix("Bearer ").strip()
         return key
-
-    @staticmethod
-    def _extract_session_cookie(request: Any) -> str:
-        """Extract the admina_session cookie value from a request."""
-        if isinstance(request, dict):
-            cookies = request.get("cookies", {})
-        else:
-            cookies = dict(getattr(request, "cookies", {}))
-        return cookies.get("admina_session", "")
-
-    def _verify_session_cookie(self, token: str) -> bool:
-        """Verify a signed admina_session cookie against the configured key.
-
-        Mirrors the proxy's dashboard token format (HMAC-SHA256 over the
-        expiry). Replicated locally so this plugin does not depend on the
-        proxy package.
-        """
-        if not self._api_key or not token:
-            return False
-        try:
-            raw = base64.urlsafe_b64decode(token.encode("ascii")).decode("utf-8")
-            payload, sig = raw.rsplit(".", 1)
-        except (ValueError, UnicodeDecodeError):
-            return False
-        expected = hmac.new(
-            self._api_key.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
-        ).hexdigest()
-        if not secrets.compare_digest(sig, expected):
-            return False
-        try:
-            return int(time.time()) < int(payload)
-        except ValueError:
-            return False

{admina_framework-0.12.0 → admina_framework-0.12.1}/admina/proxy/api/dashboard.py

@@ -175,6 +175,7 @@ def create_dashboard_endpoints(
     get_governance_guards: Any = None,
     get_config: Any = None,
     verify_credential: Any = None,
+    session_expiry: Any = None,
 ) -> APIRouter:
     """Create a new APIRouter with dashboard endpoints.
 
@@ -200,6 +201,11 @@ def create_dashboard_endpoints(
             Shared credential verifier for header/query/cookie auth.  When
             provided, the WebSocket live endpoint routes all auth through it
             so the signed session cookie is validated correctly.
+        session_expiry: Callable(headers, query_params, cookies) -> int | None.
+            Expiry (Unix seconds) of the browser session that authorized a
+            live-feed connection, or None when the API key itself was
+            presented. A connection opened with a session is closed when the
+            session expires.
 
     Returns:
         The configured APIRouter.
@@ -231,34 +237,49 @@ def create_dashboard_endpoints(
                 return
 
         expected = getattr(settings, "ADMINA_API_KEY", "") or ""
+        # Unix time at which the connection must end: set when a browser
+        # session (not the API key) authorized it, so the feed never
+        # outlives the session.
+        deadline: int | None = None
         if expected:
-            ok = (
-                bool(
-                    verify_credential(
-                        headers=dict(websocket.headers),
-                        query_params=dict(websocket.query_params),
-                        cookies=dict(websocket.cookies),
-                    )
-                )
-                if verify_credential is not None
-                else False
-            )
+            credentials = {
+                "headers": dict(websocket.headers),
+                "query_params": dict(websocket.query_params),
+                "cookies": dict(websocket.cookies),
+            }
+            ok = bool(verify_credential(**credentials)) if verify_credential is not None else False
             if not ok:
                 await websocket.close(code=1008)
                 return
+            if session_expiry is not None:
+                deadline = session_expiry(**credentials)
         elif not getattr(settings, "ALLOW_UNAUTHENTICATED", False):
             await websocket.close(code=1008)
             return
 
         await websocket.accept()
         _ws_clients.add(websocket)
+        expired = False
         try:
             while True:
-                await websocket.receive_text()
+                if deadline is None:
+                    await websocket.receive_text()
+                    continue
+                remaining = deadline - time.time()
+                if remaining <= 0:
+                    expired = True
+                    break
+                try:
+                    await asyncio.wait_for(websocket.receive_text(), timeout=remaining)
+                except TimeoutError:
+                    expired = True
+                    break
         except WebSocketDisconnect:
             pass
         finally:
             _ws_clients.discard(websocket)
+        if expired:
+            await websocket.close(code=1008)
 
     @router.get("/score")
     async def dashboard_score() -> dict[str, Any]:

{admina_framework-0.12.0 → admina_framework-0.12.1}/admina/proxy/config.py

@@ -89,13 +89,25 @@ class Settings(BaseSettings):
     CORS_ORIGINS: str = "http://localhost:3000,http://localhost:8080"
 
     # Auth — set a strong random key in production: openssl rand -hex 32
-    # If empty, auth is disabled (local development only).
+    # If empty, protected routes are refused (fail-closed) unless
+    # ALLOW_UNAUTHENTICATED=true is set explicitly (local development only).
     ADMINA_API_KEY: str = ""
     ALLOW_UNAUTHENTICATED: bool = False
-    # Set the `Secure` flag on the dashboard session cookie so the browser
-    # only sends it over HTTPS. Default False because local dev is HTTP;
-    # set DASHBOARD_COOKIE_SECURE=true in any production / TLS deployment.
+    # Force the `Secure` flag on the dashboard session cookie. The flag is
+    # already set automatically when the request arrives over HTTPS; set
+    # DASHBOARD_COOKIE_SECURE=true when TLS terminates at a reverse proxy
+    # that does not forward the original scheme.
     DASHBOARD_COOKIE_SECURE: bool = False
+    # Bundled dashboard (GET /, /vendor/*, sign-in at /api/dashboard/session).
+    # false removes the SPA and browser sign-in; the /api/dashboard/* data
+    # API stays available with the API key. `dashboard.enabled: false` in
+    # admina.yaml has the same effect.
+    ADMINA_DASHBOARD_ENABLED: bool = True
+    # Lifetime in seconds of a dashboard browser session (60 s to 12 h).
+    # The browser signs in again with the API key when it expires.
+    ADMINA_DASHBOARD_SESSION_TTL: int = Field(default=3600, ge=60, le=43200)
+    # Public OpenAPI documentation (/docs, /redoc, /openapi.json).
+    ADMINA_API_DOCS_ENABLED: bool = True
 
     # Rate limiting (per session, requires Redis)
     RATE_LIMIT_MAX_REQUESTS: int = 100  # requests per window

admina_framework-0.12.1/admina/proxy/dashboard_session.py

@@ -0,0 +1,133 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — dashboard browser sessions.
+
+The bundled dashboard is a browser application: it cannot hold the API key
+in a header without exposing it to page scripts. Instead, the browser
+presents the key once to ``POST /api/dashboard/session`` and receives a
+short-lived session cookie. This module holds the two rules that make that
+safe:
+
+* **What a session token is.** A signed, expiring token bound to the current
+  ``ADMINA_API_KEY``. The signature uses a key derived from the API key with a
+  fixed purpose label, so a token cannot be confused with any other HMAC
+  computed from the same secret, and rotating the API key invalidates every
+  outstanding session. The API key itself never leaves the server.
+
+* **Where a session is accepted.** Only on read-only requests to the
+  dashboard API (``/api/dashboard/*`` and ``/api/stats``), plus reading and
+  ending the session itself. The MCP proxy, the OpenAI-compatible gateway and
+  the integration and compliance APIs always require the API key.
+
+Token format (base64url, unpadded)::
+
+    v2.<expiry-unix-seconds>.<nonce-hex>.<hmac-sha256-hex>
+
+where the HMAC covers ``v2.<expiry>.<nonce>``.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import secrets
+import time
+
+COOKIE_NAME = "admina_dashboard_session"
+#: Cookie name used by releases up to 0.12.0. Never accepted; only cleared.
+LEGACY_COOKIE_NAME = "admina_session"
+#: Browsers send the cookie only to the API, never to ``/mcp`` or ``/v1``.
+COOKIE_PATH = "/api/"
+SESSION_PATH = "/api/dashboard/session"
+
+DEFAULT_TTL_SECONDS = 3600
+MIN_TTL_SECONDS = 60
+MAX_TTL_SECONDS = 12 * 3600
+
+_VERSION = "v2"
+_PURPOSE = b"admina/dashboard-session/v2"
+_MAX_TOKEN_LEN = 256
+
+_READ_METHODS = frozenset({"GET", "HEAD"})
+_SESSION_METHODS = frozenset({"GET", "HEAD", "DELETE"})
+_SCOPE_PREFIX = "/api/dashboard/"
+_SCOPE_PATHS = frozenset({"/api/stats"})
+
+
+def _signing_key(api_key: str) -> bytes:
+    return hmac.new(api_key.encode("utf-8"), _PURPOSE, hashlib.sha256).digest()
+
+
+def _sign(api_key: str, payload: str) -> str:
+    return hmac.new(_signing_key(api_key), payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def issue_token(api_key: str, *, ttl: int, now: int | None = None) -> str:
+    """Mint a session token valid for *ttl* seconds.
+
+    Raises:
+        ValueError: if no API key is configured or *ttl* is out of range.
+    """
+    if not api_key:
+        raise ValueError("a dashboard session requires ADMINA_API_KEY")
+    if not MIN_TTL_SECONDS <= ttl <= MAX_TTL_SECONDS:
+        raise ValueError(
+            f"session ttl must be between {MIN_TTL_SECONDS} and {MAX_TTL_SECONDS} seconds"
+        )
+    exp = (now if now is not None else int(time.time())) + ttl
+    payload = f"{_VERSION}.{exp}.{secrets.token_hex(16)}"
+    raw = f"{payload}.{_sign(api_key, payload)}".encode("ascii")
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def token_expiry(api_key: str, token: str, *, now: int | None = None) -> int | None:
+    """Return the expiry of a valid, unexpired token, else ``None``."""
+    if not api_key or not token or len(token) > _MAX_TOKEN_LEN:
+        return None
+    try:
+        padded = token + "=" * (-len(token) % 4)
+        raw = base64.urlsafe_b64decode(padded.encode("ascii")).decode("ascii")
+    except (ValueError, UnicodeError, binascii.Error):
+        return None
+    parts = raw.split(".")
+    if len(parts) != 4 or parts[0] != _VERSION:
+        return None
+    payload, sig = ".".join(parts[:3]), parts[3]
+    if not secrets.compare_digest(sig, _sign(api_key, payload)):
+        return None
+    try:
+        exp = int(parts[1])
+    except ValueError:
+        return None
+    if (now if now is not None else int(time.time())) >= exp:
+        return None
+    return exp
+
+
+def verify_token(api_key: str, token: str, *, now: int | None = None) -> bool:
+    """True if *token* is a valid, unexpired session for *api_key*."""
+    return token_expiry(api_key, token, now=now) is not None
+
+
+def session_allowed(method: str, path: str) -> bool:
+    """True if a dashboard session may authenticate *method* on *path*."""
+    method = method.upper()
+    if path == SESSION_PATH:
+        return method in _SESSION_METHODS
+    if method not in _READ_METHODS:
+        return False
+    return path.startswith(_SCOPE_PREFIX) or path in _SCOPE_PATHS