dsh-plugin-inspector 0.5.0 → 0.7.0

package/lib/knowledge.js

@@ -11,9 +11,15 @@
  */
 /**
  * Harness version these tables were transcribed from — the version string in
- * the checkout's own `packages/bundle/*/package.json`.
+ * the shipped bundles' own `package.json`, which is `dsh`'s own version.
+ *
+ * Re-verified against `0.1.1-rc.2`, the release npm tags `latest`, by
+ * extracting each table from the published packages and diffing it against the
+ * one here. What moved: six rows inserted by the web bundle, three seam keys,
+ * and two sandbox traps this table had never carried. What did not: every row
+ * name, every row's bundle membership, and the waterfall event set.
  */
-export const HARNESS_REFERENCE = '0.1.0-rc.5';
+export const HARNESS_REFERENCE = '0.1.1-rc.2';
 /**
  * The three profile bundles the harness ships, mapped to what each one is.
  * A package that *is* one of these composes the core rows rather than modifying
@@ -63,6 +69,7 @@ export const CORE_ROWS = new Map([
     ['cordis-host-runner', { module: '@deepseek-ai/dsh-cordis-host-runner', bundles: ['web-app'] }],
     ['credentials', { module: '@deepseek-ai/dsh-credentials-local', bundles: ['base'] }],
     ['directory-picker', { module: '@deepseek-ai/dsh-host-directory-picker-auto', bundles: ['web-app'] }],
+    ['file-reference-local', { module: '@deepseek-ai/dsh-file-reference-local', bundles: ['web-app'] }],
     ['fs-observation-policy', { module: '@deepseek-ai/dsh-fs-observation-policy', bundles: ['base'] }],
     ['fs-sandbox', { module: '@deepseek-ai/dsh-fs-sandbox', bundles: ['base'] }],
     ['goal', { module: '@deepseek-ai/dsh-goal', bundles: ['base'] }],
@@ -92,6 +99,7 @@ export const CORE_ROWS = new Map([
     ['session-projection', { module: '@deepseek-ai/dsh-session-projection', bundles: ['base'] }],
     ['session-projection-cache', { module: '@deepseek-ai/dsh-session-projection-cache', bundles: ['web-app'] }],
     ['session-query-sqlite', { module: '@deepseek-ai/dsh-session-query-sqlite', bundles: ['base'] }],
+    ['session-reference', { module: '@deepseek-ai/dsh-session-reference', bundles: ['web-app'] }],
     ['session-stats', { module: '@deepseek-ai/dsh-session-stats', bundles: ['web-app'] }],
     ['session-telemetry-otel', { module: '@deepseek-ai/dsh-session-telemetry-otel', bundles: ['base'] }],
     ['session-title', { module: '@deepseek-ai/dsh-session-title', bundles: ['base'] }],
@@ -137,6 +145,8 @@ export const CORE_ROWS = new Map([
     ['typert-gateway', { module: '@deepseek-ai/dsh-api-gateway', bundles: ['base'] }],
     ['typert-loader', { module: '@deepseek-ai/dsh-typert-loader', bundles: ['base'] }],
     ['ui-agent-preset', { module: '@deepseek-ai/dsh-client-ui-agent-preset', bundles: ['web-app'] }],
+    ['ui-attachment', { module: '@deepseek-ai/dsh-client-ui-attachment', bundles: ['web-app'] }],
+    ['ui-brand-official', { module: '@deepseek-ai/dsh-client-ui-brand-official', bundles: ['web-app'] }],
     ['ui-commands', { module: '@deepseek-ai/dsh-client-ui-commands', bundles: ['web-app'] }],
     ['ui-conversation', { module: '@deepseek-ai/dsh-client-ui-conversation', bundles: ['web-app'] }],
     ['ui-cordis', { module: '@deepseek-ai/dsh-client-ui-cordis', bundles: ['web-app'] }],
@@ -149,6 +159,8 @@ export const CORE_ROWS = new Map([
     ['ui-model-selection', { module: '@deepseek-ai/dsh-client-ui-model-selection', bundles: ['web-app'] }],
     ['ui-permission', { module: '@deepseek-ai/dsh-client-ui-permission-presets', bundles: ['web-app'] }],
     ['ui-plan', { module: '@deepseek-ai/dsh-client-ui-plan', bundles: ['web-app'] }],
+    ['ui-reference', { module: '@deepseek-ai/dsh-client-ui-reference', bundles: ['web-app'] }],
+    ['ui-renderer', { module: '@deepseek-ai/dsh-client-ui-renderer', bundles: ['web-app'] }],
     ['ui-settings', { module: '@deepseek-ai/dsh-client-ui-settings', bundles: ['web-app'] }],
     ['ui-settings-general', { module: '@deepseek-ai/dsh-client-ui-settings-general', bundles: ['web-app'] }],
     ['ui-settings-models', { module: '@deepseek-ai/dsh-client-ui-settings-models', bundles: ['web-app'] }],
@@ -207,10 +219,10 @@ export const SECURITY_ROW_IDS = new Map([
  * replaces a core service for every consumer in its scope.
  */
 export const SEAM_KEYS = new Set([
-    'agentDefaultModel', 'agentLoop', 'agentPresets', 'agents', 'apiProxy', 'approval',
-    'attachments', 'clientModules', 'codeRuntime', 'commands', 'compaction', 'credentials',
-    'directoryPicker', 'e2b', 'fs', 'goals', 'invariants', 'jobs', 'llm', 'lsp',
-    'messageFeedback', 'permissionPresets', 'planMode', 'sandbox', 'sandboxPolicy',
+    'agentDefaultModel', 'agentLoop', 'agentPresets', 'agents', 'agentTeams', 'apiProxy', 'approval',
+    'attachments', 'authorization', 'clientModules', 'codeRuntime', 'commands', 'compaction',
+    'credentials', 'directoryPicker', 'e2b', 'fileReferences', 'fs', 'goals', 'invariants', 'jobs',
+    'llm', 'lsp', 'messageFeedback', 'permissionPresets', 'planMode', 'sandbox', 'sandboxPolicy',
     'sessionPersistence', 'sessionProjectionCache', 'sessionProjections', 'sessionQuery',
     'sessionReferenceResolver', 'sessions', 'sessionTelemetry', 'sessionTitle', 'settings',
     'shell', 'shellEnv', 'skills', 'spillStore', 'storage', 'storageDomain', 'subagents',
@@ -218,10 +230,21 @@ export const SEAM_KEYS = new Set([
     'tools', 'typert', 'typertGateway', 'userQuestions', 'web', 'webServer', 'workflowEngine',
     'workspaceRegistry',
 ]);
-/** The subset of {@link SEAM_KEYS} whose replacement removes a constraint. */
+/**
+ * The subset of {@link SEAM_KEYS} whose replacement removes a constraint.
+ *
+ * `authorization` joined the catalogue in `0.1.1-rc.2`: it is the registry of
+ * flows that obtain a credential through a conversation with the user, so
+ * providing it means owning that conversation. That is the same class of
+ * substitution as `credentials`, which this set already holds. The other two
+ * keys the release added are not: `fileReferences` decides which paths are
+ * offered for completion and `agentTeams` is the team form of `subagents`,
+ * which is deliberately not here either.
+ */
 export const SECURITY_SEAM_KEYS = new Set([
-    'approval', 'sandbox', 'sandboxPolicy', 'permissionPresets', 'credentials', 'subprocess',
-    'shell', 'fs', 'tools', 'agentLoop', 'sessionPersistence', 'sessionTelemetry', 'invariants',
+    'approval', 'authorization', 'sandbox', 'sandboxPolicy', 'permissionPresets', 'credentials',
+    'subprocess', 'shell', 'fs', 'tools', 'agentLoop', 'sessionPersistence', 'sessionTelemetry',
+    'invariants',
 ]);
 /**
  * Waterfall events, from `EVENT_API` in the api-catalog. A listener on one of
@@ -229,6 +252,10 @@ export const SECURITY_SEAM_KEYS = new Set([
  * without calling it short-circuits the chain including the built-in behavior.
  *
  * Note there is no `fs/read-intent` — the intent family is write and edit only.
+ *
+ * Unchanged in `0.1.1-rc.2`. The catalogue's event set grew by four and lost
+ * one, but every addition carries `mode: 'emit'`, and only `mode: 'waterfall'`
+ * hands a listener the trailing `next` this set is about.
  */
 export const WATERFALL_EVENTS = new Set([
     'agent/pre-step', 'agent/request', 'agent/request-error', 'approval/request',
@@ -252,6 +279,8 @@ export const SANDBOX_DENIED_GLOBALS = new Map([
     ['setTimeout', "redirected to the cordis timer service (inject: ['timer'])"],
     ['setInterval', "redirected to the cordis timer service (inject: ['timer'])"],
     ['setImmediate', "redirected to the cordis timer service (inject: ['timer'])"],
+    ['clearTimeout', "redirected to the cordis timer service (inject: ['timer'])"],
+    ['clearInterval', "redirected to the cordis timer service (inject: ['timer'])"],
 ]);
 /**
  * Node builtins that start or evaluate code off the mediated path. A mounted

package/lib/npm.js

@@ -7,16 +7,27 @@
  * fixed and their order is the guarantee:
  *
  * 1. read the version document (~3 KB) — which already answers
- *    `hasInstallScript`, the install lifecycle scripts, and `dsh.bundle`;
+ *    `hasInstallScript`, the install lifecycle scripts, `dsh.bundle`, and
+ *    whether the registry holds a provenance attestation at all;
  * 2. download the tarball into memory;
  * 3. verify `dist.integrity` **before** anything parses a byte of it;
- * 4. decode in memory and analyse, exactly as the tarball path does.
+ * 4. read the provenance attestation, when step 1 said there is one, and check
+ *    it against the bytes step 3 vouched for;
+ * 5. decode in memory and analyse, exactly as the tarball path does.
+ *
+ * Step 4 is the only request this module makes that is not unconditional, and
+ * it is skipped for every package the version document says has no attestation
+ * — which on the measured corpus is 28 packages in 40. It never fails an
+ * analysis: an endpoint that is down or a bundle that does not decode leaves
+ * the provenance fact in state `unreadable`, which is a different answer from
+ * `absent` and is printed as one.
  *
  * No subprocess, no disk write, no lifecycle script, and no `npm pack`.
  * @module dsh-plugin-inspector/npm
  */
+import { provenanceAbsent, provenanceUnreadable, readProvenance, } from "./attestation.js";
 import { analyze } from "./inspect.js";
-import { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, resolvePackage, } from "./registry.js";
+import { attestationUrl, DEFAULT_REGISTRY, fetchAttestation, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, } from "./registry.js";
 import { loadTarballBuffer } from "./source.js";
 /**
  * The metadata pre-check, which needs no tarball.
@@ -31,6 +42,46 @@ import { loadTarballBuffer } from "./source.js";
 export async function precheck(spec, options = {}) {
     return resolvePackage(parseSpec(spec), options);
 }
+/**
+ * Read the registry's provenance attestation for a resolved package, when it
+ * has one, and check it against the bytes that were downloaded.
+ *
+ * Every failure on this path becomes a fact rather than a refusal. The tarball
+ * has already been checked against `dist.integrity`, so the analysis is sound
+ * whatever the attestation endpoint does, and turning a registry outage into
+ * exit code 2 would make provenance a precondition for reading a package
+ * instead of something reported about it.
+ * @param resolved - the packument reading for the version.
+ * @param registry - the registry base URL, without a trailing slash.
+ * @param tarball - the verified tarball bytes.
+ * @param options - where to fetch from.
+ * @returns what the registry says about the build origin, and what was checked.
+ */
+async function readRegistryProvenance(resolved, registry, tarball, options) {
+    if (resolved.provenancePredicateType === null)
+        return provenanceAbsent();
+    let url;
+    try {
+        url = attestationUrl(registry, resolved.name, resolved.version);
+    }
+    catch (error) {
+        /* v8 ignore next -- `attestationUrl` refuses a name or version only with a RegistryError. */
+        if (!(error instanceof RegistryError))
+            throw error;
+        return provenanceUnreadable(null, error.message);
+    }
+    let body;
+    try {
+        body = await fetchAttestation(url, options);
+    }
+    catch (error) {
+        /* v8 ignore next -- `fetchAttestation` reports every refusal as a RegistryError. */
+        if (!(error instanceof RegistryError))
+            throw error;
+        return provenanceUnreadable(url, error.message);
+    }
+    return readProvenance(body, { name: resolved.name, version: resolved.version, tarball, url });
+}
 /**
  * Fetch a published package and inspect it in memory.
  * @param spec - `<name>` or `<name>@<version>`; no version means the `latest` tag.
@@ -42,9 +93,11 @@ export async function precheck(spec, options = {}) {
 export async function inspectFromNpm(spec, options = {}) {
     const resolved = await precheck(spec, options);
     const verified = await fetchVerifiedTarball(resolved, options);
+    const registry = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
+    const attestation = await readRegistryProvenance(resolved, registry, verified.bytes, options);
     const provenance = {
         spec,
-        registry: (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, ''),
+        registry,
         resolvedVersion: resolved.version,
         tarball: resolved.tarball,
         digest: verified.digest,
@@ -54,5 +107,5 @@ export async function inspectFromNpm(spec, options = {}) {
         tarballBytes: verified.bytes.byteLength,
     };
     const source = await loadTarballBuffer(verified.bytes, `npm:${resolved.name}@${resolved.version}`);
-    return analyze(source, provenance);
+    return analyze(source, provenance, attestation);
 }

package/lib/registry.js

@@ -19,6 +19,7 @@
  * @module dsh-plugin-inspector/registry
  */
 import { createHash } from 'node:crypto';
+import { MAX_ATTESTATION_BYTES } from "./attestation.js";
 import { INSTALL_LIFECYCLE_SCRIPTS } from "./knowledge.js";
 import { MAX_TOTAL_BYTES } from "./source.js";
 /** The public npm registry, used when no other is named. */
@@ -146,6 +147,7 @@ export async function resolvePackage(spec, options = {}) {
         integrity: typeof dist.integrity === 'string' ? dist.integrity : null,
         shasum: typeof dist.shasum === 'string' ? dist.shasum : null,
         hasInstallScript: record.hasInstallScript === true,
+        provenancePredicateType: asString(asRecord(asRecord(dist.attestations).provenance), 'predicateType'),
         lifecycleScripts: INSTALL_LIFECYCLE_SCRIPTS.filter(name => typeof scripts[name] === 'string'),
         bundlePatch: typeof bundle.patch === 'string' ? bundle.patch : null,
         metadataBytes: body.byteLength,
@@ -162,6 +164,16 @@ function asRecord(value) {
         ? value
         : {};
 }
+/**
+ * Read a string field, or `null` when it is absent or of another type.
+ * @param record - the containing record.
+ * @param key - the field name.
+ * @returns the string, or `null`.
+ */
+function asString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : null;
+}
 /**
  * Refuse a tarball URL that points somewhere other than the registry that
  * described it.
@@ -260,3 +272,45 @@ export async function fetchVerifiedTarball(resolved, options = {}) {
     const bytes = await readCapped(response, MAX_TARBALL_BYTES, `tarball ${resolved.tarball}`);
     return verifyIntegrity(bytes, resolved);
 }
+/**
+ * The endpoint an npm-compatible registry serves a version's attestation
+ * bundle from.
+ *
+ * Built from the registry base URL rather than read out of
+ * `dist.attestations.url`, which is the opposite of how the tarball URL is
+ * handled and is deliberate: the tarball has to come from wherever the registry
+ * says because there is no other way to name it, so that URL is taken from the
+ * document and then refused unless it is same-origin. An attestation needs no
+ * such freedom. Constructing the path here means a doctored packument cannot
+ * redirect the request at all, not even to another path on the same host.
+ *
+ * The name and version are re-validated because both come out of the version
+ * document, which is registry-controlled: `name` is not necessarily the name
+ * that was asked for, and it is interpolated into a URL.
+ * @param registry - the registry base URL, without a trailing slash.
+ * @param name - the resolved package name.
+ * @param version - the resolved version.
+ * @returns the absolute URL.
+ * @throws RegistryError when the document's name or version would not address this endpoint.
+ */
+export function attestationUrl(registry, name, version) {
+    if (!PACKAGE_NAME.test(name))
+        throw new RegistryError(`the version document names no npm package: ${name}`);
+    if (!VERSION_OR_TAG.test(version))
+        throw new RegistryError(`the version document names no version: ${version}`);
+    return `${registry}/-/npm/v1/attestations/${name}@${version}`;
+}
+/**
+ * Download an attestation document.
+ *
+ * Only ever called when the version document said there is one, so a package
+ * without provenance costs no request at all.
+ * @param url - the endpoint, from {@link attestationUrl}.
+ * @param options - where to fetch from.
+ * @returns the document as served.
+ * @throws RegistryError on a transport failure, a non-2xx status, or an oversized body.
+ */
+export async function fetchAttestation(url, options = {}) {
+    const response = await get(url, 'application/json', options);
+    return readCapped(response, MAX_ATTESTATION_BYTES, 'attestation document');
+}

package/lib/report.js

@@ -19,6 +19,16 @@ const COLOR = {
     bold: '\u001b[1m',
     reset: '\u001b[0m',
 };
+/** Indent that lines a wrapped fact value up under the first one. */
+const CONTINUATION = `\n${' '.repeat(18)}`;
+/** What each unchecked claim means, spelled out rather than left as a key. */
+const GAP_MEANING = {
+    'certificate-chain': 'that the signing certificate is Sigstore\'s — this tool carries no trust root, so a '
+        + 'registry serving a doctored bundle passes every check above',
+    'transparency-log': 'the Rekor transparency-log inclusion proof in the bundle, which needs the same trust root',
+    'builder-identity': 'the signer identity, because the statement names no GitHub Actions workflow to compare the '
+        + 'certificate against',
+};
 /** How the human report labels each severity. */
 const LABEL = {
     critical: 'CRITICAL',
@@ -123,6 +133,46 @@ function describeFileSet(facts) {
     return `working tree narrowed to what npm would publish, by ${basis}`
         + ` (${facts.unpublishedFiles} unpublished file(s) not read)`;
 }
+/**
+ * Say what the registry attested about this tarball's build origin, and — with
+ * equal prominence — what of that was checked here and what was not.
+ *
+ * The report is not allowed to let a reader mistake one for the other. "The
+ * registry told me a claim exists" and "I checked the claim" are different
+ * statements, and the second is only partly true: the digest, the package
+ * name, the DSSE signature and the certificate's own identity are checked, and
+ * whether the certificate belongs to Sigstore is not. So the `not checked` row
+ * is printed whenever the `checked` row is, never as a footnote and never
+ * conditionally.
+ * @param provenance - the fact.
+ * @returns the rows to print.
+ */
+function renderProvenance(provenance) {
+    if (provenance.state === 'unavailable') {
+        return [['provenance', `not readable here — ${provenance.reason}`]];
+    }
+    if (provenance.state === 'absent') {
+        return [['provenance',
+                'none — the registry published no build provenance for this version, which most published packages do not']];
+    }
+    if (provenance.state === 'unreadable') {
+        return [['provenance', `the registry says this version has one and it could not be read — ${provenance.reason}`]];
+    }
+    const origin = `${provenance.sourceRepository ?? 'an unnamed repository'}`
+        + `${provenance.sourceCommit === null ? '' : ` @ ${provenance.sourceCommit}`}`
+        + `${provenance.sourceRef === null ? '' : ` (${provenance.sourceRef})`}`;
+    return [
+        ['provenance', provenance.state === 'attested'
+                ? `attested to ${origin}`
+                : `ATTESTED TO ${origin}, AND THE ATTESTATION DOES NOT CHECK OUT`],
+        ['built by', `${provenance.workflow ?? 'an unnamed workflow'}`
+                + `${provenance.builder === null ? '' : ` on ${provenance.builder}`}`],
+        ['checked', provenance.checks
+                .map(check => `${check.passed ? 'ok  ' : 'FAIL'} ${check.name} — ${check.detail}`)
+                .join(CONTINUATION)],
+        ['not checked', provenance.notChecked.map(gap => GAP_MEANING[gap]).join(CONTINUATION)],
+    ];
+}
 /**
  * Render the "what does this plugin do" section, which is printed whether or
  * not there are findings.
@@ -132,19 +182,24 @@ function describeFileSet(facts) {
  */
 function renderFacts(report, paint) {
     const { facts } = report;
-    const provenance = report.target.registry;
+    const registry = report.target.registry;
     const rows = [
         ['package', `${facts.packageName}@${facts.packageVersion}${facts.license === null ? '' : ` (${facts.license})`}`],
         ['read from', `${report.target.kind} ${report.target.path}`],
-        ...provenance === undefined
+        ...registry === undefined
             ? []
             : [
-                ['fetched from', `${provenance.tarball} (${provenance.tarballBytes} bytes, never written to disk)`],
-                ['verified', `${provenance.digest} matched dist.integrity before anything parsed it`],
-                ['install script', provenance.hasInstallScript
+                ['fetched from', `${registry.tarball} (${registry.tarballBytes} bytes, never written to disk)`],
+                // Which field matched is not cosmetic: `dist.shasum` is SHA-1 and is
+                // only reached on packages published before npm 5, so naming
+                // `dist.integrity` there would report a stronger check than ran.
+                ['verified', `${registry.digest} matched `
+                        + `${registry.algorithm === 'sha1' ? 'dist.shasum' : 'dist.integrity'} before anything parsed it`],
+                ['install script', registry.hasInstallScript
                         ? 'yes — the registry marks this package as running one at install time'
                         : 'no — the registry does not mark this package as running one'],
             ],
+        ...renderProvenance(facts.provenance),
         /* v8 ignore start -- `mountsAsBundle` is true exactly when the manifest declared a path. */
         ['mounted layer', facts.mountsAsBundle
                 ? `yes — dsh.bundle.patch = ${facts.bundlePatchPath ?? '?'} (imported into the harness process at the agent's uid)`
@@ -153,7 +208,7 @@ function renderFacts(report, paint) {
         ['browser bundle', facts.shipsClientBundle ? 'yes — dsh.client with an ./client export, executed in the user\'s browser' : 'no'],
         ['rows inserted', facts.insertedRows.length === 0
                 ? 'none'
-                : facts.insertedRows.map(row => `${row.id}${row.name === undefined ? '' : ` → ${row.name}`}`).join('\n                ')],
+                : facts.insertedRows.map(row => `${row.id}${row.name === undefined ? '' : ` → ${row.name}`}`).join(CONTINUATION)],
         ['rows modified', facts.targetedRows.length === 0 ? 'none' : facts.targetedRows.join(', ')],
         ['!!js in layer', describeExpressions(facts.jsExpressions)],
         ['other layers', facts.unmountedPatchFiles.length === 0

package/lib/source.js

@@ -15,7 +15,9 @@
  * cap.
  *
  * Symbolic links are recorded and never followed, for the same reason: a link
- * pointing outside the package is not part of the package.
+ * pointing outside the package is not part of the package. Anything else that
+ * is not a regular file — a FIFO, a socket, a device node — is recorded the
+ * same way and never opened.
  * @module dsh-plugin-inspector/source
  */
 import { createReadStream, openSync, readdirSync, readFileSync, readSync, closeSync, statSync } from 'node:fs';
@@ -131,8 +133,15 @@ function walkDirectory(root, directory, collector, published) {
             walkDirectory(root, absolute, collector, published);
             continue;
         }
-        if (!entry.isFile())
+        if (!entry.isFile()) {
+            // A FIFO, socket or device node the publish set includes is content the
+            // analyzer did not read, and "how much could be read" is the one number
+            // that may never be overstated. Reading one is also not an option: a
+            // `readFileSync` on a FIFO blocks until somebody writes to it.
+            if (published.includes(path))
+                collector.skipped.push({ path, reason: 'unreadable' });
             continue;
+        }
         if (!published.includes(path)) {
             collector.unpublished += 1;
             continue;

package/lib/syntax.js

@@ -0,0 +1,135 @@
+/**
+ * Readings of a syntax tree that both capability detection and readability
+ * detection need, and that must agree between them.
+ *
+ * Tier B matches a name; Tier C reports the names it could not match. If the
+ * two disagree about which expressions are constant, a package gets both a
+ * finding and a degrade for the same site, or neither. They agree because they
+ * ask the same function.
+ *
+ * Nothing here evaluates anything. {@link foldConstantString} reads literals
+ * out of an already-parsed tree and concatenates them; it never constructs a
+ * function, and it never touches an identifier's value.
+ * @module dsh-plugin-inspector/syntax
+ */
+import ts from 'typescript';
+/**
+ * How far {@link foldConstantString} descends before answering `null`.
+ *
+ * A bound rather than a promise: the folder recurses over attacker-supplied
+ * syntax, and a name worth hiding is not hidden eight levels of concatenation
+ * deep. Past the bound the answer is "this tool cannot resolve it", which
+ * degrades the report rather than dropping the site.
+ */
+const MAX_FOLD_DEPTH = 8;
+/**
+ * The separator `Array.prototype.join` uses when called with no argument.
+ */
+const DEFAULT_JOIN_SEPARATOR = ',';
+/**
+ * The `Array.prototype.join` case: `['node:child', '_process'].join('')`.
+ * @param node - the call expression.
+ * @param depth - the current recursion depth.
+ * @returns the joined text, or `null` when any part is not a constant.
+ */
+function foldJoin(node, depth) {
+    const callee = node.expression;
+    if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'join')
+        return null;
+    if (!ts.isArrayLiteralExpression(callee.expression))
+        return null;
+    const separator = node.arguments.length === 0
+        ? DEFAULT_JOIN_SEPARATOR
+        : fold(node.arguments[0], depth + 1);
+    if (separator === null)
+        return null;
+    const parts = [];
+    for (const element of callee.expression.elements) {
+        const part = fold(element, depth + 1);
+        if (part === null)
+            return null;
+        parts.push(part);
+    }
+    return parts.join(separator);
+}
+/**
+ * The template case: `` `node:${'fs'}` ``.
+ * @param node - the template expression.
+ * @param depth - the current recursion depth.
+ * @returns the assembled text, or `null` when any span is not a constant.
+ */
+function foldTemplate(node, depth) {
+    let text = node.head.text;
+    for (const span of node.templateSpans) {
+        const value = fold(span.expression, depth + 1);
+        if (value === null)
+            return null;
+        text += value + span.literal.text;
+    }
+    return text;
+}
+/**
+ * The recursive half of {@link foldConstantString}.
+ * @param node - the expression to fold.
+ * @param depth - the current recursion depth.
+ * @returns the text, or `null`.
+ */
+function fold(node, depth) {
+    if (node === undefined || depth > MAX_FOLD_DEPTH)
+        return null;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    if (ts.isParenthesizedExpression(node))
+        return fold(node.expression, depth + 1);
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const left = fold(node.left, depth + 1);
+        const right = fold(node.right, depth + 1);
+        return left === null || right === null ? null : left + right;
+    }
+    if (ts.isTemplateExpression(node))
+        return foldTemplate(node, depth);
+    if (ts.isCallExpression(node))
+        return foldJoin(node, depth);
+    return null;
+}
+/**
+ * The text a constant string expression holds, or `null` when the expression is
+ * not constant.
+ *
+ * Four forms, chosen because each one is a spelling of a name that a reader
+ * sees and a name-matching check does not: a literal, a `+` chain of them, a
+ * template whose every span is one, and `[…].join(…)` over an array of them.
+ * Anything reaching an identifier, a property, or any other call answers
+ * `null` — resolving those is value tracking, which this tool does not do and
+ * which Tier C exists to admit.
+ * @param node - the expression, or `undefined` for a missing argument.
+ * @returns the text, or `null`.
+ */
+export function foldConstantString(node) {
+    return fold(node, 0);
+}
+/**
+ * The Node API that hands back a builtin module without `require` and without
+ * an `import` declaration, added in Node 22.3.
+ *
+ * It reaches the same modules the harness sandbox's `require` trap covers,
+ * from a call that sandbox never sees: the sandbox leaves
+ * `process` `undefined`, so inside it this expression throws, and a mounted
+ * bundle layer is not inside it.
+ * @see https://nodejs.org/api/process.html#processgetbuiltinmoduleid
+ */
+export const BUILTIN_MODULE_GETTER = 'getBuiltinModule';
+/**
+ * Whether a call is `process.getBuiltinModule(…)`.
+ *
+ * The receiver is required. `getBuiltinModule` pulled off `process` and bound
+ * to a bare name is not this — it is a detached member, which Tier C reports as
+ * dispatch it cannot follow.
+ * @param node - the call expression.
+ * @returns true when the call loads a builtin through `process`.
+ */
+export function isBuiltinModuleGetter(node) {
+    const callee = node.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === BUILTIN_MODULE_GETTER
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'process';
+}