@exodus/stasis-core 1.0.0-beta.8 → 1.0.0-rc.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/fs.js CHANGED
@@ -1,23 +1,18 @@
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'
9
6
  import { fileURLToPath, pathToFileURL } from 'node:url'
10
7
 
11
- import { realReadFileSync } from './state-util.js'
8
+ import { realContained, realReadFileSync } from './state-util.js'
12
9
  import { isDotEnvFile, isPathWithin, isStasisArtifactName } from './util.js'
13
10
 
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,68 +33,40 @@ function toAbsPath(path) {
40
33
  return null
41
34
  }
42
35
 
43
- let realRootCache
44
- function realRootOf(root) {
45
- if (realRootCache?.root !== root) {
46
- let real
47
- try { real = realRealpathSync(root) } catch { real = root }
48
- realRootCache = { root, real }
49
- }
50
- return realRootCache.real
51
- }
52
-
53
- // Capture-side containment: the path's REAL location must stay inside root's real path, else an
54
- // in-tree symlink pointing OUT would pull external content into the signed bundle.
55
- function realContained(root, abs) {
56
- let real
57
- try { real = realRealpathSync(abs) } catch { return false }
58
- return isPathWithin(realRootOf(root), real)
59
- }
36
+ const encodingOf = (options) => (typeof options === 'string' ? options : options?.encoding)
60
37
 
61
- // At the project root, drop stasis's own artifacts from the RECORDED listing so it doesn't depend on
62
- // whether an earlier run left them behind; the program still receives the true on-disk `names`.
63
- function dirCaptureNames(root, abs, names) {
64
- if (!isPathWithin(abs, root)) return names
65
- return names.filter((name) => !isStasisArtifactName(name))
66
- }
67
-
68
- // 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.
69
39
  function decode(buf, options) {
70
- const encoding = typeof options === 'string' ? options : options?.encoding
40
+ const encoding = encodingOf(options)
71
41
  return encoding == null ? buf : buf.toString(encoding)
72
42
  }
73
43
 
74
- // Honour realpath's `encoding` arg for the synthetic answer when a bundle-served path is gone from disk.
75
- function encodeRealpath(abs, options) {
76
- const encoding = typeof options === 'string' ? options : options?.encoding
77
- return encoding === 'buffer' ? Buffer.from(abs) : abs
78
- }
44
+ // The synthetic realpath of a bundle-served path gone from disk.
45
+ const encodeRealpath = (abs, options) => (encodingOf(options) === 'buffer' ? Buffer.from(abs) : abs)
79
46
 
80
- // NON-EXISTENT under --fs (a faithful ENOENT from every reader, listings included, in both modes):
81
- // source-map sidecars (`*.map`, so a captured build replays byte-identically; opt out via `map` in
82
- // resources) and `.env`/`.env.*` (an automated capture can never bake a secret in; no opt-in). The
83
- // 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.
84
49
  function isSkippedFsPath(state, abs) {
85
50
  const skipped = (abs.toLowerCase().endsWith('.map') && !state.config.resources?.has('map')) || isDotEnvFile(abs)
86
51
  return skipped && !(state.config.loadBundle && state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined)
87
52
  }
88
53
 
89
- // 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.
90
55
  function enoent(syscall, path) {
91
- const p = typeof path === 'string' ? path : Buffer.isBuffer(path) ? path.toString() : String(path)
56
+ const p = String(path)
92
57
  return Object.assign(new Error(`ENOENT: no such file or directory, ${syscall} '${p}'`), { code: 'ENOENT', errno: -2, syscall, path: p })
93
58
  }
94
59
 
95
- // File-type bits, so code reading stats.mode (not the is*() methods) still sees file-vs-dir.
96
- const S_IFREG = 0o100000
97
- 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)
98
63
 
99
- // Neutral fs.Stats-shaped record for a bundle-served path gone from disk; never throws, so wrappers
100
- // 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.
101
65
  function syntheticStat(isDir) {
102
66
  const epoch = new Date(0)
103
67
  return {
104
- 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,
105
70
  rdev: 0, size: 0, blksize: 4096, blocks: 0,
106
71
  atimeMs: 0, mtimeMs: 0, ctimeMs: 0, birthtimeMs: 0,
107
72
  atime: epoch, mtime: epoch, ctime: epoch, birthtime: epoch,
@@ -110,9 +75,7 @@ function syntheticStat(isDir) {
110
75
  }
111
76
  }
112
77
 
113
- // A Stats-like Proxy for a bundle-served path: isFile()/isDirectory() answer from the bundle, other
114
- // members from the REAL stat while on disk, else syntheticStat. `then` is short-circuited so a
115
- // 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`.
116
79
  function bundleStats(realStatFn, statPath, isDir) {
117
80
  let data
118
81
  const overrides = { isFile: () => !isDir, isDirectory: () => isDir }
@@ -135,35 +98,34 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
135
98
  if (installed) return
136
99
  installed = true
137
100
 
138
- // Classify a path for every hook: null passes through to the real fs; else { mode, abs, url, state }
139
- // with mode 'absent' (a skipped path: ENOENT), 'serve' (bundle=load; an uncaptured path still falls
140
- // through to disk) or 'capture' (bundle=add|replace, outside a loader read).
101
+ // Node's glob takes fs's readers when first loaded: load it on the real ones, so the `extra` sweep isn't captured.
102
+ fs.globSync([])
103
+
104
+ // null passes through to the real fs; 'serve' still falls through to disk for an uncaptured path.
141
105
  const classify = (path) => {
142
106
  const state = getState()
143
107
  if (!state) return null
144
108
  const abs = toAbsPath(path)
145
109
  if (abs === null || !isPathWithin(state.root, abs)) return null
146
- if (isSkippedFsPath(state, abs)) return { mode: 'absent', abs }
110
+ if (isSkippedFsPath(state, abs)) return { mode: 'absent' }
147
111
  const url = pathToFileURL(abs).toString()
148
112
  if (state.config.loadBundle) return { mode: 'serve', state, url, abs }
149
113
  if (state.config.writeBundle && !isLoadingModule()) return { mode: 'capture', state, url, abs }
150
114
  return null
151
115
  }
152
- // A path the bundle knows (content, listing, stat record or implied dir), for the serve-only probes.
153
116
  const served = (t) => t?.mode === 'serve' && t.state.getFsStatFamily(t.url) !== undefined
154
117
 
155
- // 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.
156
119
  const record = (fn) => { try { fn() } catch (err) { markAborted(err) } }
157
- // A path whose real location escapes root (in-tree symlink) is read but NOT recorded, and neither is
158
- // 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.
159
121
  const captureFile = ({ state, abs, url }, buf) => {
160
122
  if (realContained(state.root, abs) && !state.attestedBySidecar(url)) record(() => state.addFsFile(url, buf))
161
123
  }
162
124
  const captureDir = ({ state, abs, url }, names) => {
163
- 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))
164
128
  }
165
- // A stat records the path's KIND as a payload-free record so a stat-ONLY path's type getters answer
166
- // at load. Only file and dir are modelled.
167
129
  const captureStat = ({ state, abs, url }, stats) => {
168
130
  const isDir = stats.isDirectory()
169
131
  if (!isDir && !stats.isFile()) return
@@ -187,7 +149,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
187
149
  fs.readdirSync = function readdirSync(path, options) {
188
150
  const t = classify(path)
189
151
  if (t?.mode === 'absent') throw enoent('scandir', path)
190
- // Served/captured in the single-argument form only; any options pass straight through.
191
152
  if (options == null && t?.mode === 'serve') {
192
153
  const names = t.state.getFsDirFamily(t.url)
193
154
  if (names !== undefined) return names // sorted at capture time
@@ -199,16 +160,17 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
199
160
  return realReaddirSync(path, options)
200
161
  }
201
162
 
202
- // Single-arg form only; capture still hands the caller the REAL Stats/errors. statSync follows
203
- // 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.
204
164
  const servedStatSync = (syscall, realFn) => ({
205
165
  [`${syscall}Sync`](path, options) {
206
- const t = options == null ? classify(path) : null
207
- if (t?.mode === 'absent') throw enoent(syscall, path)
208
- 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') {
209
171
  const kind = t.state.getFsStatFamily(t.url)
210
172
  if (kind !== undefined) return bundleStats(realFn, path, kind === 'directory')
211
- } else if (t?.mode === 'capture') {
173
+ } else if (options == null && t?.mode === 'capture') {
212
174
  const stats = realFn(path)
213
175
  captureStat(t, stats)
214
176
  return stats
@@ -219,8 +181,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
219
181
  fs.lstatSync = servedStatSync('lstat', realLstatSync)
220
182
  fs.statSync = servedStatSync('stat', realStatSync)
221
183
 
222
- // existsSync/accessSync/realpathSync: existence + canonical-path PROBES, serve-only (bundle=load) --
223
- // 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.
224
185
  fs.existsSync = function existsSync(path) {
225
186
  const t = classify(path)
226
187
  if (t?.mode === 'absent') return false
@@ -234,27 +195,21 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
234
195
  return realAccessSync(path, mode)
235
196
  }
236
197
 
237
- // Try the real realpath first (true symlink resolution while on disk), fall back to the lexical abs
238
- // 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).
239
199
  const servedRealpathSync = (realFn) => function realpathSync(path, options) {
240
200
  const t = classify(path)
241
201
  if (t?.mode === 'absent') throw enoent('realpath', path)
242
- if (served(t)) {
243
- try { return realFn(path, options) } catch { return encodeRealpath(t.abs, options) }
244
- }
245
- return realFn(path, options)
202
+ if (!served(t)) return realFn(path, options)
203
+ try { return realFn(path, options) } catch { return encodeRealpath(t.abs, options) }
246
204
  }
247
205
  fs.realpathSync = servedRealpathSync(realRealpathSync)
248
206
  fs.realpathSync.native = servedRealpathSync(realRealpathSyncNative)
249
207
 
250
- // --fs=async counterparts; a served callback is deferred (queueMicrotask) to preserve fs's
251
- // always-async contract.
208
+ // A served callback is deferred, keeping fs's always-async contract.
252
209
  if (patchAsync) {
253
- // Split a trailing callback from its optional options argument.
254
210
  const cbArgs = (options, callback) => (typeof options === 'function' ? [undefined, options] : [options, callback])
255
211
  const later = (cb, ...args) => queueMicrotask(() => cb(...args))
256
- // Route a decode error to the callback (as fs.readFile does); a throw from a deferred callback
257
- // 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.
258
213
  const decodeToCb = (cb, buf, options) => {
259
214
  let out
260
215
  try { out = decode(buf, options) } catch (err) { cb(err); return }
@@ -296,8 +251,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
296
251
  const [opts, cb] = cbArgs(options, callback)
297
252
  const t = typeof cb === 'function' ? classify(path) : null
298
253
  if (t?.mode === 'absent') return later(cb, enoent('scandir', path))
299
- // Served/captured in the single-arg form only, where a null options must count as "no options"
300
- // (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.
301
255
  if (opts == null && t?.mode === 'serve') {
302
256
  const names = t.state.getFsDirFamily(t.url)
303
257
  if (names !== undefined) return later(cb, null, names)
@@ -325,16 +279,16 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
325
279
  return realReaddirP(path, options)
326
280
  }
327
281
 
328
- // lstat/stat mirror their sync siblings; bundleStats's field fallback stays sync.
282
+ // bundleStats's field fallback stays sync.
329
283
  const servedStat = (syscall, realFn, realSyncFn) => ({
330
284
  [syscall](path, options, callback) {
331
285
  const [opts, cb] = cbArgs(options, callback)
332
- const t = opts == null && typeof cb === 'function' ? classify(path) : null
333
- if (t?.mode === 'absent') return later(cb, enoent(syscall, path))
334
- 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') {
335
289
  const kind = t.state.getFsStatFamily(t.url)
336
290
  if (kind !== undefined) return later(cb, null, bundleStats(realSyncFn, path, kind === 'directory'))
337
- } else if (t?.mode === 'capture') {
291
+ } else if (opts == null && t?.mode === 'capture') {
338
292
  return realFn(path, (err, stats) => {
339
293
  if (err) return cb(err)
340
294
  captureStat(t, stats)
@@ -349,12 +303,12 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
349
303
 
350
304
  const servedStatP = (syscall, realFn, realSyncFn) => ({
351
305
  async [syscall](path, options) {
352
- const t = options == null ? classify(path) : null
353
- if (t?.mode === 'absent') throw enoent(syscall, path)
354
- 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') {
355
309
  const kind = t.state.getFsStatFamily(t.url)
356
310
  if (kind !== undefined) return bundleStats(realSyncFn, path, kind === 'directory')
357
- } else if (t?.mode === 'capture') {
311
+ } else if (options == null && t?.mode === 'capture') {
358
312
  const stats = await realFn(path)
359
313
  captureStat(t, stats)
360
314
  return stats
@@ -393,14 +347,11 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
393
347
  fs.promises.realpath = async function realpath(path, options) {
394
348
  const t = classify(path)
395
349
  if (t?.mode === 'absent') throw enoent('realpath', path)
396
- if (served(t)) {
397
- try { return await realRealpathP(path, options) } catch { return encodeRealpath(t.abs, options) }
398
- }
399
- 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) }
400
352
  }
401
353
  }
402
354
 
403
- // Refresh the node:fs (+ node:fs/promises) ESM wrappers so user-code live imports see the patched fns.
404
355
  // INVARIANT: a stasis module needing the real fs must snapshot it (`const { ... } = fs`), never live-import.
405
356
  syncBuiltinESMExports()
406
357
  }