mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-21 04:09:45 +03:00
00953653cf
A git install of a plugin now refuses a package whose folder name is not a
plain folder name, before anything in desktop-plugins is touched. The name
comes from the repository (the manifest's `name`, or a subdirectory's last
segment) and was joined to the desktop-plugins root unchecked, so a package
named `..` made a forced install remove and replace the Hermes home, on
every OS; `a/b` nested a folder, and on Windows `C:..` or a device name like
`nul .js` reach somewhere else entirely.
The check refuses separators, a colon, a leading or trailing dot, control
characters, more than 128 characters (code points, as the agent side's
len() counts them), and Windows device names with any extension, reusing
the device-name pattern the plugin file door already has. On Linux and
macOS this also refuses names Windows cannot use (device names, a colon, a
trailing dot), which installed before. The folder name is trimmed of what
the agent side's str.strip() removes (JS trim() differs on U+FEFF, U+0085
and U+001C-U+001F), and the package marker now records that same trimmed
name, so the folder and marker agree, as the agent side's desktop
installer writes them. When removing a standalone desktop plugin, an
existing folder's exact name removes that folder; any other name is
trimmed as the installer trims it, with the same helper (trim() on every
name turned `\ufeffgizmo` or ` gizmo ` into a `gizmo` neighbour).
Root cause: installDesktopPluginFromGit used the manifest name as a path
segment without validating it.
Regression from 359e09fd65 (#89464, @serefyarar, 2026-08-18).
254 lines
10 KiB
TypeScript
254 lines
10 KiB
TypeScript
// Path rules for the `ctx.files` door (plugin-files.ts): how a plugin-supplied
|
|
// relative path is split, how containment is compared, and which folders can
|
|
// never be granted. Pure helpers plus filesystem identity checks; no state.
|
|
|
|
import { createHash } from 'node:crypto'
|
|
import fs from 'node:fs'
|
|
import os from 'node:os'
|
|
import path from 'node:path'
|
|
|
|
import { realpathOrNull, refuse } from './plugin-files-ops'
|
|
|
|
const REL_PATH_MAX = 1024
|
|
const SEGMENT_MAX = 255
|
|
// Plugin ids become a folder name under the shared data root, so only a plain
|
|
// slug may reach the join (no separators, no leading dot, no `..`, and no
|
|
// trailing dot, which Windows drops: `foo.` would share `foo`'s folder).
|
|
const PLUGIN_ID_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9_-])?$/
|
|
// Windows device names open the device, not a file, with any extension.
|
|
export const WIN_RESERVED_RE = /^(?:con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$|clock\$)(?:\.|$)/i
|
|
// Python's str.strip() set (what the agent side's `_checked_name` trims). JS trim() differs: it also
|
|
// strips U+FEFF and keeps U+001C-U+001F and U+0085, so the two sides would name different folders.
|
|
const PY_STRIP_WS = '\\t-\\r\\x1c-\\x20\\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000'
|
|
// The trailing run must start after a non-space: a bare `[ws]+$` retries from every space of an
|
|
// inner run, which is quadratic in a repository-controlled name and blocks the main process.
|
|
const PY_STRIP_RE = new RegExp(`^[${PY_STRIP_WS}]+|(?<![${PY_STRIP_WS}])[${PY_STRIP_WS}]+$`, 'g')
|
|
|
|
/** *text* without the leading and trailing whitespace Python's `str.strip()` removes, in linear time.
|
|
* Desktop plugin folder names go through this on install and on remove, so both agree with the agent side. */
|
|
export const stripLikePython = (text: string): string => text.replace(PY_STRIP_RE, '')
|
|
// Kernel pseudo-filesystems: their files are "regular" with size 0 and can
|
|
// hold the app's own environment (`/proc/self/environ`).
|
|
const SYSTEM_ROOTS = ['/proc', '/sys', '/dev']
|
|
|
|
// The same filesystems by type, wherever they are mounted (a container's
|
|
// `/host/proc`, a chroot's `proc`): proc, sysfs, debugfs, tracefs,
|
|
// securityfs, cgroup, cgroup2, bpf, efivarfs, configfs, pstore, selinuxfs.
|
|
const PSEUDO_FS_TYPES = new Set([
|
|
0x9fa0, 0x62656572, 0x64626720, 0x74726163, 0x73636673, 0x27e0eb, 0x63677270, 0xcafe4a11, 0xde5e81e4,
|
|
0x62656570, 0x6165676c, 0xf97cff8c
|
|
])
|
|
|
|
const WSL_SHARE_RE = /^\\\\(?:wsl\.localhost|wsl\$)\\[^\\]+/i
|
|
// Top-level WSL folders that are not files of the distro: its kernel views
|
|
// (process environments included) and its mounts of the Windows drives.
|
|
const WSL_SYSTEM_DIRS = new Set(['dev', 'mnt', 'proc', 'run', 'sys'])
|
|
|
|
const within = (child: string, parent: string): boolean => {
|
|
const rel = path.relative(parent, child)
|
|
|
|
return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel))
|
|
}
|
|
|
|
export function pathTools(platform: NodeJS.Platform) {
|
|
// Every comparison errs toward refusing. Containment ("may the plugin use
|
|
// this?") compares realpaths exactly, so a case-sensitive volume's `vault`
|
|
// is never mistaken for the granted `Vault`. Protection ("is this Hermes
|
|
// data?") also matches case-insensitively where volumes usually are, so a
|
|
// differently-cased spelling of a protected path is still refused.
|
|
const caseless = platform === 'win32' || platform === 'darwin'
|
|
const inside = (child: string, parent: string) => within(child, parent)
|
|
|
|
const insideLoose = (child: string, parent: string) =>
|
|
within(child, parent) || (caseless && within(child.toLowerCase(), parent.toLowerCase()))
|
|
|
|
const same = (a: string, b: string) => path.resolve(a) === path.resolve(b)
|
|
|
|
// Split a plugin-supplied relative path into plain segments, refusing (not
|
|
// normalizing) anything that could name a place outside the folder.
|
|
const segments = (raw: unknown): string[] => {
|
|
if (typeof raw !== 'string' || raw.length > REL_PATH_MAX || raw.includes('\0')) {
|
|
return refuse('invalid-path', 'Path must be a relative path inside the folder.')
|
|
}
|
|
|
|
if (path.posix.isAbsolute(raw) || path.win32.isAbsolute(raw) || /^[a-zA-Z]:/.test(raw)) {
|
|
return refuse('invalid-path', 'Path must be relative to the folder, not absolute.')
|
|
}
|
|
|
|
const parts = raw.split(/[\\/]+/).filter(part => part && part !== '.')
|
|
|
|
for (const part of parts) {
|
|
// `..namedfork` opens a macOS file's forks under another name
|
|
// (`.env/..namedfork/data` is `.env`).
|
|
if (part === '..' || part.length > SEGMENT_MAX || part.toLowerCase() === '..namedfork') {
|
|
return refuse('invalid-path', 'Path may not leave the folder.')
|
|
}
|
|
|
|
// Windows drops trailing dots/spaces (`.. ` is `..`), reads `:` as a
|
|
// stream, and opens a device for `CON`, `NUL.txt`…
|
|
if (platform === 'win32' && (part.includes(':') || /[. ]$/.test(part) || WIN_RESERVED_RE.test(part))) {
|
|
return refuse('invalid-path', 'Path segment is not valid on Windows.')
|
|
}
|
|
}
|
|
|
|
return parts
|
|
}
|
|
|
|
return { inside, insideLoose, same, segments }
|
|
}
|
|
|
|
export const pluginKey = (pluginId: unknown): string =>
|
|
typeof pluginId === 'string' && PLUGIN_ID_RE.test(pluginId) && !WIN_RESERVED_RE.test(pluginId)
|
|
? pluginId
|
|
: refuse('invalid-plugin', 'Plugin id is not a plain slug.')
|
|
|
|
// Case-insensitive filesystems would give `Plexus` and `plexus` one folder; an
|
|
// id with capitals gets a suffix (`~` never appears in an id) to keep them apart.
|
|
export function dataDirName(pluginId: string): string {
|
|
return pluginId === pluginId.toLowerCase()
|
|
? pluginId
|
|
: `${pluginId.toLowerCase()}~${createHash('sha256').update(pluginId).digest('hex').slice(0, 8)}`
|
|
}
|
|
|
|
export const systemRoots = (platform: NodeJS.Platform): string[] => (platform === 'win32' ? [] : SYSTEM_ROOTS)
|
|
|
|
export async function realRoots(roots: string[]): Promise<string[]> {
|
|
const resolved = await Promise.all(
|
|
roots.filter(Boolean).map(async root => (await realpathOrNull(root)) ?? path.resolve(root))
|
|
)
|
|
|
|
return [...new Set(resolved)]
|
|
}
|
|
|
|
/**
|
|
* A WSL share path that is Hermes data or not the distro's own files: the
|
|
* distro root, `/home`, a home dir and `/root` each hold a `~/.hermes`, and
|
|
* anything under a `.hermes` segment is one (Windows Desktop cannot know which
|
|
* WSL user runs the gateway, so every WSL home counts); `/proc`, `/sys`,
|
|
* `/dev` and `/run` are the distro's kernel views, and `/mnt` reaches the
|
|
* Windows drives (and this app's own data) by a second spelling.
|
|
*/
|
|
export function wslProtectedPath(candidate: string): boolean {
|
|
const share = WSL_SHARE_RE.exec(candidate)
|
|
|
|
if (!share) {
|
|
return false
|
|
}
|
|
|
|
const rest = candidate
|
|
.slice(share[0].length)
|
|
.split('\\')
|
|
.filter(Boolean)
|
|
.map(part => part.toLowerCase())
|
|
|
|
const holdsHome =
|
|
rest.length === 0 ||
|
|
(rest.length === 1 && (rest[0] === 'home' || rest[0] === 'root')) ||
|
|
(rest.length === 2 && rest[0] === 'home')
|
|
|
|
return holdsHome || WSL_SYSTEM_DIRS.has(rest[0]) || rest.includes('.hermes')
|
|
}
|
|
|
|
const LOOPBACK_HOSTS = new Set(['localhost', '::1', '[::1]', '0--1.ipv6-literal.net'])
|
|
|
|
/**
|
|
* A Windows path that reaches this machine's own drives a second way, which a
|
|
* realpath comparison cannot match to the protected folders: a device path
|
|
* (`\\?\C:\`, `\\.\`, `\\?\GLOBALROOT\…` shadow copies) or a share served by
|
|
* this machine (`\\localhost\C$`, `\\127.0.0.1\…`, its own name or address).
|
|
*/
|
|
export function loopbackShare(candidate: string): boolean {
|
|
const unc = /^\\\\\?\\UNC\\/i.test(candidate) ? `\\\\${candidate.slice(8)}` : candidate
|
|
|
|
if (/^\\\\[?.]\\/.test(unc)) {
|
|
return true
|
|
}
|
|
|
|
const host = /^\\\\([^\\]+)/.exec(unc)?.[1].split('@')[0].toLowerCase()
|
|
|
|
if (!host) {
|
|
return false
|
|
}
|
|
|
|
const own = new Set([os.hostname().toLowerCase()])
|
|
|
|
for (const addresses of Object.values(os.networkInterfaces())) {
|
|
for (const address of addresses ?? []) {
|
|
own.add(address.address.toLowerCase())
|
|
}
|
|
}
|
|
|
|
return LOOPBACK_HOSTS.has(host) || /^127\./.test(host) || own.has(host) || own.has(host.split('.')[0])
|
|
}
|
|
|
|
/** True when `target` lives on a kernel pseudo-filesystem (Linux). */
|
|
export async function onPseudoFilesystem(target: string): Promise<boolean> {
|
|
const stats = await fs.promises.statfs(target).catch(() => null)
|
|
|
|
return stats !== null && PSEUDO_FS_TYPES.has(Number(stats.type))
|
|
}
|
|
|
|
const identity = async (target: string): Promise<null | string> => {
|
|
const stat = await fs.promises.stat(target).catch(() => null)
|
|
|
|
return stat ? `${stat.dev}:${stat.ino}` : null
|
|
}
|
|
|
|
// The identity of a path and of every folder above it.
|
|
async function identityChain(target: string): Promise<string[]> {
|
|
const ids: string[] = []
|
|
|
|
for (let current = target; ; current = path.dirname(current)) {
|
|
const id = await identity(current)
|
|
|
|
if (id) {
|
|
ids.push(id)
|
|
}
|
|
|
|
if (path.dirname(current) === current) {
|
|
return ids
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Overlap by filesystem identity, not spelling: a bind mount, a macOS firmlink
|
|
* (`/System/Volumes/Data/Users/…`) or a case-insensitive mount is a second
|
|
* path to the same folder that a realpath string comparison would miss.
|
|
*/
|
|
export async function overlapsByIdentity(candidate: string, roots: string[]): Promise<boolean> {
|
|
const self = await identity(candidate)
|
|
const chain = await identityChain(candidate)
|
|
|
|
for (const root of roots) {
|
|
const rootId = await identity(root)
|
|
|
|
if (rootId && (chain.includes(rootId) || (self && (await identityChain(root)).includes(self)))) {
|
|
return true
|
|
}
|
|
}
|
|
|
|
return false
|
|
}
|
|
|
|
/**
|
|
* True when `target`, or a folder between it and `root`, is one of `roots` by
|
|
* filesystem identity: a bind mount of the Hermes home inside a granted folder
|
|
* keeps an inside path but is the protected folder itself.
|
|
*/
|
|
export async function protectedIdentityWithin(target: string, root: string, roots: string[]): Promise<boolean> {
|
|
const ids = new Set((await Promise.all(roots.map(identity))).filter((id): id is string => id !== null))
|
|
|
|
for (let current = target; ; current = path.dirname(current)) {
|
|
const id = await identity(current)
|
|
|
|
if (id && ids.has(id)) {
|
|
return true
|
|
}
|
|
|
|
if (current === root || path.dirname(current) === current) {
|
|
return false
|
|
}
|
|
}
|
|
}
|