293 lines
11 KiB
TypeScript
293 lines
11 KiB
TypeScript
import { lstat, realpath } from 'fs/promises'
|
||
import { dirname, join, resolve, sep } from 'path'
|
||
import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js'
|
||
import { getErrnoCode } from '../utils/errors.js'
|
||
import { getAutoMemPath, isAutoMemoryEnabled } from './paths.js'
|
||
|
||
/**
|
||
* Error thrown when a path validation detects a traversal or injection attempt.
|
||
*/
|
||
export class PathTraversalError extends Error {
|
||
constructor(message: string) {
|
||
super(message)
|
||
this.name = 'PathTraversalError'
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Sanitize a file path key by rejecting dangerous patterns.
|
||
* Checks for null bytes, URL-encoded traversals, and other injection vectors.
|
||
* Returns the sanitized string or throws PathTraversalError.
|
||
*/
|
||
function sanitizePathKey(key: string): string {
|
||
// Null bytes can truncate paths in C-based syscalls
|
||
if (key.includes('\0')) {
|
||
throw new PathTraversalError(`Null byte in path key: "${key}"`)
|
||
}
|
||
// URL-encoded traversals (e.g. %2e%2e%2f = ../)
|
||
let decoded: string
|
||
try {
|
||
decoded = decodeURIComponent(key)
|
||
} catch {
|
||
// Malformed percent-encoding (e.g. %ZZ, lone %) — not valid URL-encoding,
|
||
// so no URL-encoded traversal is possible
|
||
decoded = key
|
||
}
|
||
if (decoded !== key && (decoded.includes('..') || decoded.includes('/'))) {
|
||
throw new PathTraversalError(`URL-encoded traversal in path key: "${key}"`)
|
||
}
|
||
// Unicode normalization attacks: fullwidth ．．／ (U+FF0E U+FF0F) normalize
|
||
// to ASCII ../ under NFKC. While path.resolve/fs.writeFile treat these as
|
||
// literal bytes (not separators), downstream layers or filesystems may
|
||
// normalize — reject for defense-in-depth (PSR M22187 vector 4).
|
||
const normalized = key.normalize('NFKC')
|
||
if (
|
||
normalized !== key &&
|
||
(normalized.includes('..') ||
|
||
normalized.includes('/') ||
|
||
normalized.includes('\\') ||
|
||
normalized.includes('\0'))
|
||
) {
|
||
throw new PathTraversalError(
|
||
`Unicode-normalized traversal in path key: "${key}"`,
|
||
)
|
||
}
|
||
// Reject backslashes (Windows path separator used as traversal vector)
|
||
if (key.includes('\\')) {
|
||
throw new PathTraversalError(`Backslash in path key: "${key}"`)
|
||
}
|
||
// Reject absolute paths
|
||
if (key.startsWith('/')) {
|
||
throw new PathTraversalError(`Absolute path key: "${key}"`)
|
||
}
|
||
return key
|
||
}
|
||
|
||
/**
|
||
* Whether team memory features are enabled.
|
||
* Team memory is a subdirectory of auto memory, so it requires auto memory
|
||
* to be enabled. This keeps all team-memory consumers (prompt, content
|
||
* injection, sync watcher, file detection) consistent when auto memory is
|
||
* disabled via env var or settings.
|
||
*/
|
||
export function isTeamMemoryEnabled(): boolean {
|
||
if (!isAutoMemoryEnabled()) {
|
||
return false
|
||
}
|
||
return getFeatureValue_CACHED_MAY_BE_STALE('tengu_herring_clock', false)
|
||
}
|
||
|
||
/**
|
||
* Returns the team memory path: <memoryBase>/projects/<sanitized-project-root>/memory/team/
|
||
* Lives as a subdirectory of the auto-memory directory, scoped per-project.
|
||
*/
|
||
export function getTeamMemPath(): string {
|
||
return (join(getAutoMemPath(), 'team') + sep).normalize('NFC')
|
||
}
|
||
|
||
/**
|
||
* Returns the team memory entrypoint: <memoryBase>/projects/<sanitized-project-root>/memory/team/MEMORY.md
|
||
* Lives as a subdirectory of the auto-memory directory, scoped per-project.
|
||
*/
|
||
export function getTeamMemEntrypoint(): string {
|
||
return join(getAutoMemPath(), 'team', 'MEMORY.md')
|
||
}
|
||
|
||
/**
|
||
* Resolve symlinks for the deepest existing ancestor of a path.
|
||
* The target file may not exist yet (we may be about to create it), so we
|
||
* walk up the directory tree until realpath() succeeds, then rejoin the
|
||
* non-existing tail onto the resolved ancestor.
|
||
*
|
||
* SECURITY (PSR M22186): path.resolve() does NOT resolve symlinks. An attacker
|
||
* who can place a symlink inside teamDir pointing outside (e.g. to
|
||
* ~/.ssh/authorized_keys) would pass a resolve()-based containment check.
|
||
* Using realpath() on the deepest existing ancestor ensures we compare the
|
||
* actual filesystem location, not the symbolic path.
|
||
*
|
||
*/
|
||
async function realpathDeepestExisting(absolutePath: string): Promise<string> {
|
||
const tail: string[] = []
|
||
let current = absolutePath
|
||
// Walk up until realpath succeeds. ENOENT means this segment doesn't exist
|
||
// yet; pop it onto the tail and try the parent. ENOTDIR means a non-directory
|
||
// component sits in the middle of the path; pop and retry so we can realpath
|
||
// the ancestor to detect symlink escapes.
|
||
// Loop terminates when we reach the filesystem root (dirname('/') === '/').
|
||
for (
|
||
let parent = dirname(current);
|
||
current !== parent;
|
||
parent = dirname(current)
|
||
) {
|
||
try {
|
||
const realCurrent = await realpath(current)
|
||
// Rejoin the non-existing tail in reverse order (deepest popped first)
|
||
return tail.length === 0
|
||
? realCurrent
|
||
: join(realCurrent, ...tail.reverse())
|
||
} catch (e: unknown) {
|
||
const code = getErrnoCode(e)
|
||
if (code === 'ENOENT') {
|
||
// Could be truly non-existent (safe to walk up) OR a dangling symlink
|
||
// whose target doesn't exist. Dangling symlinks are an attack vector:
|
||
// writeFile would follow the link and create the target outside teamDir.
|
||
// lstat distinguishes: it succeeds for dangling symlinks (the link entry
|
||
// itself exists), fails with ENOENT for truly non-existent paths.
|
||
try {
|
||
const st = await lstat(current)
|
||
if (st.isSymbolicLink()) {
|
||
throw new PathTraversalError(
|
||
`Dangling symlink detected (target does not exist): "${current}"`,
|
||
)
|
||
}
|
||
// lstat succeeded but isn't a symlink — ENOENT from realpath was
|
||
// caused by a dangling symlink in an ancestor. Walk up to find it.
|
||
} catch (lstatErr: unknown) {
|
||
if (lstatErr instanceof PathTraversalError) {
|
||
throw lstatErr
|
||
}
|
||
// lstat also failed (truly non-existent or inaccessible) — safe to walk up.
|
||
}
|
||
} else if (code === 'ELOOP') {
|
||
// Symlink loop — corrupted or malicious filesystem state.
|
||
throw new PathTraversalError(
|
||
`Symlink loop detected in path: "${current}"`,
|
||
)
|
||
} else if (code !== 'ENOTDIR' && code !== 'ENAMETOOLONG') {
|
||
// EACCES, EIO, etc. — cannot verify containment. Fail closed by wrapping
|
||
// as PathTraversalError so the caller can skip this entry gracefully
|
||
// instead of aborting the entire batch.
|
||
throw new PathTraversalError(
|
||
`Cannot verify path containment (${code}): "${current}"`,
|
||
)
|
||
}
|
||
tail.push(current.slice(parent.length + sep.length))
|
||
current = parent
|
||
}
|
||
}
|
||
// Reached filesystem root without finding an existing ancestor (rare —
|
||
// root normally exists). Fall back to the input; containment check will reject.
|
||
return absolutePath
|
||
}
|
||
|
||
/**
|
||
* Check whether a real (symlink-resolved) path is within the real team
|
||
* memory directory. Both sides are realpath'd so the comparison is between
|
||
* canonical filesystem locations.
|
||
*
|
||
* If teamDir does not exist, returns true (skips the check). This is safe:
|
||
* a symlink escape requires a pre-existing symlink inside teamDir, which
|
||
* requires teamDir to exist. If there's no directory, there's no symlink,
|
||
* and the first-pass string-level containment check is sufficient.
|
||
*/
|
||
async function isRealPathWithinTeamDir(
|
||
realCandidate: string,
|
||
): Promise<boolean> {
|
||
let realTeamDir: string
|
||
try {
|
||
// getTeamMemPath() includes a trailing separator; strip it because
|
||
// realpath() rejects trailing separators on some platforms.
|
||
realTeamDir = await realpath(getTeamMemPath().replace(/[/\\]+$/, ''))
|
||
} catch (e: unknown) {
|
||
const code = getErrnoCode(e)
|
||
if (code === 'ENOENT' || code === 'ENOTDIR') {
|
||
// Team dir doesn't exist — symlink escape impossible, skip check.
|
||
return true
|
||
}
|
||
// Unexpected error (EACCES, EIO) — fail closed.
|
||
return false
|
||
}
|
||
if (realCandidate === realTeamDir) {
|
||
return true
|
||
}
|
||
// Prefix-attack protection: require separator after the prefix so that
|
||
// "/foo/team-evil" doesn't match "/foo/team".
|
||
return realCandidate.startsWith(realTeamDir + sep)
|
||
}
|
||
|
||
/**
|
||
* Check if a resolved absolute path is within the team memory directory.
|
||
* Uses path.resolve() to convert relative paths and eliminate traversal segments.
|
||
* Does NOT resolve symlinks — for write validation use validateTeamMemWritePath()
|
||
* or validateTeamMemKey() which include symlink resolution.
|
||
*/
|
||
export function isTeamMemPath(filePath: string): boolean {
|
||
// SECURITY: resolve() converts to absolute and eliminates .. segments,
|
||
// preventing path traversal attacks (e.g. "team/../../etc/passwd")
|
||
const resolvedPath = resolve(filePath)
|
||
const teamDir = getTeamMemPath()
|
||
return resolvedPath.startsWith(teamDir)
|
||
}
|
||
|
||
/**
|
||
* Validate that an absolute file path is safe for writing to the team memory directory.
|
||
* Returns the resolved absolute path if valid.
|
||
* Throws PathTraversalError if the path contains injection vectors, escapes the
|
||
* directory via .. segments, or escapes via a symlink (PSR M22186).
|
||
*/
|
||
export async function validateTeamMemWritePath(
|
||
filePath: string,
|
||
): Promise<string> {
|
||
if (filePath.includes('\0')) {
|
||
throw new PathTraversalError(`Null byte in path: "${filePath}"`)
|
||
}
|
||
// First pass: normalize .. segments and check string-level containment.
|
||
// This is a fast rejection for obvious traversal attempts before we touch
|
||
// the filesystem.
|
||
const resolvedPath = resolve(filePath)
|
||
const teamDir = getTeamMemPath()
|
||
// Prefix attack protection: teamDir already ends with sep (from getTeamMemPath),
|
||
// so "team-evil/" won't match "team/"
|
||
if (!resolvedPath.startsWith(teamDir)) {
|
||
throw new PathTraversalError(
|
||
`Path escapes team memory directory: "${filePath}"`,
|
||
)
|
||
}
|
||
// Second pass: resolve symlinks on the deepest existing ancestor and verify
|
||
// the real path is still within the real team dir. This catches symlink-based
|
||
// escapes that path.resolve() alone cannot detect.
|
||
const realPath = await realpathDeepestExisting(resolvedPath)
|
||
if (!(await isRealPathWithinTeamDir(realPath))) {
|
||
throw new PathTraversalError(
|
||
`Path escapes team memory directory via symlink: "${filePath}"`,
|
||
)
|
||
}
|
||
return resolvedPath
|
||
}
|
||
|
||
/**
|
||
* Validate a relative path key from the server against the team memory directory.
|
||
* Sanitizes the key, joins with the team dir, resolves symlinks on the deepest
|
||
* existing ancestor, and verifies containment against the real team dir.
|
||
* Returns the resolved absolute path.
|
||
* Throws PathTraversalError if the key is malicious (PSR M22186).
|
||
*/
|
||
export async function validateTeamMemKey(relativeKey: string): Promise<string> {
|
||
sanitizePathKey(relativeKey)
|
||
const teamDir = getTeamMemPath()
|
||
const fullPath = join(teamDir, relativeKey)
|
||
// First pass: normalize .. segments and check string-level containment.
|
||
const resolvedPath = resolve(fullPath)
|
||
if (!resolvedPath.startsWith(teamDir)) {
|
||
throw new PathTraversalError(
|
||
`Key escapes team memory directory: "${relativeKey}"`,
|
||
)
|
||
}
|
||
// Second pass: resolve symlinks and verify real containment.
|
||
const realPath = await realpathDeepestExisting(resolvedPath)
|
||
if (!(await isRealPathWithinTeamDir(realPath))) {
|
||
throw new PathTraversalError(
|
||
`Key escapes team memory directory via symlink: "${relativeKey}"`,
|
||
)
|
||
}
|
||
return resolvedPath
|
||
}
|
||
|
||
/**
|
||
* Check if a file path is within the team memory directory
|
||
* and team memory is enabled.
|
||
*/
|
||
export function isTeamMemFile(filePath: string): boolean {
|
||
return isTeamMemoryEnabled() && isTeamMemPath(filePath)
|
||
}
|