132 lines
5.1 KiB
TypeScript
132 lines
5.1 KiB
TypeScript
import { fileTypeFromBuffer } from "file-type";
|
|
import { DEFAULT_ALLOW_LIST } from "./allow-list.js";
|
|
import type { PreUploadAllowList, PreUploadScanAdapter, PreUploadScanInput, PreUploadScanResult } from "./pre-upload-types.js";
|
|
|
|
// Reject control characters (\x00 null, \x01-\x1f, \x7f DEL) and path-traversal
|
|
// sequences (../ or ..\\) which would let an attacker escape the bucket prefix.
|
|
// eslint-disable-next-line no-control-regex
|
|
const FILENAME_BAD_PATTERN = /[\x00-\x1f\x7f]|\.\.[\\/]/;
|
|
const FILENAME_MAX_LENGTH = 255;
|
|
|
|
const SVG_SIGNATURE = /^<\?xml[\s\S]*?<svg\b|^<svg\b/i;
|
|
const TEXT_PLAIN_FALLBACK_MIMES = new Set(["text/plain", "text/csv"]);
|
|
|
|
export interface MagicBytesScanAdapterOptions {
|
|
/**
|
|
* Per-context MIME allow-list. Defaults to DEFAULT_ALLOW_LIST.
|
|
*/
|
|
allowList?: PreUploadAllowList;
|
|
/**
|
|
* Env-style toggle. When false, scan() returns `{ status: "skipped",
|
|
* reason: "scanner_disabled" }`. Intended as a Notfall-Bypass — never
|
|
* default to false.
|
|
*/
|
|
enabled?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Synchronous pre-upload scanner. Uses file-type's magic-bytes signature
|
|
* database to derive the actual MIME type from the leading bytes of the buffer
|
|
* and validates it against (a) the client-declared MIME type and (b) the
|
|
* per-context allow-list.
|
|
*
|
|
* Defense-in-depth: the adapter does NOT log the buffer contents. Only the
|
|
* filename, sizes, and detected/declared MIME types are surfaced via the
|
|
* `detail` field so the caller can decide what to write to the audit log.
|
|
*/
|
|
export function createMagicBytesScanAdapter(options: MagicBytesScanAdapterOptions = {}): PreUploadScanAdapter {
|
|
const allowList = options.allowList ?? DEFAULT_ALLOW_LIST;
|
|
const enabled = options.enabled !== false;
|
|
|
|
return {
|
|
async scan(input: PreUploadScanInput): Promise<PreUploadScanResult> {
|
|
if (!enabled) {
|
|
return { status: "skipped", reason: "scanner_disabled" };
|
|
}
|
|
|
|
const filenameVerdict = validateFilename(input.filename);
|
|
if (filenameVerdict) return filenameVerdict;
|
|
|
|
if (!input.buffer || input.buffer.byteLength === 0) {
|
|
return { status: "rejected", reason: "empty", detail: "buffer was empty" };
|
|
}
|
|
|
|
const declared = input.declaredMimeType.trim().toLowerCase();
|
|
const contextAllowList = allowList[input.context] ?? [];
|
|
|
|
const detected = await detectMimeType(input.buffer);
|
|
|
|
// SVG-special-case: file-type reports SVG (which is just XML) as
|
|
// application/xml. Promote it to image/svg+xml only when the declared
|
|
// type asks for SVG, the content looks like SVG, and the context
|
|
// allow-list permits it. Otherwise XML stays XML and falls through
|
|
// to the normal mismatch path below.
|
|
if (detected === "application/xml" && declared === "image/svg+xml" && contextAllowList.includes("image/svg+xml") && looksLikeSvg(input.buffer)) {
|
|
return { status: "clean", detectedMimeType: "image/svg+xml" };
|
|
}
|
|
|
|
if (!detected) {
|
|
// file-type returns undefined for plain text / csv and a handful of
|
|
// long-tail formats. Allow it through only when the declared MIME is
|
|
// in our text fallback set AND the allow-list permits it.
|
|
if (TEXT_PLAIN_FALLBACK_MIMES.has(declared) && contextAllowList.includes(declared)) {
|
|
return { status: "clean" };
|
|
}
|
|
return {
|
|
status: "rejected",
|
|
reason: "mime_undetectable",
|
|
detail: `unable to detect MIME for declared="${declared}"`,
|
|
};
|
|
}
|
|
|
|
if (detected !== declared) {
|
|
return {
|
|
status: "rejected",
|
|
reason: "mime_mismatch",
|
|
detectedMimeType: detected,
|
|
detail: `declared="${declared}", detected="${detected}"`,
|
|
};
|
|
}
|
|
|
|
if (!contextAllowList.includes(detected)) {
|
|
return {
|
|
status: "rejected",
|
|
reason: "mime_not_allowed",
|
|
detectedMimeType: detected,
|
|
detail: `context="${input.context}" does not permit "${detected}"`,
|
|
};
|
|
}
|
|
|
|
return { status: "clean", detectedMimeType: detected };
|
|
},
|
|
};
|
|
}
|
|
|
|
async function detectMimeType(buffer: Uint8Array): Promise<string | undefined> {
|
|
const head = buffer.byteLength > 4100 ? buffer.subarray(0, 4100) : buffer;
|
|
try {
|
|
const result = await fileTypeFromBuffer(head);
|
|
return result?.mime;
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|
|
|
|
function validateFilename(filename: string): PreUploadScanResult | undefined {
|
|
if (typeof filename !== "string" || filename.length === 0) {
|
|
return { status: "rejected", reason: "filename_invalid", detail: "filename was empty" };
|
|
}
|
|
if (filename.length > FILENAME_MAX_LENGTH) {
|
|
return { status: "rejected", reason: "filename_invalid", detail: `filename exceeded ${FILENAME_MAX_LENGTH} chars` };
|
|
}
|
|
if (FILENAME_BAD_PATTERN.test(filename)) {
|
|
return { status: "rejected", reason: "filename_invalid", detail: "filename contained control chars or path traversal" };
|
|
}
|
|
return undefined;
|
|
}
|
|
|
|
function looksLikeSvg(buffer: Uint8Array): boolean {
|
|
const head = new TextDecoder("utf-8", { fatal: false }).decode(buffer.subarray(0, 512)).trimStart();
|
|
return SVG_SIGNATURE.test(head);
|
|
}
|