diff --git a/docs/plugin-platform/contract-and-sdk.md b/docs/plugin-platform/contract-and-sdk.md index 662901a43..cb138ee89 100644 --- a/docs/plugin-platform/contract-and-sdk.md +++ b/docs/plugin-platform/contract-and-sdk.md @@ -378,6 +378,12 @@ arbitrary JavaScript without terminating the isolated runtime. The packer sorts UTF-8 package paths, stores fixed ZIP timestamps and file modes, and writes entries without platform-dependent compression output. The same files and manifest therefore produce the same archive bytes. +The validated source-manifest byte length and SHA-256 are bound to the scanned +manifest entry before writing; the archive writer then rechecks every scanned +file while streaming it. A manifest changed after validation cannot be packaged +under the previously validated object model. Source hashing enforces its byte +budget during the read, and archive writing stops before emitting bytes beyond +the scanned size, so a concurrently growing file cannot cause unbounded I/O. Package validation rejects: @@ -388,6 +394,7 @@ Package validation rejects: - companion binaries whose SHA-256 does not match the manifest; - duplicate entries, encrypted entries, and unsupported compression methods; - missing entrypoints, views, package icons, and companion variants; +- a source manifest whose packaged bytes differ from the validated snapshot; - excessive path, file, archive, or expanded-package sizes. These checks are repeated when reading `.ncpkg` files. Installation in phase 2 diff --git a/docs/plugin-platform/threat-model.md b/docs/plugin-platform/threat-model.md index 2c1b3a2e2..94d3c9bed 100644 --- a/docs/plugin-platform/threat-model.md +++ b/docs/plugin-platform/threat-model.md @@ -59,6 +59,13 @@ from validating and extracting different interpretations of one package. Manifest decoding is fatal UTF-8 on both source directories and archives. Malformed byte sequences cannot be normalized differently by separate package inspection and installation paths. +The packer also binds the exact validated manifest bytes to the scanned package +entry with byte length and SHA-256, then rechecks the entry while writing. A +source manifest changed between semantic validation and archive creation is +rejected instead of inheriting the decision made for older bytes. +Every source hash read enforces the file budget incrementally, and the writer +refuses the first byte beyond the scanned size. Concurrent file growth therefore +fails before it can turn validation or packaging into unbounded disk I/O. ### Symbolic links and executable smuggling diff --git a/packages/plugin-cli/src/archive.ts b/packages/plugin-cli/src/archive.ts index 9958668c9..87dc8143f 100644 --- a/packages/plugin-cli/src/archive.ts +++ b/packages/plugin-cli/src/archive.ts @@ -19,7 +19,8 @@ import yauzl, { type Entry, type ZipFile } from "yauzl"; import { IGNORED_ROOT_ENTRIES, PACKAGE_LIMITS } from "./constants.js"; import { parseAndValidateManifestContents, - readAndValidateManifest, + readValidatedManifestSource, + type ValidatedManifestSource, } from "./manifest.js"; import { assertSafePackagePath, PackagePathRegistry } from "./packagePath.js"; @@ -42,6 +43,20 @@ interface ScannedFile { readonly executable: boolean; } +interface ScannedManifestIdentity { + readonly size: number; + readonly sha256: string; +} + +export function assertManifestSnapshotMatches( + source: Pick, + scanned: ScannedManifestIdentity | undefined, +): void { + if (!scanned || scanned.size !== source.size || scanned.sha256 !== source.sha256) { + throw new Error("Plugin manifest changed after validation"); + } +} + export interface PackageBuildResult { readonly outputPath: string; readonly fileCount: number; @@ -66,6 +81,7 @@ function updateCrc32(current: number, chunk: Buffer): number { async function readRegularFile( filePath: string, + maxBytes: number, onChunk: (chunk: Buffer) => void, ): Promise<{ size: number; mode: number }> { const noFollow = "O_NOFOLLOW" in constants @@ -80,6 +96,9 @@ async function readRegularFile( for await (const chunk of stream) { const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); size += buffer.byteLength; + if (size > maxBytes) { + throw new Error(`Package source exceeds ${maxBytes} bytes while reading: ${filePath}`); + } onChunk(buffer); } return { size, mode: fileStats.mode }; @@ -88,12 +107,13 @@ async function readRegularFile( } } -async function hashFile( +export async function hashFile( filePath: string, + maxBytes: number, ): Promise<{ crc32: number; sha256: string; size: number; mode: number }> { const sha256 = createHash("sha256"); let crc = 0xffffffff; - const file = await readRegularFile(filePath, (buffer) => { + const file = await readRegularFile(filePath, maxBytes, (buffer) => { sha256.update(buffer); crc = updateCrc32(crc, buffer); }); @@ -148,8 +168,9 @@ async function resolveThroughExistingAncestor(targetPath: string): Promise { + const { manifest } = manifestSource; const registry = new PackagePathRegistry(); const companionPaths = new Map( (manifest.companionExecutables ?? []).flatMap((companion) => ( @@ -199,7 +220,7 @@ async function scanPackageDirectory( `Plugin package exceeds ${PACKAGE_LIMITS.uncompressedBytes} uncompressed bytes`, ); } - const hashes = await hashFile(absolutePath); + const hashes = await hashFile(absolutePath, PACKAGE_LIMITS.singleFileBytes); if (hashes.size !== fileStats.size || hashes.mode !== fileStats.mode) { throw new Error(`Package source changed while it was being scanned: ${packagePath}`); } @@ -223,6 +244,10 @@ async function scanPackageDirectory( } await visit(pluginDirectory, ""); + assertManifestSnapshotMatches( + manifestSource, + files.find(({ packagePath }) => packagePath === "netcatty.plugin.json"), + ); const packagedPaths = new Set(files.map(({ packagePath }) => packagePath)); const requiredPaths = [ "netcatty.plugin.json", @@ -335,6 +360,9 @@ async function writeArchive(files: readonly ScannedFile[], outputPath: string): for await (const chunk of stream) { const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); writtenBytes += buffer.byteLength; + if (writtenBytes > file.size) { + throw new Error(`Package source changed while it was being written: ${file.packagePath}`); + } sha256.update(buffer); crc = updateCrc32(crc, buffer); await writeBuffer(output, buffer); @@ -391,11 +419,11 @@ export async function buildPluginPackage( ) { throw new Error("Plugin package output must be outside the plugin source directory"); } - const manifest = await readAndValidateManifest(sourceDirectory); - const files = await scanPackageDirectory(sourceDirectory, manifest); + const manifestSource = await readValidatedManifestSource(sourceDirectory); + const files = await scanPackageDirectory(sourceDirectory, manifestSource); await writeArchive(files, resolvedOutputPath); const outputStats = await stat(resolvedOutputPath); - const archiveHash = await hashFile(resolvedOutputPath); + const archiveHash = await hashFile(resolvedOutputPath, PACKAGE_LIMITS.archiveBytes); return { outputPath: resolvedOutputPath, fileCount: files.length, @@ -409,10 +437,10 @@ export async function validatePluginDirectory( pluginDirectory: string, ): Promise { const sourceDirectory = path.resolve(pluginDirectory); - const manifest = await readAndValidateManifest(sourceDirectory); - const files = await scanPackageDirectory(sourceDirectory, manifest); + const manifestSource = await readValidatedManifestSource(sourceDirectory); + const files = await scanPackageDirectory(sourceDirectory, manifestSource); return { - manifest, + manifest: manifestSource.manifest, fileCount: files.length, uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0), }; diff --git a/packages/plugin-cli/src/cli.test.ts b/packages/plugin-cli/src/cli.test.ts index 676f953a3..8da989600 100644 --- a/packages/plugin-cli/src/cli.test.ts +++ b/packages/plugin-cli/src/cli.test.ts @@ -16,7 +16,12 @@ import { promisify } from "node:util"; import { fileURLToPath } from "node:url"; import test from "node:test"; -import { buildPluginPackage, validatePluginPackage } from "./archive.ts"; +import { + assertManifestSnapshotMatches, + buildPluginPackage, + hashFile, + validatePluginPackage, +} from "./archive.ts"; import { checkPluginCompatibility } from "./compatibility.ts"; import { PACKAGE_LIMITS } from "./constants.ts"; import { initPlugin } from "./commands.ts"; @@ -611,3 +616,30 @@ test("manifest validation refuses symlinked source manifests", async (context) = await symlink(target, path.join(root, "netcatty.plugin.json")); await assert.rejects(readAndValidateManifest(root), /must be a regular file/); }); + +test("validated manifest snapshots reject changed package bytes", () => { + const snapshot = { size: 128, sha256: "a".repeat(64) }; + assert.doesNotThrow(() => assertManifestSnapshotMatches(snapshot, snapshot)); + assert.throws( + () => assertManifestSnapshotMatches(snapshot, { ...snapshot, size: 129 }), + /manifest changed after validation/, + ); + assert.throws( + () => assertManifestSnapshotMatches(snapshot, { ...snapshot, sha256: "b".repeat(64) }), + /manifest changed after validation/, + ); + assert.throws( + () => assertManifestSnapshotMatches(snapshot, undefined), + /manifest changed after validation/, + ); +}); + +test("source hashing enforces its byte budget while reading", async (context) => { + const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-source-limit-")); + context.after(() => rm(root, { recursive: true, force: true })); + const filePath = path.join(root, "growing.bin"); + await writeFile(filePath, "1234"); + + await assert.rejects(hashFile(filePath, 3), /source exceeds 3 bytes while reading/); + assert.equal((await hashFile(filePath, 4)).size, 4); +}); diff --git a/packages/plugin-cli/src/manifest.ts b/packages/plugin-cli/src/manifest.ts index fb16d8a7b..581f43c58 100644 --- a/packages/plugin-cli/src/manifest.ts +++ b/packages/plugin-cli/src/manifest.ts @@ -1,3 +1,4 @@ +import { createHash } from "node:crypto"; import { createRequire } from "node:module"; import { lstat, @@ -53,6 +54,12 @@ export interface ManifestValidationResult { readonly errors: readonly string[]; } +export interface ValidatedManifestSource { + readonly manifest: PluginManifest; + readonly size: number; + readonly sha256: string; +} + function formatAjvError(error: ErrorObject): string { const location = error.instancePath || "/"; return `${location} ${error.message ?? "is invalid"}`; @@ -520,9 +527,9 @@ export function parseAndValidateManifestContents(contents: Uint8Array): PluginMa return result.manifest; } -export async function readAndValidateManifest( +export async function readValidatedManifestSource( pluginDirectory: string, -): Promise { +): Promise { const manifestPath = path.join(pluginDirectory, "netcatty.plugin.json"); const initialStats = await lstat(manifestPath); if (!initialStats.isFile()) { @@ -566,5 +573,15 @@ export async function readAndValidateManifest( } finally { await handle.close(); } - return parseAndValidateManifestContents(contents); + return { + manifest: parseAndValidateManifestContents(contents), + size: contents.byteLength, + sha256: createHash("sha256").update(contents).digest("hex"), + }; +} + +export async function readAndValidateManifest( + pluginDirectory: string, +): Promise { + return (await readValidatedManifestSource(pluginDirectory)).manifest; }