ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
#!/usr/bin/env python3
"""Verify installed plugin package files against a pinned npm archive."""
from __future__ import annotations
import argparse
import base64
import binascii
import hashlib
import json
import os
from pathlib import Path, PurePosixPath
import re
import stat
import sys
import tarfile
import tempfile
MAX_MEMBERS = 10_000
MAX_FILE_BYTES = 50 * 1024 * 1024
MAX_TOTAL_BYTES = 100 * 1024 * 1024
GENERATED_INSTALL_LOCK = Path("node_modules/.package-lock.json")
SEMVER = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
PACKAGE_NAME = re.compile(r"^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$")
EXTRA_LOCK_RECORD_KEYS = {
"bin", "cpu", "dependencies", "engines", "funding", "inBundle", "integrity",
"license", "optional", "optionalDependencies", "os", "peer", "peerDependencies",
"peerDependenciesMeta", "resolved", "version",
}
MAX_INSTALL_ENTRIES = 100_000
MAX_INSTALL_FILE_BYTES = 2 * 1024 * 1024 * 1024
MAX_INSTALL_TOTAL_BYTES = 4 * 1024 * 1024 * 1024
class VerificationError(RuntimeError):
pass
def digest_stream(stream, expected_size: int) -> str:
digest = hashlib.sha256()
observed = 0
while True:
block = stream.read(1024 * 1024)
if not block:
break
observed += len(block)
if observed > expected_size or observed > MAX_FILE_BYTES:
raise VerificationError("archive member exceeded its declared or allowed size")
digest.update(block)
if observed != expected_size:
raise VerificationError("archive member size does not match its payload")
return digest.hexdigest()
def package_relative(name: str) -> Path:
path = PurePosixPath(name)
if path.is_absolute() or not path.parts or path.parts[0] != "package":
raise VerificationError(f"archive member is outside package/: {name}")
relative = path.relative_to("package")
if not relative.parts or any(part in {"", ".", ".."} for part in relative.parts):
raise VerificationError(f"archive member has an unsafe path: {name}")
return Path(*relative.parts)
def archive_json(bundle: tarfile.TarFile, member: tarfile.TarInfo, label: str) -> dict:
if not member.isfile() or member.size < 2 or member.size > MAX_FILE_BYTES:
raise VerificationError(f"{label} is not a bounded regular file")
extracted = bundle.extractfile(member)
if extracted is None:
raise VerificationError(f"{label} cannot be read")
try:
value = json.loads(extracted.read(MAX_FILE_BYTES + 1))
except (UnicodeError, json.JSONDecodeError) as exc:
raise VerificationError(f"{label} is invalid JSON") from exc
if not isinstance(value, dict):
raise VerificationError(f"{label} must be an object")
return value
def archive_install_metadata(
bundle: tarfile.TarFile, members: dict[Path, tarfile.TarInfo],
) -> tuple[set[Path], dict | None]:
shrinkwrap_member = members.get(Path("npm-shrinkwrap.json"))
if shrinkwrap_member is None:
return set(), None
shrinkwrap = archive_json(bundle, shrinkwrap_member, "npm-shrinkwrap.json")
packages = shrinkwrap.get("packages")
if not isinstance(packages, dict):
raise VerificationError("npm-shrinkwrap.json has no package inventory")
roots: set[Path] = set()
for name, record in packages.items():
if not isinstance(name, str) or not isinstance(record, dict) or record.get("optional") is not True:
continue
pure = PurePosixPath(name)
if (
pure.is_absolute() or not pure.parts or pure.parts[0] != "node_modules"
or any(part in {"", ".", ".."} for part in pure.parts)
):
raise VerificationError("npm-shrinkwrap.json has an unsafe optional package path")
relative = Path(*pure.parts)
package_json = members.get(relative / "package.json")
if package_json is None:
has_archived_payload = any(
candidate == relative or relative in candidate.parents for candidate in members
)
if has_archived_payload:
raise VerificationError(f"optional package has no archived package.json: {relative}")
continue
metadata = archive_json(bundle, package_json, f"{relative}/package.json")
package_name = metadata.get("name")
expected_name = pure.parts[-1] if len(pure.parts) < 3 or not pure.parts[-2].startswith("@") else f"{pure.parts[-2]}/{pure.parts[-1]}"
if package_name != expected_name:
raise VerificationError(f"optional package identity differs from its path: {relative}")
roots.add(relative)
return roots, shrinkwrap
def absent_optional_root(relative: Path, root: Path, optional_roots: set[Path]) -> bool:
for optional in optional_roots:
if relative == optional or optional in relative.parents:
destination = root / optional
return not os.path.lexists(destination)
return False
def installed_json(path: Path, label: str) -> dict:
try:
metadata = path.lstat()
except FileNotFoundError as exc:
raise VerificationError(f"installed {label} is missing") from exc
if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
raise VerificationError(f"installed {label} is not a regular file")
if metadata.st_size < 2 or metadata.st_size > MAX_FILE_BYTES:
raise VerificationError(f"installed {label} is not bounded")
try:
value = json.loads(path.read_bytes())
except (UnicodeError, json.JSONDecodeError) as exc:
raise VerificationError(f"installed {label} is invalid JSON") from exc
if not isinstance(value, dict):
raise VerificationError(f"installed {label} must be an object")
return value
def flat_lock_package(name: str) -> tuple[Path, str]:
pure = PurePosixPath(name)
if pure.is_absolute() or any(part in {"", ".", ".."} for part in pure.parts):
raise VerificationError("installed shrinkwrap has an unsafe package path")
if len(pure.parts) == 2 and pure.parts[0] == "node_modules" and not pure.parts[1].startswith("@"):
return Path(*pure.parts), pure.parts[1]
if (
len(pure.parts) == 3 and pure.parts[0] == "node_modules"
and pure.parts[1].startswith("@") and len(pure.parts[1]) > 1
and not pure.parts[2].startswith("@")
):
return Path(*pure.parts), f"{pure.parts[1]}/{pure.parts[2]}"
raise VerificationError("installed shrinkwrap added a non-flat package path")
def version_matches(spec: str, version: str) -> bool:
observed = SEMVER.fullmatch(version)
if observed is None:
return False
if spec == version:
return True
if spec.startswith(">="):
minimum = SEMVER.fullmatch(spec[2:])
return minimum is not None and tuple(int(value) for value in observed.groups()) >= tuple(
int(value) for value in minimum.groups()
)
if len(spec) < 2 or spec[0] not in {"^", "~"}:
return False
minimum = SEMVER.fullmatch(spec[1:])
if minimum is None:
return False
current = tuple(int(value) for value in observed.groups())
floor = tuple(int(value) for value in minimum.groups())
if current < floor:
return False
if spec[0] == "~":
return current[:2] == floor[:2]
if floor[0] > 0:
return current[0] == floor[0]
if floor[1] > 0:
return current[:2] == floor[:2]
return current == floor
def parse_allowed_peers(values: list[str]) -> dict[str, tuple[str, Path]]:
result: dict[str, tuple[str, Path]] = {}
for value in values:
try:
identity, raw_path = value.split("=", 1)
package_name, version = identity.rsplit("@", 1)
except ValueError as exc:
raise VerificationError("allowed peer must be NAME@VERSION=ABSOLUTE_PATH") from exc
if (
PACKAGE_NAME.fullmatch(package_name) is None
or SEMVER.fullmatch(version) is None
or package_name in result
):
raise VerificationError("allowed peer identity is invalid or duplicated")
path = Path(raw_path)
if not path.is_absolute():
raise VerificationError("allowed peer path must be absolute")
try:
resolved = path.resolve(strict=True)
except OSError as exc:
raise VerificationError("allowed peer path does not exist") from exc
if not resolved.is_dir():
raise VerificationError("allowed peer path must be a directory")
result[package_name] = version, resolved
return result
def peer_relative_path(package_name: str) -> Path:
if package_name.startswith("@"):
scope, leaf = package_name.split("/", 1)
return Path("node_modules", scope, leaf)
return Path("node_modules", package_name)
def verify_allowed_peer_link(
candidate: Path,
relative: Path,
package_manifest: dict,
allowed_peers: dict[str, tuple[str, Path]],
) -> bool:
matching = [name for name in allowed_peers if peer_relative_path(name) == relative]
if not matching:
return False
package_name = matching[0]
expected_version, expected_root = allowed_peers[package_name]
peer_dependencies = package_manifest.get("peerDependencies", {})
peer_metadata = package_manifest.get("peerDependenciesMeta", {})
if not isinstance(peer_dependencies, dict) or not isinstance(peer_metadata, dict):
raise VerificationError("package.json peer dependency metadata must be objects")
metadata = peer_metadata.get(package_name)
spec = peer_dependencies.get(package_name)
if not isinstance(metadata, dict) or metadata.get("optional") is not True or not isinstance(spec, str):
raise VerificationError(f"installed peer link is not an optional declared peer: {relative}")
if not candidate.is_symlink():
raise VerificationError(f"installed peer link is not a symlink: {relative}")
try:
observed_root = candidate.resolve(strict=True)
except OSError as exc:
raise VerificationError(f"installed peer link is broken: {relative}") from exc
if observed_root != expected_root:
raise VerificationError(f"installed peer link targets a different runtime: {relative}")
peer_manifest = installed_json(expected_root / "package.json", f"{package_name} peer package.json")
if (
peer_manifest.get("name") != package_name
or peer_manifest.get("version") != expected_version
or not version_matches(spec, expected_version)
):
raise VerificationError(f"installed peer link has a different identity: {relative}")
return True
def dependency_specs(record: dict) -> dict[str, set[str]]:
result: dict[str, set[str]] = {}
for field in ("dependencies", "optionalDependencies", "peerDependencies"):
values = record.get(field, {})
if not isinstance(values, dict):
raise VerificationError(f"installed shrinkwrap {field} must be an object")
for name, spec in values.items():
if not isinstance(name, str) or not isinstance(spec, str):
raise VerificationError(f"installed shrinkwrap {field} entries must be strings")
result.setdefault(name, set()).add(spec)
return result
def merge_specs(target: dict[str, set[str]], record: dict) -> None:
for name, specs in dependency_specs(record).items():
target.setdefault(name, set()).update(specs)
def verify_added_peer_record(name: str, record: dict, root: Path) -> tuple[Path, str, str]:
relative, package_name = flat_lock_package(name)
if set(record) - EXTRA_LOCK_RECORD_KEYS:
raise VerificationError(f"installed shrinkwrap added unsupported metadata: {relative}")
if record.get("optional") is not True or record.get("peer") is not True or record.get("inBundle") is not True:
raise VerificationError(f"installed shrinkwrap added non-optional peer metadata: {relative}")
version = record.get("version")
resolved = record.get("resolved")
integrity = record.get("integrity")
if not isinstance(version, str) or SEMVER.fullmatch(version) is None:
raise VerificationError(f"installed shrinkwrap added an invalid version: {relative}")
leaf = package_name.split("/", 1)[-1]
expected_url = f"https://registry.npmjs.org/{package_name}/-/{leaf}-{version}.tgz"
if resolved != expected_url or not isinstance(integrity, str) or not integrity.startswith("sha512-"):
raise VerificationError(f"installed shrinkwrap added an untrusted package source: {relative}")
try:
decoded = base64.b64decode(integrity.removeprefix("sha512-"), validate=True)
except (binascii.Error, ValueError) as exc:
raise VerificationError(f"installed shrinkwrap added invalid integrity: {relative}") from exc
if len(decoded) != 64:
raise VerificationError(f"installed shrinkwrap added invalid integrity: {relative}")
if os.path.lexists(root / relative):
raise VerificationError(f"unarchived peer package was installed: {relative}")
return relative, package_name, version
def lock_package_path(name: str) -> tuple[Path, str]:
pure = PurePosixPath(name)
if (
pure.is_absolute() or not pure.parts or pure.parts[0] != "node_modules"
or any(part in {"", ".", ".."} for part in pure.parts)
):
raise VerificationError("npm-shrinkwrap.json has an unsafe package path")
indexes = [index for index, part in enumerate(pure.parts) if part == "node_modules"]
tail = pure.parts[indexes[-1] + 1:]
if len(tail) == 1 and not tail[0].startswith("@"):
package_name = tail[0]
elif len(tail) == 2 and tail[0].startswith("@") and len(tail[0]) > 1 and not tail[1].startswith("@"):
package_name = f"{tail[0]}/{tail[1]}"
else:
raise VerificationError("npm-shrinkwrap.json has an invalid package identity path")
if PACKAGE_NAME.fullmatch(package_name) is None:
raise VerificationError("npm-shrinkwrap.json has an invalid package name")
return Path(*pure.parts), package_name
def verify_registry_record(relative: Path, package_name: str, record: dict) -> str:
version = record.get("version")
resolved = record.get("resolved")
integrity = record.get("integrity")
if not isinstance(version, str) or SEMVER.fullmatch(version) is None:
raise VerificationError(f"npm-shrinkwrap.json has an invalid package version: {relative}")
leaf = package_name.split("/", 1)[-1]
expected_url = f"https://registry.npmjs.org/{package_name}/-/{leaf}-{version}.tgz"
if resolved != expected_url or not isinstance(integrity, str) or not integrity.startswith("sha512-"):
raise VerificationError(f"npm-shrinkwrap.json has an untrusted package source: {relative}")
try:
decoded = base64.b64decode(integrity.removeprefix("sha512-"), validate=True)
except (binascii.Error, ValueError) as exc:
raise VerificationError(f"npm-shrinkwrap.json has invalid package integrity: {relative}") from exc
if len(decoded) != 64:
raise VerificationError(f"npm-shrinkwrap.json has invalid package integrity: {relative}")
return version
def installed_lock_package_roots(
root: Path,
members: dict[Path, tarfile.TarInfo],
archived_shrinkwrap: dict | None,
) -> dict[Path, str]:
if archived_shrinkwrap is None:
return {}
packages = archived_shrinkwrap.get("packages")
if not isinstance(packages, dict):
raise VerificationError("npm-shrinkwrap.json has no package inventory")
installed: dict[Path, str] = {}
for name, record in packages.items():
if name == "":
continue
if not isinstance(name, str) or not isinstance(record, dict):
raise VerificationError("npm-shrinkwrap.json package record must be an object")
relative, package_name = lock_package_path(name)
package_root = root / relative
if not os.path.lexists(package_root):
continue
if members.get(relative / "package.json") is not None:
continue
if package_root.is_symlink() or not package_root.is_dir():
raise VerificationError(f"lock-declared package root is not a real directory: {relative}")
version = verify_registry_record(relative, package_name, record)
metadata = installed_json(package_root / "package.json", f"{relative}/package.json")
if metadata.get("name") != package_name or metadata.get("version") != version:
raise VerificationError(f"installed lock-declared package has a different identity: {relative}")
installed[relative] = package_name
return installed
def belongs_to(relative: Path, roots: dict[Path, str]) -> bool:
return any(relative == package_root or package_root in relative.parents for package_root in roots)
def safe_internal_symlink(candidate: Path, root: Path, lock_roots: dict[Path, str]) -> None:
if not candidate.is_symlink():
return
try:
resolved = candidate.resolve(strict=True)
resolved_relative = resolved.relative_to(root)
except (OSError, ValueError) as exc:
raise VerificationError("installed dependency has an escaping or broken symlink") from exc
if not belongs_to(resolved_relative, lock_roots):
raise VerificationError("installed dependency symlink does not target a locked package")
def verify_installed_shrinkwrap(
bundle: tarfile.TarFile,
members: dict[Path, tarfile.TarInfo],
archived: dict,
destination: Path,
root: Path,
) -> int:
observed = installed_json(destination, "npm-shrinkwrap.json")
archived_packages = archived.get("packages")
observed_packages = observed.get("packages")
if not isinstance(archived_packages, dict) or not isinstance(observed_packages, dict):
raise VerificationError("npm-shrinkwrap.json has no package inventory")
if {key: value for key, value in observed.items() if key != "packages"} != {
key: value for key, value in archived.items() if key != "packages"
}:
raise VerificationError("installed npm-shrinkwrap.json changed release metadata")
package_member = members.get(Path("package.json"))
if package_member is None:
raise VerificationError("archive does not contain package.json")
package_manifest = archive_json(bundle, package_member, "package.json")
bundle_dependencies = package_manifest.get(
"bundledDependencies", package_manifest.get("bundleDependencies", []),
)
if not isinstance(bundle_dependencies, list) or not all(isinstance(value, str) for value in bundle_dependencies):
raise VerificationError("package.json bundledDependencies must be a string array")
for name, expected in archived_packages.items():
actual = observed_packages.get(name)
if not isinstance(name, str) or not isinstance(expected, dict) or not isinstance(actual, dict):
raise VerificationError("installed npm-shrinkwrap.json removed or changed a package record")
normalized = dict(actual)
if "inBundle" not in expected and "inBundle" in normalized:
if normalized.pop("inBundle") is not True:
raise VerificationError("installed npm-shrinkwrap.json has invalid bundle metadata")
if name == "" and "bundleDependencies" not in expected and "bundleDependencies" in normalized:
if normalized.pop("bundleDependencies") != bundle_dependencies:
raise VerificationError("installed npm-shrinkwrap.json changed bundled dependencies")
if normalized != expected:
raise VerificationError(f"installed npm-shrinkwrap.json changed package metadata: {name or '<root>'}")
additions = {name: value for name, value in observed_packages.items() if name not in archived_packages}
pending: dict[str, tuple[Path, str, str, dict]] = {}
for name, record in additions.items():
if not isinstance(name, str) or not isinstance(record, dict):
raise VerificationError("installed npm-shrinkwrap.json added an invalid package record")
relative, package_name, version = verify_added_peer_record(name, record, root)
pending[name] = (relative, package_name, version, record)
references: dict[str, set[str]] = {}
for record in archived_packages.values():
if not isinstance(record, dict):
raise VerificationError("npm-shrinkwrap.json package record must be an object")
merge_specs(references, record)
while pending:
accepted = None
for lock_name, (_, package_name, version, record) in pending.items():
if any(version_matches(spec, version) for spec in references.get(package_name, set())):
accepted = lock_name, record
break
if accepted is None:
raise VerificationError("installed npm-shrinkwrap.json added unreachable peer metadata")
lock_name, record = accepted
merge_specs(references, record)
del pending[lock_name]
return len(additions)
def verify_installed_inventory(
root: Path,
members: dict[Path, tarfile.TarInfo],
package_manifest: dict,
allowed_peers: dict[str, tuple[str, Path]],
archived_shrinkwrap: dict | None,
) -> tuple[int, int]:
expected = set(members)
lock_roots = installed_lock_package_roots(root, members, archived_shrinkwrap)
saw_generated_lock = False
linked_peers = 0
for directory, subdirectories, filenames in os.walk(root, followlinks=False):
base = Path(directory)
for name in [*subdirectories, *filenames]:
candidate = base / name
relative = candidate.relative_to(root)
if candidate.is_dir() and not candidate.is_symlink():
continue
if relative in expected:
continue
if relative == GENERATED_INSTALL_LOCK:
installed_json(candidate, str(GENERATED_INSTALL_LOCK))
saw_generated_lock = True
continue
if verify_allowed_peer_link(candidate, relative, package_manifest, allowed_peers):
linked_peers += 1
continue
if belongs_to(relative, lock_roots):
safe_internal_symlink(candidate, root, lock_roots)
continue
if (
len(relative.parts) == 3 and relative.parts[:2] == ("node_modules", ".bin")
and candidate.is_symlink()
):
safe_internal_symlink(candidate, root, lock_roots)
continue
raise VerificationError(f"installed package has an unexpected payload: {relative}")
if (root / GENERATED_INSTALL_LOCK).exists() and not saw_generated_lock:
raise VerificationError("generated npm install lock was not inspected")
return linked_peers, len(lock_roots)
def digest_file(path: Path, metadata: os.stat_result) -> tuple[str, int]:
if metadata.st_size > MAX_INSTALL_FILE_BYTES:
raise VerificationError("installed dependency file exceeds its size limit")
flags = (
os.O_RDONLY | getattr(os, "O_BINARY", 0)
| getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
)
descriptor = os.open(path, flags)
try:
observed = os.fstat(descriptor)
if (
not stat.S_ISREG(observed.st_mode)
or (observed.st_dev, observed.st_ino) != (metadata.st_dev, metadata.st_ino)
):
raise VerificationError("installed dependency changed during hashing")
digest = hashlib.sha256()
total = 0
while True:
block = os.read(descriptor, 1024 * 1024)
if not block:
break
total += len(block)
if total > metadata.st_size or total > MAX_INSTALL_FILE_BYTES:
raise VerificationError("installed dependency changed size during hashing")
digest.update(block)
if total != metadata.st_size:
raise VerificationError("installed dependency changed size during hashing")
return digest.hexdigest(), total
finally:
os.close(descriptor)
def installed_tree(root: Path) -> dict[str, int | str]:
records: list[tuple[str, str, int, int, str]] = []
total_bytes = 0
for directory, subdirectories, filenames in os.walk(root, followlinks=False):
subdirectories.sort()
filenames.sort()
base = Path(directory)
for name in [*subdirectories, *filenames]:
candidate = base / name
relative = candidate.relative_to(root).as_posix()
metadata = candidate.lstat()
mode = stat.S_IMODE(metadata.st_mode)
if stat.S_ISLNK(metadata.st_mode):
records.append((relative, "link", mode, 0, os.readlink(candidate)))
elif stat.S_ISDIR(metadata.st_mode):
records.append((relative, "directory", mode, 0, ""))
elif stat.S_ISREG(metadata.st_mode):
file_digest, size = digest_file(candidate, metadata)
total_bytes += size
if total_bytes > MAX_INSTALL_TOTAL_BYTES:
raise VerificationError("installed dependency tree exceeds its size limit")
records.append((relative, "file", mode, size, file_digest))
else:
raise VerificationError("installed dependency tree contains a special file")
if len(records) > MAX_INSTALL_ENTRIES:
raise VerificationError("installed dependency tree has too many entries")
digest = hashlib.sha256()
for record in sorted(records):
digest.update(json.dumps(record, ensure_ascii=False, separators=(",", ":")).encode("utf-8"))
digest.update(b"\n")
return {"sha256": digest.hexdigest(), "entries": len(records), "bytes": total_bytes}
def archive_digest(archive: Path) -> str:
digest = hashlib.sha256()
with archive.open("rb") as source:
while block := source.read(1024 * 1024):
digest.update(block)
return digest.hexdigest()
def expected_receipt(
archive: Path,
root: Path,
package_manifest: dict,
allowed_peers: dict[str, tuple[str, Path]],
lock_packages: int,
) -> dict:
package_name = package_manifest.get("name")
package_version = package_manifest.get("version")
if not isinstance(package_name, str) or not isinstance(package_version, str):
raise VerificationError("package.json has no exact package identity")
return {
"schemaVersion": 1,
"archiveSha256": archive_digest(archive),
"package": {"name": package_name, "version": package_version},
"allowedPeers": [
{"name": name, "version": version}
for name, (version, _) in sorted(allowed_peers.items())
],
"verifiedLockPackages": lock_packages,
"tree": installed_tree(root),
}
def write_private_json(path: Path, value: dict) -> None:
if not path.is_absolute():
raise VerificationError("plugin integrity receipt path must be absolute")
parent = path.parent.resolve(strict=True)
if not parent.is_dir():
raise VerificationError("plugin integrity receipt parent must be a directory")
descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=parent)
temporary = Path(temporary_name)
try:
if hasattr(os, "fchmod"):
os.fchmod(descriptor, 0o600)
payload = json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8") + b"\n"
with os.fdopen(descriptor, "wb") as destination:
descriptor = -1
destination.write(payload)
destination.flush()
os.fsync(destination.fileno())
os.replace(temporary, path)
if os.name != "nt":
path.chmod(0o600)
finally:
if descriptor >= 0:
os.close(descriptor)
try:
temporary.unlink()
except FileNotFoundError:
pass
def bind_receipt(
receipt: Path | None,
write_receipt: Path | None,
required: bool,
expected: dict,
) -> bool:
if receipt is not None and write_receipt is not None:
raise VerificationError("choose either receipt verification or receipt recording")
if write_receipt is not None:
write_private_json(write_receipt, expected)
receipt = write_receipt
if receipt is None:
if required:
raise VerificationError("installed lock dependencies require an integrity receipt")
return False
if not receipt.exists():
if required:
raise VerificationError("installed lock dependency integrity receipt is missing")
return False
observed = installed_json(receipt, "plugin integrity receipt")
if os.name != "nt" and stat.S_IMODE(receipt.lstat().st_mode) & 0o077:
raise VerificationError("plugin integrity receipt permissions are not private")
if observed != expected:
raise VerificationError("installed plugin tree differs from its integrity receipt")
return True
def verify(
archive: Path,
root: Path,
allowed_peers: dict[str, tuple[str, Path]] | None = None,
receipt: Path | None = None,
write_receipt: Path | None = None,
) -> dict[str, int | bool]:
archive = archive.resolve(strict=True)
root = root.resolve(strict=True)
if not archive.is_file() or not root.is_dir():
raise VerificationError("archive and installed root must exist")
files = 0
total_bytes = 0
saw_package_json = False
omitted_optional: set[Path] = set()
with tarfile.open(archive, mode="r:gz") as bundle:
raw_members = bundle.getmembers()
if len(raw_members) > MAX_MEMBERS:
raise VerificationError("archive has too many members")
members: dict[Path, tarfile.TarInfo] = {}
for member in raw_members:
relative = package_relative(member.name)
if relative in members:
raise VerificationError(f"archive contains a duplicate member: {relative}")
members[relative] = member
optional_roots, archived_shrinkwrap = archive_install_metadata(bundle, members)
package_member = members.get(Path("package.json"))
if package_member is None:
raise VerificationError("archive does not contain package.json")
package_manifest = archive_json(bundle, package_member, "package.json")
omitted_peer_metadata = 0
for relative, member in members.items():
destination = root / relative
if absent_optional_root(relative, root, optional_roots):
omitted_optional.add(next(value for value in optional_roots if relative == value or value in relative.parents))
continue
try:
resolved_parent = destination.parent.resolve(strict=True)
resolved_parent.relative_to(root)
except (FileNotFoundError, ValueError) as exc:
raise VerificationError(f"installed path escapes or is missing: {relative}") from exc
if member.isdir():
if not destination.is_dir():
raise VerificationError(f"installed directory is missing: {relative}")
continue
if member.issym():
if not destination.is_symlink() or destination.readlink().as_posix() != member.linkname:
raise VerificationError(f"installed symlink differs: {relative}")
continue
if not member.isfile():
raise VerificationError(f"unsupported archive member type: {relative}")
if member.size > MAX_FILE_BYTES:
raise VerificationError(f"archive member is too large: {relative}")
total_bytes += member.size
if total_bytes > MAX_TOTAL_BYTES:
raise VerificationError("archive payload is too large")
extracted = bundle.extractfile(member)
if extracted is None:
raise VerificationError(f"archive member cannot be read: {relative}")
expected_digest = digest_stream(extracted, member.size)
if destination.is_symlink() or not destination.is_file():
raise VerificationError(f"installed file is missing or linked: {relative}")
if relative == Path("npm-shrinkwrap.json") and archived_shrinkwrap is not None:
omitted_peer_metadata = verify_installed_shrinkwrap(
bundle, members, archived_shrinkwrap, destination, root,
)
files += 1
saw_package_json = saw_package_json or relative.as_posix() == "package.json"
continue
if destination.stat().st_size != member.size:
raise VerificationError(f"installed file size differs: {relative}")
actual_digest = hashlib.sha256(destination.read_bytes()).hexdigest()
if actual_digest != expected_digest:
raise VerificationError(f"installed file digest differs: {relative}")
files += 1
saw_package_json = saw_package_json or relative.as_posix() == "package.json"
linked_peers, lock_packages = verify_installed_inventory(
root, members, package_manifest, allowed_peers or {}, archived_shrinkwrap,
)
if not saw_package_json or files == 0:
raise VerificationError("archive does not contain a package.json payload")
receipt_bound = False
if lock_packages > 0 or receipt is not None or write_receipt is not None:
receipt_value = expected_receipt(archive, root, package_manifest, allowed_peers or {}, lock_packages)
receipt_bound = bind_receipt(receipt, write_receipt, lock_packages > 0, receipt_value)
return {
"verifiedFiles": files,
"verifiedBytes": total_bytes,
"omittedOptionalPackages": len(omitted_optional),
"omittedPeerMetadata": omitted_peer_metadata,
"linkedPeers": linked_peers,
"verifiedLockPackages": lock_packages,
"receiptBound": receipt_bound,
}
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--allowed-peer", action="append", default=[], metavar="NAME@VERSION=ABSOLUTE_PATH")
receipts = parser.add_mutually_exclusive_group()
receipts.add_argument("--receipt", type=Path)
receipts.add_argument("--write-receipt", type=Path)
parser.add_argument("archive", type=Path)
parser.add_argument("installed_root", type=Path)
args = parser.parse_args()
try:
result = verify(
args.archive,
args.installed_root,
parse_allowed_peers(args.allowed_peer),
receipt=args.receipt,
write_receipt=args.write_receipt,
)
except (VerificationError, OSError, tarfile.TarError) as exc:
print(f"plugin archive verification failed: {exc}", file=sys.stderr)
return 1
print(json.dumps(result, sort_keys=True))
return 0
if __name__ == "__main__":
raise SystemExit(main())