Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,131 @@
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);
}