@depup/express-openid-connect 2.19.4-depup.0

package/index.d.ts

@@ -0,0 +1,1055 @@
+// Type definitions for express-openid-connect
+
+import type { Agent as HttpAgent } from 'http';
+import type { Agent as HttpsAgent } from 'https';
+import {
+  AuthorizationParameters,
+  IdTokenClaims,
+  UserinfoResponse,
+} from 'openid-client';
+import { Request, Response, RequestHandler } from 'express';
+import type { JSONWebKey, KeyInput } from 'jose';
+import type { KeyObject } from 'crypto';
+
+/**
+ * Session object
+ */
+interface Session {
+  /**
+   * Values stored in an authentication session
+   */
+  id_token: string;
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_at: string;
+  [key: string]: any;
+}
+
+/**
+ * The Express.js Request with `oidc` context added by the `auth` middleware.
+ *
+ * ```js
+ * app.use(auth());
+ *
+ * app.get('/profile', (req, res) => {
+ *   const user = req.oidc.user;
+ *   ...
+ * })
+ * ```
+ *
+ * @deprecated use the native the `Request` interface of `express` instead; it has
+ * been extended and now includes a built in `oidc` param.
+ */
+interface OpenidRequest extends Request {
+  /**
+   * Library namespace for authentication methods and data.
+   */
+  oidc: RequestContext;
+}
+
+/**
+ * The Express.js Response with `oidc` context added by the `auth` middleware.
+ *
+ * ```js
+ * app.use(auth());
+ *
+ * app.get('/login', (req, res) => {
+ *   res.oidc.login();
+ * })
+ * ```
+ *
+ * @deprecated use the native the `Response` interface of `express` instead; it has
+ * been extended and now includes a built in `oidc` param.
+ */
+interface OpenidResponse extends Response {
+  /**
+   * Library namespace for authentication methods and data.
+   */
+  oidc: ResponseContext;
+}
+
+/**
+ * The request authentication context found on the Express request when
+ * OpenID Connect auth middleware is added to your application.
+ *
+ * ```js
+ * app.use(auth());
+ *
+ * app.get('/profile', (req, res) => {
+ *   const user = req.oidc.user;
+ *   ...
+ * })
+ * ```
+ */
+interface RequestContext {
+  /**
+   * Method to check the user's authenticated state, returns `true` if logged in.
+   */
+  isAuthenticated: () => boolean;
+
+  /**
+   * The OpenID Connect ID Token.
+   *
+   * See: https://auth0.com/docs/protocols/oidc#id-tokens
+   */
+  idToken?: string;
+
+  /**
+   * Credentials that can be used by an application to access an API.
+   *
+   * See: https://auth0.com/docs/protocols/oidc#access-tokens
+   */
+  accessToken?: AccessToken;
+
+  /**
+   * Credentials that can be used to refresh an access token.
+   *
+   * See: https://auth0.com/docs/tokens/concepts/refresh-tokens
+   */
+  refreshToken?: string;
+
+  /**
+   * An object containing all the claims of the ID Token.
+   */
+  idTokenClaims?: IdTokenClaims;
+
+  /**
+   * An object containing all the claims of the ID Token with the claims
+   * specified in {@link ConfigParams.identityClaimFilter identityClaimFilter} removed.
+   */
+  user?: Record<string, any>;
+
+  /**
+   * Fetches the OIDC userinfo response.
+   *
+   * ```js
+   * app.use(auth());
+   *
+   * app.get('/user-info', async (req, res) => {
+   *   const userInfo = await req.oidc.fetchUserInfo();
+   *   res.json(userInfo);
+   * })
+   * ```
+   *
+   */
+  fetchUserInfo(): Promise<UserinfoResponse>;
+}
+
+/**
+ * The response authentication context found on the Express response when
+ * OpenID Connect auth middleware is added to your application.
+ *
+ * ```js
+ * app.use(auth());
+ *
+ * app.get('/admin-login', (req, res) => {
+ *   res.oidc.login({ returnTo: '/admin' })
+ * })
+ * ```
+ */
+interface ResponseContext {
+  /**
+   * Provided by default via the `/login` route. Call this to override or have other
+   * login routes with custom {@link ConfigParams.authorizationParams authorizationParams} or returnTo
+   *
+   * ```js
+   * app.get('/admin-login', (req, res) => {
+   *   res.oidc.login({
+   *     returnTo: '/admin',
+   *     authorizationParams: {
+   *       scope: 'openid profile email admin:user',
+   *     }
+   *   });
+   * });
+   * ```
+   */
+  login: (opts?: LoginOptions) => Promise<void>;
+
+  /**
+   * Provided by default via the `/logout` route. Call this to override or have other
+   * logout routes with custom returnTo
+   *
+   * ```js
+   * app.get('/admin-logout', (req, res) => {
+   *   res.oidc.logout({ returnTo: '/admin-welcome' })
+   * });
+   * ```
+   */
+  logout: (opts?: LogoutOptions) => Promise<void>;
+
+  /**
+   * Provided by default via the `/callback` route. Call this to override or have other
+   * callback routes with
+   *
+   * ```js
+   * app.get('/callback', (req, res) => {
+   *  res.oidc.callback({ redirectUri: 'https://example.com/callback' });
+   * });
+   * ```
+   */
+  callback: (opts?: CallbackOptions) => Promise<void>;
+}
+
+/**
+ * Extend express interfaces (Response/Request) to support oidc param
+ */
+declare global {
+  namespace Express {
+    interface Request {
+      oidc: RequestContext;
+    }
+
+    interface Response {
+      oidc: ResponseContext;
+    }
+  }
+}
+
+/**
+ * Custom options to pass to login.
+ */
+interface LoginOptions {
+  /**
+   * Override the default {@link ConfigParams.authorizationParams authorizationParams}, if also passing a custom callback
+   * route then  {@link AuthorizationParameters.redirect_uri redirect_uri} must be provided here or in
+   * {@link ConfigParams.authorizationParams config}
+   */
+  authorizationParams?: AuthorizationParameters;
+
+  /**
+   *  URL to return to after login, overrides the Default is {@link express!Request.originalUrl Request.originalUrl}
+   */
+  returnTo?: string;
+
+  /**
+   *  Used by {@link ConfigParams.attemptSilentLogin} to swallow callback errors on silent login.
+   */
+  silent?: boolean;
+}
+
+/**
+ * Custom options to pass to logout.
+ */
+interface LogoutOptions {
+  /**
+   *  URL to returnTo after logout, overrides the Default in {@link ConfigParams.routes routes.postLogoutRedirect}
+   */
+  returnTo?: string;
+
+  /**
+   * Additional custom parameters to pass to the logout endpoint.
+   */
+  logoutParams?: { [key: string]: any };
+}
+
+interface CallbackOptions {
+  /**
+   * This is useful to specify in addition to {@link ConfigParams.baseURL} when your app runs on multiple domains,
+   * it should match {@link LoginOptions.authorizationParams.redirect_uri}
+   */
+  redirectUri: string;
+
+  /**
+   * Additional request body properties to be sent to the `token_endpoint.
+   */
+  tokenEndpointParams?: TokenParameters;
+}
+
+/**
+ * Custom options to configure Back-Channel Logout on your application.
+ */
+interface BackchannelLogoutOptions {
+  /**
+   * Used to store Back-Channel Logout entries, you can specify a separate store
+   * for this or just reuse {@link SessionConfigParams.store} if you are using one already.
+   *
+   * The store should have `get`, `set` and `destroy` methods, making it compatible
+   * with [express-session stores](https://github.com/expressjs/session#session-store-implementation).
+   */
+  store?: SessionStore<Pick<SessionStorePayload, 'cookie'>>;
+
+  /**
+   * On receipt of a Logout Token the SDK validates the token then by default stores 2 entries: one
+   * by the token's `sid` claim (if available) and one by the token's `sub` claim (if available).
+   *
+   * If a session subsequently shows up with either the same `sid` or `sub`, the user if forbidden access and
+   * their cookie is deleted.
+   *
+   * You can override this to implement your own Back-Channel Logout logic
+   * (See {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-genid.js} or {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-query-store.js})
+   */
+  onLogoutToken?: (
+    decodedToken: object,
+    config: ConfigParams
+  ) => Promise<void> | void;
+
+  /**
+   * When {@link backchannelLogout} is enabled all requests that have a session
+   * will be checked for a previous Back-Channel logout. By default, this
+   * uses the `sub` and the `sid` (if available) from the session's ID token to look up a previous logout and
+   * logs the user out if one is found.
+   *
+   * You can override this to implement your own Back-Channel Logout logic
+   * (See {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-genid.js} or {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-query-store.js})
+   */
+  isLoggedOut?:
+    | false
+    | ((req: Request, config: ConfigParams) => Promise<boolean> | boolean);
+
+  /**
+   * When {@link backchannelLogout} is enabled, upon successful login the SDK will remove any existing Back-Channel
+   * logout entries for the same `sub`, to prevent the user from being logged out by an old Back-Channel logout.
+   *
+   * You can override this to implement your own Back-Channel Logout logic
+   * (See {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-genid.js} or {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-query-store.js})
+   */
+  onLogin?:
+    | false
+    | ((req: Request, config: ConfigParams) => Promise<void> | void);
+}
+
+/**
+ * Configuration parameters passed to the `auth()` middleware.
+ *
+ * {@link ConfigParams.issuerBaseURL issuerBaseURL}, {@link ConfigParams.baseURL baseURL}, {@link ConfigParams.clientID clientID}
+ * and {@link ConfigParams.secret secret} are required but can be configured with environmental variables. {@link ConfigParams.clientSecret clientSecret} is not required but can also be configured this way.
+ *
+ * ```js
+ * # Required
+ * ISSUER_BASE_URL=https://YOUR_DOMAIN
+ * BASE_URL=https://YOUR_APPLICATION_ROOT_URL
+ * CLIENT_ID=YOUR_CLIENT_ID
+ * SECRET=LONG_RANDOM_VALUE
+ *
+ * # Not required
+ * CLIENT_SECRET=YOUR_CLIENT_SECRET
+ * ```
+ */
+interface ConfigParams {
+  /**
+   * REQUIRED. The secret(s) used to derive an encryption key for the user identity in a stateless session cookie,
+   * to sign the transient cookies used by the login callback and to sign the custom session store cookies if
+   * {@Link signSessionStoreCookie} is `true`. Use a single string key or array of keys. Secrets must be at least 8 characters long.
+   * If an array of secrets is provided, only the first element will be used to sign or encrypt the values, while all
+   * the elements will be considered when decrypting or verifying the values.
+   *
+   * Can use env key SECRET instead.
+   */
+  secret?: string | Array<string>;
+
+  /**
+   * Object defining application session cookie attributes.
+   */
+  session?: SessionConfigParams;
+
+  /**
+   * Boolean value to enable idpLogout with an Auth0 custom domain
+   */
+  auth0Logout?: boolean;
+
+  /**
+   *  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:
+   *
+   * ```js
+   * {
+   *   response_type: 'id_token',
+   *   response_mode: 'form_post',
+   *   scope: 'openid profile email'
+   * }
+   * ```
+   *
+   * New values can be passed in to change what is returned from the authorization server depending on your specific scenario.
+   *
+   * For example, to receive an access token for an API, you could initialize like the sample below. Note that `response_mode` can be omitted because the OAuth2 default mode of `query` is fine:
+   *
+   * ```js
+   * app.use(
+   *   auth({
+   *     authorizationParams: {
+   *       response_type: 'code',
+   *       scope: 'openid profile email read:reports',
+   *       audience: 'https://your-api-identifier',
+   *     },
+   *   })
+   * );
+   * ```
+   *
+   * Additional custom parameters can be added as well:
+   *
+   * ```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"
+   *    // Additional parameters
+   *    acr_value: "tenant:test-tenant",
+   *    custom_param: "custom-value"
+   *   }
+   * }));
+   * ```
+   */
+  authorizationParams?: AuthorizationParameters;
+
+  /**
+   * Additional custom parameters to pass to the logout endpoint.
+   */
+  logoutParams?: { [key: string]: any };
+
+  /**
+   * REQUIRED. The root URL for the application router, eg https://localhost
+   * Can use env key BASE_URL instead.
+   *
+   * Note: In the event that the URL has a path at the end, the `auth` middleware
+   * will need to be bound relative to that path. I.e
+   *
+   * ```js
+   * app.use('/some/path', auth({
+   *  baseURL: "https://example.com/some/path"
+   *  [...]
+   * })
+   * ```
+   */
+  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.`
+   * Default is 60
+   */
+  clockTolerance?: number;
+
+  /**
+   * To opt-out of sending the library and node version to your authorization server
+   * via the `Auth0-Client` header. Default is `true
+   */
+  enableTelemetry?: boolean;
+
+  /**
+   * Throw a 401 error instead of triggering the login process for routes that require authentication.
+   * Default is `false`
+   */
+  errorOnRequiredAuth?: boolean;
+
+  /**
+   * Attempt silent login (`prompt: 'none'`) on the first unauthenticated route the user visits.
+   * For protected routes this can be useful if your Identity Provider does not default to
+   * `prompt: 'none'` and you'd like to attempt this before requiring the user to interact with a login prompt.
+   * For unprotected routes this can be useful if you want to check the user's logged in state on their IDP, to
+   * show them a login/logout button for example.
+   * Default is `false`
+   */
+  attemptSilentLogin?: boolean;
+
+  /**
+   * Function that returns an object with URL-safe state values for `res.oidc.login()`.
+   * Used for passing custom state parameters to your authorization server.
+   *
+   * ```js
+   * app.use(auth({
+   *   ...
+   *   getLoginState(req, options) {
+   *     return {
+   *       returnTo: options.returnTo || req.originalUrl,
+   *       customState: 'foo'
+   *     };
+   *   }
+   * }))
+   * ``
+   */
+  getLoginState?: (req: OpenidRequest, options: LoginOptions) => object;
+
+  /**
+   * Function for custom callback handling after receiving and validating the ID Token and before redirecting.
+   * This can be used for handling token storage, making userinfo calls, claim validation, etc.
+   *
+   * ```js
+   * app.use(auth({
+   *   ...
+   *   afterCallback: async (req, res, session, decodedState) => {
+   *     const userProfile = await request(`${issuerBaseURL}/userinfo`);
+   *     return {
+   *       ...session,
+   *       userProfile // access using `req.appSession.userProfile`
+   *     };
+   *   }
+   * }))
+   * ``
+   */
+  afterCallback?: (
+    req: OpenidRequest,
+    res: OpenidResponse,
+    session: Session,
+    decodedState: { [key: string]: any }
+  ) => Promise<Session> | Session;
+
+  /**
+   * 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' ]`
+   */
+  identityClaimFilter?: string[];
+
+  /**
+   * Boolean value to log the user out from the identity provider on application logout. Default is `false`
+   */
+  idpLogout?: boolean;
+
+  /**
+   * String value for the expected ID token algorithm. Default is 'RS256'
+   */
+  idTokenSigningAlg?: 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.
+   * Default is true
+   */
+  legacySameSiteCookie?: boolean;
+
+  /**
+   * Require authentication for all routes.
+   */
+  authRequired?: boolean;
+
+  /**
+   * Perform a Pushed Authorization Request at the issuer's pushed_authorization_request_endpoint at login.
+   */
+  pushedAuthorizationRequests?: boolean;
+
+  /**
+   * Set to `true` to enable Back-Channel Logout in your application.
+   * This will set up a web hook on your app at {@link ConfigParams.routes routes.backchannelLogout}
+   * On receipt of a Logout Token the webhook will store the token, then on any
+   * subsequent requests, will check the store for a Logout Token that corresponds to the
+   * current session. If it finds one, it will log the user out.
+   *
+   * In order for this to work you need to specify a {@link ConfigParams.backchannelLogout.store},
+   * which can be any `express-session` compatible store, or you can
+   * reuse {@link SessionConfigParams.store} if you are using one already.
+   *
+   * See: https://openid.net/specs/openid-connect-backchannel-1_0.html
+   */
+  backchannelLogout?: boolean | BackchannelLogoutOptions;
+
+  /**
+   * Configuration for the login, logout, callback and postLogoutRedirect routes.
+   */
+  routes?: {
+    /**
+     * Relative path to application login.
+     */
+    login?: string | false;
+
+    /**
+     * Relative path to application logout.
+     */
+    logout?: string | false;
+
+    /**
+     * Either a relative path to the application or a valid URI to an external domain.
+     * This value must be registered on the authorization server.
+     * The user will be redirected to this after a logout has been performed.
+     */
+    postLogoutRedirect?: string;
+
+    /**
+     * Relative path to the application callback to process the response from the authorization server.
+     */
+    callback?: string | false;
+
+    /**
+     * Relative path to the application's Back-Channel Logout web hook.
+     */
+    backchannelLogout?: string;
+  };
+
+  /**
+   * Configuration parameters used for the transaction cookie.
+   */
+  transactionCookie?: Pick<CookieConfigParams, 'sameSite'> & { name?: string };
+
+  /**
+   * String value for the client's authentication method. Default is `none` when using response_type='id_token', `private_key_jwt` when using a `clientAssertionSigningKey`, otherwise `client_secret_basic`.
+   */
+  clientAuthMethod?: string;
+
+  /**
+   * Private key for use with 'private_key_jwt' clients.
+   *
+   * Can be a PEM:
+   *
+   * ```js
+   * app.use(auth({
+   *   ...
+   *   clientAssertionSigningKey: '-----BEGIN PRIVATE KEY-----\nMIIEo...PgCaw\n-----END PRIVATE KEY-----',
+   * }))
+   * ```
+   *
+   * Or JWK:
+   *
+   * ```js
+   * app.use(auth({
+   *   ...
+   *   clientAssertionSigningKey: {
+   *     kty: 'RSA',
+   *     n: 'u2fhZ...XIqhQ',
+   *     e: 'AQAB',
+   *     d: 'Cmvt9...g__Jw',
+   *     p: 'y5iuh...dIMwM',
+   *     q: '66Rex...IZcdc',
+   *     dp: 'GVGVc...La4a0',
+   *     dq: 'SyER8...Dnaes',
+   *     qi: 'JTtu5...P2HMw'
+   *   },
+   * }))
+   * ```
+   *
+   * Or KeyObject:
+   *
+   * ```js
+   * app.use(auth({
+   *   ...
+   *   clientAssertionSigningKey: crypto.createPrivateKey({ key: '-----BEGIN PRIVATE KEY-----\nMIIEo...PgCaw\n-----END PRIVATE KEY-----' }),
+   * }))
+   * ```
+   */
+  clientAssertionSigningKey?: KeyInput | KeyObject | JSONWebKey;
+
+  /**
+   * The algorithm to sign the client assertion JWT.
+   * Uses one of `token_endpoint_auth_signing_alg_values_supported` if not specified.
+   * If the Authorization Server discovery document does not list `token_endpoint_auth_signing_alg_values_supported`
+   * this property will be required.
+   */
+  clientAssertionSigningAlg?:
+    | 'RS256'
+    | 'RS384'
+    | 'RS512'
+    | 'PS256'
+    | 'PS384'
+    | 'PS512'
+    | 'ES256'
+    | 'ES256K'
+    | 'ES384'
+    | 'ES512'
+    | 'EdDSA';
+
+  /**
+   * Additional request body properties to be sent to the `token_endpoint` during authorization code exchange or token refresh.
+   */
+  tokenEndpointParams?: TokenParameters;
+
+  /**
+   * Maximum time (in milliseconds) to wait before fetching the Identity Provider's Discovery document again. Default is 600000 (10 minutes).
+   */
+  discoveryCacheMaxAge?: number;
+
+  /**
+   * Http timeout for oidc client requests in milliseconds.  Default is 5000.   Minimum is 500.
+   */
+  httpTimeout?: number;
+
+  /**
+   * Specify an Agent or Agents to pass to the underlying http client https://github.com/sindresorhus/got/
+   *
+   * An object representing `http`, `https` and `http2` keys for [`http.Agent`](https://nodejs.org/api/http.html#http_class_http_agent),
+   * [`https.Agent`](https://nodejs.org/api/https.html#https_class_https_agent) and [`http2wrapper.Agent`](https://github.com/szmarczak/http2-wrapper#new-http2agentoptions) instance.
+   *
+   * See https://github.com/sindresorhus/got/blob/v11.8.6/readme.md#agent
+   *
+   * For a proxy agent see https://www.npmjs.com/package/proxy-agent
+   */
+  httpAgent?: {
+    http?: HttpAgent | false;
+    https?: HttpsAgent | false;
+    http2?: unknown | false;
+  };
+
+  /**
+   * Optional User-Agent header value for oidc client requests.  Default is `express-openid-connect/{version}`.
+   */
+  httpUserAgent?: string;
+}
+
+interface SessionStorePayload<Data = Session> {
+  header: {
+    /**
+     * timestamp (in secs) when the session was created.
+     */
+    iat: number;
+    /**
+     * timestamp (in secs) when the session was last touched.
+     */
+    uat: number;
+    /**
+     * timestamp (in secs) when the session expires.
+     */
+    exp: number;
+  };
+
+  /**
+   * The session data.
+   */
+  data: Data;
+
+  /**
+   * This makes it compatible with some `express-session` stores that use this
+   * to set their ttl.
+   */
+  cookie: {
+    expires: number;
+    maxAge: number;
+  };
+}
+
+interface SessionStore<Data = Session> {
+  /**
+   * Gets the session from the store given a session ID and passes it to `callback`.
+   */
+  get(
+    sid: string,
+    callback: (err: any, session?: SessionStorePayload<Data> | null) => void
+  ): void;
+
+  /**
+   * Upsert a session in the store given a session ID and `SessionData`
+   */
+  set(
+    sid: string,
+    session: SessionStorePayload<Data>,
+    callback?: (err?: any) => void
+  ): void;
+
+  /**
+   * Destroys the session with the given session ID.
+   */
+  destroy(sid: string, callback?: (err?: any) => void): void;
+
+  [key: string]: any;
+}
+
+/**
+ * Configuration parameters used for the application session.
+ */
+interface SessionConfigParams {
+  /**
+   * String value for the cookie name used for the internal session.
+   * This value must only include letters, numbers, and underscores.
+   * Default is `appSession`.
+   */
+  name?: string;
+
+  /**
+   * By default the session is stored in an encrypted cookie. But when the session
+   * gets too large it can bump up against the limits of cookie storage.
+   * In these instances you can use a custom session store. The store should
+   * have `get`, `set` and `destroy` methods, making it compatible
+   * with [express-session stores](https://github.com/expressjs/session#session-store-implementation).
+   */
+  store?: SessionStore;
+
+  /**
+   * A Function for generating a session id when using a custom session store.
+   * For full details see the documentation for express-session
+   * at [genid](https://github.com/expressjs/session/blob/master/README.md#genid).
+   *
+   * Be aware the default implementation is slightly different in this library as
+   * compared to the default session id generation used in express-session.
+   *
+   * **IMPORTANT** If you override this method you should be careful to generate
+   * unique IDs so your sessions do not conflict. Also, to reduce the ability
+   * to hijack a session by guessing the session ID, you must use a suitable
+   * cryptographically strong random value of sufficient size or sign the cookie
+   * by setting {@Link signSessionStoreCookie} to `true`.
+   */
+  genid?: (req: OpenidRequest) => Promise<string> | string;
+
+  /**
+   * Sign the session store cookies to reduce the chance of collisions
+   * and reduce the ability to hijack a session by guessing the session ID.
+   *
+   * This is required if you override {@Link genid} and don't use a suitable
+   * cryptographically strong random value of sufficient size.
+   */
+  signSessionStoreCookie?: boolean;
+
+  /**
+   * If you enable {@Link signSessionStoreCookie} your existing sessions will
+   * be invalidated. You can use this flag to temporarily allow unsigned cookies
+   * while you sign your user's session cookies. For example:
+   *
+   * Set {@Link signSessionStoreCookie} to `true` and {@Link requireSignedSessionStoreCookie} to `false`.
+   * Wait for your {@Link rollingDuration} (default 1 day) or {@Link absoluteDuration} (default 1 week)
+   * to pass (which ever comes first). By this time all your sessions cookies will either be signed or
+   * have expired, then you can remove the {@Link requireSignedSessionStoreCookie} config option which
+   * will set it to `true`.
+   *
+   * Signed session store cookies will be mandatory in the next major release.
+   */
+  requireSignedSessionStoreCookie?: boolean;
+
+  /**
+   * 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`.
+   */
+  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.
+   * Default is 86400 seconds (1 day).
+   */
+  rollingDuration?: number;
+
+  /**
+   * 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).
+   */
+  absoluteDuration?: boolean | number;
+
+  /**
+   * Configuration parameters used for the session cookie and transient cookies.
+   */
+  cookie?: CookieConfigParams;
+}
+
+interface CookieConfigParams {
+  /**
+   * Domain name for the cookie.
+   * 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`
+   */
+  path?: string;
+
+  /**
+   * Set to true to use a transient cookie (cookie without an explicit expiration).
+   * Default is `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`.
+   * 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`.
+   * Defaults to the protocol of {@link ConfigParams.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}.
+   * When setting to 'None' (uncommon), you should implement CSRF protection on your own routes
+   */
+  sameSite?: string;
+}
+
+interface AccessToken {
+  /**
+   * The access token itself, can be an opaque string, JWT, or non-JWT token.
+   */
+  access_token: string;
+
+  /**
+   * The type of access token, Usually "Bearer".
+   */
+  token_type: string;
+
+  /**
+   * Number of seconds until the access token expires.
+   */
+  expires_in: number;
+
+  /**
+   * Returns `true` if the access_token has expired.
+   */
+  isExpired: () => boolean;
+
+  /**
+   * Performs refresh_token grant type exchange and updates the session's access token.
+   *
+   * ```js
+   * let accessToken = req.oidc.accessToken;
+   * if (accessToken.isExpired()) {
+   *   accessToken = await accessToken.refresh();
+   * }
+   * ```
+   */
+  refresh(params?: RefreshParams): Promise<AccessToken>;
+}
+
+interface RefreshParams {
+  tokenEndpointParams?: TokenParameters;
+}
+
+interface TokenParameters {
+  [key: string]: unknown;
+}
+
+/**
+ * Express JS middleware implementing sign on for Express web apps using OpenID Connect.
+ *
+ * The `auth()` middleware requires {@link ConfigParams.secret secret}, {@link ConfigParams.baseURL baseURL}, {@link ConfigParams.clientID clientID}
+ * and {@link ConfigParams.issuerBaseURL issuerBaseURL}.
+ *
+ * If you are using a response type that includes `code`, you will also need: {@link ConfigParams.clientSecret clientSecret}
+ * ```
+ * const express = require('express');
+ * const { auth } = require('express-openid-connect');
+ *
+ * const app = express();
+ *
+ * app.use(
+ *   auth({
+ *      issuerBaseURL: 'https://YOUR_DOMAIN',
+ *      baseURL: 'https://YOUR_APPLICATION_ROOT_URL',
+ *      clientID: 'YOUR_CLIENT_ID',
+ *      secret: 'LONG_RANDOM_STRING',
+ *   })
+ * );
+ *
+ * app.get('/', (req, res) => {
+ *   res.send(`hello ${req.oidc.user.name}`);
+ * });
+ *
+ *  app.listen(3000, () => console.log('listening at http://localhost:3000'))
+ * ```
+ */
+export function auth(params?: ConfigParams): RequestHandler;
+
+/**
+ * Set {@link ConfigParams.authRequired authRequired} to `false` then require authentication
+ * on specific routes.
+ *
+ * ```js
+ * const { auth, requiresAuth } = require('express-openid-connect');
+ *
+ * app.use(
+ *   auth({
+ *      ...
+ *      authRequired: false
+ *   })
+ * );
+ *
+ * app.get('/profile', requiresAuth(), (req, res) => {
+ *   res.send(`hello ${req.oidc.user.name}`);
+ * });
+ *
+ * ```
+ */
+export function requiresAuth(
+  requiresLoginCheck?: (req: OpenidRequest) => boolean
+): RequestHandler;
+
+/**
+ * Use this MW to protect a route based on the value of a specific claim.
+ *
+ * ```js
+ * const { claimEquals } = require('express-openid-connect');
+ *
+ * app.get('/admin', claimEquals('isAdmin', true), (req, res) => {
+ *   res.send(...);
+ * });
+ *
+ * ```
+ *
+ * @param claim The name of the claim
+ * @param value The value of the claim, should be a primitive
+ */
+export function claimEquals(
+  claim: string,
+  value: boolean | number | string | null
+): RequestHandler;
+
+/**
+ * Use this MW to protect a route, checking that _all_ values are in a claim.
+ *
+ * ```js
+ * const { claimIncludes } = require('express-openid-connect');
+ *
+ * app.get('/admin/delete', claimIncludes('roles', 'admin', 'superadmin'), (req, res) => {
+ *   res.send(...);
+ * });
+ *
+ * ```
+ *
+ * @param claim The name of the claim
+ * @param args Claim values that must all be included
+ */
+export function claimIncludes(
+  claim: string,
+  ...args: (boolean | number | string | null)[]
+): RequestHandler;
+
+/**
+ * Use this MW to protect a route, providing a custom function to check.
+ *
+ * ```js
+ * const { claimCheck } = require('express-openid-connect');
+ *
+ * app.get('/admin/community', claimCheck((req, claims) => {
+ *   return claims.isAdmin && claims.roles.includes('community');
+ * }), (req, res) => {
+ *   res.send(...);
+ * });
+ *
+ * ```
+ */
+export function claimCheck(
+  checkFn: (req: OpenidRequest, claims: IdTokenClaims) => boolean
+): RequestHandler;
+
+/**
+ * Use this MW to attempt silent login (`prompt=none`) but not require authentication.
+ *
+ * See {@link ConfigParams.attemptSilentLogin attemptSilentLogin}
+ *
+ * ```js
+ * const { attemptSilentLogin } = require('express-openid-connect');
+ *
+ * app.get('/', attemptSilentLogin(), (req, res) => {
+ *   res.render('homepage', {
+ *     isAuthenticated: req.isAuthenticated() // show a login or logout button
+ *   });
+ * });
+ *
+ * ```
+ */
+export function attemptSilentLogin(): RequestHandler;