@shipstatic/types 0.4.18 → 0.4.20

package/dist/index.d.ts

@@ -339,6 +339,9 @@ export declare class ShipError extends Error {
 export declare function isShipError(error: unknown): error is ShipError;
 /**
  * Platform configuration response from API
+ *
+ * Contains ONLY dynamic, runtime-specific values (plan-based limits).
+ * Static constants (MIME types, validation rules) live as exported constants.
  */
 export interface ConfigResponse {
     /** Maximum individual file size in bytes */
@@ -347,9 +350,87 @@ export interface ConfigResponse {
     maxFilesCount: number;
     /** Maximum total deployment size in bytes */
     maxTotalSize: number;
-    /** Allowed MIME type categories for file validation */
-    allowedMimeTypes: string[];
 }
+/**
+ * Allowed MIME types for static web hosting.
+ *
+ * This is a static platform constant, not per-user configuration.
+ * Safe to share across frontend/backend due to atomic deploys.
+ *
+ * Validation rules:
+ * - Exact match: 'application/json' allows only 'application/json'
+ * - Prefix match: 'image/' allows all image types (png, jpeg, webp, etc.)
+ *
+ * Coverage: 100% of browser-renderable web content
+ * - Core web (HTML, CSS, JS, WASM)
+ * - Media (images, audio, video, fonts)
+ * - Documents (PDF, Markdown, data formats)
+ * - Modern web (PWA, 3D, structured data)
+ *
+ * ============================================================================
+ * INTENTIONALLY EXCLUDED (Security & Platform Integrity)
+ * ============================================================================
+ *
+ * We are a WEB HOSTING platform, not a file distribution service.
+ * GitHub Pages-style parity for renderable content, more restrictive for downloads.
+ *
+ * 1. EXECUTABLES (Malware Distribution)
+ *    → .exe, .msi, .dmg, .deb, .rpm, .app, .apk, .jar
+ *    → Reason: Direct malware delivery vector
+ *    → Alternative: Use GitHub Releases or dedicated software distribution CDN
+ *
+ * 2. ARCHIVES (Piracy & Abuse)
+ *    → .zip, .rar, .tar, .gz, .7z, .bz2
+ *    → Reason: File sharing abuse, can contain executables, no web rendering
+ *    → Alternative: Use file hosting service (Dropbox, Google Drive) or GitHub Releases
+ *
+ * 3. SERVER-SIDE SCRIPTS (Credential Leakage)
+ *    → .php, .asp, .jsp, .cgi
+ *    → Reason: Source code exposure (database passwords, API keys, secrets)
+ *    → Alternative: Static hosting only - use serverless functions for backends
+ *
+ * 4. SHELL SCRIPTS (OS Execution)
+ *    → .sh, .bash, .bat, .cmd, .ps1, .vbs
+ *    → Reason: Execute on user's OS outside browser sandbox, social engineering risk
+ *    → Alternative: Embed code examples in HTML <pre><code> or link to GitHub repo
+ *
+ * 5. PROGRAMMING LANGUAGE SOURCE (Platform Scope)
+ *    → .py, .rb, .pl, .java, .c, .cpp, .cs, .go, .rs
+ *    → Reason: Not web-renderable, better served by GitHub/GitLab/Bitbucket
+ *    → Alternative: Use GitHub for code hosting, link to repository
+ *
+ * 6. OFFICE DOCUMENTS (Macro Malware)
+ *    → .doc, .docx, .xls, .xlsx, .ppt, .pptx
+ *    → Reason: Can contain VBA macros, active exploits in the wild
+ *    → Alternative: Use PDF for documents (fully supported)
+ *
+ * 7. GENERIC BINARIES (Unvalidatable)
+ *    → application/octet-stream
+ *    → Reason: Too broad - allows any binary format, cannot moderate effectively
+ *    → Alternative: Use specific MIME types for known formats
+ *
+ * ============================================================================
+ * Security Model:
+ * - Browser sandbox (JS/WASM execute safely in controlled environment)
+ * - AI content moderation (scans text/image content for abuse)
+ * - No server-side execution (static files only)
+ * - Explicit allowlist (only approved formats, reject unknown)
+ * ============================================================================
+ */
+export declare const ALLOWED_MIME_TYPES: readonly ["text/html", "text/css", "text/plain", "text/markdown", "text/xml", "text/csv", "text/yaml", "text/vtt", "text/calendar", "text/javascript", "image/", "audio/", "video/", "font/", "application/javascript", "application/ecmascript", "application/x-javascript", "application/wasm", "application/json", "application/ld+json", "application/manifest+json", "application/xml", "application/xhtml+xml", "application/rss+xml", "application/atom+xml", "application/yaml", "application/pdf", "model/gltf+json", "model/gltf-binary", "application/mp4", "application/font-woff", "application/font-woff2", "application/x-font-woff", "application/x-woff", "application/vnd.ms-fontobject", "application/x-font-ttf", "application/x-font-truetype", "application/x-font-otf", "application/x-font-opentype"];
+/**
+ * Check if a MIME type is allowed for upload.
+ *
+ * Supports both exact matches and prefix matches:
+ * - 'application/json' matches 'application/json' exactly
+ * - 'text/' matches 'text/plain', 'text/html', etc.
+ *
+ * @example
+ * isAllowedMimeType('text/plain')     // true (prefix match)
+ * isAllowedMimeType('application/json') // true (exact match)
+ * isAllowedMimeType('application/wasm') // false (not allowed)
+ */
+export declare function isAllowedMimeType(mimeType: string): boolean;
 /**
  * Generic success response wrapper
  */

package/dist/index.js

@@ -199,6 +199,160 @@ export function isShipError(error) {
         error.name === 'ShipError' &&
         'status' in error);
 }
+/**
+ * Allowed MIME types for static web hosting.
+ *
+ * This is a static platform constant, not per-user configuration.
+ * Safe to share across frontend/backend due to atomic deploys.
+ *
+ * Validation rules:
+ * - Exact match: 'application/json' allows only 'application/json'
+ * - Prefix match: 'image/' allows all image types (png, jpeg, webp, etc.)
+ *
+ * Coverage: 100% of browser-renderable web content
+ * - Core web (HTML, CSS, JS, WASM)
+ * - Media (images, audio, video, fonts)
+ * - Documents (PDF, Markdown, data formats)
+ * - Modern web (PWA, 3D, structured data)
+ *
+ * ============================================================================
+ * INTENTIONALLY EXCLUDED (Security & Platform Integrity)
+ * ============================================================================
+ *
+ * We are a WEB HOSTING platform, not a file distribution service.
+ * GitHub Pages-style parity for renderable content, more restrictive for downloads.
+ *
+ * 1. EXECUTABLES (Malware Distribution)
+ *    → .exe, .msi, .dmg, .deb, .rpm, .app, .apk, .jar
+ *    → Reason: Direct malware delivery vector
+ *    → Alternative: Use GitHub Releases or dedicated software distribution CDN
+ *
+ * 2. ARCHIVES (Piracy & Abuse)
+ *    → .zip, .rar, .tar, .gz, .7z, .bz2
+ *    → Reason: File sharing abuse, can contain executables, no web rendering
+ *    → Alternative: Use file hosting service (Dropbox, Google Drive) or GitHub Releases
+ *
+ * 3. SERVER-SIDE SCRIPTS (Credential Leakage)
+ *    → .php, .asp, .jsp, .cgi
+ *    → Reason: Source code exposure (database passwords, API keys, secrets)
+ *    → Alternative: Static hosting only - use serverless functions for backends
+ *
+ * 4. SHELL SCRIPTS (OS Execution)
+ *    → .sh, .bash, .bat, .cmd, .ps1, .vbs
+ *    → Reason: Execute on user's OS outside browser sandbox, social engineering risk
+ *    → Alternative: Embed code examples in HTML <pre><code> or link to GitHub repo
+ *
+ * 5. PROGRAMMING LANGUAGE SOURCE (Platform Scope)
+ *    → .py, .rb, .pl, .java, .c, .cpp, .cs, .go, .rs
+ *    → Reason: Not web-renderable, better served by GitHub/GitLab/Bitbucket
+ *    → Alternative: Use GitHub for code hosting, link to repository
+ *
+ * 6. OFFICE DOCUMENTS (Macro Malware)
+ *    → .doc, .docx, .xls, .xlsx, .ppt, .pptx
+ *    → Reason: Can contain VBA macros, active exploits in the wild
+ *    → Alternative: Use PDF for documents (fully supported)
+ *
+ * 7. GENERIC BINARIES (Unvalidatable)
+ *    → application/octet-stream
+ *    → Reason: Too broad - allows any binary format, cannot moderate effectively
+ *    → Alternative: Use specific MIME types for known formats
+ *
+ * ============================================================================
+ * Security Model:
+ * - Browser sandbox (JS/WASM execute safely in controlled environment)
+ * - AI content moderation (scans text/image content for abuse)
+ * - No server-side execution (static files only)
+ * - Explicit allowlist (only approved formats, reject unknown)
+ * ============================================================================
+ */
+export const ALLOWED_MIME_TYPES = [
+    // =========================================================================
+    // TEXT CONTENT (explicit list - no prefix matching for security)
+    // =========================================================================
+    // Core web documents
+    'text/html', // HTML pages
+    'text/css', // Stylesheets
+    'text/plain', // Plain text (robots.txt, .well-known/*, LICENSE, README.txt)
+    'text/markdown', // Markdown files (.md)
+    'text/xml', // XML files
+    // Data formats
+    'text/csv', // CSV data files
+    'text/yaml', // YAML config files
+    // Web-specific formats
+    'text/vtt', // WebVTT video subtitles/captions (accessibility)
+    'text/calendar', // iCalendar (.ics) event files
+    // JavaScript (legacy MIME type, still widely used by ~50% of servers)
+    'text/javascript',
+    // =========================================================================
+    // MEDIA (prefix matching - covers all common subtypes)
+    // =========================================================================
+    // Images: PNG, JPEG, GIF, SVG, WebP, AVIF, HEIC, BMP, TIFF, ICO, etc.
+    'image/',
+    // Audio: MP3, OGG, WAV, WebM, AAC, FLAC, Opus, etc.
+    'audio/',
+    // Video: MP4, WebM, OGG, QuickTime, etc.
+    'video/',
+    // Modern fonts: WOFF2, WOFF, TTF, OTF
+    'font/',
+    // =========================================================================
+    // CORE WEB APPLICATION TYPES
+    // =========================================================================
+    // JavaScript (multiple MIME types for compatibility)
+    'application/javascript', // Modern standard (RFC 9239)
+    'application/ecmascript', // ECMAScript (legacy but still used)
+    'application/x-javascript', // Legacy variant (old CDNs, Apache configs)
+    // WebAssembly (modern web apps, games, compute-heavy workloads)
+    'application/wasm',
+    // JSON and structured data
+    'application/json',
+    'application/ld+json', // JSON-LD for structured data / SEO (Schema.org, Open Graph)
+    'application/manifest+json', // PWA web app manifests
+    // XML and feeds
+    'application/xml',
+    'application/xhtml+xml', // XHTML - XML-compliant HTML (legacy sites)
+    'application/rss+xml', // RSS feeds (blogs, podcasts)
+    'application/atom+xml', // Atom feeds
+    // Configuration formats
+    'application/yaml', // YAML configs (static site generators)
+    // Documents
+    'application/pdf', // PDF documents
+    // =========================================================================
+    // 3D FORMATS (industry standard only)
+    // =========================================================================
+    // glTF - Khronos standard for 3D web content
+    'model/gltf+json', // glTF JSON format
+    'model/gltf-binary', // GLB binary format
+    // =========================================================================
+    // LEGACY COMPATIBILITY
+    // =========================================================================
+    // Video (some tools detect MP4 as application/mp4)
+    'application/mp4',
+    // Legacy font MIME types (Bootstrap, Font Awesome, IE compatibility)
+    'application/font-woff',
+    'application/font-woff2',
+    'application/x-font-woff',
+    'application/x-woff',
+    'application/vnd.ms-fontobject', // EOT files (Internet Explorer)
+    'application/x-font-ttf',
+    'application/x-font-truetype',
+    'application/x-font-otf',
+    'application/x-font-opentype',
+];
+/**
+ * Check if a MIME type is allowed for upload.
+ *
+ * Supports both exact matches and prefix matches:
+ * - 'application/json' matches 'application/json' exactly
+ * - 'text/' matches 'text/plain', 'text/html', etc.
+ *
+ * @example
+ * isAllowedMimeType('text/plain')     // true (prefix match)
+ * isAllowedMimeType('application/json') // true (exact match)
+ * isAllowedMimeType('application/wasm') // false (not allowed)
+ */
+export function isAllowedMimeType(mimeType) {
+    return ALLOWED_MIME_TYPES.some(allowed => mimeType === allowed || mimeType.startsWith(allowed));
+}
 // API Key Configuration
 export const API_KEY_PREFIX = 'ship-';
 export const API_KEY_HEX_LENGTH = 64;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "Shared types for Shipstatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -492,6 +492,9 @@ export function isShipError(error: unknown): error is ShipError {
 
 /**
  * Platform configuration response from API
+ *
+ * Contains ONLY dynamic, runtime-specific values (plan-based limits).
+ * Static constants (MIME types, validation rules) live as exported constants.
  */
 export interface ConfigResponse {
   /** Maximum individual file size in bytes */
@@ -500,8 +503,185 @@ export interface ConfigResponse {
   maxFilesCount: number;
   /** Maximum total deployment size in bytes */
   maxTotalSize: number;
-  /** Allowed MIME type categories for file validation */
-  allowedMimeTypes: string[];
+}
+
+/**
+ * Allowed MIME types for static web hosting.
+ *
+ * This is a static platform constant, not per-user configuration.
+ * Safe to share across frontend/backend due to atomic deploys.
+ *
+ * Validation rules:
+ * - Exact match: 'application/json' allows only 'application/json'
+ * - Prefix match: 'image/' allows all image types (png, jpeg, webp, etc.)
+ *
+ * Coverage: 100% of browser-renderable web content
+ * - Core web (HTML, CSS, JS, WASM)
+ * - Media (images, audio, video, fonts)
+ * - Documents (PDF, Markdown, data formats)
+ * - Modern web (PWA, 3D, structured data)
+ *
+ * ============================================================================
+ * INTENTIONALLY EXCLUDED (Security & Platform Integrity)
+ * ============================================================================
+ *
+ * We are a WEB HOSTING platform, not a file distribution service.
+ * GitHub Pages-style parity for renderable content, more restrictive for downloads.
+ *
+ * 1. EXECUTABLES (Malware Distribution)
+ *    → .exe, .msi, .dmg, .deb, .rpm, .app, .apk, .jar
+ *    → Reason: Direct malware delivery vector
+ *    → Alternative: Use GitHub Releases or dedicated software distribution CDN
+ *
+ * 2. ARCHIVES (Piracy & Abuse)
+ *    → .zip, .rar, .tar, .gz, .7z, .bz2
+ *    → Reason: File sharing abuse, can contain executables, no web rendering
+ *    → Alternative: Use file hosting service (Dropbox, Google Drive) or GitHub Releases
+ *
+ * 3. SERVER-SIDE SCRIPTS (Credential Leakage)
+ *    → .php, .asp, .jsp, .cgi
+ *    → Reason: Source code exposure (database passwords, API keys, secrets)
+ *    → Alternative: Static hosting only - use serverless functions for backends
+ *
+ * 4. SHELL SCRIPTS (OS Execution)
+ *    → .sh, .bash, .bat, .cmd, .ps1, .vbs
+ *    → Reason: Execute on user's OS outside browser sandbox, social engineering risk
+ *    → Alternative: Embed code examples in HTML <pre><code> or link to GitHub repo
+ *
+ * 5. PROGRAMMING LANGUAGE SOURCE (Platform Scope)
+ *    → .py, .rb, .pl, .java, .c, .cpp, .cs, .go, .rs
+ *    → Reason: Not web-renderable, better served by GitHub/GitLab/Bitbucket
+ *    → Alternative: Use GitHub for code hosting, link to repository
+ *
+ * 6. OFFICE DOCUMENTS (Macro Malware)
+ *    → .doc, .docx, .xls, .xlsx, .ppt, .pptx
+ *    → Reason: Can contain VBA macros, active exploits in the wild
+ *    → Alternative: Use PDF for documents (fully supported)
+ *
+ * 7. GENERIC BINARIES (Unvalidatable)
+ *    → application/octet-stream
+ *    → Reason: Too broad - allows any binary format, cannot moderate effectively
+ *    → Alternative: Use specific MIME types for known formats
+ *
+ * ============================================================================
+ * Security Model:
+ * - Browser sandbox (JS/WASM execute safely in controlled environment)
+ * - AI content moderation (scans text/image content for abuse)
+ * - No server-side execution (static files only)
+ * - Explicit allowlist (only approved formats, reject unknown)
+ * ============================================================================
+ */
+export const ALLOWED_MIME_TYPES = [
+  // =========================================================================
+  // TEXT CONTENT (explicit list - no prefix matching for security)
+  // =========================================================================
+
+  // Core web documents
+  'text/html',                     // HTML pages
+  'text/css',                      // Stylesheets
+  'text/plain',                    // Plain text (robots.txt, .well-known/*, LICENSE, README.txt)
+  'text/markdown',                 // Markdown files (.md)
+  'text/xml',                      // XML files
+
+  // Data formats
+  'text/csv',                      // CSV data files
+  'text/yaml',                     // YAML config files
+
+  // Web-specific formats
+  'text/vtt',                      // WebVTT video subtitles/captions (accessibility)
+  'text/calendar',                 // iCalendar (.ics) event files
+
+  // JavaScript (legacy MIME type, still widely used by ~50% of servers)
+  'text/javascript',
+
+  // =========================================================================
+  // MEDIA (prefix matching - covers all common subtypes)
+  // =========================================================================
+
+  // Images: PNG, JPEG, GIF, SVG, WebP, AVIF, HEIC, BMP, TIFF, ICO, etc.
+  'image/',
+
+  // Audio: MP3, OGG, WAV, WebM, AAC, FLAC, Opus, etc.
+  'audio/',
+
+  // Video: MP4, WebM, OGG, QuickTime, etc.
+  'video/',
+
+  // Modern fonts: WOFF2, WOFF, TTF, OTF
+  'font/',
+
+  // =========================================================================
+  // CORE WEB APPLICATION TYPES
+  // =========================================================================
+
+  // JavaScript (multiple MIME types for compatibility)
+  'application/javascript',        // Modern standard (RFC 9239)
+  'application/ecmascript',        // ECMAScript (legacy but still used)
+  'application/x-javascript',      // Legacy variant (old CDNs, Apache configs)
+
+  // WebAssembly (modern web apps, games, compute-heavy workloads)
+  'application/wasm',
+
+  // JSON and structured data
+  'application/json',
+  'application/ld+json',           // JSON-LD for structured data / SEO (Schema.org, Open Graph)
+  'application/manifest+json',     // PWA web app manifests
+
+  // XML and feeds
+  'application/xml',
+  'application/xhtml+xml',         // XHTML - XML-compliant HTML (legacy sites)
+  'application/rss+xml',           // RSS feeds (blogs, podcasts)
+  'application/atom+xml',          // Atom feeds
+
+  // Configuration formats
+  'application/yaml',              // YAML configs (static site generators)
+
+  // Documents
+  'application/pdf',               // PDF documents
+
+  // =========================================================================
+  // 3D FORMATS (industry standard only)
+  // =========================================================================
+
+  // glTF - Khronos standard for 3D web content
+  'model/gltf+json',               // glTF JSON format
+  'model/gltf-binary',             // GLB binary format
+
+  // =========================================================================
+  // LEGACY COMPATIBILITY
+  // =========================================================================
+
+  // Video (some tools detect MP4 as application/mp4)
+  'application/mp4',
+
+  // Legacy font MIME types (Bootstrap, Font Awesome, IE compatibility)
+  'application/font-woff',
+  'application/font-woff2',
+  'application/x-font-woff',
+  'application/x-woff',
+  'application/vnd.ms-fontobject',  // EOT files (Internet Explorer)
+  'application/x-font-ttf',
+  'application/x-font-truetype',
+  'application/x-font-otf',
+  'application/x-font-opentype',
+] as const;
+
+/**
+ * Check if a MIME type is allowed for upload.
+ *
+ * Supports both exact matches and prefix matches:
+ * - 'application/json' matches 'application/json' exactly
+ * - 'text/' matches 'text/plain', 'text/html', etc.
+ *
+ * @example
+ * isAllowedMimeType('text/plain')     // true (prefix match)
+ * isAllowedMimeType('application/json') // true (exact match)
+ * isAllowedMimeType('application/wasm') // false (not allowed)
+ */
+export function isAllowedMimeType(mimeType: string): boolean {
+  return ALLOWED_MIME_TYPES.some(allowed =>
+    mimeType === allowed || mimeType.startsWith(allowed)
+  );
 }
 
 // =============================================================================