@matatbread/matbot-gate-fs-node 0.0.0-stage → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +117 -2
- package/package.json +46 -3
- package/src/gate.ts +167 -0
- package/src/index.ts +63 -0
- package/src/paths.ts +290 -0
- package/src/wrap.ts +433 -0
package/src/paths.ts
ADDED
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
import * as path from 'node:path';
|
|
2
|
+
import { fileURLToPath } from 'node:url';
|
|
3
|
+
import { constants, readlinkSync, realpathSync, statSync } from 'node:fs';
|
|
4
|
+
|
|
5
|
+
/** Which of the three gates a path argument is put to. Each is independent: a grant to read a path does not let
|
|
6
|
+
* a body change it, and neither reading nor writing it lets a body change its permissions, owner or timestamps. */
|
|
7
|
+
export type Access = 'read' | 'write' | 'access';
|
|
8
|
+
|
|
9
|
+
/** For one call: each path argument's index and the access it needs. */
|
|
10
|
+
type PathArgs = (args: readonly unknown[]) => readonly (readonly [index: number, access: Access])[];
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The method → path-argument map for `node:fs`. Typed per method rather than inferred from the arguments,
|
|
14
|
+
* deliberately: "looks like a path" cannot tell a path from an `fd` (a number), an encoding (`'utf8'` as a
|
|
15
|
+
* second arg), or a flags string, and a wrong guess is worse than none. The sync variants share the async
|
|
16
|
+
* names with a `Sync` suffix, so the table is written once and expanded.
|
|
17
|
+
*
|
|
18
|
+
* fd-based calls (`read`, `write`, `fstat`, `fchmod`, …) take no path — the `open` that produced the fd
|
|
19
|
+
* was already asked about, with the access its flags asked for, so the fd is a capability the body
|
|
20
|
+
* legitimately holds.
|
|
21
|
+
*/
|
|
22
|
+
const READ = [
|
|
23
|
+
'readdir', 'stat', 'lstat', 'statfs', 'access', 'opendir', 'realpath', 'readlink', 'exists',
|
|
24
|
+
'openAsBlob', 'watch', 'watchFile',
|
|
25
|
+
] as const;
|
|
26
|
+
const WRITE = [
|
|
27
|
+
'mkdir', 'rmdir', 'rm', 'unlink', 'truncate', 'mkdtemp', 'mkdtempDisposable',
|
|
28
|
+
] as const;
|
|
29
|
+
const ACCESS = ['chmod', 'lchmod', 'chown', 'lchown', 'utimes', 'lutimes'] as const;
|
|
30
|
+
|
|
31
|
+
/** The calls taking an open flag in an options argument, with where it is and what it defaults to. They are
|
|
32
|
+
* asked about as what the flag does: `readFile(p, { flag: 'w' })` truncates, whatever its name says. */
|
|
33
|
+
export const FLAG_OPTION: ReadonlyMap<string, readonly [index: number, flag: string]> = new Map(
|
|
34
|
+
([['readFile', [1, 'r']], ['writeFile', [2, 'w']], ['appendFile', [2, 'a']]] as const)
|
|
35
|
+
.flatMap(([n, at]) => [[n, at] as const, [`${n}Sync`, at] as const]),
|
|
36
|
+
);
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The function members known to reach no file: `unwatchFile` (which only removes a listener), and the classes
|
|
40
|
+
* a body is handed rather than constructs onto a file. Everything else that is in none of the tables here is
|
|
41
|
+
* REFUSED: the tables are written by hand, and a member node adds later (as it added `mkdtempDisposable` and
|
|
42
|
+
* `Utf8Stream`) would otherwise be a way to a file that is asked about by nobody. A body that needs one finds
|
|
43
|
+
* out at once, with a message naming it.
|
|
44
|
+
*/
|
|
45
|
+
export const PATHLESS: ReadonlySet<string> = new Set(['unwatchFile', 'unwatchFileSync', 'Dirent', 'Stats', 'Dir', '_toUnixTimestamp']);
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The calls that take a descriptor rather than a path, and what each does with it. A descriptor is a capability
|
|
49
|
+
* only when the body got it from the gate, so each is checked against the ones this invocation opened: any other
|
|
50
|
+
* number is a file this process has open for its own reasons, found by trying numbers. `close` forgets it, since
|
|
51
|
+
* the number is reused. The three that change metadata ask `fs-access` about the file it was opened on, because
|
|
52
|
+
* the kernel allows them on a descriptor opened only for reading.
|
|
53
|
+
*/
|
|
54
|
+
export const FD_CALLS: ReadonlyMap<string, 'use' | 'close' | 'access'> = new Map(
|
|
55
|
+
([
|
|
56
|
+
['read', 'use'], ['readv', 'use'], ['write', 'use'], ['writev', 'use'], ['fstat', 'use'],
|
|
57
|
+
['fsync', 'use'], ['fdatasync', 'use'], ['ftruncate', 'use'], ['close', 'close'],
|
|
58
|
+
['fchmod', 'access'], ['fchown', 'access'], ['futimes', 'access'],
|
|
59
|
+
] as const).flatMap(([n, use]) => [[n, use] as const, [`${n}Sync`, use] as const]),
|
|
60
|
+
);
|
|
61
|
+
|
|
62
|
+
const fixed = (...pairs: (readonly [number, Access])[]): PathArgs => () => pairs;
|
|
63
|
+
|
|
64
|
+
/** Build `method → path args` for the async surface, then the `*Sync` twins for `fs`. */
|
|
65
|
+
export function fsPathArgs(withSync: boolean): Map<string, PathArgs> {
|
|
66
|
+
const m = new Map<string, PathArgs>();
|
|
67
|
+
for (const name of READ) m.set(name, fixed([0, 'read']));
|
|
68
|
+
for (const name of WRITE) m.set(name, fixed([0, 'write']));
|
|
69
|
+
for (const name of ACCESS) m.set(name, fixed([0, 'access']));
|
|
70
|
+
m.set('copyFile', fixed([0, 'read'], [1, 'write']));
|
|
71
|
+
m.set('cp', fixed([0, 'read'], [1, 'write']));
|
|
72
|
+
// Both give the source's content a new name, which is asked about as itself — so the source is READ as
|
|
73
|
+
// well (else a file denied for reading in a writable directory is read under the name it was given), and
|
|
74
|
+
// changed: a hard link shares its inode, and a rename removes it.
|
|
75
|
+
m.set('link', fixed([0, 'read'], [0, 'write'], [1, 'write']));
|
|
76
|
+
m.set('rename', fixed([0, 'read'], [0, 'write'], [1, 'write']));
|
|
77
|
+
m.set('symlink', fixed([1, 'write'])); // the target is not touched; reading through
|
|
78
|
+
// the link is asked about at its real target
|
|
79
|
+
m.set('open', args => openAccesses(args[1]).map(access => [0, access] as const));
|
|
80
|
+
for (const [name, [index, flag]] of FLAG_OPTION) {
|
|
81
|
+
m.set(name, args => {
|
|
82
|
+
const o = args[index];
|
|
83
|
+
const given = typeof o === 'object' && o !== null ? (o as { flag?: unknown }).flag : undefined;
|
|
84
|
+
return openAccesses(given ?? flag).map(access => [0, access] as const);
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
if (withSync) for (const [name, args] of [...m]) m.set(`${name}Sync`, args);
|
|
88
|
+
return m;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* What a flag opens a file to do, which is more than one thing: `r+` hands back a descriptor that both reads
|
|
93
|
+
* and writes, so asking only the write gate would let a grant to write read a file denied for reading. `w` is
|
|
94
|
+
* write alone, since the descriptor cannot read. Anything creating or truncating writes, whatever else it
|
|
95
|
+
* says. Absent (or the callback, in `fs.open(p, cb)`) means node's default, `r`. Anything unrecognised asks
|
|
96
|
+
* both, and node then rejects it.
|
|
97
|
+
*/
|
|
98
|
+
export function openAccesses(flags: unknown): Access[] {
|
|
99
|
+
if (flags === undefined || flags === null || typeof flags === 'function') return ['read'];
|
|
100
|
+
let reads = true, writes = true;
|
|
101
|
+
if (typeof flags === 'string') {
|
|
102
|
+
reads = /[r+]/.test(flags);
|
|
103
|
+
writes = /[wa+]/.test(flags);
|
|
104
|
+
if (!reads && !writes) reads = writes = true;
|
|
105
|
+
} else if (typeof flags === 'number') {
|
|
106
|
+
const mode = flags & (constants.O_RDONLY | constants.O_WRONLY | constants.O_RDWR);
|
|
107
|
+
reads = mode !== constants.O_WRONLY;
|
|
108
|
+
writes = mode !== constants.O_RDONLY || (flags & (constants.O_APPEND | constants.O_CREAT | constants.O_TRUNC)) !== 0;
|
|
109
|
+
}
|
|
110
|
+
return [...(reads ? ['read'] as const : []), ...(writes ? ['write'] as const : [])];
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** `glob`/`globSync` take patterns, not paths: each is asked about as a read of the directory it starts
|
|
114
|
+
* from — its static prefix, resolved against `options.cwd` (else the process cwd). */
|
|
115
|
+
export const GLOB = ['glob', 'globSync'] as const;
|
|
116
|
+
|
|
117
|
+
/** Past this many alternatives a pattern's braces are not expanded, and it is asked about at the root. */
|
|
118
|
+
const MAX_BRACE_EXPANSION = 256;
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The directory each glob pattern starts from: its leading segments up to the first with a glob
|
|
122
|
+
* character, resolved against `cwd`. An absolute pattern ignores `cwd`, as glob itself does.
|
|
123
|
+
*
|
|
124
|
+
* Two things in a pattern reach outside that prefix, so each is accounted for rather than read past:
|
|
125
|
+
* braces, whose alternatives may be paths of their own (`{/etc/*,x}`), are expanded first; and a `..`
|
|
126
|
+
* after a wildcard climbs, so the base climbs once for each — no other segment ascends.
|
|
127
|
+
*/
|
|
128
|
+
export function globBases(patterns: unknown, cwd: string | undefined): string[] {
|
|
129
|
+
const list = Array.isArray(patterns) ? patterns : [patterns];
|
|
130
|
+
const base = cwd ?? process.cwd();
|
|
131
|
+
const bases = list.filter((p): p is string => typeof p === 'string').flatMap(pattern => {
|
|
132
|
+
const expanded = expandBraces(pattern);
|
|
133
|
+
if (expanded === undefined) return [path.parse(path.resolve(base)).root];
|
|
134
|
+
return expanded.map(p => {
|
|
135
|
+
const segs = p.split(/[\\/]/);
|
|
136
|
+
const glob = segs.findIndex(seg => /[*?[\]{}()!]/.test(seg));
|
|
137
|
+
const prefix = (glob === -1 ? segs : segs.slice(0, glob)).join('/');
|
|
138
|
+
let dir = path.resolve(base, prefix === '' && p.startsWith('/') ? '/' : prefix);
|
|
139
|
+
if (glob !== -1) for (const seg of segs.slice(glob)) if (seg === '..') dir = path.dirname(dir);
|
|
140
|
+
return dir;
|
|
141
|
+
});
|
|
142
|
+
});
|
|
143
|
+
return [...new Set(bases)];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** `a{b,c}d` → `abd`, `acd`, recursively; a brace with no top-level comma is literal, as in glob. Undefined
|
|
147
|
+
* when the alternatives would exceed {@link MAX_BRACE_EXPANSION}. */
|
|
148
|
+
function expandBraces(p: string): string[] | undefined {
|
|
149
|
+
let depth = 0, start = -1;
|
|
150
|
+
for (let i = 0; i < p.length; i++) {
|
|
151
|
+
const c = p[i];
|
|
152
|
+
if (c === '\\') { i++; continue; }
|
|
153
|
+
if (c === '{') { if (depth++ === 0) start = i; continue; }
|
|
154
|
+
if (c !== '}' || depth === 0 || --depth !== 0) continue;
|
|
155
|
+
const alternatives = splitTopLevelCommas(p.slice(start + 1, i));
|
|
156
|
+
if (alternatives.length < 2) continue;
|
|
157
|
+
const out: string[] = [];
|
|
158
|
+
for (const alt of alternatives) {
|
|
159
|
+
const more = expandBraces(p.slice(0, start) + alt + p.slice(i + 1));
|
|
160
|
+
if (more === undefined || out.push(...more) > MAX_BRACE_EXPANSION) return undefined;
|
|
161
|
+
}
|
|
162
|
+
return out;
|
|
163
|
+
}
|
|
164
|
+
return [p];
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function splitTopLevelCommas(body: string): string[] {
|
|
168
|
+
const parts: string[] = [];
|
|
169
|
+
let depth = 0, from = 0;
|
|
170
|
+
for (let i = 0; i < body.length; i++) {
|
|
171
|
+
const c = body[i];
|
|
172
|
+
if (c === '\\') { i++; continue; }
|
|
173
|
+
if (c === '{') depth++;
|
|
174
|
+
else if (c === '}') depth--;
|
|
175
|
+
else if (c === ',' && depth === 0) { parts.push(body.slice(from, i)); from = i + 1; }
|
|
176
|
+
}
|
|
177
|
+
parts.push(body.slice(from));
|
|
178
|
+
return parts;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
export function refusal(message: string): Error {
|
|
182
|
+
return Object.assign(new Error(message), { code: 'EACCES' });
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* A path argument reduced, ONCE, to the string that is both asked about and handed to node. Everything but a
|
|
189
|
+
* string can change after it has been read — a `Buffer` or `URL` the body still holds, a getter, a Proxy — so
|
|
190
|
+
* a call never passes the original on (see `prepare` in wrap.ts). `undefined` for what is not a path: an `fd`,
|
|
191
|
+
* a missing optional argument, or anything else node rejects by itself.
|
|
192
|
+
*
|
|
193
|
+
* An object is what node would take for a URL or nothing, and `fileURLToPath` is node's own reading of one: it
|
|
194
|
+
* throws what node would (`ERR_INVALID_URL_SCHEME`, `ERR_INVALID_ARG_TYPE`), so there is no "not a path"
|
|
195
|
+
* outcome to pass through unasked, which a getter answering differently the second time could exploit.
|
|
196
|
+
*
|
|
197
|
+
* Bytes that are not UTF-8 name a file no string can, and decoded lossily they name a different one: the
|
|
198
|
+
* question would be about `\uFFFD` while node opened the real bytes. So they are refused, with no way to ask.
|
|
199
|
+
*/
|
|
200
|
+
export function toPath(arg: unknown): string | undefined {
|
|
201
|
+
if (typeof arg === 'string') return arg;
|
|
202
|
+
if (arg instanceof Uint8Array) {
|
|
203
|
+
try { return utf8.decode(arg); }
|
|
204
|
+
catch { throw refusal('A path that is not valid UTF-8 cannot be asked about, so it is refused. Pass it as a string.'); }
|
|
205
|
+
}
|
|
206
|
+
return typeof arg === 'object' && arg !== null ? fileURLToPath(arg as URL) : undefined;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/** More links than this on the way to a file is more than the kernel would follow (`ELOOP`). */
|
|
210
|
+
const MAX_LINKS = 40;
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Resolve `p` to an absolute path with symlinks collapsed, so one file has one subject however it is
|
|
214
|
+
* spelled (`~`-expanded, relative, through a link) and a grant cannot be walked out of: a symlink
|
|
215
|
+
* `src/escape → /etc/shadow` is asked about as `/etc/shadow`. A path that does not exist yet (a file about
|
|
216
|
+
* to be created) has its nearest existing ancestor realpath'd and the rest re-appended, so a write cannot
|
|
217
|
+
* be aimed through a symlinked parent either.
|
|
218
|
+
*
|
|
219
|
+
* A dangling link is the one thing in that walk which "does not exist" and still leads somewhere: `open`
|
|
220
|
+
* with `O_CREAT` follows it and creates its target, so it is followed here too, rather than asked about at
|
|
221
|
+
* the link's own name. A cycle resolves to itself, and the call then fails with `ELOOP`.
|
|
222
|
+
*
|
|
223
|
+
* The native realpath, because it is the one that returns the name as stored: the JS one keeps the case
|
|
224
|
+
* it was given, so on a case-insensitive filesystem (macOS's default) `.ENV` would be a different subject
|
|
225
|
+
* from the `.env` a denial names, and the same file.
|
|
226
|
+
*/
|
|
227
|
+
export function realResolve(p: string): string {
|
|
228
|
+
const abs = path.resolve(p);
|
|
229
|
+
const tail: string[] = [];
|
|
230
|
+
let cur = abs;
|
|
231
|
+
for (let links = 0; links < MAX_LINKS;) {
|
|
232
|
+
try { return path.join(realpathSync.native(cur), ...tail.reverse()); }
|
|
233
|
+
catch { /* not all there */ }
|
|
234
|
+
let target: string | undefined;
|
|
235
|
+
try { target = readlinkSync(cur); } catch { /* not a link */ }
|
|
236
|
+
if (target !== undefined) { cur = path.resolve(path.dirname(cur), target); links++; continue; }
|
|
237
|
+
const parent = path.dirname(cur);
|
|
238
|
+
if (parent === cur) return abs; // reached the root with nothing existing
|
|
239
|
+
tail.push(path.basename(cur));
|
|
240
|
+
cur = parent;
|
|
241
|
+
}
|
|
242
|
+
// A cycle: still the real spelling of its directory, or `/var/…` on macOS is a different subject from the
|
|
243
|
+
// `/private/var/…` an answer names. Not followed further — a parent can be part of the cycle too.
|
|
244
|
+
try { return path.join(realpathSync.native(path.dirname(abs)), path.basename(abs)); }
|
|
245
|
+
catch { return abs; }
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
const insensitiveByDevice = new Map<number, boolean>();
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* Whether the volume holding `real` (a {@link realResolve}d path) ignores letter case. Node has no call that
|
|
252
|
+
* says, and the answer is per volume (macOS's default is insensitive, a volume may be formatted otherwise,
|
|
253
|
+
* a mount on Linux may be either), so it is measured: the nearest existing name with a letter in it, looked
|
|
254
|
+
* up again with its case swapped, is the same file exactly when case is ignored. Remembered per device.
|
|
255
|
+
*/
|
|
256
|
+
export function caseInsensitiveAt(real: string): boolean {
|
|
257
|
+
let cur = real;
|
|
258
|
+
for (;;) {
|
|
259
|
+
const name = path.basename(cur);
|
|
260
|
+
const swapped = [...name].map(c => c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()).join('');
|
|
261
|
+
if (swapped !== name) {
|
|
262
|
+
try {
|
|
263
|
+
const st = statSync(cur);
|
|
264
|
+
const known = insensitiveByDevice.get(st.dev);
|
|
265
|
+
if (known !== undefined) return known;
|
|
266
|
+
let same = false;
|
|
267
|
+
try { const other = statSync(path.join(path.dirname(cur), swapped)); same = other.dev === st.dev && other.ino === st.ino; }
|
|
268
|
+
catch { /* no such name: case matters here */ }
|
|
269
|
+
insensitiveByDevice.set(st.dev, same);
|
|
270
|
+
return same;
|
|
271
|
+
} catch { /* `cur` does not exist yet: try its parent */ }
|
|
272
|
+
}
|
|
273
|
+
const parent = path.dirname(cur);
|
|
274
|
+
if (parent === cur) return false;
|
|
275
|
+
cur = parent;
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* The directory a grant for `real` may name: `real` itself when it is a directory (listing it, and
|
|
281
|
+
* everything in it, are then one answer), else the directory holding it. Always with a trailing
|
|
282
|
+
* separator, which no realpath has. That is what makes a directory subject the only kind that covers by
|
|
283
|
+
* prefix (`PermissionRequest.separators`): a file grant stays exact.
|
|
284
|
+
*/
|
|
285
|
+
export function directoryOf(real: string): string {
|
|
286
|
+
let isDir = false;
|
|
287
|
+
try { isDir = statSync(real).isDirectory(); } catch { /* not there yet: its parent is the directory */ }
|
|
288
|
+
const dir = isDir ? real : path.dirname(real);
|
|
289
|
+
return dir.endsWith(path.sep) ? dir : dir + path.sep;
|
|
290
|
+
}
|