feat(plugins): add plugin contract and SDK

This commit is contained in:
ryan-wong-coder committed 2026-07-17 19:47:16 +08:00
1 parent b66fea9fd0
commit 2a8dba4818
32 files changed
+4200 -33

No files matched your search

+535
View File
@@ -0,0 +1,535 @@
import { createHash, randomUUID } from "node:crypto";
import { constants, createReadStream, createWriteStream } from "node:fs";
import {
lstat,
mkdir,
open,
opendir,
rename,
rm,
stat,
} from "node:fs/promises";
import path from "node:path";
import { once } from "node:events";
import type { PluginManifest } from "@netcatty/plugin-contract";
import yauzl, { type Entry, type ZipFile } from "yauzl";
import { IGNORED_ROOT_ENTRIES, PACKAGE_LIMITS } from "./constants.js";
import { readAndValidateManifest, validateManifestValue } from "./manifest.js";
import { assertSafePackagePath, PackagePathRegistry } from "./packagePath.js";
const CRC32_TABLE = new Uint32Array(256);
const EXECUTABLE_EXTENSIONS = new Set([".bat", ".cmd", ".com", ".exe", ".ps1"]);
for (let index = 0; index < CRC32_TABLE.length; index += 1) {
let value = index;
for (let bit = 0; bit < 8; bit += 1) {
value = (value & 1) === 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
}
CRC32_TABLE[index] = value >>> 0;
}
interface ScannedFile {
readonly absolutePath: string;
readonly packagePath: string;
readonly size: number;
readonly crc32: number;
readonly sha256: string;
readonly executable: boolean;
}
export interface PackageBuildResult {
readonly outputPath: string;
readonly fileCount: number;
readonly uncompressedBytes: number;
readonly archiveBytes: number;
readonly sha256: string;
}
export interface PackageValidationResult {
readonly manifest: PluginManifest;
readonly fileCount: number;
readonly uncompressedBytes: number;
}
export type PluginDirectoryValidationResult = PackageValidationResult;
function updateCrc32(current: number, chunk: Buffer): number {
let crc = current;
for (const byte of chunk) crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
return crc >>> 0;
}
async function readRegularFile(
filePath: string,
onChunk: (chunk: Buffer) => void,
): Promise<{ size: number; mode: number }> {
const noFollow = "O_NOFOLLOW" in constants
? constants.O_NOFOLLOW
: 0;
const handle = await open(filePath, constants.O_RDONLY | noFollow);
try {
const fileStats = await handle.stat();
if (!fileStats.isFile()) throw new Error(`Package source is not a regular file: ${filePath}`);
let size = 0;
const stream = createReadStream(filePath, { fd: handle.fd, autoClose: false });
for await (const chunk of stream) {
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
size += buffer.byteLength;
onChunk(buffer);
}
return { size, mode: fileStats.mode };
} finally {
await handle.close();
}
}
async function hashFile(
filePath: string,
): Promise<{ crc32: number; sha256: string; size: number; mode: number }> {
const sha256 = createHash("sha256");
let crc = 0xffffffff;
const file = await readRegularFile(filePath, (buffer) => {
sha256.update(buffer);
crc = updateCrc32(crc, buffer);
});
return {
crc32: (crc ^ 0xffffffff) >>> 0,
sha256: sha256.digest("hex"),
size: file.size,
mode: file.mode,
};
}
function sortPackagePaths(left: ScannedFile, right: ScannedFile): number {
return Buffer.compare(Buffer.from(left.packagePath), Buffer.from(right.packagePath));
}
function isExecutablePackageFile(packagePath: string, mode: number): boolean {
return (mode & 0o111) !== 0
|| EXECUTABLE_EXTENSIONS.has(path.posix.extname(packagePath).toLowerCase());
}
async function scanPackageDirectory(
pluginDirectory: string,
manifest: PluginManifest,
): Promise<ScannedFile[]> {
const registry = new PackagePathRegistry();
const companionPaths = new Map(
(manifest.companionExecutables ?? []).map((companion) => [companion.path, companion]),
);
const files: ScannedFile[] = [];
let totalBytes = 0;
async function visit(directory: string, relativeDirectory: string): Promise<void> {
const entries = [];
for await (const entry of await opendir(directory)) entries.push(entry);
entries.sort((left, right) => Buffer.compare(Buffer.from(left.name), Buffer.from(right.name)));
for (const entry of entries) {
if (IGNORED_ROOT_ENTRIES.has(entry.name) || entry.name.endsWith(".ncpkg")) continue;
const relativePath = relativeDirectory
? `${relativeDirectory}/${entry.name}`
: entry.name;
const packagePath = assertSafePackagePath(relativePath);
const absolutePath = path.join(directory, entry.name);
const fileStats = await lstat(absolutePath);
if (fileStats.isSymbolicLink()) {
throw new Error(`Symbolic links are not allowed in plugin packages: ${packagePath}`);
}
if (fileStats.isDirectory()) {
await visit(absolutePath, packagePath);
continue;
}
if (!fileStats.isFile()) {
throw new Error(`Only regular files are allowed in plugin packages: ${packagePath}`);
}
registry.add(packagePath);
if (files.length + 1 > PACKAGE_LIMITS.fileCount) {
throw new Error(`Plugin package exceeds ${PACKAGE_LIMITS.fileCount} files`);
}
if (fileStats.size > PACKAGE_LIMITS.singleFileBytes) {
throw new Error(`Plugin file exceeds ${PACKAGE_LIMITS.singleFileBytes} bytes: ${packagePath}`);
}
totalBytes += fileStats.size;
if (totalBytes > PACKAGE_LIMITS.uncompressedBytes) {
throw new Error(
`Plugin package exceeds ${PACKAGE_LIMITS.uncompressedBytes} uncompressed bytes`,
);
}
const hashes = await hashFile(absolutePath);
if (hashes.size !== fileStats.size || hashes.mode !== fileStats.mode) {
throw new Error(`Package source changed while it was being scanned: ${packagePath}`);
}
const isExecutable = isExecutablePackageFile(packagePath, hashes.mode);
if (isExecutable && !companionPaths.has(packagePath)) {
throw new Error(`Executable file is not declared as a companion: ${packagePath}`);
}
const companion = companionPaths.get(packagePath);
if (companion && companion.sha256 !== hashes.sha256) {
throw new Error(`Companion SHA-256 mismatch: ${packagePath}`);
}
files.push({
absolutePath,
packagePath,
size: fileStats.size,
executable: Boolean(companion),
crc32: hashes.crc32,
sha256: hashes.sha256,
});
}
}
await visit(pluginDirectory, "");
const packagedPaths = new Set(files.map(({ packagePath }) => packagePath));
const requiredPaths = [
"netcatty.plugin.json",
manifest.main.browser,
manifest.main.node,
...(manifest.contributes?.views ?? []).map(({ entry }) => entry),
...companionPaths.keys(),
].filter((entryPath): entryPath is string => Boolean(entryPath));
for (const requiredPath of requiredPaths) {
if (!packagedPaths.has(requiredPath)) {
throw new Error(`Manifest references a missing package file: ${requiredPath}`);
}
}
return files.sort(sortPackagePaths);
}
function makeLocalHeader(file: ScannedFile): Buffer {
const name = Buffer.from(file.packagePath, "utf8");
const header = Buffer.alloc(30 + name.byteLength);
header.writeUInt32LE(0x04034b50, 0);
header.writeUInt16LE(20, 4);
header.writeUInt16LE(0x0800, 6);
header.writeUInt16LE(0, 8);
header.writeUInt16LE(0, 10);
header.writeUInt16LE(33, 12);
header.writeUInt32LE(file.crc32, 14);
header.writeUInt32LE(file.size, 18);
header.writeUInt32LE(file.size, 22);
header.writeUInt16LE(name.byteLength, 26);
header.writeUInt16LE(0, 28);
name.copy(header, 30);
return header;
}
function makeCentralHeader(file: ScannedFile, localOffset: number): Buffer {
const name = Buffer.from(file.packagePath, "utf8");
const header = Buffer.alloc(46 + name.byteLength);
header.writeUInt32LE(0x02014b50, 0);
header.writeUInt16LE(0x0314, 4);
header.writeUInt16LE(20, 6);
header.writeUInt16LE(0x0800, 8);
header.writeUInt16LE(0, 10);
header.writeUInt16LE(0, 12);
header.writeUInt16LE(33, 14);
header.writeUInt32LE(file.crc32, 16);
header.writeUInt32LE(file.size, 20);
header.writeUInt32LE(file.size, 24);
header.writeUInt16LE(name.byteLength, 28);
header.writeUInt16LE(0, 30);
header.writeUInt16LE(0, 32);
header.writeUInt16LE(0, 34);
header.writeUInt16LE(0, 36);
const mode = file.executable ? 0o100755 : 0o100644;
header.writeUInt32LE((mode << 16) >>> 0, 38);
header.writeUInt32LE(localOffset, 42);
name.copy(header, 46);
return header;
}
function makeEndOfCentralDirectory(
entryCount: number,
centralSize: number,
centralOffset: number,
): Buffer {
const footer = Buffer.alloc(22);
footer.writeUInt32LE(0x06054b50, 0);
footer.writeUInt16LE(0, 4);
footer.writeUInt16LE(0, 6);
footer.writeUInt16LE(entryCount, 8);
footer.writeUInt16LE(entryCount, 10);
footer.writeUInt32LE(centralSize, 12);
footer.writeUInt32LE(centralOffset, 16);
footer.writeUInt16LE(0, 20);
return footer;
}
async function writeBuffer(output: ReturnType<typeof createWriteStream>, buffer: Buffer) {
if (!output.write(buffer)) await once(output, "drain");
}
async function writeArchive(files: readonly ScannedFile[], outputPath: string): Promise<void> {
await mkdir(path.dirname(outputPath), { recursive: true });
const temporaryPath = `${outputPath}.tmp-${process.pid}-${randomUUID()}`;
const output = createWriteStream(temporaryPath, { flags: "wx", mode: 0o600 });
const centralHeaders: Buffer[] = [];
let offset = 0;
try {
await once(output, "open");
for (const file of files) {
const localHeader = makeLocalHeader(file);
centralHeaders.push(makeCentralHeader(file, offset));
await writeBuffer(output, localHeader);
offset += localHeader.byteLength;
const sha256 = createHash("sha256");
let crc = 0xffffffff;
let writtenBytes = 0;
const input = await open(
file.absolutePath,
constants.O_RDONLY | ("O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0),
);
try {
const inputStats = await input.stat();
if (!inputStats.isFile() || inputStats.size !== file.size) {
throw new Error(`Package source changed before archive write: ${file.packagePath}`);
}
const stream = createReadStream(file.absolutePath, { fd: input.fd, autoClose: false });
for await (const chunk of stream) {
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
writtenBytes += buffer.byteLength;
sha256.update(buffer);
crc = updateCrc32(crc, buffer);
await writeBuffer(output, buffer);
offset += buffer.byteLength;
}
} finally {
await input.close();
}
if (
writtenBytes !== file.size
|| ((crc ^ 0xffffffff) >>> 0) !== file.crc32
|| sha256.digest("hex") !== file.sha256
) {
throw new Error(`Package source changed while it was being written: ${file.packagePath}`);
}
}
const centralOffset = offset;
for (const centralHeader of centralHeaders) {
await writeBuffer(output, centralHeader);
offset += centralHeader.byteLength;
}
await writeBuffer(
output,
makeEndOfCentralDirectory(files.length, offset - centralOffset, centralOffset),
);
output.end();
await once(output, "close");
const archiveStats = await stat(temporaryPath);
if (archiveStats.size > PACKAGE_LIMITS.archiveBytes) {
throw new Error(`Plugin archive exceeds ${PACKAGE_LIMITS.archiveBytes} bytes`);
}
await rename(temporaryPath, outputPath);
} catch (error) {
output.destroy();
await rm(temporaryPath, { force: true });
throw error;
}
}
export async function buildPluginPackage(
pluginDirectory: string,
outputPath: string,
): Promise<PackageBuildResult> {
const sourceDirectory = path.resolve(pluginDirectory);
const resolvedOutputPath = path.resolve(outputPath);
if (!resolvedOutputPath.endsWith(".ncpkg")) {
throw new Error("Plugin package output must use the .ncpkg extension");
}
const manifest = await readAndValidateManifest(sourceDirectory);
const files = await scanPackageDirectory(sourceDirectory, manifest);
await writeArchive(files, resolvedOutputPath);
const outputStats = await stat(resolvedOutputPath);
const archiveHash = await hashFile(resolvedOutputPath);
return {
outputPath: resolvedOutputPath,
fileCount: files.length,
uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0),
archiveBytes: outputStats.size,
sha256: archiveHash.sha256,
};
}
export async function validatePluginDirectory(
pluginDirectory: string,
): Promise<PluginDirectoryValidationResult> {
const sourceDirectory = path.resolve(pluginDirectory);
const manifest = await readAndValidateManifest(sourceDirectory);
const files = await scanPackageDirectory(sourceDirectory, manifest);
return {
manifest,
fileCount: files.length,
uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0),
};
}
function openZip(filePath: string): Promise<ZipFile> {
return new Promise((resolve, reject) => {
yauzl.open(
filePath,
{ lazyEntries: true, decodeStrings: true, strictFileNames: true, validateEntrySizes: true },
(error, zipFile) => {
if (error || !zipFile) reject(error ?? new Error("Unable to open plugin archive"));
else resolve(zipFile);
},
);
});
}
interface ReadArchiveEntryResult {
readonly bytes: number;
readonly crc32: number;
readonly sha256: string;
readonly contents?: Buffer;
}
function readEntry(
zipFile: ZipFile,
entry: Entry,
captureContents: boolean,
): Promise<ReadArchiveEntryResult> {
return new Promise((resolve, reject) => {
zipFile.openReadStream(entry, (error, stream) => {
if (error || !stream) {
reject(error ?? new Error(`Unable to read archive entry: ${entry.fileName}`));
return;
}
const chunks: Buffer[] = [];
const sha256 = createHash("sha256");
let crc = 0xffffffff;
let bytes = 0;
stream.on("data", (chunk: Buffer) => {
const buffer = Buffer.from(chunk);
bytes += chunk.byteLength;
if (bytes > PACKAGE_LIMITS.singleFileBytes) {
stream.destroy(new Error(`Plugin file exceeds size limit: ${entry.fileName}`));
return;
}
sha256.update(buffer);
crc = updateCrc32(crc, buffer);
if (captureContents) chunks.push(buffer);
});
stream.once("error", reject);
stream.once("end", () => resolve({
bytes,
crc32: (crc ^ 0xffffffff) >>> 0,
sha256: sha256.digest("hex"),
contents: captureContents ? Buffer.concat(chunks) : undefined,
}));
});
});
}
export async function validatePluginPackage(
archivePath: string,
): Promise<PackageValidationResult> {
const archiveStats = await stat(archivePath);
if (archiveStats.size > PACKAGE_LIMITS.archiveBytes) {
throw new Error(`Plugin archive exceeds ${PACKAGE_LIMITS.archiveBytes} bytes`);
}
const zipFile = await openZip(archivePath);
const registry = new PackagePathRegistry();
const entries = new Map<string, { contents?: Buffer; mode: number; sha256: string }>();
let totalBytes = 0;
await new Promise<void>((resolve, reject) => {
const fail = (error: unknown) => {
zipFile.close();
reject(error);
};
zipFile.once("error", fail);
zipFile.once("end", resolve);
zipFile.on("entry", (entry: Entry) => {
void (async () => {
try {
const packagePath = registry.add(entry.fileName);
if (entries.size + 1 > PACKAGE_LIMITS.fileCount) {
throw new Error(`Plugin package exceeds ${PACKAGE_LIMITS.fileCount} files`);
}
if ((entry.generalPurposeBitFlag & 1) !== 0) {
throw new Error(`Encrypted ZIP entries are not allowed: ${packagePath}`);
}
if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
throw new Error(`Unsupported ZIP compression method: ${packagePath}`);
}
const mode = (entry.externalFileAttributes >>> 16) & 0xffff;
const fileType = mode & 0o170000;
if (fileType !== 0 && fileType !== 0o100000) {
throw new Error(`Only regular files are allowed: ${packagePath}`);
}
if (entry.uncompressedSize > PACKAGE_LIMITS.singleFileBytes) {
throw new Error(`Plugin file exceeds size limit: ${packagePath}`);
}
totalBytes += entry.uncompressedSize;
if (totalBytes > PACKAGE_LIMITS.uncompressedBytes) {
throw new Error("Plugin package exceeds the uncompressed size limit");
}
const result = await readEntry(
zipFile,
entry,
packagePath === "netcatty.plugin.json",
);
if (result.bytes !== entry.uncompressedSize || result.crc32 !== entry.crc32) {
throw new Error(`ZIP entry integrity check failed: ${packagePath}`);
}
entries.set(packagePath, {
contents: result.contents,
mode,
sha256: result.sha256,
});
zipFile.readEntry();
} catch (error) {
fail(error);
}
})();
});
zipFile.readEntry();
});
const manifestEntry = entries.get("netcatty.plugin.json");
if (!manifestEntry?.contents) throw new Error("Plugin package is missing netcatty.plugin.json");
if (manifestEntry.contents.byteLength > PACKAGE_LIMITS.manifestBytes) {
throw new Error("Plugin manifest exceeds the size limit");
}
let manifestValue: unknown;
try {
manifestValue = JSON.parse(manifestEntry.contents.toString("utf8"));
} catch (error) {
throw new Error(
`Plugin manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
);
}
const validation = validateManifestValue(manifestValue);
if (!validation.valid || !validation.manifest) {
throw new Error(`Plugin manifest is invalid:\n- ${validation.errors.join("\n- ")}`);
}
const manifest = validation.manifest;
const declaredCompanions = new Map(
(manifest.companionExecutables ?? []).map((companion) => [companion.path, companion]),
);
for (const [packagePath, entry] of entries) {
const isExecutable = isExecutablePackageFile(packagePath, entry.mode);
if (isExecutable && !declaredCompanions.has(packagePath)) {
throw new Error(`Executable file is not declared as a companion: ${packagePath}`);
}
}
const requiredPaths = [
manifest.main.browser,
manifest.main.node,
...(manifest.contributes?.views ?? []).map(({ entry }) => entry),
].filter((entryPath): entryPath is string => Boolean(entryPath));
for (const requiredPath of requiredPaths) {
if (!entries.has(requiredPath)) {
throw new Error(`Manifest references a missing package file: ${requiredPath}`);
}
}
for (const [companionPath, companion] of declaredCompanions) {
const entry = entries.get(companionPath);
if (!entry) throw new Error(`Manifest references a missing companion: ${companionPath}`);
if (entry.sha256 !== companion.sha256) {
throw new Error(`Companion SHA-256 mismatch: ${companionPath}`);
}
}
return { manifest, fileCount: entries.size, uncompressedBytes: totalBytes };
}
+173
View File
@@ -0,0 +1,173 @@
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import {
mkdir,
mkdtemp,
readFile,
rm,
symlink,
writeFile,
} from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import test from "node:test";
import { buildPluginPackage, validatePluginPackage } from "./archive.ts";
import { PACKAGE_LIMITS } from "./constants.ts";
import { initPlugin } from "./commands.ts";
import { readAndValidateManifest, validateManifestValue } from "./manifest.ts";
import { assertSafePackagePath, PackagePathRegistry } from "./packagePath.ts";
function manifest(overrides: Record<string, unknown> = {}) {
return {
manifestVersion: 1,
id: "com.example.package-test",
name: "package-test",
version: "1.0.0",
publisher: "example",
engines: { netcatty: ">=1.0.0", api: "0.1.0-internal" },
main: { browser: "dist/index.js" },
...overrides,
};
}
async function createPlugin(root: string): Promise<string> {
const directory = path.join(root, "plugin");
await mkdir(path.join(directory, "dist"), { recursive: true });
await Promise.all([
writeFile(
path.join(directory, "netcatty.plugin.json"),
`${JSON.stringify(manifest(), null, 2)}\n`,
),
writeFile(path.join(directory, "dist/index.js"), "export default {};\n"),
writeFile(path.join(directory, "README.md"), "# Package test\n"),
]);
return directory;
}
test("path validation rejects traversal, platform aliases, and duplicates", () => {
for (const unsafe of ["../escape", "/absolute", "C:/drive", "a\\b", "a/../b", "CON", "a//b"]) {
assert.throws(() => assertSafePackagePath(unsafe));
}
const registry = new PackagePathRegistry();
registry.add("dist/Plugin.js");
assert.throws(() => registry.add("dist/plugin.js"), /case-colliding/);
});
test("manifest validation reports permission and contribution mistakes", () => {
const result = validateManifestValue(manifest({
permissions: { required: ["network"], optional: ["network"] },
contributes: {
commands: [{ id: "package.run", title: "Run" }],
menus: [{ command: "package.missing", location: "commandPalette" }],
},
}));
assert.equal(result.valid, false);
assert.match(result.errors.join("\n"), /both required and optional/);
assert.match(result.errors.join("\n"), /undeclared command/);
});
test("init creates a valid TypeScript plugin skeleton", async (context) => {
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-init-"));
context.after(() => rm(root, { recursive: true, force: true }));
const directory = path.join(root, "created");
await initPlugin(directory, { id: "com.example.created", name: "Created" });
const createdManifest = await readAndValidateManifest(directory);
assert.equal(createdManifest.id, "com.example.created");
assert.match(await readFile(path.join(directory, "src/index.ts"), "utf8"), /definePlugin/);
});
test("packing is deterministic and the archive validates", async (context) => {
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-pack-"));
context.after(() => rm(root, { recursive: true, force: true }));
const directory = await createPlugin(root);
const first = path.join(root, "first.ncpkg");
const second = path.join(root, "second.ncpkg");
const firstResult = await buildPluginPackage(directory, first);
await buildPluginPackage(directory, second);
const firstBytes = await readFile(first);
const secondBytes = await readFile(second);
assert.deepEqual(firstBytes, secondBytes);
assert.equal(
firstResult.sha256,
createHash("sha256").update(firstBytes).digest("hex"),
);
const validation = await validatePluginPackage(first);
assert.equal(validation.manifest.id, "com.example.package-test");
assert.equal(validation.fileCount, 3);
});
test("archive validation rejects duplicate names and CRC corruption", async (context) => {
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-archive-safety-"));
context.after(() => rm(root, { recursive: true, force: true }));
const directory = await createPlugin(root);
await Promise.all([
writeFile(path.join(directory, "a.txt"), "first\n"),
writeFile(path.join(directory, "b.txt"), "second\n"),
]);
const validPath = path.join(root, "valid.ncpkg");
await buildPluginPackage(directory, validPath);
const validBytes = await readFile(validPath);
const duplicateBytes = Buffer.from(validBytes);
const originalName = Buffer.from("b.txt");
const duplicateName = Buffer.from("a.txt");
let replacements = 0;
for (let offset = duplicateBytes.indexOf(originalName); offset !== -1;) {
duplicateName.copy(duplicateBytes, offset);
replacements += 1;
offset = duplicateBytes.indexOf(originalName, offset + originalName.byteLength);
}
assert.equal(replacements, 2, "ZIP should contain the local and central entry names");
const duplicatePath = path.join(root, "duplicate.ncpkg");
await writeFile(duplicatePath, duplicateBytes);
await assert.rejects(validatePluginPackage(duplicatePath), /Duplicate or case-colliding/);
const corruptedBytes = Buffer.from(validBytes);
const content = Buffer.from("# Package test\n");
const contentOffset = corruptedBytes.indexOf(content);
assert.notEqual(contentOffset, -1);
corruptedBytes[contentOffset] ^= 0x01;
const corruptedPath = path.join(root, "corrupted.ncpkg");
await writeFile(corruptedPath, corruptedBytes);
await assert.rejects(validatePluginPackage(corruptedPath), /integrity check failed/);
});
test("packer rejects symbolic links and undeclared executables", async (context) => {
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-safety-"));
context.after(() => rm(root, { recursive: true, force: true }));
const directory = await createPlugin(root);
await assert.rejects(
buildPluginPackage(directory, path.join(root, "wrong-extension.zip")),
/\.ncpkg extension/,
);
if (process.platform !== "win32") {
await symlink("README.md", path.join(directory, "linked-readme"));
await assert.rejects(
buildPluginPackage(directory, path.join(root, "symlink.ncpkg")),
/Symbolic links/,
);
await rm(path.join(directory, "linked-readme"));
}
await mkdir(path.join(directory, "bin"));
const executablePath = path.join(directory, "bin/tool.exe");
await writeFile(executablePath, "not-a-real-executable\n");
await assert.rejects(
buildPluginPackage(directory, path.join(root, "executable.ncpkg")),
/not declared as a companion/,
);
});
test("manifest byte limit is enforced before JSON parsing", async (context) => {
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-limit-"));
context.after(() => rm(root, { recursive: true, force: true }));
await writeFile(
path.join(root, "netcatty.plugin.json"),
`{"padding":"${"x".repeat(PACKAGE_LIMITS.manifestBytes)}"}`,
);
await assert.rejects(readAndValidateManifest(root), /manifest exceeds/);
});
+64
View File
@@ -0,0 +1,64 @@
#!/usr/bin/env node
import process from "node:process";
import { buildPlugin, initPlugin, packPlugin, validateTarget } from "./commands.js";
const USAGE = `Netcatty plugin CLI (API 0.1.0-internal)
Usage:
netcatty-plugin init <directory> --id <reverse.dns.id> [--name <display name>]
netcatty-plugin validate <directory|package.ncpkg>
netcatty-plugin build <directory>
netcatty-plugin pack <directory> [--out <package.ncpkg>]
`;
function optionValue(args: readonly string[], name: string): string | undefined {
const index = args.indexOf(name);
if (index === -1) return undefined;
const value = args[index + 1];
if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}`);
return value;
}
async function main(args: readonly string[]): Promise<void> {
const [command, target] = args;
if (!command || command === "help" || command === "--help" || command === "-h") {
process.stdout.write(USAGE);
return;
}
if (!target) throw new Error(`Missing target for ${command}`);
if (command === "init") {
const id = optionValue(args, "--id");
if (!id) throw new Error("init requires --id <reverse.dns.id>");
const directory = await initPlugin(target, { id, name: optionValue(args, "--name") });
process.stdout.write(`Initialized plugin in ${directory}\n`);
return;
}
if (command === "validate") {
const result = await validateTarget(target);
process.stdout.write(
`Valid ${result.kind}: ${result.manifest.id}@${result.manifest.version}\n`,
);
return;
}
if (command === "build") {
await buildPlugin(target);
process.stdout.write("Plugin build completed.\n");
return;
}
if (command === "pack") {
const result = await packPlugin(target, optionValue(args, "--out"));
process.stdout.write(
`Packed ${result.fileCount} files to ${result.outputPath}\nSHA-256 ${result.sha256}\n`,
);
return;
}
throw new Error(`Unknown command: ${command}`);
}
main(process.argv.slice(2)).catch((error: unknown) => {
process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
process.exitCode = 1;
});
+136
View File
@@ -0,0 +1,136 @@
import { spawn } from "node:child_process";
import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import type { PluginManifest } from "@netcatty/plugin-contract";
import {
buildPluginPackage,
validatePluginDirectory,
validatePluginPackage,
} from "./archive.js";
import { readAndValidateManifest } from "./manifest.js";
export interface InitPluginOptions {
readonly id: string;
readonly name?: string;
}
export async function initPlugin(
targetDirectory: string,
options: InitPluginOptions,
): Promise<string> {
const directory = path.resolve(targetDirectory);
await mkdir(directory, { recursive: true });
const existingEntries = await readdir(directory);
if (existingEntries.length > 0) {
throw new Error(`Target directory is not empty: ${directory}`);
}
const displayName = options.name?.trim() || options.id.split(".").at(-1) || options.id;
const packageName = options.id.replaceAll(".", "-");
const manifest: PluginManifest = {
$schema: "https://netcatty.com/schemas/plugins/0.1.0-internal/plugin-contract.schema.json",
manifestVersion: 1,
id: options.id,
name: displayName,
displayName,
description: "A Netcatty plugin",
version: "0.1.0",
publisher: options.id.split(".")[0] || "local",
engines: {
netcatty: ">=0.0.0",
api: "0.1.0-internal",
},
main: { browser: "dist/index.js" },
activationEvents: ["onStartupFinished"],
permissions: { required: [], optional: [] },
};
await mkdir(path.join(directory, "src"), { recursive: true });
await Promise.all([
writeFile(
path.join(directory, "netcatty.plugin.json"),
`${JSON.stringify(manifest, null, 2)}\n`,
"utf8",
),
writeFile(
path.join(directory, "package.json"),
`${JSON.stringify({
name: packageName,
version: "0.1.0",
private: true,
type: "module",
scripts: { build: "tsc -p tsconfig.json" },
dependencies: { "@netcatty/plugin-sdk": "0.1.0-internal" },
devDependencies: { typescript: "^5.9.0" },
}, null, 2)}\n`,
"utf8",
),
writeFile(
path.join(directory, "tsconfig.json"),
`${JSON.stringify({
compilerOptions: {
target: "ES2022",
module: "ESNext",
moduleResolution: "Bundler",
strict: true,
declaration: true,
rootDir: "src",
outDir: "dist",
},
include: ["src/**/*.ts"],
}, null, 2)}\n`,
"utf8",
),
writeFile(
path.join(directory, "src/index.ts"),
`import { definePlugin } from "@netcatty/plugin-sdk";\n\nexport default definePlugin({\n activate(context) {\n context.logger.info("${displayName} activated");\n },\n});\n`,
"utf8",
),
]);
await readAndValidateManifest(directory);
return directory;
}
export async function validateTarget(target: string) {
const resolved = path.resolve(target);
const targetStats = await stat(resolved);
if (targetStats.isDirectory()) {
const result = await validatePluginDirectory(resolved);
return { kind: "directory" as const, ...result };
}
if (targetStats.isFile() && resolved.endsWith(".ncpkg")) {
const result = await validatePluginPackage(resolved);
return { kind: "package" as const, ...result };
}
throw new Error("Validation target must be a plugin directory or .ncpkg file");
}
export async function buildPlugin(pluginDirectory: string): Promise<void> {
const directory = path.resolve(pluginDirectory);
await readAndValidateManifest(directory);
const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
await new Promise<void>((resolve, reject) => {
const child = spawn(npmCommand, ["run", "build", "--if-present"], {
cwd: directory,
env: process.env,
shell: false,
stdio: "inherit",
windowsHide: true,
});
child.once("error", reject);
child.once("exit", (code, signal) => {
if (code === 0) resolve();
else reject(new Error(`Plugin build failed (${signal ?? `exit ${String(code)}`})`));
});
});
await validatePluginDirectory(directory);
}
export async function packPlugin(pluginDirectory: string, outputPath?: string) {
const directory = path.resolve(pluginDirectory);
const manifest = await readAndValidateManifest(directory);
const resolvedOutput = outputPath
? path.resolve(outputPath)
: path.join(path.dirname(directory), `${manifest.id}-${manifest.version}.ncpkg`);
return buildPluginPackage(directory, resolvedOutput);
}
+14
View File
@@ -0,0 +1,14 @@
export const PACKAGE_LIMITS = Object.freeze({
archiveBytes: 100 * 1024 * 1024,
uncompressedBytes: 250 * 1024 * 1024,
singleFileBytes: 50 * 1024 * 1024,
manifestBytes: 1024 * 1024,
fileCount: 5_000,
pathBytes: 512,
});
export const IGNORED_ROOT_ENTRIES = new Set([
".DS_Store",
".git",
"node_modules",
]);
+22
View File
@@ -0,0 +1,22 @@
export { PACKAGE_LIMITS } from "./constants.js";
export {
buildPluginPackage,
validatePluginDirectory,
validatePluginPackage,
type PackageBuildResult,
type PackageValidationResult,
type PluginDirectoryValidationResult,
} from "./archive.js";
export {
buildPlugin,
initPlugin,
packPlugin,
validateTarget,
type InitPluginOptions,
} from "./commands.js";
export {
readAndValidateManifest,
validateManifestValue,
type ManifestValidationResult,
} from "./manifest.js";
export { assertSafePackagePath, PackagePathRegistry } from "./packagePath.js";
+144
View File
@@ -0,0 +1,144 @@
import { createRequire } from "node:module";
import { readFile } from "node:fs/promises";
import path from "node:path";
import type {
PermissionDeclaration,
PluginManifest,
PluginPermission,
} from "@netcatty/plugin-contract";
import Ajv2020, { type ErrorObject } from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import { PACKAGE_LIMITS } from "./constants.js";
import { assertSafePackagePath } from "./packagePath.js";
const require = createRequire(import.meta.url);
const schemaPath = require.resolve(
"@netcatty/plugin-contract/schema/plugin-contract.schema.json",
);
const contractSchema = JSON.parse(await readFile(schemaPath, "utf8")) as object;
const ajv = new Ajv2020({ allErrors: true, strict: true });
addFormats(ajv);
const validateSchema = ajv.compile<PluginManifest>(contractSchema);
export interface ManifestValidationResult {
readonly valid: boolean;
readonly manifest?: PluginManifest;
readonly errors: readonly string[];
}
function formatAjvError(error: ErrorObject): string {
const location = error.instancePath || "/";
return `${location} ${error.message ?? "is invalid"}`;
}
function permissionName(declaration: PermissionDeclaration): PluginPermission {
return typeof declaration === "string" ? declaration : declaration.permission;
}
function findDuplicateIds(manifest: PluginManifest): string[] {
const errors: string[] = [];
const groups = [
["settings", manifest.contributes?.settings],
["commands", manifest.contributes?.commands],
["views", manifest.contributes?.views],
["providers", manifest.contributes?.providers],
["companionExecutables", manifest.companionExecutables],
] as const;
for (const [groupName, contributions] of groups) {
const ids = new Set<string>();
for (const contribution of contributions ?? []) {
if (ids.has(contribution.id)) {
errors.push(`Duplicate ${groupName} id: ${contribution.id}`);
}
ids.add(contribution.id);
}
}
return errors;
}
function validateSemantics(manifest: PluginManifest): string[] {
const errors = findDuplicateIds(manifest);
const requiredPermissions = new Set(
(manifest.permissions?.required ?? []).map(permissionName),
);
for (const declaration of manifest.permissions?.optional ?? []) {
const permission = permissionName(declaration);
if (requiredPermissions.has(permission)) {
errors.push(`Permission cannot be both required and optional: ${permission}`);
}
}
const commandIds = new Set((manifest.contributes?.commands ?? []).map(({ id }) => id));
for (const menu of manifest.contributes?.menus ?? []) {
if (!commandIds.has(menu.command)) {
errors.push(`Menu references an undeclared command: ${menu.command}`);
}
}
for (const setting of manifest.contributes?.settings ?? []) {
if (setting.secret && setting.default !== undefined) {
errors.push(`Secret setting must not declare a default value: ${setting.id}`);
}
if (["select", "multiselect"].includes(setting.control) && !setting.options?.length) {
errors.push(`${setting.control} setting requires options: ${setting.id}`);
}
if (setting.control === "number" && setting.minimum !== undefined
&& setting.maximum !== undefined && setting.minimum > setting.maximum) {
errors.push(`Number setting minimum exceeds maximum: ${setting.id}`);
}
}
for (const entryPath of [
manifest.main.browser,
manifest.main.node,
...(manifest.contributes?.views ?? []).map(({ entry }) => entry),
...(manifest.companionExecutables ?? []).map(({ path: companionPath }) => companionPath),
]) {
if (entryPath) {
try {
assertSafePackagePath(entryPath);
} catch (error) {
errors.push(error instanceof Error ? error.message : String(error));
}
}
}
return errors;
}
export function validateManifestValue(value: unknown): ManifestValidationResult {
if (!validateSchema(value)) {
return {
valid: false,
errors: (validateSchema.errors ?? []).map(formatAjvError),
};
}
const semanticErrors = validateSemantics(value);
return semanticErrors.length === 0
? { valid: true, manifest: value, errors: [] }
: { valid: false, errors: semanticErrors };
}
export async function readAndValidateManifest(
pluginDirectory: string,
): Promise<PluginManifest> {
const manifestPath = path.join(pluginDirectory, "netcatty.plugin.json");
const contents = await readFile(manifestPath);
if (contents.byteLength > PACKAGE_LIMITS.manifestBytes) {
throw new Error(`Plugin manifest exceeds ${PACKAGE_LIMITS.manifestBytes} bytes`);
}
let value: unknown;
try {
value = JSON.parse(contents.toString("utf8"));
} catch (error) {
throw new Error(
`Plugin manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
);
}
const result = validateManifestValue(value);
if (!result.valid || !result.manifest) {
throw new Error(`Plugin manifest is invalid:\n- ${result.errors.join("\n- ")}`);
}
return result.manifest;
}
+52
View File
@@ -0,0 +1,52 @@
import { PACKAGE_LIMITS } from "./constants.js";
const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
const WINDOWS_SPECIAL = /[<>:"|?*]/;
function containsControlCharacter(value: string): boolean {
return [...value].some((character) => character.charCodeAt(0) <= 0x1f);
}
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)}`);
}
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}`);
}
}
return input;
}
export class PackagePathRegistry {
readonly #exact = new Set<string>();
readonly #portable = new Set<string>();
add(input: string): string {
const safePath = assertSafePackagePath(input);
const portableKey = safePath.toLowerCase();
if (this.#exact.has(safePath) || this.#portable.has(portableKey)) {
throw new Error(`Duplicate or case-colliding package path: ${safePath}`);
}
this.#exact.add(safePath);
this.#portable.add(portableKey);
return safePath;
}
}