From 03f842bd9e6e13106fefe470fa2091d7b9c68211 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Mon, 8 Dec 2025 22:49:10 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`fix/thi?=
 =?UTF-8?q?rd-party-login`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @d-gubert.

* https://github.com/RocketChat/Rocket.Chat/pull/37707#issuecomment-3629346608

The following files were modified:

* `apps/meteor/app/api/server/middlewares/authentication.ts`
* `apps/meteor/app/oauth2-server-config/server/oauth/oauth2-server.ts`
---
 .../app/api/server/middlewares/authentication.ts   | 13 ++++++++++++-
 .../server/oauth/oauth2-server.ts                  | 14 ++++++++++++--
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/apps/meteor/app/api/server/middlewares/authentication.ts b/apps/meteor/app/api/server/middlewares/authentication.ts
index f2c7028a02601..df551f258b05d 100644
--- a/apps/meteor/app/api/server/middlewares/authentication.ts
+++ b/apps/meteor/app/api/server/middlewares/authentication.ts
@@ -10,6 +10,17 @@ type AuthenticationMiddlewareConfig = {
 	cookies?: boolean;
 };
 
+/**
+ * Creates an Express middleware that authenticates requests using header/cookie tokens or OAuth2.
+ *
+ * The middleware sets `req.user` when authentication succeeds and `req.userId` to the authenticated user's `_id`.
+ * If `rejectUnauthorized` is true and no user is authenticated, the middleware responds with HTTP 401 and stops the request.
+ *
+ * @param config - Configuration for the middleware.
+ *   - `rejectUnauthorized` (default: `true`): If true, unauthenticated requests are rejected with HTTP 401.
+ *   - `cookies` (default: `false`): If true, authentication values are read from cookies when available.
+ * @returns An Express middleware function that enforces authentication and populates `req.user` and `req.userId`.
+ */
 export function authenticationMiddleware(
 	config: AuthenticationMiddlewareConfig = {
 		rejectUnauthorized: true,
@@ -69,4 +80,4 @@ export function hasPermissionMiddleware(
 		}
 		next();
 	};
-}
+}
\ No newline at end of file
diff --git a/apps/meteor/app/oauth2-server-config/server/oauth/oauth2-server.ts b/apps/meteor/app/oauth2-server-config/server/oauth/oauth2-server.ts
index 03ac6a54ceaca..bca1a65d46bdf 100644
--- a/apps/meteor/app/oauth2-server-config/server/oauth/oauth2-server.ts
+++ b/apps/meteor/app/oauth2-server-config/server/oauth/oauth2-server.ts
@@ -13,11 +13,21 @@ const oauth2server = new OAuth2Server({
 	debug: false,
 });
 
-// https://github.com/RocketChat/rocketchat-oauth2-server/blob/e758fd7ef69348c7ceceabe241747a986c32d036/model.coffee#L27-L27
+/**
+ * Fetches an access token record by its token string.
+ *
+ * @returns The access token record matching `accessToken`, or `undefined` if none is found.
+ */
 async function getAccessToken(accessToken: string) {
 	return OAuthAccessTokens.findOneByAccessToken(accessToken);
 }
 
+/**
+ * Authenticate a request using an OAuth2 access token and return the corresponding user.
+ *
+ * @param partialRequest - Object containing `headers` and `query` used to locate the access token (`Authorization: Bearer <token>` header or `access_token` query parameter)
+ * @returns The authenticated `IUser` when the token is present, valid, and maps to an existing user; `undefined` if the token is missing, invalid, expired, or the user is not found
+ */
 export async function oAuth2ServerAuth(partialRequest: {
 	headers: Record<string, string | undefined>;
 	query: Record<string, string | undefined>;
@@ -82,4 +92,4 @@ API.v1.addAuthMethod((request: globalThis.Request) => {
 	return oAuth2ServerAuth({ headers, query });
 });
 
-(WebApp.connectHandlers as unknown as ReturnType<typeof express>).use(oauth2server.app);
+(WebApp.connectHandlers as unknown as ReturnType<typeof express>).use(oauth2server.app);
\ No newline at end of file