You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5ffa148
Browse filesBrowse the repository at this point in the historyBrowse files
Thanks for taking the time to improve this package.
4
+
5
+
## Local setup
6
+
7
+
```bash
8
+
npm install
9
+
npm run typecheck
10
+
npm test
11
+
npm run build
12
+
```
13
+
14
+
## Pull requests
15
+
16
+
Please keep changes focused and include tests for behavior changes. Small API improvements are welcome when they keep path validation predictable, typed, and easy to use in both Node and browser-oriented tooling.
17
+
18
+
Before opening a pull request, run:
19
+
20
+
```bash
21
+
npm run typecheck
22
+
npm test
23
+
npm run build
24
+
```
25
+
26
+
## Issues
27
+
28
+
When reporting a bug, include:
29
+
30
+
- the package version;
31
+
- the path input that failed;
32
+
- the options used;
33
+
- the expected diagnostic or result;
34
+
- the actual diagnostic code or result.
35
+
36
+
This package validates path strings only. Please keep feature requests focused on diagnostics and policy checks rather than filesystem access, sanitization, or path resolution.
Validate file path strings with explicit portable, POSIX or Windows policies and structured diagnostics.
8
+
9
+
`filepath-validator-kit` is a small clean-room toolkit for forms, config editors, archive builders and CLIs that need to explain why a user-provided path is unsafe or unsupported. It validates strings only: no filesystem access, no path resolution, no symlink checks and no mutation of user input.
const result =vetPath("reports/con.txt", { platform: "portable" });
12
37
13
38
if (!result.valid) {
14
-
console.log(result.issues[0]?.code);
39
+
result.issues[0]?.code;
15
40
// "windows-reserved-name"
41
+
42
+
result.issues[0]?.segment;
43
+
// "con.txt"
16
44
}
45
+
46
+
assertValidPath("exports/report.csv");
47
+
// "exports/report.csv"
17
48
```
18
49
19
-
## Why
50
+
## Why this package
20
51
21
-
Some path checks only return `true` or `false`. `filepath-validator-kit` is for validation flows that need to explain what failed, which segment failed, and whether the policy is POSIX, Windows, or portable across both.
52
+
Some path validators only answer `true` or `false`. That is hard to use in product UI, imports, config files and command-line tools because the caller still has to explain what went wrong.
53
+
54
+
`filepath-validator-kit` returns stable issue codes, source offsets and the failing path segment:
55
+
56
+
```ts
57
+
const result =vetPath("safe//con.txt", { platform: "portable" });
58
+
59
+
result.issues;
60
+
// [
61
+
// {
62
+
// code: "empty-segment",
63
+
// message: "Path contains an empty segment.",
64
+
// segmentIndex: 1,
65
+
// segment: "",
66
+
// start: 5,
67
+
// end: 5
68
+
// },
69
+
// {
70
+
// code: "windows-reserved-name",
71
+
// message: "Path segment is a Windows-reserved device name.",
72
+
// segmentIndex: 2,
73
+
// segment: "con.txt",
74
+
// start: 6,
75
+
// end: 13
76
+
// }
77
+
// ]
78
+
```
22
79
23
80
## API
24
81
25
82
### `vetPath(input, options?)`
26
83
27
-
Returns a `PathVetResult`.
84
+
Returns a `PathVetResult`:
85
+
86
+
```ts
87
+
typePathVetResult= {
88
+
valid:boolean;
89
+
input:unknown;
90
+
normalizedSeparators:string;
91
+
absolute:boolean;
92
+
segments:PathVetSegment[];
93
+
issues:PathVetIssue[];
94
+
};
95
+
```
96
+
97
+
Example:
28
98
29
99
```ts
30
100
const result =vetPath("assets/logo?.svg", {
@@ -34,24 +104,80 @@ const result = vetPath("assets/logo?.svg", {
34
104
});
35
105
```
36
106
37
-
Options:
38
-
39
-
-`platform`: `"portable"` by default, or `"posix"` / `"windows"`.
40
-
-`allowAbsolute`: defaults to `true`.
41
-
-`allowRelative`: defaults to `true`.
42
-
-`allowTraversal`: allows `.` and `..` segments when `true`; defaults to `false`.
43
-
-`allowEmptySegments`: allows repeated separators when `true`; defaults to `false`.
-`portable`: rejects Windows-reserved characters, Windows device names and Windows trailing dots/spaces.
145
+
-`windows`: applies Windows segment restrictions.
146
+
-`posix`: accepts characters such as `?` and `:` because they are not path separators under POSIX.
147
+
148
+
Root-only absolute paths such as `/` and `C:\\` are accepted when absolute paths are allowed.
149
+
150
+
## Diagnostics
151
+
152
+
Issue codes are stable and intended for UI messages, logs or localization:
153
+
154
+
-`empty-input`
155
+
-`not-a-string`
156
+
-`invalid-option`
157
+
-`absolute-not-allowed`
158
+
-`relative-not-allowed`
159
+
-`traversal-not-allowed`
160
+
-`empty-segment`
161
+
-`segment-too-long`
162
+
-`path-too-long`
163
+
-`nul-byte`
164
+
-`windows-reserved-character`
165
+
-`windows-reserved-name`
166
+
-`windows-trailing-dot-or-space`
167
+
168
+
## Limits
169
+
170
+
This package validates path strings only. It does not:
171
+
172
+
- check whether a file exists;
173
+
- normalize or resolve paths;
174
+
- inspect permissions;
175
+
- resolve symlinks;
176
+
- sanitize filenames;
177
+
- guarantee that every filesystem, archive format or host application will accept the path.
178
+
179
+
Use it as an explainable first-pass validation layer before application-specific checks.
54
180
55
-
## Notes
181
+
## License
56
182
57
-
This library validates path strings only. It does not touch the file system, resolve symlinks, check permissions, or guarantee that an operating system will accept a path in every context.
If you find a security issue, please report it privately when GitHub security advisories are available for this repository. If private advisories are not available, open a minimal issue that describes the affected package and version without publishing exploit details.
6
+
7
+
Please include:
8
+
9
+
- the affected package and version;
10
+
- the smallest input or scenario needed to understand the issue;
11
+
- the validation options used;
12
+
- the impact you believe it has;
13
+
- whether the issue affects Node, browsers, or both.
14
+
15
+
This package does not touch the filesystem, but misleading validation can still matter in upload forms, archive builders, config editors, or CLI tools. Reports about denial-of-service behavior or incorrect acceptance of unsafe path strings are welcome.
0 commit comments