@exodus/stasis-core 1.0.0-beta.1 → 1.0.0-beta.3
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/README.md +1 -1
- package/bin/stasis-core.js +38 -28
- package/package.json +8 -1
- package/src/add.js +325 -0
- package/src/brotli.js +15 -16
- package/src/bundle-util.js +66 -0
- package/src/bundle.js +99 -88
- package/src/config.js +78 -104
- package/src/extract.js +159 -0
- package/src/fs.js +123 -313
- package/src/hooks.js +129 -449
- package/src/loader.js +1 -3
- package/src/lockfile.js +82 -62
- package/src/prune.js +37 -152
- package/src/shard.js +60 -0
- package/src/state-util.js +4 -26
- package/src/state.js +579 -1128
- package/src/util.js +545 -97
package/src/config.js
CHANGED
|
@@ -1,44 +1,35 @@
|
|
|
1
1
|
import assert from 'node:assert/strict'
|
|
2
2
|
|
|
3
3
|
import { canonicalizePath } from './state-util.js'
|
|
4
|
-
import { extSetsEqual, parseResourcesOption } from './util.js'
|
|
4
|
+
import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseResourcesOption } from './util.js'
|
|
5
5
|
|
|
6
6
|
const VALID_SCOPE = new Set(['node_modules', 'full'])
|
|
7
7
|
const VALID_LOCK = new Set(['none', 'ignore', 'add', 'replace', 'frozen'])
|
|
8
8
|
const VALID_BUNDLE = new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen'])
|
|
9
9
|
const VALID_FS = new Set(['sync', 'async'])
|
|
10
10
|
|
|
11
|
-
// The defaults Config applies when neither env nor options specify a value.
|
|
12
|
-
// Exported so callers (plugins.js error messages) can reference the same source of
|
|
13
|
-
// truth instead of hardcoding the literal -- a default drift then surfaces at one
|
|
14
|
-
// place, not silently in a user-facing message.
|
|
15
11
|
export const DEFAULT_LOCK = 'add'
|
|
16
12
|
export const DEFAULT_BUNDLE = 'none'
|
|
17
13
|
export const DEFAULT_SCOPE = 'full'
|
|
18
14
|
|
|
19
|
-
// Strict
|
|
20
|
-
// ('no', 'off', ...) throws -- a truthiness parse would read those as *enabling* the
|
|
21
|
-
// toggle, and a misconfigured env var should fail loudly, not silently flip a feature on.
|
|
15
|
+
// Strict, not truthy: a truthiness parse would read 'no'/'off' as *enabling* the toggle.
|
|
22
16
|
const envBool = (name, value) => {
|
|
23
17
|
if (value === '' || value === '0' || value === 'false') return false
|
|
24
18
|
if (value === '1' || value === 'true') return true
|
|
25
19
|
throw new RangeError(`${name} must be ''/'0'/'false' or '1'/'true' (got '${value}')`)
|
|
26
20
|
}
|
|
27
21
|
|
|
28
|
-
// EXODUS_STASIS_RESOURCES is a comma-separated extension list;
|
|
29
|
-
// empties so '' and ' png , svg ' normalize predictably (parseResourcesOption then
|
|
30
|
-
// validates each entry). An empty/unset env var means "no allowlist".
|
|
22
|
+
// EXODUS_STASIS_RESOURCES is a comma-separated extension list; empty/unset means "no allowlist".
|
|
31
23
|
const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
|
|
32
24
|
|
|
33
|
-
const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'resources', 'childProcess']
|
|
25
|
+
const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'resources', 'childProcess', 'packageJSON']
|
|
34
26
|
|
|
35
|
-
// Plugins
|
|
36
|
-
// since constructing State has side effects. Mirror Config's per-field validation.
|
|
27
|
+
// Plugins validate the same options without constructing a Config (which has side effects).
|
|
37
28
|
export function validatePluginOptions(label, options) {
|
|
38
29
|
const rest = { ...options }
|
|
39
30
|
for (const key of OPTION_KEYS) delete rest[key]
|
|
40
31
|
assert.equal(Object.keys(rest).length, 0, `Unknown ${label} options: ${Object.keys(rest).join(', ')}`)
|
|
41
|
-
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess } = options
|
|
32
|
+
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON } = options
|
|
42
33
|
if (scope !== undefined) assert.ok(VALID_SCOPE.has(scope), `Invalid scope: ${scope}`)
|
|
43
34
|
if (lock !== undefined) assert.ok(VALID_LOCK.has(lock), `Invalid lock: ${lock}`)
|
|
44
35
|
if (bundle !== undefined) assert.ok(VALID_BUNDLE.has(bundle), `Invalid bundle: ${bundle}`)
|
|
@@ -46,18 +37,14 @@ export function validatePluginOptions(label, options) {
|
|
|
46
37
|
if (resourcesBundleFile !== undefined) assert.equal(typeof resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
|
|
47
38
|
if (debug !== undefined) assert.equal(typeof debug, 'boolean', 'debug must be a boolean')
|
|
48
39
|
if (childProcess !== undefined) assert.equal(typeof childProcess, 'boolean', 'childProcess must be a boolean')
|
|
49
|
-
|
|
50
|
-
// malformed extensions, or a code extension (those are always tracked, never resources).
|
|
40
|
+
if (packageJSON !== undefined) assert.equal(typeof packageJSON, 'boolean', 'packageJSON must be a boolean')
|
|
51
41
|
if (resources !== undefined) parseResourcesOption(label, resources)
|
|
52
42
|
}
|
|
53
43
|
|
|
54
|
-
//
|
|
55
|
-
// is authoritative. Any options the plugin was given must agree with it.
|
|
44
|
+
// The active Config is authoritative; options a plugin was given must agree with it.
|
|
56
45
|
export function assertOptionsMatchConfig(config, options) {
|
|
57
|
-
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess } = options
|
|
58
|
-
// `resources` is
|
|
59
|
-
// which assert.equal can't express) and is coordinated explicitly in resolvePluginState
|
|
60
|
-
// before this runs -- don't "fix" the omission with assert.equal(config.resources, ...).
|
|
46
|
+
const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, packageJSON } = options
|
|
47
|
+
// `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
|
|
61
48
|
try {
|
|
62
49
|
if (scope !== undefined) assert.equal(config.scope, scope)
|
|
63
50
|
if (lock !== undefined) assert.equal(config.lock, lock)
|
|
@@ -66,10 +53,8 @@ export function assertOptionsMatchConfig(config, options) {
|
|
|
66
53
|
if (resourcesBundleFile !== undefined) assert.equal(config.resourcesBundleFile, resourcesBundleFile)
|
|
67
54
|
if (debug !== undefined) assert.equal(config.debug, debug)
|
|
68
55
|
if (childProcess !== undefined) assert.equal(config.childProcess, childProcess)
|
|
56
|
+
if (packageJSON !== undefined) assert.equal(config.packageJSON, packageJSON)
|
|
69
57
|
} catch (cause) {
|
|
70
|
-
// Re-throw with the underlying assertion message folded into the top-level
|
|
71
|
-
// text -- a plugin author hitting this gets the offending field's name and
|
|
72
|
-
// expected/actual values without having to inspect err.cause.
|
|
73
58
|
throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
|
|
74
59
|
}
|
|
75
60
|
}
|
|
@@ -86,20 +71,16 @@ export class Config {
|
|
|
86
71
|
#resources
|
|
87
72
|
#debug
|
|
88
73
|
#childProcess
|
|
74
|
+
#packageJSON
|
|
75
|
+
#shardSignalFlush
|
|
89
76
|
#fs
|
|
77
|
+
#brotliQuality
|
|
90
78
|
|
|
91
|
-
//
|
|
92
|
-
// resources/childProcess/fs).
|
|
93
|
-
// Env vars take effect at construction time; if both env and an option are set they must
|
|
94
|
-
// agree. Likewise, any explicit constructor option is treated as authoritative: a later
|
|
95
|
-
// `loadConfig` call (which reads stasis.config.json) must agree with it -- the alternative
|
|
96
|
-
// (silently overwriting `--scope=full` with the file's `"scope":"node_modules"`)
|
|
97
|
-
// was a footgun the CLI couldn't detect, since the flag was happily accepted
|
|
98
|
-
// and then quietly ignored.
|
|
79
|
+
// Env and options must agree when both are set; #explicit is kept so a later loadConfig can't override them.
|
|
99
80
|
constructor(options = {}) {
|
|
100
|
-
const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, ...rest } = options
|
|
81
|
+
const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON, fs, brotliQuality, ...rest } = options
|
|
101
82
|
assert.equal(Object.keys(rest).length, 0, `Unknown Config options: ${Object.keys(rest).join(', ')}`)
|
|
102
|
-
this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs }
|
|
83
|
+
this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, packageJSON, fs, brotliQuality }
|
|
103
84
|
|
|
104
85
|
this.#env = {
|
|
105
86
|
scope: process.env.EXODUS_STASIS_SCOPE || undefined,
|
|
@@ -111,7 +92,10 @@ export class Config {
|
|
|
111
92
|
debug: process.env.EXODUS_STASIS_DEBUG || undefined,
|
|
112
93
|
resources: process.env.EXODUS_STASIS_RESOURCES || undefined,
|
|
113
94
|
childProcess: process.env.EXODUS_STASIS_CHILD_PROCESS || undefined,
|
|
95
|
+
packageJSON: process.env.EXODUS_STASIS_PACKAGE_JSON || undefined,
|
|
96
|
+
shardSignalFlush: process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH || undefined,
|
|
114
97
|
fs: process.env.EXODUS_STASIS_FS || undefined,
|
|
98
|
+
brotliQuality: process.env.EXODUS_STASIS_BROTLI_QUALITY || undefined,
|
|
115
99
|
}
|
|
116
100
|
|
|
117
101
|
try {
|
|
@@ -133,10 +117,14 @@ export class Config {
|
|
|
133
117
|
if (this.#env.childProcess !== undefined && childProcess !== undefined) {
|
|
134
118
|
assert.equal(envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess), childProcess)
|
|
135
119
|
}
|
|
120
|
+
if (this.#env.packageJSON !== undefined && packageJSON !== undefined) {
|
|
121
|
+
assert.equal(envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON), packageJSON)
|
|
122
|
+
}
|
|
136
123
|
if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
124
|
+
if (this.#env.brotliQuality !== undefined && brotliQuality !== undefined) {
|
|
125
|
+
assert.equal(parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality), brotliQuality)
|
|
126
|
+
}
|
|
127
|
+
// Compare parsed sets, not raw strings: ['png','svg'] and 'svg,png' are the same allowlist.
|
|
140
128
|
if (this.#env.resources !== undefined && resources !== undefined) {
|
|
141
129
|
assert.ok(
|
|
142
130
|
extSetsEqual(parseResourcesOption('env', envList(this.#env.resources)), parseResourcesOption('options', resources)),
|
|
@@ -155,10 +143,15 @@ export class Config {
|
|
|
155
143
|
this.#resourcesBundleFile = this.#env.resourcesBundleFile || resourcesBundleFile || undefined
|
|
156
144
|
this.#debug = this.#env.debug !== undefined ? envBool('EXODUS_STASIS_DEBUG', this.#env.debug) : (debug ?? false)
|
|
157
145
|
this.#childProcess = this.#env.childProcess !== undefined ? envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess) : (childProcess ?? false)
|
|
158
|
-
|
|
146
|
+
this.#packageJSON = this.#env.packageJSON !== undefined ? envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON) : (packageJSON ?? false)
|
|
147
|
+
this.#shardSignalFlush = this.#env.shardSignalFlush !== undefined
|
|
148
|
+
? envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', this.#env.shardSignalFlush)
|
|
149
|
+
: false
|
|
159
150
|
this.#fs = this.#env.fs || fs || undefined
|
|
160
|
-
//
|
|
161
|
-
|
|
151
|
+
// No `||` chaining here -- 0 is a valid quality and falsy.
|
|
152
|
+
this.#brotliQuality = this.#env.brotliQuality !== undefined
|
|
153
|
+
? parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality)
|
|
154
|
+
: brotliQuality
|
|
162
155
|
this.#resources = parseResourcesOption(
|
|
163
156
|
'resources',
|
|
164
157
|
this.#env.resources !== undefined ? envList(this.#env.resources) : resources
|
|
@@ -167,19 +160,19 @@ export class Config {
|
|
|
167
160
|
this.#checkInvariants()
|
|
168
161
|
}
|
|
169
162
|
|
|
170
|
-
// Per-field validation + cross-field invariants. Constructor (options path) and
|
|
171
|
-
// loadConfig (disk path) both call this so the rules live in one place.
|
|
172
163
|
#checkInvariants() {
|
|
173
164
|
assert.ok(VALID_SCOPE.has(this.#scope), `Invalid scope: ${this.#scope}`)
|
|
174
165
|
assert.ok(VALID_LOCK.has(this.#lock), `Invalid lock: ${this.#lock}`)
|
|
175
166
|
assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
|
|
176
167
|
assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
|
|
177
168
|
assert.equal(typeof this.#childProcess, 'boolean', 'childProcess must be a boolean')
|
|
169
|
+
assert.equal(typeof this.#packageJSON, 'boolean', 'packageJSON must be a boolean')
|
|
170
|
+
if (this.#brotliQuality !== undefined && !isBrotliQuality(this.#brotliQuality)) {
|
|
171
|
+
throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(this.#brotliQuality)})`)
|
|
172
|
+
}
|
|
178
173
|
if (this.#fs !== undefined) {
|
|
179
174
|
assert.ok(VALID_FS.has(this.#fs), `Invalid fs: ${this.#fs}`)
|
|
180
|
-
// --fs
|
|
181
|
-
// from it (load); with any other bundle mode it has nothing to record into or read from.
|
|
182
|
-
// Mirrors the CLI's "--fs requires --bundle=(add|replace|load)" guard.
|
|
175
|
+
// --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
|
|
183
176
|
if (this.#bundle !== 'add' && this.#bundle !== 'replace' && this.#bundle !== 'load') {
|
|
184
177
|
throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${this.#bundle}')`)
|
|
185
178
|
}
|
|
@@ -187,26 +180,18 @@ export class Config {
|
|
|
187
180
|
if (this.#bundleFile !== undefined) assert.equal(typeof this.#bundleFile, 'string', 'bundleFile must be a string')
|
|
188
181
|
if (this.#lockFile !== undefined) {
|
|
189
182
|
assert.equal(typeof this.#lockFile, 'string', 'lockFile must be a string')
|
|
190
|
-
// lockFile is only meaningful when there IS a lockfile. Lock modes that opt out
|
|
191
|
-
// (none / ignore) would silently ignore the path -- catch the misconfig explicitly.
|
|
192
183
|
if (this.#lock === 'none' || this.#lock === 'ignore') {
|
|
193
184
|
throw new RangeError(`lockFile requires an active lock mode (got lock='${this.#lock}')`)
|
|
194
185
|
}
|
|
195
186
|
}
|
|
196
187
|
if (this.#resourcesBundleFile !== undefined) {
|
|
197
188
|
assert.equal(typeof this.#resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
|
|
198
|
-
// The split is only meaningful when there IS a bundle to split. With bundle=none / ignore the
|
|
199
|
-
// option would be silently inert -- catch the misconfiguration explicitly instead.
|
|
200
189
|
if (this.#bundle === 'none' || this.#bundle === 'ignore') {
|
|
201
190
|
throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${this.#bundle}')`)
|
|
202
191
|
}
|
|
203
192
|
}
|
|
204
193
|
|
|
205
|
-
//
|
|
206
|
-
// resourcesBundleFile) must each name a distinct on-disk file. Canonicalize via
|
|
207
|
-
// resolve() + realpathSync so './x.br' vs 'x.br', and two symlinks to the same
|
|
208
|
-
// inode, both compare equal -- a raw string compare would let `./out/x.br` and
|
|
209
|
-
// `out/x.br` slip past and the second writer would silently clobber the first.
|
|
194
|
+
// Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
|
|
210
195
|
const claimed = new Map()
|
|
211
196
|
for (const [label, value] of [
|
|
212
197
|
['lockFile', this.#lockFile],
|
|
@@ -221,23 +206,12 @@ export class Config {
|
|
|
221
206
|
claimed.set(canonical, label)
|
|
222
207
|
}
|
|
223
208
|
|
|
224
|
-
// bundle=load needs a trust root
|
|
225
|
-
// the lockfile and we cross-check it on load; otherwise the bundle is itself
|
|
226
|
-
// authoritative -- lock=none with no lockfile on disk, or lock=ignore with a lockfile
|
|
227
|
-
// deliberately bypassed.
|
|
228
|
-
// WARNING: the lockfile attests source bytes, entries, module identity, and
|
|
229
|
-
// (when it records them) resolutions and loader formats. Lockfiles predating
|
|
230
|
-
// a given attestation cover only what they recorded (bytes at minimum).
|
|
209
|
+
// bundle=load needs a trust root: frozen pins each file's sha512, else the bundle itself is it (none/ignore).
|
|
231
210
|
if (this.#bundle === 'load' && this.#lock !== 'frozen' && this.#lock !== 'none' && this.#lock !== 'ignore') {
|
|
232
211
|
throw new RangeError('bundle=load is incompatible with lock=(add|replace)')
|
|
233
212
|
}
|
|
234
213
|
|
|
235
|
-
// bundle=frozen
|
|
236
|
-
// bundle's bytes, it reads each file from disk and verifies it against the bundle's
|
|
237
|
-
// own recorded bytes/resolutions/formats (the bundle is itself the trust root, so it
|
|
238
|
-
// needs no sibling lockfile -- it "operates as a lockfile"). It composes with any lock
|
|
239
|
-
// mode, and (being a real bundle) satisfies the "needs a lockfile or a bundle" rule
|
|
240
|
-
// below -- which only rejects leaving both unset.
|
|
214
|
+
// bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
|
|
241
215
|
if (this.#lock === 'none' && this.#bundle === 'none') {
|
|
242
216
|
throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
|
|
243
217
|
}
|
|
@@ -252,7 +226,9 @@ export class Config {
|
|
|
252
226
|
resourcesBundleFile = this.#resourcesBundleFile,
|
|
253
227
|
debug = this.#debug,
|
|
254
228
|
childProcess = this.#childProcess,
|
|
229
|
+
packageJSON = this.#packageJSON,
|
|
255
230
|
fs = this.#fs,
|
|
231
|
+
brotliQuality = this.#brotliQuality,
|
|
256
232
|
resources,
|
|
257
233
|
...rest
|
|
258
234
|
} = JSON.parse(json)
|
|
@@ -260,14 +236,14 @@ export class Config {
|
|
|
260
236
|
this.#scope = scope
|
|
261
237
|
this.#lock = lock
|
|
262
238
|
this.#bundle = bundle
|
|
263
|
-
//
|
|
264
|
-
// everywhere downstream (State consumes bundleFile truthily), but #checkInvariants would
|
|
265
|
-
// otherwise resolve('') -> cwd and claim it as a write target.
|
|
239
|
+
// '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
|
|
266
240
|
this.#bundleFile = bundleFile || undefined
|
|
267
241
|
this.#resourcesBundleFile = resourcesBundleFile || undefined
|
|
268
242
|
this.#debug = debug
|
|
269
243
|
this.#childProcess = childProcess
|
|
244
|
+
this.#packageJSON = packageJSON
|
|
270
245
|
this.#fs = fs
|
|
246
|
+
this.#brotliQuality = brotliQuality
|
|
271
247
|
if (resources !== undefined) this.#resources = parseResourcesOption('stasis.config.json', resources)
|
|
272
248
|
this.#checkInvariants()
|
|
273
249
|
|
|
@@ -279,14 +255,16 @@ export class Config {
|
|
|
279
255
|
if (this.#env.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#env.resourcesBundleFile)
|
|
280
256
|
if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool('EXODUS_STASIS_DEBUG', this.#env.debug))
|
|
281
257
|
if (this.#env.childProcess !== undefined) assert.equal(this.#childProcess, envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess))
|
|
258
|
+
if (this.#env.packageJSON !== undefined) assert.equal(this.#packageJSON, envBool('EXODUS_STASIS_PACKAGE_JSON', this.#env.packageJSON))
|
|
282
259
|
if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
|
|
260
|
+
if (this.#env.brotliQuality !== undefined) {
|
|
261
|
+
assert.equal(this.#brotliQuality, parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality))
|
|
262
|
+
}
|
|
283
263
|
if (this.#env.resources !== undefined) {
|
|
284
264
|
assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
|
|
285
265
|
'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
|
|
286
266
|
}
|
|
287
|
-
// Explicit constructor options are equally authoritative: an
|
|
288
|
-
// `--scope=full` shouldn't be silently overridden by an on-disk
|
|
289
|
-
// `{"scope":"node_modules"}`. The asserts mirror the env block above.
|
|
267
|
+
// Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
|
|
290
268
|
if (this.#explicit.scope !== undefined) assert.equal(this.#scope, this.#explicit.scope)
|
|
291
269
|
if (this.#explicit.lock !== undefined) assert.equal(this.#lock, this.#explicit.lock)
|
|
292
270
|
if (this.#explicit.bundle !== undefined) assert.equal(this.#bundle, this.#explicit.bundle)
|
|
@@ -294,7 +272,9 @@ export class Config {
|
|
|
294
272
|
if (this.#explicit.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#explicit.resourcesBundleFile)
|
|
295
273
|
if (this.#explicit.debug !== undefined) assert.equal(this.#debug, this.#explicit.debug)
|
|
296
274
|
if (this.#explicit.childProcess !== undefined) assert.equal(this.#childProcess, this.#explicit.childProcess)
|
|
275
|
+
if (this.#explicit.packageJSON !== undefined) assert.equal(this.#packageJSON, this.#explicit.packageJSON)
|
|
297
276
|
if (this.#explicit.fs !== undefined) assert.equal(this.#fs, this.#explicit.fs)
|
|
277
|
+
if (this.#explicit.brotliQuality !== undefined) assert.equal(this.#brotliQuality, this.#explicit.brotliQuality)
|
|
298
278
|
if (this.#explicit.resources !== undefined) {
|
|
299
279
|
assert.ok(extSetsEqual(this.#resources, parseResourcesOption('options', this.#explicit.resources)),
|
|
300
280
|
'resources in stasis.config.json must match the resources option')
|
|
@@ -308,25 +288,17 @@ export class Config {
|
|
|
308
288
|
return this.#bundleFile
|
|
309
289
|
}
|
|
310
290
|
|
|
311
|
-
//
|
|
312
|
-
// discovering `stasis.lock.json` at the project root. Set via the CLI,
|
|
313
|
-
// `EXODUS_STASIS_LOCK_FILE`, or direct State construction; bundler plugins
|
|
314
|
-
// can't set it (they always share the ambient lockfile). Unset -> default
|
|
315
|
-
// discovery applies.
|
|
291
|
+
// Exact lockfile path, bypassing `stasis.lock.json` discovery; bundler plugins can't set it.
|
|
316
292
|
get lockFile() {
|
|
317
293
|
return this.#lockFile
|
|
318
294
|
}
|
|
319
295
|
|
|
320
|
-
// When set,
|
|
321
|
-
// bundle=load reads both. Unset is the default unified-bundle behavior.
|
|
296
|
+
// When set, resources go to this file and code-only to bundleFile; bundle=load reads both.
|
|
322
297
|
get resourcesBundleFile() {
|
|
323
298
|
return this.#resourcesBundleFile
|
|
324
299
|
}
|
|
325
300
|
|
|
326
|
-
//
|
|
327
|
-
// filenames that classifyExtension treats as asset payloads. Drives both the plugins'
|
|
328
|
-
// per-import classification and State's `--fs` capture, so the two share one list.
|
|
329
|
-
// Empty Set when no allowlist was configured (option or EXODUS_STASIS_RESOURCES).
|
|
301
|
+
// Set of lowercase extensions/filenames treated as asset payloads.
|
|
330
302
|
get resources() {
|
|
331
303
|
return this.#resources
|
|
332
304
|
}
|
|
@@ -335,25 +307,32 @@ export class Config {
|
|
|
335
307
|
return this.#debug
|
|
336
308
|
}
|
|
337
309
|
|
|
338
|
-
// Opt-in
|
|
339
|
-
// stasis.config.json): enable cross-process capture forwarding. A forked child (e.g. a
|
|
340
|
-
// Metro transform worker) writes a shard of what it captured into a root-owned dir, and
|
|
341
|
-
// the root merges it before writing -- so files only a child loads (a worker's babel
|
|
342
|
-
// toolchain) are attested. Off by default: the shard dir is a process-coordination channel,
|
|
343
|
-
// so it's only created when explicitly enabled. Not attested (not in `values`), like debug.
|
|
310
|
+
// Opt-in cross-process capture forwarding: a forked child writes a shard the root merges. Not attested.
|
|
344
311
|
get childProcess() {
|
|
345
312
|
return this.#childProcess
|
|
346
313
|
}
|
|
347
314
|
|
|
348
|
-
//
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
315
|
+
// Opt-in: bundle every bundled module's package.json even if the run never reached it. Not attested.
|
|
316
|
+
get packageJSON() {
|
|
317
|
+
return this.#packageJSON
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
// Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers),
|
|
321
|
+
// then re-delivers the signal. Not a user option, not attested.
|
|
322
|
+
get shardSignalFlush() {
|
|
323
|
+
return this.#shardSignalFlush
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
// --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
|
|
353
327
|
get fs() {
|
|
354
328
|
return this.#fs
|
|
355
329
|
}
|
|
356
330
|
|
|
331
|
+
// Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
|
|
332
|
+
get brotliQuality() {
|
|
333
|
+
return this.#brotliQuality
|
|
334
|
+
}
|
|
335
|
+
|
|
357
336
|
get values() {
|
|
358
337
|
return { scope: this.#scope }
|
|
359
338
|
}
|
|
@@ -382,11 +361,7 @@ export class Config {
|
|
|
382
361
|
return this.#bundle === 'load'
|
|
383
362
|
}
|
|
384
363
|
|
|
385
|
-
// bundle=frozen:
|
|
386
|
-
// It is loaded (its bytes/resolutions/entries/modules become the attested set) but
|
|
387
|
-
// never rewritten, and every file/resolution observed from disk is checked against
|
|
388
|
-
// it. Distinct from load (which serves bytes from the bundle instead of reading disk)
|
|
389
|
-
// and from add (which loads-then-rewrites and tolerates new files).
|
|
364
|
+
// bundle=frozen: loaded, never rewritten, and disk is checked against it (load serves bytes instead).
|
|
390
365
|
get frozenBundle() {
|
|
391
366
|
return this.#bundle === 'frozen'
|
|
392
367
|
}
|
|
@@ -425,8 +400,7 @@ export class Config {
|
|
|
425
400
|
|
|
426
401
|
get json() {
|
|
427
402
|
const data = { scope: this.#scope, lock: this.#lock, bundle: this.#bundle }
|
|
428
|
-
// resources
|
|
429
|
-
// when non-empty so configs without an allowlist serialize byte-identically as before.
|
|
403
|
+
// Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
|
|
430
404
|
if (this.#resources.size > 0) data.resources = [...this.#resources].toSorted()
|
|
431
405
|
return JSON.stringify(data, undefined, 2) + '\n'
|
|
432
406
|
}
|
package/src/extract.js
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
|
|
2
|
+
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
|
|
3
|
+
import { brotliDecompressSync } from 'node:zlib'
|
|
4
|
+
|
|
5
|
+
import { Bundle } from './bundle.js'
|
|
6
|
+
import { Lockfile } from './lockfile.js'
|
|
7
|
+
import { sha512integrity } from './state-util.js'
|
|
8
|
+
import { EXECUTE_BITS, canObserveExecuteBits, moduleFileKey } from './util.js'
|
|
9
|
+
|
|
10
|
+
const FILE_LOCK = 'stasis.lock.json'
|
|
11
|
+
|
|
12
|
+
// Buffer.from silently drops invalid chars, so a tampered `resource:base64` could hash-spoof; require a fixed point.
|
|
13
|
+
function assertCanonicalBase64(content, file) {
|
|
14
|
+
const buf = Buffer.from(content, 'base64')
|
|
15
|
+
if (buf.toString('base64') !== content) {
|
|
16
|
+
throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
|
|
17
|
+
}
|
|
18
|
+
return buf
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export function lockfileFromBundle(bundle) {
|
|
22
|
+
const modules = new Map()
|
|
23
|
+
for (const [dir, { name, version, ecosystem, files }] of bundle.modules) {
|
|
24
|
+
const hashed = Object.create(null)
|
|
25
|
+
for (const [rel, content] of Object.entries(files)) {
|
|
26
|
+
// Hash the raw on-disk bytes, so decode 'resource:base64' back first.
|
|
27
|
+
const file = moduleFileKey(dir, rel)
|
|
28
|
+
const bytes = bundle.formats.get(file) === 'resource:base64'
|
|
29
|
+
? assertCanonicalBase64(content, file)
|
|
30
|
+
: content
|
|
31
|
+
hashed[rel] = sha512integrity(bytes)
|
|
32
|
+
}
|
|
33
|
+
modules.set(dir, ecosystem === undefined
|
|
34
|
+
? { name, version, files: hashed }
|
|
35
|
+
: { name, version, ecosystem, files: hashed })
|
|
36
|
+
}
|
|
37
|
+
// Carry imports+formats across, else the derived lockfile is bytes-only and a later frozen run skips those cross-checks.
|
|
38
|
+
return new Lockfile({
|
|
39
|
+
config: bundle.config,
|
|
40
|
+
entries: bundle.entries,
|
|
41
|
+
modules,
|
|
42
|
+
imports: bundle.imports,
|
|
43
|
+
formats: bundle.formats,
|
|
44
|
+
// Same file set as the bundle, so its executable list transfers as-is.
|
|
45
|
+
executable: bundle.executable,
|
|
46
|
+
})
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function extractCommand({ cwd = process.cwd(), bundleFile, output, logLabel = 'stasis-core' } = {}) {
|
|
50
|
+
if (!bundleFile) throw new Error('extract: a bundle file is required')
|
|
51
|
+
const bundleAbs = resolve(cwd, bundleFile)
|
|
52
|
+
if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
|
|
53
|
+
|
|
54
|
+
let bundle
|
|
55
|
+
try {
|
|
56
|
+
bundle = Bundle.parse(brotliDecompressSync(readFileSync(bundleAbs)).toString('utf-8'))
|
|
57
|
+
} catch (cause) {
|
|
58
|
+
// Bundle.parse throws message-less asserts; wrap so the user learns which file failed.
|
|
59
|
+
throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// v0 bundles have null metadata, so no lockfile can be derived (serialize requires name+version).
|
|
63
|
+
const withLockfile = bundle.version === Bundle.VERSION
|
|
64
|
+
|
|
65
|
+
const outDir = resolve(cwd, output ?? '.')
|
|
66
|
+
const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
|
|
67
|
+
const lockAbs = join(outDir, FILE_LOCK)
|
|
68
|
+
|
|
69
|
+
// Plan-first: every target is validated inside outDir before any write; walk modules, not the last-wins
|
|
70
|
+
// `sources` getter. Containment is lexical -- symlinks are followed, so untrusted bundles need a fresh dir (doc/extract.md).
|
|
71
|
+
const writes = []
|
|
72
|
+
const targets = new Set()
|
|
73
|
+
let executables = 0
|
|
74
|
+
for (const [dir, { files }] of bundle.modules) {
|
|
75
|
+
for (const [rel, content] of Object.entries(files)) {
|
|
76
|
+
// `key` is the per-file map key (moduleFileKey handles rel === ''); `file` below is the WRITE path and keeps
|
|
77
|
+
// the plain join, so a non-`directory` rel === '' fails the canonical-path check instead of writing at the bucket root.
|
|
78
|
+
const key = moduleFileKey(dir, rel)
|
|
79
|
+
// Skip a `directory` capture: it's a listing at the dir's own path, not a file to write (its children recreate the dir).
|
|
80
|
+
if (bundle.formats.get(key) === 'directory') continue
|
|
81
|
+
const file = dir === '.' ? rel : `${dir}/${rel}`
|
|
82
|
+
if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
|
|
83
|
+
const abs = resolve(outDir, file)
|
|
84
|
+
const relToOut = relative(outDir, abs)
|
|
85
|
+
// The `..` test is `../`-aware, NOT a bare startsWith('..') -- that would reject a legit `..foo` filename.
|
|
86
|
+
if (relToOut === '..' || relToOut.startsWith(`..${sep}`) || isAbsolute(relToOut) || !abs.startsWith(outPrefix)) {
|
|
87
|
+
throw new Error(`extract: bundle path escapes output dir: ${file}`)
|
|
88
|
+
}
|
|
89
|
+
// A non-canonical path changes under the resolve+relative round-trip; writing it desyncs tree from lockfile.
|
|
90
|
+
if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
|
|
91
|
+
if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
|
|
92
|
+
if (withLockfile && abs === lockAbs) {
|
|
93
|
+
throw new Error(`extract: bundle contains ${FILE_LOCK}, which would collide with the derived lockfile`)
|
|
94
|
+
}
|
|
95
|
+
targets.add(abs)
|
|
96
|
+
// Executability rides the plan tuple, so the chmod can only ever reach a file we actually wrote.
|
|
97
|
+
const exec = bundle.executable.has(key)
|
|
98
|
+
if (exec) executables += 1
|
|
99
|
+
const data = bundle.formats.get(key) === 'resource:base64'
|
|
100
|
+
? assertCanonicalBase64(content, file)
|
|
101
|
+
: content
|
|
102
|
+
writes.push([abs, data, exec])
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
// A planned file must not also be a parent directory of another, else the writes throw halfway through.
|
|
106
|
+
for (const [abs] of writes) {
|
|
107
|
+
for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) {
|
|
108
|
+
if (targets.has(d)) {
|
|
109
|
+
throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
|
|
114
|
+
|
|
115
|
+
// Only the execute bit is attested, so only it is touched -- rw bits stay as written (never widen a 0600 target)
|
|
116
|
+
// and setuid/setgid/sticky are cleared. Applied to every written file; skipped for v0, which attests no modes.
|
|
117
|
+
const withModes = withLockfile && canObserveExecuteBits()
|
|
118
|
+
let chmodFailures = 0
|
|
119
|
+
const applyMode = (abs, exec) => {
|
|
120
|
+
let stats
|
|
121
|
+
try {
|
|
122
|
+
stats = lstatSync(abs)
|
|
123
|
+
} catch {
|
|
124
|
+
chmodFailures += 1
|
|
125
|
+
return
|
|
126
|
+
}
|
|
127
|
+
// Never chmod through a symlink: +x on a link's target could make an arbitrary file outside outDir runnable.
|
|
128
|
+
if (stats.isSymbolicLink()) return
|
|
129
|
+
const perms = stats.mode & 0o7777
|
|
130
|
+
const rwx = perms & 0o777
|
|
131
|
+
// Execute wherever readable, with owner-execute as a floor so an aggressive umask can't defeat it.
|
|
132
|
+
const want = exec ? rwx | ((rwx & 0o444) >> 2) | 0o100 : rwx & ~EXECUTE_BITS
|
|
133
|
+
if (want === perms) return
|
|
134
|
+
// Tolerated per file: a mode-less filesystem (vfat/exFAT/CIFS) accepts the write and rejects the chmod.
|
|
135
|
+
try {
|
|
136
|
+
chmodSync(abs, want)
|
|
137
|
+
} catch {
|
|
138
|
+
chmodFailures += 1
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
for (const [abs, content, exec] of writes) {
|
|
143
|
+
mkdirSync(dirname(abs), { recursive: true })
|
|
144
|
+
writeFileSync(abs, content)
|
|
145
|
+
if (withModes) applyMode(abs, exec)
|
|
146
|
+
}
|
|
147
|
+
mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
|
|
148
|
+
if (withLockfile) writeFileSync(lockAbs, lockText)
|
|
149
|
+
|
|
150
|
+
const execNote = executables > 0 ? ` (${executables} executable)` : ''
|
|
151
|
+
console.warn(`[${logLabel}] Extracted ${writes.length} file(s)${execNote}${withLockfile ? ` and ${FILE_LOCK}` : ''} to ${outDir}`)
|
|
152
|
+
if (chmodFailures > 0) {
|
|
153
|
+
console.warn(`[${logLabel}] Warning: could not set file modes on ${chmodFailures} file(s) (the filesystem may not support them); contents were written`)
|
|
154
|
+
}
|
|
155
|
+
if (!withLockfile) {
|
|
156
|
+
console.warn(`[${logLabel}] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
|
|
157
|
+
}
|
|
158
|
+
return { dir: outDir, files: writes.length, executable: executables }
|
|
159
|
+
}
|