@exodus/stasis-core 1.0.0-beta.2 → 1.0.0-beta.4

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/hooks.js CHANGED
@@ -8,34 +8,17 @@ import assert from 'node:assert/strict'
8
8
 
9
9
  import { State } from './state.js'
10
10
  import { installFsHooks } from './fs.js'
11
-
12
- // Snapshot off the namespace so `--fs` (which patches fs.readFileSync and then
13
- // syncBuiltinESMExports()s for user code) can't redirect the read the CJS-source
14
- // capture below relies on. Same rationale as state.js / state-util.js. The shard
15
- // readers/writers below are snapshotted for the same reason (and writes aren't patched
16
- // by --fs anyway, but reads are).
11
+ import {
12
+ NATIVE_BUILD_FORMATS as NATIVE_SOURCE_FORMATS,
13
+ NODE_FORMATS as NODEJS_FORMATS,
14
+ RESOURCE_FORMATS,
15
+ SOURCE_LANGUAGE_FORMATS as NON_NODE_SOURCE_LANGUAGES,
16
+ STAT_FORMATS,
17
+ } from './util.js'
18
+
19
+ // Snapshot off the namespace so `--fs` can't redirect stasis's own capture/shard reads.
17
20
  const { mkdtempSync, opendirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } = fs
18
21
 
19
- // Warning: only covers code imports, not file reads
20
-
21
- // Formats Node's module loader recognizes (and either executes, like `module`/
22
- // `commonjs`/typescript variants, or imports as data, like `json`). The runtime
23
- // loader treats this as the trust boundary -- a file served from the bundle whose
24
- // attested format is outside this allowlist is refused at load time (and earlier
25
- // at resolve, where applicable) with a contextual message. Adding a tag here
26
- // means "Node can handle it"; everything else (resource/asset content,
27
- // source-language bundles, an unknown string from a tampered or newer bundle)
28
- // fails closed.
29
- const NODEJS_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript'])
30
-
31
- // Per-kind messages for the few categories we recognize; everything else gets a
32
- // generic "unrecognized format" message. Kept separate from NODEJS_FORMATS so
33
- // the allowlist stays the single trust gate and the message is just UX.
34
- const NON_NODE_SOURCE_LANGUAGES = new Set(['solidity', 'php', 'bash', 'rust'])
35
- const RESOURCE_FORMATS = new Set(['resource', 'resource:base64'])
36
- const STAT_FORMATS = new Set(['stat:file', 'stat:directory'])
37
- // The executable CommonJS formats (plain CJS + TS-CJS). Named like the sets above so
38
- // "which formats are CJS" lives in one place; the require-repair below keys off it.
39
22
  const CJS_FORMATS = new Set(['commonjs', 'commonjs-typescript'])
40
23
 
41
24
  function refuseNonNodeFormat(format, url) {
@@ -45,12 +28,25 @@ function refuseNonNodeFormat(format, url) {
45
28
  `produced for external analysis, not for 'stasis run --bundle=load' (${url})`
46
29
  )
47
30
  }
31
+ if (NATIVE_SOURCE_FORMATS.has(format)) {
32
+ throw new Error(
33
+ `[stasis] cannot execute a '${format}' file: native build inputs ` +
34
+ `(podspec/gradle/Java/Kotlin/ObjC++/...) are attested for the CocoaPods/Gradle ` +
35
+ `toolchain, not executable by Node (${url})`
36
+ )
37
+ }
48
38
  if (RESOURCE_FORMATS.has(format)) {
49
39
  throw new Error(
50
40
  `[stasis] cannot import a resource file ('${format}'): asset content is not ` +
51
41
  `executable JavaScript. Read it with fs (or your bundler's asset loader) instead (${url})`
52
42
  )
53
43
  }
44
+ if (format === 'patch') {
45
+ throw new Error(
46
+ `[stasis] cannot execute a 'patch' file: a unified diff is applied by a patch step ` +
47
+ `(pnpm patchedDependencies, patch-package, a build script), not run by Node (${url})`
48
+ )
49
+ }
54
50
  if (format === 'directory') {
55
51
  throw new Error(
56
52
  `[stasis] cannot import a directory listing ('directory'): a captured ` +
@@ -64,7 +60,6 @@ function refuseNonNodeFormat(format, url) {
64
60
  `not the file's content. Capture a run that reads or imports it to bundle its bytes.`
65
61
  )
66
62
  }
67
- // Unknown format string: usually a tampered or forward-incompatible bundle.
68
63
  throw new Error(
69
64
  `[stasis] cannot execute '${url}': attested format '${format}' is not a Node loader ` +
70
65
  `format. The bundle may be tampered, produced by a newer stasis, or built for a ` +
@@ -72,14 +67,7 @@ function refuseNonNodeFormat(format, url) {
72
67
  )
73
68
  }
74
69
 
75
- // node:59666 workaround (see the load hook). A single-line prelude, injected
76
- // into served CommonJS source, that restores the `require.cache` and
77
- // `require.extensions` the ESM->CJS translator's re-invented require omits.
78
- // `require` here is the module wrapper's own parameter; node:module's CJS
79
- // loader owns the real `Module._cache` / `Module._extensions`, so pointing the
80
- // two properties at those makes a bundle-served module's require match a
81
- // disk-loaded one's shape. Guarded (typeof/try) so a require without the usual
82
- // shape, or a frozen builtins object, degrades to a no-op rather than throwing.
70
+ // node:59666: restores require.cache/require.extensions the ESM->CJS translator's require omits.
83
71
  const CJS_REQUIRE_REPAIR =
84
72
  "try{if(typeof require==='function'&&!require.cache){" +
85
73
  "const __stasis_m=require('node:module');" +
@@ -87,22 +75,11 @@ const CJS_REQUIRE_REPAIR =
87
75
  'require.cache=__stasis_m.Module._cache;' +
88
76
  'if(!require.extensions)require.extensions=__stasis_m.Module._extensions;}}}catch{}'
89
77
 
90
- // Sticky scanners for the pieces of a Directive Prologue: a run of whitespace and
91
- // line/block comments, a single string literal, and the run of horizontal space and
92
- // SAME-LINE block comments that may trail a directive before its terminator. Sticky (`y`)
93
- // + lastIndex so the prologue is walked in place, never by re-slicing the source each step.
94
78
  const WS_COMMENTS = /(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*/uy
95
79
  const STRING_LITERAL = /(['"])(?:[^\\]|\\.)*?\1/uy
96
- // A block comment that CONTAINS a line terminator counts as a line terminator for ASI, so
97
- // the trailing run stops at one (it's handled as a line boundary below); this matches only
98
- // single-line block comments (comment body has no line terminators).
80
+ // Matches only single-line block comments: a newline-spanning one counts as a line boundary for ASI.
99
81
  const TRAILING_SAME_LINE = /(?:[ \t]|\/\*(?:[^*\n\r\u2028\u2029]|\*(?!\/))*\*\/)*/uy
100
- // Tokens that CONTINUE an expression across a line break. If the first token after the
101
- // break following a candidate directive string is one of these, the string heads a
102
- // multi-line expression (`'a,b'\n.split(...)`, `'x'\ninstanceof Y`), not a directive
103
- // (ASI does not insert a semicolon before them), so it must NOT be skipped. Punctuators
104
- // are matched by first char; the two keyword operators need a `\b` so `in`/`instanceof`
105
- // don't swallow identifiers like `index`/`instances`.
82
+ // A directive string followed by one of these heads a multi-line expression, not a directive (ASI gotcha).
106
83
  const EXPR_CONTINUATION = new Set(['.', '[', '(', '`', '+', '-', '*', '/', '%', ',', '?', ':', '=', '<', '>', '&', '|', '^'])
107
84
  const KEYWORD_CONTINUATION = /(?:instanceof|in)\b/uy
108
85
  function skipSticky(re, source, i) {
@@ -110,9 +87,6 @@ function skipSticky(re, source, i) {
110
87
  re.exec(source)
111
88
  return re.lastIndex
112
89
  }
113
- // At a line boundary at `pos` (a line terminator or a newline-spanning block comment), does
114
- // the next significant token begin a NEW statement -- so the preceding string is a complete
115
- // directive -- rather than continue the expression?
116
90
  function newStatementAfterBreak(source, pos) {
117
91
  const afterBreak = skipSticky(WS_COMMENTS, source, pos)
118
92
  if (afterBreak >= source.length) return true
@@ -121,23 +95,8 @@ function newStatementAfterBreak(source, pos) {
121
95
  return !KEYWORD_CONTINUATION.test(source)
122
96
  }
123
97
 
124
- // Prepend CJS_REQUIRE_REPAIR to a served CommonJS module's source WITHOUT shifting line
125
- // numbers (the prelude adds no line break) and WITHOUT perturbing the module's Directive
126
- // Prologue -- so a `'use strict'` directive keeps strict mode. The prelude is a `try{...}`
127
- // statement: inserting it ahead of a directive would demote that directive to a plain
128
- // expression (dropping the module to sloppy mode), so we insert AFTER the prologue --
129
- // shebang, then whitespace, comments, and string-literal directive STATEMENTS. A leading
130
- // ';' makes the insertion self-terminating so it can never fuse `'use strict'try{` into a
131
- // SyntaxError.
132
- //
133
- // A leading string counts as a directive only when a real statement boundary follows it:
134
- // `;`, `}`, a line comment, EOF, or a LINE boundary -- a line terminator OR a block comment
135
- // containing one -- whose next token does not continue the expression. So a module that
136
- // opens with a string EXPRESSION (`'x'.toUpperCase()`, `'a' + b`, `'a,b'` newline-then-
137
- // `.split()`, `'x'` newline-then-`instanceof Y`) is left intact instead of being split
138
- // mid-expression (a SyntaxError, or silently wrong bytes), while a real directive followed
139
- // by a multi-line banner comment still keeps strict mode. Distinguishing the two is the ASI
140
- // problem, so this is a small scan rather than one regex.
98
+ // Insert CJS_REQUIRE_REPAIR AFTER the Directive Prologue with a leading ';', so a `'use strict'`
99
+ // stays strict and a leading string EXPRESSION isn't split mid-expression.
141
100
  function repairCjsRequire(source) {
142
101
  if (typeof source !== 'string') return source
143
102
  let i = 0
@@ -148,92 +107,47 @@ function repairCjsRequire(source) {
148
107
  for (;;) {
149
108
  const afterWs = skipSticky(WS_COMMENTS, source, i)
150
109
  STRING_LITERAL.lastIndex = afterWs
151
- if (STRING_LITERAL.exec(source) === null) break // next token isn't a string: end of prologue
110
+ if (STRING_LITERAL.exec(source) === null) break
152
111
  const afterStr = STRING_LITERAL.lastIndex
153
112
  const afterTrail = skipSticky(TRAILING_SAME_LINE, source, afterStr)
154
113
  const c = source[afterTrail]
155
114
  let isDirective
156
115
  if (c === undefined || c === ';' || c === '}') isDirective = true
157
- else if (c === '/' && source[afterTrail + 1] === '/') isDirective = true // trailing line comment
158
- // A `/*` here is a newline-spanning block comment (single-line ones were consumed
159
- // above); like a bare line break it terminates the directive when a new statement follows.
116
+ else if (c === '/' && source[afterTrail + 1] === '/') isDirective = true
117
+ // A `/*` here is a newline-spanning block comment: like a line break it can end the directive.
160
118
  else if (c === '/' && source[afterTrail + 1] === '*') isDirective = newStatementAfterBreak(source, afterTrail)
161
119
  else if (c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029') isDirective = newStatementAfterBreak(source, afterTrail)
162
- else isDirective = false // same-line continuation (`.`, `+`, `,`, ...): a string expression
120
+ else isDirective = false
163
121
  if (!isDirective) break
164
- i = afterStr // past the directive; loop for stacked directives
122
+ i = afterStr
165
123
  }
166
124
  return `${source.slice(0, i)};${CJS_REQUIRE_REPAIR}${source.slice(i)}`
167
125
  }
168
126
 
169
127
  let state
170
- // The shard dir + per-build ed25519 keypair THIS process created (root only). The PRIVATE key
171
- // is exported to descendants via env (each capturing child signs its shard with it); the PUBLIC
172
- // key (createdShardPub, a KeyObject) is what the root verifies every shard's signature against,
173
- // and its base64url form (createdShardPubId) prefixes each shard's filename. Tracked so the root
174
- // merges from / removes ONLY a dir it minted, and accepts ONLY shards that carry a valid
175
- // signature under the keypair it minted -- never an inherited/attacker dir or a foreign-signed file.
128
+ // The root merges/removes ONLY a shard dir it minted and accepts ONLY shards signed under its own key.
176
129
  let createdShardDir
177
130
  let createdShardPub
178
131
  let createdShardPubId
179
- // True once the ROOT has written its artifacts at least once (save() is re-entrant across
180
- // beforeExit/exit firings and re-flushes late-observed resolution edges; see its comment).
181
- // Consulted by the load hook's fail-loud assert: a module whose BYTES first load after a
182
- // write may miss the final artifact entirely, so it must crash the capture rather than
183
- // silently ship unattested. Late resolution EDGES of already-loaded modules, by contrast,
184
- // are what the re-flush exists to pick up.
132
+ // True once artifacts are written; the load hook asserts on it so a late first load can't ship unattested.
185
133
  let saved = false
186
- // Serialized shard text a child last wrote, so the exit firing skips an identical
187
- // re-write instead of dropping a second (equal) shard file for the root to merge.
134
+ // Serialized shard text a child last wrote, so a second flush skips an identical re-write.
188
135
  let lastShardWritten
189
- // Set when stasis's own capture/verification rejects something (see the hooks around
190
- // addFile/addImport below). Distinct from "the run exited non-zero": a clean capture is
191
- // allowed to exit non-zero for its own reasons and still be persisted.
136
+ // Set when stasis's own capture/verification rejects something; when set, nothing is written.
192
137
  let aborted = false
193
- // >0 while Node's default loader (nextLoad) is reading a module's source -- which for
194
- // CommonJS goes through the public fs.readFileSync the --fs hook patches. The module is
195
- // already captured as code via addFile, so the --fs capture hook skips reads taken
196
- // while this is set: it records the program's OWN fs reads, not Node's module loading.
138
+ // >0 while Node's loader reads a module's source; the --fs hook skips reads taken then.
197
139
  let loadingModule = 0
198
- // True until the first non-builtin load hook fires. Replaces the legacy
199
- // `!state` heuristic for entry detection, which broke once initState could
200
- // be triggered eagerly by plugins.js via ensureStateForLoader (state set
201
- // before the entry's load).
140
+ // True until the first non-builtin load hook fires (entry detection).
202
141
  let entryUnseen = true
203
142
 
204
- // Child-process handling, WITHOUT intercepting child_process or adding a flag.
205
- // EXODUS_STASIS_PID records the ROOT stasis process's pid -- the first stasis process in the
206
- // tree (the one the CLI launches, or a direct `node --import`). It is unset there, so the
207
- // root claims the slot with its own pid and is allowed to write. A process that ends up
208
- // running this loader as a child -- child_process.fork() inherits our `--import` via
209
- // process.execArgv automatically; a manual `spawn(node, ['--import', <loader>, ...])` does so
210
- // explicitly -- inherits EXODUS_STASIS_PID through the environment but runs under a different
211
- // pid. On that mismatch we suppress the bundle/lockfile write for ANY child, fork or not --
212
- // the root owns the artifact, and a second writer to the same path would race it. We
213
- // additionally relax the entry-point check for a FORKED child specifically (mismatch AND an
214
- // IPC channel, which fork() always creates and a non-fork child lacks): its main module is a
215
- // fork target, not a declared CLI entry, whereas a `node --import` child names its own entry.
216
- // getFile() still fails closed on anything unattested. (A `stasis run` nested inside an
217
- // already-running stasis process inherits the pid and is thus treated as a child too -- it
218
- // won't write; run stasis at a single level.) Resolved once, before any user code runs.
143
+ // EXODUS_STASIS_PID = the root stasis's pid; on mismatch we're a child and must not write the
144
+ // bundle/lockfile (root owns the artifact; a 2nd writer races). A forked child also relaxes assertEntry.
219
145
  const OWN_PID = String(process.pid)
220
146
  if (!process.env.EXODUS_STASIS_PID) process.env.EXODUS_STASIS_PID = OWN_PID
221
147
  const isChildProcess = process.env.EXODUS_STASIS_PID !== OWN_PID
222
148
  const forkedChild = isChildProcess && process.channel !== undefined
223
149
 
224
- // Resolve once at module-load: stasis-core's own package root. Passed to State
225
- // as `preloadRoot` so state.write()'s backfill statically captures stasis-core's
226
- // internal edges -- the (state.js -> config.js)-shape relative imports that
227
- // were loaded by Node BEFORE install() registered our hooks and that the live
228
- // resolve hook therefore never observed.
229
- //
230
- // `findPackageJSON` is wrapped because bundlers that ship this file as part
231
- // of a captured bundle don't always have it mocked / wired up -- e.g. a
232
- // metro-built bundle replaces node:module with its own shim where the API
233
- // is absent. Returning undefined on failure makes the State constructor's
234
- // `if (preloadRoot !== undefined)` skip cleanly; the backfill that consumes
235
- // preloadRoot is a best-effort feature and falls through gracefully when
236
- // it's unset.
150
+ // stasis-core's own package root, so State's backfill captures edges loaded before our hooks registered.
237
151
  const PRELOAD_ROOT = (() => {
238
152
  try {
239
153
  return dirname(findPackageJSON(import.meta.url))
@@ -242,44 +156,9 @@ const PRELOAD_ROOT = (() => {
242
156
  }
243
157
  })()
244
158
 
245
- // --- Child-process capture forwarding (shards) --------------------------------------
246
- // A forked child (e.g. a Metro transform worker) runs this loader and captures into its OWN
247
- // State -- including files ONLY it loads, like babel.config.js and the babel preset/plugins
248
- // the transformer requires per file. But a child must never write the real lockfile/bundle
249
- // (the root owns it; two writers race -- see save()). So each capturing child instead writes
250
- // a per-pid SHARD -- its shardSnapshot(), a lockfile-shaped record of what it captured -- into
251
- // a shared dir the ROOT creates and exports as EXODUS_STASIS_SHARD_DIR (inherited through the
252
- // env by every descendant). Just before the root writes, it merges every shard back into its
253
- // State (re-reading each file's bytes from disk), so observations only a child made are still
254
- // attested. Best-effort throughout: a missing/partial shard (a child killed mid-write) or an
255
- // unreadable dir is skipped, never fatal -- the root's own capture is unaffected.
256
- //
257
- // OPT-IN: gated behind --child-process (config.childProcess). The shard dir is a
258
- // process-coordination channel, not part of normal capture, so it exists only when a user
259
- // explicitly enables cross-process capture (e.g. for Metro). A default run never creates it.
260
- //
261
- // TRUST (defense in depth against shard-channel injection):
262
- // - the channel only exists under the --child-process opt-in;
263
- // - the dir is minted in the OS tmpdir via mkdtemp, which creates it mode 0700 (owner-only), so
264
- // a different-uid process can't read its contents; trust does NOT rest on the dir being secret
265
- // (its path travels to children in env) -- it rests on the signature gate below;
266
- // - the root ALWAYS mints its own dir + a per-build ed25519 keypair, overwriting any
267
- // inherited/attacker-set EXODUS_STASIS_SHARD_DIR/_KEY, and merges from / removes ONLY
268
- // that dir. Only the PRIVATE key reaches descendants (via env); each child SIGNS its shard
269
- // with it, and the root verifies every shard against its own PUBLIC key, accepting only a
270
- // valid signature. The filename carries the public key (non-secret) purely to pre-filter;
271
- // trust comes from the signature, NOT the filename -- a file signed by some other keypair,
272
- // or unsigned, is rejected even if it's named with the right public-key prefix;
273
- // - shards carry NO bytes -- mergeShard re-reads each file from disk and re-hashes -- so a shard
274
- // can never inject forged file CONTENT (bytes); it can only over-attest a file already on disk.
275
- // Because the dir holds only public-keyed, signed shards, a peer who can read the (owner-only)
276
- // dir but NOT this process's env cannot forge one. The residual is broader than a /proc snooper:
277
- // the private key rides in the environment, so ANY code the build itself executes -- a postinstall
278
- // script, codegen, a transitive dependency -- inherits it and can mint a valid shard. And a valid
279
- // shard does more than over-attest bytes: mergeShard replays its resolution edges via addImport
280
- // WITHOUT re-deriving them on disk, so a key-holder can also forge resolution edges (and formats).
281
- // All of that is within the build's own trust domain -- that code already runs with the build's
282
- // privileges -- which is the line this opt-in deliberately draws.
159
+ // Child-process capture forwarding (shards), opt-in via --child-process: a capturing child writes a
160
+ // signed per-pid shard the root verifies against its own public key before merging. Trust rests on
161
+ // that signature, not the dir being secret; shards carry NO bytes (the root re-reads from disk).
283
162
 
284
163
  function shardForwardingEnabled() {
285
164
  return Boolean(state) && state.config.childProcess && (state.config.writeLockfile || state.config.writeBundle)
@@ -291,48 +170,29 @@ function writeChildShard() {
291
170
  const keyB64 = process.env.EXODUS_STASIS_SHARD_KEY
292
171
  if (!dir || !keyB64) return
293
172
  try {
294
- // Sign the snapshot with the env-passed private key so the root can authenticate it. We sign
295
- // the snapshot's exact bytes and store them verbatim next to the signature in an envelope
296
- // ({ shard, signature }) -- signing the string directly, rather than mutating + re-stringifying
297
- // the parsed object, makes verification independent of JSON key ordering and robust against a
298
- // future top-level `signature` lockfile key. The PUBLIC key (base64url) names the file --
299
- // <base64url(public)>-<pid>-<rand>.json: the public prefix lets the root cheaply pre-filter to
300
- // its own build; the pid + random suffix keep workers from colliding even if the OS recycles an
301
- // exited worker's pid within one build. Write to a dot-prefixed temp then rename: the merge
302
- // filter ignores the temp, so the root never reads a half-written shard.
303
- const shard = state.shardSnapshot() // serialized lockfile string
304
- // save() re-fires on exit after the beforeExit flush (late-observed resolution edges;
305
- // see save's comment). An unchanged snapshot means nothing new to forward -- skip the
306
- // duplicate shard file rather than make the root merge the same content twice.
173
+ // Sign the exact snapshot string, never a re-stringify, so verify is independent of JSON key
174
+ // order; temp + rename so the merge never reads a half-written shard.
175
+ const shard = state.shardSnapshot()
307
176
  if (shard === lastShardWritten) return
308
177
  const privateKey = createPrivateKey({ key: Buffer.from(keyB64, 'base64'), format: 'der', type: 'pkcs8' })
309
178
  const pubId = createPublicKey(privateKey).export({ format: 'jwk' }).x
310
179
  const signature = sign(null, Buffer.from(shard), privateKey).toString('base64url')
311
- const unique = `${OWN_PID}-${randomBytes(6).toString('hex')}` // pid + random: no collision even on pid reuse
180
+ const unique = `${OWN_PID}-${randomBytes(6).toString('hex')}`
312
181
  const tmpPath = join(dir, `.${pubId}-${unique}.tmp`)
313
182
  writeFileSync(tmpPath, JSON.stringify({ shard, signature }))
314
183
  renameSync(tmpPath, join(dir, `${pubId}-${unique}.json`))
315
184
  lastShardWritten = shard
316
185
  } catch {
317
- // A child that can't snapshot/sign/write just doesn't contribute; the root still persists
318
- // its own capture, and a later frozen run fails closed on anything genuinely missing.
186
+ // Best-effort: a child that can't snapshot/sign/write just doesn't contribute.
319
187
  }
320
188
  }
321
189
 
322
- // Defense-in-depth bounds on a merge: cap the count + per-shard size so a hostile/runaway set
323
- // of shards can't OOM the root. Generous -- a real toolchain shard is a small lockfile.
190
+ // Cap shard count + size so a hostile/runaway set can't OOM the root.
324
191
  const MAX_SHARDS = 4096
325
192
  const MAX_SHARD_BYTES = 64 * 1024 * 1024
326
193
 
327
- // Merge the shards THIS root's children wrote into `dir` (the dir we created). We pre-filter to
328
- // filenames carrying our public key, then AUTHENTICATE each: the file is an { shard, signature }
329
- // envelope; verify the shard's exact bytes against our own PUBLIC key (createdShardPub -- never a
330
- // key derived from the filename) and merge only those verified bytes. So a file that's unsigned,
331
- // foreign-signed, or tampered after signing (e.g. dropped by a non-descendant that doesn't hold
332
- // the private key) is ignored even if it's named with our prefix. The caller (save) removes `dir`
333
- // afterward in a finally, so a partial read here never leaves it behind. We iterate with opendir
334
- // (not readdirSync) so the listing is streamed, never materialized -- MEMORY stays bounded even for
335
- // a dir stuffed with entries -- and stop parsing/verifying after MAX_SHARDS matching shards.
194
+ // Merge children's shards from `dir`: verify each envelope against our own PUBLIC key, not one from
195
+ // the filename. opendir streams the listing so memory stays bounded.
336
196
  function mergeChildShards(dir) {
337
197
  let handle
338
198
  try { handle = opendirSync(dir) } catch { return }
@@ -346,13 +206,13 @@ function mergeChildShards(dir) {
346
206
  if (++count > MAX_SHARDS) break
347
207
  const path = join(dir, name)
348
208
  try {
349
- if (statSync(path).size > MAX_SHARD_BYTES) continue // skip an over-large shard
209
+ if (statSync(path).size > MAX_SHARD_BYTES) continue
350
210
  const { shard, signature } = JSON.parse(readFileSync(path, 'utf-8'))
351
- if (typeof shard !== 'string' || typeof signature !== 'string') continue // unsigned/malformed: reject
211
+ if (typeof shard !== 'string' || typeof signature !== 'string') continue
352
212
  if (!verify(null, Buffer.from(shard), createdShardPub, Buffer.from(signature, 'base64url'))) continue
353
- state.mergeShard(shard) // the exact bytes we just verified
213
+ state.mergeShard(shard)
354
214
  } catch {
355
- // A malformed/partial shard (a child SIGKILLed mid-write) is skipped; the rest merge.
215
+ // A malformed/partial shard is skipped; the rest merge.
356
216
  }
357
217
  }
358
218
  } finally {
@@ -360,32 +220,16 @@ function mergeChildShards(dir) {
360
220
  }
361
221
  }
362
222
 
363
- // `--fs` (EXODUS_STASIS_FS = 'sync' | 'async', or "fs" in stasis.config.json): monkey-patch the
364
- // fs readers -- readFileSync/readdirSync + lstatSync/statSync and the existence/realpath probes,
365
- // and under 'async' their async (callback + fs.promises) counterparts -- to capture them into the
366
- // bundle (bundle=add|replace) or serve them from it (bundle=load). Driven off the resolved Config
367
- // (state.config.fs) rather than the raw env var, so the mode can also come from stasis.config.json
368
- // -- which isn't read until State is constructed. Called from initState (which fires on the first
369
- // load/resolve hook, before any user code runs), AFTER the lib's own fs snapshots (fs.js /
370
- // state.js / state-util.js, all taken at module-eval) and after registerHooks -- so the patch
371
- // never redirects stasis's own reads, and only when the user opted in. `state` is read lazily
372
- // (per call); installFsHooks is internally idempotent. A capture-side conflict (a file read twice
373
- // with diverging bytes) taints the run the same way an addFile/addImport rejection does, so
374
- // nothing inconsistent is written.
223
+ // Install the --fs reader patches. Must run AFTER stasis's own fs snapshots so they never redirect
224
+ // stasis's own reads.
375
225
  function installFsHooksFromConfig() {
376
226
  const fsMode = state.config.fs
377
227
  if (!fsMode) return
378
228
  installFsHooks({
379
- // 'async' adds the async readers; 'sync' (the only other valid value) is sync-only.
380
229
  async: fsMode === 'async',
381
230
  getState: () => state,
382
- // True while Node's default loader is reading a module's source: the --fs hook
383
- // skips those so it captures the program's explicit reads, not module loading.
384
231
  isLoadingModule: () => loadingModule > 0,
385
- // A genuine capture conflict (a file read twice mid-run with diverging bytes)
386
- // taints the run like an addFile/addImport rejection -- nothing is written.
387
- // Warn on the first taint so the discard isn't silent (the user's reads still
388
- // succeed, so the run otherwise exits 0 with no bundle/lockfile and no clue).
232
+ // Warn on the first taint so the silent discard (reads succeed, exit 0, no artifact) has a clue.
389
233
  markAborted: (err) => {
390
234
  if (!aborted) console.warn(`[stasis] --fs: capture aborted, no bundle/lockfile will be written -- ${err?.message ?? err}`)
391
235
  aborted = true
@@ -396,27 +240,10 @@ function installFsHooksFromConfig() {
396
240
  function initState(root) {
397
241
  state = new State(root, { preload: true, preloadRoot: PRELOAD_ROOT })
398
242
 
399
- // Install the --fs reader patches now that Config is resolved (it carries the fs mode,
400
- // possibly from stasis.config.json). Before any child can fork and before user code runs.
401
243
  installFsHooksFromConfig()
402
244
 
403
- // Root + opt-in: create the shard dir forked children report into, BEFORE any child can fork
404
- // (initState fires on the first load, ahead of user code spawning workers). Mint it in the OS
405
- // tmpdir via mkdtemp (mode 0700, owner-only) -- NOT under the project/write-target tree, where a
406
- // dir would pollute an `--fs` readdir of the root and, on a SIGKILL that skips our exit cleanup,
407
- // litter the repo (a later `--fs` run could even re-capture it). tmpdir keeps the scaffolding out
408
- // of the captured tree and lets the OS reap it if we're hard-killed. The location is not a secret
409
- // (its path travels to children in env); forgery is stopped by the signature, and the 0700 mode
410
- // keeps a different-uid peer from reading the dir's contents. ALWAYS mint our own dir + per-build
411
- // ed25519 keypair, overwriting any inherited/attacker-set EXODUS_STASIS_SHARD_DIR/_KEY, so the
412
- // root only ever merges from -- and rm's -- a dir it created, and only shards it can
413
- // authenticate. The PRIVATE key is exported so descendants inherit it and sign their shards; the
414
- // root keeps the PUBLIC key to verify. The dir is removed on every exit path (see `save`). Only
415
- // the root mints (children are isChildProcess); a non-opt-in or non-capturing run creates
416
- // nothing, so children no-op. NB: the dir lives under os.tmpdir(), so capture integrity assumes a
417
- // trustworthy TMPDIR -- a TMPDIR an attacker controls (or a non-sticky shared one) reopens the
418
- // classic tmpdir symlink race; that is outside the threat model (we defend a dir READER, not a
419
- // TMPDIR controller), and /tmp's sticky bit defeats it in the normal case.
245
+ // Root + opt-in only, before any child can fork: ALWAYS mint our own dir (OS tmpdir, mkdtemp 0700)
246
+ // and keypair, overwriting any inherited/attacker-set env, so we merge only shards we can verify.
420
247
  if (!isChildProcess && shardForwardingEnabled()) {
421
248
  try {
422
249
  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
@@ -424,18 +251,11 @@ function initState(root) {
424
251
  createdShardPub = publicKey
425
252
  createdShardPubId = publicKey.export({ format: 'jwk' }).x // base64url(raw public key)
426
253
  process.env.EXODUS_STASIS_SHARD_DIR = createdShardDir
427
- // Only the private key travels to children: the dir then holds only public-keyed, signed
428
- // shards, so reading the dir (without this env) is not enough to forge one. These two vars
429
- // ride process.env, so EVERY transitive descendant inherits them -- a child that itself
430
- // forks/spawns a subprocess (or re-invokes a stasis bin) propagates the channel onward, and
431
- // those grandchildren contribute shards too. Do NOT scrub them anywhere downstream: that would
432
- // sever capture for whole subtrees the build legitimately spawns.
254
+ // Rides process.env so every transitive descendant inherits; do NOT scrub it downstream.
433
255
  process.env.EXODUS_STASIS_SHARD_KEY = privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64')
434
256
  } catch {
435
- // Shard reporting is a best-effort enhancement; capture still works without it. If we threw
436
- // BEFORE overwriting the env, an inherited (possibly attacker-set) dir/key is still in it --
437
- // clear both so descendants don't fall back to a channel we never minted or validated. If
438
- // mkdtemp already created the dir before a later step threw, remove the (empty) dir too.
257
+ // Best-effort: clear any inherited (possibly attacker-set) dir/key so descendants don't fall
258
+ // back to a channel we never minted.
439
259
  if (createdShardDir) { try { rmSync(createdShardDir, { recursive: true, force: true }) } catch { /* best-effort */ } }
440
260
  createdShardDir = undefined
441
261
  createdShardPub = undefined
@@ -444,132 +264,44 @@ function initState(root) {
444
264
  delete process.env.EXODUS_STASIS_SHARD_KEY
445
265
  }
446
266
  } else if (!isChildProcess) {
447
- // Non-capturing root (--lock=frozen, or --child-process off): we never mint or merge a shard
448
- // dir, so shed any inherited (possibly attacker-set) EXODUS_STASIS_SHARD_DIR/_KEY rather than
449
- // leave them in our env. A non-capturing root's descendants can't capture either (they inherit
450
- // our non-writing config), so this severs no legitimate channel -- it just drops dead weight.
267
+ // Non-capturing root: shed any inherited (possibly attacker-set) shard env.
451
268
  delete process.env.EXODUS_STASIS_SHARD_DIR
452
269
  delete process.env.EXODUS_STASIS_SHARD_KEY
453
270
  }
454
271
 
455
- // Persist the lockfile/bundle on exit UNLESS a stasis verification rejected something.
456
- // We deliberately do NOT gate on the exit code: a clean capture that exits non-zero for
457
- // its own reasons -- a server running its own SIGINT shutdown and exiting 130, or any
458
- // script that returns non-zero -- must still persist what it captured. The hazard we
459
- // guard is narrower: addFile records a file's hash (which lock=add/replace then
460
- // serializes) *before* a later check -- the frozen bundle's byte/format/resolution
461
- // check, or a lock=add conflict against an existing lockfile -- can reject it. Writing
462
- // that would bake the rejected drift into the lockfile/bundle, so a subsequent
463
- // lock=frozen run would accept it. So we skip the write only when `aborted` is set, which
464
- // the hooks set whenever addFile/addImport throws -- catching a stasis rejection even if
465
- // user code swallows it (try/catch around a dynamic import) and exits 0.
466
- //
467
- // An abort that does NOT originate in addFile/addImport -- an uncaught module-not-found
468
- // (thrown by Node's resolver), or a user error after a partial-but-clean capture -- does
469
- // not taint, so the files captured so far ARE still written. That is intentional and
470
- // safe: those recorded hashes are accurate (nothing drifted is baked in), and a later
471
- // lock=frozen run fails closed on anything missing. Unhandled signals (SIGINT/SIGTERM
472
- // with no handler) bypass exit hooks entirely; servers own that behavior, we don't touch
473
- // it -- except for a capturing CHILD under the EXODUS_STASIS_SHARD_SIGNAL_FLUSH opt-in
474
- // (StasisMetro sets it for its force-killed transform workers), which flushes its shard
475
- // on SIGTERM and re-delivers the signal -- see the handler registered below.
476
- //
477
- // save() runs on EVERY beforeExit/exit firing rather than latching after the first.
478
- // These handlers were registered at initState -- before any user code ran -- so they fire
479
- // FIRST on each event, and a require() issued by a LATER handler on the same event
480
- // resolves AFTER our write. CLIs commonly log a summary at exit through a lazy require
481
- // (Babel lazy interop: @react-native-community/cli-tools' logger require()s chalk on
482
- // its first call): the target's bytes are usually attested via other importers, so a
483
- // one-shot save silently dropped only that resolution EDGE, surfacing at bundle=load
484
- // as MODULE_NOT_FOUND for a package the bundle carries. Re-running is cheap -- write()
485
- // compares each artifact's serialized text and skips unchanged outputs, and the child
486
- // shard path keeps its own last-written compare -- so the exit firing re-flushes
487
- // whatever the beforeExit firing missed. Requires issued by a user 'exit' handler
488
- // AFTER ours are the residual gap: 'exit' is the last stop, nothing later can flush.
272
+ // Persist on exit unless `aborted` -- deliberately NOT gated on exit code, so a clean capture
273
+ // exiting non-zero still persists. Must stay fully synchronous for `exit` to host it.
489
274
  const save = () => {
490
- // A child process (pid mismatch) must never write the real artifact -- fork OR a non-fork
491
- // child that inherited our loader: the root owns the lockfile/bundle, and a second writer
492
- // would race it. Instead it forwards what it captured via a shard the root merges below.
493
- // writeChildShard no-ops unless the channel is on AND a shard dir was inherited: a child of a
494
- // non---child-process run (no dir minted) contributes nothing, while a child under
495
- // --child-process (forked or a spawned `node --import` loader) inherits the dir+key and does.
275
+ const writing = state.config.writeLockfile || state.config.writeBundle
276
+ // A child forwards a shard instead of writing the artifact (root owns it; a 2nd writer races).
496
277
  if (isChildProcess) {
497
- // An aborted child (its own addFile/addImport rejected something) forwards nothing -- the
498
- // same fail-stance the root takes when `aborted`. The root re-reads + noupserts every shard
499
- // so a partial one couldn't taint it, but there's no value in shipping a rejected capture.
500
- if (!aborted) writeChildShard()
278
+ if (writing && !aborted) writeChildShard()
501
279
  return
502
280
  }
503
281
  try {
504
- // A stasis rejection (addFile/addImport threw -> aborted) must NOT write -- that would bake
505
- // the rejected drift into the lockfile/bundle, so a later frozen run would accept it. We
506
- // still tear down the shard dir in the finally below.
507
282
  if (aborted) return
508
- // Root: fold in every forked child's shard before writing, so files/edges only a child
509
- // observed (e.g. a Metro worker's babel.config.js + preset/plugins) are attested too. Only
510
- // when we minted a shard dir (opt-in + capturing); merges from that dir alone. On a
511
- // re-flush after the dir was already removed below, the merge no-ops (opendir fails).
512
283
  if (createdShardDir) mergeChildShards(createdShardDir)
284
+ // write() self-gates the artifact writes, but also VERIFIES in read-only frozen modes, so it
285
+ // must run in every mode.
513
286
  state.write()
514
- saved = true
287
+ // Latch only in write modes: a read-only run persists nothing, so a later first load (e.g. a
288
+ // require() from another exit handler) is still attested and must not trip the load hook.
289
+ if (writing) saved = true
515
290
  } finally {
516
- // Always remove the shard dir we minted -- clean exit, abort, or a throwing write. This is
517
- // the single owner of that cleanup (mergeChildShards no longer self-removes). A SIGKILL
518
- // bypasses exit hooks, but the dir is in the OS tmpdir, so the OS reaps it.
519
291
  if (createdShardDir) {
520
292
  try { rmSync(createdShardDir, { recursive: true, force: true }) } catch { /* best-effort */ }
521
293
  }
522
294
  }
523
295
  }
524
296
 
525
- process.on('beforeExit', save)
297
+ // `exit` alone, NOT the beforeExit/exit pair: it runs after every beforeExit handler, so one flush
298
+ // there sees strictly more. A process that never reaches `exit` writes nothing.
526
299
  process.on('exit', save)
527
300
 
528
- // config.shardSignalFlush (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, opt-in; StasisMetro's
529
- // capture wiring sets it for its build's children -- see the plugin's constructor):
530
- // flush the shard when a capturing child is ended BY SIGNAL. Metro's transform workers
531
- // are routinely killed that way: jest-worker's end() sends its END message, gives the
532
- // worker 500ms to drain its event loop, then forceExit()s it -- SIGTERM, and SIGKILL
533
- // another 500ms later -- and a worker whose loop doesn't drain in time (a watcher or
534
- // ref'd timer some transformer left behind) dies by SIGTERM, which bypasses
535
- // beforeExit/exit entirely. Everything ONLY that worker observed (its fork-target
536
- // entry, jest-worker's processChild.js; babel.config.js + the preset/plugin graph
537
- // loaded per transform) then silently vanished from the capture, surfacing only later
538
- // at bundle=load as "file not attested in bundle" when the forked child's loader can't
539
- // be served its own entry. The handler runs the same save() the exit hooks run (for a
540
- // child: forward the shard unless the capture aborted) and re-delivers the signal;
541
- // semantics are preserved:
542
- // - the `once` listener is already removed when the handler runs, so when no user
543
- // listener remains the OS default disposition is restored and the re-kill terminates
544
- // the process BY that signal (the parent still observes code=null, signal=SIGTERM);
545
- // the finally makes that re-delivery unconditional even if a future save() edit
546
- // grows a throw path (today it cannot throw on the child branch);
547
- // - when user code owns process lifetime we only flush and do NOT re-kill. "User code"
548
- // is detected two ways, because a `once` listener that ran EARLIER in this same emit
549
- // has already removed itself and is invisible to a post-emit listenerCount: listeners
550
- // present at REGISTRATION time (a --require preload's graceful-shutdown hook -- those
551
- // always precede this initState-time registration) are remembered in
552
- // `userOwnedSigterm`, and listeners added later are still attached when the handler
553
- // runs. A user handler that exits normally re-flushes via the exit hooks
554
- // (lastShardWritten dedups); if a SECOND signal kills it instead, capture accrued
555
- // after this one-shot flush is lost -- an accepted residual, fail-closed at verify.
556
- // The conservative direction is deliberate: when in doubt, don't re-kill -- the
557
- // worst case is jest-worker's own SIGKILL landing 500ms later;
558
- // - signal listeners don't ref the event loop, so a cleanly-draining worker still
559
- // exits (and writes) exactly as before.
560
- // NOT a global default: a signal listener changes a process's default-kill disposition,
561
- // which in arbitrary user children is the user's domain -- the Metro plugin opts in its
562
- // KNOWN tool workers, where flush-then-redeliver is the right trade. Gated additionally
563
- // to a CHILD (the root's signal behavior stays untouched -- servers own it) with shard
564
- // forwarding on; a channel that was never minted (root mint failure cleared DIR+KEY) just
565
- // makes the flush a no-op via writeChildShard's own guard. SIGTERM only -- it's what
566
- // jest-worker's forceExit sends (Metro doesn't override killSignal). Best-effort
567
- // residuals, all fail-closed at a later frozen/load run: the flush must fit inside
568
- // forceExit's 500ms SIGTERM->SIGKILL window; SIGKILL and any OTHER signal (group
569
- // SIGINT/SIGHUP, a killSignal override) are not covered; and a capturing child that
570
- // is itself the process EVALUATING metro.config.js (a nested orchestration) snapshots
571
- // its Config before the plugin sets the flag, so only its DESCENDANTS are covered --
572
- // see the plugin's KNOWN LIMITATIONS bullet.
301
+ // config.shardSignalFlush (opt-in): flush the shard when a capturing CHILD is ended by SIGTERM
302
+ // (jest-worker's forceExit bypasses `exit`), then re-deliver the signal -- unless user code owns
303
+ // SIGTERM, then only flush. `userOwnedSigterm` is snapshotted at registration: a `once` that
304
+ // already ran is invisible to listenerCount. Must fit forceExit's 500ms window.
573
305
  if (isChildProcess && shardForwardingEnabled() && state.config.shardSignalFlush) {
574
306
  const userOwnedSigterm = process.listenerCount('SIGTERM') > 0
575
307
  process.once('SIGTERM', () => {
@@ -594,54 +326,23 @@ function load(url, context, nextLoad) {
594
326
  }
595
327
 
596
328
  if (state && state.config.loadBundle) {
597
- // node_modules scope only bundles node_modules deps; everything else -- app/workspace
598
- // sources, including a workspace package symlinked into node_modules (its real path is
599
- // not under node_modules, so inNodeModules() is false) -- is read from disk via Node's
600
- // default loader. Gate on the canonical classification, not a raw '/node_modules/'
601
- // substring: otherwise such a symlink URL would be routed to state.getFile and crash,
602
- // since the file is a source deliberately omitted from the node_modules-scope bundle.
329
+ // node_modules scope serves only nm deps; gate on inNodeModules(), not a raw substring (symlinks).
603
330
  if (!state.config.full && !state.inNodeModules(url)) {
604
331
  return nextLoad(url, context)
605
332
  }
606
333
  const { source, format } = state.getFile(url)
607
- // context.format may be null when the resolve chain didn't set it (e.g. node_modules
608
- // scope, where non-nm parents go through nextResolve and Node's default doesn't
609
- // populate format for the load hook). Only cross-check when the chain provided one.
610
- // The `formats` map this value comes from is attested against the lockfile at State
611
- // construction (#mergeBundleMetadata) when a lockfile is loaded -- so a tampered
612
- // bundle can't flip module<->commonjs (or a .js file to module-typescript, which
613
- // would make Node strip type-argument-shaped syntax like `f<string>('x')`) for a
614
- // hash-valid file. Without a lockfile the bundle is self-authoritative for formats
615
- // just as it is for bytes (see getFile's hash carve-out).
334
+ // Cross-check format only when the resolve chain set it; the formats map is itself attested
335
+ // against the lockfile at construction.
616
336
  if (context.format != null) assert.equal(format, context.format)
617
- // Trust gate: the loader will only serve a file whose attested format Node
618
- // can actually execute. Resource assets (`resource`, `resource:base64`),
619
- // source-language bundles (solidity/php/bash/rust), and any unknown string
620
- // a tampered or forward-incompatible bundle might smuggle through all fail
621
- // closed here with a contextual message -- never as an opaque assertion.
622
- // *-typescript formats are in the allowlist: Node's own translators strip
623
- // the types after this hook returns.
337
+ // Trust gate: only serve a file whose attested format Node can execute; everything else fails closed.
624
338
  if (!NODEJS_FORMATS.has(format)) refuseNonNodeFormat(format, url)
625
- // node:59666 workaround. When a load hook supplies `source` for a CommonJS
626
- // module, Node's ESM->CJS translator (loadCJSModule) hands the module a
627
- // *re-invented* require() that sets only `.resolve`/`.main` and omits
628
- // `.cache` and `.extensions` -- unlike the require a disk-loaded CJS module
629
- // gets (makeRequireFunction, which sets all four). Packages that read those
630
- // (import-fresh, and anything walking require.cache / require.extensions)
631
- // then throw `Cannot read properties of undefined` or misbehave -- but only
632
- // under bundle=load, because that's the only mode that serves CJS via a
633
- // source override. Repair the two missing properties from node:module
634
- // before user code runs. Confined to executable CJS formats; ESM has no
635
- // require and resources are not executed.
339
+ // node:59666: a load-hook-supplied CJS source gets a re-invented require() missing .cache/.extensions.
636
340
  if (CJS_FORMATS.has(format)) {
637
341
  return { source: repairCjsRequire(source), format, shortCircuit: true }
638
342
  }
639
343
  return { source, format, shortCircuit: true }
640
344
  }
641
345
 
642
- // nextLoad runs Node's default loader, which reads a CJS module's source through
643
- // the public fs.readFileSync the --fs hook patches. Mark the window so that hook
644
- // doesn't re-capture the module as a filesystem read (it's recorded as code below).
645
346
  loadingModule++
646
347
  let result
647
348
  try {
@@ -656,13 +357,6 @@ function load(url, context, nextLoad) {
656
357
  // Node's CJS loader may return source=null and read from disk itself; capture it for the bundle
657
358
  if (source == null && format === 'commonjs') source = readFileSync(fileURLToPath(url))
658
359
 
659
- // Entry detection: the FIRST non-builtin load through this hook is the
660
- // entry. `entryUnseen` (set true on every state init) flips to false after
661
- // the first load fires here. The pre-existing heuristic was `!state` --
662
- // tight while initState was lazy, but a plugin-driven `ensureStateForLoader`
663
- // path now eager-inits from cwd before the first load, so `!state` would
664
- // miss the entry. The flag lives module-local rather than on State because
665
- // it's strictly a hook-firing-order signal.
666
360
  const isEntry = entryUnseen
667
361
  entryUnseen = false
668
362
  if (!state) {
@@ -672,10 +366,7 @@ function load(url, context, nextLoad) {
672
366
  }
673
367
 
674
368
  assert.equal(saved, false)
675
- // A throw from addFile -- a frozen byte/format mismatch, an unattested file, a lock=add
676
- // conflict against an existing lockfile, ... -- means stasis rejected this capture. Flag
677
- // it so save() persists nothing, even if user code swallows the rejection (a try/catch
678
- // around a dynamic import) and the process then exits cleanly.
369
+ // A rejected capture must never be written, even if user code swallows the throw.
679
370
  try {
680
371
  state.addFile(url, { source, format, isEntry })
681
372
  } catch (err) {
@@ -694,53 +385,37 @@ function resolve(specifier, context, nextResolve) {
694
385
  }
695
386
 
696
387
  if (context.importAttributes !== undefined) {
697
- const expectedAttrs = Object.create(null) // Saving is not supported yet, so we ensure expected ones
388
+ const expectedAttrs = Object.create(null) // saving not supported yet; enforce expected attrs
698
389
  if (extname(specifier) === '.json' && context.importAttributes?.type) expectedAttrs.type = 'json'
699
390
  assert.deepStrictEqual(context.importAttributes, expectedAttrs)
700
391
  }
701
392
 
702
393
  const { parentURL, conditions, importAttributes } = context
703
394
 
704
- // In full-scope load mode, the entry point is served from the bundle without touching
705
- // disk, so state must be initialised before nextResolve runs. node_modules scope reads
706
- // non-nm sources (including the entry) from disk, so state is initialised later in load().
395
+ // Full-scope load serves the entry from the bundle, so state must exist before nextResolve.
707
396
  if (!state && !parentURL && process.env.EXODUS_STASIS_BUNDLE === 'load'
708
397
  && process.env.EXODUS_STASIS_SCOPE !== 'node_modules') {
709
398
  initState(process.cwd())
710
399
  }
711
400
 
712
401
  if (state && state.config.loadBundle) {
713
- // node_modules scope defers resolution of non-nm parents to Node. Relative imports
714
- // between non-nm sources then resolve to local files, and bare specifiers resolve via
715
- // the on-disk node_modules layout -- but the load() hook still serves the resulting
716
- // node_modules target from the bundle, so package contents need not be on disk. A
717
- // workspace source linked into node_modules is a non-nm parent (its canonical path is
718
- // outside node_modules), so it too is deferred -- hence inNodeModules() rather than a
719
- // raw '/node_modules/' substring on parentURL.
402
+ // nm scope defers non-nm parents to Node's resolver; gate on inNodeModules() to cover symlinks.
720
403
  if (!state.config.full && !(parentURL && state.inNodeModules(parentURL))) {
721
404
  return nextResolve(specifier)
722
405
  }
723
- // Bare specifier with a parent is the regular ESM import: look up the recorded
724
- // import map. Otherwise we have either a pre-resolved file URL (CLI entries and
725
- // ESM-to-CJS translator require() targets both arrive that way) or a bare entry
726
- // specifier we anchor to cwd -- either way, skip nextResolve so the entry file
727
- // doesn't need to exist on disk.
406
+ // A bare specifier with a parent resolves from the recorded import map; otherwise skip
407
+ // nextResolve so the entry needn't be on disk.
728
408
  if (parentURL && !specifier.startsWith('file:')) {
729
409
  const { url, format } = state.getImport(parentURL, specifier, { conditions, importAttributes })
730
- // Refuse a non-executable target at resolve time too. Catches the same
731
- // tampered/asset cases load() catches, just earlier and with the parent
732
- // module's URL in the stack trace for easier diagnosis. The load gate
733
- // remains the load-bearing one (a sibling resolver could deliver a target
734
- // that bypasses this branch); we throw here as a friendlier failure point.
410
+ // Friendlier error at resolve time; the load gate is the load-bearing one.
735
411
  if (format != null && !NODEJS_FORMATS.has(format)) refuseNonNodeFormat(format, url)
736
412
  return { url, format, importAttributes: undefined, shortCircuit: true }
737
413
  }
738
414
  const url = specifier.startsWith('file:')
739
415
  ? specifier
740
416
  : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
741
- // A forked child's main module is whatever the parent passed to fork(), not a declared
742
- // CLI entry, so it need not be in the bundle's entries list -- getFile() below still
743
- // rejects anything the bundle doesn't attest. The root run stays strict.
417
+ // A forked child's main module isn't a declared CLI entry, so skip assertEntry (getFile still
418
+ // fails closed on anything unattested).
744
419
  if (!parentURL && state.config.full && !forkedChild) state.assertEntry(url)
745
420
  const format = state.getFormat(url)
746
421
  if (format != null && !NODEJS_FORMATS.has(format)) refuseNonNodeFormat(format, url)
@@ -752,8 +427,6 @@ function resolve(specifier, context, nextResolve) {
752
427
 
753
428
  assert.equal(res.importAttributes, undefined) // unsupported yet
754
429
  if (parentURL) assert.ok(state)
755
- // As in load(): a rejected resolution (frozen redirect mismatch, conflict, ...) must keep
756
- // the captured state from being written, swallowed or not.
757
430
  if (state) {
758
431
  try {
759
432
  state.addImport(parentURL, specifier, url, { conditions, format, importAttributes })
@@ -767,57 +440,28 @@ function resolve(specifier, context, nextResolve) {
767
440
 
768
441
  let installed = false
769
442
 
770
- // True iff install() has run. Exported so plugins.js can detect "we're
771
- // running under the stasis loader" even before the lazy initState fires --
772
- // a bundler plugin constructed during webpack's config-parse can run
773
- // AHEAD of the first user-file load hook, leaving State.preload null.
774
- // resolvePluginState reads this to force-init State from cwd in that
775
- // window so the plugin inherits the loader's config rather than erroring
776
- // on the default lock mode.
443
+ // Exported so plugins.js can detect "under the stasis loader" before the lazy initState fires.
777
444
  export function isLoaderInstalled() {
778
445
  return installed
779
446
  }
780
447
 
781
- // Force-initialize state from process.cwd() if it hasn't been initialized
782
- // yet. Used by plugins.js's resolvePluginState to ensure State.preload is
783
- // available when the plugin constructor runs ahead of the load hook. A
784
- // subsequent first-load through the load hook detects "state already set"
785
- // and skips its own lazy initState, but still marks isEntry correctly via
786
- // the entryUnseen flag.
448
+ // For plugins.js when a plugin constructor runs ahead of the load hook.
787
449
  export function ensureStateForLoader() {
788
450
  if (state) return
789
451
  initState(process.cwd())
790
452
  }
791
453
 
792
- // Register Node's module hooks. Kept separate from the --import entry points
793
- // (loader.js here; the @exodus/stasis package's loader and --mock loader) so a
794
- // host can evaluate this lib -- snapshotting node:fs/path/etc. for stasis's own
795
- // use -- and compose extra setup (e.g. the tooling package's --mock side-effect
796
- // denials) via static import order BEFORE the hooks are registered, with no
797
- // env-var coordination. Idempotent.
454
+ // Separate from the --import entry points so a host can compose setup before the hooks register.
798
455
  export function install() {
799
456
  if (installed) return
800
457
  installed = true
801
458
  registerHooks({ load, resolve })
802
459
  patchCjsResolution()
803
- // NB: the `--fs` reader patches are NOT installed here. Their mode can come from
804
- // stasis.config.json, which isn't read until State is constructed, so installation is
805
- // deferred to initState() (see installFsHooksFromConfig) -- which still runs before any
806
- // user code. install() only registers the module hooks the fs patch composes on top of.
460
+ // The --fs reader patches are deferred to initState (their mode may come from stasis.config.json).
807
461
  }
808
462
 
809
- // registerHooks intercepts the ESM loader and Node's native CommonJS loader, but
810
- // NOT the require() the ESM->CJS translator (node:internal/modules/esm/translators)
811
- // builds when it evaluates a CJS module: that require resolves through
812
- // Module._resolveFilename against disk before any hook runs. So a CJS module we
813
- // serve from the bundle (`import chalk from 'chalk'`, chalk being CommonJS) has
814
- // its nested require()s resolved on disk -- and once node_modules is pruned or
815
- // shipped-without, `require('escape-string-regexp')` throws MODULE_NOT_FOUND
816
- // before our hooks can serve it, i.e. the bundle isn't self-contained for a CJS
817
- // dependency graph. Shim _resolveFilename in load mode to resolve such a target
818
- // from the bundle's recorded import map and return its (possibly non-existent on
819
- // disk) path; the load() hook then serves the bytes. For an edge the bundle
820
- // doesn't record, or outside load mode, fall back to Node's native resolution.
463
+ // registerHooks doesn't intercept the require() the ESM->CJS translator builds for a CJS module (it
464
+ // resolves through Module._resolveFilename against disk), so shim that to resolve from the import map.
821
465
  function patchCjsResolution() {
822
466
  const original = Module._resolveFilename
823
467
  Module._resolveFilename = function (request, parent, ...rest) {
@@ -825,38 +469,15 @@ function patchCjsResolution() {
825
469
  if (loadMode && typeof request === 'string' && !isBuiltin(request)) {
826
470
  if (typeof parent?.filename === 'string') {
827
471
  const parentURL = pathToFileURL(parent.filename).toString()
828
- // Same scope gate the resolve hook applies (see above): node_modules scope
829
- // only serves dependency parents from the bundle; workspace/app code is left
830
- // to Node's native resolution (read from disk). Without this the shim would
831
- // silently take over CJS resolution for app files too.
832
472
  if (state.config.full || state.inNodeModules(parentURL)) {
833
473
  const resolved = state.resolveBundled(parentURL, request)
834
474
  if (resolved !== undefined) return resolved
835
475
  }
836
476
  } else if (isAbsolute(request)) {
837
- // NO parent, request already an absolute path: Node's ESM<->CJS interop re-enters
838
- // the monkey-patchable CJS loader with the RESOLVED filename, no parent module, and
839
- // the registerHooks hooks SKIPPED -- translators.js evaluates an import-linked CJS
840
- // module via wrapModuleLoad(filename, undefined|null, isMain, kShouldSkipModuleHooks)
841
- // (the 'commonjs-sync' translator, reached whenever a require() pulls in an ESM graph
842
- // that imports a CJS dep; also createCJSNoSourceModuleWrap). resolveForCJSWithHooks
843
- // then bypasses the resolve hook entirely, so this shim is the ONLY interception
844
- // point. An absolute path can only arrive here from a prior successful resolution
845
- // (ours, from the bundle -- or Node's own), so when the bundle attests that exact
846
- // FILE under the same scope gate, the resolution is the identity (returned in
847
- // path.resolve()d form, matching native's normalized cache-key contract). Falling
848
- // through to native would stat a file the bundle carries but disk (pruned /
849
- // never-shipped node_modules) may not -- MODULE_NOT_FOUND on a servable path.
850
- // hasFsFileContent (byte content, not getFsStat's kind) keeps a --fs-captured
851
- // directory LISTING -- and a payload-free 'stat:*' record, whose bytes the
852
- // bundle can NOT serve -- from hijacking native disk resolution. This widens
853
- // parentless reachability to any attested in-scope file when disk lacks the path;
854
- // that is bounded by attestation and the load hook's gates (getFile +
855
- // NODEJS_FORMATS), which remain the load-bearing checks.
856
- // Node >=24.18 forwards pre-resolved context for hook-resolved modules, masking the
857
- // common case; on 24.14-24.17 (our supported floor) every commonjs-sync evaluation
858
- // re-resolves through here, and the no-parent shape survives on >=24.18 too (the
859
- // deferred-resolution branch and createCJSNoSourceModuleWrap still take it).
477
+ // NO parent, absolute request: Node's ESM<->CJS interop re-enters the CJS loader with hooks
478
+ // SKIPPED, so this shim is the only interception point. hasFsFileContent (not a dir/stat
479
+ // record) keeps a listing or payload-free stat from hijacking resolution. Node 24.14-24.17
480
+ // re-resolve here every commonjs-sync eval; the no-parent shape survives on >=24.18 too.
860
481
  const url = pathToFileURL(request).toString()
861
482
  if ((state.config.full || state.inNodeModules(url)) && state.hasFsFileContent(url)) {
862
483
  return resolvePath(request)
@@ -864,10 +485,7 @@ function patchCjsResolution() {
864
485
  }
865
486
  }
866
487
  const resolved = original.call(this, request, parent, ...rest)
867
- // Capture: require.resolve() (and, on some Node versions, CJS require()s)
868
- // resolve through native Module._resolveFilename WITHOUT firing the resolve
869
- // hook, so addImport never sees them. Observe the resolution here; write()'s
870
- // backfill records the ones the hook missed (deduped, in-bundle targets only).
488
+ // Capture: require.resolve() and some CJS require()s never fire the resolve hook.
871
489
  if (state && !loadMode && typeof request === 'string'
872
490
  && !isBuiltin(request) && typeof parent?.filename === 'string') {
873
491
  state.observeResolution(pathToFileURL(parent.filename).toString(), request, pathToFileURL(resolved).toString())
@@ -875,16 +493,8 @@ function patchCjsResolution() {
875
493
  return resolved
876
494
  }
877
495
 
878
- // Capture: Module._load's fast path (relativeResolveCache, keyed by the parent
879
- // DIRECTORY + request) returns an already-loaded module WITHOUT calling
880
- // _resolveFilename -- so a SECOND sibling importer's require() of a target the first
881
- // sibling already loaded never reaches the observe shim above, and the edge is
882
- // recorded only under the first importer (under-recording). _load runs for EVERY
883
- // require() including cache hits, so force the resolution here to observe the true
884
- // per-importer edge; _resolveFilename is itself cached, so this is cheap, and a
885
- // resolution error is left for the original _load to raise (behavior unchanged).
886
- // We call the PROPERTY `Module._resolveFilename` (our shim above), not a captured
887
- // reference, so the call routes through observeResolution.
496
+ // Capture: Module._load's cache fast path can skip _resolveFilename, so a second require() of the
497
+ // same target goes unrecorded. Force it through the PROPERTY (our shim) to observe the edge.
888
498
  const originalLoad = Module._load
889
499
  Module._load = function (request, parent, ...rest) {
890
500
  if (state && !state.config.loadBundle && typeof request === 'string'