docs(api): document the current authentication flow, comment non-obvi…

[YuryShkoda]

Issue

The authentication flow (session login, auth-code exchange, JWT issuance/refresh/revocation, LDAP, desktop mode, permission checks) had no diagram, and several non-obvious behaviours in the auth code were undocumented - e.g. why a client's clientSecret isn't checked during token exchange, how token revocation actually works despite using JWTs, and where /SASjsApi/client's access control is actually enforced.

Intent

Make the authentication flow easy to understand from the docs alone, and leave WHY comments at the specific spots in the code where the behaviour would otherwise be surprising or easy to misread in isolation.

Implementation

• Added docs/diagrams/authentication-flow.md: a sequence diagram plus description covering the full flow - GET / (CSRF token) → POST /SASLogon/login (password or LDAP bind, establishes a session) → POST /SASLogon/authorize (session + clientId → short-lived auth code) → POST /SASjsApi/auth/token (code → access/refresh JWT pair) → authenticated SASjsApi requests → refresh → logout. Also documents the two-credential model (session cookie vs bearer JWT), the public-route fallback, desktop-mode bypass, and the authorize middleware's permission-lookup order.
• Added targeted comments (no behaviour changes) explaining:
  • why /auth/token can return an existing token pair instead of always rotating it (controllers/auth.ts)
  • why the auth-code exchange never checks a client's clientSecret (controllers/auth.ts)
  • how verifyTokenInDB turns self-verifying JWTs into revocable ones (utils/verifyTokenInDB.ts)
  • why two /SASjsApi/user routes stay reachable in desktop mode (middlewares/desktop.ts)
  • why the static authorized-route list exists on top of plain authentication (utils/getAuthorizedRoutes.ts)
  • that a failed token check can still pass through as publicUser on public routes (middlewares/authenticateToken.ts)
  • that /SASjsApi/client's actual access control comes from its router mount point in routes/api/index.ts, not from anything in client.ts itself (routes/api/client.ts)

Checks

• Code is formatted correctly (npm run lint:fix).
• Any new functionality has been unit tested.
• All unit tests are passing (npm test).
• All CI checks are green.
• Reviewer is assigned.