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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/bundle.js CHANGED
@@ -4,20 +4,25 @@ import {
4
4
  fileMapToObject,
5
5
  fileSetToObject,
6
6
  fromEntries,
7
+ hasNodeModulesSegment,
7
8
  isPlainObject,
9
+ mergeFormatMaps,
10
+ mergeImportMaps,
11
+ mergeExecutableSets,
12
+ mergeModuleMaps,
8
13
  moduleFileKey,
9
14
  objectToMaps,
15
+ parseExecutable,
16
+ serializeExecutable,
10
17
  posixPathEscapes,
11
18
  sortPaths,
12
19
  splitNodeModulesPath,
13
- } from './util.js'
20
+ } from './artifact-util.js'
14
21
 
15
22
  const VERSION = 1
16
23
  const LEGACY_VERSION = 0
17
24
 
18
25
  const normalize = ({ name, version, ecosystem, files }) => {
19
- // `ecosystem` (when present) names the package ecosystem a dependency came from
20
- // (`npm`, `composer`, `soldeer`); the workspace/top-level buckets omit it.
21
26
  assert(ecosystem === undefined || typeof ecosystem === 'string')
22
27
  return { name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files: fromEntries(Object.entries(files)) }
23
28
  }
@@ -25,41 +30,34 @@ const normalize = ({ name, version, ecosystem, files }) => {
25
30
  const inferModuleDir = (path) =>
26
31
  splitNodeModulesPath(path) ?? { dir: '.', rel: path, name: null }
27
32
 
28
- // Bundle handles the JSON shape of stasis.code.br; callers (State) are responsible
29
- // for the brotli wrapper around the JSON text. One unified shape carries both code
30
- // and resources, distinguished per file by `formats[file]` ('resource' = raw UTF-8
31
- // payload, 'resource:base64' = base64-encoded; everything else is code). On-disk
32
- // version:
33
- // v0 — legacy flat layout: top-level `sources` keyed by project-relative path.
34
- // No entries / modules / formats / imports.
35
- // v1 — current layout, mirrors stasis.lock.json: per-package buckets under
36
- // `sources` (workspace) and `modules` (node_modules) with name+version+files,
37
- // plus `entries`, `formats`, and `imports`.
38
- // `Bundle.parse` accepts both; offline tooling (stasis extract / diff / audit /
39
- // sbom) reads v0 -- paths are regrouped by package dir via `inferModuleDir`
40
- // (best-effort, last-wins); name/version stay null since v0 records neither,
41
- // which State uses as a marker to skip metadata cross-checks. `stasis run`
42
- // refuses v0 -- see State's load path. We always serialize v1.
33
+ const mergeReason = (a, b) => {
34
+ if (a === undefined) return b
35
+ if (b === undefined) return a
36
+ const out = {}
37
+ for (const src of [a, b]) {
38
+ for (const [consumer, files] of Object.entries(src)) {
39
+ out[consumer] = fileSetToObject(new Set([...(out[consumer] ?? []), ...files]))
40
+ }
41
+ }
42
+ return out
43
+ }
44
+
45
+ // JSON shape of stasis.code.br; callers own the brotli wrap. parse accepts legacy v0 and v1, serialize always writes v1.
43
46
  export class Bundle {
44
47
  static VERSION = VERSION
45
48
 
46
- // The on-disk version this instance represents. Defaults to VERSION; parse*
47
- // sets it to whatever the file declared (LEGACY_VERSION for v0 input).
48
- // Serialization always writes the current VERSION regardless — loading v0 and
49
- // re-saving promotes the bundle to v1.
50
49
  version = VERSION
51
50
  config
52
51
  entries
53
52
  modules
54
53
  formats
55
54
  imports
56
- // Informational only (NOT attested): maps each consumer that recorded a bundled file --
57
- // 'run' (the loader/CLI), 'StasisWebpack', 'StasisMetro', etc. -- to the files it contributed.
58
- // Present only when a single bundle had MORE THAN ONE consumer (e.g. `run` plus a plugin sharing
59
- // the same bundleFile); a single-consumer bundle omits it. Never consulted for verification.
55
+ // Project-relative paths of bundled files carrying a POSIX execute bit, for `stasis extract`. Files only, never a `directory`.
56
+ executable
57
+ // Informational only, NOT attested -- never consulted for verification.
60
58
  reason
61
59
 
62
- constructor({ config = { scope: 'full' }, entries, modules, formats, imports, reason, version = VERSION } = {}) {
60
+ constructor({ config = { scope: 'full' }, entries, modules, formats, imports, executable, reason, version = VERSION } = {}) {
63
61
  assert([LEGACY_VERSION, VERSION].includes(version))
64
62
  assert(['node_modules', 'full'].includes(config.scope))
65
63
  this.version = version
@@ -68,13 +66,11 @@ export class Bundle {
68
66
  this.modules = modules ?? new Map()
69
67
  this.formats = formats ?? new Map()
70
68
  this.imports = imports ?? new Map()
69
+ this.executable = executable ?? new Set()
71
70
  this.reason = reason
72
71
  }
73
72
 
74
- // Flat project-relative view of file contents collected from this.modules.
75
- // Per-file encoding is signalled by `formats[file]`: 'resource:base64' is a
76
- // base64 string, everything else (including 'resource' and 'directory') is a
77
- // raw UTF-8 string.
73
+ // Flat project-relative view of the raw stored file contents (resources stay base64).
78
74
  get sources() {
79
75
  const m = new Map()
80
76
  for (const [dir, { files }] of this.modules) {
@@ -85,19 +81,20 @@ export class Bundle {
85
81
  return m
86
82
  }
87
83
 
88
- // True for the resource-like, non-executable payload formats. Their bundle
89
- // content is a raw UTF-8 string ('resource', and 'directory' — a JSON-serialized
90
- // `fs.readdirSync` listing) or a base64 blob ('resource:base64'). State stores
91
- // all three in `this.resources` (vs `this.sources` for code) and the loader's
92
- // executable allowlist rejects them, so this is the single "is this a code file?"
93
- // discriminator. Only 'resource:base64' is base64-decoded; the others are raw.
94
84
  static isResourceFormat(format) {
95
85
  return format === 'resource' || format === 'resource:base64' || format === 'directory'
96
86
  }
97
87
 
98
- // One parser for the unified shape (and legacy v0 code bundles). Resources are just
99
- // files tagged 'resource'/'resource:base64' in `formats`; State splits them back out
100
- // by consulting the formats map.
88
+ // True if any bundled file is non-resource; a full-scope code bundle must declare an entry to be runnable (State#absorbCodeBundle).
89
+ get hasCode() {
90
+ for (const [dir, { files }] of this.modules) {
91
+ for (const rel of Object.keys(files)) {
92
+ if (!Bundle.isResourceFormat(this.formats.get(moduleFileKey(dir, rel)))) return true
93
+ }
94
+ }
95
+ return false
96
+ }
97
+
101
98
  static parse(text) {
102
99
  const json = JSON.parse(text)
103
100
  assert(json.version === VERSION || json.version === LEGACY_VERSION)
@@ -105,18 +102,12 @@ export class Bundle {
105
102
  assert(isPlainObject(json.formats))
106
103
  assert(isPlainObject(json.imports))
107
104
 
108
- // Validate `formats` early so downstream branches (hasCode, etc.) can consult
109
- // the typed Map instead of the raw `json.formats` object -- a missing key like
110
- // `__proto__` would otherwise short-circuit on the prototype, and an unknown
111
- // tag would only surface late at a string compare.
105
+ // Validate formats into a typed Map early: a raw-object lookup like `__proto__` would hit the prototype.
112
106
  const formats = new Map()
113
107
  for (const [file, format] of Object.entries(json.formats)) {
114
108
  assert(!posixPathEscapes(file))
115
109
  assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
116
- // The project root's `directory` listing is keyed '.' -- bundles written before
117
- // that normalization keyed it '' (see moduleFileKey), which no lookup ever hits
118
- // again at load. Normalize on parse so those artifacts keep serving; the alias
119
- // makes '' and '.' the SAME key, so both appearing is a duplicate -- fail closed.
110
+ // '' and '.' alias to the same key (older bundles keyed the root listing ''); normalize, fail closed on dupes.
120
111
  const key = file === '' ? '.' : file
121
112
  assert(!formats.has(key), `duplicate format key '${key}'`)
122
113
  formats.set(key, format)
@@ -130,7 +121,7 @@ export class Bundle {
130
121
  if (json.modules !== undefined) {
131
122
  assert(typeof json.modules === 'object' && json.modules !== null)
132
123
  for (const [dir, info] of Object.entries(json.modules)) {
133
- assert(dir.includes('node_modules'))
124
+ assert(hasNodeModulesSegment(dir))
134
125
  assert(!posixPathEscapes(dir))
135
126
  assert(info?.name && info.version && info.files)
136
127
  modules.set(dir, normalize(info))
@@ -139,46 +130,23 @@ export class Bundle {
139
130
  if (full) {
140
131
  assert(json.sources && typeof json.sources === 'object')
141
132
  for (const [dir, info] of Object.entries(json.sources)) {
142
- assert(!dir.includes('node_modules'))
133
+ assert(!hasNodeModulesSegment(dir))
143
134
  assert(!posixPathEscapes(dir))
144
135
  assert(info?.name && info.version && info.files)
145
136
  modules.set(dir, normalize(info))
146
137
  }
147
- // A bundle that carries code in full scope must declare at least one entry:
148
- // empty entries would let `state.assertEntry` skip its check (it short-circuits
149
- // on entries.size === 0 for v0+no-lockfile compatibility), which a tampered
150
- // bundle could exploit. A resources-only bundle has no code files and thus no
151
- // entries -- allowed, since there is nothing for assertEntry to guard.
152
- let hasCode = false
153
- for (const [dir, { files }] of modules) {
154
- for (const rel of Object.keys(files)) {
155
- // moduleFileKey (not `${dir}/${rel}`): a `directory` capture at a module
156
- // root keys at rel === '', whose trailing-slash join would miss its
157
- // resource-format lookup and miscount the listing as code here.
158
- const fp = moduleFileKey(dir, rel)
159
- if (!Bundle.isResourceFormat(formats.get(fp))) { hasCode = true; break }
160
- }
161
- if (hasCode) break
162
- }
163
- if (hasCode) {
164
- assert(Array.isArray(json.entries) && json.entries.length > 0,
165
- 'bundle carrying code in scope=full must have at least one entry')
166
- entries = new Set(json.entries)
167
- } else {
168
- assert(json.entries === undefined || (Array.isArray(json.entries) && json.entries.length === 0))
169
- }
138
+ // Empty entries are valid (`stasis add` attests files without making them entry points); state.assertEntry fails closed on an empty set.
139
+ assert(json.entries === undefined || Array.isArray(json.entries))
140
+ entries = new Set(json.entries)
170
141
  } else {
171
142
  assert(json.entries === undefined)
172
143
  assert(json.sources === undefined)
173
144
  }
174
145
  for (const [, { files }] of modules) {
175
- // posixPathEscapes (not a '..' prefix check) so a mid-path escape or an
176
- // absolute path fails too, matching Lockfile.parse. rel === '' (a
177
- // `directory` capture keyed at a module root) normalizes to '.' and passes.
146
+ // posixPathEscapes (not a '..' prefix): also catches mid-path escapes and absolute paths.
178
147
  for (const rel of Object.keys(files)) assert(!posixPathEscapes(rel))
179
148
  }
180
149
  } else {
181
- // v0 legacy: flat sources at top level, regrouped by inferred module dir.
182
150
  assert(json.sources)
183
151
  for (const [path, content] of Object.entries(json.sources)) {
184
152
  assert(!posixPathEscapes(path))
@@ -189,15 +157,18 @@ export class Bundle {
189
157
  }
190
158
  }
191
159
 
192
- // Resolution edges name project-relative files on both sides; getImport
193
- // resolves the target against the project root, so a path that escapes the
194
- // root (including a mid-path `a/../../x`) must be rejected here rather than
195
- // pulling an out-of-tree file in at load time.
160
+ // Flat keys must be unique across buckets: two different bucket splits can flatten to one path, and the `sources` getter would serve either payload.
161
+ const flatKeys = new Set()
162
+ for (const [dir, { files }] of modules) {
163
+ for (const rel of Object.keys(files)) {
164
+ const key = moduleFileKey(dir, rel)
165
+ assert(!flatKeys.has(key), `duplicate file key '${key}' across bundle buckets`)
166
+ flatKeys.add(key)
167
+ }
168
+ }
169
+
170
+ // Reject paths escaping the root here (incl. mid-path `a/../../x`): getImport resolves against the root at load.
196
171
  const imports = objectToMaps(json.imports)
197
- // An edge target is normally a file string. A `stasis bundle --metro` edge that
198
- // resolves differently per platform is instead a { platform: file } map (which
199
- // objectToMaps has turned into a Map). Validate both shapes; reject anything else
200
- // (e.g. a deeper nesting) so a tampered artifact fails closed at the schema edge.
201
172
  const assertTarget = (target) => {
202
173
  if (typeof target === 'string') {
203
174
  assert(!posixPathEscapes(target))
@@ -226,7 +197,11 @@ export class Bundle {
226
197
  modules,
227
198
  formats,
228
199
  imports,
229
- reason: isPlainObject(json.reason) ? json.reason : undefined, // informational, preserved for round-trip
200
+ // Every executable must be a file this bundle carries. A v0 `executable` is ignored: with no per-file `formats` it could point `extract` at any path to chmod +x.
201
+ executable: json.version === VERSION
202
+ ? parseExecutable(json.executable, { what: 'bundle', files: flatKeys, formats, scope: json.config.scope })
203
+ : new Set(),
204
+ reason: isPlainObject(json.reason) ? json.reason : undefined,
230
205
  })
231
206
  }
232
207
 
@@ -235,7 +210,7 @@ export class Bundle {
235
210
  const sourceEntries = []
236
211
  for (const [dir, { name, version, ecosystem, files }] of this.modules) {
237
212
  if (Object.keys(files).length === 0) continue
238
- const inNodeModules = dir.includes('node_modules')
213
+ const inNodeModules = hasNodeModulesSegment(dir)
239
214
  if (inNodeModules) assert(name && version && files)
240
215
  const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
241
216
  const target = inNodeModules ? moduleEntries : sourceEntries
@@ -246,10 +221,6 @@ export class Bundle {
246
221
  return { modules: fromEntries(moduleEntries), sources: fromEntries(sourceEntries) }
247
222
  }
248
223
 
249
- // One unified on-disk shape for code AND resources. A file is a resource when its
250
- // `formats` entry is 'resource' (raw UTF-8 content) or 'resource:base64' (binary,
251
- // base64-encoded); every other format is code carrying a raw UTF-8 source string.
252
- // A single bundle can therefore hold both; readers split by consulting `formats`.
253
224
  serialize() {
254
225
  const entries = fileSetToObject(this.entries)
255
226
  const { modules, sources } = this.#groupedFromModules()
@@ -258,8 +229,42 @@ export class Bundle {
258
229
  const data = { version: VERSION, config: this.config }
259
230
  if (this.config.scope === 'full') Object.assign(data, { entries, sources })
260
231
  Object.assign(data, { modules, formats, imports })
261
- // Informational provenance, last: only present when set (more than one consumer).
232
+ const executable = serializeExecutable(this.executable, {
233
+ what: 'bundle', modules: this.modules, formats: this.formats, scope: this.config.scope,
234
+ })
235
+ if (executable !== undefined) data.executable = executable
262
236
  if (this.reason !== undefined) data.reason = this.reason
263
237
  return JSON.stringify(data, undefined, 2)
264
238
  }
239
+
240
+ // Stamp `consumer` onto every carried file in the informational `reason` map.
241
+ withReason(consumer) {
242
+ const files = [...this.sources.keys()]
243
+ return new Bundle({
244
+ version: this.version,
245
+ config: this.config,
246
+ entries: this.entries,
247
+ modules: this.modules,
248
+ formats: this.formats,
249
+ imports: this.imports,
250
+ executable: this.executable,
251
+ reason: mergeReason(this.reason, { [consumer]: files }),
252
+ })
253
+ }
254
+
255
+ // Strict union of two Bundles (returns a NEW one): any genuine conflict throws -- a bundle is an attestation.
256
+ merge(other) {
257
+ assert(this.config.scope === other.config.scope,
258
+ `bundle merge: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
259
+ return new Bundle({
260
+ config: { scope: this.config.scope },
261
+ entries: new Set([...this.entries, ...other.entries]),
262
+ modules: mergeModuleMaps(this.modules, other.modules, 'bundle merge'),
263
+ formats: mergeFormatMaps(this.formats, other.formats, 'bundle merge'),
264
+ imports: mergeImportMaps(this.imports, other.imports, 'bundle merge'),
265
+ // `other` (the incoming, newer build) wins for the files it carries -- see mergeExecutableSets.
266
+ executable: mergeExecutableSets(this.executable, other.executable, other.modules, this.config.scope),
267
+ reason: mergeReason(this.reason, other.reason),
268
+ })
269
+ }
265
270
  }