Skip to content

The agent that grows with you

14.2 KB
Raw Blame
// The folder-scoped file door behind the plugin SDK's `ctx.files`. A plugin
// names a folder handle (`'data'` = its own data folder, or the id of a folder
// the user granted it through the app's picker) plus a RELATIVE path; this
// module, in the main process, decides what that may reach:
//
// - a relative path is split into plain segments; `..`, absolute paths, drive
//   letters, UNC paths and NUL bytes are refused, never normalized away;
// - the parent of every target is realpath'd and must sit inside the folder's
//   realpath, and an existing target that is a symlink is followed only when
//   its realpath stays inside (a dangling link is refused, so a write can
//   never create the link's outside target);
// - nothing may resolve into a protected root (the Hermes homes, which hold
//   config.yaml, .env, auth and every profile; the app's own data folder,
//   which holds every plugin's data folder and the grants record), and a
//   folder overlapping one in either direction (by path, by filesystem
//   identity, as a WSL home or a loopback share) can never be granted, and
//   no op reaches a kernel pseudo-filesystem (/proc, /sys, …) by path or by
//   filesystem type;
// - reads and writes are size-capped and refused, never truncated, and the
//   app's sensitive-file rules (.env, SSH/GPG keys, .npmrc…) hold inside a
//   granted folder too; a key folder (~/.ssh, ~/.gnupg) cannot be granted.
//
// Grants live in `<userData>/plugin-files/grants.json`, written only here.
// The renderer cannot mint one: `addGrant` is reached only from the native
// folder picker the user answers (plugin-files-ipc.ts).
//
// This bounds what the DOOR can reach. It is not a sandbox for plugin code:
// a renderer-realm plugin can still call the raw `window.hermesDesktop` file
// bridge, which is why catalog admission requires the door instead.

import { randomBytes } from 'node:crypto'
import fs from 'node:fs'
import path from 'node:path'

import {
  dataDirName,
  loopbackShare,
  onPseudoFilesystem,
  overlapsByIdentity,
  pathTools,
  pluginKey,
  protectedIdentityWithin,
  realRoots,
  systemRoots,
  wslProtectedPath
} from './plugin-files-guards'
import {
  createPluginFileOps,
  errnoCode,
  fail,
  lstatOrNull,
  realpathOrNull,
  Refusal,
  refuse,
  type Resolved,
  sensitiveReason
} from './plugin-files-ops'

export const PLUGIN_DATA_FOLDER = 'data'

const GRANT_ID_RE = /^[a-f0-9]{16}$/

export type PluginFilesErrorCode =
  | 'binary'
  | 'exists'
  | 'folder-changed'
  | 'folder-missing'
  | 'invalid-op'
  | 'invalid-path'
  | 'invalid-plugin'
  | 'io-error'
  | 'is-directory'
  | 'not-a-directory'
  | 'not-a-file'
  | 'not-found'
  | 'not-granted'
  | 'outside-folder'
  | 'protected'
  | 'sensitive-file'
  | 'too-large'

export interface PluginFilesFailure {
  ok: false
  error: PluginFilesErrorCode
  message: string
}

export type PluginFilesResult<T extends object = object> = ({ ok: true } & T) | PluginFilesFailure

export interface PluginFolderGrant {
  id: string
  name: string
  path: string
  grantedAt: string
}

export type PluginFilesRequest =
  | { op: 'list'; folder: string; path: string }
  | { op: 'readDataUrl'; folder: string; path: string }
  | { op: 'readText'; folder: string; path: string }
  | { op: 'rename'; folder: string; path: string; name: string }
  | { op: 'stat'; folder: string; path: string }
  | { op: 'trash'; folder: string; path: string }
  | { op: 'writeText'; folder: string; path: string; text: string; exclusive?: boolean }

export interface PluginFilesDeps {
  /** Electron's userData dir, read lazily (main sets it before `ready`). */
  userDataDir: () => string
  /** Hermes homes (the resolved HERMES_HOME and the platform defaults). */
  protectedRoots: () => string[]
  trashItem: (target: string) => Promise<void>
  platform?: NodeJS.Platform
}

export interface PluginFiles {
  grants: (pluginId: unknown) => Promise<PluginFolderGrant[]>
  addGrant: (pluginId: unknown, picked: string) => Promise<PluginFilesResult<{ folder: PluginFolderGrant }>>
  revoke: (pluginId: unknown, folderId?: unknown) => Promise<{ ok: true; removed: number }>
  run: (pluginId: unknown, request: PluginFilesRequest) => Promise<PluginFilesResult>
}


export function createPluginFiles(deps: PluginFilesDeps): PluginFiles {
  const platform = deps.platform ?? process.platform
  const { inside, insideLoose, same, segments } = pathTools(platform)
  const baseDir = () => path.join(deps.userDataDir(), 'plugin-files')
  const storeFile = () => path.join(baseDir(), 'grants.json')

  type Store = Record<string, PluginFolderGrant[]>
  let store: null | Store = null
  let loading: null | Promise<Store> = null
  let writes: Promise<unknown> = Promise.resolve()

  // Null prototype: a plugin id such as `constructor` is just a key.
  const fresh = (grants: unknown): Store =>
    Object.assign(Object.create(null), grants && typeof grants === 'object' ? grants : {})

  const readStore = async (): Promise<Store> => {
    // A missing or unreadable-as-JSON record is no grants (fail closed). Any
    // other read error is thrown, so a later write never replaces a record
    // it could not read.
    const raw = await fs.promises.readFile(storeFile(), 'utf8').catch(error => {
      if (errnoCode(error) === 'ENOENT') {
        return '{}'
      }

      throw error
    })

    try {
      return fresh((JSON.parse(raw) as { grants?: unknown } | null)?.grants)
    } catch {
      return fresh(null)
    }
  }

  // One initial read, shared; a read finishing late never replaces a record
  // a write already published.
  const load = async (): Promise<Store> => {
    if (store) {
      return store
    }

    loading ??= readStore().finally(() => {
      loading = null
    })
    const read = await loading
    store ??= read

    return store
  }

  // Serialized read-modify-write on a copy, saved with tmp + rename, and only
  // published once saved: a failed save changes nothing, now or after restart.
  const mutate = <T>(change: (grants: Store) => T): Promise<T> => {
    const next = writes.then(async () => {
      const grants = fresh(structuredClone({ ...(await load()) }))
      const result = change(grants)
      await fs.promises.mkdir(baseDir(), { recursive: true })
      const tmp = `${storeFile()}.${process.pid}.tmp`
      await fs.promises.writeFile(tmp, JSON.stringify({ version: 1, grants }, null, 2), { mode: 0o600 })
      await fs.promises.rename(tmp, storeFile())
      store = grants

      return result
    })

    writes = next.catch(() => undefined)

    return next
  }

  const protectedRoots = async (): Promise<string[]> =>
    realRoots([...deps.protectedRoots(), deps.userDataDir(), ...systemRoots(platform)])

  // A second spelling of this machine's files that no realpath comparison can
  // match: a WSL share or a loopback/device path on Windows.
  const secondPath = (real: string) => platform === 'win32' && (wslProtectedPath(real) || loopbackShare(real))

  // Kernel pseudo-filesystems by type, so one mounted anywhere is refused.
  const refusePseudo = async (real: string) => {
    if (platform === 'linux' && (await onPseudoFilesystem(real))) {
      refuse('protected', 'That is a kernel filesystem and cannot be used by a plugin.')
    }
  }

  const overlapsProtected = (real: string, roots: string[]) =>
    roots.some(root => insideLoose(real, root) || insideLoose(root, real)) || secondPath(real)

  // The folder a handle names, as a realpath, plus the protected roots an op
  // inside it must still avoid (none for the plugin's own data folder, whose
  // root already excludes every sibling).
  const openFolder = async (pluginId: string, folder: unknown): Promise<{ root: string; avoid: string[] }> => {
    const roots = await realRoots(deps.protectedRoots())

    if (folder === PLUGIN_DATA_FOLDER) {
      const dir = path.join(baseDir(), 'data', dataDirName(pluginId))
      await fs.promises.mkdir(dir, { recursive: true })

      return { root: await fs.promises.realpath(dir), avoid: roots }
    }

    const grant =
      typeof folder === 'string' && GRANT_ID_RE.test(folder)
        ? (await load())[pluginId]?.find(row => row.id === folder)
        : undefined

    if (!grant) {
      return refuse('not-granted', 'This plugin has no access to that folder.')
    }

    const real = await realpathOrNull(grant.path)

    if (!real) {
      return refuse('folder-missing', 'The granted folder no longer exists.')
    }

    // A grant is to the folder the user picked, not to whatever a path later
    // resolves to (a folder swapped for a link into another tree).
    if (!same(real, grant.path)) {
      return refuse('folder-changed', 'The granted folder was moved or replaced; grant it again.')
    }

    const avoid = await protectedRoots()

    if (overlapsProtected(real, avoid)) {
      return refuse('protected', 'That folder overlaps Hermes data and cannot be used by a plugin.')
    }

    await refusePseudo(real)

    return { root: real, avoid }
  }

  const resolve = async (pluginId: string, folder: unknown, rel: unknown): Promise<Resolved> => {
    const parts = segments(rel)
    const { root, avoid } = await openFolder(pluginId, folder)

    const guard = (real: string) => {
      if (!inside(real, root)) {
        refuse('outside-folder', 'That path leaves the folder.')
      }

      if (avoid.some(protectedRoot => insideLoose(real, protectedRoot)) || secondPath(real)) {
        refuse('protected', 'That path is Hermes data and cannot be used by a plugin.')
      }
    }

    // Hermes data mounted inside the folder keeps an inside path; its
    // filesystem identity gives it away.
    const refuseMounted = async (real: string) => {
      if (await protectedIdentityWithin(real, root, avoid)) {
        refuse('protected', 'That path is Hermes data mounted inside the folder and cannot be used by a plugin.')
      }
    }

    if (parts.length === 0) {
      return { root, parts, parent: null, entry: root, target: root, stat: await fs.promises.stat(root) }
    }

    const parent = await realpathOrNull(path.join(root, ...parts.slice(0, -1)))

    if (!parent) {
      return refuse('not-found', 'The parent folder does not exist.')
    }

    guard(parent)

    const entry = path.join(parent, parts[parts.length - 1])
    const lstat = await lstatOrNull(entry)

    if (!lstat) {
      await refuseMounted(parent)

      return { root, parts, parent, entry, target: entry, stat: null }
    }

    // Every existing entry is checked by its realpath: a symlink's target, and
    // the long, correctly-cased name behind a Windows short name (`ENV~1`).
    const target = await realpathOrNull(entry)

    if (!target) {
      return refuse('outside-folder', 'That link points nowhere inside the folder.')
    }

    guard(target)
    await refusePseudo(target)
    await refuseMounted(target)

    // The realpath itself, not followed: a link here now means the path was
    // swapped after it was resolved. The ops re-check it after they open.
    const stat = await fs.promises.lstat(target)

    if (stat.isSymbolicLink()) {
      return refuse('outside-folder', 'The file changed while it was being checked.')
    }

    return { root, parts, parent, entry, target, stat }
  }

  const OPS = createPluginFileOps({ resolve, inside, segments, trashItem: deps.trashItem })

  const answer = async <T>(work: () => Promise<T>): Promise<PluginFilesFailure | T> => {
    try {
      return await work()
    } catch (error) {
      if (error instanceof Refusal) {
        return error.failure
      }

      const code = errnoCode(error)

      return code === 'ENOENT' || code === 'ENOTDIR'
        ? fail('not-found', 'No such file or folder.')
        : code === 'EEXIST'
          ? fail('exists', 'A file with that name already exists.')
          : fail('io-error', error instanceof Error ? error.message : String(error))
    }
  }

  return {
    async grants(pluginId) {
      const key = typeof pluginId === 'string' ? pluginId : ''

      return [...((await load())[key] ?? [])]
    },

    addGrant: (pluginId, picked) =>
      answer(async () => {
        const key = pluginKey(pluginId)
        const real = await realpathOrNull(String(picked || ''))

        if (!real || !(await fs.promises.stat(real)).isDirectory()) {
          return fail('not-a-directory', 'Pick a folder.')
        }

        if ((await realRoots(systemRoots(platform))).some(root => insideLoose(real, root))) {
          return fail('protected', 'That is a system folder and cannot be shared with a plugin.')
        }

        const roots = await protectedRoots()

        if (overlapsProtected(real, roots) || (await overlapsByIdentity(real, roots))) {
          return fail('protected', 'That folder holds Hermes data and cannot be shared with a plugin.')
        }

        await refusePseudo(real)

        if (sensitiveReason(path.join(real, 'entry')) || sensitiveReason(real)) {
          return fail('protected', 'That folder holds keys or credentials and cannot be shared with a plugin.')
        }

        return mutate(grants => {
          const rows = (grants[key] ??= [])
          const existing = rows.find(row => same(row.path, real))

          if (existing) {
            return { ok: true as const, folder: { ...existing } }
          }

          const folder = {
            id: randomBytes(8).toString('hex'),
            name: path.basename(real) || real,
            path: real,
            grantedAt: new Date().toISOString()
          }

          rows.push(folder)

          return { ok: true as const, folder: { ...folder } }
        })
      }),

    revoke: (pluginId, folderId) =>
      mutate(grants => {
        const key = typeof pluginId === 'string' ? pluginId : ''
        const rows = grants[key] ?? []
        const kept = folderId === undefined ? [] : rows.filter(row => row.id !== folderId)

        if (kept.length) {
          grants[key] = kept
        } else {
          delete grants[key]
        }

        return { ok: true as const, removed: rows.length - kept.length }
      }),

    run: (pluginId, request) =>
      answer(async () => {
        const key = pluginKey(pluginId)
        const op = request && typeof request === 'object' ? request.op : undefined

        if (typeof op !== 'string' || !Object.prototype.hasOwnProperty.call(OPS, op)) {
          return fail('invalid-op', 'Unknown file operation.')
        }

        return OPS[op](key, request)
      })
  }
}