@exodus/stasis-core 1.0.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +9 -0
- package/bin/stasis-core.js +116 -0
- package/package.json +50 -0
- package/src/brotli.js +21 -0
- package/src/bundle.js +256 -0
- package/src/config.js +426 -0
- package/src/fs.js +712 -0
- package/src/hooks.js +826 -0
- package/src/loader.js +6 -0
- package/src/lockfile.js +152 -0
- package/src/package.cjs +1 -0
- package/src/prune.js +532 -0
- package/src/state-util.js +64 -0
- package/src/state.js +2375 -0
- package/src/util.js +210 -0
package/src/hooks.js
ADDED
|
@@ -0,0 +1,826 @@
|
|
|
1
|
+
import Module, { registerHooks, findPackageJSON, isBuiltin } from 'node:module'
|
|
2
|
+
import { basename, dirname, extname, isAbsolute, join, resolve as resolvePath } from 'node:path'
|
|
3
|
+
import * as fs from 'node:fs'
|
|
4
|
+
import { fileURLToPath, pathToFileURL } from 'node:url'
|
|
5
|
+
import { createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign, verify } from 'node:crypto'
|
|
6
|
+
import { tmpdir } from 'node:os'
|
|
7
|
+
import assert from 'node:assert/strict'
|
|
8
|
+
|
|
9
|
+
import { State } from './state.js'
|
|
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).
|
|
17
|
+
const { mkdtempSync, opendirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } = fs
|
|
18
|
+
|
|
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
|
+
const CJS_FORMATS = new Set(['commonjs', 'commonjs-typescript'])
|
|
39
|
+
|
|
40
|
+
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
|
+
)
|
|
46
|
+
}
|
|
47
|
+
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
|
+
)
|
|
52
|
+
}
|
|
53
|
+
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
|
+
)
|
|
58
|
+
}
|
|
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
|
+
)
|
|
65
|
+
}
|
|
66
|
+
|
|
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.
|
|
75
|
+
const CJS_REQUIRE_REPAIR =
|
|
76
|
+
"try{if(typeof require==='function'&&!require.cache){" +
|
|
77
|
+
"const __stasis_m=require('node:module');" +
|
|
78
|
+
'if(__stasis_m&&__stasis_m.Module){' +
|
|
79
|
+
'require.cache=__stasis_m.Module._cache;' +
|
|
80
|
+
'if(!require.extensions)require.extensions=__stasis_m.Module._extensions;}}}catch{}'
|
|
81
|
+
|
|
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
|
+
const WS_COMMENTS = /(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*/uy
|
|
87
|
+
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).
|
|
91
|
+
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`.
|
|
98
|
+
const EXPR_CONTINUATION = new Set(['.', '[', '(', '`', '+', '-', '*', '/', '%', ',', '?', ':', '=', '<', '>', '&', '|', '^'])
|
|
99
|
+
const KEYWORD_CONTINUATION = /(?:instanceof|in)\b/uy
|
|
100
|
+
function skipSticky(re, source, i) {
|
|
101
|
+
re.lastIndex = i
|
|
102
|
+
re.exec(source)
|
|
103
|
+
return re.lastIndex
|
|
104
|
+
}
|
|
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
|
+
function newStatementAfterBreak(source, pos) {
|
|
109
|
+
const afterBreak = skipSticky(WS_COMMENTS, source, pos)
|
|
110
|
+
if (afterBreak >= source.length) return true
|
|
111
|
+
if (EXPR_CONTINUATION.has(source[afterBreak])) return false
|
|
112
|
+
KEYWORD_CONTINUATION.lastIndex = afterBreak
|
|
113
|
+
return !KEYWORD_CONTINUATION.test(source)
|
|
114
|
+
}
|
|
115
|
+
|
|
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.
|
|
133
|
+
function repairCjsRequire(source) {
|
|
134
|
+
if (typeof source !== 'string') return source
|
|
135
|
+
let i = 0
|
|
136
|
+
if (source.startsWith('#!')) {
|
|
137
|
+
const nl = source.indexOf('\n')
|
|
138
|
+
i = nl === -1 ? source.length : nl + 1
|
|
139
|
+
}
|
|
140
|
+
for (;;) {
|
|
141
|
+
const afterWs = skipSticky(WS_COMMENTS, source, i)
|
|
142
|
+
STRING_LITERAL.lastIndex = afterWs
|
|
143
|
+
if (STRING_LITERAL.exec(source) === null) break // next token isn't a string: end of prologue
|
|
144
|
+
const afterStr = STRING_LITERAL.lastIndex
|
|
145
|
+
const afterTrail = skipSticky(TRAILING_SAME_LINE, source, afterStr)
|
|
146
|
+
const c = source[afterTrail]
|
|
147
|
+
let isDirective
|
|
148
|
+
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.
|
|
152
|
+
else if (c === '/' && source[afterTrail + 1] === '*') isDirective = newStatementAfterBreak(source, afterTrail)
|
|
153
|
+
else if (c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029') isDirective = newStatementAfterBreak(source, afterTrail)
|
|
154
|
+
else isDirective = false // same-line continuation (`.`, `+`, `,`, ...): a string expression
|
|
155
|
+
if (!isDirective) break
|
|
156
|
+
i = afterStr // past the directive; loop for stacked directives
|
|
157
|
+
}
|
|
158
|
+
return `${source.slice(0, i)};${CJS_REQUIRE_REPAIR}${source.slice(i)}`
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
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.
|
|
168
|
+
let createdShardDir
|
|
169
|
+
let createdShardPub
|
|
170
|
+
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.
|
|
177
|
+
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.
|
|
180
|
+
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.
|
|
184
|
+
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.
|
|
189
|
+
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).
|
|
194
|
+
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.
|
|
211
|
+
const OWN_PID = String(process.pid)
|
|
212
|
+
if (!process.env.EXODUS_STASIS_PID) process.env.EXODUS_STASIS_PID = OWN_PID
|
|
213
|
+
const isChildProcess = process.env.EXODUS_STASIS_PID !== OWN_PID
|
|
214
|
+
const forkedChild = isChildProcess && process.channel !== undefined
|
|
215
|
+
|
|
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.
|
|
229
|
+
const PRELOAD_ROOT = (() => {
|
|
230
|
+
try {
|
|
231
|
+
return dirname(findPackageJSON(import.meta.url))
|
|
232
|
+
} catch {
|
|
233
|
+
return undefined
|
|
234
|
+
}
|
|
235
|
+
})()
|
|
236
|
+
|
|
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.
|
|
275
|
+
|
|
276
|
+
function shardForwardingEnabled() {
|
|
277
|
+
return Boolean(state) && state.config.childProcess && (state.config.writeLockfile || state.config.writeBundle)
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
function writeChildShard() {
|
|
281
|
+
if (!shardForwardingEnabled()) return
|
|
282
|
+
const dir = process.env.EXODUS_STASIS_SHARD_DIR
|
|
283
|
+
const keyB64 = process.env.EXODUS_STASIS_SHARD_KEY
|
|
284
|
+
if (!dir || !keyB64) return
|
|
285
|
+
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.
|
|
299
|
+
if (shard === lastShardWritten) return
|
|
300
|
+
const privateKey = createPrivateKey({ key: Buffer.from(keyB64, 'base64'), format: 'der', type: 'pkcs8' })
|
|
301
|
+
const pubId = createPublicKey(privateKey).export({ format: 'jwk' }).x
|
|
302
|
+
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
|
|
304
|
+
const tmpPath = join(dir, `.${pubId}-${unique}.tmp`)
|
|
305
|
+
writeFileSync(tmpPath, JSON.stringify({ shard, signature }))
|
|
306
|
+
renameSync(tmpPath, join(dir, `${pubId}-${unique}.json`))
|
|
307
|
+
lastShardWritten = shard
|
|
308
|
+
} 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.
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
|
|
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.
|
|
316
|
+
const MAX_SHARDS = 4096
|
|
317
|
+
const MAX_SHARD_BYTES = 64 * 1024 * 1024
|
|
318
|
+
|
|
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.
|
|
328
|
+
function mergeChildShards(dir) {
|
|
329
|
+
let handle
|
|
330
|
+
try { handle = opendirSync(dir) } catch { return }
|
|
331
|
+
const prefix = `${createdShardPubId}-`
|
|
332
|
+
let count = 0
|
|
333
|
+
try {
|
|
334
|
+
let dirent
|
|
335
|
+
while ((dirent = handle.readSync()) !== null) {
|
|
336
|
+
const name = dirent.name
|
|
337
|
+
if (!name.startsWith(prefix) || !name.endsWith('.json')) continue
|
|
338
|
+
if (++count > MAX_SHARDS) break
|
|
339
|
+
const path = join(dir, name)
|
|
340
|
+
try {
|
|
341
|
+
if (statSync(path).size > MAX_SHARD_BYTES) continue // skip an over-large shard
|
|
342
|
+
const { shard, signature } = JSON.parse(readFileSync(path, 'utf-8'))
|
|
343
|
+
if (typeof shard !== 'string' || typeof signature !== 'string') continue // unsigned/malformed: reject
|
|
344
|
+
if (!verify(null, Buffer.from(shard), createdShardPub, Buffer.from(signature, 'base64url'))) continue
|
|
345
|
+
state.mergeShard(shard) // the exact bytes we just verified
|
|
346
|
+
} catch {
|
|
347
|
+
// A malformed/partial shard (a child SIGKILLed mid-write) is skipped; the rest merge.
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
} finally {
|
|
351
|
+
try { handle.closeSync() } catch { /* best-effort */ }
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
|
|
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.
|
|
367
|
+
function installFsHooksFromConfig() {
|
|
368
|
+
const fsMode = state.config.fs
|
|
369
|
+
if (!fsMode) return
|
|
370
|
+
installFsHooks({
|
|
371
|
+
// 'async' adds the async readers; 'sync' (the only other valid value) is sync-only.
|
|
372
|
+
async: fsMode === 'async',
|
|
373
|
+
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
|
+
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).
|
|
381
|
+
markAborted: (err) => {
|
|
382
|
+
if (!aborted) console.warn(`[stasis] --fs: capture aborted, no bundle/lockfile will be written -- ${err?.message ?? err}`)
|
|
383
|
+
aborted = true
|
|
384
|
+
},
|
|
385
|
+
})
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
function initState(root) {
|
|
389
|
+
state = new State(root, { preload: true, preloadRoot: PRELOAD_ROOT })
|
|
390
|
+
|
|
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
|
+
installFsHooksFromConfig()
|
|
394
|
+
|
|
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.
|
|
412
|
+
if (!isChildProcess && shardForwardingEnabled()) {
|
|
413
|
+
try {
|
|
414
|
+
const { publicKey, privateKey } = generateKeyPairSync('ed25519')
|
|
415
|
+
createdShardDir = mkdtempSync(join(tmpdir(), 'stasis-shard-'))
|
|
416
|
+
createdShardPub = publicKey
|
|
417
|
+
createdShardPubId = publicKey.export({ format: 'jwk' }).x // base64url(raw public key)
|
|
418
|
+
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.
|
|
425
|
+
process.env.EXODUS_STASIS_SHARD_KEY = privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64')
|
|
426
|
+
} 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
|
|
437
|
+
}
|
|
438
|
+
} 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
|
|
445
|
+
}
|
|
446
|
+
|
|
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.
|
|
478
|
+
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.
|
|
485
|
+
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()
|
|
490
|
+
return
|
|
491
|
+
}
|
|
492
|
+
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
|
+
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
|
+
if (createdShardDir) mergeChildShards(createdShardDir)
|
|
502
|
+
state.write()
|
|
503
|
+
saved = true
|
|
504
|
+
} 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
|
+
}
|
|
511
|
+
}
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
process.on('beforeExit', save)
|
|
515
|
+
process.on('exit', save)
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
function load(url, context, nextLoad) {
|
|
519
|
+
assert.equal(typeof url, 'string')
|
|
520
|
+
|
|
521
|
+
if (url.startsWith('node:')) {
|
|
522
|
+
const result = nextLoad(url, context)
|
|
523
|
+
assert.equal(result.format, 'builtin')
|
|
524
|
+
return result
|
|
525
|
+
}
|
|
526
|
+
|
|
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
|
+
}
|
|
537
|
+
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 }
|
|
569
|
+
}
|
|
570
|
+
return { source, format, shortCircuit: true }
|
|
571
|
+
}
|
|
572
|
+
|
|
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
|
+
}
|
|
583
|
+
let { source } = result
|
|
584
|
+
const { format } = result
|
|
585
|
+
assert.notEqual(format, 'builtin')
|
|
586
|
+
|
|
587
|
+
// Node's CJS loader may return source=null and read from disk itself; capture it for the bundle
|
|
588
|
+
if (source == null && format === 'commonjs') source = readFileSync(fileURLToPath(url))
|
|
589
|
+
|
|
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
|
+
const isEntry = entryUnseen
|
|
598
|
+
entryUnseen = false
|
|
599
|
+
if (!state) {
|
|
600
|
+
const pkg = findPackageJSON(url)
|
|
601
|
+
assert.equal(basename(pkg), 'package.json')
|
|
602
|
+
initState(dirname(pkg))
|
|
603
|
+
}
|
|
604
|
+
|
|
605
|
+
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
|
+
}
|
|
616
|
+
|
|
617
|
+
return result
|
|
618
|
+
}
|
|
619
|
+
|
|
620
|
+
function resolve(specifier, context, nextResolve) {
|
|
621
|
+
if (isBuiltin(specifier)) {
|
|
622
|
+
const res = nextResolve(specifier)
|
|
623
|
+
assert.equal(res.url, specifier.startsWith('node:') ? specifier : `node:${specifier}`)
|
|
624
|
+
return res
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
if (context.importAttributes !== undefined) {
|
|
628
|
+
const expectedAttrs = Object.create(null) // Saving is not supported yet, so we ensure expected ones
|
|
629
|
+
if (extname(specifier) === '.json' && context.importAttributes?.type) expectedAttrs.type = 'json'
|
|
630
|
+
assert.deepStrictEqual(context.importAttributes, expectedAttrs)
|
|
631
|
+
}
|
|
632
|
+
|
|
633
|
+
const { parentURL, conditions, importAttributes } = context
|
|
634
|
+
|
|
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().
|
|
638
|
+
if (!state && !parentURL && process.env.EXODUS_STASIS_BUNDLE === 'load'
|
|
639
|
+
&& process.env.EXODUS_STASIS_SCOPE !== 'node_modules') {
|
|
640
|
+
initState(process.cwd())
|
|
641
|
+
}
|
|
642
|
+
|
|
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.
|
|
659
|
+
if (parentURL && !specifier.startsWith('file:')) {
|
|
660
|
+
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)
|
|
667
|
+
return { url, format, importAttributes: undefined, shortCircuit: true }
|
|
668
|
+
}
|
|
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.
|
|
675
|
+
if (!parentURL && state.config.full && !forkedChild) state.assertEntry(url)
|
|
676
|
+
const format = state.getFormat(url)
|
|
677
|
+
if (format != null && !NODEJS_FORMATS.has(format)) refuseNonNodeFormat(format, url)
|
|
678
|
+
return { url, format, importAttributes: undefined, shortCircuit: true }
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
const res = nextResolve(specifier)
|
|
682
|
+
const { url, format } = res
|
|
683
|
+
|
|
684
|
+
assert.equal(res.importAttributes, undefined) // unsupported yet
|
|
685
|
+
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
|
|
694
|
+
}
|
|
695
|
+
}
|
|
696
|
+
return res
|
|
697
|
+
}
|
|
698
|
+
|
|
699
|
+
let installed = false
|
|
700
|
+
|
|
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.
|
|
708
|
+
export function isLoaderInstalled() {
|
|
709
|
+
return installed
|
|
710
|
+
}
|
|
711
|
+
|
|
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.
|
|
718
|
+
export function ensureStateForLoader() {
|
|
719
|
+
if (state) return
|
|
720
|
+
initState(process.cwd())
|
|
721
|
+
}
|
|
722
|
+
|
|
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.
|
|
729
|
+
export function install() {
|
|
730
|
+
if (installed) return
|
|
731
|
+
installed = true
|
|
732
|
+
registerHooks({ load, resolve })
|
|
733
|
+
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.
|
|
738
|
+
}
|
|
739
|
+
|
|
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.
|
|
752
|
+
function patchCjsResolution() {
|
|
753
|
+
const original = Module._resolveFilename
|
|
754
|
+
Module._resolveFilename = function (request, parent, ...rest) {
|
|
755
|
+
const loadMode = state?.config.loadBundle
|
|
756
|
+
if (loadMode && typeof request === 'string' && !isBuiltin(request)) {
|
|
757
|
+
if (typeof parent?.filename === 'string') {
|
|
758
|
+
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
|
+
if (state.config.full || state.inNodeModules(parentURL)) {
|
|
764
|
+
const resolved = state.resolveBundled(parentURL, request)
|
|
765
|
+
if (resolved !== undefined) return resolved
|
|
766
|
+
}
|
|
767
|
+
} 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).
|
|
790
|
+
const url = pathToFileURL(request).toString()
|
|
791
|
+
if ((state.config.full || state.inNodeModules(url)) && state.getFsStat(url) === 'file') {
|
|
792
|
+
return resolvePath(request)
|
|
793
|
+
}
|
|
794
|
+
}
|
|
795
|
+
}
|
|
796
|
+
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') {
|
|
803
|
+
state.observeResolution(pathToFileURL(parent.filename).toString(), request, pathToFileURL(resolved).toString())
|
|
804
|
+
}
|
|
805
|
+
return resolved
|
|
806
|
+
}
|
|
807
|
+
|
|
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.
|
|
818
|
+
const originalLoad = Module._load
|
|
819
|
+
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 */ }
|
|
823
|
+
}
|
|
824
|
+
return originalLoad.call(this, request, parent, ...rest)
|
|
825
|
+
}
|
|
826
|
+
}
|