@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/plugins/installer/normalizeManifest.js

@@ -0,0 +1,306 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+import { CANONICAL_PLUGIN_MANIFEST_FILE, CODESHELL_PLUGIN_OVERLAY_FILE, CanonicalPluginManifest, CodeShellPluginOverlay, CodexPluginManifest, PluginInterfaceMetadata, PluginAutomationsManifest, } from "./types.js";
+import { validateSchedule } from "../../automation/scheduler.js";
+const CANONICAL_PLUGIN_ASSET_DIR = ".cs-plugin-assets";
+const MAX_PLUGIN_BRAND_ASSET_BYTES = 2 * 1024 * 1024;
+const MAX_PLUGIN_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+const MAX_PLUGIN_IMAGE_DIMENSION = 8192;
+const MAX_PLUGIN_IMAGE_PIXELS = 40_000_000;
+const MAX_PLUGIN_MANIFEST_BYTES = 1024 * 1024;
+function manifestPath(sourceRoot, format) {
+    return join(sourceRoot, format === "codex" ? ".codex-plugin" : ".claude-plugin", "plugin.json");
+}
+function isContained(root, candidate) {
+    const withSep = root.endsWith(sep) ? root : `${root}${sep}`;
+    return candidate.startsWith(withSep);
+}
+function safeAuthorAssetPath(value, field) {
+    if (value !== value.trim() ||
+        !value.startsWith("./") ||
+        value.includes("\\") ||
+        value.includes("\0") ||
+        value.includes("?") ||
+        value.includes("#")) {
+        throw new Error(`${field} must be a ./ relative path inside the plugin root`);
+    }
+    const relative = value.slice(2);
+    if (!relative ||
+        relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new Error(`${field} must be a safe relative path inside the plugin root`);
+    }
+    return relative;
+}
+function readUInt24LE(bytes, offset) {
+    return bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16);
+}
+function pngDimensions(bytes) {
+    if (bytes.length < 24 ||
+        !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ||
+        bytes.readUInt32BE(8) !== 13 ||
+        bytes.toString("ascii", 12, 16) !== "IHDR") {
+        return null;
+    }
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+function jpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return null;
+    let offset = 2;
+    while (offset + 4 <= bytes.length) {
+        while (offset < bytes.length && bytes[offset] === 0xff)
+            offset += 1;
+        if (offset >= bytes.length)
+            break;
+        const marker = bytes[offset];
+        offset += 1;
+        if (marker === 0xd8 ||
+            marker === 0xd9 ||
+            marker === 0x01 ||
+            (marker >= 0xd0 && marker <= 0xd7)) {
+            continue;
+        }
+        if (offset + 2 > bytes.length)
+            return null;
+        const length = bytes.readUInt16BE(offset);
+        if (length < 2 || offset + length > bytes.length)
+            return null;
+        const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (isStartOfFrame) {
+            if (length < 7)
+                return null;
+            return {
+                width: bytes.readUInt16BE(offset + 5),
+                height: bytes.readUInt16BE(offset + 3),
+            };
+        }
+        offset += length;
+    }
+    return null;
+}
+function webpDimensions(bytes) {
+    if (bytes.length < 30 ||
+        bytes.toString("ascii", 0, 4) !== "RIFF" ||
+        bytes.toString("ascii", 8, 12) !== "WEBP" ||
+        bytes.readUInt32LE(4) + 8 > bytes.length) {
+        return null;
+    }
+    const chunk = bytes.toString("ascii", 12, 16);
+    if (chunk === "VP8X") {
+        return {
+            width: readUInt24LE(bytes, 24) + 1,
+            height: readUInt24LE(bytes, 27) + 1,
+        };
+    }
+    if (chunk === "VP8L" && bytes[20] === 0x2f) {
+        return {
+            width: 1 + (((bytes[22] & 0x3f) << 8) | bytes[21]),
+            height: 1 + (((bytes[24] & 0x0f) << 10) | (bytes[23] << 2) | (bytes[22] >> 6)),
+        };
+    }
+    if (chunk === "VP8 " && bytes[23] === 0x9d && bytes[24] === 0x01 && bytes[25] === 0x2a) {
+        return {
+            width: bytes.readUInt16LE(26) & 0x3fff,
+            height: bytes.readUInt16LE(28) & 0x3fff,
+        };
+    }
+    return null;
+}
+function detectRaster(bytes) {
+    const png = pngDimensions(bytes);
+    if (png)
+        return { mediaType: "image/png", ...png };
+    const jpeg = jpegDimensions(bytes);
+    if (jpeg)
+        return { mediaType: "image/jpeg", ...jpeg };
+    const webp = webpDimensions(bytes);
+    if (webp)
+        return { mediaType: "image/webp", ...webp };
+    return null;
+}
+function expectedMediaType(relativePath) {
+    switch (extname(relativePath).toLowerCase()) {
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".webp":
+            return "image/webp";
+        default:
+            return null;
+    }
+}
+async function validateRasterAsset(sourceRoot, sourceRootReal, declaredPath, field, maxBytes, screenshot) {
+    const relativePath = safeAuthorAssetPath(declaredPath, field);
+    if (screenshot &&
+        (!relativePath.startsWith("assets/") || extname(relativePath).toLowerCase() !== ".png")) {
+        throw new Error(`${field} must be a PNG file under ./assets/`);
+    }
+    const expected = expectedMediaType(relativePath);
+    if (!expected || (screenshot && expected !== "image/png")) {
+        throw new Error(`${field} must be PNG, JPEG, or WebP`);
+    }
+    const candidate = resolve(sourceRoot, ...relativePath.split("/"));
+    let target;
+    try {
+        target = await realpath(candidate);
+    }
+    catch {
+        throw new Error(`${field} does not exist: ${declaredPath}`);
+    }
+    if (!isContained(sourceRootReal, target)) {
+        throw new Error(`${field} escapes the plugin root: ${declaredPath}`);
+    }
+    const info = await stat(target);
+    if (!info.isFile())
+        throw new Error(`${field} is not a file: ${declaredPath}`);
+    if (info.size > maxBytes) {
+        throw new Error(`${field} exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB limit`);
+    }
+    const bytes = await readFile(target);
+    const detected = detectRaster(bytes);
+    if (!detected || detected.mediaType !== expected) {
+        throw new Error(`${field} content does not match its supported raster extension`);
+    }
+    if (detected.width <= 0 ||
+        detected.height <= 0 ||
+        detected.width > MAX_PLUGIN_IMAGE_DIMENSION ||
+        detected.height > MAX_PLUGIN_IMAGE_DIMENSION ||
+        detected.width * detected.height > MAX_PLUGIN_IMAGE_PIXELS) {
+        throw new Error(`${field} dimensions exceed ${MAX_PLUGIN_IMAGE_DIMENSION}px / ${MAX_PLUGIN_IMAGE_PIXELS} pixels`);
+    }
+    return { bytes, mediaType: detected.mediaType };
+}
+function canonicalAssetExtension(mediaType) {
+    if (mediaType === "image/jpeg")
+        return "jpeg";
+    if (mediaType === "image/webp")
+        return "webp";
+    return "png";
+}
+async function normalizeInterfaceAssets(sourceRoot, destinationRoot, metadata) {
+    const hasDeclaredAssets = Boolean(metadata.composerIcon || metadata.logo || metadata.logoDark) ||
+        metadata.screenshots !== undefined;
+    if (!hasDeclaredAssets)
+        return metadata;
+    const sourceRootReal = await realpath(sourceRoot);
+    const declared = [
+        ["composerIcon", metadata.composerIcon, "composer-icon"],
+        ["logo", metadata.logo, "logo"],
+        ["logoDark", metadata.logoDark, "logo-dark"],
+    ];
+    const brandAssets = await Promise.all(declared.map(async ([field, value, canonicalName]) => {
+        if (!value)
+            return null;
+        const asset = await validateRasterAsset(sourceRoot, sourceRootReal, value, `interface.${field}`, MAX_PLUGIN_BRAND_ASSET_BYTES, false);
+        return { field, canonicalName, asset };
+    }));
+    const screenshots = await Promise.all((metadata.screenshots ?? []).map(async (value, index) => ({
+        canonicalName: `screenshot-${index + 1}`,
+        asset: await validateRasterAsset(sourceRoot, sourceRootReal, value, `interface.screenshots[${index}]`, MAX_PLUGIN_SCREENSHOT_BYTES, true),
+    })));
+    const assetRoot = join(destinationRoot, CANONICAL_PLUGIN_ASSET_DIR);
+    await rm(assetRoot, { recursive: true, force: true });
+    const hasAssets = brandAssets.some(Boolean) || screenshots.length > 0;
+    if (hasAssets)
+        await mkdir(assetRoot, { recursive: true });
+    const normalized = { ...metadata };
+    for (const entry of brandAssets) {
+        if (!entry)
+            continue;
+        const relativePath = `${CANONICAL_PLUGIN_ASSET_DIR}/${entry.canonicalName}.${canonicalAssetExtension(entry.asset.mediaType)}`;
+        await writeFile(join(destinationRoot, relativePath), entry.asset.bytes);
+        normalized[entry.field] = relativePath;
+    }
+    if (metadata.screenshots !== undefined) {
+        normalized.screenshots = [];
+        for (const entry of screenshots) {
+            const relativePath = `${CANONICAL_PLUGIN_ASSET_DIR}/${entry.canonicalName}.png`;
+            await writeFile(join(destinationRoot, relativePath), entry.asset.bytes);
+            normalized.screenshots.push(relativePath);
+        }
+    }
+    return normalized;
+}
+async function readCodeShellOverlay(sourceRoot) {
+    const file = join(sourceRoot, CODESHELL_PLUGIN_OVERLAY_FILE);
+    if (!existsSync(file))
+        return null;
+    const info = await stat(file);
+    if (!info.isFile() || info.size > MAX_PLUGIN_MANIFEST_BYTES) {
+        throw new Error(`${CODESHELL_PLUGIN_OVERLAY_FILE} must be a regular file no larger than ${MAX_PLUGIN_MANIFEST_BYTES} bytes`);
+    }
+    const raw = JSON.parse(await readFile(file, "utf-8"));
+    if (raw.panels !== undefined) {
+        throw new Error("Agent Plugin packages cannot declare panels; package Desktop UI as a separate " +
+            ".codeshell-panel/panel.json Panel App");
+    }
+    return CodeShellPluginOverlay.parse(raw);
+}
+/**
+ * Normalize an Agent Plugin into the runtime manifest. Desktop Panel Apps have
+ * their own package and installer, so a Plugin declaration cannot contain UI.
+ */
+export async function normalizePluginManifest(sourceRoot, options) {
+    const authorPath = manifestPath(sourceRoot, options.format);
+    let raw = {};
+    if (existsSync(authorPath)) {
+        const info = await stat(authorPath);
+        if (!info.isFile() || info.size > MAX_PLUGIN_MANIFEST_BYTES) {
+            throw new Error(`plugin manifest must be a regular file no larger than ${MAX_PLUGIN_MANIFEST_BYTES} bytes`);
+        }
+        raw = JSON.parse(await readFile(authorPath, "utf-8"));
+    }
+    const parsed = options.format === "codex"
+        ? CodexPluginManifest.parse(raw)
+        : {
+            description: typeof raw.description === "string" ? raw.description : undefined,
+            interface: undefined,
+        };
+    const overlay = await readCodeShellOverlay(sourceRoot);
+    if (raw.panels !== undefined) {
+        throw new Error("Agent Plugin packages cannot declare panels; package Desktop UI as a separate " +
+            ".codeshell-panel/panel.json Panel App");
+    }
+    const automations = overlay?.automations
+        ? PluginAutomationsManifest.parse(overlay.automations)
+        : undefined;
+    for (const template of automations?.templates ?? []) {
+        try {
+            validateSchedule(template.schedule, template.timezone);
+        }
+        catch (error) {
+            throw new Error(`automation template '${template.id}' has an invalid schedule: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    const parsedInterface = parsed.interface
+        ? PluginInterfaceMetadata.parse(parsed.interface)
+        : undefined;
+    const normalizedInterface = parsedInterface
+        ? await normalizeInterfaceAssets(sourceRoot, options.destinationRoot, parsedInterface)
+        : undefined;
+    const canonical = CanonicalPluginManifest.parse({
+        schemaVersion: 1,
+        name: options.name,
+        version: options.version ?? (typeof raw.version === "string" ? raw.version : undefined),
+        description: parsed.description,
+        interface: normalizedInterface,
+        automations,
+    });
+    await mkdir(options.destinationRoot, { recursive: true });
+    await writeFile(join(options.destinationRoot, CANONICAL_PLUGIN_MANIFEST_FILE), `${JSON.stringify(canonical, null, 2)}\n`, "utf-8");
+    return canonical;
+}
+export async function readCanonicalPluginManifest(installRoot) {
+    const file = join(installRoot, CANONICAL_PLUGIN_MANIFEST_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        return CanonicalPluginManifest.parse(JSON.parse(await readFile(file, "utf-8")));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plugins/installer/npmTar.d.ts

@@ -0,0 +1,13 @@
+export declare const MAX_NPM_TARBALL_BYTES: number;
+export declare const MAX_NPM_TAR_EXTRACTED_BYTES: number;
+export declare const MAX_NPM_TAR_FILE_BYTES: number;
+export declare const MAX_NPM_TAR_ENTRIES = 10000;
+export declare const MAX_NPM_TAR_PATH_BYTES = 1024;
+export declare const MAX_NPM_TAR_DEPTH = 32;
+/** Inflate the npm .tgz into a bounded private tar file. */
+export declare function gunzipNpmTarball(tgzPath: string, tarPath: string): Promise<void>;
+/**
+ * Extract only regular files/directories from an already-bounded tar.
+ * Links, devices, FIFOs, sparse files and every other special type fail closed.
+ */
+export declare function extractNpmTar(tarPath: string, destDir: string): Promise<void>;

package/dist/plugins/installer/npmTar.js

@@ -0,0 +1,321 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { lstat, mkdir, open, readdir, stat } from "node:fs/promises";
+import { dirname, join, normalize, sep } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { PluginInstallError } from "./types.js";
+export const MAX_NPM_TARBALL_BYTES = 64 * 1024 * 1024;
+export const MAX_NPM_TAR_EXTRACTED_BYTES = 256 * 1024 * 1024;
+export const MAX_NPM_TAR_FILE_BYTES = 64 * 1024 * 1024;
+export const MAX_NPM_TAR_ENTRIES = 10_000;
+export const MAX_NPM_TAR_PATH_BYTES = 1_024;
+export const MAX_NPM_TAR_DEPTH = 32;
+const TAR_BLOCK = 512;
+const MAX_PAX_BYTES = 64 * 1024;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+function installError(message, cause) {
+    const suffix = cause instanceof Error ? `: ${cause.message}` : "";
+    return new PluginInstallError(`${message}${suffix}`);
+}
+/** Inflate the npm .tgz into a bounded private tar file. */
+export async function gunzipNpmTarball(tgzPath, tarPath) {
+    const compressed = await stat(tgzPath);
+    if (!compressed.isFile() || compressed.size > MAX_NPM_TARBALL_BYTES) {
+        throw new PluginInstallError(`npm plugin tarball must be a regular file no larger than ${MAX_NPM_TARBALL_BYTES} bytes`);
+    }
+    let expanded = 0;
+    const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+            expanded += chunk.length;
+            if (expanded > MAX_NPM_TAR_EXTRACTED_BYTES) {
+                callback(new PluginInstallError(`npm plugin tarball expands beyond ${MAX_NPM_TAR_EXTRACTED_BYTES} bytes`));
+                return;
+            }
+            callback(null, chunk);
+        },
+    });
+    try {
+        await pipeline(createReadStream(tgzPath), createGunzip(), limiter, createWriteStream(tarPath, { flags: "wx", mode: 0o600 }));
+    }
+    catch (error) {
+        if (error instanceof PluginInstallError)
+            throw error;
+        throw installError("cannot decompress npm plugin tarball", error);
+    }
+}
+function isZeroBlock(block) {
+    for (const byte of block)
+        if (byte !== 0)
+            return false;
+    return true;
+}
+function decodeField(block, start, length, label) {
+    const field = block.subarray(start, start + length);
+    const nul = field.indexOf(0);
+    const value = nul < 0 ? field : field.subarray(0, nul);
+    try {
+        return utf8.decode(value);
+    }
+    catch (error) {
+        throw installError(`npm tar has invalid UTF-8 in ${label}`, error);
+    }
+}
+function parseOctal(block, start, length, label) {
+    const field = block.subarray(start, start + length);
+    if ((field[0] ?? 0) & 0x80) {
+        throw new PluginInstallError(`npm tar uses unsupported base-256 ${label}`);
+    }
+    const raw = field.toString("ascii").replace(/\0.*$/, "").trim();
+    if (!/^[0-7]+$/.test(raw)) {
+        throw new PluginInstallError(`npm tar has invalid ${label}`);
+    }
+    const value = Number.parseInt(raw, 8);
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new PluginInstallError(`npm tar ${label} is out of range`);
+    }
+    return value;
+}
+function assertHeaderChecksum(block) {
+    const expected = parseOctal(block, 148, 8, "header checksum");
+    let actual = 0;
+    for (let i = 0; i < block.length; i += 1) {
+        actual += i >= 148 && i < 156 ? 0x20 : (block[i] ?? 0);
+    }
+    if (actual !== expected) {
+        throw new PluginInstallError("npm tar header checksum mismatch");
+    }
+}
+function safeTarPath(destDir, rawName) {
+    if (rawName.length === 0 ||
+        Buffer.byteLength(rawName, "utf8") > MAX_NPM_TAR_PATH_BYTES ||
+        rawName.includes("\0") ||
+        rawName.includes("\\") ||
+        rawName.startsWith("/") ||
+        /^[A-Za-z]:/.test(rawName)) {
+        throw new PluginInstallError(`refusing unsafe npm tar path: ${rawName}`);
+    }
+    const segments = rawName.replace(/\/+$/, "").split("/");
+    if (segments.length === 0 ||
+        segments.length > MAX_NPM_TAR_DEPTH ||
+        segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new PluginInstallError(`refusing unsafe npm tar path: ${rawName}`);
+    }
+    const target = normalize(join(destDir, ...segments));
+    const root = normalize(destDir.endsWith(sep) ? destDir : destDir + sep);
+    if (target !== normalize(destDir) && !target.startsWith(root)) {
+        throw new PluginInstallError(`npm tar path escapes extraction root: ${rawName}`);
+    }
+    // Reject names that collide on the default case-insensitive macOS/Windows
+    // filesystems even when tests run on a case-sensitive volume.
+    return { target, portableKey: segments.join("/").toLowerCase() };
+}
+async function readExactly(handle, position, length) {
+    const value = Buffer.alloc(length);
+    let offset = 0;
+    while (offset < length) {
+        const { bytesRead } = await handle.read(value, offset, length - offset, position + offset);
+        if (bytesRead === 0)
+            throw new PluginInstallError("npm tar is truncated");
+        offset += bytesRead;
+    }
+    return value;
+}
+function parsePax(data) {
+    let cursor = 0;
+    const result = {};
+    while (cursor < data.length) {
+        const space = data.indexOf(0x20, cursor);
+        if (space < 0)
+            throw new PluginInstallError("npm tar has malformed PAX metadata");
+        const lengthText = data.subarray(cursor, space).toString("ascii");
+        if (!/^[1-9][0-9]*$/.test(lengthText)) {
+            throw new PluginInstallError("npm tar has malformed PAX record length");
+        }
+        const length = Number(lengthText);
+        if (!Number.isSafeInteger(length) ||
+            length <= space - cursor + 2 ||
+            cursor + length > data.length) {
+            throw new PluginInstallError("npm tar has out-of-range PAX record length");
+        }
+        const record = data.subarray(space + 1, cursor + length);
+        if (record[record.length - 1] !== 0x0a) {
+            throw new PluginInstallError("npm tar PAX record is not newline terminated");
+        }
+        let text;
+        try {
+            text = utf8.decode(record.subarray(0, -1));
+        }
+        catch (error) {
+            throw installError("npm tar has invalid UTF-8 in PAX metadata", error);
+        }
+        const equals = text.indexOf("=");
+        if (equals <= 0)
+            throw new PluginInstallError("npm tar has malformed PAX metadata");
+        const key = text.slice(0, equals);
+        const value = text.slice(equals + 1);
+        if (key === "path")
+            result.path = value;
+        if (key === "linkpath") {
+            throw new PluginInstallError("npm tar link metadata is forbidden");
+        }
+        if (key === "size") {
+            throw new PluginInstallError("npm tar PAX size overrides are unsupported");
+        }
+        cursor += length;
+    }
+    return result;
+}
+async function copyFilePayload(source, sourceOffset, target, size) {
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const output = await open(target, "wx", 0o600);
+    try {
+        let copied = 0;
+        while (copied < size) {
+            const chunkSize = Math.min(64 * 1024, size - copied);
+            const chunk = await readExactly(source, sourceOffset + copied, chunkSize);
+            await output.write(chunk, 0, chunk.length, copied);
+            copied += chunk.length;
+        }
+    }
+    finally {
+        await output.close();
+    }
+}
+/**
+ * Extract only regular files/directories from an already-bounded tar.
+ * Links, devices, FIFOs, sparse files and every other special type fail closed.
+ */
+export async function extractNpmTar(tarPath, destDir) {
+    await mkdir(destDir, { recursive: true, mode: 0o700 });
+    const destination = await lstat(destDir);
+    if (!destination.isDirectory() || destination.isSymbolicLink()) {
+        throw new PluginInstallError("npm tar extraction destination must be a real directory");
+    }
+    if ((await readdir(destDir)).length !== 0) {
+        throw new PluginInstallError("npm tar extraction destination must be empty");
+    }
+    const archive = await stat(tarPath);
+    if (!archive.isFile() || archive.size > MAX_NPM_TAR_EXTRACTED_BYTES) {
+        throw new PluginInstallError("npm tar is not a bounded regular file");
+    }
+    const input = await open(tarPath, "r");
+    const seen = new Set();
+    let entries = 0;
+    let materializedBytes = 0;
+    let position = 0;
+    let zeroBlocks = 0;
+    let nextPath;
+    try {
+        while (position < archive.size) {
+            if (position + TAR_BLOCK > archive.size) {
+                throw new PluginInstallError("npm tar has a partial header block");
+            }
+            const header = await readExactly(input, position, TAR_BLOCK);
+            position += TAR_BLOCK;
+            if (isZeroBlock(header)) {
+                zeroBlocks += 1;
+                if (zeroBlocks >= 2)
+                    break;
+                continue;
+            }
+            if (zeroBlocks !== 0) {
+                throw new PluginInstallError("npm tar has data after an end marker");
+            }
+            assertHeaderChecksum(header);
+            entries += 1;
+            if (entries > MAX_NPM_TAR_ENTRIES) {
+                throw new PluginInstallError(`npm tar contains more than ${MAX_NPM_TAR_ENTRIES} entries`);
+            }
+            const name = decodeField(header, 0, 100, "entry name");
+            const prefix = decodeField(header, 345, 155, "entry prefix");
+            const headerPath = prefix ? `${prefix}/${name}` : name;
+            const size = parseOctal(header, 124, 12, "entry size");
+            const typeByte = header[156] ?? 0;
+            const type = typeByte === 0 ? "0" : String.fromCharCode(typeByte);
+            const padded = Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+            if (position + padded > archive.size) {
+                throw new PluginInstallError("npm tar entry payload is truncated");
+            }
+            if (type === "x") {
+                if (size > MAX_PAX_BYTES)
+                    throw new PluginInstallError("npm tar PAX metadata is too large");
+                const pax = parsePax(await readExactly(input, position, size));
+                nextPath = pax.path;
+                position += padded;
+                continue;
+            }
+            if (type === "g") {
+                if (size > MAX_PAX_BYTES)
+                    throw new PluginInstallError("npm tar PAX metadata is too large");
+                parsePax(await readExactly(input, position, size));
+                position += padded;
+                continue;
+            }
+            if (type === "L") {
+                if (size === 0 || size > MAX_NPM_TAR_PATH_BYTES + 1) {
+                    throw new PluginInstallError("npm tar GNU long path is out of bounds");
+                }
+                const longName = await readExactly(input, position, size);
+                const nul = longName.indexOf(0);
+                try {
+                    nextPath = utf8.decode(nul < 0 ? longName : longName.subarray(0, nul));
+                }
+                catch (error) {
+                    throw installError("npm tar has invalid UTF-8 in GNU long path", error);
+                }
+                position += padded;
+                continue;
+            }
+            const effectivePath = nextPath ?? headerPath;
+            nextPath = undefined;
+            if (type !== "0" && type !== "5") {
+                const labels = {
+                    "1": "hardlink",
+                    "2": "symlink",
+                    "3": "character device",
+                    "4": "block device",
+                    "6": "FIFO",
+                };
+                throw new PluginInstallError(`npm tar ${labels[type] ?? `special entry type ${JSON.stringify(type)}`} is forbidden: ${effectivePath}`);
+            }
+            const safe = safeTarPath(destDir, effectivePath);
+            if (seen.has(safe.portableKey)) {
+                throw new PluginInstallError(`npm tar contains a duplicate path: ${effectivePath}`);
+            }
+            seen.add(safe.portableKey);
+            if (type === "5") {
+                if (size !== 0)
+                    throw new PluginInstallError("npm tar directory has a non-zero payload");
+                await mkdir(safe.target, { recursive: true, mode: 0o700 });
+            }
+            else {
+                if (size > MAX_NPM_TAR_FILE_BYTES) {
+                    throw new PluginInstallError(`npm tar file exceeds ${MAX_NPM_TAR_FILE_BYTES} bytes`);
+                }
+                materializedBytes += size;
+                if (materializedBytes > MAX_NPM_TAR_EXTRACTED_BYTES) {
+                    throw new PluginInstallError(`npm tar files exceed ${MAX_NPM_TAR_EXTRACTED_BYTES} extracted bytes`);
+                }
+                await copyFilePayload(input, position, safe.target, size);
+            }
+            position += padded;
+        }
+        if (zeroBlocks < 2)
+            throw new PluginInstallError("npm tar is missing its end marker");
+        while (position < archive.size) {
+            const remaining = Math.min(TAR_BLOCK, archive.size - position);
+            const trailing = await readExactly(input, position, remaining);
+            if (!isZeroBlock(trailing)) {
+                throw new PluginInstallError("npm tar has non-zero trailing data");
+            }
+            position += remaining;
+        }
+        if (nextPath !== undefined) {
+            throw new PluginInstallError("npm tar ends with unapplied path metadata");
+        }
+    }
+    finally {
+        await input.close();
+    }
+}

package/dist/plugins/installer/parseSource.d.ts

@@ -9,6 +9,13 @@
 export type ParsedSource = {
     kind: "local";
     path: string;
+} | {
+    kind: "npm";
+    packageName: string;
+    selector: string;
+    selectorKind: "exact" | "tag";
+    raw: string;
+    inferredName: string;
 } | {
     kind: "remote";
     url: string;
@@ -20,4 +27,8 @@ export type ParsedSource = {
 export interface ParseSourceOptions {
     allowUnsafeTransport?: boolean;
 }
+/** Parse the intentionally small npm Phase-A source grammar. */
+export declare function parseNpmPluginSource(input: string): Extract<ParsedSource, {
+    kind: "npm";
+}>;
 export declare function parseSource(input: string, options?: ParseSourceOptions): ParsedSource;