mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-20 15:19:16 +00:00
feat(plugins): add plugin contract and SDK
This commit is contained in:
1 parent
b66fea9fd0
commit
2a8dba4818
32 files changed
+4200
-33
No files matched your search
@@ -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 };
|
||||
}
|
||||
@@ -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/);
|
||||
});
|
||||
@@ -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;
|
||||
});
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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",
|
||||
]);
|
||||
@@ -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";
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user