diff --git a/docs/plugin-platform/contract-and-sdk.md b/docs/plugin-platform/contract-and-sdk.md index 4878e063e..71d72b50b 100644 --- a/docs/plugin-platform/contract-and-sdk.md +++ b/docs/plugin-platform/contract-and-sdk.md @@ -77,9 +77,11 @@ drive-letter paths, repeated separators, backslashes, `.` and `..` segments, Windows reserved names, control or platform-special characters, and platform-specific trailing dots or spaces. The semantic package validator also requires NFC-normalized text and uses conservative Unicode compatibility/case -folding when detecting path aliases; every official host consumer must run it -after schema validation because JSON Schema cannot express these filesystem -rules. +folding when detecting path aliases. It applies the same syntax and portability +checks after Unicode compatibility normalization, so compatibility characters +cannot introduce separators, traversal segments, drive prefixes, reserved +names, or trailing dots. Every official host consumer must run it after schema +validation because JSON Schema cannot express these filesystem rules. Every entrypoint, view document, package icon, and companion variant must exist in the package. diff --git a/packages/plugin-cli/src/cli.test.ts b/packages/plugin-cli/src/cli.test.ts index 7a12b3e49..6f0182285 100644 --- a/packages/plugin-cli/src/cli.test.ts +++ b/packages/plugin-cli/src/cli.test.ts @@ -140,11 +140,19 @@ test("path validation rejects traversal, platform aliases, and duplicates", () = "folder/file ", "folder/file?.js", "a//b", + "a/b", + "a\b", + "../x", + "..", + "C:/x", + "assets/CON.txt", + "file.", "😀".repeat(129), ]) { assert.throws(() => assertSafePackagePath(unsafe)); } assert.equal(assertSafePackagePath("😀".repeat(128)), "😀".repeat(128)); + assert.equal(assertSafePackagePath("assets/fullwidth-S.txt"), "assets/fullwidth-S.txt"); const registry = new PackagePathRegistry(); registry.add("dist/Plugin.js"); assert.throws(() => registry.add("dist/plugin.js"), /case-colliding/); diff --git a/packages/plugin-cli/src/packagePath.ts b/packages/plugin-cli/src/packagePath.ts index 52b485dd0..a843f68aa 100644 --- a/packages/plugin-cli/src/packagePath.ts +++ b/packages/plugin-cli/src/packagePath.ts @@ -15,6 +15,28 @@ function portablePathKey(value: string): string { .normalize("NFKC"); } +function assertPortablePathSyntax(value: string, originalInput: string): string[] { + if (value.startsWith("/") || /^[A-Za-z]:/.test(value) || value.includes("\\")) { + throw new Error(`Package path must be relative POSIX syntax: ${originalInput}`); + } + const segments = value.split("/"); + if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) { + throw new Error(`Package path contains an unsafe segment: ${originalInput}`); + } + for (const segment of segments) { + if ( + segment.endsWith(".") + || segment.endsWith(" ") + || WINDOWS_RESERVED_NAME.test(segment) + || WINDOWS_SPECIAL.test(segment) + || containsControlCharacter(segment) + ) { + throw new Error(`Package path is not portable across supported platforms: ${originalInput}`); + } + } + return segments; +} + export function assertSafePackagePath(input: string): string { if (!input || input !== input.normalize("NFC")) { throw new Error(`Package path must be non-empty NFC text: ${JSON.stringify(input)}`); @@ -27,23 +49,12 @@ export function assertSafePackagePath(input: string): string { if (Buffer.byteLength(input, "utf8") > PACKAGE_LIMITS.pathBytes) { throw new Error(`Package path exceeds ${PACKAGE_LIMITS.pathBytes} UTF-8 bytes: ${input}`); } - if (input.startsWith("/") || /^[A-Za-z]:/.test(input) || input.includes("\\")) { - throw new Error(`Package path must be relative POSIX syntax: ${input}`); - } - const segments = input.split("/"); - if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) { - throw new Error(`Package path contains an unsafe segment: ${input}`); - } - for (const segment of segments) { - if ( - segment.endsWith(".") - || segment.endsWith(" ") - || WINDOWS_RESERVED_NAME.test(segment) - || WINDOWS_SPECIAL.test(segment) - || containsControlCharacter(segment) - ) { - throw new Error(`Package path is not portable across supported platforms: ${input}`); - } + const rawSegments = assertPortablePathSyntax(input, input); + const compatibilitySegments = assertPortablePathSyntax(input.normalize("NFKC"), input); + if (compatibilitySegments.length !== rawSegments.length) { + throw new Error( + `Package path changes directory structure after Unicode compatibility normalization: ${input}`, + ); } return input; }