@shipstatic/types 0.7.4 → 0.7.5

package/dist/index.d.ts

@@ -389,12 +389,34 @@ export declare const BLOCKED_EXTENSIONS: ReadonlySet<string>;
  */
 export declare function isBlockedExtension(filename: string): boolean;
 /**
- * Directory names that indicate an unbuilt project was uploaded instead of build output.
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+export declare const UNSAFE_FILENAME_CHARS: RegExp;
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+export declare function hasUnsafeChars(filename: string): boolean;
+/**
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
  * Used for early detection in CLI, browser, and server validation.
  */
 export declare const UNBUILT_PROJECT_MARKERS: ReadonlySet<string>;
 /**
- * Check if a file path contains an unbuilt project marker directory.
+ * Check if a file path contains an unbuilt project marker.
  *
  * @example
  * hasUnbuiltMarker('node_modules/react/index.js')  // true

package/dist/index.js

@@ -250,10 +250,37 @@ export function isBlockedExtension(filename) {
     return BLOCKED_EXTENSIONS.has(ext);
 }
 // =============================================================================
+// FILENAME CHARACTER VALIDATION
+// =============================================================================
+/**
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+export const UNSAFE_FILENAME_CHARS = /[\x00-\x1f\x7f#?%\\<>"]/;
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+export function hasUnsafeChars(filename) {
+    return UNSAFE_FILENAME_CHARS.test(filename);
+}
+// =============================================================================
 // UNBUILT PROJECT MARKERS
 // =============================================================================
 /**
- * Directory names that indicate an unbuilt project was uploaded instead of build output.
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
  * Used for early detection in CLI, browser, and server validation.
  */
 export const UNBUILT_PROJECT_MARKERS = new Set([
@@ -261,7 +288,7 @@ export const UNBUILT_PROJECT_MARKERS = new Set([
     'package.json',
 ]);
 /**
- * Check if a file path contains an unbuilt project marker directory.
+ * Check if a file path contains an unbuilt project marker.
  *
  * @example
  * hasUnbuiltMarker('node_modules/react/index.js')  // true

package/package.json

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

package/src/index.ts

@@ -571,12 +571,42 @@ export function isBlockedExtension(filename: string): boolean {
   return BLOCKED_EXTENSIONS.has(ext);
 }
 
+// =============================================================================
+// FILENAME CHARACTER VALIDATION
+// =============================================================================
+
+/**
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+export const UNSAFE_FILENAME_CHARS = /[\x00-\x1f\x7f#?%\\<>"]/;
+
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+export function hasUnsafeChars(filename: string): boolean {
+  return UNSAFE_FILENAME_CHARS.test(filename);
+}
+
 // =============================================================================
 // UNBUILT PROJECT MARKERS
 // =============================================================================
 
 /**
- * Directory names that indicate an unbuilt project was uploaded instead of build output.
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
  * Used for early detection in CLI, browser, and server validation.
  */
 export const UNBUILT_PROJECT_MARKERS: ReadonlySet<string> = new Set([
@@ -585,7 +615,7 @@ export const UNBUILT_PROJECT_MARKERS: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Check if a file path contains an unbuilt project marker directory.
+ * Check if a file path contains an unbuilt project marker.
  *
  * @example
  * hasUnbuiltMarker('node_modules/react/index.js')  // true