@exodus/stasis-core 1.0.0-beta.15 → 1.0.0-beta.16

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/host.js CHANGED
@@ -35,10 +35,7 @@ export const diskHost = {
35
35
  },
36
36
  readlink: (p) => (lstatSync(p).isSymbolicLink() ? readlinkSync(p) : null),
37
37
  realpath: (p) => realpathSync(p),
38
- // fs.globSync's matches of `pattern` from `cwd`, as it spells them, never walking into a path
39
- // `exclude` takes, given its absolute path (Node leaves one out where its `**` meets it alone).
40
- // With `exclude`, the walk is over Dirents, which know their parent (Node hands its callback a
41
- // bare name for a file otherwise), each match then spelled from `cwd`.
38
+ // `exclude` takes an absolute path, so that walk is over Dirents: else Node hands it a bare file name.
42
39
  glob(pattern, { cwd, exclude } = {}) {
43
40
  if (exclude === undefined) return globSync(pattern, { cwd })
44
41
  const pathOf = (dirent) => join(dirent.parentPath, dirent.name)
package/src/loader.js CHANGED
@@ -1,4 +1,4 @@
1
- // Run-time loader entry (`node --import @exodus/stasis-core/loader`): evaluating it snapshots the lib's node:fs/path bindings before any patch.
1
+ // `node --import @exodus/stasis-core/loader`: evaluating it snapshots the lib's node:fs bindings before any patch.
2
2
  import { install } from './hooks.js'
3
3
 
4
4
  install()
package/src/lockfile.js CHANGED
@@ -1,42 +1,29 @@
1
- import { assert, assertArtifactPath, duplicateKeyError, serializeExecutable, flatFileKeys, groupModules, hasNodeModulesSegment, mergeExecutableSets, mergeFormatMaps, mergeImportMaps, mergeModuleMaps, moduleFileKey, moduleInfo, normalizeModule, parseEntries, parseExecutable, parseFormats, parseImports, serializeEntries, serializeFormats, serializeImports } from './artifact-util.js'
1
+ import { assert, assertScope, duplicateKeyError, flatFileKeys, isPlainObject, mergeExecutableSets, mergeFormatMaps, mergeImportMaps, mergeModuleMaps, moduleFileKey, moduleFileKeys, moduleInfo, parseBuckets, parseEntries, parseExecutable, parseFormats, parseImports, serializedParts } from './artifact-util.js'
2
2
 
3
3
  const VERSION = 0
4
4
 
5
5
  const duplicateKey = duplicateKeyError('lockfile', 'lockfile (lock=replace)')
6
6
 
7
- // A record as a lockfile holds it: without `repo` and `subpackages`, metadata a bundle carries and nothing attests.
8
- // `vendored` it keeps, unattested too, so the copies a dependency ships can be audited from a lockfile alone.
9
- const LOCK_METADATA = ['vendored']
10
- const lockRecord = ({ repo: _repo, subpackages: _subpackages, ...info }) => info
7
+ // What the tarball and patch a package was installed from are, and the copies it ships, so a lockfile can be audited alone.
8
+ const LOCK_METADATA = ['integrity', 'patch', 'vendored']
11
9
 
12
10
  export class Lockfile {
13
11
  static VERSION = VERSION
14
12
 
15
13
  version = VERSION
16
- config
17
- entries
18
- modules
19
- // conditions -> parent -> specifier -> resolved file. A Map from parse; null only on in-memory constructs that don't attest it.
20
- imports
21
- // file -> format string. Same Map/null rule as imports.
22
- formats
23
- // Project-relative paths of attested files carrying a POSIX execute bit, for `stasis extract`. Files only, never a `directory`.
24
- executable
25
14
 
26
15
  constructor({ config = { scope: 'full' }, entries, modules, imports, formats, executable } = {}) {
27
- assert(['node_modules', 'full'].includes(config.scope))
16
+ assertScope(config.scope, 'lockfile')
28
17
  this.config = config
29
18
  this.entries = entries ?? new Set()
30
19
  this.modules = modules ?? new Map()
20
+ // conditions -> parent -> specifier -> resolved file, and file -> format: null only on an in-memory construct.
31
21
  this.imports = imports ?? null
32
22
  this.formats = formats ?? null
33
- this.executable = executable ?? new Set()
23
+ this.executable = executable ?? new Set() // files only, never a `directory`
34
24
  }
35
25
 
36
- // The companion lockfile of `bundle`: its shape, each file's content swapped for its integrity,
37
- // `integrityOf(file, content)` of its project-relative path. Imports and formats carry across, else
38
- // the lockfile is bytes-only and a frozen run skips those cross-checks; the file set is the bundle's,
39
- // so its executable list attests it as-is.
26
+ // Imports and formats carry across, else a frozen run would skip those cross-checks.
40
27
  static fromBundle(bundle, integrityOf) {
41
28
  const modules = new Map()
42
29
  for (const [dir, m] of bundle.modules) {
@@ -50,89 +37,58 @@ export class Lockfile {
50
37
  static parse(text) {
51
38
  const json = JSON.parse(text)
52
39
  assert(json.version === VERSION)
53
- assert(['node_modules', 'full'].includes(json.config?.scope))
40
+ assertScope(json.config?.scope, 'lockfile')
54
41
  assert(json.imports !== undefined && json.formats !== undefined, 'lockfile must attest imports and formats')
55
-
56
42
  const full = json.config.scope === 'full'
57
43
  assert(!!json.entries === full)
58
44
  assert(!!json.sources === full)
59
- assert(json.modules)
60
-
61
- const modules = new Map()
62
- for (const [dir, info] of Object.entries(json.modules)) {
63
- assert(hasNodeModulesSegment(dir))
64
- assert(info?.name && info.version && info.files)
65
- modules.set(dir, normalizeModule(lockRecord(info), dir, 'lockfile'))
66
- }
67
-
68
- let entries = new Set()
69
- if (full) {
70
- entries = parseEntries(json.entries, 'lockfile')
71
- for (const [dir, info] of Object.entries(json.sources)) {
72
- assert(!hasNodeModulesSegment(dir))
73
- // A workspace bucket may omit version (a private/unpublished package.json can lack one).
74
- assert(info?.name && info.files)
75
- modules.set(dir, normalizeModule(lockRecord(info), dir, 'lockfile'))
76
- }
77
- }
78
-
79
- // Flat keys must be unique across buckets (mirrors Bundle.parse): two bucket splits can flatten
80
- // to one path, and hashes/attestation lookups key on the flat path.
81
- for (const [dir, { files }] of modules) {
82
- assertArtifactPath(dir, 'lockfile')
83
- assert(files)
84
- }
45
+ assert(isPlainObject(json.modules), 'lockfile: modules must be an object')
46
+ const entries = full ? parseEntries(json.entries, 'lockfile') : new Set()
47
+ const modules = parseBuckets(json, 'lockfile', LOCK_METADATA)
48
+ // Unique across buckets, as in Bundle.parse: hashes and attestation lookups key on the flat path.
85
49
  const flatKeys = flatFileKeys(modules, 'lockfile', duplicateKey)
86
-
87
50
  const imports = parseImports(json.imports)
88
51
  const formats = parseFormats(json.formats)
89
- // Every executable must be a file this lockfile attests.
90
- const executable = json.executable === undefined
91
- ? new Set()
92
- : parseExecutable(json.executable, { what: 'lockfile', files: flatKeys, formats, scope: json.config.scope })
93
-
52
+ const executable = parseExecutable(json.executable, { what: 'lockfile', files: flatKeys, formats, scope: json.config.scope })
94
53
  return new Lockfile({ config: json.config, entries, modules, imports, formats, executable })
95
54
  }
96
55
 
97
56
  serialize() {
98
- // Never write an artifact that parse would reject.
99
57
  flatFileKeys(this.modules, 'lockfile', duplicateKey)
100
- const { modules, sources } = groupModules(this.modules, { metadata: LOCK_METADATA, what: 'lockfile' })
101
- const store = { version: this.version, config: this.config }
102
- if (this.config.scope === 'full') Object.assign(store, { entries: serializeEntries(this.entries, 'lockfile'), sources })
103
- store.modules = modules
104
- if (this.imports !== null) store.imports = serializeImports(this.imports)
105
- if (this.formats !== null) store.formats = serializeFormats(this.formats)
106
- const executable = serializeExecutable(this.executable, {
107
- what: 'lockfile',
108
- modules: this.modules,
109
- // Null on an in-memory construct; an unrecorded format is simply not a directory/stat.
110
- formats: this.formats ?? new Map(),
111
- scope: this.config.scope,
112
- })
113
- if (executable !== undefined) store.executable = executable
58
+ const { entries, sources, modules, imports, formats, executable } = serializedParts(this, 'lockfile', { metadata: LOCK_METADATA })
59
+ const store = { version: this.version, config: this.config, entries, sources, modules, imports, formats, executable }
114
60
  return JSON.stringify(store, undefined, 2) + '\n'
115
61
  }
116
62
 
117
- // Strict union of two Lockfiles (returns a NEW one): buckets must agree, and a file in both must carry the identical hash (fail closed).
118
- merge(other) {
63
+ // A strict union: buckets must agree, and a file in both must carry the identical hash (fail closed).
64
+ merge(other, label = 'lockfile merge', options) {
119
65
  assert(this.config.scope === other.config.scope,
120
- `lockfile merge: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
66
+ `${label}: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
121
67
  return new Lockfile({
122
68
  config: { scope: this.config.scope },
123
69
  entries: new Set([...this.entries, ...other.entries]),
124
- modules: mergeModuleMaps(this.modules, other.modules, 'lockfile merge'),
125
- imports: mergeNullable(this.imports, other.imports, (a, b) => mergeImportMaps(a, b, 'lockfile merge'), 'imports'),
126
- formats: mergeNullable(this.formats, other.formats, (a, b) => mergeFormatMaps(a, b, 'lockfile merge'), 'formats'),
70
+ modules: mergeModuleMaps(this.modules, other.modules, label, options),
71
+ imports: mergeNullable(this.imports, other.imports, mergeImportMaps, 'imports', label),
72
+ formats: mergeNullable(this.formats, other.formats, mergeFormatMaps, 'formats', label),
127
73
  // `other` (the incoming, newer lockfile) wins for the files it records -- see mergeExecutableSets.
128
74
  executable: mergeExecutableSets(this.executable, other.executable, other.modules, this.config.scope),
129
75
  })
130
76
  }
77
+
78
+ // merge, refusing a file both record whose execute bit `other` gives otherwise (merge lets `other`'s win).
79
+ mergeAgreeing(other, label = 'lockfile merge', options) {
80
+ const merged = this.merge(other, label, options)
81
+ const recorded = moduleFileKeys(this.modules, { scope: this.config.scope })
82
+ for (const file of moduleFileKeys(other.modules, { scope: other.config.scope })) {
83
+ if (recorded.has(file) && this.executable.has(file) !== other.executable.has(file)) throw new Error(`${label}: ${file}'s execute bit differs`)
84
+ }
85
+ return merged
86
+ }
131
87
  }
132
88
 
133
- const mergeNullable = (a, b, merge, what) => {
89
+ const mergeNullable = (a, b, merge, what, label) => {
134
90
  if (a === null && b === null) return null
135
91
  assert(a !== null && b !== null,
136
- `lockfile merge: cannot merge ${what} (one lockfile attests ${what}, the other does not)`)
137
- return merge(a, b)
92
+ `${label}: cannot merge ${what} (one lockfile attests ${what}, the other does not)`)
93
+ return merge(a, b, label)
138
94
  }
package/src/policy.js ADDED
@@ -0,0 +1,222 @@
1
+ import { posix, relative, resolve } from 'node:path'
2
+
3
+ import { dependencyEcosystem, hasNodeModulesSegment, moduleFileKeys, posixPathEscapes, sortedByPath, splitNodeModulesPath } from './artifact-util.js'
4
+ import { readPackageJson } from './bundle-util.js'
5
+ import { diskHost } from './host.js'
6
+ import { memoized, relativeEscapes, toPosix } from './util.js'
7
+
8
+ // Each rule is checked on its own, and an artifact meets every Policy that applies: none overrides another.
9
+ export const POLICY_KEYS = ['allowedPaths', 'disallowedPaths', 'allowedModules', 'disallowedModules']
10
+ const PATH_KEYS = new Set(['allowedPaths', 'disallowedPaths'])
11
+ const ALLOWING = new Set(['allowedPaths', 'allowedModules'])
12
+
13
+ const MAX_ALTERNATIVES = 256
14
+ const MAX_LISTED = 20
15
+
16
+ // The patterns every glob reads alike; anything else (a class, an escape, an extglob, a range, a lone or nested
17
+ // brace) is refused, as Node's glob (`extra`'s) may read it otherwise.
18
+ const SIMPLE = /^(?:[\p{L}\p{N}_.@+\-/*?]|\{[\p{L}\p{N}_.@+\-/*?]*,[\p{L}\p{N}_.@+\-/*?,]*\})*$/u
19
+ const isSimple = (pattern) => SIMPLE.test(pattern) && !/[^/]\*\*|\*\*[^/]/u.test(pattern)
20
+
21
+ // As a shell expands brace lists, but for an empty alternative, which Node's glob drops (`{src,}` is `src` alone).
22
+ function alternativesOf(label, pattern) {
23
+ if (!isSimple(pattern)) {
24
+ throw new Error(`${label}: ${JSON.stringify(pattern)} is not supported: a pattern is names of letters, digits ` +
25
+ 'and `_.@+-`, with `*`, `?`, `**` as a whole name and `{a,b}` lists (none nested); match any other character with `?`')
26
+ }
27
+ let out = ['']
28
+ for (const [, text, list] of pattern.matchAll(/([^{]*)(?:\{([^}]*)\})?/gu)) {
29
+ out = out.flatMap((head) => (list === undefined ? [head + text] : list.split(',').map((item) => head + text + item)))
30
+ if (out.length > MAX_ALTERNATIVES) throw new Error(`${label}: ${JSON.stringify(pattern)} expands to more than ${MAX_ALTERNATIVES} patterns`)
31
+ }
32
+ out = out.filter((alternative) => alternative !== '')
33
+ if (out.length === 0) throw new Error(`${label}: ${JSON.stringify(pattern)} expands to no pattern`)
34
+ return out
35
+ }
36
+
37
+ const escapeRegExp = (text) => text.replaceAll(/[$()*+.?[\\\]^{|}]/gu, '\\$&')
38
+
39
+ // `*` and `?` match a dotfile's characters too, so `.env` doesn't slip past `**`.
40
+ const segmentSource = (segment) => segment.replaceAll(/[*?]|[^*?]+/gu, (part) => (part === '*' ? '[^/]*' : part === '?' ? '[^/]' : escapeRegExp(part)))
41
+
42
+ // A `**` segment is any number of segments, none included (`a/**` matches `a`, `**/b` matches `b`).
43
+ function patternSource(pattern) {
44
+ const segments = pattern.split('/').filter((segment, i, all) => !(segment === '**' && all[i - 1] === '**'))
45
+ let out = ''
46
+ for (const [i, segment] of segments.entries()) {
47
+ const first = i === 0
48
+ const last = i === segments.length - 1
49
+ if (segment === '**') {
50
+ out += first && last ? '.*' : first ? '(?:.*/)?' : last ? '(?:/.*)?' : '/(?:.*/)?'
51
+ } else {
52
+ if (!first && segments[i - 1] !== '**') out += '/'
53
+ out += segmentSource(segment)
54
+ }
55
+ }
56
+ return out
57
+ }
58
+
59
+ // `s`: a name may hold a line break, which `.*` (`**`, a directory's paths) must match too.
60
+ const compile = (alternatives, suffix = '') => new RegExp(`^(?:${alternatives.map(patternSource).join('|')})${suffix}$`, 'su')
61
+
62
+ // `src` takes in src/**; the root's own `--fs` listing (`.`) is matched by `.` and `**` alone.
63
+ function pathPattern(label, pattern) {
64
+ const alternatives = alternativesOf(label, pattern).map((alternative) => posix.normalize(alternative).replace(/(?<=.)\/+$/u, ''))
65
+ if (alternatives.some(posixPathEscapes)) {
66
+ throw new Error(`${label}: ${JSON.stringify(pattern)} must be a path or pattern within the directory of stasis.config.json`)
67
+ }
68
+ if (alternatives.includes('.')) return { pattern, test: () => true }
69
+ const regex = compile(alternatives, '(?:/.*)?')
70
+ const matchesRoot = alternatives.some((alternative) => alternative.split('/').every((segment) => segment === '**'))
71
+ return { pattern, test: (path) => (path === '.' ? matchesRoot : regex.test(path)) }
72
+ }
73
+
74
+ // A path such as node_modules/left-pad would match no name, and so silently refuse nothing.
75
+ function modulePattern(label, pattern) {
76
+ const alternatives = alternativesOf(label, pattern)
77
+ const named = (alternative) => {
78
+ const segments = alternative.split('/')
79
+ return segments.length <= 2 && segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..' && segment !== 'node_modules')
80
+ }
81
+ if (!alternatives.every(named)) throw new Error(`${label}: ${JSON.stringify(pattern)} is no package name or pattern of names (such as "left-pad", "@babel/*")`)
82
+ const regex = compile(alternatives)
83
+ return { pattern, test: (name) => name === pattern || regex.test(name) }
84
+ }
85
+
86
+ const listed = (items) => {
87
+ const shown = items.slice(0, MAX_LISTED).join(', ')
88
+ return items.length > MAX_LISTED ? `${shown}, and ${items.length - MAX_LISTED} more` : shown
89
+ }
90
+
91
+ const installedName = (dir) => splitNodeModulesPath(`${dir}/package.json`)?.name
92
+
93
+ const packageText = ({ dir, name, version, via }) => {
94
+ const installed = installedName(dir)
95
+ return `${name}${version === undefined ? '' : `@${version}`} at ${dir}` +
96
+ `${installed === undefined || installed === name ? '' : ` (installed as ${installed})`}${via === undefined ? '' : ` (linked from ${via})`}`
97
+ }
98
+
99
+ export const recordedIn = (path) => ` -- recorded in ${path} already`
100
+
101
+ // The lookup gives { real, pkg } for a path linking to another file in the root, `pkg` the dependency that one is in.
102
+ export function linksOn(root, host = diskHost) {
103
+ let realRoot
104
+ try {
105
+ realRoot = host.realpath(root)
106
+ } catch {
107
+ return () => undefined
108
+ }
109
+ const manifestOf = memoized((dir) => {
110
+ const manifest = readPackageJson(realRoot, `${dir}/package.json`, { host })
111
+ const name = typeof manifest?.name === 'string' && manifest.name !== '' ? manifest.name : installedName(dir)
112
+ return { dir, name, version: typeof manifest?.version === 'string' ? manifest.version : undefined }
113
+ })
114
+ return memoized((path) => {
115
+ const absolute = resolve(root, path)
116
+ let real
117
+ try {
118
+ real = host.realpath(absolute)
119
+ } catch {
120
+ return undefined // gone: a file a loaded artifact records
121
+ }
122
+ if (real === absolute) return undefined
123
+ const rel = toPosix(relative(realRoot, real)) || '.'
124
+ if (rel === path || relativeEscapes(rel)) return undefined
125
+ const dir = splitNodeModulesPath(rel)?.dir
126
+ const pkg = dir === undefined ? undefined : manifestOf(dir)
127
+ return { real: rel, pkg: pkg && { ...pkg, via: path } }
128
+ })
129
+ }
130
+
131
+ // A node_modules-scope artifact carries node_modules alone; a link into a dependency counts as that dependency.
132
+ function artifactContents({ modules, formats, config }, linkOf) {
133
+ const scope = config?.scope ?? 'full'
134
+ const inScope = (path) => scope === 'full' || hasNodeModulesSegment(path)
135
+ const paths = moduleFileKeys(modules, { scope })
136
+ for (const file of formats?.keys() ?? []) if (inScope(file)) paths.add(file)
137
+ const isPackage = ([dir, info]) => Object.keys(info.files).length > 0 && inScope(dir) && dependencyEcosystem(dir, info.ecosystem) !== undefined
138
+ const packages = [...modules].filter(isPackage).map(([dir, { name, version }]) => ({ dir, name, version: version ?? undefined }))
139
+ const dirs = new Set(packages.map(({ dir }) => dir))
140
+ const links = new Map()
141
+ for (const path of paths) {
142
+ const link = linkOf(path)
143
+ if (link === undefined) continue
144
+ links.set(path, link.real)
145
+ if (link.pkg !== undefined && !dirs.has(link.pkg.dir)) {
146
+ dirs.add(link.pkg.dir)
147
+ packages.push(link.pkg)
148
+ }
149
+ }
150
+ return { paths, packages, links }
151
+ }
152
+
153
+ class Policy {
154
+ #rules = new Map()
155
+ // The rules as given, each list deduped and sorted.
156
+ #given = {}
157
+
158
+ constructor(label, config) {
159
+ this.label = label
160
+ for (const key of POLICY_KEYS) {
161
+ const patterns = config[key]
162
+ if (patterns === undefined) continue
163
+ if (!Array.isArray(patterns) || patterns.some((pattern) => typeof pattern !== 'string' || pattern === '')) {
164
+ throw new TypeError(`${label}: ${key} must be an array of non-empty strings`)
165
+ }
166
+ const compileOne = PATH_KEYS.has(key) ? pathPattern : modulePattern
167
+ this.#rules.set(key, patterns.map((pattern) => compileOne(`${label}: ${key}`, pattern)))
168
+ this.#given[key] = [...new Set(patterns)].toSorted()
169
+ }
170
+ }
171
+
172
+ get key() {
173
+ return JSON.stringify(this.#given)
174
+ }
175
+
176
+ withLabel(label) {
177
+ return new Policy(label, this.#given)
178
+ }
179
+
180
+ // A path is checked as its link's target too; a dependency by its package.json name and its install name:
181
+ // refused if a disallowing rule matches either, allowed only if an allowing rule matches both.
182
+ #problems({ paths, packages, links = new Map() }) {
183
+ const problems = []
184
+ for (const [key, patterns] of this.#rules) {
185
+ const allowing = ALLOWING.has(key)
186
+ const isPath = PATH_KEYS.has(key)
187
+ const offenders = []
188
+ for (const item of isPath ? paths : packages) {
189
+ const names = isPath ? [item, links.get(item)] : [item.name, installedName(item.dir)]
190
+ const matches = names.filter((name) => name !== undefined).map((name) => patterns.find(({ test }) => test(name)))
191
+ const match = matches.find((found) => found !== undefined)
192
+ if (allowing ? matches.includes(undefined) : match !== undefined) offenders.push({ item, by: allowing ? '' : ` (${JSON.stringify(match.pattern)})` })
193
+ }
194
+ if (offenders.length === 0) continue
195
+ const texts = isPath
196
+ ? sortedByPath(offenders, ({ item }) => item).map(({ item, by }) => `${item}${links.has(item) ? ` (a link to ${links.get(item)})` : ''}${by}`)
197
+ : offenders.map(({ item, by }) => `${packageText(item)}${by}`)
198
+ const many = `${texts.length} ${isPath ? 'paths' : 'packages'}: ${listed(texts)}`
199
+ if (allowing) problems.push(texts.length === 1 ? `${key} does not allow ${texts[0]}` : `${key} allows none of ${many}`)
200
+ else problems.push(`${key} refuses ${texts.length === 1 ? texts[0] : many}`)
201
+ }
202
+ return problems
203
+ }
204
+
205
+ assert(contents, hint = '') {
206
+ const problems = this.#problems(contents)
207
+ if (problems.length > 0) throw new Error(`${this.label}: ${problems.join('; ')}${hint}`)
208
+ }
209
+
210
+ assertArtifact(artifact, { hint, links }) {
211
+ this.assert(artifactContents(artifact, links), hint)
212
+ }
213
+
214
+ assertPath(path, pkg, link) {
215
+ const packages = pkg === undefined ? [] : [pkg]
216
+ if (link?.pkg !== undefined && link.pkg.dir !== pkg?.dir) packages.push(link.pkg)
217
+ this.assert({ paths: [path], packages, links: link === undefined ? new Map() : new Map([[path, link.real]]) })
218
+ }
219
+ }
220
+
221
+ export const parsePolicy = (label, config) =>
222
+ (config === null || typeof config !== 'object' || !POLICY_KEYS.some((key) => Object.hasOwn(config, key)) ? null : new Policy(label, config))