@exodus/stasis-core 1.0.0-beta.1 → 1.0.0-beta.10

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