@venizia/ignis-helpers 0.4.8 → 0.5.0-0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/esm/common/constants/http.d.ts +3 -0
- package/dist/esm/common/constants/http.js +3 -0
- package/dist/esm/common/constants/http.js.map +1 -1
- package/dist/esm/common/redact.js +2 -0
- package/dist/esm/common/redact.js.map +1 -1
- package/dist/esm/core.d.ts +5 -2
- package/dist/esm/core.js +5 -2
- package/dist/esm/core.js.map +1 -1
- package/dist/esm/modules/network/http-request/base-network-request.helper.d.ts +5 -0
- package/dist/esm/modules/network/http-request/base-network-request.helper.js +14 -17
- package/dist/esm/modules/network/http-request/base-network-request.helper.js.map +1 -1
- package/dist/esm/modules/network/http-request/common/constants.d.ts +2 -1
- package/dist/esm/modules/network/http-request/common/constants.js +2 -1
- package/dist/esm/modules/network/http-request/common/constants.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.d.ts +37 -11
- package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.js +181 -38
- package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/base-fetcher.d.ts +204 -18
- package/dist/esm/modules/network/http-request/fetcher/base-fetcher.js +433 -13
- package/dist/esm/modules/network/http-request/fetcher/base-fetcher.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/common/body-limit.d.ts +36 -0
- package/dist/esm/modules/network/http-request/fetcher/common/body-limit.js +119 -0
- package/dist/esm/modules/network/http-request/fetcher/common/body-limit.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/errors.d.ts +40 -0
- package/dist/esm/modules/network/http-request/fetcher/common/errors.js +37 -0
- package/dist/esm/modules/network/http-request/fetcher/common/errors.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/guard.d.ts +27 -0
- package/dist/esm/modules/network/http-request/fetcher/common/guard.js +2 -0
- package/dist/esm/modules/network/http-request/fetcher/common/guard.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/index.d.ts +6 -0
- package/dist/esm/modules/network/http-request/fetcher/common/index.js +6 -0
- package/dist/esm/modules/network/http-request/fetcher/common/index.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/common/request-context.d.ts +15 -0
- package/dist/esm/modules/network/http-request/fetcher/common/request-context.js +11 -0
- package/dist/esm/modules/network/http-request/fetcher/common/request-context.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/response-reader.d.ts +9 -0
- package/dist/esm/modules/network/http-request/fetcher/common/response-reader.js +14 -0
- package/dist/esm/modules/network/http-request/fetcher/common/response-reader.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/common/types.d.ts +65 -1
- package/dist/esm/modules/network/http-request/fetcher/common/types.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/common/utilities.d.ts +68 -0
- package/dist/esm/modules/network/http-request/fetcher/common/utilities.js +143 -0
- package/dist/esm/modules/network/http-request/fetcher/common/utilities.js.map +1 -0
- package/dist/esm/modules/network/http-request/fetcher/index.d.ts +2 -1
- package/dist/esm/modules/network/http-request/fetcher/index.js +2 -1
- package/dist/esm/modules/network/http-request/fetcher/index.js.map +1 -1
- package/dist/esm/modules/network/http-request/fetcher/native-fetcher.d.ts +83 -0
- package/dist/esm/modules/network/http-request/fetcher/native-fetcher.js +221 -0
- package/dist/esm/modules/network/http-request/fetcher/native-fetcher.js.map +1 -0
- package/dist/esm/modules/network/utilities/index.d.ts +1 -0
- package/dist/esm/modules/network/utilities/index.js +1 -0
- package/dist/esm/modules/network/utilities/index.js.map +1 -1
- package/dist/esm/modules/network/utilities/query-string.d.ts +6 -23
- package/dist/esm/modules/network/utilities/query-string.js +3 -17
- package/dist/esm/modules/network/utilities/query-string.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-builder.d.ts +39 -0
- package/dist/esm/modules/network/utilities/url-builder.js +102 -0
- package/dist/esm/modules/network/utilities/url-builder.js.map +1 -0
- package/dist/esm/modules/network/utilities/url-safety/common/constants.d.ts +0 -3
- package/dist/esm/modules/network/utilities/url-safety/common/constants.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/common/errors.d.ts +38 -0
- package/dist/esm/modules/network/utilities/url-safety/common/errors.js +33 -1
- package/dist/esm/modules/network/utilities/url-safety/common/errors.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/common/types.d.ts +26 -3
- package/dist/esm/modules/network/utilities/url-safety/common/types.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/guard.d.ts +46 -0
- package/dist/esm/modules/network/utilities/url-safety/guard.js +145 -0
- package/dist/esm/modules/network/utilities/url-safety/guard.js.map +1 -0
- package/dist/esm/modules/network/utilities/url-safety/index.d.ts +1 -1
- package/dist/esm/modules/network/utilities/url-safety/index.js +1 -1
- package/dist/esm/modules/network/utilities/url-safety/index.js.map +1 -1
- package/dist/esm/modules/network/utilities/url-safety/policy.d.ts +52 -2
- package/dist/esm/modules/network/utilities/url-safety/policy.js +161 -14
- package/dist/esm/modules/network/utilities/url-safety/policy.js.map +1 -1
- package/dist/esm/modules/queue/bullmq/helper.d.ts +43 -7
- package/dist/esm/modules/queue/bullmq/helper.js +70 -2
- package/dist/esm/modules/queue/bullmq/helper.js.map +1 -1
- package/dist/esm/modules/retry/helper.d.ts +3 -1
- package/dist/esm/modules/retry/helper.js +8 -4
- package/dist/esm/modules/retry/helper.js.map +1 -1
- package/package.json +3 -3
- package/dist/esm/modules/network/http-request/fetcher/node-fetcher.d.ts +0 -41
- package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js +0 -111
- package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js.map +0 -1
- package/dist/esm/modules/network/utilities/url-safety/ingest.d.ts +0 -95
- package/dist/esm/modules/network/utilities/url-safety/ingest.js +0 -328
- package/dist/esm/modules/network/utilities/url-safety/ingest.js.map +0 -1
|
@@ -7,20 +7,6 @@ export class QueryStringSeparators {
|
|
|
7
7
|
/** Between a name and its value. */
|
|
8
8
|
static { this.ASSIGN = '='; }
|
|
9
9
|
}
|
|
10
|
-
/** What a `null` or `undefined` value becomes. */
|
|
11
|
-
export class QueryStringNullishModes {
|
|
12
|
-
/** An empty value (`a=`): what `node:querystring` does. */
|
|
13
|
-
static { this.EMPTY = 'empty'; }
|
|
14
|
-
/** The pair is left out. */
|
|
15
|
-
static { this.SKIP = 'skip'; }
|
|
16
|
-
}
|
|
17
|
-
/** What an object or an array value becomes. */
|
|
18
|
-
export class QueryStringNestedModes {
|
|
19
|
-
/** An empty value (an array repeats its key instead): what `node:querystring` does. */
|
|
20
|
-
static { this.DROP = 'drop'; }
|
|
21
|
-
/** One JSON-encoded parameter (`ids=[1,2]`, `filter={"where":{}}`), the shape a JSON filter travels in. */
|
|
22
|
-
static { this.JSON = 'json'; }
|
|
23
|
-
}
|
|
24
10
|
/** Builds a query string without a node builtin, so the network layer stays browser-safe. */
|
|
25
11
|
export class QueryStringUtility {
|
|
26
12
|
/**
|
|
@@ -40,10 +26,10 @@ export class QueryStringUtility {
|
|
|
40
26
|
* the trip. Without them the behavior is the one above.
|
|
41
27
|
*/
|
|
42
28
|
static toQueryString(opts) {
|
|
43
|
-
const { params, nullish =
|
|
29
|
+
const { params, nullish = 'empty', nested = 'drop' } = opts;
|
|
44
30
|
const parts = [];
|
|
45
|
-
const isSkipped = (value) => nullish ===
|
|
46
|
-
const isJson = nested ===
|
|
31
|
+
const isSkipped = (value) => nullish === 'skip' && (value === null || value === undefined);
|
|
32
|
+
const isJson = nested === 'json';
|
|
47
33
|
// A primitive only. `querystring` drops an object or a nested array to an empty value rather than
|
|
48
34
|
// stringifying it, and a caller that passed one meant something this format cannot carry anyway.
|
|
49
35
|
const encode = (value) => value === null || value === undefined || typeof value === 'object'
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-string.js","sourceRoot":"","sources":["../../../../../src/modules/network/utilities/query-string.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"query-string.js","sourceRoot":"","sources":["../../../../../src/modules/network/utilities/query-string.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,OAAO,qBAAqB;IAChC,2CAA2C;aAC3B,UAAK,GAAG,GAAG,CAAC;IAC5B,yBAAyB;aACT,SAAI,GAAG,GAAG,CAAC;IAC3B,oCAAoC;aACpB,WAAM,GAAG,GAAG,CAAC;;AAmB/B,6FAA6F;AAC7F,MAAM,OAAO,kBAAkB;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,aAAa,CAAC,IAA+D;QAClF,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;QAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,CAAC,KAAc,EAAE,EAAE,CACnC,OAAO,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,MAAM,KAAK,MAAM,CAAC;QAEjC,kGAAkG;QAClG,iGAAiG;QACjG,MAAM,MAAM,GAAG,CAAC,KAAc,EAAE,EAAE,CAChC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ;YAChE,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAExC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YAErC,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,SAAS;YACX,CAAC;YAED,IAAI,MAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAC1D,KAAK,CAAC,IAAI,CACR,GAAG,IAAI,GAAG,qBAAqB,CAAC,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CACrF,CAAC;gBACF,SAAS;YACX,CAAC;YAED,2EAA2E;YAC3E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;oBAC1B,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;wBACrB,SAAS;oBACX,CAAC;oBAED,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,qBAAqB,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACvE,CAAC;gBAED,SAAS;YACX,CAAC;YAED,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,qBAAqB,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;CACF","sourcesContent":["/** The punctuation of a query string, named so a reader sees the role rather than the character. */\nexport class QueryStringSeparators {\n /** Between the path and the first pair. */\n static readonly START = '?';\n /** Between two pairs. */\n static readonly PAIR = '&';\n /** Between a name and its value. */\n static readonly ASSIGN = '=';\n}\n\n/** How {@link QueryStringUtility.toQueryString} treats the values `node:querystring` has no answer for. */\nexport interface IQueryStringOptions {\n /**\n * What a `null` or `undefined` value becomes.\n * `'empty'` is `a=` (what `node:querystring` does), `'skip'` leaves the pair out.\n * @default 'empty'\n */\n nullish?: 'empty' | 'skip';\n /**\n * What an object or an array value becomes.\n * `'drop'` is an empty value (an array repeats its key: what `node:querystring` does), `'json'` is one JSON-encoded parameter (`filter={\"where\":{}}`).\n * @default 'drop'\n */\n nested?: 'drop' | 'json';\n}\n\n/** Builds a query string without a node builtin, so the network layer stays browser-safe. */\nexport class QueryStringUtility {\n /**\n * `node:querystring`'s `stringify`, written out so nothing on the HTTP path carries a node builtin -\n * that one import is what kept the whole network layer out of a browser bundle.\n *\n * Not `new URLSearchParams(params).toString()`, which differs on four counts measured against the\n * original: an array becomes `a=1%2C2` instead of `a=1&a=2`, `undefined` and `null` become the\n * STRINGS \"undefined\" and \"null\" instead of an empty value, and a space encodes as `+` rather than\n * `%20`. The first changes what a server parses; the second is the same coercion that sends a header\n * reading \"undefined\".\n *\n * Diffed against `node:querystring` across 22 shapes with zero mismatches.\n *\n * `nullish: 'skip'` leaves a null or undefined pair out. `nested: 'json'` sends an object or an\n * array as ONE JSON parameter instead (an array does not repeat its key), so a filter object survives\n * the trip. Without them the behavior is the one above.\n */\n static toQueryString(opts: { params: Record<string, unknown> } & IQueryStringOptions): string {\n const { params, nullish = 'empty', nested = 'drop' } = opts;\n const parts: string[] = [];\n const isSkipped = (value: unknown) =>\n nullish === 'skip' && (value === null || value === undefined);\n const isJson = nested === 'json';\n\n // A primitive only. `querystring` drops an object or a nested array to an empty value rather than\n // stringifying it, and a caller that passed one meant something this format cannot carry anyway.\n const encode = (value: unknown) =>\n value === null || value === undefined || typeof value === 'object'\n ? ''\n : encodeURIComponent(String(value));\n\n const entries = Object.entries(params);\n\n for (const [key, value] of entries) {\n const name = encodeURIComponent(key);\n\n if (isSkipped(value)) {\n continue;\n }\n\n if (isJson && typeof value === 'object' && value !== null) {\n parts.push(\n `${name}${QueryStringSeparators.ASSIGN}${encodeURIComponent(JSON.stringify(value))}`,\n );\n continue;\n }\n\n // An array repeats the key, which is what a server reading a list expects.\n if (Array.isArray(value)) {\n for (const entry of value) {\n if (isSkipped(entry)) {\n continue;\n }\n\n parts.push(`${name}${QueryStringSeparators.ASSIGN}${encode(entry)}`);\n }\n\n continue;\n }\n\n parts.push(`${name}${QueryStringSeparators.ASSIGN}${encode(value)}`);\n }\n\n return parts.join(QueryStringSeparators.PAIR);\n }\n}\n"]}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/** Building the url of a request from a base and path segments, so a segment cannot leave the base. */
|
|
2
|
+
export declare class UrlBuilder {
|
|
3
|
+
/** The origin of the page or Web Worker that runs this, or `undefined` on a server: the browser global `location` is not declared for a server build, so it is probed. */
|
|
4
|
+
static readLocationOrigin(): string | undefined;
|
|
5
|
+
/** The base is an absolute url or a path from the origin (`/api`), and carries no query or fragment. */
|
|
6
|
+
static assertBase(opts: {
|
|
7
|
+
baseUrl: string;
|
|
8
|
+
scope: string;
|
|
9
|
+
}): void;
|
|
10
|
+
/** The request paths name a place under the base path, so none may be a dot segment, hide one, or carry a separator the URL parser would read differently from a server. */
|
|
11
|
+
static assertPaths(opts: {
|
|
12
|
+
paths: ReadonlyArray<string>;
|
|
13
|
+
scope: string;
|
|
14
|
+
}): void;
|
|
15
|
+
/** `baseUrl` (no trailing slash) followed by each path with one leading slash: `('/api/', ['a', '/b'])` is `/api/a/b`. */
|
|
16
|
+
static toText(opts: {
|
|
17
|
+
baseUrl: string;
|
|
18
|
+
paths: ReadonlyArray<string>;
|
|
19
|
+
}): string;
|
|
20
|
+
/**
|
|
21
|
+
* The url of a request: the base and the paths, checked. A path may not be a dot segment, hide one, or carry a backslash
|
|
22
|
+
* or a control character; a relative base (`/api`) is resolved against `origin` (the page's, by default); and the result
|
|
23
|
+
* must be on the base's origin and under its path.
|
|
24
|
+
*/
|
|
25
|
+
static join(opts: {
|
|
26
|
+
baseUrl: string;
|
|
27
|
+
paths: ReadonlyArray<string>;
|
|
28
|
+
scope: string;
|
|
29
|
+
origin?: string;
|
|
30
|
+
}): URL;
|
|
31
|
+
/** The resolved URL, whatever built it, is on the base's origin and under its path: the check that holds when the text checks above miss a form. */
|
|
32
|
+
static assertUnderBase(opts: {
|
|
33
|
+
url: URL;
|
|
34
|
+
baseUrl: string;
|
|
35
|
+
origin?: string;
|
|
36
|
+
scope: string;
|
|
37
|
+
}): void;
|
|
38
|
+
}
|
|
39
|
+
//# sourceMappingURL=url-builder.d.ts.map
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { HTTP } from '../../../common/constants/http.js';
|
|
2
|
+
import { getError } from '../../error/index.js';
|
|
3
|
+
import { EchoUtility } from '../../../utilities/echo.utility.js';
|
|
4
|
+
const ABSOLUTE_URL_PATTERN = /^[a-z][a-z\d+.-]*:\/\//i;
|
|
5
|
+
/** A backslash is a separator to the URL parser, and a control character (a tab or a newline inside `.<TAB>.`) is dropped by it: neither may hide a dot segment. `%5c` is the encoded backslash. */
|
|
6
|
+
const UNSAFE_PATH_PATTERN = /[\p{Cc}\\]|%5c/iu;
|
|
7
|
+
/** What ends a path segment for the URL parser: a slash, a `?` or a `#` (it ends the path itself, so `..?` is a `..` segment), and the encoded slash, which a server may decode into a separator. */
|
|
8
|
+
const PATH_SEPARATOR_PATTERN = /[/?#]|%2f/i;
|
|
9
|
+
/** A segment that is `.` or `..` once its `%2e` is decoded. */
|
|
10
|
+
const DOT_SEGMENT_PATTERN = /^(?:\.|%2e){1,2}$/i;
|
|
11
|
+
/** The longest part of a refused path an error message copies. */
|
|
12
|
+
const MAX_ECHOED_PATH_LENGTH = 200;
|
|
13
|
+
/** Building the url of a request from a base and path segments, so a segment cannot leave the base. */
|
|
14
|
+
export class UrlBuilder {
|
|
15
|
+
/** The origin of the page or Web Worker that runs this, or `undefined` on a server: the browser global `location` is not declared for a server build, so it is probed. */
|
|
16
|
+
static readLocationOrigin() {
|
|
17
|
+
const location = Reflect.get(globalThis, 'location');
|
|
18
|
+
if (typeof location !== 'object' || location === null || !('origin' in location)) {
|
|
19
|
+
return undefined;
|
|
20
|
+
}
|
|
21
|
+
return typeof location.origin === 'string' ? location.origin : undefined;
|
|
22
|
+
}
|
|
23
|
+
/** The base is an absolute url or a path from the origin (`/api`), and carries no query or fragment. */
|
|
24
|
+
static assertBase(opts) {
|
|
25
|
+
const { baseUrl, scope } = opts;
|
|
26
|
+
// Against the page, `api` would follow the current route; `localhost:3000` is not a URL at all.
|
|
27
|
+
if (!ABSOLUTE_URL_PATTERN.test(baseUrl) && !baseUrl.startsWith('/')) {
|
|
28
|
+
throw getError({
|
|
29
|
+
statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
|
|
30
|
+
message: `[${scope}] baseUrl '${baseUrl}' is neither absolute nor a path from the origin | Pass '/api' or an absolute URL such as 'https://api.example.com'`,
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
// A `?` or `#` in the base would swallow the request paths into the query or the fragment.
|
|
34
|
+
if (/[?#]/.test(baseUrl)) {
|
|
35
|
+
throw getError({
|
|
36
|
+
statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
|
|
37
|
+
message: `[${scope}] baseUrl must not carry a query or a fragment: the request paths would end up inside it | Pass the base without '?' or '#', and use the call's query option`,
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
/** The request paths name a place under the base path, so none may be a dot segment, hide one, or carry a separator the URL parser would read differently from a server. */
|
|
42
|
+
static assertPaths(opts) {
|
|
43
|
+
const { paths, scope } = opts;
|
|
44
|
+
for (const path of paths) {
|
|
45
|
+
const segments = path.split(PATH_SEPARATOR_PATTERN);
|
|
46
|
+
const isEscaping = UNSAFE_PATH_PATTERN.test(path) ||
|
|
47
|
+
// A trailing space is stripped from the whole URL by the parser, so `.. ` ends as `..`.
|
|
48
|
+
segments.some((segment) => DOT_SEGMENT_PATTERN.test(segment.trimEnd()));
|
|
49
|
+
if (isEscaping) {
|
|
50
|
+
const cut = path.length > MAX_ECHOED_PATH_LENGTH ? `${path.slice(0, MAX_ECHOED_PATH_LENGTH)}…` : path;
|
|
51
|
+
throw getError({
|
|
52
|
+
statusCode: HTTP.ResultCodes.RS_4.BadRequest,
|
|
53
|
+
message: `[${scope}] A request path must stay under the base path: no dot segment, backslash or control character | path: '${EchoUtility.toSafeText({ value: cut })}'`,
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
/** `baseUrl` (no trailing slash) followed by each path with one leading slash: `('/api/', ['a', '/b'])` is `/api/a/b`. */
|
|
59
|
+
static toText(opts) {
|
|
60
|
+
const { baseUrl, paths } = opts;
|
|
61
|
+
const base = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
|
|
62
|
+
return `${base}${paths.map((path) => (path.startsWith('/') ? path : `/${path}`)).join('')}`;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The url of a request: the base and the paths, checked. A path may not be a dot segment, hide one, or carry a backslash
|
|
66
|
+
* or a control character; a relative base (`/api`) is resolved against `origin` (the page's, by default); and the result
|
|
67
|
+
* must be on the base's origin and under its path.
|
|
68
|
+
*/
|
|
69
|
+
static join(opts) {
|
|
70
|
+
const { baseUrl, paths, scope } = opts;
|
|
71
|
+
UrlBuilder.assertBase({ baseUrl, scope });
|
|
72
|
+
UrlBuilder.assertPaths({ paths, scope });
|
|
73
|
+
const isRelative = !ABSOLUTE_URL_PATTERN.test(baseUrl);
|
|
74
|
+
const text = UrlBuilder.toText({ baseUrl, paths });
|
|
75
|
+
// A page or a Web Worker has an origin to resolve '/api' against; a server has none.
|
|
76
|
+
const origin = isRelative ? (opts.origin ?? UrlBuilder.readLocationOrigin()) : undefined;
|
|
77
|
+
if (isRelative && !origin) {
|
|
78
|
+
throw getError({
|
|
79
|
+
statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
|
|
80
|
+
message: `[${scope}] Relative baseUrl '${baseUrl}' needs a page or worker location to resolve against, and there is none here | Pass an absolute baseUrl such as 'https://api.example.com'`,
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
const url = new URL(text, origin);
|
|
84
|
+
UrlBuilder.assertUnderBase({ url, baseUrl, origin, scope });
|
|
85
|
+
return url;
|
|
86
|
+
}
|
|
87
|
+
/** The resolved URL, whatever built it, is on the base's origin and under its path: the check that holds when the text checks above miss a form. */
|
|
88
|
+
static assertUnderBase(opts) {
|
|
89
|
+
const { url, baseUrl, origin, scope } = opts;
|
|
90
|
+
const base = new URL(baseUrl, origin);
|
|
91
|
+
const basePath = base.pathname.replace(/\/+$/, '');
|
|
92
|
+
const isUnderBase = url.origin === base.origin &&
|
|
93
|
+
(url.pathname === basePath || url.pathname.startsWith(`${basePath}/`));
|
|
94
|
+
if (!isUnderBase) {
|
|
95
|
+
throw getError({
|
|
96
|
+
statusCode: HTTP.ResultCodes.RS_4.BadRequest,
|
|
97
|
+
message: `[${scope}] A request path must stay under the base path: the URL left the origin or the base path`,
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
//# sourceMappingURL=url-builder.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"url-builder.js","sourceRoot":"","sources":["../../../../../src/modules/network/utilities/url-builder.ts"],"names":[],"mappings":"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","sourcesContent":["import { HTTP } from '@/common/constants/http';\nimport { getError } from '@/modules/error';\nimport { EchoUtility } from '@/utilities/echo.utility';\n\nconst ABSOLUTE_URL_PATTERN = /^[a-z][a-z\\d+.-]*:\\/\\//i;\n\n/** A backslash is a separator to the URL parser, and a control character (a tab or a newline inside `.<TAB>.`) is dropped by it: neither may hide a dot segment. `%5c` is the encoded backslash. */\nconst UNSAFE_PATH_PATTERN = /[\\p{Cc}\\\\]|%5c/iu;\n\n/** What ends a path segment for the URL parser: a slash, a `?` or a `#` (it ends the path itself, so `..?` is a `..` segment), and the encoded slash, which a server may decode into a separator. */\nconst PATH_SEPARATOR_PATTERN = /[/?#]|%2f/i;\n\n/** A segment that is `.` or `..` once its `%2e` is decoded. */\nconst DOT_SEGMENT_PATTERN = /^(?:\\.|%2e){1,2}$/i;\n\n/** The longest part of a refused path an error message copies. */\nconst MAX_ECHOED_PATH_LENGTH = 200;\n\n/** Building the url of a request from a base and path segments, so a segment cannot leave the base. */\nexport class UrlBuilder {\n /** The origin of the page or Web Worker that runs this, or `undefined` on a server: the browser global `location` is not declared for a server build, so it is probed. */\n static readLocationOrigin(): string | undefined {\n const location: unknown = Reflect.get(globalThis, 'location');\n\n if (typeof location !== 'object' || location === null || !('origin' in location)) {\n return undefined;\n }\n\n return typeof location.origin === 'string' ? location.origin : undefined;\n }\n\n /** The base is an absolute url or a path from the origin (`/api`), and carries no query or fragment. */\n static assertBase(opts: { baseUrl: string; scope: string }): void {\n const { baseUrl, scope } = opts;\n\n // Against the page, `api` would follow the current route; `localhost:3000` is not a URL at all.\n if (!ABSOLUTE_URL_PATTERN.test(baseUrl) && !baseUrl.startsWith('/')) {\n throw getError({\n statusCode: HTTP.ResultCodes.RS_5.InternalServerError,\n message: `[${scope}] baseUrl '${baseUrl}' is neither absolute nor a path from the origin | Pass '/api' or an absolute URL such as 'https://api.example.com'`,\n });\n }\n\n // A `?` or `#` in the base would swallow the request paths into the query or the fragment.\n if (/[?#]/.test(baseUrl)) {\n throw getError({\n statusCode: HTTP.ResultCodes.RS_5.InternalServerError,\n message: `[${scope}] baseUrl must not carry a query or a fragment: the request paths would end up inside it | Pass the base without '?' or '#', and use the call's query option`,\n });\n }\n }\n\n /** The request paths name a place under the base path, so none may be a dot segment, hide one, or carry a separator the URL parser would read differently from a server. */\n static assertPaths(opts: { paths: ReadonlyArray<string>; scope: string }): void {\n const { paths, scope } = opts;\n\n for (const path of paths) {\n const segments = path.split(PATH_SEPARATOR_PATTERN);\n const isEscaping =\n UNSAFE_PATH_PATTERN.test(path) ||\n // A trailing space is stripped from the whole URL by the parser, so `.. ` ends as `..`.\n segments.some((segment) => DOT_SEGMENT_PATTERN.test(segment.trimEnd()));\n\n if (isEscaping) {\n const cut =\n path.length > MAX_ECHOED_PATH_LENGTH ? `${path.slice(0, MAX_ECHOED_PATH_LENGTH)}…` : path;\n\n throw getError({\n statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n message: `[${scope}] A request path must stay under the base path: no dot segment, backslash or control character | path: '${EchoUtility.toSafeText({ value: cut })}'`,\n });\n }\n }\n }\n\n /** `baseUrl` (no trailing slash) followed by each path with one leading slash: `('/api/', ['a', '/b'])` is `/api/a/b`. */\n static toText(opts: { baseUrl: string; paths: ReadonlyArray<string> }): string {\n const { baseUrl, paths } = opts;\n const base = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n\n return `${base}${paths.map((path) => (path.startsWith('/') ? path : `/${path}`)).join('')}`;\n }\n\n /**\n * The url of a request: the base and the paths, checked. A path may not be a dot segment, hide one, or carry a backslash\n * or a control character; a relative base (`/api`) is resolved against `origin` (the page's, by default); and the result\n * must be on the base's origin and under its path.\n */\n static join(opts: {\n baseUrl: string;\n paths: ReadonlyArray<string>;\n scope: string;\n origin?: string;\n }): URL {\n const { baseUrl, paths, scope } = opts;\n\n UrlBuilder.assertBase({ baseUrl, scope });\n UrlBuilder.assertPaths({ paths, scope });\n\n const isRelative = !ABSOLUTE_URL_PATTERN.test(baseUrl);\n const text = UrlBuilder.toText({ baseUrl, paths });\n\n // A page or a Web Worker has an origin to resolve '/api' against; a server has none.\n const origin = isRelative ? (opts.origin ?? UrlBuilder.readLocationOrigin()) : undefined;\n\n if (isRelative && !origin) {\n throw getError({\n statusCode: HTTP.ResultCodes.RS_5.InternalServerError,\n message: `[${scope}] Relative baseUrl '${baseUrl}' needs a page or worker location to resolve against, and there is none here | Pass an absolute baseUrl such as 'https://api.example.com'`,\n });\n }\n\n const url = new URL(text, origin);\n\n UrlBuilder.assertUnderBase({ url, baseUrl, origin, scope });\n\n return url;\n }\n\n /** The resolved URL, whatever built it, is on the base's origin and under its path: the check that holds when the text checks above miss a form. */\n static assertUnderBase(opts: {\n url: URL;\n baseUrl: string;\n origin?: string;\n scope: string;\n }): void {\n const { url, baseUrl, origin, scope } = opts;\n const base = new URL(baseUrl, origin);\n const basePath = base.pathname.replace(/\\/+$/, '');\n const isUnderBase =\n url.origin === base.origin &&\n (url.pathname === basePath || url.pathname.startsWith(`${basePath}/`));\n\n if (!isUnderBase) {\n throw getError({\n statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n message: `[${scope}] A request path must stay under the base path: the URL left the origin or the base path`,\n });\n }\n }\n}\n"]}
|
|
@@ -1,11 +1,8 @@
|
|
|
1
|
-
import { type TConstValue } from '../../../../../common/types/index.js';
|
|
2
1
|
/** The only schemes a guarded fetch will speak. `file:` and `gopher:` are the classic SSRF pivots. */
|
|
3
2
|
export declare class UrlSchemes {
|
|
4
3
|
static readonly HTTP = "http:";
|
|
5
4
|
static readonly HTTPS = "https:";
|
|
6
5
|
}
|
|
7
|
-
/** A scheme a guarded fetch accepts: `http:` or `https:`. */
|
|
8
|
-
export type TUrlScheme = TConstValue<typeof UrlSchemes>;
|
|
9
6
|
/** The values `IUrlSafetyPolicy` uses for a field the caller leaves unset; each is the safe choice. */
|
|
10
7
|
export declare class UrlSafetyDefaults {
|
|
11
8
|
static readonly ALLOWED_SCHEMES: string[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/constants.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/constants.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,MAAM,OAAO,UAAU;aACL,SAAI,GAAG,OAAO,CAAC;aACf,UAAK,GAAG,QAAQ,CAAC;;AAGnC,uGAAuG;AACvG,MAAM,OAAO,iBAAiB;aACZ,oBAAe,GAAa,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;aAC/C,0BAAqB,GAAG,KAAK,CAAC;aAC9B,kBAAa,GAAG,CAAC,CAAC;aAClB,yBAAoB,GAAG,MAAM,CAAC;aAC9B,cAAS,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC","sourcesContent":["/** The only schemes a guarded fetch will speak. `file:` and `gopher:` are the classic SSRF pivots. */\nexport class UrlSchemes {\n static readonly HTTP = 'http:';\n static readonly HTTPS = 'https:';\n}\n\n/** The values `IUrlSafetyPolicy` uses for a field the caller leaves unset; each is the safe choice. */\nexport class UrlSafetyDefaults {\n static readonly ALLOWED_SCHEMES: string[] = [UrlSchemes.HTTPS];\n static readonly ALLOW_PRIVATE_ADDRESS = false;\n static readonly MAX_REDIRECTS = 3;\n static readonly TIMEOUT_MILLISECONDS = 10_000;\n static readonly MAX_BYTES = 10 * 1024 * 1024;\n}\n"]}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { TRegisterErrors } from '@venizia/ignis-inversion';
|
|
2
|
+
import { ApplicationError } from '@venizia/ignis-inversion';
|
|
2
3
|
/**
|
|
3
4
|
* A url the policy refuses is refused forever - the same url will never be allowed. A caller that
|
|
4
5
|
* retries on failure has to tell that apart from a host that timed out, or it retries a rejection
|
|
@@ -14,8 +15,45 @@ export declare const UrlSafetyErrors: {
|
|
|
14
15
|
readonly category: "business";
|
|
15
16
|
};
|
|
16
17
|
};
|
|
18
|
+
/**
|
|
19
|
+
* The upstream answered, and the answer is not one a fetcher returns: a status `acceptStatus` refuses (a 4xx or 5xx
|
|
20
|
+
* by default), or a redirect it was not allowed to follow (`maxRedirects: 0`, or a `Location` that is not a url).
|
|
21
|
+
* `status` is the upstream's; `statusCode` (inherited) is the one this server answers with, and stays 400. `response` carries the first 64 KiB
|
|
22
|
+
* of the body, still readable, and the socket is free.
|
|
23
|
+
*/
|
|
24
|
+
export declare class UrlFetchError<R = Response> extends ApplicationError {
|
|
25
|
+
/** How much of a refused answer's body stays readable on `response`. */
|
|
26
|
+
static readonly MAX_BODY_BYTES: number;
|
|
27
|
+
/** The status the upstream answered with. */
|
|
28
|
+
readonly status: number;
|
|
29
|
+
/** The url the caller asked for (the first hop, not a redirect's target). */
|
|
30
|
+
readonly url: string;
|
|
31
|
+
/** The upstream's headers. */
|
|
32
|
+
readonly headers: Headers;
|
|
33
|
+
/** The upstream's answer as the fetcher's client has it, with up to `MAX_BODY_BYTES` of its body readable. */
|
|
34
|
+
readonly response?: R;
|
|
35
|
+
/** The raw `Location` header of a redirect, as sent; unset for a non-redirect or when the header was missing. */
|
|
36
|
+
readonly location?: string;
|
|
37
|
+
constructor(opts: {
|
|
38
|
+
message: string;
|
|
39
|
+
status: number;
|
|
40
|
+
url: string;
|
|
41
|
+
headers?: Headers;
|
|
42
|
+
response?: R;
|
|
43
|
+
location?: string;
|
|
44
|
+
});
|
|
45
|
+
/** Whether `error` is a `UrlFetchError`: the shape a caller narrows on before it reads `status`. */
|
|
46
|
+
static is(error: unknown): error is UrlFetchError<unknown>;
|
|
47
|
+
}
|
|
17
48
|
declare module '@venizia/ignis-inversion' {
|
|
18
49
|
interface IErrorKeyRegistry extends TRegisterErrors<typeof UrlSafetyErrors> {
|
|
19
50
|
}
|
|
20
51
|
}
|
|
52
|
+
/** Telling a url-guard refusal from a failure worth another attempt. */
|
|
53
|
+
export declare class UrlSafetyRefusals {
|
|
54
|
+
/** Whether `error` is the guard's `URL_REFUSED`: refused forever, so a caller that retries must drop it. */
|
|
55
|
+
static is(opts: {
|
|
56
|
+
error: unknown;
|
|
57
|
+
}): boolean;
|
|
58
|
+
}
|
|
21
59
|
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { HTTP } from '../../../../../common/constants/index.js';
|
|
2
|
-
import { ErrorScopes } from '@venizia/ignis-inversion';
|
|
2
|
+
import { ApplicationError, ErrorScopes, isApplicationError } from '@venizia/ignis-inversion';
|
|
3
3
|
/**
|
|
4
4
|
* A url the policy refuses is refused forever - the same url will never be allowed. A caller that
|
|
5
5
|
* retries on failure has to tell that apart from a host that timed out, or it retries a rejection
|
|
@@ -12,4 +12,36 @@ export const UrlSafetyErrors = {
|
|
|
12
12
|
category: ErrorScopes.BUSINESS,
|
|
13
13
|
},
|
|
14
14
|
};
|
|
15
|
+
/**
|
|
16
|
+
* The upstream answered, and the answer is not one a fetcher returns: a status `acceptStatus` refuses (a 4xx or 5xx
|
|
17
|
+
* by default), or a redirect it was not allowed to follow (`maxRedirects: 0`, or a `Location` that is not a url).
|
|
18
|
+
* `status` is the upstream's; `statusCode` (inherited) is the one this server answers with, and stays 400. `response` carries the first 64 KiB
|
|
19
|
+
* of the body, still readable, and the socket is free.
|
|
20
|
+
*/
|
|
21
|
+
export class UrlFetchError extends ApplicationError {
|
|
22
|
+
/** How much of a refused answer's body stays readable on `response`. */
|
|
23
|
+
static { this.MAX_BODY_BYTES = 64 * 1024; }
|
|
24
|
+
constructor(opts) {
|
|
25
|
+
super({ message: opts.message });
|
|
26
|
+
this.name = 'UrlFetchError';
|
|
27
|
+
this.status = opts.status;
|
|
28
|
+
this.url = opts.url;
|
|
29
|
+
this.headers = opts.headers ?? new Headers();
|
|
30
|
+
this.response = opts.response;
|
|
31
|
+
this.location = opts.location;
|
|
32
|
+
}
|
|
33
|
+
/** Whether `error` is a `UrlFetchError`: the shape a caller narrows on before it reads `status`. */
|
|
34
|
+
static is(error) {
|
|
35
|
+
return error instanceof UrlFetchError;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
/** Telling a url-guard refusal from a failure worth another attempt. */
|
|
39
|
+
export class UrlSafetyRefusals {
|
|
40
|
+
/** Whether `error` is the guard's `URL_REFUSED`: refused forever, so a caller that retries must drop it. */
|
|
41
|
+
static is(opts) {
|
|
42
|
+
const { error } = opts;
|
|
43
|
+
return (isApplicationError(error) &&
|
|
44
|
+
error.normalized.code === UrlSafetyErrors.URL_REFUSED.message.code);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
15
47
|
//# sourceMappingURL=errors.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE7F;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE;QACX,OAAO,EAAE,EAAE,IAAI,EAAE,kCAAkC,EAAE,IAAI,EAAE,6BAA6B,EAAE;QAC1F,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;CACkD,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,OAAO,aAA4B,SAAQ,gBAAgB;IAC/D,wEAAwE;aACxD,mBAAc,GAAG,EAAE,GAAG,IAAI,CAAC;IAa3C,YAAY,IAOX;QACC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAEjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,OAAO,EAAE,CAAC;QAC7C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChC,CAAC;IAED,oGAAoG;IACpG,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,OAAO,KAAK,YAAY,aAAa,CAAC;IACxC,CAAC;;AAOH,wEAAwE;AACxE,MAAM,OAAO,iBAAiB;IAC5B,4GAA4G;IAC5G,MAAM,CAAC,EAAE,CAAC,IAAwB;QAChC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QAEvB,OAAO,CACL,kBAAkB,CAAC,KAAK,CAAC;YACzB,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CACnE,CAAC;IACJ,CAAC;CACF","sourcesContent":["import { HTTP } from '@/common/constants';\nimport type { TErrorDefinition, TRegisterErrors } from '@venizia/ignis-inversion';\nimport { ApplicationError, ErrorScopes, isApplicationError } from '@venizia/ignis-inversion';\n\n/**\n * A url the policy refuses is refused forever - the same url will never be allowed. A caller that\n * retries on failure has to tell that apart from a host that timed out, or it retries a rejection\n * and turns the guard into a repeat scanner.\n */\nexport const UrlSafetyErrors = {\n URL_REFUSED: {\n message: { text: 'Url refused by the safety policy', code: 'core.url_safety.url_refused' },\n statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n category: ErrorScopes.BUSINESS,\n },\n} as const satisfies Record<string, TErrorDefinition>;\n\n/**\n * The upstream answered, and the answer is not one a fetcher returns: a status `acceptStatus` refuses (a 4xx or 5xx\n * by default), or a redirect it was not allowed to follow (`maxRedirects: 0`, or a `Location` that is not a url).\n * `status` is the upstream's; `statusCode` (inherited) is the one this server answers with, and stays 400. `response` carries the first 64 KiB\n * of the body, still readable, and the socket is free.\n */\nexport class UrlFetchError<R = Response> extends ApplicationError {\n /** How much of a refused answer's body stays readable on `response`. */\n static readonly MAX_BODY_BYTES = 64 * 1024;\n\n /** The status the upstream answered with. */\n readonly status: number;\n /** The url the caller asked for (the first hop, not a redirect's target). */\n readonly url: string;\n /** The upstream's headers. */\n readonly headers: Headers;\n /** The upstream's answer as the fetcher's client has it, with up to `MAX_BODY_BYTES` of its body readable. */\n readonly response?: R;\n /** The raw `Location` header of a redirect, as sent; unset for a non-redirect or when the header was missing. */\n readonly location?: string;\n\n constructor(opts: {\n message: string;\n status: number;\n url: string;\n headers?: Headers;\n response?: R;\n location?: string;\n }) {\n super({ message: opts.message });\n\n this.name = 'UrlFetchError';\n this.status = opts.status;\n this.url = opts.url;\n this.headers = opts.headers ?? new Headers();\n this.response = opts.response;\n this.location = opts.location;\n }\n\n /** Whether `error` is a `UrlFetchError`: the shape a caller narrows on before it reads `status`. */\n static is(error: unknown): error is UrlFetchError<unknown> {\n return error instanceof UrlFetchError;\n }\n}\n\ndeclare module '@venizia/ignis-inversion' {\n interface IErrorKeyRegistry extends TRegisterErrors<typeof UrlSafetyErrors> {}\n}\n\n/** Telling a url-guard refusal from a failure worth another attempt. */\nexport class UrlSafetyRefusals {\n /** Whether `error` is the guard's `URL_REFUSED`: refused forever, so a caller that retries must drop it. */\n static is(opts: { error: unknown }): boolean {\n const { error } = opts;\n\n return (\n isApplicationError(error) &&\n error.normalized.code === UrlSafetyErrors.URL_REFUSED.message.code\n );\n }\n}\n"]}
|
|
@@ -1,4 +1,21 @@
|
|
|
1
1
|
import type { IDuration } from '../../../../../common/constants/duration.js';
|
|
2
|
+
/** An origin written the way `new URL(origin).origin` writes it: scheme, host and a non-default port, nothing else. */
|
|
3
|
+
export type TTrustedOrigin = `${'http' | 'https'}://${string}`;
|
|
4
|
+
/** The origins a caller trusts, and whether it trusts nothing else. */
|
|
5
|
+
export interface IUrlTrustedHosts {
|
|
6
|
+
/**
|
|
7
|
+
* Exact origins that pass whatever they resolve to: `https://cdn.example.com`, `http://vault.corp.local:8200`,
|
|
8
|
+
* `http://10.0.0.5:8080`, `http://[fd00::1]`. An entry is valid only when `new URL(entry).origin === entry`, so a path,
|
|
9
|
+
* a query, credentials, upper case, a trailing slash, a default port (`:443`) or an odd IP spelling
|
|
10
|
+
* (`http://2130706433`) is refused with a configuration error.
|
|
11
|
+
*/
|
|
12
|
+
trusted: TTrustedOrigin[];
|
|
13
|
+
/**
|
|
14
|
+
* Only the trusted origins pass; every other origin is refused, a public one included. Needs at least one trusted origin.
|
|
15
|
+
* @default false
|
|
16
|
+
*/
|
|
17
|
+
strict?: boolean;
|
|
18
|
+
}
|
|
2
19
|
/**
|
|
3
20
|
* What a caller will accept from an untrusted url. Every field is per call: an app that must reach
|
|
4
21
|
* plain `http` says so at the call site rather than weakening a build-time constant for everyone.
|
|
@@ -16,8 +33,14 @@ export interface IUrlSafetyPolicy {
|
|
|
16
33
|
* @default false
|
|
17
34
|
*/
|
|
18
35
|
allowPrivateAddress?: boolean;
|
|
19
|
-
/**
|
|
20
|
-
|
|
36
|
+
/**
|
|
37
|
+
* Origins the caller trusts. An origin in `trusted` passes the guard even when it resolves to a private address, so a
|
|
38
|
+
* service on the internal network can be reached on purpose while every other url keeps the full guard. The request
|
|
39
|
+
* still connects to the addresses that were checked, and every redirect hop is judged again. With `strict` nothing
|
|
40
|
+
* outside the list passes. The cloud metadata addresses open only when the trusted origin's host IS that literal
|
|
41
|
+
* address, never because a trusted host name resolves to one.
|
|
42
|
+
*/
|
|
43
|
+
hosts?: IUrlTrustedHosts;
|
|
21
44
|
/**
|
|
22
45
|
* Redirects followed. Each hop is re-checked, so a public host cannot bounce into a private one.
|
|
23
46
|
* @default 3
|
|
@@ -29,7 +52,7 @@ export interface IUrlSafetyPolicy {
|
|
|
29
52
|
*/
|
|
30
53
|
timeout?: IDuration;
|
|
31
54
|
/**
|
|
32
|
-
* A proxy for `
|
|
55
|
+
* A proxy for a guarded fetcher call (`NativeFetcher` only) to send the request through, as `http://host:port`. Off by default, and the
|
|
33
56
|
* environment's `HTTP_PROXY` / `HTTPS_PROXY` is ignored: a proxy resolves the host name itself, so the vetted address
|
|
34
57
|
* the guard pins to would never be used. With this set the address check still runs, but the connection is NOT pinned:
|
|
35
58
|
* the proxy decides where the request goes, so only point it at a proxy you trust to refuse internal addresses.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { IDuration } from '@/common/constants/duration';\n\n/**\n * What a caller will accept from an untrusted url. Every field is per call: an app that must reach\n * plain `http` says so at the call site rather than weakening a build-time constant for everyone.\n */\nexport interface IUrlSafetyPolicy {\n /**\n * The schemes a url may use.\n * @default ['https:']\n */\n allowedSchemes?: string[];\n\n /**\n * Whether a url may resolve to a private address. Turning it on in a path that takes urls from user input re-opens the\n * server-side request forgery this guard exists to close - a request can then be steered at\n * `169.254.169.254` and the cloud credentials behind it.\n * @default false\n */\n allowPrivateAddress?: boolean;\n\n
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { IDuration } from '@/common/constants/duration';\n\n/** An origin written the way `new URL(origin).origin` writes it: scheme, host and a non-default port, nothing else. */\nexport type TTrustedOrigin = `${'http' | 'https'}://${string}`;\n\n/** The origins a caller trusts, and whether it trusts nothing else. */\nexport interface IUrlTrustedHosts {\n /**\n * Exact origins that pass whatever they resolve to: `https://cdn.example.com`, `http://vault.corp.local:8200`,\n * `http://10.0.0.5:8080`, `http://[fd00::1]`. An entry is valid only when `new URL(entry).origin === entry`, so a path,\n * a query, credentials, upper case, a trailing slash, a default port (`:443`) or an odd IP spelling\n * (`http://2130706433`) is refused with a configuration error.\n */\n trusted: TTrustedOrigin[];\n\n /**\n * Only the trusted origins pass; every other origin is refused, a public one included. Needs at least one trusted origin.\n * @default false\n */\n strict?: boolean;\n}\n\n/**\n * What a caller will accept from an untrusted url. Every field is per call: an app that must reach\n * plain `http` says so at the call site rather than weakening a build-time constant for everyone.\n */\nexport interface IUrlSafetyPolicy {\n /**\n * The schemes a url may use.\n * @default ['https:']\n */\n allowedSchemes?: string[];\n\n /**\n * Whether a url may resolve to a private address. Turning it on in a path that takes urls from user input re-opens the\n * server-side request forgery this guard exists to close - a request can then be steered at\n * `169.254.169.254` and the cloud credentials behind it.\n * @default false\n */\n allowPrivateAddress?: boolean;\n\n /**\n * Origins the caller trusts. An origin in `trusted` passes the guard even when it resolves to a private address, so a\n * service on the internal network can be reached on purpose while every other url keeps the full guard. The request\n * still connects to the addresses that were checked, and every redirect hop is judged again. With `strict` nothing\n * outside the list passes. The cloud metadata addresses open only when the trusted origin's host IS that literal\n * address, never because a trusted host name resolves to one.\n */\n hosts?: IUrlTrustedHosts;\n\n /**\n * Redirects followed. Each hop is re-checked, so a public host cannot bounce into a private one.\n * @default 3\n */\n maxRedirects?: number;\n\n /**\n * How long a request may take. A slow host holds a worker slot for exactly this long.\n * @default UrlSafetyDefaults.TIMEOUT_MILLISECONDS\n */\n timeout?: IDuration;\n\n /**\n * A proxy for a guarded fetcher call (`NativeFetcher` only) to send the request through, as `http://host:port`. Off by default, and the\n * environment's `HTTP_PROXY` / `HTTPS_PROXY` is ignored: a proxy resolves the host name itself, so the vetted address\n * the guard pins to would never be used. With this set the address check still runs, but the connection is NOT pinned:\n * the proxy decides where the request goes, so only point it at a proxy you trust to refuse internal addresses.\n */\n proxy?: string;\n\n /**\n * Largest body, in bytes. The read stops and cancels the moment the body crosses it.\n * @default UrlSafetyDefaults.MAX_BYTES\n */\n maxBytes?: number;\n}\n"]}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { IFetchGuardRoute } from '../../http-request/fetcher/common/guard.js';
|
|
2
|
+
import type { IUrlSafetyPolicy } from './common/types.js';
|
|
3
|
+
/**
|
|
4
|
+
* The server half of the url guard, the one name for it. As a fetcher's engine: `new NativeFetcher({ ..., guardEngine: UrlGuard })`, then `guard: {}` (or a policy)
|
|
5
|
+
* on a call. Per hop the host is resolved ONCE, every answer is checked, and the request connects to those addresses and
|
|
6
|
+
* to no other, so a DNS answer that changes after the check (DNS rebinding) is never looked up again.
|
|
7
|
+
*/
|
|
8
|
+
export declare class UrlGuard {
|
|
9
|
+
static createRoute(opts: {
|
|
10
|
+
policy: IUrlSafetyPolicy;
|
|
11
|
+
}): IFetchGuardRoute;
|
|
12
|
+
/**
|
|
13
|
+
* Resolves `hostname` once and returns every address it answered, refusing the host when ANY of them is non-public.
|
|
14
|
+
* Checking only the first walks straight into a host that publishes one public A record beside an internal one.
|
|
15
|
+
* An IP literal answers itself. `allowPrivateAddress` skips the check and returns an empty list: nothing to pin to.
|
|
16
|
+
*
|
|
17
|
+
* With `trusted` (the caller has judged the origin trusted AND every hop before it was trusted too) a private answer
|
|
18
|
+
* is accepted, and the addresses are still returned to pin to. A cloud metadata address is accepted only when the trusted origin's host IS
|
|
19
|
+
* that literal; a trusted host NAME that resolves to one is refused.
|
|
20
|
+
*/
|
|
21
|
+
static resolvePublicAddresses(opts: {
|
|
22
|
+
hostname: string;
|
|
23
|
+
trusted?: boolean;
|
|
24
|
+
policy?: IUrlSafetyPolicy;
|
|
25
|
+
signal?: AbortSignal;
|
|
26
|
+
}): Promise<string[]>;
|
|
27
|
+
/**
|
|
28
|
+
* Rejects when ANY resolved address is non-public.
|
|
29
|
+
*
|
|
30
|
+
* A rebinding window remains when this is called on its own: the address can change between this check and a
|
|
31
|
+
* later connect. a fetcher call with a `guard` closes it by connecting to the address it vetted.
|
|
32
|
+
*/
|
|
33
|
+
static assertPublicHost(opts: {
|
|
34
|
+
hostname: string;
|
|
35
|
+
trusted?: boolean;
|
|
36
|
+
policy?: IUrlSafetyPolicy;
|
|
37
|
+
}): Promise<void>;
|
|
38
|
+
/** Both halves, in the order they must run: shape first, then the network. */
|
|
39
|
+
static assertReachableUrl(opts: {
|
|
40
|
+
url: string;
|
|
41
|
+
policy?: IUrlSafetyPolicy;
|
|
42
|
+
}): Promise<URL>;
|
|
43
|
+
/** Settles with `work`, or rejects with the signal's reason when the deadline passes first: a slow resolver must not outlive it. */
|
|
44
|
+
private static withDeadline;
|
|
45
|
+
}
|
|
46
|
+
//# sourceMappingURL=guard.d.ts.map
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
// The server half of the url guard: resolving a hostname needs `node:dns`, so nothing here may be re-exported from the
|
|
2
|
+
// `./core` subpath. A fetcher (browser-pure) is handed `UrlGuard` as its `guardEngine`.
|
|
3
|
+
import { DurationMultipliers } from '../../../../common/constants/duration.js';
|
|
4
|
+
import { getError } from '../../../error/index.js';
|
|
5
|
+
import { lookup } from 'node:dns/promises';
|
|
6
|
+
import { UrlSafetyDefaults } from './common/constants.js';
|
|
7
|
+
import { UrlSafetyErrors } from './common/errors.js';
|
|
8
|
+
import { UrlPolicy } from './policy.js';
|
|
9
|
+
/** One guarded call: it carries the trust of the redirect chain so far, so a hop after an untrusted one never enters a trusted private origin. */
|
|
10
|
+
class UrlGuardRoute {
|
|
11
|
+
constructor(policy,
|
|
12
|
+
// Passed in because this class is defined before `UrlGuard`, which owns the resolver.
|
|
13
|
+
resolve) {
|
|
14
|
+
this.policy = policy;
|
|
15
|
+
this.resolve = resolve;
|
|
16
|
+
this.isChainTrusted = true;
|
|
17
|
+
this.isFirstHop = true;
|
|
18
|
+
this.timeoutMs = policy.timeout
|
|
19
|
+
? (DurationMultipliers.toMilliseconds(policy.timeout) ?? undefined)
|
|
20
|
+
: undefined;
|
|
21
|
+
}
|
|
22
|
+
async vet(opts) {
|
|
23
|
+
const { url, signal } = opts;
|
|
24
|
+
const { policy } = this;
|
|
25
|
+
let target;
|
|
26
|
+
if (this.isFirstHop) {
|
|
27
|
+
// The first url: its shape, then its origin decides whether the chain starts trusted.
|
|
28
|
+
target = UrlPolicy.assertSafeUrl({ url, policy });
|
|
29
|
+
this.isChainTrusted = UrlPolicy.isTrustedOrigin({ origin: target.origin, policy });
|
|
30
|
+
this.isFirstHop = false;
|
|
31
|
+
}
|
|
32
|
+
else {
|
|
33
|
+
// Trust is entered only through a trusted hop: once a hop is not trusted, every later hop gets the full guard.
|
|
34
|
+
const parsed = new URL(url);
|
|
35
|
+
this.isChainTrusted =
|
|
36
|
+
this.isChainTrusted && UrlPolicy.isTrustedOrigin({ origin: parsed.origin, policy });
|
|
37
|
+
target = UrlPolicy.assertSafeUrl({ url, policy, isTrustedAllowed: this.isChainTrusted });
|
|
38
|
+
}
|
|
39
|
+
const addresses = await this.resolve({
|
|
40
|
+
hostname: target.hostname,
|
|
41
|
+
trusted: this.isChainTrusted,
|
|
42
|
+
policy,
|
|
43
|
+
signal,
|
|
44
|
+
});
|
|
45
|
+
// A proxy resolves the name itself, so there is nothing to pin: the caller chose it (`policy.proxy`).
|
|
46
|
+
// A pinned https connection names the host for the certificate; a literal address has no name to verify.
|
|
47
|
+
const tlsServerName = target.protocol === 'https:' && !UrlPolicy.isLiteralHost({ hostname: target.hostname })
|
|
48
|
+
? target.hostname
|
|
49
|
+
: undefined;
|
|
50
|
+
return { url: target, addresses: policy.proxy ? [] : addresses, tlsServerName };
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The server half of the url guard, the one name for it. As a fetcher's engine: `new NativeFetcher({ ..., guardEngine: UrlGuard })`, then `guard: {}` (or a policy)
|
|
55
|
+
* on a call. Per hop the host is resolved ONCE, every answer is checked, and the request connects to those addresses and
|
|
56
|
+
* to no other, so a DNS answer that changes after the check (DNS rebinding) is never looked up again.
|
|
57
|
+
*/
|
|
58
|
+
export class UrlGuard {
|
|
59
|
+
static createRoute(opts) {
|
|
60
|
+
return new UrlGuardRoute(opts.policy, (resolveOpts) => UrlGuard.resolvePublicAddresses(resolveOpts));
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Resolves `hostname` once and returns every address it answered, refusing the host when ANY of them is non-public.
|
|
64
|
+
* Checking only the first walks straight into a host that publishes one public A record beside an internal one.
|
|
65
|
+
* An IP literal answers itself. `allowPrivateAddress` skips the check and returns an empty list: nothing to pin to.
|
|
66
|
+
*
|
|
67
|
+
* With `trusted` (the caller has judged the origin trusted AND every hop before it was trusted too) a private answer
|
|
68
|
+
* is accepted, and the addresses are still returned to pin to. A cloud metadata address is accepted only when the trusted origin's host IS
|
|
69
|
+
* that literal; a trusted host NAME that resolves to one is refused.
|
|
70
|
+
*/
|
|
71
|
+
static async resolvePublicAddresses(opts) {
|
|
72
|
+
const { hostname, trusted, policy, signal } = opts;
|
|
73
|
+
if (policy?.allowPrivateAddress ?? UrlSafetyDefaults.ALLOW_PRIVATE_ADDRESS) {
|
|
74
|
+
return [];
|
|
75
|
+
}
|
|
76
|
+
// `URL.hostname` keeps the brackets on an IPv6 literal; `lookup` does not accept them, and the
|
|
77
|
+
// ENOTFOUND that follows reads as a transient DNS failure rather than the refusal it should be.
|
|
78
|
+
const address = UrlPolicy.readHostAddress({ hostname });
|
|
79
|
+
const addresses = await UrlGuard.withDeadline({
|
|
80
|
+
work: lookup(address, { all: true }),
|
|
81
|
+
signal,
|
|
82
|
+
});
|
|
83
|
+
if (!addresses.length) {
|
|
84
|
+
throw getError({
|
|
85
|
+
error: UrlSafetyErrors.URL_REFUSED,
|
|
86
|
+
message: `[assertPublicHost] Host resolves to nothing | host: ${hostname}`,
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
const isLiteral = UrlPolicy.isLiteralHost({ hostname });
|
|
90
|
+
const offender = addresses.find((entry) => trusted
|
|
91
|
+
? !isLiteral && UrlPolicy.isMetadataAddress({ address: entry.address })
|
|
92
|
+
: UrlPolicy.isNonPublicAddress({ address: entry.address }));
|
|
93
|
+
if (offender) {
|
|
94
|
+
throw getError({
|
|
95
|
+
error: UrlSafetyErrors.URL_REFUSED,
|
|
96
|
+
message: `[assertPublicHost] Host resolves to a non-public address | host: ${hostname} | address: ${offender.address}`,
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
return addresses.map((entry) => entry.address);
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Rejects when ANY resolved address is non-public.
|
|
103
|
+
*
|
|
104
|
+
* A rebinding window remains when this is called on its own: the address can change between this check and a
|
|
105
|
+
* later connect. a fetcher call with a `guard` closes it by connecting to the address it vetted.
|
|
106
|
+
*/
|
|
107
|
+
static async assertPublicHost(opts) {
|
|
108
|
+
await UrlGuard.resolvePublicAddresses(opts);
|
|
109
|
+
}
|
|
110
|
+
/** Both halves, in the order they must run: shape first, then the network. */
|
|
111
|
+
static async assertReachableUrl(opts) {
|
|
112
|
+
const parsed = UrlPolicy.assertSafeUrl(opts);
|
|
113
|
+
await UrlGuard.assertPublicHost({
|
|
114
|
+
hostname: parsed.hostname,
|
|
115
|
+
trusted: UrlPolicy.isTrustedOrigin({ origin: parsed.origin, policy: opts.policy }),
|
|
116
|
+
policy: opts.policy,
|
|
117
|
+
});
|
|
118
|
+
return parsed;
|
|
119
|
+
}
|
|
120
|
+
/** Settles with `work`, or rejects with the signal's reason when the deadline passes first: a slow resolver must not outlive it. */
|
|
121
|
+
static async withDeadline(opts) {
|
|
122
|
+
const { work, signal } = opts;
|
|
123
|
+
if (!signal) {
|
|
124
|
+
return work;
|
|
125
|
+
}
|
|
126
|
+
signal.throwIfAborted();
|
|
127
|
+
let onAbort;
|
|
128
|
+
const aborted = new Promise((_resolve, reject) => {
|
|
129
|
+
onAbort = () => reject(signal.reason);
|
|
130
|
+
signal.addEventListener('abort', onAbort, { once: true });
|
|
131
|
+
});
|
|
132
|
+
try {
|
|
133
|
+
const settled = await Promise.race([work, aborted]);
|
|
134
|
+
return settled;
|
|
135
|
+
}
|
|
136
|
+
finally {
|
|
137
|
+
signal.removeEventListener('abort', onAbort);
|
|
138
|
+
// The lookup that lost keeps running; its late answer or error must not surface as an unhandled rejection. Nothing
|
|
139
|
+
// is left to report: the caller already got the deadline's error.
|
|
140
|
+
// eslint-disable-next-line venizia/no-silent-catch -- the work lost the race; its outcome is irrelevant by now
|
|
141
|
+
work.catch(() => undefined);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
//# sourceMappingURL=guard.js.map
|