fix(#411): QA-010 — fix minor JSDoc and comment issues across auth files

Fix response.ok JSDoc (2xx not 200), remove stale token refresh claim,
remove non-actionable comment, fix CSRF comment placement, add 403 mapping rationale.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/api/src/auth/auth.config.ts

@@ -210,12 +210,12 @@ export function createAuth(prisma: PrismaClient) {
       provider: "postgresql",
     }),
     emailAndPassword: {
-      enabled: true, // Enable for now, can be disabled later
+      enabled: true,
     },
     plugins: [...getOidcPlugins()],
     session: {
       expiresIn: 60 * 60 * 24 * 7, // 7 days absolute max
-      updateAge: 60 * 60 * 2, // 2 hours idle timeout (sliding window)
+      updateAge: 60 * 60 * 2, // 2 hours — minimum session age before BetterAuth refreshes the expiry on next request
     },
     advanced: {
       defaultCookieAttributes: {

apps/api/src/auth/auth.controller.ts

@@ -112,12 +112,9 @@ export class AuthController {
    * Rate limiting and logging are applied to mitigate abuse (SEC-API-10).
    */
   @All("*")
-  /**
-   * BetterAuth implements CSRF protection internally via Fetch Metadata headers
-   * (Sec-Fetch-Site, Sec-Fetch-Mode) and SameSite=Lax cookies. The @SkipCsrf()
-   * decorator skips the custom CSRF guard to avoid double-protection conflicts.
-   * Reference: https://www.better-auth.com/docs/reference/security
-   */
+  // BetterAuth handles CSRF internally (Fetch Metadata + SameSite=Lax cookies).
+  // @SkipCsrf avoids double-protection conflicts.
+  // See: https://www.better-auth.com/docs/reference/security
   @SkipCsrf()
   @Throttle({ strict: { limit: 10, ttl: 60000 } })
   async handleAuth(@Req() req: ExpressRequest, @Res() res: ExpressResponse): Promise<void> {

apps/api/src/auth/auth.service.ts

@@ -153,7 +153,7 @@ export class AuthService {
    * Check if the OIDC provider (Authentik) is reachable by fetching the discovery URL.
    * Results are cached for 30 seconds to prevent repeated network calls.
    *
-   * @returns true if the provider responds with HTTP 200, false otherwise
+   * @returns true if the provider responds with an HTTP 2xx status, false otherwise
    */
   async isOidcProviderReachable(): Promise<boolean> {
     const now = Date.now();