@resq-systems/security 1.0.4 → 2.0.0

package/lib/controls/upload.d.mts

@@ -0,0 +1,108 @@
+//#region src/controls/upload.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 Upload type agreement — the control for WSTG-BUSL-08 and BUSL-09.
+ *
+ * This deliberately is not a rule in the threat catalog, because it cannot be one at
+ * any grade: the weakness is a *disagreement between three values* — the declared
+ * `Content-Type`, the filename extension, and the actual leading bytes — and a rule
+ * sees one string at a time. `shell.php.jpg` only becomes interesting once you know
+ * the bytes are not a JPEG.
+ *
+ * The check is allowlist-shaped. A denylist of dangerous extensions is bypassed by the
+ * next extension nobody listed; an allowlist of permitted types fails closed.
+ *
+ * **Still not sufficient alone.** A polyglot can carry a valid PNG header and PHP
+ * source in its trailing bytes, and this reads only the head. The controls that hold
+ * are: generate the stored filename yourself, store outside the webroot, serve from a
+ * separate origin with a fixed `Content-Type` and `Content-Disposition: attachment`,
+ * and re-encode images through a parser rather than storing raw bytes.
+ *
+ * @module @resq-systems/security/controls/upload
+ */
+/** File types this module recognizes from leading bytes. */
+type FileTypeName = "png" | "jpeg" | "gif" | "webp" | "bmp" | "tiff" | "ico" | "pdf" | "zip" | "gzip" | "mp4" | "svg" | "text";
+/**
+ * Identify a file from its leading bytes.
+ *
+ * Binary signatures are checked first. If none matches and the bytes decode as UTF-8
+ * with no control characters, the content is classified `svg` or `text`.
+ *
+ * @param headBytes - The file's leading bytes. 64 covers every binary signature here;
+ *   256 or more improves text and SVG classification.
+ * @returns The detected type, or `null` when nothing matches.
+ *
+ * @example
+ * ```ts
+ * detectFileSignature(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+ * // "png"
+ * ```
+ */
+declare function detectFileSignature(headBytes: Uint8Array): FileTypeName | null;
+/** Why an upload was refused. */
+type UploadRejectionReason = "no_bytes" | "unrecognized_signature" | "type_not_allowed" | "extension_missing" | "extension_mismatch" | "declared_type_mismatch";
+/** Outcome of {@link assertUploadType}. */
+type UploadVerdict = {
+  readonly ok: true;
+  readonly type: FileTypeName;
+} | {
+  readonly ok: false;
+  readonly reason: UploadRejectionReason;
+  readonly detail: string;
+};
+/** Input for {@link assertUploadType}. */
+interface UploadCandidate {
+  /** `Content-Type` the client claimed. Parameters such as `; charset=` are ignored. */
+  readonly declaredType: string;
+  /** Filename the client supplied. */
+  readonly filename: string;
+  /** The file's leading bytes — at least 64, ideally 256 or more. */
+  readonly headBytes: Uint8Array;
+  /** Types permitted for this endpoint. An empty list refuses everything. */
+  readonly allow: readonly FileTypeName[];
+}
+/**
+ * Require the declared type, the filename extension, and the actual bytes to agree on
+ * one permitted file type.
+ *
+ * The bytes are authoritative — they are the only one of the three a client cannot
+ * simply assert. The other two must be consistent with what the bytes actually are,
+ * which is what refuses `shell.php.jpg` (bytes are PHP source, extension claims JPEG)
+ * and an `avatar.jpg` declared as `application/x-httpd-php`.
+ *
+ * @param candidate - See {@link UploadCandidate}.
+ * @returns `{ ok: true, type }`, or `{ ok: false, reason, detail }`. Never throws.
+ *
+ * @example
+ * ```ts
+ * const verdict = assertUploadType({
+ *   declaredType: file.type,
+ *   filename: file.name,
+ *   headBytes: new Uint8Array(await file.slice(0, 256).arrayBuffer()),
+ *   allow: ["png", "jpeg", "webp"],
+ * });
+ *
+ * if (!verdict.ok) return new Response(`Rejected: ${verdict.reason}`, { status: 400 });
+ *
+ * // Generate the stored name yourself — never reuse the client's.
+ * const stored = `${crypto.randomUUID()}.${verdict.type}`;
+ * ```
+ */
+declare function assertUploadType(candidate: UploadCandidate): UploadVerdict;
+//#endregion
+export { FileTypeName, UploadCandidate, UploadRejectionReason, UploadVerdict, assertUploadType, detectFileSignature };
+//# sourceMappingURL=upload.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.mts","names":[],"sources":["../../src/controls/upload.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAwCY;;;;;;;;;;;;;;;;;iBAoLI,oBAAoB,WAAW,aAAa;;KAqChD;;KASA;WACE;WAAmB,MAAM;;WACzB;WAAoB,QAAQ;WAAgC;;;UAGzD;;WAEP;;WAEA;;WAEA,WAAW;;WAEX,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+CV,iBAAiB,WAAW,kBAAkB"}

package/lib/controls/upload.mjs

@@ -0,0 +1,374 @@
+//#region src/controls/upload.ts
+/** ASCII bytes for an ISO base media file format brand. */
+const brand = (code) => [...code].map((c) => c.charCodeAt(0));
+/**
+* Magic-byte signatures, most specific first.
+*
+* `zip` covers DOCX, XLSX, PPTX, ODT, JAR, and APK — every one is a ZIP container and
+* nothing in the leading bytes distinguishes them. A caller needing that distinction
+* must open the archive and inspect its manifest.
+*/
+const SIGNATURES = [
+	{
+		type: "png",
+		offset: 0,
+		bytes: [
+			137,
+			80,
+			78,
+			71,
+			13,
+			10,
+			26,
+			10
+		]
+	},
+	{
+		type: "gif",
+		offset: 0,
+		bytes: [
+			71,
+			73,
+			70,
+			56
+		]
+	},
+	{
+		type: "pdf",
+		offset: 0,
+		bytes: [
+			37,
+			80,
+			68,
+			70,
+			45
+		]
+	},
+	{
+		type: "webp",
+		offset: 0,
+		bytes: [
+			82,
+			73,
+			70,
+			70
+		],
+		also: {
+			offset: 8,
+			bytes: [
+				87,
+				69,
+				66,
+				80
+			]
+		}
+	},
+	{
+		type: "jpeg",
+		offset: 0,
+		bytes: [
+			255,
+			216,
+			255
+		]
+	},
+	{
+		type: "tiff",
+		offset: 0,
+		bytes: [
+			73,
+			73,
+			42,
+			0
+		]
+	},
+	{
+		type: "tiff",
+		offset: 0,
+		bytes: [
+			77,
+			77,
+			0,
+			42
+		]
+	},
+	{
+		type: "ico",
+		offset: 0,
+		bytes: [
+			0,
+			0,
+			1,
+			0
+		]
+	},
+	{
+		type: "zip",
+		offset: 0,
+		bytes: [
+			80,
+			75,
+			3,
+			4
+		]
+	},
+	{
+		type: "zip",
+		offset: 0,
+		bytes: [
+			80,
+			75,
+			5,
+			6
+		]
+	},
+	{
+		type: "gzip",
+		offset: 0,
+		bytes: [31, 139]
+	},
+	{
+		type: "bmp",
+		offset: 0,
+		bytes: [66, 77]
+	},
+	{
+		type: "mp4",
+		offset: 4,
+		bytes: [
+			102,
+			116,
+			121,
+			112
+		],
+		alsoAnyOf: {
+			offset: 8,
+			options: [
+				"isom",
+				"iso2",
+				"iso4",
+				"iso5",
+				"iso6",
+				"mp41",
+				"mp42",
+				"mmp4",
+				"avc1",
+				"dash",
+				"M4V ",
+				"M4A ",
+				"M4P ",
+				"M4B ",
+				"qt  ",
+				"3gp4",
+				"3gp5",
+				"3g2a",
+				"MSNV"
+			].map(brand)
+		}
+	}
+];
+/** Extensions each recognized type may legitimately carry. */
+const EXTENSIONS_BY_TYPE = {
+	png: ["png"],
+	jpeg: [
+		"jpg",
+		"jpeg",
+		"jpe"
+	],
+	gif: ["gif"],
+	webp: ["webp"],
+	bmp: ["bmp"],
+	tiff: ["tif", "tiff"],
+	ico: ["ico"],
+	pdf: ["pdf"],
+	zip: [
+		"zip",
+		"docx",
+		"xlsx",
+		"pptx",
+		"odt",
+		"ods",
+		"odp",
+		"epub"
+	],
+	gzip: ["gz", "tgz"],
+	mp4: [
+		"mp4",
+		"m4v",
+		"m4a",
+		"mov"
+	],
+	svg: ["svg"],
+	text: [
+		"txt",
+		"csv",
+		"md",
+		"log",
+		"json"
+	]
+};
+/** Media types each recognized type may legitimately be declared as. */
+const MEDIA_TYPES_BY_TYPE = {
+	png: ["image/png"],
+	jpeg: ["image/jpeg", "image/jpg"],
+	gif: ["image/gif"],
+	webp: ["image/webp"],
+	bmp: ["image/bmp", "image/x-ms-bmp"],
+	tiff: ["image/tiff"],
+	ico: ["image/x-icon", "image/vnd.microsoft.icon"],
+	pdf: ["application/pdf"],
+	zip: [
+		"application/zip",
+		"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		"application/vnd.openxmlformats-officedocument.presentationml.presentation",
+		"application/vnd.oasis.opendocument.text",
+		"application/epub+zip"
+	],
+	gzip: ["application/gzip", "application/x-gzip"],
+	mp4: [
+		"video/mp4",
+		"audio/mp4",
+		"video/quicktime"
+	],
+	svg: ["image/svg+xml"],
+	text: [
+		"text/plain",
+		"text/csv",
+		"text/markdown",
+		"application/json"
+	]
+};
+/** Leading bytes inspected when no binary signature matches, to classify text. */
+const TEXT_SNIFF_LENGTH = 256;
+/** Opening of an SVG document, with or without an XML prolog or leading comments. */
+const SVG_OPENING = /^\s{0,64}(?:<\?xml[^>]{0,512}\?>\s{0,64})?(?:<!--[^>]{0,512}-->\s{0,64}){0,8}<svg\b/i;
+/** True when `haystack` contains `bytes` starting at `offset`. */
+function matchesAt(haystack, offset, bytes) {
+	if (haystack.length < offset + bytes.length) return false;
+	for (let i = 0; i < bytes.length; i++) if (haystack[offset + i] !== bytes[i]) return false;
+	return true;
+}
+/**
+* Identify a file from its leading bytes.
+*
+* Binary signatures are checked first. If none matches and the bytes decode as UTF-8
+* with no control characters, the content is classified `svg` or `text`.
+*
+* @param headBytes - The file's leading bytes. 64 covers every binary signature here;
+*   256 or more improves text and SVG classification.
+* @returns The detected type, or `null` when nothing matches.
+*
+* @example
+* ```ts
+* detectFileSignature(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+* // "png"
+* ```
+*/
+function detectFileSignature(headBytes) {
+	if (!(headBytes instanceof Uint8Array) || headBytes.length === 0) return null;
+	for (const signature of SIGNATURES) {
+		if (!matchesAt(headBytes, signature.offset, signature.bytes)) continue;
+		if (signature.also && !matchesAt(headBytes, signature.also.offset, signature.also.bytes)) continue;
+		if (signature.alsoAnyOf) {
+			const { offset, options } = signature.alsoAnyOf;
+			if (!options.some((candidate) => matchesAt(headBytes, offset, candidate))) continue;
+		}
+		return signature.type;
+	}
+	const head = headBytes.subarray(0, TEXT_SNIFF_LENGTH);
+	let decoded;
+	try {
+		decoded = new TextDecoder("utf-8", { fatal: true }).decode(head);
+	} catch {
+		return null;
+	}
+	for (let i = 0; i < decoded.length; i++) {
+		const code = decoded.charCodeAt(i);
+		if (code < 32 && code !== 9 && code !== 10 && code !== 13) return null;
+	}
+	return SVG_OPENING.test(decoded) ? "svg" : "text";
+}
+/** Lowercase extension without the dot, or `null` when the name carries none. */
+function extensionOf(filename) {
+	const lastDot = filename.lastIndexOf(".");
+	if (lastDot <= 0 || lastDot === filename.length - 1) return null;
+	return filename.slice(lastDot + 1).toLowerCase().trim();
+}
+/** Media type with parameters and casing stripped. */
+function mediaTypeOf(declaredType) {
+	if (typeof declaredType !== "string") return "";
+	const [base = ""] = declaredType.split(";");
+	return base.trim().toLowerCase();
+}
+/**
+* Require the declared type, the filename extension, and the actual bytes to agree on
+* one permitted file type.
+*
+* The bytes are authoritative — they are the only one of the three a client cannot
+* simply assert. The other two must be consistent with what the bytes actually are,
+* which is what refuses `shell.php.jpg` (bytes are PHP source, extension claims JPEG)
+* and an `avatar.jpg` declared as `application/x-httpd-php`.
+*
+* @param candidate - See {@link UploadCandidate}.
+* @returns `{ ok: true, type }`, or `{ ok: false, reason, detail }`. Never throws.
+*
+* @example
+* ```ts
+* const verdict = assertUploadType({
+*   declaredType: file.type,
+*   filename: file.name,
+*   headBytes: new Uint8Array(await file.slice(0, 256).arrayBuffer()),
+*   allow: ["png", "jpeg", "webp"],
+* });
+*
+* if (!verdict.ok) return new Response(`Rejected: ${verdict.reason}`, { status: 400 });
+*
+* // Generate the stored name yourself — never reuse the client's.
+* const stored = `${crypto.randomUUID()}.${verdict.type}`;
+* ```
+*/
+function assertUploadType(candidate) {
+	const { declaredType, filename, headBytes, allow } = candidate;
+	if (!(headBytes instanceof Uint8Array) || headBytes.length === 0) return {
+		ok: false,
+		reason: "no_bytes",
+		detail: "headBytes was empty"
+	};
+	const detected = detectFileSignature(headBytes);
+	if (detected === null) return {
+		ok: false,
+		reason: "unrecognized_signature",
+		detail: "leading bytes match no known file type"
+	};
+	if (!Array.isArray(allow) || !allow.includes(detected)) return {
+		ok: false,
+		reason: "type_not_allowed",
+		detail: `detected ${detected}, which is not in the allowlist`
+	};
+	const extension = extensionOf(typeof filename === "string" ? filename : "");
+	if (extension === null) return {
+		ok: false,
+		reason: "extension_missing",
+		detail: "filename carries no extension"
+	};
+	if (!EXTENSIONS_BY_TYPE[detected].includes(extension)) return {
+		ok: false,
+		reason: "extension_mismatch",
+		detail: `bytes are ${detected} but the extension is .${extension}`
+	};
+	const media = mediaTypeOf(declaredType);
+	if (media.length > 0 && !MEDIA_TYPES_BY_TYPE[detected].includes(media)) return {
+		ok: false,
+		reason: "declared_type_mismatch",
+		detail: `bytes are ${detected} but Content-Type claimed ${media}`
+	};
+	return {
+		ok: true,
+		type: detected
+	};
+}
+//#endregion
+export { assertUploadType, detectFileSignature };
+
+//# sourceMappingURL=upload.mjs.map

package/lib/controls/upload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.mjs","names":[],"sources":["../../src/controls/upload.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 Upload type agreement — the control for WSTG-BUSL-08 and BUSL-09.\n *\n * This deliberately is not a rule in the threat catalog, because it cannot be one at\n * any grade: the weakness is a *disagreement between three values* — the declared\n * `Content-Type`, the filename extension, and the actual leading bytes — and a rule\n * sees one string at a time. `shell.php.jpg` only becomes interesting once you know\n * the bytes are not a JPEG.\n *\n * The check is allowlist-shaped. A denylist of dangerous extensions is bypassed by the\n * next extension nobody listed; an allowlist of permitted types fails closed.\n *\n * **Still not sufficient alone.** A polyglot can carry a valid PNG header and PHP\n * source in its trailing bytes, and this reads only the head. The controls that hold\n * are: generate the stored filename yourself, store outside the webroot, serve from a\n * separate origin with a fixed `Content-Type` and `Content-Disposition: attachment`,\n * and re-encode images through a parser rather than storing raw bytes.\n *\n * @module @resq-systems/security/controls/upload\n */\n\n//#region Signature table\n\n/** File types this module recognizes from leading bytes. */\nexport type FileTypeName =\n\t| \"png\"\n\t| \"jpeg\"\n\t| \"gif\"\n\t| \"webp\"\n\t| \"bmp\"\n\t| \"tiff\"\n\t| \"ico\"\n\t| \"pdf\"\n\t| \"zip\"\n\t| \"gzip\"\n\t| \"mp4\"\n\t| \"svg\"\n\t| \"text\";\n\n/** One magic-byte signature. `offset` is where `bytes` must appear. */\ninterface FileSignature {\n\treadonly type: FileTypeName;\n\treadonly offset: number;\n\treadonly bytes: readonly number[];\n\t/** Further bytes required at a second offset, for container formats. */\n\treadonly also?: { readonly offset: number; readonly bytes: readonly number[] };\n\t/** Further bytes at a second offset, any one of which satisfies the signature. */\n\treadonly alsoAnyOf?: {\n\t\treadonly offset: number;\n\t\treadonly options: readonly (readonly number[])[];\n\t};\n}\n\n/** ASCII bytes for an ISO base media file format brand. */\nconst brand = (code: string): readonly number[] => [...code].map((c) => c.charCodeAt(0));\n\n/**\n * ISO-BMFF major brands accepted for the `mp4` family.\n *\n * The `ftyp` box marker sits at offset 4, so a signature that checks only those four\n * bytes constrains nothing at offset 0 — `<!--ftyp--><script>alert(1)</script>` was\n * detected as `mp4` and accepted as `clip.mp4`. Every other row in the table pins\n * offset 0; this one cannot, so it pins the brand at offset 8 instead.\n *\n * The list is deliberately generous: too narrow and legitimate video is rejected,\n * trading a fail-open for a fail-closed. `qt  ` is required by the `.mov` and\n * `video/quicktime` entries already present in the extension and media-type tables.\n */\nconst MP4_BRANDS: readonly (readonly number[])[] = [\n\t\"isom\",\n\t\"iso2\",\n\t\"iso4\",\n\t\"iso5\",\n\t\"iso6\",\n\t\"mp41\",\n\t\"mp42\",\n\t\"mmp4\",\n\t\"avc1\",\n\t\"dash\",\n\t\"M4V \",\n\t\"M4A \",\n\t\"M4P \",\n\t\"M4B \",\n\t\"qt  \",\n\t\"3gp4\",\n\t\"3gp5\",\n\t\"3g2a\",\n\t\"MSNV\",\n].map(brand);\n\n/**\n * Magic-byte signatures, most specific first.\n *\n * `zip` covers DOCX, XLSX, PPTX, ODT, JAR, and APK — every one is a ZIP container and\n * nothing in the leading bytes distinguishes them. A caller needing that distinction\n * must open the archive and inspect its manifest.\n */\nconst SIGNATURES: readonly FileSignature[] = [\n\t{ type: \"png\", offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },\n\t{ type: \"gif\", offset: 0, bytes: [0x47, 0x49, 0x46, 0x38] },\n\t{ type: \"pdf\", offset: 0, bytes: [0x25, 0x50, 0x44, 0x46, 0x2d] },\n\t// RIFF....WEBP — the four size bytes between the markers are skipped.\n\t{\n\t\ttype: \"webp\",\n\t\toffset: 0,\n\t\tbytes: [0x52, 0x49, 0x46, 0x46],\n\t\talso: { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] },\n\t},\n\t{ type: \"jpeg\", offset: 0, bytes: [0xff, 0xd8, 0xff] },\n\t{ type: \"tiff\", offset: 0, bytes: [0x49, 0x49, 0x2a, 0x00] },\n\t{ type: \"tiff\", offset: 0, bytes: [0x4d, 0x4d, 0x00, 0x2a] },\n\t{ type: \"ico\", offset: 0, bytes: [0x00, 0x00, 0x01, 0x00] },\n\t{ type: \"zip\", offset: 0, bytes: [0x50, 0x4b, 0x03, 0x04] },\n\t{ type: \"zip\", offset: 0, bytes: [0x50, 0x4b, 0x05, 0x06] },\n\t{ type: \"gzip\", offset: 0, bytes: [0x1f, 0x8b] },\n\t{ type: \"bmp\", offset: 0, bytes: [0x42, 0x4d] },\n\t// Last, and below every offset-0 row, so it can never shadow a fixed magic number.\n\t// The brand requirement at offset 8 is what stops arbitrary content from claiming\n\t// to be video on the strength of four bytes at offset 4.\n\t{\n\t\ttype: \"mp4\",\n\t\toffset: 4,\n\t\tbytes: [0x66, 0x74, 0x79, 0x70],\n\t\talsoAnyOf: { offset: 8, options: MP4_BRANDS },\n\t},\n];\n\n/** Extensions each recognized type may legitimately carry. */\nconst EXTENSIONS_BY_TYPE: Readonly<Record<FileTypeName, readonly string[]>> = {\n\tpng: [\"png\"],\n\tjpeg: [\"jpg\", \"jpeg\", \"jpe\"],\n\tgif: [\"gif\"],\n\twebp: [\"webp\"],\n\tbmp: [\"bmp\"],\n\ttiff: [\"tif\", \"tiff\"],\n\tico: [\"ico\"],\n\tpdf: [\"pdf\"],\n\tzip: [\"zip\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"epub\"],\n\tgzip: [\"gz\", \"tgz\"],\n\tmp4: [\"mp4\", \"m4v\", \"m4a\", \"mov\"],\n\tsvg: [\"svg\"],\n\ttext: [\"txt\", \"csv\", \"md\", \"log\", \"json\"],\n};\n\n/** Media types each recognized type may legitimately be declared as. */\nconst MEDIA_TYPES_BY_TYPE: Readonly<Record<FileTypeName, readonly string[]>> = {\n\tpng: [\"image/png\"],\n\tjpeg: [\"image/jpeg\", \"image/jpg\"],\n\tgif: [\"image/gif\"],\n\twebp: [\"image/webp\"],\n\tbmp: [\"image/bmp\", \"image/x-ms-bmp\"],\n\ttiff: [\"image/tiff\"],\n\tico: [\"image/x-icon\", \"image/vnd.microsoft.icon\"],\n\tpdf: [\"application/pdf\"],\n\tzip: [\n\t\t\"application/zip\",\n\t\t\"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n\t\t\"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n\t\t\"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n\t\t\"application/vnd.oasis.opendocument.text\",\n\t\t\"application/epub+zip\",\n\t],\n\tgzip: [\"application/gzip\", \"application/x-gzip\"],\n\tmp4: [\"video/mp4\", \"audio/mp4\", \"video/quicktime\"],\n\tsvg: [\"image/svg+xml\"],\n\ttext: [\"text/plain\", \"text/csv\", \"text/markdown\", \"application/json\"],\n};\n\n//#endregion\n\n//#region Detection\n\n/** Leading bytes inspected when no binary signature matches, to classify text. */\nconst TEXT_SNIFF_LENGTH = 256;\n\n/** Opening of an SVG document, with or without an XML prolog or leading comments. */\nconst SVG_OPENING =\n\t/^\\s{0,64}(?:<\\?xml[^>]{0,512}\\?>\\s{0,64})?(?:<!--[^>]{0,512}-->\\s{0,64}){0,8}<svg\\b/i;\n\n/** True when `haystack` contains `bytes` starting at `offset`. */\nfunction matchesAt(haystack: Uint8Array, offset: number, bytes: readonly number[]): boolean {\n\tif (haystack.length < offset + bytes.length) return false;\n\tfor (let i = 0; i < bytes.length; i++) {\n\t\tif (haystack[offset + i] !== bytes[i]) return false;\n\t}\n\treturn true;\n}\n\n/**\n * Identify a file from its leading bytes.\n *\n * Binary signatures are checked first. If none matches and the bytes decode as UTF-8\n * with no control characters, the content is classified `svg` or `text`.\n *\n * @param headBytes - The file's leading bytes. 64 covers every binary signature here;\n *   256 or more improves text and SVG classification.\n * @returns The detected type, or `null` when nothing matches.\n *\n * @example\n * ```ts\n * detectFileSignature(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));\n * // \"png\"\n * ```\n */\nexport function detectFileSignature(headBytes: Uint8Array): FileTypeName | null {\n\tif (!(headBytes instanceof Uint8Array) || headBytes.length === 0) return null;\n\n\tfor (const signature of SIGNATURES) {\n\t\tif (!matchesAt(headBytes, signature.offset, signature.bytes)) continue;\n\t\tif (signature.also && !matchesAt(headBytes, signature.also.offset, signature.also.bytes)) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (signature.alsoAnyOf) {\n\t\t\tconst { offset, options } = signature.alsoAnyOf;\n\t\t\tif (!options.some((candidate) => matchesAt(headBytes, offset, candidate))) continue;\n\t\t}\n\t\treturn signature.type;\n\t}\n\n\tconst head = headBytes.subarray(0, TEXT_SNIFF_LENGTH);\n\tlet decoded: string;\n\ttry {\n\t\tdecoded = new TextDecoder(\"utf-8\", { fatal: true }).decode(head);\n\t} catch {\n\t\treturn null;\n\t}\n\n\t// A NUL or other C0 control (tab, CR, and LF excepted) means this is not text.\n\tfor (let i = 0; i < decoded.length; i++) {\n\t\tconst code = decoded.charCodeAt(i);\n\t\tif (code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d) return null;\n\t}\n\n\treturn SVG_OPENING.test(decoded) ? \"svg\" : \"text\";\n}\n\n//#endregion\n\n//#region Agreement check\n\n/** Why an upload was refused. */\nexport type UploadRejectionReason =\n\t| \"no_bytes\"\n\t| \"unrecognized_signature\"\n\t| \"type_not_allowed\"\n\t| \"extension_missing\"\n\t| \"extension_mismatch\"\n\t| \"declared_type_mismatch\";\n\n/** Outcome of {@link assertUploadType}. */\nexport type UploadVerdict =\n\t| { readonly ok: true; readonly type: FileTypeName }\n\t| { readonly ok: false; readonly reason: UploadRejectionReason; readonly detail: string };\n\n/** Input for {@link assertUploadType}. */\nexport interface UploadCandidate {\n\t/** `Content-Type` the client claimed. Parameters such as `; charset=` are ignored. */\n\treadonly declaredType: string;\n\t/** Filename the client supplied. */\n\treadonly filename: string;\n\t/** The file's leading bytes — at least 64, ideally 256 or more. */\n\treadonly headBytes: Uint8Array;\n\t/** Types permitted for this endpoint. An empty list refuses everything. */\n\treadonly allow: readonly FileTypeName[];\n}\n\n/** Lowercase extension without the dot, or `null` when the name carries none. */\nfunction extensionOf(filename: string): string | null {\n\tconst lastDot = filename.lastIndexOf(\".\");\n\tif (lastDot <= 0 || lastDot === filename.length - 1) return null;\n\treturn filename\n\t\t.slice(lastDot + 1)\n\t\t.toLowerCase()\n\t\t.trim();\n}\n\n/** Media type with parameters and casing stripped. */\nfunction mediaTypeOf(declaredType: string): string {\n\tif (typeof declaredType !== \"string\") return \"\";\n\tconst [base = \"\"] = declaredType.split(\";\");\n\treturn base.trim().toLowerCase();\n}\n\n/**\n * Require the declared type, the filename extension, and the actual bytes to agree on\n * one permitted file type.\n *\n * The bytes are authoritative — they are the only one of the three a client cannot\n * simply assert. The other two must be consistent with what the bytes actually are,\n * which is what refuses `shell.php.jpg` (bytes are PHP source, extension claims JPEG)\n * and an `avatar.jpg` declared as `application/x-httpd-php`.\n *\n * @param candidate - See {@link UploadCandidate}.\n * @returns `{ ok: true, type }`, or `{ ok: false, reason, detail }`. Never throws.\n *\n * @example\n * ```ts\n * const verdict = assertUploadType({\n *   declaredType: file.type,\n *   filename: file.name,\n *   headBytes: new Uint8Array(await file.slice(0, 256).arrayBuffer()),\n *   allow: [\"png\", \"jpeg\", \"webp\"],\n * });\n *\n * if (!verdict.ok) return new Response(`Rejected: ${verdict.reason}`, { status: 400 });\n *\n * // Generate the stored name yourself — never reuse the client's.\n * const stored = `${crypto.randomUUID()}.${verdict.type}`;\n * ```\n */\nexport function assertUploadType(candidate: UploadCandidate): UploadVerdict {\n\tconst { declaredType, filename, headBytes, allow } = candidate;\n\n\tif (!(headBytes instanceof Uint8Array) || headBytes.length === 0) {\n\t\treturn { ok: false, reason: \"no_bytes\", detail: \"headBytes was empty\" };\n\t}\n\n\tconst detected = detectFileSignature(headBytes);\n\tif (detected === null) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\treason: \"unrecognized_signature\",\n\t\t\tdetail: \"leading bytes match no known file type\",\n\t\t};\n\t}\n\n\tif (!Array.isArray(allow) || !allow.includes(detected)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\treason: \"type_not_allowed\",\n\t\t\tdetail: `detected ${detected}, which is not in the allowlist`,\n\t\t};\n\t}\n\n\tconst extension = extensionOf(typeof filename === \"string\" ? filename : \"\");\n\tif (extension === null) {\n\t\treturn { ok: false, reason: \"extension_missing\", detail: \"filename carries no extension\" };\n\t}\n\n\t// The *last* extension is what a webserver dispatches on, so `shell.php.jpg` is\n\t// judged here as `jpg` and caught by the byte comparison instead, while\n\t// `avatar.jpg.php` is judged as `php` and caught right here.\n\tif (!EXTENSIONS_BY_TYPE[detected].includes(extension)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\treason: \"extension_mismatch\",\n\t\t\tdetail: `bytes are ${detected} but the extension is .${extension}`,\n\t\t};\n\t}\n\n\tconst media = mediaTypeOf(declaredType);\n\tif (media.length > 0 && !MEDIA_TYPES_BY_TYPE[detected].includes(media)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\treason: \"declared_type_mismatch\",\n\t\t\tdetail: `bytes are ${detected} but Content-Type claimed ${media}`,\n\t\t};\n\t}\n\n\treturn { ok: true, type: detected };\n}\n\n//#endregion\n"],"mappings":"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"}

package/lib/crypto.d.mts

@@ -1,5 +1,4 @@
 import { Brand, PositiveInt } from "@resq-systems/types";
-
 //#region src/crypto.d.ts
 /**
  * Base64 AES-256-GCM payload produced by {@link encryptData} — the
@@ -55,7 +54,13 @@ declare const unsafeCiphertext: (value: string) => Brand<string, "Ciphertext">;
  *   the salt/IV are recovered on decryption.
  *
  * @throws From the underlying Node crypto primitives if `encryptionKey`
- *   is empty or scrypt fails.
+ *   is empty or scrypt fails. Failure surfaces as a rejected `Promise`,
+ *   never a resolved error value.
+ *
+ * Draws from the platform CSPRNG (`randomBytes`) each call, so it is not
+ * a pure function and its output is non-deterministic. There is no
+ * `AbortSignal` hook — once awaited the scrypt work runs to completion.
+ * Independent calls share no state and are safe to run concurrently.
  *
  * @compliance NIST 800-53 SC-28 (Protection of Information at Rest),
  *   SC-13 (Cryptographic Protection).
@@ -81,7 +86,9 @@ declare function encryptData(plaintext: string, encryptionKey: EncryptionKey): P
  *
  * @throws Error if the tag does not verify (wrong key, modified
  *   ciphertext, truncated payload). Catch this and treat it as a
- *   security event, not a recoverable error.
+ *   security event, not a recoverable error. The rejection comes back
+ *   as a rejected `Promise`. No `AbortSignal` is honoured; concurrent
+ *   calls are independent and share no state.
  *
  * @example
  * ```ts
@@ -175,8 +182,14 @@ declare function maskEmail(email: string): Masked;
  *   key, e.g. `"token"` matches `"refreshToken"` and `"id_token"`.
  *
  * @returns A new object with sensitive fields redacted and emails
- *   masked. Nested objects are recursed; arrays and primitives pass
- *   through unchanged.
+ *   masked. Any non-null object value is recursed and comes back as a
+ *   plain object keyed by its enumerable own properties — so arrays
+ *   return as index-keyed objects (`["a"]` → `{ "0": "a" }`) and class
+ *   instances / `Date`s lose their prototype. Only primitives, `null`,
+ *   and `undefined` pass through unchanged.
+ *
+ * @throws {RangeError} On a circular reference — recursion has no cycle
+ *   guard, so a self-referential object overflows the call stack.
  *
  * @example
  * ```ts

package/lib/crypto.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.mts","names":[],"sources":["../src/crypto.ts"],"mappings":";;;;AA8FA;;;;;KAjCY,UAAA,GAAa,KAAA;;;;AAmCzB;;KA5BY,aAAA,GAAgB,KAAA;;KAGhB,WAAA,GAAc,KAAA;AA2B1B;AAAA,KAxBY,SAAA,GAAY,KAAA;;KAGZ,MAAA,GAAS,KAAA;;cAiBR,eAAA,GAAe,KAAA,aAAA,KAAA,IAAA,KAAA;;cAEf,eAAA,GAAe,KAAA,aAAA,KAAA;;cAEf,mBAAA,GAAmB,KAAA,aAAA,KAAA;AAgBhC;AAAA,cAda,mBAAA,GAAmB,KAAA,aAAA,KAAA;;cAcnB,YAAA,GAAY,KAAA,aAAA,KAAA,IAAA,KAAA;;cAEZ,YAAA,GAAY,KAAA,aAAA,KAAA;;cAEZ,gBAAA,GAAgB,KAAA,aAAA,KAAA;;cAEhB,gBAAA,GAAgB,KAAA,aAAA,KAAA;;;;;AAF7B;;;;;AAEA;;;;;AA8CA;;;;;;;;;;;;;;;AAqCA;iBArCsB,WAAA,CACrB,SAAA,UACA,aAAA,EAAe,aAAA,GACb,OAAA,CAAQ,UAAA;;;;;;;;;;;;;;AA0EX;;;;;AAsBA;;;iBA9DsB,WAAA,CACrB,aAAA,EAAe,UAAA,EACf,aAAA,EAAe,aAAA,GACb,OAAA;;;;;;AA6EH;;;;;AAyBA;;;;;AA2CA;;iBA5GgB,QAAA,CAAS,IAAA,WAAe,SAAA;;;;;;;;;;;;;;;;;;;iBAsBxB,mBAAA,CAAoB,MAAA,GAAQ,WAAA,GAAkC,WAAA;;;;;;;;;;;;;;;iBAkB9D,OAAA,CAAQ,IAAA,WAAe,MAAA;;;;;;;;;;;;;;;;;iBAyBvB,SAAA,CAAU,KAAA,WAAgB,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2C1B,kBAAA,CACf,GAAA,EAAK,MAAA,mBACL,eAAA,cAQE,MAAA"}
+{"version":3,"file":"crypto.d.mts","names":[],"sources":["../src/crypto.ts"],"mappings":";;;;;;;;KA2DY,aAAa;;;;;;KAOb,gBAAgB;;KAGhB,cAAc;;KAGd,YAAY;;KAGZ,SAAS;;cAiBR,kBAAe,kBAAA,SAAA;;cAEf,kBAAe,kBAAA;;cAEf,sBAAmB,kBAAA;;cAEnB,sBAAmB,kBAAA;;cAcnB,eAAY,kBAAA,SAAA;;cAEZ,eAAY,kBAAA;;cAEZ,mBAAgB,kBAAA;;cAEhB,mBAAgB,kBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0DP,YACrB,mBACA,eAAe,gBACb,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;iBAoCW,YACrB,eAAe,YACf,eAAe,gBACb;;;;;;;;;;;;;;;;;;iBAqCa,SAAS,eAAe;;;;;;;;;;;;;;;;;;;iBAsBxB,oBAAoB,SAAQ,cAAkC;;;;;;;;;;;;;;;iBAkB9D,QAAQ,eAAe;;;;;;;;;;;;;;;;;iBAyBvB,UAAU,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiD1B,mBACf,KAAK,yBACL,6BAQE"}