Merge branch 'vNext' into jose4

# Conflicts:
#	src/auth0-session/transient-store.ts
#	src/config.ts

package.json

@@ -103,7 +103,7 @@
     "timekeeper": "^2.2.0",
     "tough-cookie": "^4.0.0",
     "ts-jest": "^27.0.5",
-    "typedoc": "^0.22.15",
+    "typedoc": "^0.20.28",
     "typescript": "^4.1.3"
   },
   "dependencies": {

src/auth0-session/client.ts

@@ -20,8 +20,8 @@ function sortSpaceDelimitedString(str: string): string {
 }
 
 // Issuer.discover throws an `AggregateError` in some cases, this error includes the stack trace in the
-// message which causes the stack to be exposed when reporting the error in production. Am using the non standard
-// `_errors` property to identify the polyfilled `AggregateError`
+// message which causes the stack to be exposed when reporting the error in production. We're using the non standard
+// `_errors` property to identify the polyfilled `AggregateError`.
 // See https://github.com/sindresorhus/aggregate-error/issues/4#issuecomment-488356468
 function normalizeAggregateError(e: Error | (Error & { _errors: Error[] })): Error {
   if ('_errors' in e) {

src/auth0-session/config.ts

@@ -23,15 +23,15 @@ export interface Config {
   auth0Logout: boolean;
 
   /**
-   *  URL parameters used when redirecting users to the authorization server to log in.
+   * URL parameters used when redirecting users to the authorization server to log in.
    *
-   *  If this property is not provided by your application, its default values will be:
+   * If this property is not provided by your application, its default values will be:
    *
    * ```js
    * {
    *   response_type: 'id_token',
-   *   response_mode: 'form_post,
-   *   scope: openid profile email'
+   *   response_mode: 'form_post',
+   *   scope: 'openid profile email'
    * }
    * ```
    *
@@ -46,7 +46,7 @@ export interface Config {
    *   authorizationParams: {
    *     response_type: 'code',
    *     scope: 'openid profile email read:reports',
-   *     audience: 'https://your-api-identifier'
+   *     audience: 'https://your-auth0-api-identifier'
    *   }
    * }));
    * ```
@@ -56,21 +56,21 @@ export interface Config {
    * ```js
    * app.use(auth({
    *   authorizationParams: {
-   *     // Note: you need to provide required parameters if this object is set.
-   *     response_type: "id_token",
-   *     response_mode: "form_post",
-   *     scope: "openid profile email",
+   *     // Note: you need to provide required parameters if this object is set
+   *     response_type: 'id_token',
+   *     response_mode: 'form_post',
+   *     scope: 'openid profile email',
    *     // Additional parameters
-   *     acr_value: "tenant:test-tenant",
-   *     custom_param: "custom-value"
+   *     acr_value: 'tenant:test-tenant',
+   *     custom_param: 'custom-value'
    *   }
    * }));
    * ```
    */
   authorizationParams: AuthorizationParameters;
 
   /**
-   * The root URL for the application router, eg https://localhost
+   * The root URL for the application router, for example `https://localhost`.
    */
   baseURL: string;
 
@@ -87,19 +87,19 @@ export interface Config {
 
   /**
    * Integer value for the system clock's tolerance (leeway) in seconds for ID token verification.`
-   * Default is 60
+   * Defaults to `60` seconds.
    */
   clockTolerance: number;
 
   /**
-   * Integer value for the http timeout in ms for authentication requests.
-   * Default is 5000
+   * Integer value for the HTTP timeout in milliseconds for authentication requests.
+   * Defaults to `5000` ms.
    */
   httpTimeout: number;
 
   /**
-   * To opt-out of sending the library and node version to your authorization server
-   * via the `Auth0-Client` header. Default is `true
+   * To opt-out of sending the library and Node.js version to your authorization server
+   * via the `Auth0-Client` header. Defaults to `true`.
    */
   enableTelemetry: boolean;
 
@@ -123,28 +123,28 @@ export interface Config {
 
   /**
    * Array value of claims to remove from the ID token before storing the cookie session.
-   * Default is `['aud', 'iss', 'iat', 'exp', 'nbf', 'nonce', 'azp', 'auth_time', 's_hash', 'at_hash', 'c_hash' ]`
+   * Defaults to `['aud', 'iss', 'iat', 'exp', 'nbf', 'nonce', 'azp', 'auth_time', 's_hash', 'at_hash', 'c_hash']`.
    */
   identityClaimFilter: string[];
 
   /**
-   * Boolean value to log the user out from the identity provider on application logout. Default is `false`
+   * Boolean value to log the user out from the identity provider on application logout. Defaults to `false`.
    */
   idpLogout: boolean;
 
   /**
-   * String value for the expected ID token algorithm. Default is 'RS256'
+   * String value for the expected ID token algorithm. Defaults to 'RS256'.
    */
   idTokenSigningAlg: string;
 
   /**
-   * REQUIRED. The root URL for the token issuer with no trailing slash.
+   * **REQUIRED** The root URL for the token issuer with no trailing slash.
    */
   issuerBaseURL: string;
 
   /**
-   * Set a fallback cookie with no SameSite attribute when response_mode is form_post.
-   * Default is true
+   * Set a fallback cookie with no SameSite attribute when `response_mode` is `form_post`.
+   * Defaults to `true`.
    */
   legacySameSiteCookie: boolean;
 
@@ -170,32 +170,32 @@ export interface SessionConfig {
   /**
    * String value for the cookie name used for the internal session.
    * This value must only include letters, numbers, and underscores.
-   * Default is `appSession`.
+   * Defaults to `appSession`.
    */
   name: string;
 
   /**
-   * If you want your session duration to be rolling, eg reset everytime the
-   * user is active on your site, set this to a `true`. If you want the session
-   * duration to be absolute, where the user is logged out a fixed time after login,
-   * regardless of activity, set this to `false`
-   * Default is `true`.
+   * If you want your session duration to be rolling, resetting everytime the
+   * user is active on your site, set this to `true`. If you want the session
+   * duration to be absolute, where the user gets logged out a fixed time after login
+   * regardless of activity, set this to `false`.
+   * Defaults to `true`.
    */
   rolling: boolean;
 
   /**
    * Integer value, in seconds, for application session rolling duration.
    * The amount of time for which the user must be idle for then to be logged out.
-   * Should be false when rolling is false.
-   * Default is 86400 seconds (1 day).
+   * Should be `false` when rolling is `false`.
+   * Defaults to `86400` seconds (1 day).
    */
   rollingDuration: number | false;
 
   /**
    * Integer value, in seconds, for application absolute rolling duration.
    * The amount of time after the user has logged in that they will be logged out.
    * Set this to `false` if you don't want an absolute duration on your session.
-   * Default is 604800 seconds (7 days).
+   * Defaults to `604800` seconds (7 days).
    */
   absoluteDuration: boolean | number;
 
@@ -205,40 +205,40 @@ export interface SessionConfig {
 export interface CookieConfig {
   /**
    * Domain name for the cookie.
-   * Passed to the [Response cookie](https://expressjs.com/en/api.html#res.cookie) as `domain`
+   * Passed to the [response cookie](https://expressjs.com/en/api.html#res.cookie) as `domain`.
    */
   domain?: string;
 
   /**
    * Path for the cookie.
-   * Passed to the [Response cookie](https://expressjs.com/en/api.html#res.cookie) as `path`
+   * Passed to the [response cookie](https://expressjs.com/en/api.html#res.cookie) as `path`.
    */
   path?: string;
 
   /**
-   * Set to true to use a transient cookie (cookie without an explicit expiration).
-   * Default is `false`
+   * Set to `true` to use a transient cookie (cookie without an explicit expiration).
+   * Defaults to `false`.
    */
   transient: boolean;
 
   /**
    * Flags the cookie to be accessible only by the web server.
-   * Passed to the [Response cookie](https://expressjs.com/en/api.html#res.cookie) as `httponly`.
+   * Passed to the [response cookie](https://expressjs.com/en/api.html#res.cookie) as `httponly`.
    * Defaults to `true`.
    */
   httpOnly: boolean;
 
   /**
    * Marks the cookie to be used over secure channels only.
-   * Passed to the [Response cookie](https://expressjs.com/en/api.html#res.cookie) as `secure`.
+   * Passed to the [response cookie](https://expressjs.com/en/api.html#res.cookie) as `secure`.
    * Defaults to the protocol of {@link Config.baseURL}.
    */
   secure?: boolean;
 
   /**
-   * Value of the SameSite Set-Cookie attribute.
-   * Passed to the [Response cookie](https://expressjs.com/en/api.html#res.cookie) as `samesite`.
-   * Defaults to "Lax" but will be adjusted based on {@link AuthorizationParameters.response_type}.
+   * Value of the SameSite `Set-Cookie` attribute.
+   * Passed to the [response cookie](https://expressjs.com/en/api.html#res.cookie) as `samesite`.
+   * Defaults to `Lax` but will be adjusted based on {@link AuthorizationParameters.response_type}.
    */
   sameSite: 'lax' | 'strict' | 'none';
 }
@@ -252,32 +252,32 @@ export interface AuthorizationParameters extends OidcAuthorizationParameters {
 export type GetLoginState = (req: any, options: LoginOptions) => { [key: string]: any };
 
 /**
- * Custom options to pass to login.
+ * Custom options to pass to the login handler.
  */
 export interface LoginOptions {
   /**
-   * Override the default {@link Config.authorizationParams authorizationParams}
+   * Override the default {@link Config.authorizationParams authorizationParams}.
    */
   authorizationParams?: Partial<AuthorizationParameters>;
 
   /**
-   *  URL to return to after login, overrides the Default is {@link Config.baseURL}
+   * URL to return to after login. Overrides the default in {@link Config.baseURL}.
    */
   returnTo?: string;
 
   /**
-   *  Generate a unique state value for use during login transactions.
+   * Generate a unique state value for use during login transactions.
    */
   getLoginState?: GetLoginState;
 }
 
 /**
- * Custom options to pass to logout.
+ * Custom options to pass to the logout handler.
  */
 export interface LogoutOptions {
   /**
-   *  URL to returnTo after logout, overrides the
-   *  Default in {@link Config.routes.postLogoutRedirect routes.postLogoutRedirect}
+   * URL to return to after logout. Overrides the
+   * default in {@link Config.routes.postLogoutRedirect routes.postLogoutRedirect}.
    */
   returnTo?: string;
 }

src/auth0-session/hooks/get-login-state.ts

@@ -29,8 +29,8 @@ export const getLoginState: GetLoginState = (_req, options) => {
  * @return {string}
  */
 export function encodeState(stateObject: { [key: string]: any }): string {
-  // this filters out nonce, code_verifier, and max_age from the state object so that the values are
-  // only stored in its dedicated transient cookie
+  // This filters out nonce, code_verifier, and max_age from the state object so that the values are
+  // only stored in its dedicated transient cookie.
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   const { nonce, code_verifier, max_age, ...filteredState } = stateObject;
   return jose.base64url.encode(JSON.stringify(filteredState));

src/auth0-session/transient-store.ts

@@ -59,7 +59,7 @@ export default class TransientStore {
    * @param {IncomingMessage} _req Server Request object.
    * @param {ServerResponse} res Server Response object.
    * @param {Object} opts Options object.
-   * @param {String} opts.sameSite SameSite attribute of "None," "Lax," or "Strict". Default is "None."
+   * @param {String} opts.sameSite SameSite attribute of `None`, `Lax`, or `Strict`. Defaults to `None`.
    * @param {String} opts.value Cookie value. Omit this key to store a generated value.
    *
    * @return {String} Cookie value that was set.
@@ -134,24 +134,27 @@ export default class TransientStore {
   }
 
   /**
-   * Generates a nonce value.
+   * Generates a `nonce` value.
+   *
    * @return {String}
    */
   generateNonce(): string {
     return generators.nonce();
   }
 
   /**
-   * Generates a code_verifier value.
+   * Generates a `code_verifier` value.
+   *
    * @return {String}
    */
   generateCodeVerifier(): string {
     return generators.codeVerifier();
   }
 
   /**
-   * Calculates a code_challenge value for a given codeVerifier
-   * @param {String} codeVerifier Code Verifier to calculate the code_challenge value from.
+   * Calculates a `code_challenge` value for a given `codeVerifier`.
+   *
+   * @param {String} codeVerifier Code verifier to calculate the `code_challenge` value from.
    * @return {String}
    */
   calculateCodeChallenge(codeVerifier: string): string {

src/auth0-session/utils/hkdf.ts

@@ -8,7 +8,7 @@ const digest = 'sha256';
 /**
  *
  * Derives appropriate sized keys from the end-user provided secret random string/passphrase using
- * HKDF (HMAC-based Extract-and-Expand Key Derivation Function) defined in RFC 8569
+ * HKDF (HMAC-based Extract-and-Expand Key Derivation Function) defined in RFC 8569.
  *
  * @see https://tools.ietf.org/html/rfc5869
  *