@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/bin/stasis-core.js +28 -109
- package/package.json +6 -2
- package/src/add.js +161 -157
- package/src/artifact-util.js +322 -217
- package/src/brotli.js +20 -6
- package/src/bundle-util.js +148 -98
- package/src/bundle.js +65 -128
- package/src/cli.js +123 -0
- package/src/config.js +74 -87
- package/src/extract.js +140 -67
- package/src/fs.js +57 -106
- package/src/hooks.js +126 -238
- package/src/host.js +9 -1
- package/src/loader.js +1 -1
- package/src/lockfile.js +58 -74
- package/src/policy.js +222 -0
- package/src/prune.js +60 -114
- package/src/shard.js +10 -25
- package/src/state-util.js +24 -9
- package/src/state.js +737 -862
- package/src/util.js +123 -172
package/src/fs.js
CHANGED
|
@@ -1,23 +1,18 @@
|
|
|
1
|
-
// `stasis run --fs
|
|
2
|
-
//
|
|
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
|
-
//
|
|
18
|
-
//
|
|
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
|
|
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
|
-
|
|
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
|
-
//
|
|
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 =
|
|
40
|
+
const encoding = encodingOf(options)
|
|
71
41
|
return encoding == null ? buf : buf.toString(encoding)
|
|
72
42
|
}
|
|
73
43
|
|
|
74
|
-
//
|
|
75
|
-
|
|
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
|
-
//
|
|
81
|
-
//
|
|
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
|
-
//
|
|
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 =
|
|
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
|
-
//
|
|
96
|
-
|
|
97
|
-
const
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
-
//
|
|
139
|
-
|
|
140
|
-
|
|
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'
|
|
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
|
-
//
|
|
118
|
+
// A rejected capture taints the run rather than failing the read.
|
|
156
119
|
const record = (fn) => { try { fn() } catch (err) { markAborted(err) } }
|
|
157
|
-
//
|
|
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))
|
|
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
|
-
//
|
|
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 =
|
|
207
|
-
if (t?.mode === 'absent')
|
|
208
|
-
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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 =
|
|
333
|
-
if (t?.mode === 'absent') return
|
|
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 =
|
|
353
|
-
if (t?.mode === 'absent') throw
|
|
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
|
-
|
|
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
|
}
|