mocktp 0.0.1-security → 3.15.3

package/src/pluggable-admin-api/mockttp-pluggable-admin.browser.ts

@@ -0,0 +1,7 @@
+export class MockttpAdminPlugin {
+    constructor() {
+        throw new Error("MockttpAdminPlugin cannot be used within a browser");
+    }
+}
+
+export { MockttpAdminRequestBuilder } from "../client/mockttp-admin-request-builder";

package/src/pluggable-admin-api/mockttp-pluggable-admin.ts

@@ -0,0 +1,13 @@
+/**
+ * This is part of the new 'Pluggable Admin' API.
+ *
+ * Everything exported here is experimental, and many change unpredictably in future releases.
+ */
+
+export {
+    MockttpAdminPlugin,
+    MockttpPluginOptions,
+    MockttpClientResponse
+} from "../admin/mockttp-admin-plugin";
+
+export { MockttpAdminRequestBuilder } from "../client/mockttp-admin-request-builder";

package/src/pluggable-admin-api/pluggable-admin.browser.ts

@@ -0,0 +1,9 @@
+export class AdminServer {
+    constructor() {
+        throw new Error("AdminServer cannot be used within a browser");
+    }
+}
+
+export { AdminClient } from "../client/admin-client";
+
+export * as Serialization from '../serialization/serialization';

package/src/pluggable-admin-api/pluggable-admin.ts

@@ -0,0 +1,36 @@
+/**
+ * This file exports the core pluggable admin types, without anything Mockttp-specific
+ * included. That's useful so that downstream usage of pluggable without Mockttp doesn't
+ * need to load all our dependencies (especially heavy things like brotli-wasm).
+ *
+ * In future these parts might be extracted into a separate library, but it's a bit tricky
+ * to do so immediately as the server side does actually include some unavoidable Mockttp
+ * dependencies for API backward compatibility.
+ *
+ * Everything exported here is experimental, and many change unpredictably in future releases.
+ */
+
+export type {
+    AdminPlugin,
+    PluginStartParams,
+    PluginStartParamsMap,
+    PluginClientResponse,
+    PluginClientResponsesMap
+} from "../admin/admin-plugin-types";
+
+export {
+    AdminServer,
+    AdminServerOptions
+} from "../admin/admin-server";
+
+export type {
+    AdminQuery,
+    QueryContext
+} from "../client/admin-query";
+export type { SchemaIntrospector } from "../client/schema-introspection";
+export {
+    AdminClient,
+    AdminClientOptions
+} from "../client/admin-client";
+
+export * as Serialization from '../serialization/serialization';

package/src/rules/base-rule-builder.ts

@@ -0,0 +1,312 @@
+import { isString } from "lodash";
+import { MaybePromise } from "../main";
+
+import { CompletedRequest, Method, RulePriority } from "../types";
+
+import {
+    RuleCompletionChecker,
+    Always,
+    NTimes,
+    Thrice,
+    Twice,
+    Once
+} from "./completion-checkers";
+
+import {
+    RequestMatcher,
+    HeaderMatcher,
+    QueryMatcher,
+    MultipartFieldMatchCondition,
+    MultipartFormDataMatcher,
+    FormDataMatcher,
+    RawBodyMatcher,
+    RawBodyIncludesMatcher,
+    CookieMatcher,
+    RegexBodyMatcher,
+    JsonBodyMatcher,
+    JsonBodyFlexibleMatcher,
+    ExactQueryMatcher,
+    HostMatcher,
+    CallbackMatcher,
+    HostnameMatcher,
+    PortMatcher,
+    ProtocolMatcher,
+    RegexUrlMatcher
+} from "./matchers";
+
+/**
+ * @class BaseRuleBuilder
+ *
+ * Defines the base matching & completion methods, used for both normal
+ * and websocket request handling, but excluding the handling itself
+ * which differs between the two cases.
+ */
+export abstract class BaseRuleBuilder {
+
+    /**
+     * Mock rule builders should be constructed through the Mockttp instance you're
+     * using, not directly. You shouldn't ever need to call this constructor.
+     */
+    constructor() {}
+
+    protected matchers: RequestMatcher[] = [];
+
+    private priority: number = RulePriority.DEFAULT;
+    private completionChecker?: RuleCompletionChecker;
+
+    protected buildBaseRuleData() {
+        return {
+            priority: this.priority,
+            matchers: this.matchers,
+            completionChecker: this.completionChecker
+        };
+    }
+
+    /**
+     * Set the rule priority. Any matching rule with a higher priority will always
+     * take precedence over a matching lower-priority rule, unless the higher rule
+     * has an explicit completion check (like `.once()`) that has already been
+     * completed.
+     *
+     * The RulePriority enum defines the standard values useful for most cases,
+     * but any positive number may be used for advanced configurations.
+     *
+     * In many cases it may be simpler to use forUnmatchedRequest() to set a fallback
+     * rule explicitly, rather than manually setting the priority here.
+     */
+    asPriority(priority: RulePriority | number): this {
+        this.priority = priority;
+        return this;
+    }
+
+    /**
+     * Match only requests sent to the given host, i.e. the full hostname plus
+     * port included in the request.
+     *
+     * This can behave somewhat confusingly when matching against the default
+     * ports for a protocol (i.e. 80/443), or when specifying a hostname here
+     * without specifying the port. In those cases it's usually better to use
+     * forHostname and/or forPort instead to explicit match the content you're
+     * interested in.
+     *
+     * @category Matching
+     */
+    forHost(host: string): this {
+        this.matchers.push(new HostMatcher(host));
+        return this;
+    }
+
+    /**
+     * Match only requests sent to the given hostname, ignoring the port.
+     *
+     * @category Matching
+     */
+    forHostname(hostname: string): this {
+        this.matchers.push(new HostnameMatcher(hostname));
+        return this;
+    }
+
+    /**
+     * Match only requests sent to the given port.
+     *
+     * @category Matching
+     */
+    forPort(port: number): this {
+        this.matchers.push(new PortMatcher(port));
+        return this;
+    }
+
+    /**
+     * Match only requests that include the given headers.
+     * @category Matching
+     */
+    withHeaders(headers: { [key: string]: string }): this {
+        this.matchers.push(new HeaderMatcher(headers));
+        return this;
+    }
+
+    /**
+     * Match only requests that include the given query parameters.
+     * @category Matching
+     */
+    withQuery(query: { [key: string]: string | number | (string | number)[] }): this {
+        this.matchers.push(new QueryMatcher(query));
+        return this;
+    }
+
+    /**
+     * Match only requests that include the exact query string provided.
+     * The query string must start with a ? or be entirely empty.
+     * @category Matching
+     */
+    withExactQuery(query: string): this {
+        this.matchers.push(new ExactQueryMatcher(query));
+        return this;
+    }
+
+    /**
+     * Match only requests whose bodies include the given URL-encoded form data.
+     * @category Matching
+     */
+    withForm(formData: { [key: string]: string }): this {
+        this.matchers.push(new FormDataMatcher(formData));
+        return this;
+    }
+
+    /**
+     * Match only requests whose bodies include the given multipart form data.
+     *
+     * This can take any number of form parts to look for. Each part is specified
+     * with {@link MultipartFieldMatchCondition} object containing one or more of
+     * `name` (string), `filename` (string) and `content` (string or buffer) as
+     * fields to match against in the form data.
+     *
+     * Requests are matched if all conditions match at least one part in the
+     * request's form data.
+     *
+     * @category Matching
+     */
+    withMultipartForm(...matchConditions: Array<MultipartFieldMatchCondition>): this {
+        this.matchers.push(new MultipartFormDataMatcher(matchConditions));
+        return this;
+    }
+
+    /**
+     * Match only requests whose bodies either exactly match the given string
+     * (if a string is passed) or whose bodies match a regular expression
+     * (if a regex is passed).
+     * @category Matching
+     */
+    withBody(content: string | RegExp): this {
+        this.matchers.push(
+            isString(content)
+                ? new RawBodyMatcher(content)
+                : new RegexBodyMatcher(content)
+        );
+        return this;
+    }
+
+    /**
+     * Match only requests whose bodies include the given string.
+     * @category Matching
+     */
+    withBodyIncluding(content: string): this {
+        this.matchers.push(new RawBodyIncludesMatcher(content));
+        return this;
+    }
+
+    /**
+     * Match only requests whose bodies exactly match the given
+     * object, when parsed as JSON.
+     *
+     * Note that this only tests that the body can be parsed
+     * as JSON - it doesn't require a content-type header.
+     * @category Matching
+     */
+    withJsonBody(json: {}): this {
+        this.matchers.push(
+            new JsonBodyMatcher(json)
+        );
+        return this;
+    }
+
+    /**
+     * Match only requests whose bodies match (contain equivalent
+     * values, ignoring extra values) the given object, when
+     * parsed as JSON. Matching behaviour is the same as Lodash's
+     * _.isMatch method.
+     *
+     * Note that this only tests that the body can be parsed
+     * as JSON - it doesn't require a content-type header.
+     * @category Matching
+     */
+    withJsonBodyIncluding(json: {}): this {
+        this.matchers.push(
+            new JsonBodyFlexibleMatcher(json)
+        );
+        return this;
+    }
+
+    /**
+     * Match only requests that include the given cookies
+     * @category Matching
+     */
+    withCookie(cookie: { [key: string]: string }): this {
+        this.matchers.push(new CookieMatcher(cookie));
+        return this;
+    }
+
+    /**
+     * Match only requests sent with the given protocol.
+     * @category Matching
+     */
+    withProtocol(protocol: "http" | "https" | "ws" | "wss"): this {
+        this.matchers.push(new ProtocolMatcher(protocol));
+        return this;
+    }
+
+    /**
+     * Match only requests whose absolute url matches the given RegExp.
+     * @category Matching
+     */
+    withUrlMatching(pattern: RegExp): this {
+        this.matchers.push(new RegexUrlMatcher(pattern));
+        return this;
+    }
+
+    /**
+     * Match only requests when the callback returns true
+     * @category Matching
+     */
+    matching(
+        content: (request: CompletedRequest) => MaybePromise<boolean>
+    ): this {
+        this.matchers.push(new CallbackMatcher(content));
+        return this;
+    }
+
+    /**
+     * Run this rule forever, for all matching requests
+     * @category Completion
+     */
+    always(): this {
+        this.completionChecker = new Always();
+        return this;
+    }
+
+    /**
+     * Run this rule only once, for the first matching request
+     * @category Completion
+     */
+    once(): this {
+        this.completionChecker = new Once();
+        return this;
+    }
+
+    /**
+     * Run this rule twice, for the first two matching requests
+     * @category Completion
+     */
+    twice(): this {
+        this.completionChecker = new Twice();
+        return this;
+    }
+
+    /**
+     * Run this rule three times, for the first three matching requests
+     * @category Completion
+     */
+    thrice(): this {
+        this.completionChecker = new Thrice();
+        return this;
+    }
+
+    /**
+     * Run this rule the given number of times, for the first matching requests
+     * @category Completion
+     */
+    times(n: number): this {
+        this.completionChecker = new NTimes(n);
+        return this;
+    }
+}

package/src/rules/completion-checkers.ts

@@ -0,0 +1,90 @@
+import { Serializable } from '../serialization/serialization';
+
+export interface RuleCompletionChecker extends Serializable {
+    type: keyof typeof CompletionCheckerLookup;
+    isComplete(seenRequestCount: number): boolean;
+    explain(seenRequestCount: number | undefined): string;
+}
+
+export class Always extends Serializable implements RuleCompletionChecker {
+    readonly type = 'always';
+
+    isComplete() {
+        return false;
+    }
+
+    explain(seenRequestCount: number | undefined) {
+        return explainUntil(seenRequestCount, Infinity, 'always');
+    }
+}
+
+export class Once extends Serializable implements RuleCompletionChecker {
+    readonly type = 'once';
+
+    isComplete(seenRequestCount: number) {
+        return seenRequestCount >= 1;
+    }
+
+    explain(seenRequestCount: number | undefined) {
+        return explainUntil(seenRequestCount, 1, 'once');
+    }
+}
+
+export class Twice extends Serializable implements RuleCompletionChecker {
+    readonly type = 'twice';
+
+    isComplete(seenRequestCount: number) {
+        return seenRequestCount >= 2;
+    }
+
+    explain(seenRequestCount: number | undefined) {
+        return explainUntil(seenRequestCount, 2, 'twice');
+    }
+}
+
+export class Thrice extends Serializable implements RuleCompletionChecker {
+    readonly type = 'thrice';
+
+    isComplete(seenRequestCount: number) {
+        return seenRequestCount >= 3;
+    }
+
+    explain(seenRequestCount: number | undefined) {
+        return explainUntil(seenRequestCount, 3, 'thrice');
+    }
+}
+
+export class NTimes extends Serializable implements RuleCompletionChecker {
+    readonly type = 'times';
+
+    constructor(
+        public count: number
+    ) {
+        super();
+    }
+
+    isComplete(seenRequestCount: number) {
+        return seenRequestCount >= this.count;
+    }
+
+    explain(seenRequestCount: number | undefined) {
+        return explainUntil(seenRequestCount, this.count, `${this.count} times`);
+    }
+}
+
+export const CompletionCheckerLookup = {
+    'always': Always,
+    'once': Once,
+    'twice': Twice,
+    'thrice': Thrice,
+    'times': NTimes
+}
+
+function explainUntil(seen: number | undefined, n: number, name: string): string {
+    if (seen === undefined) {
+        // Generic explainer, without the specific count
+        return name;
+    } else {
+        return name + " " + (seen < n ? `(seen ${seen})` : "(done)");
+    }
+}

package/src/rules/http-agents.ts

@@ -0,0 +1,119 @@
+import * as _ from 'lodash';
+import * as url from 'url';
+import * as http from 'http';
+import * as https from 'https';
+
+import * as LRU from 'lru-cache';
+
+import getHttpsProxyAgent = require('https-proxy-agent');
+import { PacProxyAgent } from 'pac-proxy-agent';
+import { SocksProxyAgent } from 'socks-proxy-agent';
+const getSocksProxyAgent = (opts: any) => new SocksProxyAgent(opts);
+
+import { isNode } from "../util/util";
+import { getProxySetting, matchesNoProxy, ProxySettingSource } from './proxy-config';
+import { getTrustedCAs } from './passthrough-handling';
+
+const KeepAliveAgents = isNode
+    ? { // These are only used (and only available) on the node server side
+        'http:': new http.Agent({
+            keepAlive: true
+        }),
+        'https:': new https.Agent({
+            keepAlive: true
+        })
+    } : {};
+
+const ProxyAgentFactoryMap = {
+    'http:': getHttpsProxyAgent, // HTTPS here really means 'CONNECT-tunnelled' - it can do either
+    'https:': getHttpsProxyAgent,
+
+    'pac+http:': (...args: any) => new PacProxyAgent(...args),
+    'pac+https:': (...args: any) => new PacProxyAgent(...args),
+
+    'socks:': getSocksProxyAgent,
+    'socks4:': getSocksProxyAgent,
+    'socks4a:': getSocksProxyAgent,
+    'socks5:': getSocksProxyAgent,
+    'socks5h:': getSocksProxyAgent
+} as const;
+
+const proxyAgentCache = new LRU<string, http.Agent>({
+    max: 20,
+
+    ttl: 1000 * 60 * 5, // Drop refs to unused agents after 5 minutes
+    ttlResolution: 1000 * 60, // Check for expiry once every minute maximum
+    ttlAutopurge: true, // Actively drop expired agents
+    updateAgeOnGet: true // Don't drop agents while they're in use
+});
+
+const getCacheKey = (options: {}) => JSON.stringify(options);
+
+export async function getAgent({
+    protocol, hostname, port, tryHttp2, keepAlive, proxySettingSource
+}: {
+    protocol: 'http:' | 'https:' | 'ws:' | 'wss:' | undefined,
+    hostname: string,
+    port: number,
+    tryHttp2: boolean,
+    keepAlive: boolean
+    proxySettingSource: ProxySettingSource
+}): Promise<http.Agent | undefined> { // <-- We force this cast for convenience in various different uses later
+    const proxySetting = await getProxySetting(proxySettingSource, { hostname });
+
+    if (proxySetting?.proxyUrl) {
+        // If there's a (non-empty) proxy configured, use it. We require non-empty because empty strings
+        // will fall back to detecting from the environment, which is likely to behave unexpectedly.
+
+        if (!matchesNoProxy(hostname, port, proxySetting.noProxy)) {
+            // We notably ignore HTTP/2 upstream in this case: it's complicated to mix that up with proxying
+            // so for now we ignore it entirely.
+
+            const cacheKey = getCacheKey({
+                url: proxySetting.proxyUrl,
+                trustedCAs: proxySetting.trustedCAs,
+                additionalTrustedCAs: proxySetting.additionalTrustedCAs
+            });
+
+            if (!proxyAgentCache.has(cacheKey)) {
+                const { href, protocol, auth, hostname, port } = url.parse(proxySetting.proxyUrl);
+                const buildProxyAgent = ProxyAgentFactoryMap[protocol as keyof typeof ProxyAgentFactoryMap];
+
+                // If you specify trusted CAs, we override the CAs used for this connection, i.e. the trusted
+                // CA for the certificate of an HTTPS proxy. This is *not* the CAs trusted for upstream servers
+                // on the otherside of the proxy - see the corresponding passthrough options for that.
+                const trustedCerts = await getTrustedCAs(
+                    proxySetting.trustedCAs,
+                    proxySetting.additionalTrustedCAs
+                );
+
+                proxyAgentCache.set(cacheKey, buildProxyAgent({
+                    href,
+                    protocol,
+                    auth,
+                    hostname,
+                    port,
+
+                    ...(trustedCerts
+                        ? { ca: trustedCerts }
+                        : {}
+                    )
+                }));
+            }
+
+            return proxyAgentCache.get(cacheKey);
+        }
+    }
+
+    if (tryHttp2 && (protocol === 'https:' || protocol === 'wss:')) {
+        // H2 wrapper takes multiple agents, uses the appropriate one for the detected protocol.
+        // We notably never use H2 upstream for plaintext, it's rare and we can't use ALPN to detect it.
+        return { https: KeepAliveAgents['https:'], http2: undefined } as any as http.Agent;
+    } else if (keepAlive && protocol !== 'wss:' && protocol !== 'ws:') {
+        // HTTP/1.1 or HTTP/1 with explicit keep-alive
+        return KeepAliveAgents[protocol || 'http:']
+    } else {
+        // HTTP/1 without KA - just send the request with no agent
+        return undefined;
+    }
+}