@exodus/stasis-core 1.0.0-beta.14 → 1.0.0-beta.16

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/fs.js CHANGED
@@ -1,8 +1,5 @@
1
- // `stasis run --fs=sync|async`: monkey-patch the fs readers (readFileSync/readdirSync/lstat/stat
2
- // + existence/realpath probes; under =async their callback + fs.promises counterparts) to capture a
3
- // program's explicit reads into the bundle (bundle=add|replace) or serve them from it (bundle=load).
4
- // SECURITY INVARIANT: only paths whose REAL path (symlinks resolved) stays inside the project root are
5
- // captured/served; anything else falls through to the real fs and is never attested.
1
+ // `stasis run --fs`: capture a program's fs reads into the bundle, or serve them from it (bundle=load).
2
+ // SECURITY INVARIANT: a path whose REAL path leaves the project root falls through to the real fs, never attested.
6
3
 
7
4
  import { createRequire, syncBuiltinESMExports } from 'node:module'
8
5
  import { resolve } from 'node:path'
@@ -14,10 +11,8 @@ import { isDotEnvFile, isPathWithin, isStasisArtifactName } from './util.js'
14
11
  const require = createRequire(import.meta.url)
15
12
  const fs = require('node:fs')
16
13
 
17
- // Snapshot the real fns while still genuine builtins; the hooks call THESE, never patched `fs.*`, so
18
- // there's no recursion and capture/containment always see real bytes/paths. fs.promises IS
19
- // node:fs/promises (same object). The legacy callback fs.exists is deliberately NOT reassigned
20
- // (wrapping would clobber its util.promisify.custom); it still answers via the patched fs.access.
14
+ // The hooks call these real fns, so there's no recursion and capture sees real bytes. Callback fs.exists is
15
+ // NOT patched (wrapping would clobber its util.promisify.custom); it answers via the patched fs.access.
21
16
  const {
22
17
  readdirSync: realReaddirSync, lstatSync: realLstatSync, statSync: realStatSync, realpathSync: realRealpathSync,
23
18
  existsSync: realExistsSync, accessSync: realAccessSync,
@@ -27,12 +22,10 @@ const { readFile: realReadFileP, readdir: realReaddirP, lstat: realLstatP, stat:
27
22
  const realRealpathSyncNative = realRealpathSync.native
28
23
  const realRealpathNative = realRealpath.native
29
24
 
30
- // The bundle serves read-only, so only an F_OK/R_OK-only mode may be answered from it; allowlist form
31
- // so a W_OK/X_OK or out-of-range mode defers to the real fs.
25
+ // The bundle serves read-only: an allowlist, so a W_OK/X_OK or out-of-range mode defers to the real fs.
32
26
  const READ_ACCESS = fs.constants.F_OK | fs.constants.R_OK
33
27
  const isReadOnlyAccessMode = (mode) => ((mode | 0) & ~READ_ACCESS) === 0
34
28
 
35
- // Resolve a path argument to an absolute path, or null for what we don't capture (fd, non-file URL).
36
29
  function toAbsPath(path) {
37
30
  if (typeof path === 'string') return resolve(path)
38
31
  if (Buffer.isBuffer(path)) return resolve(path.toString())
@@ -40,50 +33,40 @@ function toAbsPath(path) {
40
33
  return null
41
34
  }
42
35
 
43
- // At the project root, drop stasis's own artifacts from the RECORDED listing so it doesn't depend on
44
- // whether an earlier run left them behind; the program still receives the true on-disk `names`.
45
- function dirCaptureNames(root, abs, names) {
46
- if (!isPathWithin(abs, root)) return names
47
- return names.filter((name) => !isStasisArtifactName(name))
48
- }
36
+ const encodingOf = (options) => (typeof options === 'string' ? options : options?.encoding)
49
37
 
50
- // Apply readFileSync's encoding arg to raw bytes; Buffer.toString matches fs's ERR_UNKNOWN_ENCODING.
38
+ // Buffer.toString throws fs's ERR_UNKNOWN_ENCODING.
51
39
  function decode(buf, options) {
52
- const encoding = typeof options === 'string' ? options : options?.encoding
40
+ const encoding = encodingOf(options)
53
41
  return encoding == null ? buf : buf.toString(encoding)
54
42
  }
55
43
 
56
- // Honour realpath's `encoding` arg for the synthetic answer when a bundle-served path is gone from disk.
57
- function encodeRealpath(abs, options) {
58
- const encoding = typeof options === 'string' ? options : options?.encoding
59
- return encoding === 'buffer' ? Buffer.from(abs) : abs
60
- }
44
+ // The synthetic realpath of a bundle-served path gone from disk.
45
+ const encodeRealpath = (abs, options) => (encodingOf(options) === 'buffer' ? Buffer.from(abs) : abs)
61
46
 
62
- // NON-EXISTENT under --fs (a faithful ENOENT from every reader, listings included, in both modes):
63
- // source-map sidecars (`*.map`, so a captured build replays byte-identically; opt out via `map` in
64
- // resources) and `.env`/`.env.*` (an automated capture can never bake a secret in; no opt-in). The
65
- // ONE way either serves at load is bundle membership (an explicit `stasis add .env`).
47
+ // Absent under --fs: `*.map` (a captured build replays byte-identically; `map` in resources opts out) and
48
+ // `.env*` (a capture never bakes in a secret). Either serves at load only as an explicit bundle member.
66
49
  function isSkippedFsPath(state, abs) {
67
50
  const skipped = (abs.toLowerCase().endsWith('.map') && !state.config.resources?.has('map')) || isDotEnvFile(abs)
68
51
  return skipped && !(state.config.loadBundle && state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined)
69
52
  }
70
53
 
71
- // A faithful Node-shaped ENOENT, indistinguishable from a real absent file.
54
+ // Indistinguishable from a real absent file's. String() spells a Buffer path as UTF-8 and a URL as its href.
72
55
  function enoent(syscall, path) {
73
- const p = typeof path === 'string' ? path : Buffer.isBuffer(path) ? path.toString() : String(path)
56
+ const p = String(path)
74
57
  return Object.assign(new Error(`ENOENT: no such file or directory, ${syscall} '${p}'`), { code: 'ENOENT', errno: -2, syscall, path: p })
75
58
  }
76
59
 
77
- // File-type bits, so code reading stats.mode (not the is*() methods) still sees file-vs-dir.
78
- const S_IFREG = 0o100000
79
- const S_IFDIR = 0o040000
60
+ // An absent path's stat answers as the real fn does for '' (never exists), re-spelled: which options it honours
61
+ // varies by Node version (async stat takes throwIfNoEntry from 24.15, async lstat doesn't).
62
+ const asAbsent = (syscall, path) => (err) => (err?.code === 'ENOENT' ? enoent(syscall, path) : err)
80
63
 
81
- // Neutral fs.Stats-shaped record for a bundle-served path gone from disk; never throws, so wrappers
82
- // reading uid/gid etc. keep working.
64
+ // For a bundle-served path gone from disk; never throws, so wrappers reading uid/gid etc. keep working.
83
65
  function syntheticStat(isDir) {
84
66
  const epoch = new Date(0)
85
67
  return {
86
- dev: 0, ino: 0, mode: isDir ? S_IFDIR : S_IFREG, nlink: 1, uid: 0, gid: 0,
68
+ // S_IFDIR / S_IFREG: code reading stats.mode, not is*(), still tells file from dir.
69
+ dev: 0, ino: 0, mode: isDir ? 0o040000 : 0o100000, nlink: 1, uid: 0, gid: 0,
87
70
  rdev: 0, size: 0, blksize: 4096, blocks: 0,
88
71
  atimeMs: 0, mtimeMs: 0, ctimeMs: 0, birthtimeMs: 0,
89
72
  atime: epoch, mtime: epoch, ctime: epoch, birthtime: epoch,
@@ -92,9 +75,7 @@ function syntheticStat(isDir) {
92
75
  }
93
76
  }
94
77
 
95
- // A Stats-like Proxy for a bundle-served path: isFile()/isDirectory() answer from the bundle, other
96
- // members from the REAL stat while on disk, else syntheticStat. `then` is short-circuited so a
97
- // bundle-served Stats is never an accidental (rejecting) thenable under `await`.
78
+ // The rest from the real stat while on disk; `then` short-circuited: never an accidental thenable under `await`.
98
79
  function bundleStats(realStatFn, statPath, isDir) {
99
80
  let data
100
81
  const overrides = { isFile: () => !isDir, isDirectory: () => isDir }
@@ -117,39 +98,34 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
117
98
  if (installed) return
118
99
  installed = true
119
100
 
120
- // Node's glob takes fs's readers when it first loads: load it now, on the real ones, so the sweep
121
- // of stasis.config.json's `extra` at write (expandExtra) is never captured as the program's reads.
101
+ // Node's glob takes fs's readers when first loaded: load it on the real ones, so the `extra` sweep isn't captured.
122
102
  fs.globSync([])
123
103
 
124
- // Classify a path for every hook: null passes through to the real fs; else { mode, abs, url, state }
125
- // with mode 'absent' (a skipped path: ENOENT), 'serve' (bundle=load; an uncaptured path still falls
126
- // through to disk) or 'capture' (bundle=add|replace, outside a loader read).
104
+ // null passes through to the real fs; 'serve' still falls through to disk for an uncaptured path.
127
105
  const classify = (path) => {
128
106
  const state = getState()
129
107
  if (!state) return null
130
108
  const abs = toAbsPath(path)
131
109
  if (abs === null || !isPathWithin(state.root, abs)) return null
132
- if (isSkippedFsPath(state, abs)) return { mode: 'absent', abs }
110
+ if (isSkippedFsPath(state, abs)) return { mode: 'absent' }
133
111
  const url = pathToFileURL(abs).toString()
134
112
  if (state.config.loadBundle) return { mode: 'serve', state, url, abs }
135
113
  if (state.config.writeBundle && !isLoadingModule()) return { mode: 'capture', state, url, abs }
136
114
  return null
137
115
  }
138
- // A path the bundle knows (content, listing, stat record or implied dir), for the serve-only probes.
139
116
  const served = (t) => t?.mode === 'serve' && t.state.getFsStatFamily(t.url) !== undefined
140
117
 
141
- // Capture-side records; a rejected capture taints the run (markAborted) rather than failing the read.
118
+ // A rejected capture taints the run rather than failing the read.
142
119
  const record = (fn) => { try { fn() } catch (err) { markAborted(err) } }
143
- // A path whose real location escapes root (in-tree symlink) is read but NOT recorded, and neither is
144
- // a read a bundler-plugin sidecar already attests.
120
+ // An in-tree symlink out of root is read but NOT recorded, nor is a read a bundler-plugin sidecar attests.
145
121
  const captureFile = ({ state, abs, url }, buf) => {
146
122
  if (realContained(state.root, abs) && !state.attestedBySidecar(url)) record(() => state.addFsFile(url, buf))
147
123
  }
148
124
  const captureDir = ({ state, abs, url }, names) => {
149
- if (realContained(state.root, abs)) record(() => state.addFsDir(url, dirCaptureNames(state.root, abs, names)))
125
+ if (!realContained(state.root, abs)) return
126
+ // At the root, the RECORDED listing leaves out stasis's own artifacts, so an earlier run's don't matter.
127
+ record(() => state.addFsDir(url, isPathWithin(abs, state.root) ? names.filter((name) => !isStasisArtifactName(name)) : names))
150
128
  }
151
- // A stat records the path's KIND as a payload-free record so a stat-ONLY path's type getters answer
152
- // at load. Only file and dir are modelled.
153
129
  const captureStat = ({ state, abs, url }, stats) => {
154
130
  const isDir = stats.isDirectory()
155
131
  if (!isDir && !stats.isFile()) return
@@ -173,7 +149,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
173
149
  fs.readdirSync = function readdirSync(path, options) {
174
150
  const t = classify(path)
175
151
  if (t?.mode === 'absent') throw enoent('scandir', path)
176
- // Served/captured in the single-argument form only; any options pass straight through.
177
152
  if (options == null && t?.mode === 'serve') {
178
153
  const names = t.state.getFsDirFamily(t.url)
179
154
  if (names !== undefined) return names // sorted at capture time
@@ -185,16 +160,17 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
185
160
  return realReaddirSync(path, options)
186
161
  }
187
162
 
188
- // Single-arg form only; capture still hands the caller the REAL Stats/errors. statSync follows
189
- // symlinks, so it must use the real statSync: an in-root symlink records the TARGET's kind there.
163
+ // statSync follows symlinks: an in-root symlink records the TARGET's kind.
190
164
  const servedStatSync = (syscall, realFn) => ({
191
165
  [`${syscall}Sync`](path, options) {
192
- const t = options == null ? classify(path) : null
193
- if (t?.mode === 'absent') throw enoent(syscall, path)
194
- if (t?.mode === 'serve') {
166
+ const t = classify(path)
167
+ if (t?.mode === 'absent') {
168
+ try { return realFn('', options) } catch (err) { throw asAbsent(syscall, path)(err) }
169
+ }
170
+ if (options == null && t?.mode === 'serve') {
195
171
  const kind = t.state.getFsStatFamily(t.url)
196
172
  if (kind !== undefined) return bundleStats(realFn, path, kind === 'directory')
197
- } else if (t?.mode === 'capture') {
173
+ } else if (options == null && t?.mode === 'capture') {
198
174
  const stats = realFn(path)
199
175
  captureStat(t, stats)
200
176
  return stats
@@ -205,8 +181,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
205
181
  fs.lstatSync = servedStatSync('lstat', realLstatSync)
206
182
  fs.statSync = servedStatSync('stat', realStatSync)
207
183
 
208
- // existsSync/accessSync/realpathSync: existence + canonical-path PROBES, serve-only (bundle=load) --
209
- // a tool may probe before reading bytes (@babel/core does); capture mode and unrecorded paths defer.
184
+ // The probes are served (a tool may probe before reading bytes, as @babel/core does) but never captured.
210
185
  fs.existsSync = function existsSync(path) {
211
186
  const t = classify(path)
212
187
  if (t?.mode === 'absent') return false
@@ -220,27 +195,21 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
220
195
  return realAccessSync(path, mode)
221
196
  }
222
197
 
223
- // Try the real realpath first (true symlink resolution while on disk), fall back to the lexical abs
224
- // once gone (ancestor symlinks not re-resolved then).
198
+ // The real realpath while on disk, else the lexical abs (ancestor symlinks not re-resolved then).
225
199
  const servedRealpathSync = (realFn) => function realpathSync(path, options) {
226
200
  const t = classify(path)
227
201
  if (t?.mode === 'absent') throw enoent('realpath', path)
228
- if (served(t)) {
229
- try { return realFn(path, options) } catch { return encodeRealpath(t.abs, options) }
230
- }
231
- return realFn(path, options)
202
+ if (!served(t)) return realFn(path, options)
203
+ try { return realFn(path, options) } catch { return encodeRealpath(t.abs, options) }
232
204
  }
233
205
  fs.realpathSync = servedRealpathSync(realRealpathSync)
234
206
  fs.realpathSync.native = servedRealpathSync(realRealpathSyncNative)
235
207
 
236
- // --fs=async counterparts; a served callback is deferred (queueMicrotask) to preserve fs's
237
- // always-async contract.
208
+ // A served callback is deferred, keeping fs's always-async contract.
238
209
  if (patchAsync) {
239
- // Split a trailing callback from its optional options argument.
240
210
  const cbArgs = (options, callback) => (typeof options === 'function' ? [undefined, options] : [options, callback])
241
211
  const later = (cb, ...args) => queueMicrotask(() => cb(...args))
242
- // Route a decode error to the callback (as fs.readFile does); a throw from a deferred callback
243
- // would escape as an uncaught exception and crash the process.
212
+ // A decode error goes to the callback, as fs.readFile's does: a throw here would be uncaught.
244
213
  const decodeToCb = (cb, buf, options) => {
245
214
  let out
246
215
  try { out = decode(buf, options) } catch (err) { cb(err); return }
@@ -282,8 +251,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
282
251
  const [opts, cb] = cbArgs(options, callback)
283
252
  const t = typeof cb === 'function' ? classify(path) : null
284
253
  if (t?.mode === 'absent') return later(cb, enoent('scandir', path))
285
- // Served/captured in the single-arg form only, where a null options must count as "no options"
286
- // (graceful-fs normalises to that), else its reads never hit the bundle.
254
+ // A null options counts as none: graceful-fs normalises to that, else its reads never hit the bundle.
287
255
  if (opts == null && t?.mode === 'serve') {
288
256
  const names = t.state.getFsDirFamily(t.url)
289
257
  if (names !== undefined) return later(cb, null, names)
@@ -311,16 +279,16 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
311
279
  return realReaddirP(path, options)
312
280
  }
313
281
 
314
- // lstat/stat mirror their sync siblings; bundleStats's field fallback stays sync.
282
+ // bundleStats's field fallback stays sync.
315
283
  const servedStat = (syscall, realFn, realSyncFn) => ({
316
284
  [syscall](path, options, callback) {
317
285
  const [opts, cb] = cbArgs(options, callback)
318
- const t = opts == null && typeof cb === 'function' ? classify(path) : null
319
- if (t?.mode === 'absent') return later(cb, enoent(syscall, path))
320
- if (t?.mode === 'serve') {
286
+ const t = typeof cb === 'function' ? classify(path) : null
287
+ if (t?.mode === 'absent') return realFn('', opts, (err, stats) => cb(asAbsent(syscall, path)(err), stats))
288
+ if (opts == null && t?.mode === 'serve') {
321
289
  const kind = t.state.getFsStatFamily(t.url)
322
290
  if (kind !== undefined) return later(cb, null, bundleStats(realSyncFn, path, kind === 'directory'))
323
- } else if (t?.mode === 'capture') {
291
+ } else if (opts == null && t?.mode === 'capture') {
324
292
  return realFn(path, (err, stats) => {
325
293
  if (err) return cb(err)
326
294
  captureStat(t, stats)
@@ -335,12 +303,12 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
335
303
 
336
304
  const servedStatP = (syscall, realFn, realSyncFn) => ({
337
305
  async [syscall](path, options) {
338
- const t = options == null ? classify(path) : null
339
- if (t?.mode === 'absent') throw enoent(syscall, path)
340
- if (t?.mode === 'serve') {
306
+ const t = classify(path)
307
+ if (t?.mode === 'absent') return realFn('', options).catch((err) => { throw asAbsent(syscall, path)(err) })
308
+ if (options == null && t?.mode === 'serve') {
341
309
  const kind = t.state.getFsStatFamily(t.url)
342
310
  if (kind !== undefined) return bundleStats(realSyncFn, path, kind === 'directory')
343
- } else if (t?.mode === 'capture') {
311
+ } else if (options == null && t?.mode === 'capture') {
344
312
  const stats = await realFn(path)
345
313
  captureStat(t, stats)
346
314
  return stats
@@ -379,14 +347,11 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
379
347
  fs.promises.realpath = async function realpath(path, options) {
380
348
  const t = classify(path)
381
349
  if (t?.mode === 'absent') throw enoent('realpath', path)
382
- if (served(t)) {
383
- try { return await realRealpathP(path, options) } catch { return encodeRealpath(t.abs, options) }
384
- }
385
- return realRealpathP(path, options)
350
+ if (!served(t)) return realRealpathP(path, options)
351
+ try { return await realRealpathP(path, options) } catch { return encodeRealpath(t.abs, options) }
386
352
  }
387
353
  }
388
354
 
389
- // Refresh the node:fs (+ node:fs/promises) ESM wrappers so user-code live imports see the patched fns.
390
355
  // INVARIANT: a stasis module needing the real fs must snapshot it (`const { ... } = fs`), never live-import.
391
356
  syncBuiltinESMExports()
392
357
  }