refactor(#4653): make containment ONE decision, resolved two ways
Satisfies #4653 DW1 and DW9, which were the phase's outstanding acceptance criteria: every other implementation must be deleted or route its containment DECISION through the canonical predicate, and no surviving wrapper may decide WHETHER a path is contained. Three implementations were being retained with their own comparisons, on the argument that each needs LEXICAL resolution — a realpath-based predicate is the wrong tool wherever a symlink must be preserved rather than resolved. That argument is correct about RESOLUTION and was being used to justify owning the DECISION too. Those are separable, and separating them is what closes the criteria honestly rather than by reinterpretation. isContainedIn(resolvedTarget, resolvedRoot, pathImpl?) module-internal is now the single place this repo decides containment. It is separator-aware, so a sibling merely sharing a prefix (`<root>-evil` against `<root>`) is still rejected. Two exported families sit on it and differ ONLY in how a candidate is resolved before the decision: assertWithinRoot / tryWithinRoot realpath-resolving assertWithinRootLexical / tryWithinRootLexical path.resolve only, no I/O The lexical pair carries `opts.pathImpl`, so win32 separator semantics stay testable off Windows — that seam already existed in isPathConfined and would have been lost by a naive collapse. The three call sites now take their decision from the predicate and keep only what is genuinely theirs: external-descriptor-trust isPathConfined delegates outright; pathImpl forwarded installer-migrations ensureInsideConfig delegates; keeps its own message and its LEXICAL fullPath, which callers consume for existsSync and journal rows gsd-tools.cjs isInsideDir delegates; keeps its own `target !== root` condition, and the separate symlink refusal above it stands DW5 is not weakened by this. That criterion binds the symlink oracle and the ancestor canonicalization; both are untouched. The only change inside validatePath is three comparison lines becoming one call, and the rejection string `Path escapes allowed directory: <resolved> is outside <base>` stays byte-identical because it is an observable CLI contract. What this does NOT do, stated plainly: the lexical family still cannot see a symlink. That is a property of lexical resolution, not a gap in the seam, and the three callers that need it are the three that must pair it with their own symlink refusal — which is exactly what the fix earlier in this phase added at the install sites. The doc comment says so at the definition, and CONTEXT.md and docs/explanation/security-model.md are corrected: they previously described these three as deliberately NOT routed through the predicate, which is no longer true. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -19,6 +19,7 @@ import {
|
||||
import { platformWriteSync, retryRenameSync, posixNormalize } from './shell-command-projection.cjs';
|
||||
import { realClock, type Clock } from './clock.cjs';
|
||||
import { isInstallScopeId, type InstallScope } from './install-scope.cjs';
|
||||
import { tryWithinRootLexical } from './security.cjs';
|
||||
// #2874 (ADR-58 cleanup phase): this file is the ~1200-line migration
|
||||
// plan/apply/rollback/lock/journal engine — almost none of it is on the
|
||||
// installRuntimeArtifacts call tree. Only `readInstallManifest` and
|
||||
@@ -664,26 +665,30 @@ interface EnsureInsideConfigResult {
|
||||
fullPath: string;
|
||||
}
|
||||
|
||||
// DELIBERATELY LEXICAL — do not route this through the canonical containment
|
||||
// predicate (`assertWithinRoot` / `tryWithinRoot`, src/security.cts).
|
||||
// DELIBERATELY LEXICAL — the RESOLUTION policy stays lexical, never realpath
|
||||
// (`assertWithinRoot` / `tryWithinRoot`, src/security.cts).
|
||||
//
|
||||
// Reviewed under epic #4636 Phase 3 and reverted after the remote matrix proved
|
||||
// the collapse wrong. This module's contract is that a symlinked managed path is
|
||||
// treated AS A LINK and never dereferenced — it is snapshotted as a link,
|
||||
// restored as a link, and backed up as a link. The canonical predicate
|
||||
// realpath-resolves, so it dereferences exactly the symlinks this module exists
|
||||
// to preserve and then rejects them for escaping configDir
|
||||
// the realpath collapse wrong. This module's contract is that a symlinked
|
||||
// managed path is treated AS A LINK and never dereferenced — it is snapshotted
|
||||
// as a link, restored as a link, and backed up as a link. The realpath-based
|
||||
// predicate dereferences exactly the symlinks this module exists to preserve
|
||||
// and then rejects them for escaping configDir
|
||||
// ("migration path escapes configDir: extensions/gsd.cjs"). Four tests in
|
||||
// tests/installer-migrations.test.cjs pin that behavior.
|
||||
//
|
||||
// The containment DECISION now routes through the canonical LEXICAL predicate
|
||||
// (`tryWithinRootLexical`, ADR-4650 decision 6) — only the comparison moved;
|
||||
// the lexical policy itself remains this module's own required choice, and
|
||||
// the thrown message / returned `fullPath` are unchanged.
|
||||
//
|
||||
// `normalizeRelPath` is the pre-gate: it throws on absolute paths and on any
|
||||
// '..' segment BEFORE this runs, so the check below is defense-in-depth over
|
||||
// already-traversal-free input rather than the primary boundary.
|
||||
function ensureInsideConfig(configDir: string, relPath: string): EnsureInsideConfigResult {
|
||||
const normalized = normalizeRelPath(relPath);
|
||||
const fullPath = path.resolve(configDir, normalized);
|
||||
const root = path.resolve(configDir);
|
||||
if (fullPath !== root && !fullPath.startsWith(root + path.sep)) {
|
||||
if (tryWithinRootLexical(fullPath, configDir) === null) {
|
||||
throw new Error(`migration path escapes configDir: ${relPath}`);
|
||||
}
|
||||
return { normalized, fullPath };
|
||||
|
||||
Reference in New Issue
Block a user