From 584b7db02f0e37af0dac7412503d52c438d585c7 Mon Sep 17 00:00:00 2001
From: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>
Date: Fri, 11 Sep 2026 19:00:02 -0300
Subject: [PATCH] docs(auth): dashboard session = verified JWT + authenticated
 claim

Refs #13298
---
 .../fixes/13298-dashboard-session-authenticated-claim.md  | 1 +
 docs/architecture/AUTHZ_GUIDE.md                          | 8 ++++++++
 2 files changed, 9 insertions(+)
 create mode 100644 changelog.d/fixes/13298-dashboard-session-authenticated-claim.md

diff --git a/changelog.d/fixes/13298-dashboard-session-authenticated-claim.md b/changelog.d/fixes/13298-dashboard-session-authenticated-claim.md
new file mode 100644
index 0000000000..c84635053a
--- /dev/null
+++ b/changelog.d/fixes/13298-dashboard-session-authenticated-claim.md
@@ -0,0 +1 @@
+- **fix(auth):** a dashboard session now requires the `authenticated: true` claim that login, OIDC and the session refresh already emit — a JWT merely signed with `JWT_SECRET` (for example the Cursor CLI passthrough token, which any API-key holder can obtain) no longer verifies as the `auth_token` cookie on any route, the WebSocket handshake or the live server; existing sessions keep working ([#13298](https://github.com/diegosouzapw/OmniRoute/issues/13298))
diff --git a/docs/architecture/AUTHZ_GUIDE.md b/docs/architecture/AUTHZ_GUIDE.md
index 911b1bd72c..4b478876b8 100644
--- a/docs/architecture/AUTHZ_GUIDE.md
+++ b/docs/architecture/AUTHZ_GUIDE.md
@@ -35,6 +35,14 @@ For dashboard pages and admin operations.
 Cookie: auth_token=<JWT signed with JWT_SECRET>
 ```
 
+A cookie is a session only when the JWT verifies **and** carries `authenticated: true`
+(`src/shared/utils/dashboardSessionToken.ts` → `verifyDashboardSessionToken`). Every
+consumer of the cookie (route guard, authz pipeline refresh, WebSocket handshake, live
+server, `/api/settings/require-login`, `/api/auth/status`) goes through that helper.
+Other JWTs signed with `JWT_SECRET` exist — the Cursor CLI passthrough mints
+`iss "omniroute" / aud "cursor-cli"` tokens for key holders — and are never sessions
+(#13298).
+
 Verified by `isDashboardSessionAuthenticated()` in `src/shared/utils/apiAuth.ts`. The pipeline auto-refreshes the JWT when it has fewer than 7 days left in its 30-day lifetime.
 
 Some management routes accept **either** mode: cookie OR `Bearer <key>` when the API key has the `manage` (or `admin`) scope. This is what enables the "configurable via API calls" workflow added in v3.8.