@quantakrypto/mcp 0.1.0 → 0.2.1

package/HOSTING.md

@@ -27,9 +27,24 @@ hosted endpoint is reachable by untrusted peers. Out of the box `node dist/http.
   gate. The knowledge tools (`explain_finding`, `suggest_hybrid`, `list_rules`)
   are pure and always exposed. The gating is a pure function (`gateHttpTools`),
   unit-tested in `test/http.test.ts`.
-- **Bounds each request.** A 1 MiB request-body cap (always), a per-request tool
-  timeout (`QUANTAKRYPTO_MCP_TIMEOUT_MS`, default 30 s → `504`) and a response-size cap
-  (`QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES`, default 4 MiB → `500`).
+- **Confines the filesystem tools to a root allow-list.** When the FS tools are
+  enabled, every scanned path must resolve inside `QUANTAKRYPTO_MCP_ROOT`
+  (`:`-separated; defaults to the process CWD). `..` traversal and out-of-root
+  absolute paths are rejected (`resolveScanPath` in `src/fsconfig.ts`), so the
+  endpoint cannot be turned into an `/etc/passwd` read oracle.
+- **Validates the request `Origin`.** `POST /mcp` rejects a browser request whose
+  `Origin` host is not loopback (or in `QUANTAKRYPTO_MCP_ALLOW_ORIGIN`) with `403`,
+  blocking DNS-rebinding / localhost-CSRF against the default no-token config.
+  Requests with no `Origin` (CLI / native MCP clients) are unaffected.
+- **Bounds each request.** A 1 MiB request-body cap (`413` only on the cap; a
+  transport read error is `400`), a per-request tool timeout that **aborts the
+  in-flight scan** (`QUANTAKRYPTO_MCP_TIMEOUT_MS`, default 30 s → `504`; no
+  background work leaks past the response), a response-size cap
+  (`QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES`, default 4 MiB → `500`), and per-scan work
+  budgets (`QUANTAKRYPTO_MCP_MAX_FILES` / `QUANTAKRYPTO_MCP_MAX_BYTES`, each capped).
+- **Sanitizes error messages.** Internal failures (an `ENOENT` carrying a server
+  path, a stack trace) are logged to stderr and replaced with a generic message
+  in the wire response, so a remote caller never learns server internals.
 
 | Env var | Default | Purpose |
 | --- | --- | --- |
@@ -37,8 +52,12 @@ hosted endpoint is reachable by untrusted peers. Out of the box `node dist/http.
 | `PORT` | `3000` | Listen port. |
 | `QUANTAKRYPTO_MCP_TOKEN` | _(unset)_ | When set, requires `Authorization: Bearer <token>`. |
 | `QUANTAKRYPTO_MCP_ALLOW_FS` | _(off)_ | `1`/`true` exposes the filesystem tools over HTTP. |
-| `QUANTAKRYPTO_MCP_TIMEOUT_MS` | `30000` | Per-request tool-execution deadline. |
+| `QUANTAKRYPTO_MCP_ROOT` | _(cwd)_ | `:`-separated allow-list of directories the FS tools may scan. |
+| `QUANTAKRYPTO_MCP_ALLOW_ORIGIN` | _(loopback)_ | Comma-separated extra `Origin` hosts allowed on `/mcp`. |
+| `QUANTAKRYPTO_MCP_TIMEOUT_MS` | `30000` | Per-request deadline; aborts the in-flight scan on timeout. |
 | `QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES` | `4194304` | Response-body size cap. |
+| `QUANTAKRYPTO_MCP_MAX_FILES` | `25000` (cap `250000`) | Max files a single scan may read. |
+| `QUANTAKRYPTO_MCP_MAX_BYTES` | `268435456` (cap 2 GiB) | Max cumulative bytes a single scan may read. |
 
 **Design choice — refuse vs. warn on a wide-open bind.** Binding to a
 non-loopback host with `QUANTAKRYPTO_MCP_TOKEN` unset is **refused** (startup fails)

package/README.md

@@ -160,9 +160,21 @@ is reachable by untrusted peers:
   only when `QUANTAKRYPTO_MCP_ALLOW_FS=1`. The knowledge tools (`explain_finding`,
   `suggest_hybrid`, `list_rules`) are always available. `tools/list` and
   `tools/call` both reflect the gating.
-- **Limits.** A 1 MiB request-body cap (always), a per-request tool timeout
-  (`QUANTAKRYPTO_MCP_TIMEOUT_MS`, default 30000 → `504` on timeout) and a response-size
-  cap (`QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES`, default 4 MiB).
+- **Filesystem tools are root-confined.** Even with `QUANTAKRYPTO_MCP_ALLOW_FS=1`,
+  every scanned path must resolve inside the `QUANTAKRYPTO_MCP_ROOT` allow-list
+  (`:`-separated; the process CWD by default). `..` traversal and out-of-root
+  absolute paths (e.g. `/etc/passwd`) are rejected — the server is not an
+  arbitrary-file-read oracle.
+- **Origin validation.** `POST /mcp` rejects a browser request whose `Origin`
+  host is not loopback (or allow-listed via `QUANTAKRYPTO_MCP_ALLOW_ORIGIN`),
+  defending the default no-token loopback config against DNS-rebinding /
+  localhost-CSRF. Non-browser clients (no `Origin`) are unaffected.
+- **Limits + work budgets.** A 1 MiB request-body cap (`413` only on the cap,
+  `400` on a transport error), a per-request tool timeout that **aborts the
+  underlying scan** (`QUANTAKRYPTO_MCP_TIMEOUT_MS`, default 30000 → `504`), a
+  response-size cap (`QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES`, default 4 MiB), and
+  per-scan work budgets (`QUANTAKRYPTO_MCP_MAX_FILES` / `QUANTAKRYPTO_MCP_MAX_BYTES`)
+  so a single call cannot exhaust host resources.
 
 | Env var | Default | Purpose |
 | --- | --- | --- |
@@ -170,8 +182,12 @@ is reachable by untrusted peers:
 | `PORT` | `3000` | Listen port. |
 | `QUANTAKRYPTO_MCP_TOKEN` | _(unset)_ | When set, requires `Authorization: Bearer <token>`. |
 | `QUANTAKRYPTO_MCP_ALLOW_FS` | _(off)_ | `1`/`true` exposes the filesystem tools over HTTP. |
-| `QUANTAKRYPTO_MCP_TIMEOUT_MS` | `30000` | Per-request tool-execution deadline. |
+| `QUANTAKRYPTO_MCP_ROOT` | _(cwd)_ | `:`-separated allow-list of directories the FS tools may scan. |
+| `QUANTAKRYPTO_MCP_ALLOW_ORIGIN` | _(loopback)_ | Comma-separated extra `Origin` hosts allowed on `/mcp`. |
+| `QUANTAKRYPTO_MCP_TIMEOUT_MS` | `30000` | Per-request deadline; aborts the in-flight scan on timeout. |
 | `QUANTAKRYPTO_MCP_MAX_RESPONSE_BYTES` | `4194304` | Response-body size cap. |
+| `QUANTAKRYPTO_MCP_MAX_FILES` | `25000` (cap `250000`) | Max files a single scan may read. |
+| `QUANTAKRYPTO_MCP_MAX_BYTES` | `268435456` (cap 2 GiB) | Max cumulative bytes a single scan may read. |
 
 ```bash
 # Local, knowledge tools only (default safe posture)
@@ -225,3 +241,9 @@ streams) — no process spawning.
 ## License
 
 Apache-2.0
+
+## Support & training
+
+Questions, commercial support, or post-quantum readiness training for your team —
+visit **[quantakrypto.com](https://quantakrypto.com)** or email
+**[hello@quantakrypto.com](mailto:hello@quantakrypto.com)**.

package/dist/fsconfig.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Filesystem-tool safety policy for the quantakrypto MCP (P0 — FS confinement
+ * and work budgets).
+ *
+ * The FS-backed tools (`scan_path`, `inventory_crypto`, `generate_cbom`) pass a
+ * caller-supplied `path` straight into `@quantakrypto/core`'s `scan()`. With the
+ * filesystem tools enabled (`QUANTAKRYPTO_MCP_ALLOW_FS=1`) that turns the server
+ * into an arbitrary-file-read oracle: `path` could be `/etc/passwd` or any tree
+ * on the host (SECURITY.md warns about exactly this). This module turns that
+ * warning into enforced policy:
+ *
+ *   - **Root allow-list** (`QUANTAKRYPTO_MCP_ROOT`, `:`-separated): every scanned
+ *     path must resolve inside one of the configured roots. When unset, the
+ *     process CWD is the single implicit root.
+ *   - **`..` traversal rejection**: a resolved path that escapes every root is
+ *     refused, even if the literal string contained no `..`.
+ *   - **Work budgets** (`maxFiles` / `maxBytes`): bounded by default and capped,
+ *     so a single `scan_path` cannot exhaust host resources.
+ *
+ * Everything here is a pure function of an env snapshot + the requested path so
+ * it is fully unit-testable; only {@link resolveFsConfig} reads `process.env`.
+ */
+/** Minimal env shape so the resolver stays pure and testable. */
+export type FsEnv = Record<string, string | undefined>;
+/** Default file-count budget for a single FS tool call. */
+export declare const DEFAULT_MAX_FILES = 25000;
+/** Hard cap on the file-count budget, even when raised via env. */
+export declare const MAX_MAX_FILES = 250000;
+/** Default cumulative-bytes budget for a single FS tool call (256 MiB). */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Hard cap on the cumulative-bytes budget, even when raised via env (2 GiB). */
+export declare const MAX_MAX_BYTES: number;
+/** Resolved FS-tool policy: where scans may read and how much work they may do. */
+export interface FsConfig {
+    /**
+     * Absolute, normalized roots a scan may read inside. Always non-empty; defaults
+     * to `[process.cwd()]` when `QUANTAKRYPTO_MCP_ROOT` is unset.
+     */
+    roots: string[];
+    /** Max files a single scan may read before {@link BudgetExceededError}. */
+    maxFiles: number;
+    /** Max cumulative bytes a single scan may read before {@link BudgetExceededError}. */
+    maxBytes: number;
+}
+/**
+ * Resolve the FS-tool policy from an env snapshot. Pure aside from the supplied
+ * `cwd` default (so callers/tests can pin it).
+ */
+export declare function resolveFsConfig(env: FsEnv, cwd?: string): FsConfig;
+/** Outcome of validating a requested path against the root allow-list. */
+export type PathDecision = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate and resolve a caller-supplied scan path against the allow-list.
+ *
+ * Relative paths are resolved against the FIRST configured root (the primary
+ * scan root), not the process CWD, so a relative request can never reach outside
+ * the allow-list. Absolute paths must already sit inside a configured root. Any
+ * path that resolves outside every root — whether via an absolute path or a
+ * `..` traversal — is rejected. Pure: does no filesystem I/O (it does not follow
+ * symlinks; the allow-list is the trust boundary).
+ */
+export declare function resolveScanPath(config: FsConfig, requested: string): PathDecision;
+//# sourceMappingURL=fsconfig.d.ts.map

package/dist/fsconfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsconfig.d.ts","sourceRoot":"","sources":["../src/fsconfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,iEAAiE;AACjE,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,mEAAmE;AACnE,eAAO,MAAM,aAAa,SAAU,CAAC;AAErC,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,QAAoB,CAAC;AAEnD,iFAAiF;AACjF,eAAO,MAAM,aAAa,QAAyB,CAAC;AAEpD,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;CAClB;AA8BD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAMjF;AAED,0EAA0E;AAC1E,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAUtF;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAsBjF"}

package/dist/fsconfig.js

@@ -0,0 +1,110 @@
+/**
+ * Filesystem-tool safety policy for the quantakrypto MCP (P0 — FS confinement
+ * and work budgets).
+ *
+ * The FS-backed tools (`scan_path`, `inventory_crypto`, `generate_cbom`) pass a
+ * caller-supplied `path` straight into `@quantakrypto/core`'s `scan()`. With the
+ * filesystem tools enabled (`QUANTAKRYPTO_MCP_ALLOW_FS=1`) that turns the server
+ * into an arbitrary-file-read oracle: `path` could be `/etc/passwd` or any tree
+ * on the host (SECURITY.md warns about exactly this). This module turns that
+ * warning into enforced policy:
+ *
+ *   - **Root allow-list** (`QUANTAKRYPTO_MCP_ROOT`, `:`-separated): every scanned
+ *     path must resolve inside one of the configured roots. When unset, the
+ *     process CWD is the single implicit root.
+ *   - **`..` traversal rejection**: a resolved path that escapes every root is
+ *     refused, even if the literal string contained no `..`.
+ *   - **Work budgets** (`maxFiles` / `maxBytes`): bounded by default and capped,
+ *     so a single `scan_path` cannot exhaust host resources.
+ *
+ * Everything here is a pure function of an env snapshot + the requested path so
+ * it is fully unit-testable; only {@link resolveFsConfig} reads `process.env`.
+ */
+import * as path from "node:path";
+import process from "node:process";
+/** Default file-count budget for a single FS tool call. */
+export const DEFAULT_MAX_FILES = 25_000;
+/** Hard cap on the file-count budget, even when raised via env. */
+export const MAX_MAX_FILES = 250_000;
+/** Default cumulative-bytes budget for a single FS tool call (256 MiB). */
+export const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+/** Hard cap on the cumulative-bytes budget, even when raised via env (2 GiB). */
+export const MAX_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+/** Parse a positive integer from an env string, clamped to `[1, cap]`. */
+function toBudget(value, fallback, cap) {
+    if (value === undefined)
+        return Math.min(fallback, cap);
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return Math.min(fallback, cap);
+    return Math.min(Math.floor(n), cap);
+}
+/** Split the `:`-separated root allow-list, dropping empty segments. */
+function parseRoots(value, cwd) {
+    const raw = (value ?? "")
+        .split(path.delimiter)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    const list = raw.length > 0 ? raw : [cwd];
+    // Normalize to absolute, de-duplicated roots.
+    const seen = new Set();
+    const roots = [];
+    for (const r of list) {
+        const abs = path.resolve(cwd, r);
+        if (!seen.has(abs)) {
+            seen.add(abs);
+            roots.push(abs);
+        }
+    }
+    return roots;
+}
+/**
+ * Resolve the FS-tool policy from an env snapshot. Pure aside from the supplied
+ * `cwd` default (so callers/tests can pin it).
+ */
+export function resolveFsConfig(env, cwd = process.cwd()) {
+    return {
+        roots: parseRoots(env.QUANTAKRYPTO_MCP_ROOT, cwd),
+        maxFiles: toBudget(env.QUANTAKRYPTO_MCP_MAX_FILES, DEFAULT_MAX_FILES, MAX_MAX_FILES),
+        maxBytes: toBudget(env.QUANTAKRYPTO_MCP_MAX_BYTES, DEFAULT_MAX_BYTES, MAX_MAX_BYTES),
+    };
+}
+/** True when `child` is `root` itself or lives beneath it (no `..` escape). */
+function isInsideRoot(child, root) {
+    if (child === root)
+        return true;
+    const rel = path.relative(root, child);
+    // `rel` starting with ".." (or being absolute) means `child` escapes `root`.
+    return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Validate and resolve a caller-supplied scan path against the allow-list.
+ *
+ * Relative paths are resolved against the FIRST configured root (the primary
+ * scan root), not the process CWD, so a relative request can never reach outside
+ * the allow-list. Absolute paths must already sit inside a configured root. Any
+ * path that resolves outside every root — whether via an absolute path or a
+ * `..` traversal — is rejected. Pure: does no filesystem I/O (it does not follow
+ * symlinks; the allow-list is the trust boundary).
+ */
+export function resolveScanPath(config, requested) {
+    const trimmed = requested.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, reason: "path must be a non-empty string" };
+    }
+    const primaryRoot = config.roots[0];
+    const resolved = path.isAbsolute(trimmed)
+        ? path.resolve(trimmed)
+        : path.resolve(primaryRoot, trimmed);
+    for (const root of config.roots) {
+        if (isInsideRoot(resolved, root)) {
+            return { ok: true, path: resolved };
+        }
+    }
+    return {
+        ok: false,
+        reason: "path is outside the configured scan root(s). " +
+            "Set QUANTAKRYPTO_MCP_ROOT to allow-list the directories the MCP may scan.",
+    };
+}
+//# sourceMappingURL=fsconfig.js.map

package/dist/fsconfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsconfig.js","sourceRoot":"","sources":["../src/fsconfig.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -67,6 +67,11 @@ export interface HttpConfig {
     maxResponseBytes: number;
     /** True when the host is a loopback interface (safe without auth). */
     loopback: boolean;
+    /**
+     * Extra origin hosts to allow on `POST /mcp` (lower-cased hostnames), beyond
+     * the implicit loopback set and the bind host. From QUANTAKRYPTO_MCP_ALLOW_ORIGIN.
+     */
+    allowedOrigins: string[];
 }
 /**
  * Resolve the HTTP transport config from env + explicit overrides. Pure: does
@@ -84,6 +89,27 @@ export declare function startupDecision(config: HttpConfig): {
     ok: boolean;
     reason?: string;
 };
+/**
+ * Decide whether a request's `Origin` / `Host` is acceptable, to defend the
+ * default no-token loopback config against DNS-rebinding and localhost-CSRF: a
+ * malicious web page can POST to `http://127.0.0.1:<port>/mcp`, but the browser
+ * stamps a foreign `Origin` we can reject. Pure and testable.
+ *
+ * Policy:
+ *   - No `Origin` header (curl, a native MCP client, same-origin GET) → allow;
+ *     the header is a browser artifact and absence is not an attack signal here.
+ *   - An `Origin` present → its host must be a configured loopback host (or a
+ *     host explicitly added to the allow-list). A foreign origin is rejected.
+ *   - When the server itself binds a non-loopback interface, a token is already
+ *     mandatory (see {@link startupDecision}); the loopback allow-list still
+ *     applies but auth is the primary control there.
+ */
+export declare function originDecision(allowedHosts: ReadonlySet<string>, originHeader: string | undefined): {
+    ok: boolean;
+    reason?: string;
+};
+/** The hosts an `Origin` may name. Loopback by default, plus the bind host. */
+export declare function allowedOriginHosts(config: HttpConfig): Set<string>;
 /** A request-authorization outcome. */
 export interface AuthDecision {
     authorized: boolean;
@@ -97,6 +123,15 @@ export interface AuthDecision {
  * allowed (the loopback / trusted-edge case). Pure and testable.
  */
 export declare function authorizeRequest(token: string, authorizationHeader: string | undefined): AuthDecision;
+/**
+ * Constant-time string compare. Both inputs are hashed with the same algorithm
+ * to fixed-length digests before {@link timingSafeEqual}, so the comparison runs
+ * over equal-length buffers and the early length-mismatch return (which leaked
+ * the configured token's length) is gone. The hashing is a domain-separation /
+ * length-equalization step, not a secrecy measure: `timingSafeEqual` still does
+ * the constant-time work and rejects unequal digests.
+ */
+export declare function timingSafeEqualStr(a: string, b: string): boolean;
 /**
  * Select the tools to expose over HTTP for a given policy. The knowledge tools
  * are always returned; the filesystem tools are included only when
@@ -104,6 +139,20 @@ export declare function authorizeRequest(token: string, authorizationHeader: str
  * for HTTP tool gating, so tools/list and tools/call stay consistent.
  */
 export declare function gateHttpTools(tools: readonly ToolDefinition[], allowFs: boolean): ToolDefinition[];
+/**
+ * Error thrown by {@link readBody} when the request body exceeds the size cap.
+ * Distinguished from a transport/I/O error so the caller can map it to HTTP 413
+ * specifically, while genuine read failures map to 400/500 (M1).
+ */
+export declare class BodyTooLargeError extends Error {
+    readonly name = "BodyTooLargeError";
+    constructor(message?: string);
+}
+/** Error raised by {@link withTimeout} when the request deadline elapses. */
+export declare class RequestTimeoutError extends Error {
+    readonly name = "RequestTimeoutError";
+    constructor(message?: string);
+}
 /**
  * Build (but do not start) the HTTP server wrapping an {@link McpServer}.
  * Exposed for testing and for embedding in a larger process. The `config`

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAC;AAQzE,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,8EAA8E;AAC9E,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAc/C,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD,uEAAuE;AACvE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEzD,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAoB3F;AASD,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG;IACnD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAUA;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,mBAAmB,EAAE,MAAM,GAAG,SAAS,GACtC,YAAY,CAYd;AAUD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,EAAE,OAAO,GACf,cAAc,EAAE,CAGlB;AA4DD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAW9E;AAyGD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAEjE;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BhF"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}