Move config key descriptions to TS def file

API.md

@@ -22,18 +22,18 @@ If you are using a response type that includes `code` (typically combined with a
 Additional configuration keys that can be passed to `auth()` on initialization:
 
 - **`appSessionCookie`** - Object defining application session cookie attributes. Allowed keys are `domain`, `httpOnly`, `path`, `secure`, and `sameSite`. Defaults are `true` for `httpOnly` and `Lax` for `sameSite`.
-- **`appSessionDuration`** - Integer value, in seconds, indicating application session length. Set to `0` to indicate the cookie should be ephemeral (no expiration). Default is 7 days.
+- **`appSessionDuration`** - Integer value, in seconds, for application session duration. Set to `0` to indicate the cookie should be ephemeral (no expiration). Default is 7 days.
 - **`appSessionName`** - String value for the cookie name used for the internal session. This value must only include letters, numbers, and underscores. Default is `identity`.
 - **`auth0Logout`** - Boolean value to enable Auth0's logout feature. Default is `false`.
 - **`authorizationParams`** - Object that describes the authorization server request. [See below](#authorization-params-key) for defaults and more details.
 - **`clockTolerance`** - Integer value for the system clock's tolerance (leeway) in seconds for ID token verification. Default is `60`.
 - **`errorOnRequiredAuth`** - Boolean value to throw a `Unauthorized 401` error instead of triggering the login process for routes that require authentication. Default is `false`.
-- **`getUser`** - Asynchronous function that receives a token set and returns the profile for `req.openid.user`. This runs on each application page load for authenticated users. Default is [here](lib/hooks/getUser.js).
+- **`getUser`** - Function that returns the profile for `req.openid.user`. This runs on each application page load for authenticated users. Default is [here](lib/hooks/getUser.js).
 - **`handleCallback`** - Function that runs on the callback route, after callback processing but before redirection. Default is [here](lib/hooks/handleCallback.js).
 - **`httpOptions`** - Default options object used for all HTTP calls made by the library ([possible options](https://github.com/sindresorhus/got/tree/v9.6.0#options)). Default is empty.
+- **`identityClaimFilter`** - Array value of claims to remove from the ID token before storing the cookie session. Default is `['aud', 'iss', 'iat', 'exp', 'nonce', 'azp', 'auth_time']`.
 - **`idpLogout`** - Boolean value to log the user out from the identity provider on application logout. Requires the issuer to provide a `end_session_endpoint` value. Default is `false`.
 - **`idTokenAlg`** - String value for the expected ID token algorithm. Default is `RS256`.
-- **`identityClaimFilter`** - Array value of claims to remove from the ID token before storing the cookie session. Default is `['aud', 'iss', 'iat', 'exp', 'nonce', 'azp', 'auth_time']`.
 - **`legacySameSiteCookie`** - Set a fallback cookie with no SameSite attribute when `authorizationParams.response_mode` is `form_post`. Default is `true`.
 - **`loginPath`** - Relative path to application login. Default is `/login`.
 - **`logoutPath`** - Relative path to application logout. Default is `/logout`.

index.d.ts

@@ -4,29 +4,130 @@ import { AuthorizationParameters, TokenSet, UserinfoResponse } from 'openid-clie
 import { Request, Response, NextFunction, RequestHandler } from 'express';
 
 interface ConfigParams {
+    /**
+     * Object defining application session cookie attributes.
+     */
     appSessionCookie?: SessionCookieConfigParams;
+
+    /**
+     * Integer value, in seconds, for application session duration.
+     */
     appSessionDuration?: number;
+
+    /**
+     * String value for the cookie name used for the internal session.
+     */
     appSessionName?: string;
+
+    /**
+     * REQUIRED. The secret(s) used to derive an encryption key for the user identity in a session cookie.
+     * Can use env key APP_SESSION_SECRET instead.
+     */
     appSessionSecret: boolean | string | string[];
+
+    /**
+     * Boolean value to enable Auth0's logout feature.
+     */
     auth0Logout?: boolean;
+
+    /**
+     *  URL parameters used when redirecting users to the authorization server to log in.
+     */
     authorizationParams?: AuthorizationParameters
+
+    /**
+     * REQUIRED. The root URL for the application router.
+     * Can use env key BASE_URL instead.
+     */
     baseURL?: string;
+
+    /**
+     * REQUIRED. The Client ID for your application.
+     * Can use env key CLIENT_ID instead.
+     */
     clientID?: string;
+
+    /**
+     * The Client Secret for your application.
+     * Required when requesting access tokens.
+     * Can use env key CLIENT_SECRET instead.
+     */
     clientSecret?: string;
+
+    /**
+     * Integer value for the system clock's tolerance (leeway) in seconds for ID token verification.
+     */
     clockTolerance?: number;
+
+    /**
+     * Throw a 401 error instead of triggering the login process for routes that require authentication.
+     */
     errorOnRequiredAuth?: boolean;
+
+    /**
+     * Function that returns the profile for `req.openid.user`.
+     */
     getUser?: (req: Request, config: ConfigParams) => undefined | UserinfoResponse;
+
+    /**
+     * Function that runs on the callback route, after callback processing but before redirection.
+     */
     handleCallback?: RequestHandler;
+
+    /**
+     * Default options object used for all HTTP calls made by the library.
+     */
     httpOptions?: object;
+
+    /**
+     * Array value of claims to remove from the ID token before storing the cookie session.
+     */
     identityClaimFilter?: string[];
+
+    /**
+     * Boolean value to log the user out from the identity provider on application logout.
+     */
     idpLogout?: boolean;
+
+    /**
+     * String value for the expected ID token algorithm.
+     */
     idTokenAlg?: string;
+
+    /**
+     * REQUIRED. The root URL for the token issuer with no trailing slash.
+     * Can use env key ISSUER_BASE_URL instead.
+     */
     issuerBaseURL?: string;
+
+    /**
+     * Set a fallback cookie with no SameSite attribute when response_mode is form_post.
+     */
     legacySameSiteCookie?: boolean;
+
+    /**
+     * Relative path to application login.
+     */
     loginPath?: string;
+
+    /**
+     * Relative path to application logout.
+     */
     logoutPath?: string;
+
+    /**
+     * Relative path to the application callback to process the response from the authorization server.
+     */
     redirectUriPath?: string;
+
+    /**
+     * Require authentication for all routes.
+     */
     required?: boolean | ((request: Request) => boolean);
+
+    /**
+     * Boolean value to automatically install the login and logout routes.
+     */
     routes?: boolean;
 }
 

middleware/auth.js

@@ -13,27 +13,7 @@ const appSession = require('../lib/appSession');
 /**
 * Returns a router with two routes /login and /callback
 *
-* @param {Object} [params] The parameters object
-* @param {string} [params.issuerBaseURL] The url address for the token issuer.
-* @param {string} [params.baseURL] The url of the web application where you are installing the router.
-* @param {string} [params.clientID] The client id.
-* @param {string} [params.clientSecret] The client secret, only required for some grants.
-* @param {string} [params.clockTolerance] The clock's tolerance in seconds for token verification.
-* @param {Function} [params.getUser] An async function receiving a tokenset and returning the profile for req.user.
-* @param {boolean|Function} [params.required=true] a boolean to indicate that every route after this middleware requires authentication or
-* a function receiving a request and return a boolean to determine which routes needs authentication.
-* @param {boolean} [params.errorOnRequiredAuth=false] automatically handle unauthorized errors by triggering the authentication process
-* @param {boolean} [params.idpLogout=false] logout the user from the identity provider on logout
-* @param {boolean} [params.auth0Logout=false] use the auth0's logout mechanism if OpenID Connect session management is not supported
-* @param {boolean|Function} [params.routes=true] a boolean indicating if the routes /login and /logout should be added to the application
-* @param {string} [params.redirectUriPath=/callback] The path for the redirect uri, defaults to /callback.
-* @param {Object} [params.authorizationParams] The parameters for the authorization call. Defaults to
-* - response_type: "id_token"
-* - reponse_mode: "form_post"
-* - scope: "openid profile email"
-* @param {string} params.authorizationParams.response_type The response type.
-* @param {string} [params.authorizationParams.response_mode] The response mode.
-* @param {string} [params.authorizationParams.scope=openid profile email] The scope.
+* @param {Object} [params] The parameters object; see index.d.ts for types and descriptions.
 *
 * @returns {express.Router} the router
 */