@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/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
+ }