codex-plugin-doctor 1.59.0 → 1.61.0

package/dist/core/submission-archive-ruleset.js

@@ -0,0 +1,61 @@
+const sources = Object.freeze([
+    "https://developers.openai.com/plugins/build/plugins",
+    "https://developers.openai.com/plugins/deploy/submission-errors"
+]);
+const portalRules = Object.freeze([
+    Object.freeze({ id: "plugin.submission.archive.plugin_name_mismatch", status: "unavailable", reason: "Requires the previously published plugin identity.", source: "submission-errors" }),
+    Object.freeze({ id: "plugin.submission.archive.plugin_version_unchanged", status: "unavailable", reason: "Requires the previously published plugin version.", source: "submission-errors" }),
+    Object.freeze({ id: "plugin.submission.archive.manifest_normalized", status: "unavailable", reason: "The portal owns exact manifest normalization.", source: "submission-errors" }),
+    Object.freeze({ id: "plugin.submission.archive.developer_name_defaulted", status: "unavailable", reason: "Requires the selected verified developer identity.", source: "submission-errors" }),
+    Object.freeze({ id: "plugin.submission.archive.path_length", status: "unavailable", reason: "The public reference does not publish a numeric path-length limit.", source: "submission-errors" }),
+    Object.freeze({ id: "plugin.submission.archive.normalization_algorithm", status: "unavailable", reason: "The portal does not publish its case and Unicode collision algorithm.", source: "submission-errors" }),
+    Object.freeze({ id: "plugin.submission.archive.claude_format_normalized", status: "manual", reason: "The portal owns Claude-format normalization details.", source: "submission-errors" })
+]);
+export const submissionArchiveRuleset = Object.freeze({
+    version: "openai-directory-archive-2026-08-23",
+    reviewedAt: "2026-08-23",
+    sources,
+    limits: Object.freeze({
+        compressedBytes: 100 * 1000 * 1000,
+        entries: 5_000,
+        memberBytes: 100 * 1024 * 1024,
+        totalBytes: 512 * 1024 * 1024
+    }),
+    structures: Object.freeze({
+        eocdComments: "automatic",
+        zip64: "automatic",
+        dataDescriptors: "automatic"
+    }),
+    compression: Object.freeze({
+        stored: "automatic",
+        deflate: "automatic"
+    }),
+    collisionAlgorithm: "NFKC + toLowerCase per segment",
+    automaticChecks: Object.freeze([
+        "plugin.submission.archive.invalid_file",
+        "plugin.submission.archive.invalid_zip",
+        "plugin.submission.archive.too_large",
+        "plugin.submission.archive.entry_count",
+        "plugin.submission.archive.member_too_large",
+        "plugin.submission.archive.total_too_large",
+        "plugin.submission.archive.encrypted",
+        "plugin.submission.archive.header_mismatch",
+        "plugin.submission.archive.descriptor_invalid",
+        "plugin.submission.archive.range_invalid",
+        "plugin.submission.archive.crc_mismatch",
+        "plugin.submission.archive.path_invalid",
+        "plugin.submission.archive.path_duplicate",
+        "plugin.submission.archive.path_conflict",
+        "plugin.submission.archive.type_unsupported",
+        "plugin.submission.archive.normalization_collision",
+        "plugin.submission.archive.root_missing",
+        "plugin.submission.archive.root_ambiguous",
+        "plugin.submission.archive.root_siblings",
+        "plugin.submission.archive.manifest_missing",
+        "plugin.submission.archive.skill_missing",
+        "plugin.submission.archive.mcp_excluded",
+        "plugin.submission.archive.app_excluded",
+        "plugin.submission.archive.screenshot_excluded"
+    ]),
+    portalRules
+});

package/dist/core/submission-assets.d.ts

@@ -1,6 +1,8 @@
-import type { DiscoveredPackage } from "../domain/types.js";
+import type { DiscoveredPackage, PluginManifest } from "../domain/types.js";
+import { type SubmissionPackageReader } from "./submission-package-reader.js";
 import type { SubmissionFinding } from "./submission-preflight.js";
 export interface SubmissionAssetResult {
     findings: SubmissionFinding[];
 }
+export declare function validateSubmissionAssetsFromReader(manifest: PluginManifest, reader: SubmissionPackageReader): Promise<SubmissionAssetResult>;
 export declare function validateSubmissionAssets(discoveredPackage: DiscoveredPackage): Promise<SubmissionAssetResult>;

package/dist/core/submission-assets.js

@@ -1,8 +1,7 @@
-import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { inflateSync } from "node:zlib";
 import { XMLParser, XMLValidator } from "fast-xml-parser";
-import { resolveSafePackagePath } from "./plugin-components.js";
+import { createDirectorySubmissionPackageReader } from "./submission-package-reader.js";
 const maxAssetBytes = 5 * 1024 * 1024;
 const MAX_DECODED_PNG_BYTES = 72 * 1024 * 1024;
 const minimumDimension = 48;
@@ -360,40 +359,60 @@ function dimensionFinding(field, packagePath, format, dimensions) {
     }
     return null;
 }
-async function validateAsset(rootPath, field, value) {
+function assetPackagePath(value) {
+    if (!value.startsWith("./"))
+        return null;
+    const packagePath = value.slice(2);
+    if (packagePath === ""
+        || packagePath.startsWith("/")
+        || /^[a-zA-Z]:/u.test(packagePath)
+        || packagePath.includes("\\")
+        || /[\u0000-\u001F\u007F]/u.test(packagePath)) {
+        return null;
+    }
+    const normalizedPackagePath = path.posix.normalize(packagePath);
+    if (normalizedPackagePath === "."
+        || normalizedPackagePath === ""
+        || normalizedPackagePath === ".."
+        || normalizedPackagePath.startsWith("../")
+        || path.posix.isAbsolute(normalizedPackagePath))
+        return null;
+    return normalizedPackagePath;
+}
+async function validateAsset(reader, field, value) {
     if (value === undefined) {
         return [finding("plugin.submission.asset.required", "Branding asset is required.", assetEvidence(field))];
     }
     if (typeof value !== "string") {
         return [finding("plugin.submission.asset.invalid_path", "Branding asset path is invalid.", assetEvidence(field))];
     }
-    const resolved = await resolveSafePackagePath(rootPath, value);
-    if (resolved === null) {
+    const packagePath = assetPackagePath(value);
+    if (packagePath === null) {
         return [finding("plugin.submission.asset.invalid_path", "Branding asset path is invalid.", assetEvidence(field))];
     }
-    const extension = extensions.get(path.extname(resolved.packagePath).toLowerCase());
+    const extension = extensions.get(path.extname(packagePath).toLowerCase());
     if (extension === undefined) {
-        return [finding("plugin.submission.asset.unsupported_format", "Branding asset format is unsupported.", assetEvidence(field, resolved.packagePath))];
+        return [finding("plugin.submission.asset.unsupported_format", "Branding asset format is unsupported.", assetEvidence(field, packagePath))];
     }
-    let details;
-    try {
-        details = await stat(resolved.path);
+    const details = await reader.stat(packagePath).catch(() => null);
+    if (details === null) {
+        return [finding("plugin.submission.asset.missing", "Branding asset is missing.", assetEvidence(field, packagePath, extension))];
     }
-    catch {
-        return [finding("plugin.submission.asset.missing", "Branding asset is missing.", assetEvidence(field, resolved.packagePath, extension))];
+    if (details.safeResolution === "outside") {
+        return [finding("plugin.submission.asset.invalid_path", "Branding asset path is invalid.", assetEvidence(field))];
     }
-    if (!details.isFile()) {
-        return [finding("plugin.submission.asset.unsupported_format", "Branding asset must be a regular file.", assetEvidence(field, resolved.packagePath, extension))];
+    if (details.safeResolution !== "safe") {
+        return [finding("plugin.submission.asset.missing", "Branding asset is missing.", assetEvidence(field, packagePath, extension))];
     }
-    if (details.size > maxAssetBytes) {
-        return [finding("plugin.submission.asset.too_large", "Branding asset exceeds the size limit.", { ...assetEvidence(field, resolved.packagePath, extension), limit: maxAssetBytes })];
+    if (details.resolvedKind !== "file") {
+        return [finding("plugin.submission.asset.unsupported_format", "Branding asset must be a regular file.", assetEvidence(field, packagePath, extension))];
     }
-    let content;
-    try {
-        content = await readFile(resolved.path);
+    if (details.size > maxAssetBytes) {
+        return [finding("plugin.submission.asset.too_large", "Branding asset exceeds the size limit.", { ...assetEvidence(field, packagePath, extension), limit: maxAssetBytes })];
     }
-    catch {
-        return [finding("plugin.submission.asset.missing", "Branding asset cannot be read.", assetEvidence(field, resolved.packagePath, extension))];
+    const content = await reader.read(packagePath, maxAssetBytes).catch(() => null);
+    if (content === null) {
+        return [finding("plugin.submission.asset.missing", "Branding asset cannot be read.", assetEvidence(field, packagePath, extension))];
     }
     if (extension === "svg") {
         let source;
@@ -401,30 +420,32 @@ async function validateAsset(rootPath, field, value) {
             source = new TextDecoder("utf-8", { fatal: true }).decode(content);
         }
         catch {
-            return [finding("plugin.submission.asset.unsafe_svg", "SVG must be valid UTF-8.", assetEvidence(field, resolved.packagePath, extension))];
+            return [finding("plugin.submission.asset.unsafe_svg", "SVG must be valid UTF-8.", assetEvidence(field, packagePath, extension))];
         }
         const dimensions = svgDimensions(source);
         if (dimensions === null) {
-            return [finding("plugin.submission.asset.unsafe_svg", "SVG is unsafe or lacks valid dimensions.", assetEvidence(field, resolved.packagePath, extension))];
+            return [finding("plugin.submission.asset.unsafe_svg", "SVG is unsafe or lacks valid dimensions.", assetEvidence(field, packagePath, extension))];
         }
-        const invalidDimensions = dimensionFinding(field, resolved.packagePath, extension, dimensions);
+        const invalidDimensions = dimensionFinding(field, packagePath, extension, dimensions);
         return invalidDimensions === null ? [] : [invalidDimensions];
     }
     const decoded = rasterAsset(content);
     if (decoded === null) {
-        return [finding("plugin.submission.asset.decode_failed", "Branding asset could not be decoded.", assetEvidence(field, resolved.packagePath, extension))];
+        return [finding("plugin.submission.asset.decode_failed", "Branding asset could not be decoded.", assetEvidence(field, packagePath, extension))];
     }
     if (decoded.format !== extension) {
-        return [finding("plugin.submission.asset.extension_mismatch", "Branding asset extension does not match its content.", assetEvidence(field, resolved.packagePath, decoded.format, decoded.dimensions))];
+        return [finding("plugin.submission.asset.extension_mismatch", "Branding asset extension does not match its content.", assetEvidence(field, packagePath, decoded.format, decoded.dimensions))];
     }
-    const invalidDimensions = dimensionFinding(field, resolved.packagePath, decoded.format, decoded.dimensions);
+    const invalidDimensions = dimensionFinding(field, packagePath, decoded.format, decoded.dimensions);
     return invalidDimensions === null ? [] : [invalidDimensions];
 }
-export async function validateSubmissionAssets(discoveredPackage) {
-    const listing = discoveredPackage.manifest.interface;
-    const interfaceValues = isRecord(listing) ? listing : {};
+export async function validateSubmissionAssetsFromReader(manifest, reader) {
+    const interfaceValues = isRecord(manifest.interface) ? manifest.interface : {};
     const findings = [];
     for (const field of assetFields)
-        findings.push(...await validateAsset(discoveredPackage.rootPath, field, interfaceValues[field]));
+        findings.push(...await validateAsset(reader, field, interfaceValues[field]));
     return { findings };
 }
+export async function validateSubmissionAssets(discoveredPackage) {
+    return validateSubmissionAssetsFromReader(discoveredPackage.manifest, createDirectorySubmissionPackageReader(discoveredPackage.rootPath));
+}

package/dist/core/submission-package-reader.d.ts

@@ -0,0 +1,15 @@
+export type SubmissionPackageEntryKind = "file" | "directory" | "symlink" | "other";
+export interface SubmissionPackageEntry {
+    packagePath: string;
+    kind: SubmissionPackageEntryKind;
+    resolvedKind: Exclude<SubmissionPackageEntryKind, "symlink"> | null;
+    resolvedPackagePath?: string;
+    size: number;
+    safeResolution: "safe" | "outside" | "unavailable";
+}
+export interface SubmissionPackageReader {
+    list(directory: string): Promise<readonly SubmissionPackageEntry[]>;
+    stat(packagePath: string): Promise<SubmissionPackageEntry | null>;
+    read(packagePath: string, maxBytes: number): Promise<Uint8Array | null>;
+}
+export declare function createDirectorySubmissionPackageReader(rootPath: string): SubmissionPackageReader;

package/dist/core/submission-package-reader.js

@@ -0,0 +1,274 @@
+import { lstat, open, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+const invalidPackagePathMessage = "Invalid package path.";
+const invalidMaxBytesMessage = "maxBytes must be a nonnegative safe integer.";
+function packageEntryKind(stats) {
+    if (stats.isFile()) {
+        return "file";
+    }
+    if (stats.isDirectory()) {
+        return "directory";
+    }
+    if (stats.isSymbolicLink()) {
+        return "symlink";
+    }
+    return "other";
+}
+function resolvedEntryKind(stats) {
+    const kind = packageEntryKind(stats);
+    return kind === "symlink" ? "other" : kind;
+}
+function isWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return relativePath === "" || (relativePath !== ".."
+        && !relativePath.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relativePath));
+}
+function normalizePackagePath(packagePath, options) {
+    if (typeof packagePath !== "string") {
+        throw new Error(invalidPackagePathMessage);
+    }
+    if (packagePath === "") {
+        if (options.allowRoot) {
+            return "";
+        }
+        throw new Error(invalidPackagePathMessage);
+    }
+    if (/[\u0000-\u001F\u007F]/u.test(packagePath)
+        || packagePath.startsWith("/")
+        || packagePath.startsWith("\\")
+        || /^[a-zA-Z]:/.test(packagePath)
+        || packagePath.includes("\\")) {
+        throw new Error(invalidPackagePathMessage);
+    }
+    const pathWithoutTrailingSlash = options.allowTrailingSlash && packagePath.endsWith("/")
+        ? packagePath.slice(0, -1)
+        : packagePath;
+    const segments = pathWithoutTrailingSlash.split("/");
+    if (pathWithoutTrailingSlash === ""
+        || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new Error(invalidPackagePathMessage);
+    }
+    return segments.join("/");
+}
+function nativePathFor(rootPath, packagePath) {
+    const candidatePath = path.resolve(rootPath, ...packagePath.split("/"));
+    return isWithinRoot(rootPath, candidatePath) ? candidatePath : null;
+}
+function validMaxBytes(maxBytes) {
+    return Number.isSafeInteger(maxBytes) && maxBytes >= 0;
+}
+export function createDirectorySubmissionPackageReader(rootPath) {
+    const nativeRootPath = path.resolve(rootPath);
+    async function canonicalRootPath() {
+        try {
+            return await realpath(nativeRootPath);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function ancestorsStayWithinRoot(packagePath, rootCanonicalPath) {
+        const segments = packagePath.split("/");
+        let ancestorPath = nativeRootPath;
+        for (const segment of segments.slice(0, -1)) {
+            ancestorPath = path.join(ancestorPath, segment);
+            try {
+                const canonicalAncestorPath = await realpath(ancestorPath);
+                if (!isWithinRoot(rootCanonicalPath, canonicalAncestorPath)) {
+                    return "outside";
+                }
+            }
+            catch {
+                return "unavailable";
+            }
+        }
+        return "safe";
+    }
+    async function entryFor(packagePath) {
+        const candidatePath = nativePathFor(nativeRootPath, packagePath);
+        if (candidatePath === null) {
+            return null;
+        }
+        try {
+            const rootCanonicalPath = await canonicalRootPath();
+            if (rootCanonicalPath === null) {
+                return null;
+            }
+            const ancestorResolution = await ancestorsStayWithinRoot(packagePath, rootCanonicalPath);
+            if (ancestorResolution === "outside") {
+                return {
+                    packagePath,
+                    kind: "other",
+                    resolvedKind: null,
+                    size: 0,
+                    safeResolution: "outside"
+                };
+            }
+            if (ancestorResolution === "unavailable") {
+                return null;
+            }
+            const entryStats = await lstat(candidatePath);
+            const kind = packageEntryKind(entryStats);
+            try {
+                const canonicalCandidatePath = await realpath(candidatePath);
+                const safeResolution = isWithinRoot(rootCanonicalPath, canonicalCandidatePath);
+                if (!safeResolution) {
+                    return {
+                        packagePath,
+                        kind,
+                        resolvedKind: null,
+                        size: entryStats.size,
+                        safeResolution: "outside"
+                    };
+                }
+                const targetStats = await stat(candidatePath);
+                const resolvedPackagePath = path.relative(rootCanonicalPath, canonicalCandidatePath).split(path.sep).join("/");
+                return {
+                    packagePath,
+                    ...(resolvedPackagePath === packagePath ? {} : { resolvedPackagePath }),
+                    kind,
+                    resolvedKind: resolvedEntryKind(targetStats),
+                    size: targetStats.size,
+                    safeResolution: "safe"
+                };
+            }
+            catch {
+                return kind === "symlink"
+                    ? {
+                        packagePath,
+                        kind,
+                        resolvedKind: null,
+                        size: entryStats.size,
+                        safeResolution: "unavailable"
+                    }
+                    : null;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        async list(directory) {
+            const normalizedDirectory = normalizePackagePath(directory, {
+                allowRoot: true,
+                allowTrailingSlash: true
+            });
+            const directoryPath = normalizedDirectory === ""
+                ? nativeRootPath
+                : nativePathFor(nativeRootPath, normalizedDirectory);
+            if (directoryPath === null) {
+                return [];
+            }
+            try {
+                if (normalizedDirectory !== "") {
+                    const directoryEntry = await entryFor(normalizedDirectory);
+                    if (directoryEntry?.resolvedKind !== "directory" || directoryEntry.safeResolution !== "safe") {
+                        return [];
+                    }
+                }
+                else if (await canonicalRootPath() === null) {
+                    return [];
+                }
+                const childNames = await readdir(directoryPath);
+                const entries = new Array(childNames.length).fill(null);
+                let nextChildIndex = 0;
+                async function readNextChild() {
+                    while (nextChildIndex < childNames.length) {
+                        const childIndex = nextChildIndex;
+                        nextChildIndex += 1;
+                        const childName = childNames[childIndex];
+                        const childPackagePath = normalizedDirectory === ""
+                            ? childName
+                            : `${normalizedDirectory}/${childName}`;
+                        try {
+                            const normalizedChildPath = normalizePackagePath(childPackagePath, {
+                                allowRoot: false,
+                                allowTrailingSlash: false
+                            });
+                            entries[childIndex] = await entryFor(normalizedChildPath);
+                        }
+                        catch {
+                            entries[childIndex] = null;
+                        }
+                    }
+                }
+                const workerCount = Math.min(16, childNames.length);
+                const workers = Array.from({ length: workerCount }, async () => readNextChild());
+                await Promise.all(workers);
+                return entries
+                    .filter((entry) => entry !== null)
+                    .sort((left, right) => left.packagePath.localeCompare(right.packagePath));
+            }
+            catch {
+                return [];
+            }
+        },
+        async stat(packagePath) {
+            return entryFor(normalizePackagePath(packagePath, {
+                allowRoot: false,
+                allowTrailingSlash: false
+            }));
+        },
+        async read(packagePath, maxBytes) {
+            const normalizedPackagePath = normalizePackagePath(packagePath, {
+                allowRoot: false,
+                allowTrailingSlash: false
+            });
+            if (!validMaxBytes(maxBytes)) {
+                throw new Error(invalidMaxBytesMessage);
+            }
+            const entry = await entryFor(normalizedPackagePath);
+            if (entry?.resolvedKind !== "file" || entry.safeResolution !== "safe" || entry.size > maxBytes) {
+                return null;
+            }
+            const candidatePath = nativePathFor(nativeRootPath, normalizedPackagePath);
+            if (candidatePath === null) {
+                return null;
+            }
+            let fileHandle = null;
+            try {
+                fileHandle = await open(candidatePath, "r");
+                const handleStats = await fileHandle.stat();
+                if (!handleStats.isFile()
+                    || !Number.isSafeInteger(handleStats.size)
+                    || handleStats.size < 0
+                    || handleStats.size > maxBytes) {
+                    return null;
+                }
+                const rootCanonicalPath = await canonicalRootPath();
+                const canonicalCandidatePath = await realpath(candidatePath);
+                const pathStats = await stat(candidatePath);
+                if (rootCanonicalPath === null
+                    || !isWithinRoot(rootCanonicalPath, canonicalCandidatePath)
+                    || !pathStats.isFile()
+                    || handleStats.dev !== pathStats.dev
+                    || handleStats.ino !== pathStats.ino) {
+                    return null;
+                }
+                const content = Buffer.alloc(handleStats.size);
+                let offset = 0;
+                while (offset < content.length) {
+                    const { bytesRead } = await fileHandle.read(content, offset, content.length - offset, offset);
+                    if (bytesRead === 0) {
+                        return null;
+                    }
+                    offset += bytesRead;
+                }
+                const probe = Buffer.alloc(1);
+                const { bytesRead: extraBytesRead } = await fileHandle.read(probe, 0, 1, offset);
+                if (extraBytesRead !== 0) {
+                    return null;
+                }
+                return Uint8Array.from(content);
+            }
+            catch {
+                return null;
+            }
+            finally {
+                await fileHandle?.close().catch(() => undefined);
+            }
+        }
+    };
+}

package/dist/core/submission-preflight.d.ts

@@ -31,4 +31,6 @@ export interface SubmissionPreflightReport {
     findings: SubmissionFinding[];
     manualChecklist: SubmissionManualCheck[];
 }
+export type SubmissionTargetType = SubmissionPreflightReport["targetType"];
+export declare function validateSubmissionListing(manifest: Record<string, unknown>, targetType: SubmissionTargetType): SubmissionFinding[];
 export declare function buildSubmissionPreflight(targetPath: string): Promise<SubmissionPreflightReport>;

package/dist/core/submission-preflight.js

@@ -106,7 +106,7 @@ function isValidHttpsUrl(value) {
         return false;
     }
 }
-function validateListing(manifest, targetType) {
+export function validateSubmissionListing(manifest, targetType) {
     const findings = [];
     validatePackage(manifest, findings);
     const listing = manifest.interface;
@@ -253,7 +253,7 @@ export async function buildSubmissionPreflight(targetPath) {
     const targetType = manifest.mcpServers !== undefined || manifest.apps !== undefined
         ? "mcp-backed"
         : "skills-only";
-    const listingFindings = validateListing(manifest, targetType);
+    const listingFindings = validateSubmissionListing(manifest, targetType);
     const componentFindings = await validateApp(discovered.rootPath, manifest.apps);
     const assetFindings = (await validateSubmissionAssets(discovered)).findings;
     const skillFindings = (await validateSubmissionSkillMetadata(discovered, targetType)).findings;

package/dist/core/submission-skill-metadata.d.ts

@@ -1,9 +1,11 @@
-import type { DiscoveredPackage } from "../domain/types.js";
-import type { SubmissionFinding } from "./submission-preflight.js";
-type TargetType = "skills-only" | "mcp-backed";
+import type { DiscoveredPackage, PluginManifest } from "../domain/types.js";
+import { type SubmissionPackageReader } from "./submission-package-reader.js";
+import type { SubmissionFinding, SubmissionPreflightReport } from "./submission-preflight.js";
+type TargetType = SubmissionPreflightReport["targetType"];
 export interface SubmissionSkillMetadataResult {
     findings: SubmissionFinding[];
     skillCount: number;
 }
+export declare function validateSubmissionSkillMetadataFromReader(manifest: PluginManifest, targetType: SubmissionPreflightReport["targetType"], reader: SubmissionPackageReader): Promise<SubmissionSkillMetadataResult>;
 export declare function validateSubmissionSkillMetadata(discoveredPackage: DiscoveredPackage, targetType: TargetType): Promise<SubmissionSkillMetadataResult>;
 export {};