feat(auth): atomic session cap + change-password UI + trustProxy docs

src/data/sessions.test.ts

@@ -116,4 +116,13 @@ describe("SessionStore", () => {
     expect(sessions.validateAndTouch(tokens[1])).toBeNull();
     expect(sessions.validateAndTouch(tokens[tokens.length - 1])).not.toBeNull();
   });
+
+  it("createSession respects cap under concurrent calls (no 1-over-cap race)", async () => {
+    // better-sqlite3 transactions are serialised at the engine level. Calling
+    // createSession N times sequentially via Promise.all proves atomic check+insert.
+    const N = MAX_SESSIONS_PER_USER + 3;
+    await Promise.all(Array.from({ length: N }, () => Promise.resolve(sessions.createSession(userId))));
+    const count = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(count).toBe(MAX_SESSIONS_PER_USER);
+  });
 });

src/data/sessions.ts

@@ -49,15 +49,21 @@ export function createSessionStore(db: Database.Database): SessionStore {
   return {
     createSession(userId) {
       // Cap concurrent sessions per user — oldest gets evicted on overflow.
-      const existing = (countForUserStmt.get(userId) as { n: number }).n;
-      if (existing >= MAX_SESSIONS_PER_USER) {
-        deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
-      }
+      // Wrap the count → delete → insert in a transaction so concurrent logins
+      // for the same user can't both pass the cap check and both insert,
+      // ending up 1 over cap (race window between count and insert).
       const token = randomBytes(32).toString("base64url");
       const id = hashToken(token);
       const now = Date.now();
       const expiresAt = now + SESSION_TTL_MS;
-      insertStmt.run(id, userId, now, expiresAt, now);
+      const tx = db.transaction(() => {
+        const existing = (countForUserStmt.get(userId) as { n: number }).n;
+        if (existing >= MAX_SESSIONS_PER_USER) {
+          deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
+        }
+        insertStmt.run(id, userId, now, expiresAt, now);
+      });
+      tx();
       return { token, expiresAt };
     },