@streamscloud/kit 0.83.1 → 0.84.0

package/dist/core/files/file-helper.d.ts

@@ -1,6 +1,38 @@
+/**
+ * Outcome of `FileHelper.checkType`. The declared type is the name's extension, or `type` when the name has no known
+ * extension. `file` carries the right name and `type` (the original file when nothing changes).
+ * - `match` — the bytes identify the declared type.
+ * - `mismatch` — the bytes identify another type, or nothing is declared (`declaredExtension: ''`).
+ * - `unverifiable` — a format bytes cannot identify (CSV, Markdown, legacy DOC / XLS), typed as declared.
+ * - `contradicted` — the declared type is byte-identifiable and the bytes are not it.
+ * - `unknown` — nothing is declared and the bytes identify no known type.
+ */
+export type FileTypeCheck = {
+    status: 'match' | 'unverifiable';
+    file: File;
+} | {
+    status: 'mismatch';
+    file: File;
+    declaredExtension: string;
+} | {
+    status: 'contradicted';
+    declaredExtension: string;
+} | {
+    status: 'unknown';
+};
 export declare class FileHelper {
     static blobToFile(blob: Blob, fileName: string): File;
     static getFileExtension(fileName: string): string;
     static omitFileExtension(fileName: string): string;
+    /**
+     * Checks a file's real type against its declared one. The bytes identify images (PNG, JPEG, WebP, GIF, AVIF, HEIC, SVG),
+     * MP4, audio (WAV, MP3, M4A, AAC, FLAC), PDF, DOCX, XLSX, ZIP and fonts (WOFF2, WOFF, TTF, OTF); other formats are typed
+     * as declared. An equivalent extension (`.jpeg` for `jpg`) and any member of the declared ISO media container family
+     * (`.m4a` holding an `isom` MP4, `.heif` for HEIC) is a match, as is any ZIP archive named `.zip`. When the name lacks
+     * the right extension, it is appended and the original name stays intact: `photo.jpg` holding a PNG → `photo.jpg.png`.
+     * Binary formats read only the head; SVG is looked for only when something is declared, and a markup-looking file is
+     * then read whole to confirm an SVG root.
+     */
+    static checkType(file: File): Promise<FileTypeCheck>;
     static truncateFileName(fileName: string, maxNameLength: number | null | undefined): string;
 }

package/dist/core/files/file-helper.js

@@ -1,4 +1,68 @@
-import { StringHelper } from '../utils';
+import { HtmlHelper, StringHelper } from '../utils';
+import { default as mime } from 'mime';
+const CONTENT_DETECTABLE_EXTENSIONS = new Set([
+    'png',
+    'jpg',
+    'webp',
+    'gif',
+    'avif',
+    'heic',
+    'mp4',
+    'wav',
+    'mp3',
+    'm4a',
+    'aac',
+    'flac',
+    'pdf',
+    'docx',
+    'xlsx',
+    'zip',
+    'woff2',
+    'woff',
+    'ttf',
+    'otf'
+]);
+const PREFERRED_EXTENSIONS = { 'video/quicktime': 'mov', 'audio/mpeg': 'mp3', 'audio/aac': 'aac', 'audio/flac': 'flac' };
+const SVG_TYPE = { mime: 'image/svg+xml', extension: 'svg' };
+const ISO_MEDIA_CONTAINERS = [new Set(['mp4', 'm4v', 'm4a', 'm4b', 'mov', '3gp', '3g2', 'f4v']), new Set(['heic', 'heif'])];
+const CONTENT_DETECTABLE_MIMES = new Set([...CONTENT_DETECTABLE_EXTENSIONS, 'svg', ...ISO_MEDIA_CONTAINERS.flatMap((family) => [...family])].map((extension) => mime.getType(extension)));
+const sameFormat = (extensionA, extensionB) => {
+    const type = mime.getType(extensionA);
+    return type !== null && type === mime.getType(extensionB);
+};
+const sameContainer = (extensionA, extensionB) => ISO_MEDIA_CONTAINERS.some((family) => family.has(extensionA) && family.has(extensionB));
+const declaredType = (file) => {
+    const extension = FileHelper.getFileExtension(file.name).toLowerCase();
+    const fromName = extension ? mime.getType(extension) : null;
+    if (fromName) {
+        return { mime: fromName, extension, fromName: true };
+    }
+    const fromType = file.type ? (PREFERRED_EXTENSIONS[file.type] ?? mime.getExtension(file.type)) : null;
+    return fromType ? { mime: file.type, extension: fromType, fromName: false } : null;
+};
+const retyped = (file, name, type) => name === file.name && type === file.type ? file : new File([file], name, { type, lastModified: file.lastModified });
+const MARKUP_PROBE_BYTES = 1024;
+const startsWithMarkup = async (blob) => {
+    const head = await blob.slice(0, MARKUP_PROBE_BYTES).text();
+    return head.trimStart().startsWith('<');
+};
+const isSvgDocument = async (blob) => (await startsWithMarkup(blob)) && HtmlHelper.sanitizeSvg(await blob.text()) !== null;
+const isZipArchive = async (blob) => (await blob.slice(0, 4).text()) === 'PK\u0003\u0004';
+const contentType = async (blob, declared) => {
+    if (declared?.extension === 'zip' && (await isZipArchive(blob))) {
+        return declared;
+    }
+    const { fileTypeFromBlob } = await import('file-type');
+    const detected = await fileTypeFromBlob(blob);
+    if (detected && declared && sameContainer(detected.ext, declared.extension)) {
+        return declared;
+    }
+    const detectedMime = detected && CONTENT_DETECTABLE_EXTENSIONS.has(detected.ext) ? mime.getType(detected.ext) : null;
+    if (detected && detectedMime) {
+        return { mime: detectedMime, extension: detected.ext };
+    }
+    return declared && (!detected || detected.ext === 'xml') && (await isSvgDocument(blob)) ? SVG_TYPE : null;
+};
 export class FileHelper {
     static blobToFile(blob, fileName) {
         return new File([blob], fileName, { type: blob.type });
@@ -15,6 +79,33 @@ export class FileHelper {
         const dotIndex = fileName.lastIndexOf('.');
         return dotIndex > 0 && dotIndex < fileName.length - 1 ? fileName.slice(0, dotIndex) : fileName;
     }
+    /**
+     * Checks a file's real type against its declared one. The bytes identify images (PNG, JPEG, WebP, GIF, AVIF, HEIC, SVG),
+     * MP4, audio (WAV, MP3, M4A, AAC, FLAC), PDF, DOCX, XLSX, ZIP and fonts (WOFF2, WOFF, TTF, OTF); other formats are typed
+     * as declared. An equivalent extension (`.jpeg` for `jpg`) and any member of the declared ISO media container family
+     * (`.m4a` holding an `isom` MP4, `.heif` for HEIC) is a match, as is any ZIP archive named `.zip`. When the name lacks
+     * the right extension, it is appended and the original name stays intact: `photo.jpg` holding a PNG → `photo.jpg.png`.
+     * Binary formats read only the head; SVG is looked for only when something is declared, and a markup-looking file is
+     * then read whole to confirm an SVG root.
+     */
+    static async checkType(file) {
+        const declared = declaredType(file);
+        const content = await contentType(file, declared);
+        const appended = (extension) => `${file.name}.${extension}`;
+        if (content) {
+            if (declared && sameFormat(declared.extension, content.extension)) {
+                return { status: 'match', file: retyped(file, declared.fromName ? file.name : appended(content.extension), content.mime) };
+            }
+            return { status: 'mismatch', file: retyped(file, appended(content.extension), content.mime), declaredExtension: declared?.extension ?? '' };
+        }
+        if (!declared) {
+            return { status: 'unknown' };
+        }
+        if (CONTENT_DETECTABLE_MIMES.has(mime.getType(declared.extension))) {
+            return { status: 'contradicted', declaredExtension: declared.extension };
+        }
+        return { status: 'unverifiable', file: retyped(file, declared.fromName ? file.name : appended(declared.extension), declared.mime) };
+    }
     static truncateFileName(fileName, maxNameLength) {
         if (!maxNameLength) {
             return fileName;

package/dist/core/files/file-validation-rules.d.ts

@@ -30,8 +30,16 @@ export declare const FileRules: {
         min2: number;
     }, message?: string) => FileValidationRule;
     MaxSize: (bytes: number, message?: string) => FileValidationRule;
-    Mime: (accept: string, message?: string) => FileValidationRule;
-    VideoAspectRatio: (ratios: string[], message?: string, tolerancePercent?: number) => FileValidationRule;
+    /**
+     * `verifyContent` also reads the file through `FileHelper.checkType` and rejects it when the bytes contradict the name
+     * (`mismatch`, `contradicted`); a file the bytes cannot judge passes on its name.
+     */
+    Mime: (accept: string, message?: string, options?: {
+        verifyContent?: boolean;
+    }) => FileValidationRule;
+    VideoAspectRatio: (ratios: string[], message?: string, options?: {
+        tolerancePercent?: number;
+    }) => FileValidationRule;
     /**
      * Validates a video's width / height ratio against an inclusive `[min, max]` interval. Each
      * bound is a `'w:h'` string or a decimal; both are optional, so the interval can be open-ended
@@ -41,8 +49,12 @@ export declare const FileRules: {
     VideoAspectRatioRange: (range: {
         min?: AspectRatioBound;
         max?: AspectRatioBound;
-    }, message?: string, tolerancePercent?: number) => FileValidationRule;
-    VideoOrientation: (orientation: VideoOrientationValue, message?: string, tolerancePercent?: number) => FileValidationRule;
+    }, message?: string, options?: {
+        tolerancePercent?: number;
+    }) => FileValidationRule;
+    VideoOrientation: (orientation: VideoOrientationValue, message?: string, options?: {
+        tolerancePercent?: number;
+    }) => FileValidationRule;
     VideoDimensions: (limits: {
         max1: number;
         max2: number;

package/dist/core/files/file-validation-rules.js

@@ -65,8 +65,13 @@ const maxDimensionsMessage = (limits) => {
     const limit = toSides(limits.max1, limits.max2);
     return messages.maxDimensions(limit.long, limit.short);
 };
+const DEFAULT_TOLERANCE_PERCENT = 1;
 const formatExtensions = (extensions) => extensions.map((ext) => '.' + ext.replace(/^\./, '')).join(', ');
 const messages = new FileValidationLocalization();
+const rejectContradictedContent = async (file, message) => {
+    const { status } = await FileHelper.checkType(file);
+    return status === 'mismatch' || status === 'contradicted' ? (message ?? messages.unsupportedType) : null;
+};
 /**
  * Built-in rule factories. Each takes a constraint and an optional `message`; when omitted, the
  * rule falls back to a localized default from `FileValidationLocalization` (kit ships no English
@@ -117,20 +122,30 @@ export const FileRules = {
         return actual.long < limit.long || actual.short < limit.short ? (message ?? messages.minDimensions(limit.long, limit.short)) : null;
     },
     MaxSize: (bytes, message) => (file) => file.size > bytes ? (message ?? messages.maxSize(StringHelper.toFileSizeString(bytes))) : null,
-    Mime: (accept, message) => {
-        const rule = (file) => (matchesAcceptedFileTypes(file, accept) ? null : (message ?? messages.unsupportedType));
+    /**
+     * `verifyContent` also reads the file through `FileHelper.checkType` and rejects it when the bytes contradict the name
+     * (`mismatch`, `contradicted`); a file the bytes cannot judge passes on its name.
+     */
+    Mime: (accept, message, options) => {
+        const rule = (file) => {
+            if (!matchesAcceptedFileTypes(file, accept)) {
+                return message ?? messages.unsupportedType;
+            }
+            return options?.verifyContent ? rejectContradictedContent(file, message) : null;
+        };
         rule.accept = accept;
         return rule;
     },
-    VideoAspectRatio: (ratios, message, tolerancePercent = 1) => async (file) => {
+    VideoAspectRatio: (ratios, message, options) => async (file) => {
         const { width, height } = await readMedia(file);
         if (!width || !height) {
             return message ?? messages.aspectRatio(ratios.join(', '));
         }
         const actual = width / height;
+        const tolerance = options?.tolerancePercent ?? DEFAULT_TOLERANCE_PERCENT;
         const matches = ratios.some((ratio) => {
             const target = parseRatio(ratio);
-            return Number.isFinite(target) && Math.abs((actual / target) * 100 - 100) <= tolerancePercent;
+            return Number.isFinite(target) && Math.abs((actual / target) * 100 - 100) <= tolerance;
         });
         return matches ? null : (message ?? messages.aspectRatio(ratios.join(', ')));
     },
@@ -140,7 +155,7 @@ export const FileRules = {
      * (`{ min }` = "this wide or wider", `{ max }` = "up to this"). `tolerancePercent` widens the
      * interval outward on both edges. An empty `{}` specifies no constraint and accepts everything.
      */
-    VideoAspectRatioRange: (range, message, tolerancePercent = 1) => async (file) => {
+    VideoAspectRatioRange: (range, message, options) => async (file) => {
         const { width, height } = await readMedia(file);
         if (!width || !height) {
             return message ?? messages.aspectRatioRange(formatBound(range.min), formatBound(range.max));
@@ -148,18 +163,20 @@ export const FileRules = {
         const actual = width / height;
         const lo = resolveBound(range.min);
         const hi = resolveBound(range.max);
-        const factor = 1 + tolerancePercent / 100;
+        const tolerance = options?.tolerancePercent ?? DEFAULT_TOLERANCE_PERCENT;
+        const factor = 1 + tolerance / 100;
         const okLo = lo === null || actual >= lo / factor;
         const okHi = hi === null || actual <= hi * factor;
         return okLo && okHi ? null : (message ?? messages.aspectRatioRange(formatBound(range.min), formatBound(range.max)));
     },
-    VideoOrientation: (orientation, message, tolerancePercent = 1) => async (file) => {
+    VideoOrientation: (orientation, message, options) => async (file) => {
         const { width, height } = await readMedia(file);
         if (!width || !height) {
             return message ?? messages.orientation(orientation);
         }
         const actual = width / height;
-        const margin = tolerancePercent / 100;
+        const tolerance = options?.tolerancePercent ?? DEFAULT_TOLERANCE_PERCENT;
+        const margin = tolerance / 100;
         const ok = orientation === 'landscape' ? actual > 1 + margin : orientation === 'portrait' ? actual < 1 - margin : Math.abs(actual - 1) <= margin;
         return ok ? null : (message ?? messages.orientation(orientation));
     },

package/dist/core/files/index.d.ts

@@ -2,6 +2,7 @@ export type { BlobWithName, FileWithBlobUrl, FileWithUploadUrl } from './types';
 export type { AspectRatioBound, FileValidationResult, FileValidationRule, FileValidationRuleSets, VideoOrientationValue } from './file-validation-types';
 export type { BlobUpload, BlobUploadStrategy, PreviewableUploadingFile, UploadPreviewMode, UploadingFile, UploadingFileStatus } from './upload-types';
 export type { AddOptions, UploadMediaStoreOptions } from './upload-media-store.svelte';
+export type { FileTypeCheck } from './file-helper';
 export { toBlobWithName, toFileWithUploadUrl } from './types';
 export { uploadBlob } from './blob-storage';
 export { openFile } from './open-file';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamscloud/kit",
-  "version": "0.83.1",
+  "version": "0.84.0",
   "author": "StreamsCloud",
   "repository": {
     "type": "git",
@@ -496,6 +496,7 @@
     "dequal": "^2.0.3",
     "dompurify": "^3.4.5",
     "esm-env": "^1.2.2",
+    "file-type": "^22.1.1",
     "fuse.js": "^7.3.0",
     "hugerte": "^1.0.10",
     "mime": "^4.1.0",
@@ -536,6 +537,7 @@
     "eslint-plugin-svelte": "^3.23.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "esm-env": "^1.2.2",
+    "file-type": "^22.1.1",
     "fuse.js": "^7.3.0",
     "globals": "^17.12.0",
     "hugerte": "^1.0.10",