[v5] Update typedoc comments for requests

lib/msal-browser/src/request/AuthorizationCodeRequest.ts

@@ -5,6 +5,17 @@
 
 import { CommonAuthorizationCodeRequest } from "@azure/msal-common/browser";
 
+/**
+ * AuthorizationCodeRequest: Request object passed by browser clients to exchange an authorization code for tokens.
+ *
+ * - code                      - The authorization_code that the user acquired in the first leg of the flow.
+ * - nativeAccountId           - Identifier for the native account when integrating with native or brokered experiences.
+ * - cloudGraphHostName        - Hostname for the Microsoft Cloud instance's Graph endpoint (for example, graph.microsoft.com).
+ * - msGraphHost               - Hostname for the Microsoft Graph endpoint when overriding defaults.
+ * - cloudInstanceHostName     - Hostname for the Azure AD cloud instance that issued the authorization code.
+ *
+ * All other properties are inherited from CommonAuthorizationCodeRequest.
+ */
 export type AuthorizationCodeRequest = Partial<
     Omit<CommonAuthorizationCodeRequest, "code" | "enableSpaAuthorizationCode">
 > & {

lib/msal-browser/src/request/RedirectRequest.ts

@@ -10,6 +10,7 @@ import { CommonAuthorizationUrlRequest } from "@azure/msal-common/browser";
  * server (first leg of authorization code grant flow) with a full page redirect.
  *
  * - scopes                     - Array of scopes the application is requesting access to.
+ * - account                    - AccountInfo obtained from a getAccount API. Will be used in certain scenarios to generate login_hint if both loginHint and sid params are not provided.
  * - authority                  - Url of the authority which the application acquires tokens from.
  * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.

lib/msal-browser/src/request/SilentRequest.ts

@@ -27,6 +27,7 @@ import { CacheLookupPolicy } from "../utils/BrowserConstants.js";
  * - prompt                 - Indicates the type of user interaction that is required.
  *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error
  *          no_session: will not read existing session token when authenticating the user. Upon user being successfully authenticated, EVO won’t create a new session for the user. FOR INTERNAL USE ONLY.
+ * - state                  - A value included in the request that is also returned in the token response when a hidden iframe is used.
  */
 export type SilentRequest = Omit<
     CommonSilentFlowRequest,

lib/msal-browser/src/request/SsoSilentRequest.ts

@@ -12,6 +12,7 @@ import { CommonAuthorizationUrlRequest } from "@azure/msal-common/browser";
  * - claims                     - A stringified claims request which will be added to all /authorize and /token calls
  * - authority                  - Url of the authority which the application acquires tokens from.
  * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
+ * - account                    - AccountInfo obtained from a getAccount API. Will be used in certain scenarios to generate login_hint if both loginHint and sid params are not provided.
  * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
  * - extraScopesToConsent       - Scopes for a different resource when the user needs consent upfront.
  * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after authentication.

lib/msal-common/src/request/BaseAuthRequest.ts

@@ -24,13 +24,14 @@ import { ShrOptions } from "../crypto/SignedHttpRequest.js";
  * - sshJwk                  - A stringified JSON Web Key representing a public key that can be signed by an SSH certificate.
  * - sshKid                  - Key ID that uniquely identifies the SSH public key mentioned above.
  * - azureCloudOptions       - Convenience string enums for users to provide public/sovereign cloud ids
+ * - maxAge                  - Maximum allowed age, in milliseconds, of the user's authentication before a new sign-in is required.
  * - extraQueryParameters    - String to string map of custom query parameters added to outgoing token service requests
  * - storeInCache            - Object containing boolean values indicating whether to store tokens in the cache or not (default is true)
  * - scenarioId              - Scenario id to track custom user prompts
  * - popKid                  - Key ID to identify the public key for PoP token request
  * - embeddedClientId        - Embedded client id. When specified, broker client id (brk_client_id) and redirect uri (brk_redirect_uri) params are set with values from the config, overriding the corresponding extra parameters, if present.
- * - httpMethod              - HTTP method to use for the /authorize request. Defaults to GET, but can be set to POST if the request requires body parameters
- * - extraParameters             - String to string map of custom parameters added to outgoing token service requests
+ * - httpMethod              - HTTP method to use for the /authorize request. Defaults to GET, but can be set to POST if the request requires body parameters.
+ * - extraParameters         - String to string map of custom parameters added to outgoing token service requests.
  */
 export type BaseAuthRequest = {
     authority: string;

lib/msal-common/src/request/CommonAuthorizationCodeRequest.ts

@@ -18,9 +18,11 @@ import { CcsCredential } from "../account/CcsCredential.js";
  * - codeVerifier            - The same code_verifier that was used to obtain the authorization_code. Required if PKCE was used in the authorization code grant request.For more information, see the PKCE RFC: https://tools.ietf.org/html/rfc7636
  * - resourceRequestMethod   - HTTP Request type used to request data from the resource (i.e. "GET", "POST", etc.).  Used for proof-of-possession flows.
  * - resourceRequestUri      - URI that token will be used for. Used for proof-of-possession flows.
- * - enableSpaAuthCode       - Enables the acqusition of a spa authorization code (confidential clients only)
- * - extraQueryParameters    - String to string map of custom query parameters added to outgoing token service requests
- * - extraParameters         - String to string map of custom query parameters added to outgoing token service requests
+ * - enableSpaAuthorizationCode - Enables the acquisition of a SPA authorization code (confidential clients only).
+ * - clientInfo              - Encoded client_info returned with the authorization code, used to bind the token response to a specific account.
+ * - ccsCredential           - Credential used to populate the CCS (Cache Credential Service) header.
+ * - extraQueryParameters    - String to string map of custom query parameters added to outgoing token service requests.
+ * - extraParameters         - String to string map of custom query parameters added to outgoing token service requests.
  */
 export type CommonAuthorizationCodeRequest = BaseAuthRequest & {
     code: string;

lib/msal-common/src/request/CommonAuthorizationUrlRequest.ts

@@ -28,6 +28,7 @@ import { AccountInfo } from "../account/AccountInfo.js";
  *          create: will direct the user to the account creation experience instead of the log in experience
  *          no_session: will not read existing session token when authenticating the user. Upon user being successfully authenticated, EVO won’t create a new session for the user. FOR INTERNAL USE ONLY.
  * - account                    - AccountInfo obtained from a getAccount API. Will be used in certain scenarios to generate login_hint if both loginHint and sid params are not provided.
+ * - earJwk                     - JSON Web Key used when constructing External Authorization Request (EAR) parameters.
  * - loginHint                  - Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know the username/email address ahead of time. Often apps use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim.
  * - sid                        - Session ID, unique identifier for the session. Available as an optional claim on ID tokens.
  * - domainHint                 - Provides a hint about the tenant or domain that the user should use to sign in. The value of the domain hint is a registered domain for the tenant.
@@ -36,6 +37,7 @@ import { AccountInfo } from "../account/AccountInfo.js";
  * - nonce                      - A value included in the request that is returned in the id token. A randomly generated unique value is typically used to mitigate replay attacks.
  * - resourceRequestMethod      - HTTP Request type used to request data from the resource (i.e. "GET", "POST", etc.).  Used for proof-of-possession flows.
  * - resourceRequestUri         - URI that token will be used for. Used for proof-of-possession flows.
+ * - platformBroker             - Indicates whether this authorization request is being initiated by a platform authentication broker instead of a standard web flow.
  */
 export type CommonAuthorizationUrlRequest = BaseAuthRequest & {
     redirectUri: string;

lib/msal-common/src/request/CommonRefreshTokenRequest.ts

@@ -16,6 +16,8 @@ import { CcsCredential } from "../account/CcsCredential.js";
  * - resourceRequestMethod   - HTTP Request type used to request data from the resource (i.e. "GET", "POST", etc.).  Used for proof-of-possession flows.
  * - resourceRequestUri      - URI that token will be used for. Used for proof-of-possession flows.
  * - forceCache              - Force MSAL to cache a refresh token flow response when there is no account in the cache. Used for migration scenarios.
+ * - ccsCredential           - Credential used to populate the CCS (Cache Credential Service) header.
+ * - redirectUri             - Redirect URI to send with the refresh token request.
  * - extraQueryParameters    - String to string map of custom query parameters added to outgoing token service requests
  * - extraParameters         - String to string map of custom query parameters added to outgoing token service requests
  */

lib/msal-common/src/request/CommonSilentFlowRequest.ts

@@ -14,6 +14,8 @@ import { BaseAuthRequest } from "./BaseAuthRequest.js";
  * - correlationId          - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - account                - Account entity to lookup the credentials.
  * - forceRefresh           - Forces silent requests to make network calls if true.
+ * - redirectUri            - Redirect URI registered on the app registration.
+ * - refreshTokenExpirationOffsetSeconds - Number of seconds before the refresh token expires.
  * - resourceRequestMethod  - HTTP Request type used to request data from the resource (i.e. "GET", "POST", etc.).  Used for proof-of-possession flows.
  * - resourceRequestUri     - URI that token will be used for. Used for proof-of-possession flows.
  * - extraQueryParameters   - String to string map of custom query parameters added to outgoing token service requests

lib/msal-node/src/request/AuthorizationUrlRequest.ts

@@ -18,6 +18,7 @@ import { CommonAuthorizationUrlRequest } from "@azure/msal-common/node";
  * - codeChallenge              - Used to secure authorization code grant via Proof of Key for Code Exchange (PKCE). For more information, see the PKCE RCF:https://tools.ietf.org/html/rfc7636
  * - codeChallengeMethod        - The method used to encode the code verifier for the code challenge parameter. Can be "plain" or "S256". If excluded, code challenge is assumed to be plaintext. For more information, see the PKCE RCF: https://tools.ietf.org/html/rfc7636
  * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred.
+ * - earJwk                     - JSON Web Key used when constructing External Authorization Request (EAR) parameters for this authorization request.
  * - prompt                     - Indicates the type of user interaction that is required.
  *          login: will force the user to enter their credentials on that request, negating single-sign on
  *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error
@@ -31,6 +32,7 @@ import { CommonAuthorizationUrlRequest } from "@azure/msal-common/node";
  * - extraQueryParameters       - String to string map of custom query parameters added to outgoing token service requests
  * - extraParameters            - String to string map of custom query parameters added to outgoing token service requests
  * - nonce                      - A value included in the request that is returned in the id token. A randomly generated unique value is typically used to mitigate replay attacks.
+ * - platformBroker             - Indicates whether this authorization request is being initiated by a platform authentication broker instead of a standard web flow.
  * @public
  */
 export type AuthorizationUrlRequest = Partial<

lib/msal-node/src/request/CommonClientCredentialRequest.ts

@@ -15,9 +15,8 @@ import {
  * - authority                          - URL of the authority, the security token service (STS) from which MSAL will acquire tokens.
  * - correlationId                      - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - skipCache                          - Skip token cache lookup and force request to authority to get a a new token. Defaults to false.
- * - preferredAzureRegionOptions        - Options of the user's preferred azure region
- * - clientAssertion                  - An assertion string or a callback function that returns an assertion string (both are Base64Url-encoded signed JWTs) used in the Client Credential flow
- * - azureRegion                       - Azure region to be used for regional authentication
+ * - clientAssertion                    - An assertion string or a callback function that returns an assertion string (both are Base64Url-encoded signed JWTs) used in the Client Credential flow.
+ * - azureRegion                        - Azure region to be used for regional authentication.
  */
 export type CommonClientCredentialRequest = Omit<
     BaseAuthRequest,

lib/msal-node/src/request/CommonDeviceCodeRequest.ts

@@ -19,8 +19,8 @@ import {
  * - resourceRequestMethod      - HTTP Request type used to request data from the resource (i.e. "GET", "POST", etc.).  Used for proof-of-possession flows.
  * - resourceRequestUri         - URI that token will be used for. Used for proof-of-possession flows.
  * - timeout                    - Timeout period in seconds which the user explicitly configures for the polling of the device code endpoint. At the end of this period; assuming the device code has not expired yet; the device code polling is stopped and the request cancelled. The device code expiration window will always take precedence over this set period.
- * - extraQueryParameters       - String to string map of custom query parameters added to outgoing token service requests
- * - extraParameters         - String to string map of custom query parameters added to outgoing token service requests
+ * - extraQueryParameters       - String to string map of custom query parameters added to outgoing token service requests.
+ * - extraParameters            - String to string map of custom parameters added to outgoing token service requests.
  */
 export type CommonDeviceCodeRequest = BaseAuthRequest & {
     deviceCodeCallback: (response: DeviceCodeResponse) => void;

lib/msal-node/src/request/DeviceCodeRequest.ts

@@ -13,6 +13,7 @@ import { CommonDeviceCodeRequest } from "./CommonDeviceCodeRequest.js";
  * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - deviceCodeCallback         - Callback containing device code response. Message should be shown to end user. End user can then navigate to the verification_uri, input the user_code, and input credentials.
  * - cancel                     - Boolean to cancel polling of device code endpoint. While the user authenticates on a separate device, MSAL polls the the token endpoint of security token service for the interval specified in the device code response (usually 15 minutes). To stop polling and cancel the request, set cancel=true.
+ * - timeout                    - Timeout period in seconds which the user explicitly configures for the polling of the device code endpoint. At the end of this period, assuming the device code has not expired yet, polling is stopped and the request cancelled.
  * - extraQueryParameters       - String to string map of custom query parameters added to the query string
  * @public
  */

lib/msal-node/src/request/SilentFlowRequest.ts

@@ -15,6 +15,8 @@ import { AccountInfo, CommonSilentFlowRequest } from "@azure/msal-common/node";
  * - extraParameters        - String to string map of custom query parameters added to outgoing token service requests
  * - account                - Account entity to lookup the credentials.
  * - forceRefresh           - Forces silent requests to make network calls if true.
+ * - redirectUri            - Redirect URI registered on the app registration.
+ * - refreshTokenExpirationOffsetSeconds - Number of seconds before the refresh token expires.
  * @public
  */
 export type SilentFlowRequest = Partial<