@resq-systems/security 1.0.5 → 2.0.0

package/lib/controls/csrf.mjs

@@ -0,0 +1,200 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/controls/csrf.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 Signed CSRF tokens — the control for WSTG-SESS-05.
+*
+* A forged cross-site request is byte-identical to a genuine one; that identity *is*
+* the weakness, which is why no signature in the threat catalog can detect it. The
+* defence is to require a value the attacker's page can neither read nor predict.
+*
+* This implements the **signed double-submit** pattern: the token carries its own
+* HMAC, so verification needs the server secret and no per-session storage. Bind it to
+* a session with `sessionId` whenever one exists — an unbound token verifies for any
+* user, which still stops a plain cross-site forgery but not a logged-in attacker
+* minting a token and planting it on a victim.
+*
+* **This is one layer.** Also ship `SameSite=Lax` (or `Strict`) on session cookies and
+* validate `Origin` with `isAllowedOrigin` on state-changing requests. Each of the
+* three can be bypassed alone.
+*
+* @module @resq-systems/security/controls/csrf
+*/
+/** Bytes of randomness in the token nonce — 128 bits. */
+const NONCE_BYTES = 16;
+/** Default token lifetime: two hours. */
+const DEFAULT_TTL_MS = 7200 * 1e3;
+/** Field separator. Outside the base64url alphabet, so it cannot occur within a field. */
+const SEPARATOR = ".";
+/** Radix for the expiry field, chosen to keep the token short. */
+const TIMESTAMP_RADIX = 36;
+/** Fixed key for the length-blinding digest in {@link constantTimeEquals}. */
+const BLINDING_KEY = "resq-csrf-length-blind";
+/**
+* Whether a string is well-formed UTF-16 — no unpaired surrogate.
+*
+* This matters because `createHmac().update(string)` encodes as UTF-8, which maps
+* *every* lone surrogate to the same replacement bytes `EF BF BD`, while
+* `String.length` counts UTF-16 code units. The length prefix therefore stops being
+* injective for ill-formed input: `"tenant-\uD800"` and `"tenant-�"` hash
+* identically, and a token bound to one verifies for the other.
+*
+* Implemented by scanning rather than calling `String.prototype.isWellFormed`, so the
+* check does not depend on the ES2024 lib being configured.
+*/
+function isWellFormedUtf16(value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code < 55296 || code > 57343) continue;
+		if (code >= 56320) return false;
+		const next = value.charCodeAt(i + 1);
+		if (Number.isNaN(next) || next < 56320 || next > 57343) return false;
+		i++;
+	}
+	return true;
+}
+/** A session identifier usable for binding: a well-formed string. */
+function isBindableSessionId(value) {
+	return typeof value === "string" && isWellFormedUtf16(value);
+}
+/**
+* Compute the token signature over the nonce, expiry, and bound session.
+*
+* Each field is length-prefixed before hashing. Without that, a different
+* (nonce, expiry, sessionId) split could produce the same concatenated input — so a
+* token bound to session `"ab"` would verify against session `"a"` with a shifted
+* nonce.
+*
+* Callers must pass a well-formed string; see {@link isBindableSessionId}. Both
+* entry points enforce it, because template-stringifying a non-string collapses every
+* object to `"[object Object]"` and every such session to the *same* signature.
+*/
+function sign(secret, nonce, expiry, sessionId) {
+	return createHmac("sha256", secret).update(`${nonce.length}:${nonce}|${expiry.length}:${expiry}|${sessionId.length}:${sessionId}`).digest("base64url");
+}
+/**
+* Mint a signed CSRF token.
+*
+* Send it to the client in a readable cookie *and* require it back in a header or form
+* field. A cross-origin page can cause the cookie to be sent but cannot read it, so it
+* cannot populate the second copy.
+*
+* @param secret - Server-side signing secret. Must be non-empty; use at least 32 bytes
+*   of entropy from a secret manager, and never a value shipped to the client.
+* @param options - See {@link CsrfTokenOptions}.
+* @returns An opaque token safe to place in a cookie, header, or hidden form field.
+* @throws {TypeError} If `secret` is empty, if `sessionId` is present but is not a
+*   well-formed string, or if `ttlMs` is not a positive integer. Each of the three is
+*   a programming error that would otherwise weaken the token silently — a non-string
+*   `sessionId` binds every session to the same signature, and a fractional `ttlMs`
+*   injects the field separator into the expiry.
+*
+* @example
+* ```ts
+* const token = createCsrfToken(process.env.CSRF_SECRET!, { sessionId: session.id });
+* res.setHeader("Set-Cookie", `csrf=${token}; Path=/; SameSite=Lax`);
+* ```
+*/
+function createCsrfToken(secret, options = {}) {
+	if (typeof secret !== "string" || secret.length === 0) throw new TypeError("createCsrfToken: secret must be a non-empty string");
+	const { sessionId = "", ttlMs = DEFAULT_TTL_MS } = options;
+	if (!isBindableSessionId(sessionId)) throw new TypeError("createCsrfToken: sessionId must be a well-formed string (no unpaired surrogates)");
+	if (!Number.isInteger(ttlMs) || ttlMs <= 0) throw new TypeError("createCsrfToken: ttlMs must be a positive integer number of milliseconds");
+	const nonce = randomBytes(NONCE_BYTES).toString("base64url");
+	const expiry = (Date.now() + ttlMs).toString(TIMESTAMP_RADIX);
+	return [
+		nonce,
+		expiry,
+		sign(secret, nonce, expiry, sessionId)
+	].join(SEPARATOR);
+}
+/**
+* Constant-time comparison that does not leak length.
+*
+* `timingSafeEqual` throws when its arguments differ in length, and guarding that with
+* an early `length` check reintroduces a timing signal. Hashing both sides to a fixed
+* 32 bytes first makes the comparison both constant-time and length-blind.
+*/
+function constantTimeEquals(left, right) {
+	return timingSafeEqual(createHmac("sha256", BLINDING_KEY).update(left, "utf8").digest(), createHmac("sha256", BLINDING_KEY).update(right, "utf8").digest());
+}
+/**
+* Verify a signed CSRF token.
+*
+* Checks the signature in constant time, then the expiry. The failure `reason` is for
+* server-side logging — do not return it to the client, since it distinguishes
+* "expired" from "forged" for anyone probing the endpoint.
+*
+* @param token - The token submitted with the request.
+* @param secret - The same signing secret used at mint time.
+* @param options - See {@link CsrfVerifyOptions}.
+* @returns `{ valid: true }`, or `{ valid: false, reason }`. Never throws.
+*
+* @example
+* ```ts
+* const result = verifyCsrfToken(req.headers["x-csrf-token"], secret, {
+*   sessionId: session.id,
+* });
+* if (!result.valid) {
+*   logger.warn("csrf rejected", { reason: result.reason });
+*   return new Response("Forbidden", { status: 403 });
+* }
+* ```
+*/
+function verifyCsrfToken(token, secret, options = {}) {
+	if (typeof secret !== "string" || secret.length === 0) return {
+		valid: false,
+		reason: "missing_secret"
+	};
+	if (typeof token !== "string" || token.length === 0) return {
+		valid: false,
+		reason: "missing_token"
+	};
+	const parts = token.split(SEPARATOR);
+	if (parts.length !== 3) return {
+		valid: false,
+		reason: "malformed"
+	};
+	const [nonce, expiry, signature] = parts;
+	if (nonce.length === 0 || expiry.length === 0 || signature.length === 0) return {
+		valid: false,
+		reason: "malformed"
+	};
+	const boundSession = options.sessionId ?? "";
+	if (!isBindableSessionId(boundSession)) return {
+		valid: false,
+		reason: "malformed"
+	};
+	if (!constantTimeEquals(signature, sign(secret, nonce, expiry, boundSession))) return {
+		valid: false,
+		reason: "signature_mismatch"
+	};
+	const expiresAt = Number.parseInt(expiry, TIMESTAMP_RADIX);
+	if (!Number.isFinite(expiresAt)) return {
+		valid: false,
+		reason: "malformed"
+	};
+	if (Date.now() > expiresAt) return {
+		valid: false,
+		reason: "expired"
+	};
+	return { valid: true };
+}
+//#endregion
+export { createCsrfToken, verifyCsrfToken };
+
+//# sourceMappingURL=csrf.mjs.map

package/lib/controls/csrf.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.mjs","names":[],"sources":["../../src/controls/csrf.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 Signed CSRF tokens — the control for WSTG-SESS-05.\n *\n * A forged cross-site request is byte-identical to a genuine one; that identity *is*\n * the weakness, which is why no signature in the threat catalog can detect it. The\n * defence is to require a value the attacker's page can neither read nor predict.\n *\n * This implements the **signed double-submit** pattern: the token carries its own\n * HMAC, so verification needs the server secret and no per-session storage. Bind it to\n * a session with `sessionId` whenever one exists — an unbound token verifies for any\n * user, which still stops a plain cross-site forgery but not a logged-in attacker\n * minting a token and planting it on a victim.\n *\n * **This is one layer.** Also ship `SameSite=Lax` (or `Strict`) on session cookies and\n * validate `Origin` with `isAllowedOrigin` on state-changing requests. Each of the\n * three can be bypassed alone.\n *\n * @module @resq-systems/security/controls/csrf\n */\n\nimport { createHmac, randomBytes, timingSafeEqual } from \"node:crypto\";\n\n//#region Constants\n\n/** Bytes of randomness in the token nonce — 128 bits. */\nconst NONCE_BYTES = 16;\n\n/** Default token lifetime: two hours. */\nconst DEFAULT_TTL_MS = 2 * 60 * 60 * 1000;\n\n/** Field separator. Outside the base64url alphabet, so it cannot occur within a field. */\nconst SEPARATOR = \".\";\n\n/** Radix for the expiry field, chosen to keep the token short. */\nconst TIMESTAMP_RADIX = 36;\n\n/** Fixed key for the length-blinding digest in {@link constantTimeEquals}. */\nconst BLINDING_KEY = \"resq-csrf-length-blind\";\n\n//#endregion\n\n//#region Token minting\n\n/** Options for {@link createCsrfToken}. */\nexport interface CsrfTokenOptions {\n\t/**\n\t * Session identifier to bind the token to. Strongly recommended: without it, a\n\t * token minted by any user verifies for every other user.\n\t */\n\treadonly sessionId?: string;\n\t/** Lifetime in milliseconds. Defaults to two hours. */\n\treadonly ttlMs?: number;\n}\n\n/**\n * Whether a string is well-formed UTF-16 — no unpaired surrogate.\n *\n * This matters because `createHmac().update(string)` encodes as UTF-8, which maps\n * *every* lone surrogate to the same replacement bytes `EF BF BD`, while\n * `String.length` counts UTF-16 code units. The length prefix therefore stops being\n * injective for ill-formed input: `\"tenant-\\uD800\"` and `\"tenant-�\"` hash\n * identically, and a token bound to one verifies for the other.\n *\n * Implemented by scanning rather than calling `String.prototype.isWellFormed`, so the\n * check does not depend on the ES2024 lib being configured.\n */\nfunction isWellFormedUtf16(value: string): boolean {\n\tfor (let i = 0; i < value.length; i++) {\n\t\tconst code = value.charCodeAt(i);\n\t\t// Not a surrogate — always fine.\n\t\tif (code < 0xd800 || code > 0xdfff) continue;\n\t\t// A trailing surrogate here means it had no leading partner.\n\t\tif (code >= 0xdc00) return false;\n\t\t// A leading surrogate must be followed by a trailing one.\n\t\tconst next = value.charCodeAt(i + 1);\n\t\tif (Number.isNaN(next) || next < 0xdc00 || next > 0xdfff) return false;\n\t\ti++;\n\t}\n\treturn true;\n}\n\n/** A session identifier usable for binding: a well-formed string. */\nfunction isBindableSessionId(value: unknown): value is string {\n\treturn typeof value === \"string\" && isWellFormedUtf16(value);\n}\n\n/**\n * Compute the token signature over the nonce, expiry, and bound session.\n *\n * Each field is length-prefixed before hashing. Without that, a different\n * (nonce, expiry, sessionId) split could produce the same concatenated input — so a\n * token bound to session `\"ab\"` would verify against session `\"a\"` with a shifted\n * nonce.\n *\n * Callers must pass a well-formed string; see {@link isBindableSessionId}. Both\n * entry points enforce it, because template-stringifying a non-string collapses every\n * object to `\"[object Object]\"` and every such session to the *same* signature.\n */\nfunction sign(secret: string, nonce: string, expiry: string, sessionId: string): string {\n\treturn createHmac(\"sha256\", secret)\n\t\t.update(`${nonce.length}:${nonce}|${expiry.length}:${expiry}|${sessionId.length}:${sessionId}`)\n\t\t.digest(\"base64url\");\n}\n\n/**\n * Mint a signed CSRF token.\n *\n * Send it to the client in a readable cookie *and* require it back in a header or form\n * field. A cross-origin page can cause the cookie to be sent but cannot read it, so it\n * cannot populate the second copy.\n *\n * @param secret - Server-side signing secret. Must be non-empty; use at least 32 bytes\n *   of entropy from a secret manager, and never a value shipped to the client.\n * @param options - See {@link CsrfTokenOptions}.\n * @returns An opaque token safe to place in a cookie, header, or hidden form field.\n * @throws {TypeError} If `secret` is empty, if `sessionId` is present but is not a\n *   well-formed string, or if `ttlMs` is not a positive integer. Each of the three is\n *   a programming error that would otherwise weaken the token silently — a non-string\n *   `sessionId` binds every session to the same signature, and a fractional `ttlMs`\n *   injects the field separator into the expiry.\n *\n * @example\n * ```ts\n * const token = createCsrfToken(process.env.CSRF_SECRET!, { sessionId: session.id });\n * res.setHeader(\"Set-Cookie\", `csrf=${token}; Path=/; SameSite=Lax`);\n * ```\n */\nexport function createCsrfToken(secret: string, options: CsrfTokenOptions = {}): string {\n\tif (typeof secret !== \"string\" || secret.length === 0) {\n\t\tthrow new TypeError(\"createCsrfToken: secret must be a non-empty string\");\n\t}\n\n\tconst { sessionId = \"\", ttlMs = DEFAULT_TTL_MS } = options;\n\n\t// Guarded after the destructuring default, so `undefined` still means \"unbound\"\n\t// while `null` and every non-string are refused with a clear message rather than a\n\t// cryptic `sessionId.length` failure. Without this, any object binds to the\n\t// constant \"[object Object]\" and one token verifies for every session.\n\tif (!isBindableSessionId(sessionId)) {\n\t\tthrow new TypeError(\n\t\t\t\"createCsrfToken: sessionId must be a well-formed string (no unpaired surrogates)\",\n\t\t);\n\t}\n\n\t// Integer, not merely finite: a fractional value renders through\n\t// `Number.prototype.toString(36)` with a fractional tail, injecting the field\n\t// separator into the expiry and producing a token this module cannot parse back.\n\tif (!Number.isInteger(ttlMs) || ttlMs <= 0) {\n\t\tthrow new TypeError(\"createCsrfToken: ttlMs must be a positive integer number of milliseconds\");\n\t}\n\n\tconst nonce = randomBytes(NONCE_BYTES).toString(\"base64url\");\n\tconst expiry = (Date.now() + ttlMs).toString(TIMESTAMP_RADIX);\n\n\treturn [nonce, expiry, sign(secret, nonce, expiry, sessionId)].join(SEPARATOR);\n}\n\n//#endregion\n\n//#region Verification\n\n/** Why a CSRF token was rejected. */\nexport type CsrfFailureReason =\n\t| \"malformed\"\n\t| \"expired\"\n\t| \"signature_mismatch\"\n\t| \"missing_token\"\n\t| \"missing_secret\";\n\n/** Outcome of {@link verifyCsrfToken}. */\nexport type CsrfVerification =\n\t| { readonly valid: true }\n\t| { readonly valid: false; readonly reason: CsrfFailureReason };\n\n/** Options for {@link verifyCsrfToken}. */\nexport interface CsrfVerifyOptions {\n\t/** Session the token must be bound to. Must match the value used at mint time. */\n\treadonly sessionId?: string;\n}\n\n/**\n * Constant-time comparison that does not leak length.\n *\n * `timingSafeEqual` throws when its arguments differ in length, and guarding that with\n * an early `length` check reintroduces a timing signal. Hashing both sides to a fixed\n * 32 bytes first makes the comparison both constant-time and length-blind.\n */\nfunction constantTimeEquals(left: string, right: string): boolean {\n\tconst digestLeft = createHmac(\"sha256\", BLINDING_KEY).update(left, \"utf8\").digest();\n\tconst digestRight = createHmac(\"sha256\", BLINDING_KEY).update(right, \"utf8\").digest();\n\treturn timingSafeEqual(digestLeft, digestRight);\n}\n\n/**\n * Verify a signed CSRF token.\n *\n * Checks the signature in constant time, then the expiry. The failure `reason` is for\n * server-side logging — do not return it to the client, since it distinguishes\n * \"expired\" from \"forged\" for anyone probing the endpoint.\n *\n * @param token - The token submitted with the request.\n * @param secret - The same signing secret used at mint time.\n * @param options - See {@link CsrfVerifyOptions}.\n * @returns `{ valid: true }`, or `{ valid: false, reason }`. Never throws.\n *\n * @example\n * ```ts\n * const result = verifyCsrfToken(req.headers[\"x-csrf-token\"], secret, {\n *   sessionId: session.id,\n * });\n * if (!result.valid) {\n *   logger.warn(\"csrf rejected\", { reason: result.reason });\n *   return new Response(\"Forbidden\", { status: 403 });\n * }\n * ```\n */\nexport function verifyCsrfToken(\n\ttoken: string | undefined | null,\n\tsecret: string,\n\toptions: CsrfVerifyOptions = {},\n): CsrfVerification {\n\tif (typeof secret !== \"string\" || secret.length === 0) {\n\t\treturn { valid: false, reason: \"missing_secret\" };\n\t}\n\tif (typeof token !== \"string\" || token.length === 0) {\n\t\treturn { valid: false, reason: \"missing_token\" };\n\t}\n\n\tconst parts = token.split(SEPARATOR);\n\tif (parts.length !== 3) return { valid: false, reason: \"malformed\" };\n\n\tconst [nonce, expiry, signature] = parts as [string, string, string];\n\tif (nonce.length === 0 || expiry.length === 0 || signature.length === 0) {\n\t\treturn { valid: false, reason: \"malformed\" };\n\t}\n\n\t// `?? \"\"` first so null and undefined both keep meaning \"unbound\", then reject\n\t// anything that is not a well-formed string. Returning a verdict rather than\n\t// throwing, because this function's contract is that it never throws.\n\tconst boundSession = options.sessionId ?? \"\";\n\tif (!isBindableSessionId(boundSession)) {\n\t\treturn { valid: false, reason: \"malformed\" };\n\t}\n\n\t// Signature first, expiry second. Checking expiry first would let an attacker\n\t// distinguish a well-formed-but-stale token from a forged one by timing alone.\n\tconst expected = sign(secret, nonce, expiry, boundSession);\n\tif (!constantTimeEquals(signature, expected)) {\n\t\treturn { valid: false, reason: \"signature_mismatch\" };\n\t}\n\n\tconst expiresAt = Number.parseInt(expiry, TIMESTAMP_RADIX);\n\tif (!Number.isFinite(expiresAt)) return { valid: false, reason: \"malformed\" };\n\tif (Date.now() > expiresAt) return { valid: false, reason: \"expired\" };\n\n\treturn { valid: true };\n}\n\n//#endregion\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAM,cAAc;;AAGpB,MAAM,iBAAiB,OAAc;;AAGrC,MAAM,YAAY;;AAGlB,MAAM,kBAAkB;;AAGxB,MAAM,eAAe;;;;;;;;;;;;;AA6BrB,SAAS,kBAAkB,OAAwB;CAClD,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACtC,MAAM,OAAO,MAAM,WAAW,CAAC;EAE/B,IAAI,OAAO,SAAU,OAAO,OAAQ;EAEpC,IAAI,QAAQ,OAAQ,OAAO;EAE3B,MAAM,OAAO,MAAM,WAAW,IAAI,CAAC;EACnC,IAAI,OAAO,MAAM,IAAI,KAAK,OAAO,SAAU,OAAO,OAAQ,OAAO;EACjE;CACD;CACA,OAAO;AACR;;AAGA,SAAS,oBAAoB,OAAiC;CAC7D,OAAO,OAAO,UAAU,YAAY,kBAAkB,KAAK;AAC5D;;;;;;;;;;;;;AAcA,SAAS,KAAK,QAAgB,OAAe,QAAgB,WAA2B;CACvF,OAAO,WAAW,UAAU,MAAM,CAAC,CACjC,OAAO,GAAG,MAAM,OAAO,GAAG,MAAM,GAAG,OAAO,OAAO,GAAG,OAAO,GAAG,UAAU,OAAO,GAAG,WAAW,CAAC,CAC9F,OAAO,WAAW;AACrB;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,gBAAgB,QAAgB,UAA4B,CAAC,GAAW;CACvF,IAAI,OAAO,WAAW,YAAY,OAAO,WAAW,GACnD,MAAM,IAAI,UAAU,oDAAoD;CAGzE,MAAM,EAAE,YAAY,IAAI,QAAQ,mBAAmB;CAMnD,IAAI,CAAC,oBAAoB,SAAS,GACjC,MAAM,IAAI,UACT,kFACD;CAMD,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,SAAS,GACxC,MAAM,IAAI,UAAU,0EAA0E;CAG/F,MAAM,QAAQ,YAAY,WAAW,CAAC,CAAC,SAAS,WAAW;CAC3D,MAAM,UAAU,KAAK,IAAI,IAAI,MAAA,CAAO,SAAS,eAAe;CAE5D,OAAO;EAAC;EAAO;EAAQ,KAAK,QAAQ,OAAO,QAAQ,SAAS;CAAC,CAAC,CAAC,KAAK,SAAS;AAC9E;;;;;;;;AAgCA,SAAS,mBAAmB,MAAc,OAAwB;CAGjE,OAAO,gBAFY,WAAW,UAAU,YAAY,CAAC,CAAC,OAAO,MAAM,MAAM,CAAC,CAAC,OAE3C,GADZ,WAAW,UAAU,YAAY,CAAC,CAAC,OAAO,OAAO,MAAM,CAAC,CAAC,OAChC,CAAC;AAC/C;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,gBACf,OACA,QACA,UAA6B,CAAC,GACX;CACnB,IAAI,OAAO,WAAW,YAAY,OAAO,WAAW,GACnD,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAiB;CAEjD,IAAI,OAAO,UAAU,YAAY,MAAM,WAAW,GACjD,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAgB;CAGhD,MAAM,QAAQ,MAAM,MAAM,SAAS;CACnC,IAAI,MAAM,WAAW,GAAG,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAY;CAEnE,MAAM,CAAC,OAAO,QAAQ,aAAa;CACnC,IAAI,MAAM,WAAW,KAAK,OAAO,WAAW,KAAK,UAAU,WAAW,GACrE,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAY;CAM5C,MAAM,eAAe,QAAQ,aAAa;CAC1C,IAAI,CAAC,oBAAoB,YAAY,GACpC,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAY;CAM5C,IAAI,CAAC,mBAAmB,WADP,KAAK,QAAQ,OAAO,QAAQ,YACH,CAAC,GAC1C,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAqB;CAGrD,MAAM,YAAY,OAAO,SAAS,QAAQ,eAAe;CACzD,IAAI,CAAC,OAAO,SAAS,SAAS,GAAG,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAY;CAC5E,IAAI,KAAK,IAAI,IAAI,WAAW,OAAO;EAAE,OAAO;EAAO,QAAQ;CAAU;CAErE,OAAO,EAAE,OAAO,KAAK;AACtB"}

package/lib/controls/index.d.mts

@@ -0,0 +1,8 @@
+import { AddressClassification, OutboundRejectionReason, OutboundUrlPolicy, OutboundUrlVerdict, assertOutboundUrl, classifyAddress, isPubliclyRoutableAddress } from "./address.mjs";
+import { CsrfFailureReason, CsrfTokenOptions, CsrfVerification, CsrfVerifyOptions, createCsrfToken, verifyCsrfToken } from "./csrf.mjs";
+import { CorsResponsePolicy, OriginPolicyOptions, checkCorsResponsePolicy, isAllowedOrigin, normalizeOrigin } from "./origin.mjs";
+import { RedirectPolicyOptions, RedirectRejectionReason, RedirectVerdict, resolveRedirectTarget } from "./redirect.mjs";
+import { GraphQLRequestAnalysis, GraphQLRequestLimits, QueryComplexity, QueryComplexityLimits, analyzeGraphQLRequest, analyzeQueryComplexity, validateJsonpCallback } from "./query.mjs";
+import { JsonPayloadLimits, JsonPayloadReport, checkJsonPayloadLimits } from "./payload.mjs";
+import { FileTypeName, UploadCandidate, UploadRejectionReason, UploadVerdict, assertUploadType, detectFileSignature } from "./upload.mjs";
+export { type AddressClassification, type CorsResponsePolicy, type CsrfFailureReason, type CsrfTokenOptions, type CsrfVerification, type CsrfVerifyOptions, type FileTypeName, type GraphQLRequestAnalysis, type GraphQLRequestLimits, type JsonPayloadLimits, type JsonPayloadReport, type OriginPolicyOptions, type OutboundRejectionReason, type OutboundUrlPolicy, type OutboundUrlVerdict, type QueryComplexity, type QueryComplexityLimits, type RedirectPolicyOptions, type RedirectRejectionReason, type RedirectVerdict, type UploadCandidate, type UploadRejectionReason, type UploadVerdict, analyzeGraphQLRequest, analyzeQueryComplexity, assertOutboundUrl, assertUploadType, checkCorsResponsePolicy, checkJsonPayloadLimits, classifyAddress, createCsrfToken, detectFileSignature, isAllowedOrigin, isPubliclyRoutableAddress, normalizeOrigin, resolveRedirectTarget, validateJsonpCallback, verifyCsrfToken };

package/lib/controls/index.mjs

@@ -0,0 +1,8 @@
+import { assertOutboundUrl, classifyAddress, isPubliclyRoutableAddress } from "./address.mjs";
+import { createCsrfToken, verifyCsrfToken } from "./csrf.mjs";
+import { checkCorsResponsePolicy, isAllowedOrigin, normalizeOrigin } from "./origin.mjs";
+import { resolveRedirectTarget } from "./redirect.mjs";
+import { analyzeGraphQLRequest, analyzeQueryComplexity, validateJsonpCallback } from "./query.mjs";
+import { checkJsonPayloadLimits } from "./payload.mjs";
+import { assertUploadType, detectFileSignature } from "./upload.mjs";
+export { analyzeGraphQLRequest, analyzeQueryComplexity, assertOutboundUrl, assertUploadType, checkCorsResponsePolicy, checkJsonPayloadLimits, classifyAddress, createCsrfToken, detectFileSignature, isAllowedOrigin, isPubliclyRoutableAddress, normalizeOrigin, resolveRedirectTarget, validateJsonpCallback, verifyCsrfToken };

package/lib/controls/origin.d.mts

@@ -0,0 +1,95 @@
+//#region src/controls/origin.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.
+ */
+/**
+ * Reduce an origin string to its canonical serialized form.
+ *
+ * Lowercases the scheme and host, drops a redundant default port, and refuses anything
+ * carrying a path, query, fragment, or userinfo — none of which belongs in an origin,
+ * and each of which is a way to smuggle a different host past a careless comparison.
+ *
+ * @param origin - Raw `Origin` header value.
+ * @returns The canonical origin (`https://example.com`, `https://example.com:8443`), or
+ *   `null` when the value is not a well-formed, comparable origin. The literal `"null"`
+ *   origin always yields `null`.
+ *
+ * @example
+ * ```ts
+ * normalizeOrigin("HTTPS://Example.COM:443"); // "https://example.com"
+ * normalizeOrigin("https://example.com/path"); // null — origins carry no path
+ * normalizeOrigin("null");                     // null
+ * ```
+ */
+declare function normalizeOrigin(origin: string): string | null;
+/** Options for {@link isAllowedOrigin}. */
+interface OriginPolicyOptions {
+  /**
+   * Parent origins whose **subdomains** are also accepted. Matching is on label
+   * boundaries, so `https://example.com` admits `https://app.example.com` but never
+   * `https://example.com.evil.test` and never `https://notexample.com`.
+   *
+   * Off by default. Enabling it makes every subdomain as trusted as the parent —
+   * including any subdomain an attacker manages to take over, which is WSTG-CONF-10.
+   */
+  readonly allowSubdomainsOf?: readonly string[];
+}
+/**
+ * Decide whether an origin is allowed.
+ *
+ * Both sides are normalized, then matched **exactly**. There is no prefix, suffix, or
+ * substring path through this function, and no wildcard: the allowlist is a list of
+ * origins, not a list of patterns.
+ *
+ * @param origin - The request's `Origin` header value.
+ * @param allowlist - Origins to accept. Entries that fail normalization are skipped
+ *   rather than silently widening the policy.
+ * @param options - See {@link OriginPolicyOptions}.
+ * @returns `true` only when the origin is well-formed and present in the allowlist.
+ *
+ * @example
+ * ```ts
+ * const ALLOWED = ["https://app.example.com", "https://admin.example.com"];
+ *
+ * if (isAllowedOrigin(req.headers.origin ?? "", ALLOWED)) {
+ *   // Echo the *normalized allowlisted* value, never the raw request header.
+ *   res.setHeader("Access-Control-Allow-Origin", normalizeOrigin(req.headers.origin)!);
+ *   res.setHeader("Vary", "Origin");
+ * }
+ * ```
+ */
+declare function isAllowedOrigin(origin: string, allowlist: readonly string[], options?: OriginPolicyOptions): boolean;
+/** A CORS response configuration, checked for the credentialed-wildcard mistake. */
+interface CorsResponsePolicy {
+  /** Value destined for `Access-Control-Allow-Origin`. */
+  readonly allowOrigin: string;
+  /** Whether `Access-Control-Allow-Credentials: true` will be sent. */
+  readonly allowCredentials: boolean;
+}
+/**
+ * Reject the CORS combinations that browsers treat as an error and servers still ship:
+ * `Access-Control-Allow-Origin: *` or `null` together with
+ * `Access-Control-Allow-Credentials: true`.
+ *
+ * Call it where response headers are assembled, so the mistake fails a test rather than
+ * reaching production.
+ *
+ * @param policy - The headers about to be sent.
+ * @returns `null` when the combination is safe, otherwise a message naming the problem.
+ */
+declare function checkCorsResponsePolicy(policy: CorsResponsePolicy): string | null;
+//#endregion
+export { CorsResponsePolicy, OriginPolicyOptions, checkCorsResponsePolicy, isAllowedOrigin, normalizeOrigin };
+//# sourceMappingURL=origin.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"origin.d.mts","names":[],"sources":["../../src/controls/origin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEgB,gBAAgB;;UAiCf;;;;;;;;;WASP;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCM,gBACf,gBACA,8BACA,UAAS;;UAqCO;;WAEP;;WAEA;;;;;;;;;;;;;iBAcM,wBAAwB,QAAQ"}

package/lib/controls/origin.mjs

@@ -0,0 +1,156 @@
+//#region src/controls/origin.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 CORS origin validation — the control for WSTG-CLNT-07.
+*
+* No signature helps here: `Origin: https://evil.example` is byte-identical in shape to
+* a legitimate origin, and the vulnerability lives in how the *server* decides to
+* reflect it. So this is a decision function, not a detector.
+*
+* Every real-world CORS bypass comes from one of four shortcuts, and each is refused
+* explicitly below:
+*
+* 1. `startsWith` / `includes` matching — `https://example.com.evil.test` passes a
+*    prefix check and `https://evil-example.com` passes a substring check.
+* 2. Reflecting the request's own `Origin` header into `Access-Control-Allow-Origin`.
+* 3. Accepting the literal `null` origin, which any sandboxed iframe or `data:`
+*    document can send.
+* 4. Pairing `Access-Control-Allow-Origin: *` with
+*    `Access-Control-Allow-Credentials: true`.
+*
+* @module @resq-systems/security/controls/origin
+*/
+/** Default ports omitted from an origin's serialized form. */
+const DEFAULT_PORTS = {
+	"http:": "80",
+	"https:": "443",
+	"ws:": "80",
+	"wss:": "443"
+};
+/** Schemes an origin may use. Anything else is refused before comparison. */
+const ALLOWED_SCHEMES = /* @__PURE__ */ new Set([
+	"http:",
+	"https:",
+	"ws:",
+	"wss:"
+]);
+/**
+* Reduce an origin string to its canonical serialized form.
+*
+* Lowercases the scheme and host, drops a redundant default port, and refuses anything
+* carrying a path, query, fragment, or userinfo — none of which belongs in an origin,
+* and each of which is a way to smuggle a different host past a careless comparison.
+*
+* @param origin - Raw `Origin` header value.
+* @returns The canonical origin (`https://example.com`, `https://example.com:8443`), or
+*   `null` when the value is not a well-formed, comparable origin. The literal `"null"`
+*   origin always yields `null`.
+*
+* @example
+* ```ts
+* normalizeOrigin("HTTPS://Example.COM:443"); // "https://example.com"
+* normalizeOrigin("https://example.com/path"); // null — origins carry no path
+* normalizeOrigin("null");                     // null
+* ```
+*/
+function normalizeOrigin(origin) {
+	if (typeof origin !== "string") return null;
+	const trimmed = origin.trim();
+	if (trimmed.length === 0 || trimmed === "null" || trimmed === "*") return null;
+	let parsed;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		return null;
+	}
+	if (!ALLOWED_SCHEMES.has(parsed.protocol)) return null;
+	if (parsed.username !== "" || parsed.password !== "") return null;
+	if (parsed.search !== "" || parsed.hash !== "") return null;
+	if (parsed.pathname !== "/") return null;
+	if (parsed.hostname.length === 0) return null;
+	const port = parsed.port === DEFAULT_PORTS[parsed.protocol] ? "" : parsed.port;
+	const host = parsed.hostname.toLowerCase();
+	return port === "" ? `${parsed.protocol}//${host}` : `${parsed.protocol}//${host}:${port}`;
+}
+/** True when `host` is a strict subdomain of `parentHost`, on a label boundary. */
+function isSubdomainOf(host, parentHost) {
+	return host.length > parentHost.length && host.endsWith(`.${parentHost}`);
+}
+/**
+* Decide whether an origin is allowed.
+*
+* Both sides are normalized, then matched **exactly**. There is no prefix, suffix, or
+* substring path through this function, and no wildcard: the allowlist is a list of
+* origins, not a list of patterns.
+*
+* @param origin - The request's `Origin` header value.
+* @param allowlist - Origins to accept. Entries that fail normalization are skipped
+*   rather than silently widening the policy.
+* @param options - See {@link OriginPolicyOptions}.
+* @returns `true` only when the origin is well-formed and present in the allowlist.
+*
+* @example
+* ```ts
+* const ALLOWED = ["https://app.example.com", "https://admin.example.com"];
+*
+* if (isAllowedOrigin(req.headers.origin ?? "", ALLOWED)) {
+*   // Echo the *normalized allowlisted* value, never the raw request header.
+*   res.setHeader("Access-Control-Allow-Origin", normalizeOrigin(req.headers.origin)!);
+*   res.setHeader("Vary", "Origin");
+* }
+* ```
+*/
+function isAllowedOrigin(origin, allowlist, options = {}) {
+	const candidate = normalizeOrigin(origin);
+	if (candidate === null) return false;
+	const entries = Array.isArray(allowlist) ? allowlist : [];
+	for (const entry of entries) if (normalizeOrigin(entry) === candidate) return true;
+	const parents = options.allowSubdomainsOf;
+	if (!Array.isArray(parents) || parents.length === 0) return false;
+	const candidateUrl = new URL(candidate);
+	for (const parent of parents) {
+		const normalizedParent = normalizeOrigin(parent);
+		if (normalizedParent === null) continue;
+		const parentUrl = new URL(normalizedParent);
+		if (parentUrl.protocol !== candidateUrl.protocol) continue;
+		if (parentUrl.port !== candidateUrl.port) continue;
+		if (isSubdomainOf(candidateUrl.hostname, parentUrl.hostname)) return true;
+	}
+	return false;
+}
+/**
+* Reject the CORS combinations that browsers treat as an error and servers still ship:
+* `Access-Control-Allow-Origin: *` or `null` together with
+* `Access-Control-Allow-Credentials: true`.
+*
+* Call it where response headers are assembled, so the mistake fails a test rather than
+* reaching production.
+*
+* @param policy - The headers about to be sent.
+* @returns `null` when the combination is safe, otherwise a message naming the problem.
+*/
+function checkCorsResponsePolicy(policy) {
+	if (!policy.allowCredentials) return null;
+	const value = policy.allowOrigin.trim();
+	if (value === "*") return "Access-Control-Allow-Origin: * cannot be combined with Access-Control-Allow-Credentials: true — name the exact origin instead";
+	if (value === "null") return "Access-Control-Allow-Origin: null grants access to sandboxed and data: documents — name the exact origin instead";
+	return null;
+}
+//#endregion
+export { checkCorsResponsePolicy, isAllowedOrigin, normalizeOrigin };
+
+//# sourceMappingURL=origin.mjs.map

package/lib/controls/origin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.mjs","names":[],"sources":["../../src/controls/origin.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 CORS origin validation — the control for WSTG-CLNT-07.\n *\n * No signature helps here: `Origin: https://evil.example` is byte-identical in shape to\n * a legitimate origin, and the vulnerability lives in how the *server* decides to\n * reflect it. So this is a decision function, not a detector.\n *\n * Every real-world CORS bypass comes from one of four shortcuts, and each is refused\n * explicitly below:\n *\n * 1. `startsWith` / `includes` matching — `https://example.com.evil.test` passes a\n *    prefix check and `https://evil-example.com` passes a substring check.\n * 2. Reflecting the request's own `Origin` header into `Access-Control-Allow-Origin`.\n * 3. Accepting the literal `null` origin, which any sandboxed iframe or `data:`\n *    document can send.\n * 4. Pairing `Access-Control-Allow-Origin: *` with\n *    `Access-Control-Allow-Credentials: true`.\n *\n * @module @resq-systems/security/controls/origin\n */\n\n//#region Normalization\n\n/** Default ports omitted from an origin's serialized form. */\nconst DEFAULT_PORTS: Readonly<Record<string, string>> = {\n\t\"http:\": \"80\",\n\t\"https:\": \"443\",\n\t\"ws:\": \"80\",\n\t\"wss:\": \"443\",\n};\n\n/** Schemes an origin may use. Anything else is refused before comparison. */\nconst ALLOWED_SCHEMES = new Set([\"http:\", \"https:\", \"ws:\", \"wss:\"]);\n\n/**\n * Reduce an origin string to its canonical serialized form.\n *\n * Lowercases the scheme and host, drops a redundant default port, and refuses anything\n * carrying a path, query, fragment, or userinfo — none of which belongs in an origin,\n * and each of which is a way to smuggle a different host past a careless comparison.\n *\n * @param origin - Raw `Origin` header value.\n * @returns The canonical origin (`https://example.com`, `https://example.com:8443`), or\n *   `null` when the value is not a well-formed, comparable origin. The literal `\"null\"`\n *   origin always yields `null`.\n *\n * @example\n * ```ts\n * normalizeOrigin(\"HTTPS://Example.COM:443\"); // \"https://example.com\"\n * normalizeOrigin(\"https://example.com/path\"); // null — origins carry no path\n * normalizeOrigin(\"null\");                     // null\n * ```\n */\nexport function normalizeOrigin(origin: string): string | null {\n\tif (typeof origin !== \"string\") return null;\n\n\tconst trimmed = origin.trim();\n\t// Any sandboxed iframe, `data:` document, or cross-origin redirect can present\n\t// `null`. It is never a grant of trust, so it never survives normalization.\n\tif (trimmed.length === 0 || trimmed === \"null\" || trimmed === \"*\") return null;\n\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(trimmed);\n\t} catch {\n\t\treturn null;\n\t}\n\n\tif (!ALLOWED_SCHEMES.has(parsed.protocol)) return null;\n\tif (parsed.username !== \"\" || parsed.password !== \"\") return null;\n\tif (parsed.search !== \"\" || parsed.hash !== \"\") return null;\n\t// `new URL(\"https://example.com\")` yields pathname \"/\", the only acceptable value;\n\t// anything longer means a path was supplied and this is not a bare origin.\n\tif (parsed.pathname !== \"/\") return null;\n\tif (parsed.hostname.length === 0) return null;\n\n\tconst port = parsed.port === DEFAULT_PORTS[parsed.protocol] ? \"\" : parsed.port;\n\tconst host = parsed.hostname.toLowerCase();\n\treturn port === \"\" ? `${parsed.protocol}//${host}` : `${parsed.protocol}//${host}:${port}`;\n}\n\n//#endregion\n\n//#region Matching\n\n/** Options for {@link isAllowedOrigin}. */\nexport interface OriginPolicyOptions {\n\t/**\n\t * Parent origins whose **subdomains** are also accepted. Matching is on label\n\t * boundaries, so `https://example.com` admits `https://app.example.com` but never\n\t * `https://example.com.evil.test` and never `https://notexample.com`.\n\t *\n\t * Off by default. Enabling it makes every subdomain as trusted as the parent —\n\t * including any subdomain an attacker manages to take over, which is WSTG-CONF-10.\n\t */\n\treadonly allowSubdomainsOf?: readonly string[];\n}\n\n/** True when `host` is a strict subdomain of `parentHost`, on a label boundary. */\nfunction isSubdomainOf(host: string, parentHost: string): boolean {\n\treturn host.length > parentHost.length && host.endsWith(`.${parentHost}`);\n}\n\n/**\n * Decide whether an origin is allowed.\n *\n * Both sides are normalized, then matched **exactly**. There is no prefix, suffix, or\n * substring path through this function, and no wildcard: the allowlist is a list of\n * origins, not a list of patterns.\n *\n * @param origin - The request's `Origin` header value.\n * @param allowlist - Origins to accept. Entries that fail normalization are skipped\n *   rather than silently widening the policy.\n * @param options - See {@link OriginPolicyOptions}.\n * @returns `true` only when the origin is well-formed and present in the allowlist.\n *\n * @example\n * ```ts\n * const ALLOWED = [\"https://app.example.com\", \"https://admin.example.com\"];\n *\n * if (isAllowedOrigin(req.headers.origin ?? \"\", ALLOWED)) {\n *   // Echo the *normalized allowlisted* value, never the raw request header.\n *   res.setHeader(\"Access-Control-Allow-Origin\", normalizeOrigin(req.headers.origin)!);\n *   res.setHeader(\"Vary\", \"Origin\");\n * }\n * ```\n */\nexport function isAllowedOrigin(\n\torigin: string,\n\tallowlist: readonly string[],\n\toptions: OriginPolicyOptions = {},\n): boolean {\n\tconst candidate = normalizeOrigin(origin);\n\tif (candidate === null) return false;\n\n\tconst entries = Array.isArray(allowlist) ? allowlist : [];\n\tfor (const entry of entries) {\n\t\tif (normalizeOrigin(entry) === candidate) return true;\n\t}\n\n\t// Checked after the exact list, not instead of it: an empty `allowlist` combined\n\t// with a populated `allowSubdomainsOf` is a legitimate configuration, and an early\n\t// return on `allowlist.length === 0` would silently deny every request.\n\tconst parents = options.allowSubdomainsOf;\n\tif (!Array.isArray(parents) || parents.length === 0) return false;\n\n\t// Scheme, port, and host are compared separately so a subdomain grant cannot also\n\t// downgrade the scheme or move the port.\n\tconst candidateUrl = new URL(candidate);\n\tfor (const parent of parents) {\n\t\tconst normalizedParent = normalizeOrigin(parent);\n\t\tif (normalizedParent === null) continue;\n\n\t\tconst parentUrl = new URL(normalizedParent);\n\t\tif (parentUrl.protocol !== candidateUrl.protocol) continue;\n\t\tif (parentUrl.port !== candidateUrl.port) continue;\n\t\tif (isSubdomainOf(candidateUrl.hostname, parentUrl.hostname)) return true;\n\t}\n\n\treturn false;\n}\n\n//#endregion\n\n//#region Policy assertion\n\n/** A CORS response configuration, checked for the credentialed-wildcard mistake. */\nexport interface CorsResponsePolicy {\n\t/** Value destined for `Access-Control-Allow-Origin`. */\n\treadonly allowOrigin: string;\n\t/** Whether `Access-Control-Allow-Credentials: true` will be sent. */\n\treadonly allowCredentials: boolean;\n}\n\n/**\n * Reject the CORS combinations that browsers treat as an error and servers still ship:\n * `Access-Control-Allow-Origin: *` or `null` together with\n * `Access-Control-Allow-Credentials: true`.\n *\n * Call it where response headers are assembled, so the mistake fails a test rather than\n * reaching production.\n *\n * @param policy - The headers about to be sent.\n * @returns `null` when the combination is safe, otherwise a message naming the problem.\n */\nexport function checkCorsResponsePolicy(policy: CorsResponsePolicy): string | null {\n\tif (!policy.allowCredentials) return null;\n\n\tconst value = policy.allowOrigin.trim();\n\tif (value === \"*\") {\n\t\treturn \"Access-Control-Allow-Origin: * cannot be combined with Access-Control-Allow-Credentials: true — name the exact origin instead\";\n\t}\n\tif (value === \"null\") {\n\t\treturn \"Access-Control-Allow-Origin: null grants access to sandboxed and data: documents — name the exact origin instead\";\n\t}\n\treturn null;\n}\n\n//#endregion\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,gBAAkD;CACvD,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;AACT;;AAGA,MAAM,kCAAkB,IAAI,IAAI;CAAC;CAAS;CAAU;CAAO;AAAM,CAAC;;;;;;;;;;;;;;;;;;;;AAqBlE,SAAgB,gBAAgB,QAA+B;CAC9D,IAAI,OAAO,WAAW,UAAU,OAAO;CAEvC,MAAM,UAAU,OAAO,KAAK;CAG5B,IAAI,QAAQ,WAAW,KAAK,YAAY,UAAU,YAAY,KAAK,OAAO;CAE1E,IAAI;CACJ,IAAI;EACH,SAAS,IAAI,IAAI,OAAO;CACzB,QAAQ;EACP,OAAO;CACR;CAEA,IAAI,CAAC,gBAAgB,IAAI,OAAO,QAAQ,GAAG,OAAO;CAClD,IAAI,OAAO,aAAa,MAAM,OAAO,aAAa,IAAI,OAAO;CAC7D,IAAI,OAAO,WAAW,MAAM,OAAO,SAAS,IAAI,OAAO;CAGvD,IAAI,OAAO,aAAa,KAAK,OAAO;CACpC,IAAI,OAAO,SAAS,WAAW,GAAG,OAAO;CAEzC,MAAM,OAAO,OAAO,SAAS,cAAc,OAAO,YAAY,KAAK,OAAO;CAC1E,MAAM,OAAO,OAAO,SAAS,YAAY;CACzC,OAAO,SAAS,KAAK,GAAG,OAAO,SAAS,IAAI,SAAS,GAAG,OAAO,SAAS,IAAI,KAAK,GAAG;AACrF;;AAoBA,SAAS,cAAc,MAAc,YAA6B;CACjE,OAAO,KAAK,SAAS,WAAW,UAAU,KAAK,SAAS,IAAI,YAAY;AACzE;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,gBACf,QACA,WACA,UAA+B,CAAC,GACtB;CACV,MAAM,YAAY,gBAAgB,MAAM;CACxC,IAAI,cAAc,MAAM,OAAO;CAE/B,MAAM,UAAU,MAAM,QAAQ,SAAS,IAAI,YAAY,CAAC;CACxD,KAAK,MAAM,SAAS,SACnB,IAAI,gBAAgB,KAAK,MAAM,WAAW,OAAO;CAMlD,MAAM,UAAU,QAAQ;CACxB,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,QAAQ,WAAW,GAAG,OAAO;CAI5D,MAAM,eAAe,IAAI,IAAI,SAAS;CACtC,KAAK,MAAM,UAAU,SAAS;EAC7B,MAAM,mBAAmB,gBAAgB,MAAM;EAC/C,IAAI,qBAAqB,MAAM;EAE/B,MAAM,YAAY,IAAI,IAAI,gBAAgB;EAC1C,IAAI,UAAU,aAAa,aAAa,UAAU;EAClD,IAAI,UAAU,SAAS,aAAa,MAAM;EAC1C,IAAI,cAAc,aAAa,UAAU,UAAU,QAAQ,GAAG,OAAO;CACtE;CAEA,OAAO;AACR;;;;;;;;;;;;AAyBA,SAAgB,wBAAwB,QAA2C;CAClF,IAAI,CAAC,OAAO,kBAAkB,OAAO;CAErC,MAAM,QAAQ,OAAO,YAAY,KAAK;CACtC,IAAI,UAAU,KACb,OAAO;CAER,IAAI,UAAU,QACb,OAAO;CAER,OAAO;AACR"}

package/lib/controls/payload.d.mts

@@ -0,0 +1,84 @@
+//#region src/controls/payload.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 Structural bounds on a JSON payload, measured from the text before
+ * anything parses it (OWASP API Security API4 — unrestricted resource consumption).
+ *
+ * @module @resq-systems/security/controls/payload
+ */
+/** Bounds for {@link checkJsonPayloadLimits}. */
+interface JsonPayloadLimits {
+  /** Deepest container nesting. Defaults to 100. */
+  readonly maxDepth?: number;
+  /** Most entries in any single array. Defaults to 10 000. */
+  readonly maxArrayLength?: number;
+  /** Most keys in any single object. Defaults to 2 000. */
+  readonly maxObjectKeys?: number;
+  /** Longest single string value, in characters. Defaults to 1 000 000. */
+  readonly maxStringLength?: number;
+  /** Longest payload overall, in characters. Defaults to 5 000 000. */
+  readonly maxLength?: number;
+}
+/** Result of {@link checkJsonPayloadLimits}. */
+interface JsonPayloadReport {
+  /** Deepest container nesting reached. */
+  readonly depth: number;
+  /** Largest array seen, by entry count. */
+  readonly arrayLength: number;
+  /** Largest object seen, by key count. */
+  readonly objectKeys: number;
+  /** Longest string value seen. */
+  readonly stringLength: number;
+  /** Character length of the payload. */
+  readonly length: number;
+  /** `true` when every bound is satisfied. */
+  readonly withinLimits: boolean;
+  /** Names of the bounds exceeded; empty when `withinLimits`. */
+  readonly exceeded: readonly string[];
+}
+/**
+ * Measure a JSON payload's structure without parsing it.
+ *
+ * `JSON.parse` allocates the whole object graph before a caller can inspect anything, so
+ * a body designed to exhaust memory has already succeeded by the time validation runs.
+ * This is one linear pass over the *text*: it counts nesting, container sizes and string
+ * lengths, and never builds a value.
+ *
+ * Reporting rather than enforcing, deliberately. It returns what it measured and which
+ * bounds were exceeded; the caller decides. Schema validation remains the real control
+ * for shape — this only bounds the cost of getting there.
+ *
+ * Malformed JSON is not diagnosed. The scanner is a bracket counter, so an invalid or
+ * truncated payload yields whatever it measured before running out; use `JSON.parse` for
+ * validity, once this has bounded the cost.
+ *
+ * @param text - The raw JSON text, before parsing.
+ * @param limits - See {@link JsonPayloadLimits}.
+ * @returns The measured {@link JsonPayloadReport}. Never throws.
+ *
+ * @example
+ * ```ts
+ * const report = checkJsonPayloadLimits(await request.text());
+ * if (!report.withinLimits) {
+ *   return new Response(`Payload rejected: ${report.exceeded.join(", ")}`, { status: 413 });
+ * }
+ * ```
+ */
+declare function checkJsonPayloadLimits(text: string, limits?: JsonPayloadLimits): JsonPayloadReport;
+//#endregion
+export { JsonPayloadLimits, JsonPayloadReport, checkJsonPayloadLimits };
+//# sourceMappingURL=payload.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.mts","names":[],"sources":["../../src/controls/payload.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;UA0BiB;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIO;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DM,uBACf,cACA,SAAQ,oBACN"}