@resq-systems/security 1.0.5 → 2.1.0

package/lib/controls/query.mjs

@@ -0,0 +1,386 @@
+//#region src/controls/query.ts
+/**
+* Copyright 2026 ResQ Systems, Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* @fileoverview Two query-surface controls that are decisions rather than signatures:
+* JSONP callback validation (WSTG-CLNT-13) and a computed query-complexity bound
+* (WSTG-APIT-01).
+*
+* Both are *computed*, not matched. Depth and alias count are structural properties and
+* a regex cannot count nesting — the same reason the engine's repeated-run check is a
+* linear scan rather than a backreference.
+*
+* @module @resq-systems/security/controls/query
+*/
+/**
+* A JavaScript identifier, optionally dotted into a namespace: `cb`, `app.render`,
+* `window.jsonp.handlers.onLoad`.
+*
+* Bounded at five segments of 64 characters. Nothing outside this shape can carry a
+* payload, because the response body is `<callback>(<json>)` and every metacharacter
+* needed to break out — quotes, parens, semicolons, angle brackets — is excluded.
+*/
+const JSONP_CALLBACK = /^[A-Za-z_$][\w$]{0,63}(?:\.[A-Za-z_$][\w$]{0,63}){0,4}$/;
+/** Identifiers refused regardless of shape, because reflecting them assists an attacker. */
+const JSONP_RESERVED = /* @__PURE__ */ new Set([
+	"eval",
+	"Function",
+	"constructor",
+	"__proto__",
+	"prototype",
+	"alert",
+	"setTimeout",
+	"setInterval",
+	"import",
+	"require"
+]);
+/**
+* Validate a JSONP callback name.
+*
+* A JSONP response body is `<callback>(<json>)`, so the callback name is *concatenated
+* into executable JavaScript* — an allowlist is the only safe validation. Escaping is
+* not an option: there is no encoding of `alert(1);//` that is both harmless and still
+* callable.
+*
+* Prefer not shipping JSONP at all. It predates CORS, requires an endpoint that answers
+* `<script src>` with credentials attached, and is the mechanism behind cross-site
+* script inclusion.
+*
+* @param callback - The requested callback name.
+* @returns `true` when the name is a plain identifier or dotted namespace path and is
+*   not reserved.
+*
+* @example
+* ```ts
+* validateJsonpCallback("app.render");  // true
+* validateJsonpCallback("alert(1);//"); // false
+* validateJsonpCallback("window.eval"); // false — every segment is checked
+* ```
+*/
+function validateJsonpCallback(callback) {
+	if (typeof callback !== "string" || callback.length === 0) return false;
+	if (!JSONP_CALLBACK.test(callback)) return false;
+	for (const segment of callback.split(".")) if (JSONP_RESERVED.has(segment)) return false;
+	return true;
+}
+/** Defaults chosen to sit well above ordinary application queries. */
+const DEFAULT_LIMITS = {
+	maxDepth: 10,
+	maxAliases: 50,
+	maxFields: 500,
+	maxLength: 2e4
+};
+/** Word characters, for the field-token counter. */
+const WORD_CHARACTER = /[A-Za-z0-9_]/;
+/**
+* Measure a GraphQL-shaped query against structural limits.
+*
+* One linear pass counting brace depth, aliases, and field tokens. This is a *bound*,
+* not a parser: it does not validate the document, resolve fragments, or account for
+* list multipliers, so a production GraphQL server should still run a cost-analysis
+* plugin. What it catches is the cheap denial-of-service shape — deeply nested
+* recursive selections and mass aliasing — before the query reaches a resolver.
+*
+* String literals and `#` comments are skipped, so a brace inside `"{ }"` cannot
+* inflate the depth. The alias count is approximate: argument colons inside parens are
+* also preceded by a word and are counted too.
+*
+* @param query - The query document.
+* @param limits - See {@link QueryComplexityLimits}.
+* @returns The measured {@link QueryComplexity}. Never throws.
+*
+* @example
+* ```ts
+* const complexity = analyzeQueryComplexity(req.body.query, { maxDepth: 8 });
+* if (!complexity.withinLimits) {
+*   return new Response(`Query too complex: ${complexity.exceeded.join(", ")}`, {
+*     status: 400,
+*   });
+* }
+* ```
+*/
+function analyzeQueryComplexity(query, limits = {}) {
+	const { maxDepth, maxAliases, maxFields, maxLength } = {
+		...DEFAULT_LIMITS,
+		...limits
+	};
+	if (typeof query !== "string") return {
+		depth: 0,
+		aliases: 0,
+		fields: 0,
+		length: 0,
+		withinLimits: true,
+		exceeded: []
+	};
+	let depth = 0;
+	let deepest = 0;
+	let aliases = 0;
+	let fields = 0;
+	let inString = false;
+	let inComment = false;
+	let previousWasWord = false;
+	for (let i = 0; i < query.length; i++) {
+		const char = query[i];
+		if (inComment) {
+			if (char === "\n") inComment = false;
+			continue;
+		}
+		if (inString) {
+			if (char === "\\") i++;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			previousWasWord = false;
+			continue;
+		}
+		if (char === "#") {
+			inComment = true;
+			previousWasWord = false;
+			continue;
+		}
+		if (char === "{") {
+			depth++;
+			if (depth > deepest) deepest = depth;
+			previousWasWord = false;
+			continue;
+		}
+		if (char === "}") {
+			if (depth > 0) depth--;
+			previousWasWord = false;
+			continue;
+		}
+		if (char === ":") {
+			if (previousWasWord) aliases++;
+			previousWasWord = false;
+			continue;
+		}
+		if (WORD_CHARACTER.test(char)) {
+			if (!previousWasWord) fields++;
+			previousWasWord = true;
+			continue;
+		}
+		previousWasWord = false;
+	}
+	const exceeded = [];
+	if (deepest > maxDepth) exceeded.push("depth");
+	if (aliases > maxAliases) exceeded.push("aliases");
+	if (fields > maxFields) exceeded.push("fields");
+	if (query.length > maxLength) exceeded.push("length");
+	return {
+		depth: deepest,
+		aliases,
+		fields,
+		length: query.length,
+		withinLimits: exceeded.length === 0,
+		exceeded
+	};
+}
+/** Default batch bounds, generous compared with real client behaviour. */
+const DEFAULT_REQUEST_LIMITS = {
+	maxOperations: 10,
+	maxDocuments: 10
+};
+/** An operation keyword at the start of a definition. */
+const OPERATION_KEYWORD = /\b(?:query|mutation|subscription)\b/g;
+/**
+* Reduce a document to the text outside braces, strings and comments.
+*
+* Operation keywords only mean anything at depth 0 — `query` inside a selection set is a
+* field name, not a second operation. Strings and `#` comments are dropped so neither can
+* contribute a brace or a keyword.
+*
+* Block strings are handled explicitly: treating `"""` as three single quotes flips the
+* in-string state an odd number of times and desynchronises the rest of the scan.
+*
+* @param document - A GraphQL document.
+* @returns The depth-0 text, and whether a selection set was opened at depth 0.
+*/
+function topLevelText(document) {
+	let text = "";
+	let depth = 0;
+	let hasSelection = false;
+	let index = 0;
+	while (index < document.length) {
+		const char = document[index];
+		if (char === "#") {
+			while (index < document.length && document[index] !== "\n") index++;
+			continue;
+		}
+		if (document.startsWith("\"\"\"", index)) {
+			index += 3;
+			while (index < document.length && !document.startsWith("\"\"\"", index)) index++;
+			index += 3;
+			continue;
+		}
+		if (char === "\"") {
+			index++;
+			while (index < document.length && document[index] !== "\"") index += document[index] === "\\" ? 2 : 1;
+			index++;
+			continue;
+		}
+		if (char === "{") {
+			if (depth === 0) hasSelection = true;
+			depth++;
+			index++;
+			continue;
+		}
+		if (char === "}") {
+			depth = Math.max(0, depth - 1);
+			index++;
+			continue;
+		}
+		if (depth === 0 && char !== void 0) text += char;
+		index++;
+	}
+	return {
+		text,
+		hasSelection
+	};
+}
+/**
+* Count the top-level operations in one document.
+*
+* @param document - A GraphQL document.
+* @returns The operation count. A document with no keyword but a depth-0 selection set
+*   counts as one, because anonymous shorthand is an operation.
+*/
+function countOperations(document) {
+	const { text, hasSelection } = topLevelText(document);
+	const matches = text.match(OPERATION_KEYWORD)?.length ?? 0;
+	if (matches > 0) return matches;
+	return hasSelection ? 1 : 0;
+}
+/**
+* Deepest body nesting traversed. A real batch is one array of operation objects, so
+* anything past this is a client sending nesting for its own sake.
+*
+* The bound is what keeps {@link analyzeGraphQLRequest}'s "never throws" contract honest:
+* a caller handing over `req.body` straight from a JSON body parser can pass `[[[[…]]]]`
+* nested tens of thousands deep, and an unbounded descent raises `RangeError: Maximum
+* call stack size exceeded` inside a function documented not to throw. The raw-text path
+* never had this exposure — its `JSON.parse` failure is caught below — so only the
+* already-parsed path was affected. Same unbounded-cost shape `payload.ts` caps with
+* `MAX_COUNTER_STACK`.
+*/
+const MAX_BODY_DEPTH = 8;
+function documentsFrom(body) {
+	const documents = [];
+	let tooDeep = false;
+	let malformed = false;
+	const walk = (value, depth) => {
+		if (depth > MAX_BODY_DEPTH) {
+			tooDeep = true;
+			return;
+		}
+		if (typeof value === "string") {
+			const trimmed = value.trim();
+			if (trimmed.startsWith("{") || trimmed.startsWith("[")) try {
+				walk(JSON.parse(trimmed), depth + 1);
+				return;
+			} catch {
+				if (trimmed.startsWith("[")) {
+					malformed = true;
+					return;
+				}
+			}
+			documents.push(value);
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const entry of value) walk(entry, depth + 1);
+			return;
+		}
+		if (typeof value === "object" && value !== null) {
+			const query = value.query;
+			if (typeof query === "string") documents.push(query);
+		}
+	};
+	walk(body, 0);
+	return {
+		documents,
+		tooDeep,
+		malformed
+	};
+}
+/**
+* Measure a whole GraphQL *request*, including batches.
+*
+* {@link analyzeQueryComplexity} measures one document, which leaves two ways past it,
+* both measured against this package:
+*
+* - The documented call, `analyzeQueryComplexity(req.body.query, …)`, reads `undefined`
+*   when a client posts an **array** batch — so a 250-operation request measured
+*   `{ depth: 0, fields: 0, withinLimits: true }`. A total pass that does not even trip
+*   the length bound.
+* - Passing the raw body instead does not help: the scanner skips everything between
+*   JSON quotes, so the same batch measured `fields: 0`.
+*
+* Alias batching *inside* one document is already bounded and needs nothing here — 300
+* aliased selections report `exceeded: ["aliases", "fields"]`.
+*
+* Accepts a parsed body (`{ query }`, or an array of them) or the raw JSON text, and
+* delegates per-document measurement to {@link analyzeQueryComplexity}, so existing
+* callers and limits keep their meaning.
+*
+* Still a bound rather than a parser: run a cost-analysis plugin in the server too.
+*
+* @param body - The request body, parsed or raw.
+* @param limits - Per-document limits, plus `maxOperations` and `maxDocuments`.
+* @returns The measured {@link GraphQLRequestAnalysis}. Never throws.
+*
+* @example
+* ```ts
+* const analysis = analyzeGraphQLRequest(req.body);
+* if (!analysis.withinLimits) {
+*   return new Response("Request rejected: " + analysis.exceeded.join(", "), { status: 400 });
+* }
+* ```
+*/
+function analyzeGraphQLRequest(body, limits = {}) {
+	const { maxOperations, maxDocuments } = {
+		...DEFAULT_REQUEST_LIMITS,
+		...limits
+	};
+	const { documents, tooDeep, malformed } = documentsFrom(body);
+	const measured = documents.map((document) => analyzeQueryComplexity(document, limits));
+	const operations = documents.reduce((total, document) => total + countOperations(document), 0);
+	const worst = measured.reduce((currentWorst, complexity) => complexity.exceeded.length > currentWorst.exceeded.length || complexity.fields > currentWorst.fields ? complexity : currentWorst, {
+		depth: 0,
+		aliases: 0,
+		fields: 0,
+		length: 0,
+		withinLimits: true,
+		exceeded: []
+	});
+	const exceeded = [...worst.exceeded];
+	if (documents.length > maxDocuments) exceeded.push("documents");
+	if (operations > maxOperations) exceeded.push("operations");
+	if (tooDeep) exceeded.push("bodyDepth");
+	if (malformed) exceeded.push("malformedBody");
+	return {
+		documents: documents.length,
+		operations,
+		worst,
+		withinLimits: exceeded.length === 0,
+		exceeded
+	};
+}
+//#endregion
+export { analyzeGraphQLRequest, analyzeQueryComplexity, validateJsonpCallback };
+
+//# sourceMappingURL=query.mjs.map

package/lib/controls/query.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.mjs","names":[],"sources":["../../src/controls/query.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Two query-surface controls that are decisions rather than signatures:\n * JSONP callback validation (WSTG-CLNT-13) and a computed query-complexity bound\n * (WSTG-APIT-01).\n *\n * Both are *computed*, not matched. Depth and alias count are structural properties and\n * a regex cannot count nesting — the same reason the engine's repeated-run check is a\n * linear scan rather than a backreference.\n *\n * @module @resq-systems/security/controls/query\n */\n\n//#region JSONP\n\n/**\n * A JavaScript identifier, optionally dotted into a namespace: `cb`, `app.render`,\n * `window.jsonp.handlers.onLoad`.\n *\n * Bounded at five segments of 64 characters. Nothing outside this shape can carry a\n * payload, because the response body is `<callback>(<json>)` and every metacharacter\n * needed to break out — quotes, parens, semicolons, angle brackets — is excluded.\n */\nconst JSONP_CALLBACK = /^[A-Za-z_$][\\w$]{0,63}(?:\\.[A-Za-z_$][\\w$]{0,63}){0,4}$/;\n\n/** Identifiers refused regardless of shape, because reflecting them assists an attacker. */\nconst JSONP_RESERVED = new Set([\n\t\"eval\",\n\t\"Function\",\n\t\"constructor\",\n\t\"__proto__\",\n\t\"prototype\",\n\t\"alert\",\n\t\"setTimeout\",\n\t\"setInterval\",\n\t\"import\",\n\t\"require\",\n]);\n\n/**\n * Validate a JSONP callback name.\n *\n * A JSONP response body is `<callback>(<json>)`, so the callback name is *concatenated\n * into executable JavaScript* — an allowlist is the only safe validation. Escaping is\n * not an option: there is no encoding of `alert(1);//` that is both harmless and still\n * callable.\n *\n * Prefer not shipping JSONP at all. It predates CORS, requires an endpoint that answers\n * `<script src>` with credentials attached, and is the mechanism behind cross-site\n * script inclusion.\n *\n * @param callback - The requested callback name.\n * @returns `true` when the name is a plain identifier or dotted namespace path and is\n *   not reserved.\n *\n * @example\n * ```ts\n * validateJsonpCallback(\"app.render\");  // true\n * validateJsonpCallback(\"alert(1);//\"); // false\n * validateJsonpCallback(\"window.eval\"); // false — every segment is checked\n * ```\n */\nexport function validateJsonpCallback(callback: string): boolean {\n\tif (typeof callback !== \"string\" || callback.length === 0) return false;\n\tif (!JSONP_CALLBACK.test(callback)) return false;\n\n\t// Every segment is checked, so `window.eval` is refused as readily as `eval`.\n\tfor (const segment of callback.split(\".\")) {\n\t\tif (JSONP_RESERVED.has(segment)) return false;\n\t}\n\treturn true;\n}\n\n//#endregion\n\n//#region Query complexity\n\n/** Limits applied by {@link analyzeQueryComplexity}. */\nexport interface QueryComplexityLimits {\n\t/** Maximum nesting depth. Defaults to 10. */\n\treadonly maxDepth?: number;\n\t/** Maximum aliased fields. Defaults to 50. */\n\treadonly maxAliases?: number;\n\t/** Maximum selected fields overall. Defaults to 500. */\n\treadonly maxFields?: number;\n\t/** Maximum characters. Defaults to 20 000. */\n\treadonly maxLength?: number;\n}\n\n/** Measured shape of a query. */\nexport interface QueryComplexity {\n\t/** Deepest brace nesting reached. */\n\treadonly depth: number;\n\t/** Count of `alias: field` constructs. Approximate — see the function note. */\n\treadonly aliases: number;\n\t/** Approximate count of selected fields. */\n\treadonly fields: number;\n\t/** Character length. */\n\treadonly length: number;\n\t/** `true` when every limit is satisfied. */\n\treadonly withinLimits: boolean;\n\t/** Names of the limits exceeded; empty when `withinLimits`. */\n\treadonly exceeded: readonly string[];\n}\n\n/** Defaults chosen to sit well above ordinary application queries. */\nconst DEFAULT_LIMITS = {\n\tmaxDepth: 10,\n\tmaxAliases: 50,\n\tmaxFields: 500,\n\tmaxLength: 20_000,\n} as const satisfies Required<QueryComplexityLimits>;\n\n/** Word characters, for the field-token counter. */\nconst WORD_CHARACTER = /[A-Za-z0-9_]/;\n\n/**\n * Measure a GraphQL-shaped query against structural limits.\n *\n * One linear pass counting brace depth, aliases, and field tokens. This is a *bound*,\n * not a parser: it does not validate the document, resolve fragments, or account for\n * list multipliers, so a production GraphQL server should still run a cost-analysis\n * plugin. What it catches is the cheap denial-of-service shape — deeply nested\n * recursive selections and mass aliasing — before the query reaches a resolver.\n *\n * String literals and `#` comments are skipped, so a brace inside `\"{ }\"` cannot\n * inflate the depth. The alias count is approximate: argument colons inside parens are\n * also preceded by a word and are counted too.\n *\n * @param query - The query document.\n * @param limits - See {@link QueryComplexityLimits}.\n * @returns The measured {@link QueryComplexity}. Never throws.\n *\n * @example\n * ```ts\n * const complexity = analyzeQueryComplexity(req.body.query, { maxDepth: 8 });\n * if (!complexity.withinLimits) {\n *   return new Response(`Query too complex: ${complexity.exceeded.join(\", \")}`, {\n *     status: 400,\n *   });\n * }\n * ```\n */\nexport function analyzeQueryComplexity(\n\tquery: string,\n\tlimits: QueryComplexityLimits = {},\n): QueryComplexity {\n\tconst { maxDepth, maxAliases, maxFields, maxLength } = { ...DEFAULT_LIMITS, ...limits };\n\n\tif (typeof query !== \"string\") {\n\t\treturn { depth: 0, aliases: 0, fields: 0, length: 0, withinLimits: true, exceeded: [] };\n\t}\n\n\tlet depth = 0;\n\tlet deepest = 0;\n\tlet aliases = 0;\n\tlet fields = 0;\n\tlet inString = false;\n\tlet inComment = false;\n\tlet previousWasWord = false;\n\n\tfor (let i = 0; i < query.length; i++) {\n\t\tconst char = query[i] as string;\n\n\t\tif (inComment) {\n\t\t\tif (char === \"\\n\") inComment = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (inString) {\n\t\t\tif (char === \"\\\\\") i++;\n\t\t\telse if (char === '\"') inString = false;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === '\"') {\n\t\t\tinString = true;\n\t\t\tpreviousWasWord = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (char === \"#\") {\n\t\t\tinComment = true;\n\t\t\tpreviousWasWord = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (char === \"{\") {\n\t\t\tdepth++;\n\t\t\tif (depth > deepest) deepest = depth;\n\t\t\tpreviousWasWord = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (char === \"}\") {\n\t\t\tif (depth > 0) depth--;\n\t\t\tpreviousWasWord = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (char === \":\") {\n\t\t\tif (previousWasWord) aliases++;\n\t\t\tpreviousWasWord = false;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (WORD_CHARACTER.test(char)) {\n\t\t\tif (!previousWasWord) fields++;\n\t\t\tpreviousWasWord = true;\n\t\t\tcontinue;\n\t\t}\n\t\tpreviousWasWord = false;\n\t}\n\n\tconst exceeded: string[] = [];\n\tif (deepest > maxDepth) exceeded.push(\"depth\");\n\tif (aliases > maxAliases) exceeded.push(\"aliases\");\n\tif (fields > maxFields) exceeded.push(\"fields\");\n\tif (query.length > maxLength) exceeded.push(\"length\");\n\n\treturn {\n\t\tdepth: deepest,\n\t\taliases,\n\t\tfields,\n\t\tlength: query.length,\n\t\twithinLimits: exceeded.length === 0,\n\t\texceeded,\n\t};\n}\n\n//#endregion\n\n//#region GraphQL requests\n\n/** Limits for {@link analyzeGraphQLRequest}. */\nexport interface GraphQLRequestLimits extends QueryComplexityLimits {\n\t/**\n\t * Top-level operations permitted across the whole request. Defaults to 10.\n\t *\n\t * The bound {@link analyzeQueryComplexity} cannot express, because it measures one\n\t * document and a batch is many.\n\t */\n\treadonly maxOperations?: number;\n\t/** Documents permitted in one batch. Defaults to 10. */\n\treadonly maxDocuments?: number;\n}\n\n/** Result of {@link analyzeGraphQLRequest}. */\nexport interface GraphQLRequestAnalysis {\n\t/** Documents found in the request. `1` for an ordinary single query. */\n\treadonly documents: number;\n\t/** Top-level operations summed across every document. */\n\treadonly operations: number;\n\t/** The highest per-document complexity in the batch. */\n\treadonly worst: QueryComplexity;\n\t/** `true` when every limit is satisfied *and* the body was fully readable. */\n\treadonly withinLimits: boolean;\n\t/**\n\t * Names of the limits exceeded; empty when `withinLimits`.\n\t *\n\t * Per-document names come from {@link QueryComplexity}: `depth`, `aliases`, `fields`,\n\t * `length`. Batch-level names are `documents` and `operations`. Two more report that\n\t * the body could not be read rather than that a bound was passed, and both mean the\n\t * other counts are lower bounds rather than measurements:\n\t *\n\t * - `bodyDepth` — nesting exceeded the internal walk limit, so documents past it were\n\t *   never seen.\n\t * - `malformedBody` — a `[`-prefixed string was not valid JSON, so a batch could not\n\t *   be read at all.\n\t */\n\treadonly exceeded: readonly string[];\n}\n\n/** Default batch bounds, generous compared with real client behaviour. */\nconst DEFAULT_REQUEST_LIMITS = {\n\tmaxOperations: 10,\n\tmaxDocuments: 10,\n} as const satisfies Required<Pick<GraphQLRequestLimits, \"maxOperations\" | \"maxDocuments\">>;\n\n/** An operation keyword at the start of a definition. */\nconst OPERATION_KEYWORD = /\\b(?:query|mutation|subscription)\\b/g;\n\n/**\n * Reduce a document to the text outside braces, strings and comments.\n *\n * Operation keywords only mean anything at depth 0 — `query` inside a selection set is a\n * field name, not a second operation. Strings and `#` comments are dropped so neither can\n * contribute a brace or a keyword.\n *\n * Block strings are handled explicitly: treating `\"\"\"` as three single quotes flips the\n * in-string state an odd number of times and desynchronises the rest of the scan.\n *\n * @param document - A GraphQL document.\n * @returns The depth-0 text, and whether a selection set was opened at depth 0.\n */\nfunction topLevelText(document: string): { text: string; hasSelection: boolean } {\n\tlet text = \"\";\n\tlet depth = 0;\n\tlet hasSelection = false;\n\tlet index = 0;\n\n\twhile (index < document.length) {\n\t\tconst char = document[index];\n\n\t\tif (char === \"#\") {\n\t\t\twhile (index < document.length && document[index] !== \"\\n\") index++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (document.startsWith('\"\"\"', index)) {\n\t\t\tindex += 3;\n\t\t\twhile (index < document.length && !document.startsWith('\"\"\"', index)) index++;\n\t\t\tindex += 3;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === '\"') {\n\t\t\tindex++;\n\t\t\twhile (index < document.length && document[index] !== '\"') {\n\t\t\t\tindex += document[index] === \"\\\\\" ? 2 : 1;\n\t\t\t}\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === \"{\") {\n\t\t\tif (depth === 0) hasSelection = true;\n\t\t\tdepth++;\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === \"}\") {\n\t\t\tdepth = Math.max(0, depth - 1);\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (depth === 0 && char !== undefined) text += char;\n\t\tindex++;\n\t}\n\n\treturn { text, hasSelection };\n}\n\n/**\n * Count the top-level operations in one document.\n *\n * @param document - A GraphQL document.\n * @returns The operation count. A document with no keyword but a depth-0 selection set\n *   counts as one, because anonymous shorthand is an operation.\n */\nfunction countOperations(document: string): number {\n\tconst { text, hasSelection } = topLevelText(document);\n\tconst matches = text.match(OPERATION_KEYWORD)?.length ?? 0;\n\tif (matches > 0) return matches;\n\treturn hasSelection ? 1 : 0;\n}\n\n/**\n * Deepest body nesting traversed. A real batch is one array of operation objects, so\n * anything past this is a client sending nesting for its own sake.\n *\n * The bound is what keeps {@link analyzeGraphQLRequest}'s \"never throws\" contract honest:\n * a caller handing over `req.body` straight from a JSON body parser can pass `[[[[…]]]]`\n * nested tens of thousands deep, and an unbounded descent raises `RangeError: Maximum\n * call stack size exceeded` inside a function documented not to throw. The raw-text path\n * never had this exposure — its `JSON.parse` failure is caught below — so only the\n * already-parsed path was affected. Same unbounded-cost shape `payload.ts` caps with\n * `MAX_COUNTER_STACK`.\n */\nconst MAX_BODY_DEPTH = 8;\n\n/**\n * Extract the GraphQL documents from a request body of any accepted shape.\n *\n * Reports whether the walk completed, because both ways of stopping early —\n * {@link MAX_BODY_DEPTH}, and batch text that will not parse — otherwise return an\n * empty or short list that reads as an innocent request. Measured against this\n * package before the flags existed: 150 operations wrapped ten arrays deep extracted\n * `0` documents and satisfied every limit, and `\"[\".repeat(2500)` prefixed to a real\n * 150-operation batch extracted `1`. Both now surface as `exceeded` entries.\n *\n * @param body - Parsed body, or the raw JSON text.\n * @returns The documents found, plus the two early-stop flags.\n */\ninterface Extraction {\n\t/** Every `query` string found, in order. */\n\treadonly documents: readonly string[];\n\t/** Set when the walk hit {@link MAX_BODY_DEPTH} and stopped descending. */\n\treadonly tooDeep: boolean;\n\t/** Set when a `[`-prefixed string was not valid JSON, so a batch could not be read. */\n\treadonly malformed: boolean;\n}\n\nfunction documentsFrom(body: unknown): Extraction {\n\tconst documents: string[] = [];\n\tlet tooDeep = false;\n\tlet malformed = false;\n\n\t// A local walk rather than a recursive return, so accumulating a large batch stays\n\t// linear instead of re-copying the array at every level.\n\tconst walk = (value: unknown, depth: number): void => {\n\t\tif (depth > MAX_BODY_DEPTH) {\n\t\t\ttooDeep = true;\n\t\t\treturn;\n\t\t}\n\n\t\tif (typeof value === \"string\") {\n\t\t\tconst trimmed = value.trim();\n\t\t\tif (trimmed.startsWith(\"{\") || trimmed.startsWith(\"[\")) {\n\t\t\t\ttry {\n\t\t\t\t\twalk(JSON.parse(trimmed) as unknown, depth + 1);\n\t\t\t\t\treturn;\n\t\t\t\t} catch {\n\t\t\t\t\t// A `{`-prefixed string that is not JSON is ordinary anonymous-shorthand\n\t\t\t\t\t// GraphQL — `{ user { id } }` — so it falls through as a document. A\n\t\t\t\t\t// `[`-prefixed one cannot be: no GraphQL document starts with `[`, so this\n\t\t\t\t\t// is a batch we failed to read, and calling it \"one document\" undercounts\n\t\t\t\t\t// it to exactly the degree an attacker chooses.\n\t\t\t\t\tif (trimmed.startsWith(\"[\")) {\n\t\t\t\t\t\tmalformed = true;\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\tdocuments.push(value);\n\t\t\treturn;\n\t\t}\n\n\t\tif (Array.isArray(value)) {\n\t\t\tfor (const entry of value) walk(entry, depth + 1);\n\t\t\treturn;\n\t\t}\n\n\t\tif (typeof value === \"object\" && value !== null) {\n\t\t\tconst query = (value as { query?: unknown }).query;\n\t\t\tif (typeof query === \"string\") documents.push(query);\n\t\t}\n\t};\n\n\twalk(body, 0);\n\treturn { documents, tooDeep, malformed };\n}\n\n/**\n * Measure a whole GraphQL *request*, including batches.\n *\n * {@link analyzeQueryComplexity} measures one document, which leaves two ways past it,\n * both measured against this package:\n *\n * - The documented call, `analyzeQueryComplexity(req.body.query, …)`, reads `undefined`\n *   when a client posts an **array** batch — so a 250-operation request measured\n *   `{ depth: 0, fields: 0, withinLimits: true }`. A total pass that does not even trip\n *   the length bound.\n * - Passing the raw body instead does not help: the scanner skips everything between\n *   JSON quotes, so the same batch measured `fields: 0`.\n *\n * Alias batching *inside* one document is already bounded and needs nothing here — 300\n * aliased selections report `exceeded: [\"aliases\", \"fields\"]`.\n *\n * Accepts a parsed body (`{ query }`, or an array of them) or the raw JSON text, and\n * delegates per-document measurement to {@link analyzeQueryComplexity}, so existing\n * callers and limits keep their meaning.\n *\n * Still a bound rather than a parser: run a cost-analysis plugin in the server too.\n *\n * @param body - The request body, parsed or raw.\n * @param limits - Per-document limits, plus `maxOperations` and `maxDocuments`.\n * @returns The measured {@link GraphQLRequestAnalysis}. Never throws.\n *\n * @example\n * ```ts\n * const analysis = analyzeGraphQLRequest(req.body);\n * if (!analysis.withinLimits) {\n *   return new Response(\"Request rejected: \" + analysis.exceeded.join(\", \"), { status: 400 });\n * }\n * ```\n */\nexport function analyzeGraphQLRequest(\n\tbody: unknown,\n\tlimits: GraphQLRequestLimits = {},\n): GraphQLRequestAnalysis {\n\tconst { maxOperations, maxDocuments } = { ...DEFAULT_REQUEST_LIMITS, ...limits };\n\n\tconst { documents, tooDeep, malformed } = documentsFrom(body);\n\tconst measured = documents.map((document) => analyzeQueryComplexity(document, limits));\n\tconst operations = documents.reduce((total, document) => total + countOperations(document), 0);\n\n\tconst empty: QueryComplexity = {\n\t\tdepth: 0,\n\t\taliases: 0,\n\t\tfields: 0,\n\t\tlength: 0,\n\t\twithinLimits: true,\n\t\texceeded: [],\n\t};\n\n\t// The worst document decides, so one oversized member of a batch cannot hide behind\n\t// the rest.\n\tconst worst = measured.reduce<QueryComplexity>(\n\t\t(currentWorst, complexity) =>\n\t\t\tcomplexity.exceeded.length > currentWorst.exceeded.length ||\n\t\t\tcomplexity.fields > currentWorst.fields\n\t\t\t\t? complexity\n\t\t\t\t: currentWorst,\n\t\tempty,\n\t);\n\n\tconst exceeded = [...worst.exceeded];\n\tif (documents.length > maxDocuments) exceeded.push(\"documents\");\n\tif (operations > maxOperations) exceeded.push(\"operations\");\n\t// Fail closed. Everything above measures what was extracted, and these two say the\n\t// extraction was incomplete — so the counts are lower bounds, not measurements, and\n\t// reporting `withinLimits: true` off them would be asserting something never checked.\n\tif (tooDeep) exceeded.push(\"bodyDepth\");\n\tif (malformed) exceeded.push(\"malformedBody\");\n\n\treturn {\n\t\tdocuments: documents.length,\n\t\toperations,\n\t\tworst,\n\t\twithinLimits: exceeded.length === 0,\n\t\texceeded,\n\t};\n}\n\n//#endregion\n"],"mappings":"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"}

package/lib/controls/redirect.d.mts

@@ -0,0 +1,92 @@
+//#region src/controls/redirect.d.ts
+/**
+ * Copyright 2026 ResQ Systems, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @fileoverview Allowlisted resolution of redirect and forward destinations
+ * (CWE-601) — decides whether a caller-supplied `next` value may be placed in a
+ * `Location` header.
+ *
+ * @module @resq-systems/security/controls/redirect
+ */
+/** Why a redirect target was refused. */
+type RedirectRejectionReason =
+/** Not a string, or empty after trimming. */
+"malformed" |
+/** Longer than the configured bound. */
+"too_long" |
+/** Contains a character that lets the target escape the origin. */
+"control_character" |
+/** Opens a network-path reference and would leave the site. */
+"opens_authority" |
+/** Absolute URL using a scheme other than http or https. */
+"unsupported_scheme" |
+/** Absolute URL whose host is not allowlisted. */
+"host_not_allowed";
+/** Outcome of {@link resolveRedirectTarget}. */
+type RedirectVerdict = {
+  readonly allowed: true;
+  readonly target: string;
+} | {
+  readonly allowed: false;
+  readonly reason: RedirectRejectionReason;
+};
+/** Policy for {@link resolveRedirectTarget}. */
+interface RedirectPolicyOptions {
+  /**
+   * Hosts an absolute target may point at, compared case-insensitively against the
+   * parsed host. Omit to refuse every absolute URL — the safer default, and the right
+   * one for a `next=` parameter.
+   */
+  readonly allowedHosts?: readonly string[];
+  /**
+   * Longest target accepted. Defaults to 2048: comfortably above any real return path,
+   * and below the length at which proxies begin truncating a `Location` value.
+   */
+  readonly maxLength?: number;
+}
+/**
+ * Decide whether a caller-supplied value may be used as a redirect destination.
+ *
+ * The classic post-login `?next=` bug (CWE-601): a value that looks like a path but
+ * resolves to another origin, so the site itself delivers the victim to the attacker
+ * with its own credibility attached.
+ *
+ * An **allowlist**, per the OWASP Unvalidated Redirects and Forwards cheat sheet. Two
+ * things are accepted: a same-site path beginning with a single slash, and — only when
+ * `allowedHosts` names the host — an absolute `http`/`https` URL. Everything else is
+ * refused with a reason, including the schemes that never belong in a `Location` header.
+ *
+ * Percent-encoded control bytes are **accepted deliberately**: `%0d%0a` stays literal in
+ * a `Location` value and does not split a header, so refusing it would reject ordinary
+ * URLs whose paths carry encoded data.
+ *
+ * @param target - Untrusted destination, typically a query parameter.
+ * @param options - Policy. Absolute URLs are refused unless `allowedHosts` names the host.
+ * @returns A discriminated verdict: the trimmed target, or the reason it was refused.
+ *
+ * @example
+ * ```ts
+ * resolveRedirectTarget("/dashboard?tab=recent");
+ * // { allowed: true, target: "/dashboard?tab=recent" }
+ *
+ * resolveRedirectTarget("https://partner.example/sso", { allowedHosts: ["partner.example"] });
+ * // { allowed: true, target: "https://partner.example/sso" }
+ * ```
+ */
+declare function resolveRedirectTarget(target: string, options?: RedirectPolicyOptions): RedirectVerdict;
+//#endregion
+export { RedirectPolicyOptions, RedirectRejectionReason, RedirectVerdict, resolveRedirectTarget };
+//# sourceMappingURL=redirect.d.mts.map

package/lib/controls/redirect.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.d.mts","names":[],"sources":["../../src/controls/redirect.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KA2BY;;;;;;;;;;;;;;KAeA;WACE;WAAwB;;WACxB;WAAyB,QAAQ;;;UAG9B;;;;;;WAMP;;;;;WAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkEM,sBACf,gBACA,UAAS,wBACP"}

package/lib/controls/redirect.mjs

@@ -0,0 +1,110 @@
+//#region src/controls/redirect.ts
+/** Default bound on a redirect target. */
+const DEFAULT_MAX_LENGTH = 2048;
+/**
+* Characters that must never appear in a redirect target.
+*
+* C0, C1, and the two Unicode line terminators. Tab, LF and CR are the load-bearing
+* members: the URL parser strips them *before* resolving, so a tab between the leading
+* slash and a host resolves to a network-path reference and leaves the site — while the
+* authority test below, which reads only the literal leading characters, sees an
+* ordinary path.
+*
+* Sweeping U+0000-U+3000 for targets shaped `/<cp>/host` finds exactly five code points
+* that escape the origin: tab, LF, CR, and the two slashes. The authority test catches
+* the slashes and none of the first three, and all three of those are control
+* characters. That is why this test runs first; reordering the two reopens the hole
+* silently.
+*/
+const UNSAFE_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/**
+* A network-path reference: two leading slashes, in either direction.
+*
+* Inlined rather than imported from `sanitize.ts`, which statically imports `effect` —
+* an optional peer. Importing it here would make the entire `./controls` subpath fail to
+* load for a consumer who never installed `effect`.
+*/
+const OPENS_AUTHORITY = /^[/\\]{2}/;
+/**
+* Decide whether a caller-supplied value may be used as a redirect destination.
+*
+* The classic post-login `?next=` bug (CWE-601): a value that looks like a path but
+* resolves to another origin, so the site itself delivers the victim to the attacker
+* with its own credibility attached.
+*
+* An **allowlist**, per the OWASP Unvalidated Redirects and Forwards cheat sheet. Two
+* things are accepted: a same-site path beginning with a single slash, and — only when
+* `allowedHosts` names the host — an absolute `http`/`https` URL. Everything else is
+* refused with a reason, including the schemes that never belong in a `Location` header.
+*
+* Percent-encoded control bytes are **accepted deliberately**: `%0d%0a` stays literal in
+* a `Location` value and does not split a header, so refusing it would reject ordinary
+* URLs whose paths carry encoded data.
+*
+* @param target - Untrusted destination, typically a query parameter.
+* @param options - Policy. Absolute URLs are refused unless `allowedHosts` names the host.
+* @returns A discriminated verdict: the trimmed target, or the reason it was refused.
+*
+* @example
+* ```ts
+* resolveRedirectTarget("/dashboard?tab=recent");
+* // { allowed: true, target: "/dashboard?tab=recent" }
+*
+* resolveRedirectTarget("https://partner.example/sso", { allowedHosts: ["partner.example"] });
+* // { allowed: true, target: "https://partner.example/sso" }
+* ```
+*/
+function resolveRedirectTarget(target, options = {}) {
+	if (typeof target !== "string") return {
+		allowed: false,
+		reason: "malformed"
+	};
+	const trimmed = target.trim();
+	if (trimmed.length === 0) return {
+		allowed: false,
+		reason: "malformed"
+	};
+	const maxLength = options.maxLength ?? DEFAULT_MAX_LENGTH;
+	if (trimmed.length > maxLength) return {
+		allowed: false,
+		reason: "too_long"
+	};
+	if (UNSAFE_CHARS.test(trimmed)) return {
+		allowed: false,
+		reason: "control_character"
+	};
+	if (OPENS_AUTHORITY.test(trimmed)) return {
+		allowed: false,
+		reason: "opens_authority"
+	};
+	if (trimmed.startsWith("/")) return {
+		allowed: true,
+		target: trimmed
+	};
+	let parsed;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		return {
+			allowed: true,
+			target: trimmed
+		};
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return {
+		allowed: false,
+		reason: "unsupported_scheme"
+	};
+	const allowedHosts = options.allowedHosts ?? [];
+	const host = parsed.host.toLowerCase();
+	return allowedHosts.some((candidate) => candidate.trim().toLowerCase() === host) ? {
+		allowed: true,
+		target: trimmed
+	} : {
+		allowed: false,
+		reason: "host_not_allowed"
+	};
+}
+//#endregion
+export { resolveRedirectTarget };
+
+//# sourceMappingURL=redirect.mjs.map

package/lib/controls/redirect.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.mjs","names":[],"sources":["../../src/controls/redirect.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Allowlisted resolution of redirect and forward destinations\n * (CWE-601) — decides whether a caller-supplied `next` value may be placed in a\n * `Location` header.\n *\n * @module @resq-systems/security/controls/redirect\n */\n\n//#region Types\n\n/** Why a redirect target was refused. */\nexport type RedirectRejectionReason =\n\t/** Not a string, or empty after trimming. */\n\t| \"malformed\"\n\t/** Longer than the configured bound. */\n\t| \"too_long\"\n\t/** Contains a character that lets the target escape the origin. */\n\t| \"control_character\"\n\t/** Opens a network-path reference and would leave the site. */\n\t| \"opens_authority\"\n\t/** Absolute URL using a scheme other than http or https. */\n\t| \"unsupported_scheme\"\n\t/** Absolute URL whose host is not allowlisted. */\n\t| \"host_not_allowed\";\n\n/** Outcome of {@link resolveRedirectTarget}. */\nexport type RedirectVerdict =\n\t| { readonly allowed: true; readonly target: string }\n\t| { readonly allowed: false; readonly reason: RedirectRejectionReason };\n\n/** Policy for {@link resolveRedirectTarget}. */\nexport interface RedirectPolicyOptions {\n\t/**\n\t * Hosts an absolute target may point at, compared case-insensitively against the\n\t * parsed host. Omit to refuse every absolute URL — the safer default, and the right\n\t * one for a `next=` parameter.\n\t */\n\treadonly allowedHosts?: readonly string[];\n\t/**\n\t * Longest target accepted. Defaults to 2048: comfortably above any real return path,\n\t * and below the length at which proxies begin truncating a `Location` value.\n\t */\n\treadonly maxLength?: number;\n}\n\n//#endregion\n\n//#region Implementation\n\n/** Default bound on a redirect target. */\nconst DEFAULT_MAX_LENGTH = 2048;\n\n/**\n * Characters that must never appear in a redirect target.\n *\n * C0, C1, and the two Unicode line terminators. Tab, LF and CR are the load-bearing\n * members: the URL parser strips them *before* resolving, so a tab between the leading\n * slash and a host resolves to a network-path reference and leaves the site — while the\n * authority test below, which reads only the literal leading characters, sees an\n * ordinary path.\n *\n * Sweeping U+0000-U+3000 for targets shaped `/<cp>/host` finds exactly five code points\n * that escape the origin: tab, LF, CR, and the two slashes. The authority test catches\n * the slashes and none of the first three, and all three of those are control\n * characters. That is why this test runs first; reordering the two reopens the hole\n * silently.\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are the bypass\nconst UNSAFE_CHARS = /[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]/;\n\n/**\n * A network-path reference: two leading slashes, in either direction.\n *\n * Inlined rather than imported from `sanitize.ts`, which statically imports `effect` —\n * an optional peer. Importing it here would make the entire `./controls` subpath fail to\n * load for a consumer who never installed `effect`.\n */\nconst OPENS_AUTHORITY = /^[/\\\\]{2}/;\n\n/**\n * Decide whether a caller-supplied value may be used as a redirect destination.\n *\n * The classic post-login `?next=` bug (CWE-601): a value that looks like a path but\n * resolves to another origin, so the site itself delivers the victim to the attacker\n * with its own credibility attached.\n *\n * An **allowlist**, per the OWASP Unvalidated Redirects and Forwards cheat sheet. Two\n * things are accepted: a same-site path beginning with a single slash, and — only when\n * `allowedHosts` names the host — an absolute `http`/`https` URL. Everything else is\n * refused with a reason, including the schemes that never belong in a `Location` header.\n *\n * Percent-encoded control bytes are **accepted deliberately**: `%0d%0a` stays literal in\n * a `Location` value and does not split a header, so refusing it would reject ordinary\n * URLs whose paths carry encoded data.\n *\n * @param target - Untrusted destination, typically a query parameter.\n * @param options - Policy. Absolute URLs are refused unless `allowedHosts` names the host.\n * @returns A discriminated verdict: the trimmed target, or the reason it was refused.\n *\n * @example\n * ```ts\n * resolveRedirectTarget(\"/dashboard?tab=recent\");\n * // { allowed: true, target: \"/dashboard?tab=recent\" }\n *\n * resolveRedirectTarget(\"https://partner.example/sso\", { allowedHosts: [\"partner.example\"] });\n * // { allowed: true, target: \"https://partner.example/sso\" }\n * ```\n */\nexport function resolveRedirectTarget(\n\ttarget: string,\n\toptions: RedirectPolicyOptions = {},\n): RedirectVerdict {\n\tif (typeof target !== \"string\") return { allowed: false, reason: \"malformed\" };\n\n\t// Trimmed once, at entry. Leading whitespace otherwise survives the relative-path\n\t// test and reaches the absolute parse, where `new URL` trims it anyway — so a\n\t// space-prefixed network-path reference would be judged by a different branch than\n\t// the bare one.\n\tconst trimmed = target.trim();\n\tif (trimmed.length === 0) return { allowed: false, reason: \"malformed\" };\n\n\tconst maxLength = options.maxLength ?? DEFAULT_MAX_LENGTH;\n\tif (trimmed.length > maxLength) return { allowed: false, reason: \"too_long\" };\n\n\t// Order matters — see UNSAFE_CHARS. This must precede the authority test.\n\tif (UNSAFE_CHARS.test(trimmed)) return { allowed: false, reason: \"control_character\" };\n\n\tif (OPENS_AUTHORITY.test(trimmed)) return { allowed: false, reason: \"opens_authority\" };\n\n\t// A single leading slash is a same-site path, and the two tests above have already\n\t// ruled out everything that could make it resolve elsewhere.\n\tif (trimmed.startsWith(\"/\")) return { allowed: true, target: trimmed };\n\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(trimmed);\n\t} catch {\n\t\t// Neither absolute nor rooted — a bare relative path such as \"dashboard\", which\n\t\t// resolves against the current directory and cannot change origin.\n\t\treturn { allowed: true, target: trimmed };\n\t}\n\n\tif (parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") {\n\t\treturn { allowed: false, reason: \"unsupported_scheme\" };\n\t}\n\n\t// Compared against the *parsed* host, so userinfo cannot disguise the destination:\n\t// a URL whose userinfo is a trusted name still parses with the attacker's host.\n\tconst allowedHosts = options.allowedHosts ?? [];\n\tconst host = parsed.host.toLowerCase();\n\tconst permitted = allowedHosts.some((candidate) => candidate.trim().toLowerCase() === host);\n\n\treturn permitted\n\t\t? { allowed: true, target: trimmed }\n\t\t: { allowed: false, reason: \"host_not_allowed\" };\n}\n\n//#endregion\n"],"mappings":";;AAkEA,MAAM,qBAAqB;;;;;;;;;;;;;;;;AAkB3B,MAAM,eAAe;;;;;;;;AASrB,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BxB,SAAgB,sBACf,QACA,UAAiC,CAAC,GAChB;CAClB,IAAI,OAAO,WAAW,UAAU,OAAO;EAAE,SAAS;EAAO,QAAQ;CAAY;CAM7E,MAAM,UAAU,OAAO,KAAK;CAC5B,IAAI,QAAQ,WAAW,GAAG,OAAO;EAAE,SAAS;EAAO,QAAQ;CAAY;CAEvE,MAAM,YAAY,QAAQ,aAAa;CACvC,IAAI,QAAQ,SAAS,WAAW,OAAO;EAAE,SAAS;EAAO,QAAQ;CAAW;CAG5E,IAAI,aAAa,KAAK,OAAO,GAAG,OAAO;EAAE,SAAS;EAAO,QAAQ;CAAoB;CAErF,IAAI,gBAAgB,KAAK,OAAO,GAAG,OAAO;EAAE,SAAS;EAAO,QAAQ;CAAkB;CAItF,IAAI,QAAQ,WAAW,GAAG,GAAG,OAAO;EAAE,SAAS;EAAM,QAAQ;CAAQ;CAErE,IAAI;CACJ,IAAI;EACH,SAAS,IAAI,IAAI,OAAO;CACzB,QAAQ;EAGP,OAAO;GAAE,SAAS;GAAM,QAAQ;EAAQ;CACzC;CAEA,IAAI,OAAO,aAAa,WAAW,OAAO,aAAa,UACtD,OAAO;EAAE,SAAS;EAAO,QAAQ;CAAqB;CAKvD,MAAM,eAAe,QAAQ,gBAAgB,CAAC;CAC9C,MAAM,OAAO,OAAO,KAAK,YAAY;CAGrC,OAFkB,aAAa,MAAM,cAAc,UAAU,KAAK,CAAC,CAAC,YAAY,MAAM,IAEvE,IACZ;EAAE,SAAS;EAAM,QAAQ;CAAQ,IACjC;EAAE,SAAS;EAAO,QAAQ;CAAmB;AACjD"}