Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

19.4 KB
Raw Blame
/** Filename validation, containment checks, and approved asset resolution. */
import { existsSync, statSync } from 'fs';
import { basename, join, resolve as resolvePath, sep as PATH_SEP } from 'path';
import { platform } from 'os';
import { ServerError } from './errorHandler.js';
import { PATHS } from './paths.js';
import { escapeRegExp } from './textUtils.js';

/**
 * Validate a user-supplied filename is a safe basename with one of the
 * allowed extensions — refuses path-traversal, null bytes, separators, and
 * exact `.` / `..`. Throws a 400 ServerError with code VALIDATION_ERROR
 * so calling routes don't have to repeat the check.
 *
 * Consolidates the two near-identical assertions that used to live in
 * `services/loras.js#assertSafeLoraFilename` (`.safetensors` only) and
 * `services/imageGen/local.js#assertGalleryFilename` (`.png` only).
 *
 * Substring `..` is intentionally allowed (e.g. `foo..bar.png` is fine);
 * only the exact-string traversal cases are rejected. Path separators (`/`
 * and `\`) are rejected on every platform — the same input gets posted
 * from Windows clients too.
 *
 * @param {string} filename
 * @param {{ extensions: string[], subject?: string, requiredMessage?: string }} opts
 *   - `extensions`: list of allowed extensions including the leading dot
 *     (`['.png']`, `['.safetensors']`, etc.). Case-insensitive match. Each
 *     entry MUST be a non-empty string starting with `.` — otherwise a bare
 *     suffix like `'png'` would also match `'not-an-imagepng'` and weaken
 *     the validation, so we treat that as a programmer error and throw.
 *   - `subject`: optional noun for the error message ("LoRA filename" →
 *     "Invalid LoRA filename"). Defaults to "filename".
 *   - `requiredMessage`: optional exact message used when `filename` is
 *     missing/empty — preserves backward-compat for wrappers that used to
 *     throw a specific phrase. The gallery wrapper passes `'Invalid filename'`
 *     (its pre-refactor implementation threw that for every failure, including
 *     missing-input); the LoRA wrapper passes `'Filename required'` to match
 *     its historical wording. When omitted, the message is derived from
 *     `subject` (e.g. `'Filename required'` / `'LoRA filename required'`).
 */
export function assertSafeFilename(filename, { extensions, subject = 'filename', requiredMessage } = {}) {
  if (!Array.isArray(extensions) || extensions.length === 0) {
    throw new Error('assertSafeFilename: extensions allowlist is required');
  }
  for (const ext of extensions) {
    if (typeof ext !== 'string' || ext.length < 2 || !ext.startsWith('.')) {
      throw new Error(`assertSafeFilename: each extension must be a non-empty string starting with "." (got ${JSON.stringify(ext)})`);
    }
  }
  const subjectText = subject || 'filename';
  if (!filename || typeof filename !== 'string') {
    const Subject = `${subjectText[0].toUpperCase()}${subjectText.slice(1)}`;
    const message = typeof requiredMessage === 'string' && requiredMessage.length > 0
      ? requiredMessage
      : `${Subject} required`;
    throw new ServerError(message, { status: 400, code: 'VALIDATION_ERROR' });
  }
  // Null bytes terminate C strings — some POSIX syscalls treat the prefix
  // as a separate path. Reject up front so it can't reach the FS layer.
  if (filename.includes('\0')) {
    throw new ServerError(`Invalid ${subjectText}`, { status: 400, code: 'VALIDATION_ERROR' });
  }
  if (!isSafeFilename(filename, extensions)) {
    throw new ServerError(`Invalid ${subjectText}`, { status: 400, code: 'VALIDATION_ERROR' });
  }
}

/**
 * `assertSafeFilename`'s non-throwing twin: the same rule as a predicate, for
 * callers that must report a bad name as *data* rather than fail the request —
 * e.g. a read-only preflight that names one corrupt record as a blocked row
 * instead of 400-ing the whole sweep. Both share this implementation so the
 * thrown gate and the reported verdict can never disagree.
 *
 * Rejects: empty/non-string, null bytes (they terminate C strings, so some
 * POSIX syscalls treat the prefix as a separate path), `.`/`..`, any path
 * separator, anything that isn't already a pure basename, and any extension
 * outside `extensions`. The basename equality check is kept alongside the
 * separator check so e.g. `subdir\foo.png` is rejected on both counts.
 *
 * `extensions` must be dot-prefixed, and unlike `assertSafeFilename` this does
 * not police that for you — a bare suffix like `png` would also match
 * `not-an-imagepng`. Pass a module constant, never a caller-supplied list.
 */
export function isSafeFilename(filename, extensions) {
  if (!isTopLevelEntryName(filename)) return false;
  const lower = filename.toLowerCase();
  return extensions.some((ext) => lower.endsWith(String(ext).toLowerCase()));
}

/**
 * `isSafeFilename`'s traversal half, without the extension gate: true when
 * `name` addresses exactly one entry directly inside some directory.
 *
 * For callers that legitimately cannot allowlist extensions — an arbitrary
 * user asset, or a directory entry — but must still refuse traversal. Naming
 * a single entry is what makes a subsequent `join(dir, name)` safe *in the
 * filesystem sense* and not just lexically: with no separator there is no
 * intermediate component left for a symlink to redirect, which a
 * `resolve`/`relative` containment check cannot see. The Data Manager's
 * per-item purge (`purgeCategory`) is the reference caller.
 *
 * `isSafeFilename` is layered on top of this, so the two can never disagree
 * about what "a single entry" means.
 */
export function isTopLevelEntryName(name) {
  if (!name || typeof name !== 'string') return false;
  if (name.includes('\0')) return false;
  if (name === '.' || name === '..') return false;
  if (name.includes('/') || name.includes('\\')) return false;
  return basename(name) === name;
}

/**
 * True when `candidatePath` resolves to a location strictly inside `dir`.
 *
 * The root itself is NOT reported as "inside", which is the desired behavior
 * for file containment. `pathContainment.js` owns the root-inclusive variant
 * (`isPathAtOrInsideDir`) for guards that police a whole tree; the two are
 * deliberately separate declarations rather than one importing the other,
 * because that module is a leaf `fileCore.js` reaches and this one drags
 * `errorHandler`/`paths` — see the budget in `importScoping.test.js`.
 *
 * Uses an anchored-prefix idiom (`resolvePath(dir) + PATH_SEP`): appending the
 * platform separator means a sibling whose name merely *starts with* the root
 * (`/data/uploads-evil` vs `/data/uploads`) can't slip past a bare
 * `startsWith(root)` check.
 *
 * Comparison is case-INSENSITIVE on Windows and macOS, whose filesystems are.
 * A bare `startsWith` there reports `C:\\Users\\Foo\\wt` as outside
 * `C:\\Users\\foo`, even though both name the same directory — so a managed
 * worktree read as `worktree-unmanaged-location` and was silently never reaped.
 * Case-folding only ever makes containment recognize paths that ARE the same
 * file on that platform; it can never admit a path from outside the root, so
 * the security posture is unchanged. Linux stays case-sensitive.
 *
 * @param {string} dir - the containing directory (absolute or relative)
 * @param {string} candidatePath - the path to test
 * @returns {boolean}
 */
const CASE_INSENSITIVE_FS = platform() === 'win32' || platform() === 'darwin';

export function isPathInsideDir(dir, candidatePath) {
  if (typeof dir !== 'string' || typeof candidatePath !== 'string' || !dir || !candidatePath) {
    return false;
  }
  const fold = (p) => (CASE_INSENSITIVE_FS ? p.toLowerCase() : p);
  const rootPrefix = fold(resolvePath(dir) + PATH_SEP);
  return fold(resolvePath(candidatePath)).startsWith(rootPrefix);
}

/**
 * Build a single-root path resolver that returns a function with the same
 * signature as `resolveGalleryImage` / `resolveImageRef` / `resolveTemplateAsset`.
 *
 * Defense in depth (applied on every call):
 *  1. `basename()` strips dirs (so `../../etc/passwd` → `passwd`).
 *  2. Reject `.`/`..`/empty basenames outright.
 *  3. `resolve` + `startsWith(rootPrefix)` so unicode tricks can't escape.
 *  4. Optional extension allow-list (case-insensitive) before any FS syscall.
 *  5. When `mustExist`, `statSync({ throwIfNoEntry: false }).isFile()` rejects
 *     directories (the root itself would otherwise pass an existsSync check
 *     and flow into ffmpeg / image-gen as an "image path" where it'd fail in
 *     confusing ways). Note: `statSync` follows symlinks, so a symlink under
 *     the root pointing to a regular file outside still passes. PortOS is
 *     single-user (see AGENTS.md "Security Model") so we accept that — for
 *     symlink rejection, swap to `lstatSync`.
 *
 * Pass `{ mustExist: false }` at call time for code paths that intentionally
 * skip the existence check (e.g. when the path is resolved at request time
 * but read later — TOCTOU between resolve and use isn't worth the extra
 * syscall, and the downstream renderer surfaces a clear error if the file
 * vanished).
 *
 * @param {() => string} getRoot - Thunk returning the absolute directory.
 *   A thunk (not a literal) so tests that mutate `PATHS.x` at mock-eval
 *   time still steer the resolver — the value is captured on first call
 *   and cached thereafter (recomputed only if the thunk later returns a
 *   different value, which production code never does).
 * @param {object} [opts]
 * @param {string[]} [opts.extensions] - allowed extensions WITHOUT the leading
 *   dot (`['png', 'jpg', 'jpeg', 'webp']`). When omitted, all extensions are
 *   accepted (matches the legacy gallery/refs behavior — extension checks
 *   happen elsewhere on those paths).
 * @param {boolean} [opts.cache=false] - Memoize successful resolutions. Only
 *   safe for shipped/stable assets (templates) where the basename → path
 *   binding is stable for the process lifetime; never enable for user-mutable
 *   dirs (gallery, refs) since deletions would be masked.
 * @returns {(name: string, opts?: { mustExist?: boolean }) => string|null}
 */
export function makePathResolver(getRoot, { extensions, cache = false } = {}) {
  if (typeof getRoot !== 'function') {
    throw new Error('makePathResolver: getRoot must be a function returning the root dir');
  }
  // Escape regex metacharacters in each extension before interpolating —
  // current callers pass plain alphanumeric tokens (png/jpg/jpeg/webp), but
  // the exported factory shouldn't behave incorrectly if a future caller
  // passes an extension containing `.`/`+`/etc.
  const extRegex = Array.isArray(extensions) && extensions.length > 0
    ? new RegExp(`\\.(${extensions
      .map((e) => escapeRegExp(String(e).replace(/^\./, '')))
      .join('|')})$`, 'i')
    : null;
  const memo = cache ? new Map() : null;
  // Resolved-root cache so the hot path doesn't re-run `resolvePath(root) +
  // PATH_SEP` per call. Recomputes only when `getRoot()` returns a different
  // value — picks up test-time `PATHS.x = ...` mutation on first call, then
  // stays warm for the rest of the process.
  let _root = null;
  let _rootAbsPrefix = null;

  return (name, { mustExist = true } = {}) => {
    if (typeof name !== 'string' || !name) return null;
    const safe = basename(name);
    if (!safe || safe === '.' || safe === '..') return null;
    if (extRegex && !extRegex.test(safe)) return null;
    // Refresh the root cache BEFORE the memo lookup so a getRoot() that
    // suddenly returns a new value (e.g. a test re-mocks `PATHS.x` mid-run)
    // invalidates the memo too — otherwise the old root's cached
    // resolutions would shadow the new root forever.
    const root = getRoot();
    if (root !== _root) {
      _root = root;
      _rootAbsPrefix = resolvePath(root) + PATH_SEP;
      if (memo) memo.clear();
    }
    const cacheKey = memo ? (mustExist ? `must:${safe}` : `nostat:${safe}`) : null;
    if (memo && memo.has(cacheKey)) return memo.get(cacheKey);
    const localPath = resolvePath(join(root, safe));
    if (!localPath.startsWith(_rootAbsPrefix)) return null;
    if (!mustExist) {
      if (memo) memo.set(cacheKey, localPath);
      return localPath;
    }
    // throwIfNoEntry:false swallows ENOENT but not EACCES / transient I/O —
    // treat those as "not a valid reference" too rather than bubbling a 500
    // out of the route layer.
    let resolved = null;
    try {
      const stat = statSync(localPath, { throwIfNoEntry: false });
      resolved = stat?.isFile() ? localPath : null;
    } catch { /* falls through to null */ }
    // Only cache successful resolutions — a missing-then-installed asset
    // should pick up on the next call (e.g. setup-data.js racing a render).
    if (memo && resolved) memo.set(cacheKey, resolved);
    return resolved;
  };
}

/**
 * Resolve a user-supplied gallery image filename to an absolute path under
 * `PATHS.images`. Returns `null` on any failure so callers can decide whether
 * to throw, log-and-skip, or substitute a fallback. See `makePathResolver`
 * for the defense-in-depth checks. Late-binds via a thunk so tests that
 * mutate `PATHS.images` at mock-eval time still steer the resolver.
 */
export const resolveGalleryImage = makePathResolver(() => PATHS.images);

/**
 * Resolve a user-supplied reference-image filename to an absolute path under
 * `PATHS.imageRefs`. Multi-reference uploads land in a sibling dir to keep
 * them out of the gallery enumeration; same defense-in-depth as the gallery
 * resolver but anchored at the refs root.
 */
export const resolveImageRef = makePathResolver(() => PATHS.imageRefs);

/**
 * Resolve an Image Cleaner temp init/result filename to an absolute path under
 * `PATHS.imageCleanTmp` (issue #2264). The GPU FLUX round-trip stages the
 * sync-cleaned init bytes here and renders the result back here, so the runner
 * must accept this root as a valid `initImagePath` source. Same defense-in-depth
 * as the gallery/refs resolvers, anchored at the temp root.
 */
export const resolveImageCleanTmp = makePathResolver(() => PATHS.imageCleanTmp);

/**
 * Resolve a peer-uploaded conditioning image staged under
 * `PATHS.federatedMediaInbox` to an absolute path. The provider maps an
 * accepted asset id onto one of these before handing the job to the local
 * generator, so the runner must accept this root as a valid `initImagePath` /
 * reference / keyframe source.
 *
 * Extension-restricted at the resolver rather than only at upload: the upload
 * endpoint already MIME-allowlists, but this is the boundary the *runner*
 * crosses, and a second check here means a hand-written file in the inbox still
 * cannot become an arbitrary path argument to the generator.
 */
export const resolveFederatedMediaAsset = makePathResolver(() => PATHS.federatedMediaInbox, {
  extensions: ['png', 'jpg', 'jpeg', 'webp'],
});

/**
 * Resolve a sprite reference asset used as an image-gen init image (issue
 * #2896 — anchors i2i from the locked main reference; uploaded design
 * references). `data/sprites/` is a server-managed NESTED tree, so unlike
 * the single-level basename resolvers above this accepts only an absolute
 * path already inside the sprites root (no basename fallback — a bare
 * filename is ambiguous across records) and validates containment.
 */
export function resolveSpriteImageInput(rawPath) {
  if (typeof rawPath !== 'string' || !rawPath) return null;
  const resolved = resolvePath(rawPath);
  return isPathInsideDir(PATHS.sprites, resolved) ? resolved : null;
}

/**
 * Resolve a shipped visual template filename (e.g. character reference-sheet
 * layout PNG) to an absolute path under `PATHS.visualTemplates`. Caches
 * successful resolutions because the template assets are shipped and stable
 * for the lifetime of the process — keeps reference-sheet rendering off the
 * statSync hot path.
 */
export const resolveTemplateAsset = makePathResolver(() => PATHS.visualTemplates, {
  extensions: ['png', 'jpg', 'jpeg', 'webp'],
  cache: true,
});

/**
 * Resolve a user-supplied screenshot filename to an absolute path under
 * `PATHS.screenshots`. Used by the vision-test endpoint, whose `imagePath`
 * comes straight from `req.body` — basenaming the input (and rejecting any
 * non-image extension or missing file) stops `../` traversal and absolute-path
 * escapes from reading arbitrary files off disk and forwarding their contents
 * to an external vision provider. Returns `null` on any failure so the caller
 * can surface a clean error. See `makePathResolver` for the defense-in-depth
 * checks. Late-binds via a thunk so tests that mutate `PATHS.screenshots` still
 * steer the resolver.
 */
export const resolveScreenshot = makePathResolver(() => PATHS.screenshots, {
  extensions: ['png', 'jpg', 'jpeg', 'gif', 'webp'],
});

/**
 * Resolve any user-supplied image input (init image OR multi-reference image)
 * to an absolute path under one of PortOS's approved image roots — the
 * gallery (`PATHS.images`), the multi-ref upload dir (`PATHS.imageRefs`),
 * or the shipped visual-template dir (`PATHS.visualTemplates`). Used by the
 * image-gen runner to re-validate paths that originated from internal
 * features (gallery picks, reference-sheet renders) which may legitimately
 * cross dir boundaries.
 *
 * Accepts both basename input (`"foo.png"`) and already-resolved absolute
 * paths (the local image-gen runner re-validates the same input on every
 * call so we need to accept both shapes).
 *
 * @param {string} rawPath - basename or absolute path
 * @returns {string|null} validated absolute path, or null
 */
// Pairs of (PATHS-key, resolver). Read PATHS at CALL time so tests that
// mutate `PATHS.x` at mock-eval time still steer the prefix dispatch — a
// module-load snapshot would freeze the pre-mock paths.
const IMAGE_INPUT_RESOLVERS = [
  ['images', resolveGalleryImage],
  ['imageRefs', resolveImageRef],
  ['visualTemplates', resolveTemplateAsset],
  // Image Cleaner temp init images (issue #2264) — the GPU FLUX round-trip
  // stages sync-cleaned bytes here as the img2img init.
  ['imageCleanTmp', resolveImageCleanTmp],
  // Peer-uploaded conditioning images (#4348) — an allowlisted peer's init /
  // reference / keyframe bytes, staged for the one federated render they were
  // uploaded for.
  ['federatedMediaInbox', resolveFederatedMediaAsset],
  // Sprite reference assets (issue #2896) — the locked main reference /
  // uploaded design reference as the anchors' i2i init. Absolute-only
  // (returns null on basename input, so the fall-through loop skips it).
  ['sprites', resolveSpriteImageInput],
];

export function resolveImageInputPath(rawPath) {
  if (typeof rawPath !== 'string' || !rawPath) return null;
  // For ABSOLUTE inputs, dispatch by prefix. The single-root resolvers
  // basename their input for defense-in-depth, so trying them in order on an
  // absolute path can silently redirect a `/data/templates/foo.png` input
  // to `/data/images/foo.png` whenever a same-named file lives in the gallery.
  // Validate against the matching root only.
  const resolvedInput = resolvePath(rawPath);
  for (const [key, resolver] of IMAGE_INPUT_RESOLVERS) {
    const rootPrefix = resolvePath(PATHS[key]) + PATH_SEP;
    if (resolvedInput.startsWith(rootPrefix)) return resolver(rawPath);
  }
  // For basename / relative input (no matching prefix), fall through the
  // resolvers in order. First match wins; basename collisions across roots
  // are accepted as ambiguous and resolve to the first defined root.
  for (const [, resolver] of IMAGE_INPUT_RESOLVERS) {
    const candidate = resolver(rawPath);
    if (candidate) return candidate;
  }
  return null;
}