docs(api): document the current authentication flow, comment non-obvious auth code

Add a new diagram covering the authentication mechanism: a
session-based /SASLogon/login + /SASLogon/authorize handshake that
mints a short-lived auth code, exchanged at /SASjsApi/auth/token for a
revocable JWT pair, with optional LDAP-backed credential verification.

Add WHY comments (not present before) at the handful of spots in the
auth code whose behaviour isn't obvious from reading them in isolation:
why /auth/token can return an existing token pair instead of rotating
it, why the auth-code exchange never checks a client's clientSecret,
how verifyTokenInDB turns self-verifying JWTs into revocable ones, why
two /SASjsApi/user routes stay reachable in desktop mode, why the
static authorized-route list exists on top of plain authentication,
and why /SASjsApi/client's real protection lives at its router mount
point in routes/api/index.ts rather than in client.ts itself.

api/src/controllers/auth.ts

@@ -100,8 +100,13 @@ const token = async (data: any): Promise<TokenResponse> => {
 
   AuthController.deleteCode(userInfo.userId, clientId)
 
-  // get tokens from DB
+  // Re-exchanging a code for the same user/client while a still-valid token
+  // pair already exists returns that pair instead of minting a new one -
+  // keeps other tabs/sessions using the old tokens alive instead of
+  // silently invalidating them (saveTokensInDB below overwrites, it doesn't
+  // append).
   const existingTokens = await getTokensFromDB(userInfo.userId, clientId)
+
   if (existingTokens) {
     return {
       accessToken: existingTokens.accessToken,
@@ -109,7 +114,12 @@ const token = async (data: any): Promise<TokenResponse> => {
     }
   }
 
+  // Only used to look up token expirations - clientSecret is intentionally
+  // not checked here. The credential for this exchange is the auth code
+  // itself (single-use, 30s-lived, only obtainable by a caller that already
+  // held a valid session - see verifyAuthCode below and web.ts's authorize()).
   const client = await Client.findOne({ clientId })
+
   if (!client) throw new Error('Invalid clientId.')
 
   const accessToken = generateAccessToken(