mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-20 23:20:46 +00:00
feat(plugins): add isolated plugin host runtime (#2303)
* feat(plugins): add isolated plugin host runtime * test(plugins): build runtime dependencies before tests * fix(plugins): harden runtime lifecycle and recovery * fix(plugins): harden runtime extension boundaries * fix(plugins): enforce runtime integrity boundaries * fix(plugins): await utility process exit * fix(plugins): harden utility process containment * fix(plugins): close runtime recovery gaps * fix(plugins): harden runtime lifecycle boundaries
This commit is contained in:
1 parent
9b1bb94a25
commit
7a47187e37
83 files changed
+10646
-225
No files matched your search
@@ -1,6 +1,7 @@
|
||||
import { createHash, randomUUID } from "node:crypto";
|
||||
import { constants, createReadStream, createWriteStream } from "node:fs";
|
||||
import {
|
||||
chmod,
|
||||
lstat,
|
||||
mkdir,
|
||||
open,
|
||||
@@ -63,12 +64,14 @@ export interface PackageBuildResult {
|
||||
readonly uncompressedBytes: number;
|
||||
readonly archiveBytes: number;
|
||||
readonly sha256: string;
|
||||
readonly contentSha256: string;
|
||||
}
|
||||
|
||||
export interface PackageValidationResult {
|
||||
readonly manifest: PluginManifest;
|
||||
readonly fileCount: number;
|
||||
readonly uncompressedBytes: number;
|
||||
readonly contentSha256: string;
|
||||
}
|
||||
|
||||
export type PluginDirectoryValidationResult = PackageValidationResult;
|
||||
@@ -129,6 +132,40 @@ function sortPackagePaths(left: ScannedFile, right: ScannedFile): number {
|
||||
return Buffer.compare(Buffer.from(left.packagePath), Buffer.from(right.packagePath));
|
||||
}
|
||||
|
||||
interface PackageContentIdentity {
|
||||
readonly packagePath: string;
|
||||
readonly size: number;
|
||||
readonly sha256: string;
|
||||
readonly executable: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hash the logical package contents instead of the ZIP representation. This
|
||||
* keeps integrity checks stable across valid ZIP encoders and compression
|
||||
* choices while binding every path, byte length, executable bit, and file
|
||||
* digest into one versioned identity.
|
||||
*/
|
||||
export function computePackageContentSha256(
|
||||
entries: readonly PackageContentIdentity[],
|
||||
): string {
|
||||
const hash = createHash("sha256");
|
||||
hash.update("netcatty-plugin-content-v1\0", "utf8");
|
||||
const ordered = [...entries].sort((left, right) => (
|
||||
Buffer.compare(Buffer.from(left.packagePath), Buffer.from(right.packagePath))
|
||||
));
|
||||
for (const entry of ordered) {
|
||||
const packagePath = Buffer.from(entry.packagePath, "utf8");
|
||||
const header = Buffer.allocUnsafe(13);
|
||||
header.writeUInt32BE(packagePath.byteLength, 0);
|
||||
header.writeBigUInt64BE(BigInt(entry.size), 4);
|
||||
header.writeUInt8(entry.executable ? 1 : 0, 12);
|
||||
hash.update(header);
|
||||
hash.update(packagePath);
|
||||
hash.update(Buffer.from(entry.sha256, "hex"));
|
||||
}
|
||||
return hash.digest("hex");
|
||||
}
|
||||
|
||||
function isExecutablePackageFile(packagePath: string, mode: number): boolean {
|
||||
return (mode & 0o111) !== 0
|
||||
|| EXECUTABLE_EXTENSIONS.has(path.posix.extname(packagePath).toLowerCase());
|
||||
@@ -169,6 +206,7 @@ async function resolveThroughExistingAncestor(targetPath: string): Promise<strin
|
||||
async function scanPackageDirectory(
|
||||
pluginDirectory: string,
|
||||
manifestSource: ValidatedManifestSource,
|
||||
options: { allowIgnoredRootEntries?: boolean } = {},
|
||||
): Promise<ScannedFile[]> {
|
||||
const { manifest } = manifestSource;
|
||||
const registry = new PackagePathRegistry();
|
||||
@@ -189,6 +227,9 @@ async function scanPackageDirectory(
|
||||
relativeDirectory === ""
|
||||
&& (IGNORED_ROOT_ENTRIES.has(entry.name) || entry.name.endsWith(".ncpkg"))
|
||||
) {
|
||||
if (options.allowIgnoredRootEntries === false) {
|
||||
throw new Error(`Installed plugin contains an unpackaged root entry: ${entry.name}`);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
const relativePath = relativeDirectory
|
||||
@@ -430,19 +471,22 @@ export async function buildPluginPackage(
|
||||
uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0),
|
||||
archiveBytes: outputStats.size,
|
||||
sha256: archiveHash.sha256,
|
||||
contentSha256: computePackageContentSha256(files),
|
||||
};
|
||||
}
|
||||
|
||||
export async function validatePluginDirectory(
|
||||
pluginDirectory: string,
|
||||
options: { allowIgnoredRootEntries?: boolean } = {},
|
||||
): Promise<PluginDirectoryValidationResult> {
|
||||
const sourceDirectory = path.resolve(pluginDirectory);
|
||||
const manifestSource = await readValidatedManifestSource(sourceDirectory);
|
||||
const files = await scanPackageDirectory(sourceDirectory, manifestSource);
|
||||
const files = await scanPackageDirectory(sourceDirectory, manifestSource, options);
|
||||
return {
|
||||
manifest: manifestSource.manifest,
|
||||
fileCount: files.length,
|
||||
uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0),
|
||||
contentSha256: computePackageContentSha256(files),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -536,45 +580,66 @@ async function validateLocalFileHeader(
|
||||
}
|
||||
}
|
||||
|
||||
function readEntry(
|
||||
async function readEntry(
|
||||
zipFile: ZipFile,
|
||||
entry: Entry,
|
||||
captureContents: boolean,
|
||||
outputPath?: string,
|
||||
): Promise<ReadArchiveEntryResult> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const stream = await new Promise<NodeJS.ReadableStream>((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,
|
||||
}));
|
||||
resolve(stream);
|
||||
});
|
||||
});
|
||||
const chunks: Buffer[] = [];
|
||||
const sha256 = createHash("sha256");
|
||||
let crc = 0xffffffff;
|
||||
let bytes = 0;
|
||||
let outputHandle;
|
||||
try {
|
||||
if (outputPath) {
|
||||
await mkdir(path.dirname(outputPath), { recursive: true, mode: 0o700 });
|
||||
outputHandle = await open(outputPath, "wx", 0o600);
|
||||
}
|
||||
for await (const chunk of stream) {
|
||||
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
|
||||
bytes += buffer.byteLength;
|
||||
if (bytes > PACKAGE_LIMITS.singleFileBytes) {
|
||||
throw new Error(`Plugin file exceeds size limit: ${entry.fileName}`);
|
||||
}
|
||||
sha256.update(buffer);
|
||||
crc = updateCrc32(crc, buffer);
|
||||
if (captureContents) chunks.push(buffer);
|
||||
if (outputHandle) {
|
||||
let written = 0;
|
||||
while (written < buffer.length) {
|
||||
const result = await outputHandle.write(buffer, written, buffer.length - written);
|
||||
if (result.bytesWritten === 0) {
|
||||
throw new Error(`Unable to extract the complete archive entry: ${entry.fileName}`);
|
||||
}
|
||||
written += result.bytesWritten;
|
||||
}
|
||||
}
|
||||
}
|
||||
if (outputHandle) await outputHandle.sync();
|
||||
return {
|
||||
bytes,
|
||||
crc32: (crc ^ 0xffffffff) >>> 0,
|
||||
sha256: sha256.digest("hex"),
|
||||
contents: captureContents ? Buffer.concat(chunks) : undefined,
|
||||
};
|
||||
} finally {
|
||||
await outputHandle?.close();
|
||||
}
|
||||
}
|
||||
|
||||
export async function validatePluginPackage(
|
||||
async function inspectPluginPackage(
|
||||
archivePath: string,
|
||||
extractionDirectory?: string,
|
||||
): Promise<PackageValidationResult> {
|
||||
const archiveStats = await stat(archivePath);
|
||||
if (archiveStats.size > PACKAGE_LIMITS.archiveBytes) {
|
||||
@@ -582,7 +647,12 @@ export async function validatePluginPackage(
|
||||
}
|
||||
const zipFile = await openZip(archivePath);
|
||||
const registry = new PackagePathRegistry();
|
||||
const entries = new Map<string, { contents?: Buffer; mode: number; sha256: string }>();
|
||||
const entries = new Map<string, {
|
||||
contents?: Buffer;
|
||||
mode: number;
|
||||
sha256: string;
|
||||
size: number;
|
||||
}>();
|
||||
let totalBytes = 0;
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
@@ -628,6 +698,7 @@ export async function validatePluginPackage(
|
||||
zipFile,
|
||||
entry,
|
||||
packagePath === "netcatty.plugin.json",
|
||||
extractionDirectory ? path.join(extractionDirectory, ...packagePath.split("/")) : undefined,
|
||||
);
|
||||
if (result.bytes !== entry.uncompressedSize || result.crc32 !== entry.crc32) {
|
||||
throw new Error(`ZIP entry integrity check failed: ${packagePath}`);
|
||||
@@ -636,6 +707,7 @@ export async function validatePluginPackage(
|
||||
contents: result.contents,
|
||||
mode,
|
||||
sha256: result.sha256,
|
||||
size: result.bytes,
|
||||
});
|
||||
zipFile.readEntry();
|
||||
} catch (error) {
|
||||
@@ -680,5 +752,45 @@ export async function validatePluginPackage(
|
||||
throw new Error(`Companion SHA-256 mismatch: ${companionPath}`);
|
||||
}
|
||||
}
|
||||
return { manifest, fileCount: entries.size, uncompressedBytes: totalBytes };
|
||||
if (extractionDirectory) {
|
||||
for (const [packagePath] of entries) {
|
||||
await chmod(
|
||||
path.join(extractionDirectory, ...packagePath.split("/")),
|
||||
declaredCompanions.has(packagePath) ? 0o700 : 0o600,
|
||||
);
|
||||
}
|
||||
}
|
||||
const contentSha256 = computePackageContentSha256(
|
||||
[...entries].map(([packagePath, entry]) => ({
|
||||
packagePath,
|
||||
size: entry.size,
|
||||
sha256: entry.sha256,
|
||||
executable: declaredCompanions.has(packagePath),
|
||||
})),
|
||||
);
|
||||
return { manifest, fileCount: entries.size, uncompressedBytes: totalBytes, contentSha256 };
|
||||
}
|
||||
|
||||
export async function validatePluginPackage(
|
||||
archivePath: string,
|
||||
): Promise<PackageValidationResult> {
|
||||
return inspectPluginPackage(archivePath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates and extracts an immutable package snapshot into a new directory.
|
||||
* Failed or incomplete destinations are always removed so only callers that
|
||||
* receive a successful result can atomically publish the staged directory.
|
||||
*/
|
||||
export async function extractPluginPackage(
|
||||
archivePath: string,
|
||||
destinationDirectory: string,
|
||||
): Promise<PackageValidationResult> {
|
||||
await mkdir(destinationDirectory, { recursive: false, mode: 0o700 });
|
||||
try {
|
||||
return await inspectPluginPackage(archivePath, destinationDirectory);
|
||||
} catch (error) {
|
||||
await rm(destinationDirectory, { recursive: true, force: true });
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
@@ -20,7 +20,9 @@ import test from "node:test";
|
||||
import {
|
||||
assertManifestSnapshotMatches,
|
||||
buildPluginPackage,
|
||||
extractPluginPackage,
|
||||
hashFile,
|
||||
validatePluginDirectory,
|
||||
validatePluginPackage,
|
||||
} from "./archive.ts";
|
||||
import { checkPluginCompatibility } from "./compatibility.ts";
|
||||
@@ -100,6 +102,27 @@ function createZipEntry(
|
||||
return Buffer.concat([localHeader, encodedContents, centralHeader, end]);
|
||||
}
|
||||
|
||||
function replaceCentralEntryMode(archive: Buffer, entryName: string, mode: number): Buffer {
|
||||
const result = Buffer.from(archive);
|
||||
const endOffset = result.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
|
||||
if (endOffset < 0) throw new Error("Missing ZIP end record");
|
||||
const entryCount = result.readUInt16LE(endOffset + 10);
|
||||
let offset = result.readUInt32LE(endOffset + 16);
|
||||
for (let entry = 0; entry < entryCount; entry += 1) {
|
||||
if (result.readUInt32LE(offset) !== 0x02014b50) throw new Error("Invalid central ZIP entry");
|
||||
const nameLength = result.readUInt16LE(offset + 28);
|
||||
const extraLength = result.readUInt16LE(offset + 30);
|
||||
const commentLength = result.readUInt16LE(offset + 32);
|
||||
const name = result.subarray(offset + 46, offset + 46 + nameLength).toString("utf8");
|
||||
if (name === entryName) {
|
||||
result.writeUInt32LE((mode << 16) >>> 0, offset + 38);
|
||||
return result;
|
||||
}
|
||||
offset += 46 + nameLength + extraLength + commentLength;
|
||||
}
|
||||
throw new Error(`Missing central ZIP entry: ${entryName}`);
|
||||
}
|
||||
|
||||
function manifest(overrides: Record<string, unknown> = {}) {
|
||||
return {
|
||||
manifestVersion: 1,
|
||||
@@ -470,8 +493,77 @@ test("packing is deterministic and the archive validates", async (context) => {
|
||||
createHash("sha256").update(firstBytes).digest("hex"),
|
||||
);
|
||||
const validation = await validatePluginPackage(first);
|
||||
const directoryValidation = await validatePluginDirectory(directory);
|
||||
assert.equal(validation.manifest.id, "com.example.package-test");
|
||||
assert.equal(validation.fileCount, 3);
|
||||
assert.equal(firstResult.contentSha256, validation.contentSha256);
|
||||
assert.equal(validation.contentSha256, directoryValidation.contentSha256);
|
||||
assert.match(validation.contentSha256, /^[a-f0-9]{64}$/u);
|
||||
});
|
||||
|
||||
test("logical content identity follows companion declarations across ZIP mode encoders", async (context) => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-companion-mode-"));
|
||||
context.after(() => rm(root, { recursive: true, force: true }));
|
||||
const directory = await createPlugin(root);
|
||||
const companionContents = Buffer.from("portable companion\n");
|
||||
const companionPath = path.join(directory, "bin/helper");
|
||||
await mkdir(path.dirname(companionPath), { recursive: true });
|
||||
await writeFile(companionPath, companionContents);
|
||||
await writeFile(
|
||||
path.join(directory, "netcatty.plugin.json"),
|
||||
`${JSON.stringify(manifest({
|
||||
permissions: { required: ["companion.execute"] },
|
||||
companionExecutables: [{
|
||||
id: "com.example.package-test.helper",
|
||||
variants: [{
|
||||
path: "bin/helper",
|
||||
platforms: ["linux-x64"],
|
||||
sha256: createHash("sha256").update(companionContents).digest("hex"),
|
||||
}],
|
||||
}],
|
||||
}), null, 2)}\n`,
|
||||
);
|
||||
const builtPath = path.join(root, "built.ncpkg");
|
||||
const portablePath = path.join(root, "portable.ncpkg");
|
||||
const extracted = path.join(root, "extracted");
|
||||
await buildPluginPackage(directory, builtPath);
|
||||
await writeFile(
|
||||
portablePath,
|
||||
replaceCentralEntryMode(await readFile(builtPath), "bin/helper", 0o100644),
|
||||
);
|
||||
|
||||
const archiveValidation = await extractPluginPackage(portablePath, extracted);
|
||||
const directoryValidation = await validatePluginDirectory(extracted, {
|
||||
allowIgnoredRootEntries: false,
|
||||
});
|
||||
assert.equal(archiveValidation.contentSha256, directoryValidation.contentSha256);
|
||||
});
|
||||
|
||||
test("validated extraction creates an isolated tree and removes partial output on failure", async (context) => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-extract-"));
|
||||
context.after(() => rm(root, { recursive: true, force: true }));
|
||||
const directory = await createPlugin(root);
|
||||
const archive = path.join(root, "plugin.ncpkg");
|
||||
const extracted = path.join(root, "extracted");
|
||||
await buildPluginPackage(directory, archive);
|
||||
|
||||
const result = await extractPluginPackage(archive, extracted);
|
||||
assert.equal(result.manifest.id, "com.example.package-test");
|
||||
assert.equal(
|
||||
await readFile(path.join(extracted, "dist/index.js"), "utf8"),
|
||||
"export default {};\n",
|
||||
);
|
||||
await assert.rejects(extractPluginPackage(archive, extracted));
|
||||
assert.equal(
|
||||
await readFile(path.join(extracted, "dist/index.js"), "utf8"),
|
||||
"export default {};\n",
|
||||
);
|
||||
|
||||
const invalidArchive = path.join(root, "invalid.ncpkg");
|
||||
const failedDestination = path.join(root, "failed-extraction");
|
||||
await writeFile(invalidArchive, "not a zip");
|
||||
await assert.rejects(extractPluginPackage(invalidArchive, failedDestination));
|
||||
await assert.rejects(readFile(failedDestination), /ENOENT/);
|
||||
});
|
||||
|
||||
test("archive validation rejects oversized manifests before buffering", async (context) => {
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
export { PACKAGE_LIMITS } from "./constants.js";
|
||||
export {
|
||||
buildPluginPackage,
|
||||
extractPluginPackage,
|
||||
validatePluginDirectory,
|
||||
validatePluginPackage,
|
||||
type PackageBuildResult,
|
||||
|
||||
Reference in new issue
Block a user