pi-cursor-sdk 0.1.56 → 0.1.57

package/scripts/platform-smoke/artifact-anchored-extract.mjs

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, existsSync, mkdtempSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import {
+	MAX_BUNDLE_AGGREGATE_BYTES, MAX_BUNDLE_FILE_BYTES, MAX_BUNDLE_FILE_COUNT,
+	MAX_BUNDLE_PATH_BYTES, MAX_BUNDLE_PATH_COMPONENTS, MAX_INFLATED_BUNDLE_JSON_BYTES,
+} from "./artifact-bundle-contract.mjs";
+
+const MAGIC = Buffer.from([80, 73, 65, 82, 84, 48, 49, 0]);
+let helperPath;
+let helperDirectory;
+let helperUnavailable = false;
+
+function compileHelper() {
+	if (helperPath) return helperPath;
+	if (helperUnavailable) return undefined;
+	const source = fileURLToPath(new URL("./artifact-openat-extract.c", import.meta.url));
+	const content = readFileSync(source);
+	const nativeLimits = [
+		MAX_INFLATED_BUNDLE_JSON_BYTES, MAX_BUNDLE_FILE_COUNT, MAX_BUNDLE_FILE_BYTES,
+		MAX_BUNDLE_AGGREGATE_BYTES, MAX_BUNDLE_PATH_BYTES, MAX_BUNDLE_PATH_COMPONENTS,
+	];
+	const key = createHash("sha256").update(content).update(process.platform).update(process.arch)
+		.update(nativeLimits.join(":"))
+		.digest("hex").slice(0, 16);
+	helperDirectory = mkdtempSync(join(tmpdir(), `pi-cursor-artifact-openat-${key}-`));
+	chmodSync(helperDirectory, 0o700);
+	const output = join(helperDirectory, "extract");
+	const compiled = spawnSync("cc", [
+		"-std=c11", "-O2", "-Wall", "-Wextra", "-Werror",
+		`-DMAX_INPUT=${MAX_INFLATED_BUNDLE_JSON_BYTES}`,
+		`-DMAX_FILES=${MAX_BUNDLE_FILE_COUNT}`,
+		`-DMAX_FILE_BYTES=${MAX_BUNDLE_FILE_BYTES}`,
+		`-DMAX_TOTAL_BYTES=${MAX_BUNDLE_AGGREGATE_BYTES}`,
+		`-DMAX_PATH_BYTES=${MAX_BUNDLE_PATH_BYTES}`,
+		`-DMAX_PATH_COMPONENTS=${MAX_BUNDLE_PATH_COMPONENTS}`,
+		"-o", output, source,
+	], {
+		encoding: "utf8",
+		timeout: 30_000,
+		maxBuffer: 1024 * 1024,
+	});
+	if (compiled.status !== 0 || compiled.error || !existsSync(output)) {
+		rmSync(helperDirectory, { recursive: true, force: true });
+		helperDirectory = undefined;
+		helperUnavailable = true;
+		return undefined;
+	}
+	chmodSync(output, 0o700);
+	helperPath = output;
+	process.once("exit", () => {
+		if (helperDirectory) try { rmSync(helperDirectory, { recursive: true, force: true }); } catch {}
+	});
+	return helperPath;
+}
+
+function encodeFiles(files) {
+	const count = Buffer.alloc(4);
+	count.writeUInt32LE(files.length);
+	const chunks = [MAGIC, count];
+	for (const file of files) {
+		const path = Buffer.from(file.path, "utf8");
+		const lengths = Buffer.alloc(8);
+		lengths.writeUInt32LE(path.length, 0);
+		lengths.writeUInt32LE(file.content.length, 4);
+		chunks.push(lengths, path, file.content);
+	}
+	return Buffer.concat(chunks);
+}
+
+function writePosix(outputDir, files, expectedRoot) {
+	const helper = compileHelper();
+	if (!helper) return false;
+	let inputDirectory;
+	let inputFd;
+	try {
+		inputDirectory = mkdtempSync(join(tmpdir(), "pi-cursor-artifact-input-"));
+		chmodSync(inputDirectory, 0o700);
+		const inputPath = join(inputDirectory, "frame");
+		writeFileSync(inputPath, encodeFiles(files), { flag: "wx", mode: 0o600 });
+		inputFd = openSync(inputPath, "r");
+		unlinkSync(inputPath);
+		const result = spawnSync(helper, [outputDir, String(expectedRoot.dev), String(expectedRoot.ino)], {
+			stdio: [inputFd, "pipe", "pipe"],
+			encoding: "buffer",
+			maxBuffer: 1024 * 1024,
+		});
+		return result.status === 0 && !result.error;
+	} catch {
+		return false;
+	} finally {
+		try {
+			if (inputFd !== undefined) closeSync(inputFd);
+		} catch {
+			// Continue to remove the private input directory.
+		} finally {
+			if (inputDirectory) try { rmSync(inputDirectory, { recursive: true, force: true }); } catch {}
+		}
+	}
+}
+
+/** Extracts prevalidated files without permitting a nested host-path swap to redirect writes.
+ * Node has no handle-relative Windows creation API, so Windows controllers fail closed before
+ * mutating nonempty bundles. Windows remains a supported target of POSIX-hosted release matrices. */
+export function writeExtractedFilesAnchored(outputDir, files, expectedRoot) {
+	if (process.platform === "win32") return files.length === 0;
+	return writePosix(outputDir, files, expectedRoot);
+}

package/scripts/platform-smoke/artifact-bundle-chunk.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { closeSync, fstatSync, readSync } from "node:fs";
+import { PLATFORM_ARTIFACT_BUNDLE_PATH } from "./artifact-bundle-contract.mjs";
+import { openRegularFileNoFollow } from "./artifact-fs-safety.mjs";
+
+const MAX_CHUNK_BYTES = 32 * 1024;
+const args = process.argv.slice(2);
+
+function value(name) {
+	const index = args.indexOf(name);
+	return index >= 0 ? args[index + 1] : undefined;
+}
+
+function fail(message) {
+	console.error(`artifact bundle chunk error: ${message}`);
+	process.exitCode = 2;
+}
+
+if (args.includes("-h") || args.includes("--help")) {
+	console.log("Usage: node scripts/platform-smoke/artifact-bundle-chunk.mjs --path .platform-artifact-bundle.gz --offset <bytes> --length <1..32768>");
+	process.exit(0);
+}
+
+const pathValue = value("--path");
+const offset = Number(value("--offset"));
+const length = Number(value("--length"));
+if (args.length !== 6 || !pathValue || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 1 || length > MAX_CHUNK_BYTES) {
+	fail("invalid arguments");
+} else if (pathValue !== PLATFORM_ARTIFACT_BUNDLE_PATH) {
+	fail(`path must be exactly ${PLATFORM_ARTIFACT_BUNDLE_PATH}`);
+} else {
+	let descriptor;
+	let output;
+	try {
+		descriptor = openRegularFileNoFollow(PLATFORM_ARTIFACT_BUNDLE_PATH);
+		const total = fstatSync(descriptor).size;
+		if (offset >= total) throw new Error("offset is outside the bundle");
+		const buffer = Buffer.alloc(Math.min(length, total - offset));
+		const bytes = readSync(descriptor, buffer, 0, buffer.length, offset);
+		output = `PLATFORM_BUNDLE_CHUNK_JSON=${JSON.stringify({
+			offset,
+			total,
+			bytes,
+			contentBase64: buffer.subarray(0, bytes).toString("base64"),
+		})}`;
+	} catch (error) {
+		fail(error instanceof Error ? error.message : String(error));
+	} finally {
+		if (descriptor !== undefined) {
+			try { closeSync(descriptor); } catch {
+				output = undefined;
+				fail("failed to close bundle");
+			}
+		}
+	}
+	if (output) console.log(output);
+}

package/scripts/platform-smoke/artifact-bundle-contract.mjs

@@ -0,0 +1,34 @@
+/**
+ * Platform artifact bundle contract — transport markers, path rules, size caps, and the
+ * canonical exact-size base64 decoder shared by the writer, extractor, and remote chunk transport.
+ */
+
+export const PLATFORM_ARTIFACT_BUNDLE_START = "PLATFORM_LIVE_BUNDLE_JSON_START";
+export const PLATFORM_ARTIFACT_BUNDLE_END = "PLATFORM_LIVE_BUNDLE_JSON_END";
+export const PLATFORM_ARTIFACT_BUNDLE_FILE_MARKER = "PLATFORM_LIVE_BUNDLE_FILE_JSON=";
+export const PLATFORM_ARTIFACT_BUNDLE_PATH = ".platform-artifact-bundle.gz";
+
+export const MAX_BUNDLE_FILE_BYTES = 5 * 1024 * 1024;
+export const MAX_COMPRESSED_BUNDLE_BYTES = 20 * 1024 * 1024;
+export const MAX_INFLATED_BUNDLE_JSON_BYTES = 64 * 1024 * 1024;
+export const MAX_BUNDLE_FILE_COUNT = 512;
+export const MAX_BUNDLE_AGGREGATE_BYTES = 40 * 1024 * 1024;
+export const MAX_BUNDLE_PATH_BYTES = 4096;
+export const MAX_BUNDLE_PATH_COMPONENTS = 4096;
+
+/**
+ * Decode base64 only when it is the canonical (shortest, correctly padded) encoding of
+ * exactly `exactDecodedSize` bytes — rejects re-encodings that round-trip to a different string.
+ */
+export function decodeCanonicalBase64(value, exactDecodedSize) {
+	if (typeof value !== "string" || value.length !== 4 * Math.ceil(exactDecodedSize / 3)) return undefined;
+	const decoded = Buffer.from(value, "base64");
+	return decoded.toString("base64") === value ? decoded : undefined;
+}
+
+/** A relative, forward-slash, dot-segment-free path — the only path shape a bundle may declare. */
+export function isCanonicalPlatformBundlePath(path) {
+	if (typeof path !== "string" || !path || Buffer.byteLength(path) > MAX_BUNDLE_PATH_BYTES || path.includes("\\") || path.includes("\0")) return false;
+	if (path.startsWith("/") || /^[A-Za-z]:/.test(path)) return false;
+	return path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}

package/scripts/platform-smoke/artifact-fs-safety.mjs

@@ -0,0 +1,311 @@
+/**
+ * No-follow filesystem safety primitives shared by artifact scanning, bundling, and extraction:
+ * symlink-proof identity tracking, trusted-root traversal, bounded reads, safe extraction
+ * writes/cleanup, and the exclusive spill-file writer used when a bundle is too big to inline.
+ */
+
+import {
+	closeSync, constants, fstatSync, lstatSync, openSync, readSync,
+	readdirSync, realpathSync, unlinkSync, writeSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { MAX_BUNDLE_FILE_BYTES } from "./artifact-bundle-contract.mjs";
+import { writeExtractedFilesAnchored } from "./artifact-anchored-extract.mjs";
+
+function sameFileIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+
+function sameStableFileSnapshot(left, right) {
+	return sameFileIdentity(left, right) && left.size === right.size && left.mode === right.mode &&
+		left.nlink === right.nlink && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+
+function sameDirectorySnapshot(left, right, immutable) {
+	return sameFileIdentity(left, right) && (!immutable || (
+		left.ctimeMs === right.ctimeMs && left.mtimeMs === right.mtimeMs && left.size === right.size &&
+		left.mode === right.mode && left.nlink === right.nlink
+	));
+}
+
+export function reverifyDirectory(directory) {
+	try {
+		const current = lstatSync(directory.path);
+		return current.isDirectory() && !current.isSymbolicLink() &&
+			sameDirectorySnapshot(directory.stat, current, directory.immutable) &&
+			(directory.descriptor === undefined || sameDirectorySnapshot(directory.stat, fstatSync(directory.descriptor), directory.immutable));
+	} catch {
+		return false;
+	}
+}
+
+export function reverifyDirectories(directories) {
+	return directories.every(reverifyDirectory);
+}
+
+export function openRegularFileNoFollow(path, parentDirectories = []) {
+	if (!reverifyDirectories(parentDirectories)) throw new Error("parent directory changed before file open");
+	const before = lstatSync(path);
+	if (!before.isFile() || before.isSymbolicLink()) throw new Error("path is not a regular file");
+	if (!reverifyDirectories(parentDirectories)) throw new Error("parent directory changed before file open");
+	let descriptor;
+	try {
+		const noFollow = process.platform !== "win32" && typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+		descriptor = openSync(path, constants.O_RDONLY | noFollow);
+		const opened = fstatSync(descriptor);
+		const after = lstatSync(path);
+		if (!opened.isFile() || !after.isFile() || after.isSymbolicLink() || !sameFileIdentity(before, opened) ||
+			!sameFileIdentity(opened, after) || !reverifyDirectories(parentDirectories)) {
+			throw new Error("path changed while opening regular file");
+		}
+		return descriptor;
+	} catch (error) {
+		if (descriptor !== undefined) {
+			try { closeSync(descriptor); } catch {}
+		}
+		throw error;
+	}
+}
+
+export function boundedFileSnapshot(path, maxBytes = MAX_BUNDLE_FILE_BYTES, parentDirectories = []) {
+	let descriptor;
+	let result;
+	try {
+		descriptor = openRegularFileNoFollow(path, parentDirectories);
+		const before = fstatSync(descriptor, { bigint: true });
+		if (!before.isFile()) {
+			result = { ok: false, reason: "non-regular-entry" };
+		} else if (before.size > BigInt(maxBytes)) {
+			result = { ok: false, reason: "file-size", size: Number(before.size) };
+		} else if (!reverifyDirectories(parentDirectories)) {
+			result = { ok: false, reason: "file-changed" };
+		} else {
+			const content = Buffer.alloc(Number(before.size));
+			let offset = 0;
+			while (offset < content.length) {
+				const bytesRead = readSync(descriptor, content, offset, content.length - offset, null);
+				if (bytesRead === 0) break;
+				offset += bytesRead;
+			}
+			const after = fstatSync(descriptor, { bigint: true });
+			result = offset === Number(before.size) && sameStableFileSnapshot(before, after) && reverifyDirectories(parentDirectories)
+				? { ok: true, content }
+				: { ok: false, reason: "file-changed" };
+		}
+	} catch {
+		result = { ok: false, reason: "file-read" };
+	}
+	if (descriptor !== undefined) {
+		try { closeSync(descriptor); } catch { return { ok: false, reason: "file-close" }; }
+	}
+	return result;
+}
+
+/**
+ * Open a directory descriptor whose identity is pinned against symlink/rename swaps.
+ *
+ * `immutable: true` marks a traversal root/ancestor: its full stat snapshot (ctime/mtime/size/
+ * mode/nlink) must stay frozen for the life of the walk, so `reverifyDirectory` compares the
+ * whole snapshot — used for read-only scanning and bundling.
+ * `immutable: false` (default) marks an extraction destination, where only device+inode identity
+ * is pinned, since mtime/size legitimately change as files are written into it.
+ */
+export function openTrustedDirectory(path, { immutable = false, created = false } = {}) {
+	const before = lstatSync(path);
+	if (!before.isDirectory() || before.isSymbolicLink()) throw new Error("trusted directory target is not a real directory");
+	if (process.platform === "win32") {
+		const after = lstatSync(path);
+		if (!after.isDirectory() || after.isSymbolicLink() || !sameFileIdentity(before, after)) throw new Error("trusted directory target changed");
+		return { path, stat: after, immutable, created };
+	}
+	let descriptor;
+	try {
+		descriptor = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+		const opened = fstatSync(descriptor);
+		const after = lstatSync(path);
+		if (!opened.isDirectory() || !after.isDirectory() || after.isSymbolicLink() ||
+			!sameFileIdentity(before, opened) || !sameFileIdentity(opened, after)) throw new Error("trusted directory target changed");
+		return { path, stat: opened, descriptor, immutable, created };
+	} catch (error) {
+		if (descriptor !== undefined) try { closeSync(descriptor); } catch {}
+		throw error;
+	}
+}
+
+function closeDirectory(directory) {
+	if (directory?.descriptor !== undefined) closeSync(directory.descriptor);
+}
+
+function samePath(left, right) {
+	return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+function canonicalTraversalRoot(root) {
+	const lexicalRoot = resolve(root);
+	const final = lstatSync(lexicalRoot);
+	if (!final.isDirectory() || final.isSymbolicLink()) throw new Error("artifact root is not a real directory");
+	const actualRoot = realpathSync(lexicalRoot);
+	for (const lexicalBase of [resolve(process.cwd()), resolve(tmpdir())]) {
+		const rel = relative(lexicalBase, lexicalRoot);
+		if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) continue;
+		if (samePath(actualRoot, resolve(realpathSync(lexicalBase), rel))) return actualRoot;
+	}
+	throw new Error("artifact root is outside a trusted canonical base");
+}
+
+function isNonArtifactInfrastructureDirectory(name) {
+	return /^(?:node_modules|\.git)$/i.test(name);
+}
+
+/** Binary-safe, no-follow, symlink-race-proof walk of every file under a trusted root. */
+export function walkArtifactTree(root, handlers) {
+	let rootDirectory;
+	try {
+		rootDirectory = openTrustedDirectory(canonicalTraversalRoot(root), { immutable: true });
+	} catch {
+		handlers.directoryRead(resolve(root), undefined, resolve(root));
+		return;
+	}
+	function report(handler, path) {
+		handler(path, undefined, rootDirectory.path);
+	}
+	function walk(directory, ancestors) {
+		const guards = [...ancestors, directory];
+		let entries;
+		try {
+			if (!reverifyDirectories(guards)) throw new Error("artifact directory changed before read");
+			entries = readdirSync(directory.path, { withFileTypes: true });
+			if (!reverifyDirectories(guards)) throw new Error("artifact directory changed after read");
+		} catch {
+			report(handlers.directoryRead, directory.path);
+			return;
+		}
+		for (const entry of entries) {
+			if (!reverifyDirectories(guards)) {
+				report(handlers.directoryRead, directory.path);
+				return;
+			}
+			const path = resolve(directory.path, entry.name);
+			let stat;
+			try { stat = lstatSync(path); } catch {
+				report(handlers.fileRead, path);
+				continue;
+			}
+			if (stat.isDirectory() && !stat.isSymbolicLink()) {
+				if (isNonArtifactInfrastructureDirectory(entry.name)) continue;
+				let child;
+				try {
+					child = openTrustedDirectory(path, { immutable: true });
+					if (!reverifyDirectories(guards)) throw new Error("artifact ancestor changed");
+					walk(child, guards);
+				} catch {
+					report(handlers.directoryRead, path);
+				} finally {
+					if (child) try { closeDirectory(child); } catch { report(handlers.directoryRead, path); }
+				}
+				if (!reverifyDirectories(guards)) {
+					report(handlers.directoryRead, directory.path);
+					return;
+				}
+			} else if (stat.isFile() && !stat.isSymbolicLink()) {
+				handlers.file(path, guards, rootDirectory.path);
+			} else {
+				report(handlers.nonRegular, path);
+			}
+		}
+	}
+	try { walk(rootDirectory, []); } finally {
+		try { closeDirectory(rootDirectory); } catch { report(handlers.directoryRead, rootDirectory.path); }
+	}
+}
+
+function missingPath(path) {
+	try { return { stat: lstatSync(path) }; } catch (error) {
+		if (error?.code === "ENOENT") return {};
+		throw error;
+	}
+}
+
+function preflightExtraction(outputDir, files) {
+	const root = openTrustedDirectory(resolve(outputDir));
+	try {
+		const directoryPaths = new Set([root.path]);
+		for (const file of files) {
+			let path = dirname(resolve(outputDir, file.path));
+			while (path !== root.path) {
+				directoryPaths.add(path);
+				path = dirname(path);
+			}
+		}
+		const paths = [...directoryPaths].sort((left, right) => left.split(/[/\\]/).length - right.split(/[/\\]/).length);
+		for (const path of paths) {
+			const { stat } = missingPath(path);
+			if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error("artifact destination parent is not a real directory");
+		}
+		for (const file of files) {
+			const path = resolve(outputDir, file.path);
+			if (missingPath(path).stat) throw new Error("artifact destination already exists");
+		}
+		return { root };
+	} catch (error) {
+		if (root.descriptor !== undefined) try { closeSync(root.descriptor); } catch {}
+		throw error;
+	}
+}
+
+/** Write prevalidated `{path, content}` files through descriptor-relative POSIX extraction.
+ * Windows controllers reject nonempty extraction because Node lacks handle-relative creation. */
+export function writeExtractedFiles(outputDir, files) {
+	let preflight;
+	let succeeded = false;
+	try {
+		preflight = preflightExtraction(outputDir, files);
+		succeeded = writeExtractedFilesAnchored(preflight.root.path, files, preflight.root.stat);
+	} catch {}
+	if (preflight?.root.descriptor !== undefined) {
+		try { closeSync(preflight.root.descriptor); } catch {}
+	}
+	return succeeded;
+}
+
+/** Exclusively create `path` (no-follow, fails if it already exists) and write `content` to it,
+ * verifying identity before and after the write and unlinking on any failure. */
+export function writeBundleSpillFile(path, content) {
+	let descriptor;
+	let stat;
+	let failure;
+	try {
+		const noFollow = process.platform === "win32" ? 0 : constants.O_NOFOLLOW;
+		descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600);
+		stat = fstatSync(descriptor);
+		const afterOpen = lstatSync(path);
+		if (!stat.isFile() || !afterOpen.isFile() || afterOpen.isSymbolicLink() || !sameFileIdentity(stat, afterOpen)) {
+			throw new Error("platform artifact bundle changed while opening");
+		}
+		let offset = 0;
+		while (offset < content.length) {
+			const written = writeSync(descriptor, content, offset, content.length - offset);
+			if (written < 1) throw new Error("platform artifact bundle write made no progress");
+			offset += written;
+		}
+		const afterWrite = lstatSync(path);
+		if (!afterWrite.isFile() || afterWrite.isSymbolicLink() || !sameFileIdentity(stat, fstatSync(descriptor)) || !sameFileIdentity(stat, afterWrite)) {
+			throw new Error("platform artifact bundle changed while writing");
+		}
+	} catch (error) {
+		failure = error;
+	}
+	if (descriptor !== undefined) {
+		try { closeSync(descriptor); } catch (error) { failure ??= error; }
+	}
+	if (failure) {
+		if (stat) {
+			try {
+				const current = lstatSync(path);
+				if (current.isFile() && !current.isSymbolicLink() && sameFileIdentity(stat, current)) unlinkSync(path);
+			} catch {}
+		}
+		throw failure;
+	}
+}