@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/types/middleware/interfaces/express-rate-limit.interface.d.ts

@@ -0,0 +1,292 @@
+import { Request, Response, NextFunction } from "express";
+/**
+ * Method (in the form of middleware) to generate/retrieve a value based on the
+ * incoming request.
+ *
+ * @param request {Request} - The Express request object.
+ * @param response {Response} - The Express response object.
+ *
+ * @returns {T} - The value needed.
+ */
+type ValueDeterminingMiddleware<T> = (request: Request, response: Response) => T | Promise<T>;
+/**
+ * Express request handler that sends back a response when a client is
+ * rate-limited.
+ * @param request {Request} - The Express request object.
+ * @param response {Response} - The Express response object.
+ * @param next {NextFunction} - The Express `next` function, can be called to skip responding.
+ * @param optionsUsed {Options} - The options used to set up the middleware.
+ */
+type RateLimitExceededEventHandler = (request: Request, response: Response, next: NextFunction, optionsUsed: RateLimitOptions) => void;
+/**
+ * Data returned from the `Store` when a client's hit counter is incremented.
+ *
+ * @property totalHits {number} - The number of hits for that client so far.
+ * @property resetTime {Date | undefined} - The time when the counter resets.
+ */
+type ClientRateLimitInfo = {
+    totalHits: number;
+    resetTime: Date | undefined;
+};
+type IncrementResponse = ClientRateLimitInfo;
+/**
+ * An interface that all hit counter stores must implement.
+ */
+interface Store {
+    /**
+     * Method that initializes the store, and has access to the options passed to
+     * the middleware too.
+     *
+     * @param options {Options} - The options used to setup the middleware.
+     */
+    init?: (options: RateLimitOptions) => void;
+    /**
+     * Method to fetch a client's hit count and reset time.
+     *
+     * @param key {string} - The identifier for a client.
+     *
+     * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+     */
+    get?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
+    /**
+     * Method to increment a client's hit counter.
+     *
+     * @param key {string} - The identifier for a client.
+     *
+     * @returns {IncrementResponse | undefined} - The number of hits and reset time for that client.
+     */
+    increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
+    /**
+     * Method to decrement a client's hit counter.
+     *
+     * @param key {string} - The identifier for a client.
+     */
+    decrement: (key: string) => Promise<void> | void;
+    /**
+     * Method to reset a client's hit counter.
+     *
+     * @param key {string} - The identifier for a client.
+     */
+    resetKey: (key: string) => Promise<void> | void;
+    /**
+     * Method to reset everyone's hit counter.
+     */
+    resetAll?: () => Promise<void> | void;
+    /**
+     * Method to shutdown the store, stop timers, and release all resources.
+     */
+    shutdown?: () => Promise<void> | void;
+    /**
+     * Flag to indicate that keys incremented in one instance of this store can
+     * not affect other instances. Typically false if a database is used, true for
+     * MemoryStore.
+     *
+     * Used to help detect double-counting misconfigurations.
+     */
+    localKeys?: boolean;
+    /**
+     * Optional value that the store prepends to keys
+     *
+     * Used by the double-count check to avoid false-positives when a key is counted twice, but with different prefixes
+     */
+    prefix?: string;
+}
+interface Validations {
+    enabled: {
+        [key: string]: boolean;
+    };
+    disable(): void;
+    /**
+     * Checks whether the IP address is valid, and that it does not have a port
+     * number in it.
+     *
+     * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_invalid_ip_address.
+     *
+     * @param ip {string | undefined} - The IP address provided by Express as request.ip.
+     *
+     * @returns {void}
+     */
+    ip(ip: string | undefined): void;
+    /**
+     * Makes sure the trust proxy setting is not set to `true`.
+     *
+     * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_permissive_trust_proxy.
+     *
+     * @param request {Request} - The Express request object.
+     *
+     * @returns {void}
+     */
+    trustProxy(request: Request): void;
+    /**
+     * Makes sure the trust proxy setting is set in case the `X-Forwarded-For`
+     * header is present.
+     *
+     * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_unset_trust_proxy.
+     *
+     * @param request {Request} - The Express request object.
+     *
+     * @returns {void}
+     */
+    xForwardedForHeader(request: Request): void;
+    /**
+     * Ensures totalHits value from store is a positive integer.
+     *
+     * @param hits {any} - The `totalHits` returned by the store.
+     */
+    positiveHits(hits: any): void;
+    /**
+     * Ensures a given key is incremented only once per request.
+     *
+     * @param request {Request} - The Express request object.
+     * @param store {Store} - The store class.
+     * @param key {string} - The key used to store the client's hit count.
+     *
+     * @returns {void}
+     */
+    singleCount(request: Request, store: Store, key: string): void;
+    /**
+     * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
+     * major release.
+     *
+     * @param limit {number} - The maximum number of hits per client.
+     *
+     * @returns {void}
+     */
+    limit(limit: number): void;
+    /**
+     * Warns the user that the `draft_polli_ratelimit_headers` option is deprecated
+     * and will be removed in the next major release.
+     *
+     * @param draft_polli_ratelimit_headers {any | undefined} - The now-deprecated setting that was used to enable standard headers.
+     *
+     * @returns {void}
+     */
+    draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
+    /**
+     * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
+     * major release.
+     *
+     * @param onLimitReached {any | undefined} - The maximum number of hits per client.
+     *
+     * @returns {void}
+     */
+    onLimitReached(onLimitReached?: any): void;
+    /**
+     * Warns the user when the selected headers option requires a reset time but
+     * the store does not provide one.
+     *
+     * @param resetTime {Date | undefined} - The timestamp when the client's hit count will be reset.
+     *
+     * @returns {void}
+     */
+    headersResetTime(resetTime?: Date): void;
+    /**
+     * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+     *
+     * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+     */
+    validationsConfig(): void;
+}
+type DraftHeadersVersion = "draft-6" | "draft-7";
+interface RateLimitOptions {
+    /**
+     * How long we should remember the requests.
+     *
+     * Defaults to `60000` ms (= 1 minute).
+     */
+    windowMs?: number;
+    /**
+     * The maximum number of connections to allow during the `window` before
+     * rate limiting the client.
+     *
+     * Can be the limit itself as a number or express middleware that parses
+     * the request and then figures out the limit.
+     *
+     * Defaults to `5`.
+     */
+    limit?: number | ValueDeterminingMiddleware<number>;
+    /**
+     * The response body to send back when a client is rate limited.
+     *
+     * Defaults to `'Too many requests, please try again later.'`
+     */
+    message?: any | ValueDeterminingMiddleware<any>;
+    /**
+     * The HTTP status code to send back when a client is rate limited.
+     *
+     * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).
+     */
+    statusCode?: number;
+    /**
+     * Whether to send `X-RateLimit-*` headers with the rate limit and the number
+     * of requests.
+     *
+     * Defaults to `true` (for backward compatibility).
+     */
+    legacyHeaders?: boolean;
+    /**
+     * Whether to enable support for the standardized rate limit headers (`RateLimit-*`).
+     *
+     * Defaults to `false` (for backward compatibility, but its use is recommended).
+     */
+    standardHeaders?: false | DraftHeadersVersion;
+    /**
+     * The name of the property on the request object to store the rate limit info.
+     *
+     * Defaults to `rateLimit`.
+     */
+    requestPropertyName?: string;
+    /**
+     * If `true`, the library will (by default) skip all requests that have a 4XX
+     * or 5XX status.
+     *
+     * Defaults to `false`.
+     */
+    skipFailedRequests?: boolean;
+    /**
+     * If `true`, the library will (by default) skip all requests that have a
+     * status code less than 400.
+     *
+     * Defaults to `false`.
+     */
+    skipSuccessfulRequests?: boolean;
+    /**
+     * Method to generate custom identifiers for clients.
+     *
+     * By default, the client's IP address is used.
+     */
+    keyGenerator?: ValueDeterminingMiddleware<string>;
+    /**
+     * Express request handler that sends back a response when a client is
+     * rate-limited.
+     *
+     * By default, sends back the `statusCode` and `message` set via the options.
+     */
+    handler?: RateLimitExceededEventHandler;
+    /**
+     * Method (in the form of middleware) to determine whether or not this request
+     * counts towards a client's quota.
+     *
+     * By default, skips no requests.
+     */
+    skip?: ValueDeterminingMiddleware<boolean>;
+    /**
+     * Method to determine whether or not the request counts as 'succesful'. Used
+     * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
+     *
+     * By default, requests with a response status code less than 400 are considered
+     * successful.
+     */
+    requestWasSuccessful?: ValueDeterminingMiddleware<boolean>;
+    /**
+     * The `Store` to use to store the hit count for each client.
+     *
+     * By default, the built-in `MemoryStore` will be used.
+     */
+    store?: Store;
+    /**
+     * The list of validation checks that should run.
+     */
+    validations?: Validations;
+}
+export { RateLimitOptions };

package/lib/esm/types/middleware/interfaces/express-session.interface.d.ts

@@ -0,0 +1,207 @@
+import { Request } from "express";
+interface SessionData {
+    cookie: Cookie;
+}
+interface Cookie extends CookieOptions {
+    /** Returns the original `maxAge` (time-to-live), in milliseconds, of the session cookie. */
+    originalMaxAge: number | null;
+}
+interface Session {
+    id: string;
+    cookie: Cookie;
+    regenerate(callback: (err: any) => void): this;
+    destroy(callback: (err: any) => void): this;
+    reload(callback: (err: any) => void): this;
+    resetMaxAge(): this;
+    save(callback?: (err: any) => void): this;
+    touch(): this;
+}
+interface Store {
+    regenerate(req: Request, callback: (err?: any) => any): void;
+    load(sid: string, callback: (err: any, session?: SessionData) => any): void;
+    createSession(req: Request, session: SessionData): Session & SessionData;
+    get(sid: string, callback: (err: any, session?: SessionData | null) => void): void;
+    set(sid: string, session: SessionData, callback?: (err?: any) => void): void;
+    destroy(sid: string, callback?: (err?: any) => void): void;
+    all?(callback: (err: any, obj?: Array<SessionData> | {
+        [sid: string]: SessionData;
+    } | null) => void): void;
+    length?(callback: (err: any, length?: number) => void): void;
+    clear?(callback?: (err?: any) => void): void;
+    touch?(sid: string, session: SessionData, callback?: () => void): void;
+}
+interface CookieOptions {
+    /**
+     * Specifies the number (in milliseconds) to use when calculating the `Expires Set-Cookie` attribute.
+     * This is done by taking the current server time and adding `maxAge` milliseconds to the value to calculate an `Expires` datetime. By default, no maximum age is set.
+     *
+     * If both `expires` and `maxAge` are set in the options, then the last one defined in the object is what is used.
+     * `maxAge` should be preferred over `expires`.
+     *
+     * @see expires
+     */
+    maxAge?: number | undefined;
+    signed?: boolean | undefined;
+    /**
+     * Specifies the `Date` object to be the value for the `Expires Set-Cookie` attribute.
+     * By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application.
+     *
+     * If both `expires` and `maxAge` are set in the options, then the last one defined in the object is what is used.
+     *
+     * @deprecated The `expires` option should not be set directly; instead only use the `maxAge` option
+     * @see maxAge
+     */
+    expires?: Date | null | undefined;
+    /**
+     * Specifies the boolean value for the `HttpOnly Set-Cookie` attribute. When truthy, the `HttpOnly` attribute is set, otherwise it is not.
+     * By default, the `HttpOnly` attribute is set.
+     *
+     * Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Specifies the value for the `Path Set-Cookie` attribute.
+     * By default, this is set to '/', which is the root path of the domain.
+     */
+    path?: string | undefined;
+    /**
+     * Specifies the value for the `Domain Set-Cookie` attribute.
+     * By default, no domain is set, and most clients will consider the cookie to apply to only the current domain.
+     */
+    domain?: string | undefined;
+    /**
+     * Specifies the boolean value for the `Secure Set-Cookie` attribute. When truthy, the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
+     * Be careful when setting this to true, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection.
+     *
+     * Please note that `secure: true` is a **recommended option**.
+     * However, it requires an https-enabled website, i.e., HTTPS is necessary for secure cookies.
+     * If `secure` is set, and you access your site over HTTP, **the cookie will not be set**.
+     *
+     * The cookie.secure option can also be set to the special value `auto` to have this setting automatically match the determined security of the connection.
+     * Be careful when using this setting if the site is available both as HTTP and HTTPS, as once the cookie is set on HTTPS, it will no longer be visible over HTTP.
+     * This is useful when the Express "trust proxy" setting is properly setup to simplify development vs production configuration.
+     *
+     * If you have your node.js behind a proxy and are using `secure: true`, you need to set "trust proxy" in express. Please see the [README](https://github.com/expressjs/session) for details.
+     *
+     * Please see the [README](https://github.com/expressjs/session) for an example of using secure cookies in production, but allowing for testing in development based on NODE_ENV.
+     */
+    secure?: boolean | "auto" | undefined;
+    encode?: ((val: string) => string) | undefined;
+    /**
+     * Specifies the boolean or string to be the value for the `SameSite Set-Cookie` attribute.
+     * - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+     * - `false` will not set the `SameSite` attribute.
+     * - `lax` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
+     * - `none` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
+     * - `strict` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+     *
+     * More information about the different enforcement levels can be found in the specification.
+     *
+     * **Note:** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     */
+    sameSite?: boolean | "lax" | "strict" | "none" | undefined;
+}
+interface SessionOptions {
+    /**
+     * This is the secret used to sign the session cookie. This can be either a string for a single secret, or an array of multiple secrets.
+     * If an array of secrets is provided, **only the first element will be used to sign** the session ID cookie,
+     *   while **all the elements will be considered when verifying the signature** in requests.
+     * The secret itself should be not easily parsed by a human and would best be a random set of characters
+     *
+     * Best practices may include:
+     * - The use of environment variables to store the secret, ensuring the secret itself does not exist in your repository.
+     * - Periodic updates of the secret, while ensuring the previous secret is in the array.
+     *
+     * Using a secret that cannot be guessed will reduce the ability to hijack a session to only guessing the session ID (as determined by the `genid` option).
+     *
+     * Changing the secret value will invalidate all existing sessions.
+     * In order to rotate the secret without invalidating sessions, provide an array of secrets,
+     *   with the new secret as first element of the array, and including previous secrets as the later elements.
+     */
+    secret: string | Array<string>;
+    /**
+     * Function to call to generate a new session ID. Provide a function that returns a string that will be used as a session ID.
+     * The function is given the request as the first argument if you want to use some value attached to it when generating the ID.
+     *
+     * The default value is a function which uses the uid-safe library to generate IDs.
+     * Be careful to generate unique IDs so your sessions do not conflict.
+     */
+    genid?(req: Express.Request): string;
+    /**
+     * The name of the session ID cookie to set in the response (and read from in the request).
+     * The default value is 'connect.sid'.
+     *
+     * Note if you have multiple apps running on the same hostname (this is just the name, i.e. `localhost` or `127.0.0.1`; different schemes and ports do not name a different hostname),
+     *   then you need to separate the session cookies from each other.
+     * The simplest method is to simply set different names per app.
+     */
+    name?: string | undefined;
+    /**
+     * The session store instance, defaults to a new `MemoryStore` instance.
+     * @see MemoryStore
+     */
+    store?: Store | undefined;
+    /**
+     * Settings object for the session ID cookie.
+     * @see CookieOptions
+     */
+    cookie?: CookieOptions | undefined;
+    /**
+     * Force the session identifier cookie to be set on every response. The expiration is reset to the original `maxAge`, resetting the expiration countdown.
+     * The default value is `false`.
+     *
+     * With this enabled, the session identifier cookie will expire in `maxAge` *since the last response was sent* instead of in `maxAge` *since the session was last modified by the server*.
+     * This is typically used in conjuction with short, non-session-length `maxAge` values to provide a quick timeout of the session data
+     *   with reduced potential of it occurring during on going server interactions.
+     *
+     * Note that when this option is set to `true` but the `saveUninitialized` option is set to `false`, the cookie will not be set on a response with an uninitialized session.
+     * This option only modifies the behavior when an existing session was loaded for the request.
+     *
+     * @see saveUninitialized
+     */
+    rolling?: boolean | undefined;
+    /**
+     * Forces the session to be saved back to the session store, even if the session was never modified during the request.
+     * Depending on your store this may be necessary, but it can also create race conditions where a client makes two parallel requests to your server
+     *   and changes made to the session in one request may get overwritten when the other request ends, even if it made no changes (this behavior also depends on what store you're using).
+     *
+     * The default value is `true`, but using the default has been deprecated, as the default will change in the future.
+     * Please research into this setting and choose what is appropriate to your use-case. Typically, you'll want `false`.
+     *
+     * How do I know if this is necessary for my store? The best way to know is to check with your store if it implements the `touch` method.
+     * If it does, then you can safely set `resave: false`.
+     * If it does not implement the `touch` method and your store sets an expiration date on stored sessions, then you likely need `resave: true`.
+     */
+    resave?: boolean | undefined;
+    /**
+     * Trust the reverse proxy when setting secure cookies (via the "X-Forwarded-Proto" header).
+     * The default value is undefined.
+     *
+     * - `true`: The `X-Forwarded-Proto` header will be used.
+     * - `false`: All headers are ignored and the connection is considered secure only if there is a direct TLS/SSL connection.
+     * - `undefined`: Uses the "trust proxy" setting from express
+     */
+    proxy?: boolean | undefined;
+    /**
+     * Forces a session that is "uninitialized" to be saved to the store. A session is uninitialized when it is new but not modified.
+     * Choosing `false` is useful for implementing login sessions, reducing server storage usage, or complying with laws that require permission before setting a cookie.
+     * Choosing `false` will also help with race conditions where a client makes multiple parallel requests without a session.
+     *
+     * The default value is `true`, but using the default has been deprecated, as the default will change in the future.
+     * Please research into this setting and choose what is appropriate to your use-case.
+     *
+     * **If you are using `express-session` in conjunction with PassportJS:**
+     * Passport will add an empty Passport object to the session for use after a user is authenticated, which will be treated as a modification to the session, causing it to be saved.
+     * This has been fixed in PassportJS 0.3.0.
+     */
+    saveUninitialized?: boolean | undefined;
+    /**
+     * Control the result of unsetting req.session (through delete, setting to null, etc.).
+     * - `destroy`: The session will be destroyed (deleted) when the response ends.
+     * - `keep`: The session in the store will be kept, but modifications made during the request are ignored and not saved.
+     * @default 'keep'
+     */
+    unset?: "destroy" | "keep" | undefined;
+}
+export { SessionOptions };