Skip to content

Commit 08e774f

Browse files
committed
🐛 fix: close File containment, cleanup, and disclosure gaps
Eight corrections from review, none changing the component's API. The write form now resolves its destination after its children finish. A child can replace a directory with a symlink out of the workspace, and resolving first validated a destination the write no longer used. Temporary-file removal is registered before the temporary is written. `writeTextFile` is where an interruption is likeliest to land, and a cleanup on the far side of it did not cover the one failure it exists for. Containment diagnostics no longer carry the resolved workspace path, the destination a symlink pointed at, or a rejected absolute path — §1.2 keeps absolute paths out of diagnostics, and naming where an escape led performs the disclosure the refusal prevents. Content is written exactly as `useContent()` returns it, per #190's exact-content contract; `framed()` is gone. Only a complete `..` segment escapes, so `..notes.md` is an ordinary file rather than a rejected traversal. The replay contract distinguishes a completed-root replay, which restores without running `<File>`, from a partial replay that reaches it and repeats the read or write. `errorCode()` narrows instead of asserting `NodeJS.ErrnoException`. Tier FL grows to 22 cases; FL17–FL20 each fail against the code they replace.
1 parent fba6e04 commit 08e774f

6 files changed

Lines changed: 393 additions & 138 deletions

File tree

‎packages/core/src/components/File.test.md‎

Lines changed: 33 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -51,42 +51,58 @@ and writing the same content twice leaves the same file.
5151
</TempDir>
5252
</Test>
5353

54-
The text written is what the children rendered, with the line break after the
55-
opening tag and the one before the closing tag removed — those belong to the
56-
markup. Nothing else is touched: no trailing newline is added, and nothing is
57-
reformatted. So the two ways of writing the same file write the same bytes.
54+
What gets written is exactly what the children rendered. Nothing is added,
55+
trimmed, normalized, or reformatted — so where the tags sit is where the file's
56+
first and last bytes come from. Put the content on the same line as the tags
57+
and that is the whole file:
5858

59-
<Test name="The two authoring forms write the same bytes">
59+
<Test name="Inline content is the whole file">
6060
<TempDir>
6161
<File path="tight.txt">one line</File>
6262
<File path="tight.txt" as="tight" />
6363
<AssertEquals actual={tight} expected={"one line"} />
64+
</TempDir>
65+
</Test>
66+
67+
Put it on its own line and the line breaks around it are content too, because
68+
they are inside the element. The file starts with a newline and ends with one.
6469

70+
<Test name="Content on its own line keeps the newlines around it">
71+
<TempDir>
6572
<File path="spread.txt">
6673
one line
6774
</File>
6875
<File path="spread.txt" as="spread" />
69-
<AssertEquals actual={spread} expected={"one line"} />
76+
<AssertEquals actual={spread} expected={"\none line\n"} />
7077
</TempDir>
7178
</Test>
7279

73-
A blank line before the closing tag is content, so that is how a file ends
74-
with a newline. Indentation inside the element survives too.
80+
Indentation survives for the same reason, and so does a blank line.
7581

76-
<Test name="Nothing beyond the framing newlines is trimmed">
82+
<Test name="Whitespace inside the element is preserved exactly">
7783
<TempDir>
78-
<File path="trailing.txt">
79-
one line
80-
81-
</File>
82-
<File path="trailing.txt" as="trailing" />
83-
<AssertEquals actual={trailing} expected={"one line\n"} />
84-
8584
<File path="indented.txt">
8685
indented
8786
</File>
8887
<File path="indented.txt" as="indented" />
89-
<AssertEquals actual={indented} expected={" indented"} />
88+
<AssertEquals actual={indented} expected={"\n indented\n"} />
89+
90+
<File path="blank.txt">
91+
one line
92+
93+
</File>
94+
<File path="blank.txt" as="blank" />
95+
<AssertEquals actual={blank} expected={"\none line\n\n"} />
96+
</TempDir>
97+
</Test>
98+
99+
A name that merely begins with two dots is an ordinary file, not an escape.
100+
101+
<Test name="A name beginning with dots is an ordinary file">
102+
<TempDir>
103+
<File path="..notes.md">dotted</File>
104+
<File path="..notes.md" as="dotted" />
105+
<AssertEquals actual={dotted} expected={"dotted"} />
90106
</TempDir>
91107
</Test>
92108

‎packages/core/src/components/File.ts‎

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,28 @@
99
* part of it has been resolved, so a symlink cannot carry a read or a write
1010
* outside the workspace.
1111
*
12+
* The write form resolves its destination *after* its children have finished,
13+
* because a child can change what the path means — replacing a directory with
14+
* a symlink out of the workspace, for instance. Resolving first would validate
15+
* somewhere other than where the write lands.
16+
*
1217
* Writes go through a sibling temporary file and a rename. That is what makes
1318
* a failed or cancelled write leave the previous content in place, and it is
1419
* what closes the one containment hole resolution cannot: a dangling symlink
1520
* has nothing to resolve, and `rename` replaces the link rather than following
1621
* it wherever it points.
1722
*
23+
* Diagnostics name only the path the document wrote. A resolved workspace
24+
* path, the destination a symlink pointed at, and a rejected absolute path are
25+
* all withheld — §1.2 keeps absolute paths out of diagnostics, and a
26+
* containment failure is the last place to start reporting them.
27+
*
1828
* Every filesystem call goes through the contextual `API.Fs`, so a host can
1929
* observe or sandbox a document's own file access on the same terms as the
2030
* engine's component resolution.
2131
*/
2232

23-
import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
33+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
2434
import { randomUUID } from "node:crypto";
2535
import { ensure, scoped } from "effection";
2636
import type { Operation } from "effection";
@@ -57,14 +67,16 @@ export class FileAccessError extends Error {
5767

5868
export default function* (props: Record<string, Json>): Operation<string> {
5969
const requested = String(props.path);
60-
const target = yield* destination(requested);
6170

6271
if (yield* hasContent()) {
63-
yield* write(requested, target, framed(yield* content(requested)));
72+
// Children first, then the destination: what gets validated has to be
73+
// where the write actually lands, and a child can move that.
74+
const text = yield* content(requested);
75+
yield* write(requested, yield* destination(requested), text);
6476
return "";
6577
}
6678

67-
return yield* read(requested, target);
79+
return yield* read(requested, yield* destination(requested));
6880
}
6981

7082
/**
@@ -100,32 +112,6 @@ function* content(requested: string): Operation<string> {
100112
return rendered;
101113
}
102114

103-
/**
104-
* The rendered children with their framing newlines removed.
105-
*
106-
* A block-form invocation renders the line break that follows the opening tag
107-
* and the one that precedes the closing tag, because both are inside the
108-
* element. They are markup, not content: dropping exactly one at each end is
109-
* what makes the two ways of writing the same file produce the same bytes.
110-
*
111-
* ```md
112-
* <File path="a.txt">one line</File>
113-
* <File path="a.txt">
114-
* one line
115-
* </File>
116-
* ```
117-
*
118-
* Nothing else is touched. Indentation survives, a deliberate blank line
119-
* before the closing tag still ends the file with a newline, and no newline is
120-
* added to content that does not have one.
121-
*/
122-
function framed(content: string): string {
123-
const start = content.startsWith("\n") ? 1 : 0;
124-
const end =
125-
content.length > start && content.endsWith("\n") ? content.length - 1 : content.length;
126-
return content.slice(start, end);
127-
}
128-
129115
/**
130116
* The absolute path this invocation may touch, or a failure naming why not.
131117
*
@@ -144,31 +130,40 @@ function* destination(requested: string): Operation<string> {
144130
}
145131
if (isAbsolute(requested)) {
146132
throw new FileAccessError(
147-
`cannot use the absolute path "${requested}": give a path relative to the working directory.`,
133+
"an absolute path is not accepted; give a path relative to the working directory.",
148134
);
149135
}
150136

151137
const directory = yield* cwd();
152138
const base = (yield* realpath(directory)) ?? directory;
153139
const lexical = resolve(base, requested);
154140
if (!within(base, lexical)) {
155-
throw new FileAccessError(`"${requested}" resolves outside the working directory ${base}.`);
141+
throw new FileAccessError(`"${requested}" resolves outside the working directory.`);
156142
}
157143

158144
const effective = yield* resolveExisting(lexical);
159145
if (!within(base, effective)) {
160146
throw new FileAccessError(
161-
`"${requested}" leads through a symlink to ${effective}, outside the working directory ${base}.`,
147+
`"${requested}" leads through a symlink outside the working directory.`,
162148
);
163149
}
164150

165151
return effective;
166152
}
167153

168-
/** Whether `path` names something strictly inside `base`. */
154+
/**
155+
* Whether `path` names something strictly inside `base`.
156+
*
157+
* Only a complete `..` segment leaves the directory. A name that merely starts
158+
* with two dots — `..notes.md`, `..config/settings.json` — is an ordinary file
159+
* inside it, and a prefix test would refuse it.
160+
*/
169161
function within(base: string, path: string): boolean {
170162
const rel = relative(base, path);
171-
return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
163+
if (rel.length === 0 || isAbsolute(rel)) {
164+
return false;
165+
}
166+
return rel !== ".." && !rel.startsWith(`..${sep}`);
172167
}
173168

174169
/**
@@ -219,8 +214,13 @@ function* read(requested: string, target: string): Operation<string> {
219214
* so a child that failed never reaches the filesystem at all. What remains is
220215
* the write itself, and the temporary file is what keeps that atomic: the
221216
* rename either publishes the complete text or leaves the previous file
222-
* exactly as it was. The temporary is removed on every exit, including
223-
* cancellation, and is already gone after a successful rename.
217+
* exactly as it was.
218+
*
219+
* Removal is registered before the temporary is written rather than after.
220+
* `writeTextFile` is where an interruption is most likely to land, and a
221+
* cleanup installed on the far side of it would not run for the one failure it
222+
* exists to handle. `remove` is forced, so registering it for a file that was
223+
* never created — or one the rename has already consumed — is a no-op.
224224
*/
225225
function* write(requested: string, target: string, content: string): Operation<void> {
226226
const info = yield* stat(target);
@@ -235,8 +235,8 @@ function* write(requested: string, target: string, content: string): Operation<v
235235

236236
yield* scoped(function* () {
237237
const temporary = `${target}.xmd-${randomUUID().slice(0, 8)}.tmp`;
238-
yield* writeTextFile(temporary, content);
239238
yield* ensure(() => remove(temporary, { force: true }));
239+
yield* writeTextFile(temporary, content);
240240
yield* rename(temporary, target);
241241
});
242242
}

0 commit comments

Comments
 (0)