detect-libc 2.1.2: Prevent silent native addon resolution errors by accounting for detect-libc ignoring process.env overrides, returning null on non-Linux, and relying on multi-tier host probes

# Notes on detect-libc Configuration & Platform Probing

## search_known_solution Result
`search_known_solution` answered with low-confidence unrelated samples (Vitest 4 test environments, esbuild platform binary resolution, and python packaging specifiers) with no existing contract for `detect-libc` environment configuration.

## What a Model Would Have Written Instead
A naive model would configure `process.env.LIBC = 'musl'` or `process.env.npm_config_libc = 'musl'` in build/CI scripts expecting `detect-libc` to honor the environment override, and write `if (isNonGlibcLinuxSync()) useMusl(); else useGlibc();` expecting `isNonGlibcLinuxSync()` to return `true` on non-glibc hosts like macOS and Windows.

## How the Wrong Version Fails
Fails silently with a green build during packaging and CI, but crashes in production: setting `process.env.LIBC` is silently ignored by `detect-libc` because it strictly inspects runtime host probes (`/proc/self/exe`, `/usr/bin/ldd`, and `process.report`), while branching on `!isNonGlibcLinuxSync()` on macOS/Windows incorrectly selects glibc Linux native addons on non-Linux platforms where `isNonGlibcLinuxSync()` returns `false`.

{"case":{"caseId":"case:sha256:06740b365886dddbb3ce7dcc400d9ad8ab7caace9f9297705415f251dd35f64c","contract":["assert detect-libc ignores process.env overrides (LIBC, npm_config_libc) and strictly evaluates runtime host probes","assert non-Linux platforms return null for familySync and versionSync, not empty strings or OS names","assert isNonGlibcLinuxSync evaluates process.platform === 'linux' and returns false on non-Linux platforms","assert ELF interpreter parsing detects glibc and musl without child process execution","assert versionSync cannot resolve from ELF headers alone and returns null when ldd and diagnostic reports lack version data","assert detect-libc mutates and restores process.report.excludeNetwork when reading process reports"],"goal":"Prevent silent native addon resolution errors by accounting for detect-libc ignoring process.env overrides, returning null on non-Linux, and relying on multi-tier host probes","kind":"HOW","packages":["pkg:npm/detect-libc@2.1.2"],"schemaVersion":1,"symbols":["family","familySync","isNonGlibcLinux","isNonGlibcLinuxSync","version","versionSync","GLIBC","MUSL"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/detect-libc@2.1.2"],"schemaVersion":1,"symbols":["family","familySync","isNonGlibcLinux","isNonGlibcLinuxSync","version","versionSync","GLIBC","MUSL"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-detect-libc-config",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-detect-libc-config",
      "version": "1.0.0",
      "dependencies": {
        "detect-libc": "2.1.2"
      }
    },
    "node_modules/detect-libc": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
      "license": "Apache-2.0",
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "npm-detect-libc-config",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "detect-libc": "2.1.2"
  }
}

import assert from 'node:assert/strict';
import vm from 'node:vm';
import fs from 'node:fs';
import { createRequire } from 'node:module';
import detectLibc, {
  GLIBC,
  MUSL,
  family,
  familySync,
  isNonGlibcLinux,
  isNonGlibcLinuxSync,
  version,
  versionSync,
} from 'detect-libc';

const require = createRequire(import.meta.url);

// ============================================================================
// 1. Environment Variable Override Trap
// ============================================================================
// Naive expectation: Setting process.env.LIBC, npm_config_libc, or
// npm_config_target_libc configures detect-libc output or forces musl/glibc.
// Reality: detect-libc completely ignores process.env; it solely probes the
// runtime host system. Setting env vars has zero effect.
{
  const baselineFamily = familySync();
  const baselineVersion = versionSync();
  const baselineNonGlibc = isNonGlibcLinuxSync();

  // Attempt to override via common build/CI environment variables
  process.env.LIBC = 'musl';
  process.env.npm_config_libc = 'musl';
  process.env.npm_config_target_libc = 'musl';
  process.env.TARGET_LIBC = 'musl';

  assert.equal(
    familySync(),
    baselineFamily,
    'familySync() must not change when process.env.LIBC is set to musl'
  );
  assert.equal(
    versionSync(),
    baselineVersion,
    'versionSync() must not change when process.env.LIBC is set to musl'
  );
  assert.equal(
    isNonGlibcLinuxSync(),
    baselineNonGlibc,
    'isNonGlibcLinuxSync() must not change when process.env.LIBC is set to musl'
  );

  // Attempt to override via glibc
  process.env.LIBC = 'glibc';
  process.env.npm_config_libc = 'glibc';
  assert.equal(
    familySync(),
    baselineFamily,
    'familySync() must not change when process.env.LIBC is set to glibc'
  );

  // Clean up
  delete process.env.LIBC;
  delete process.env.npm_config_libc;
  delete process.env.npm_config_target_libc;
  delete process.env.TARGET_LIBC;
}

// ============================================================================
// 2. Non-Linux Platform Guard & isNonGlibcLinux Trap
// ============================================================================
// Naive expectation:
// 1) On macOS/Windows, familySync() returns an OS name ('darwin', 'win32', 'msvc')
//    or empty string '' (which was v1 behavior).
// 2) isNonGlibcLinuxSync() returns true on macOS/Windows because they are "not glibc Linux".
// Reality:
// 1) Non-Linux returns null (NOT empty string, NOT 'unknown', NOT 'darwin'/'win32').
// 2) isNonGlibcLinuxSync() returns false on non-Linux because it requires process.platform === 'linux'.
{
  const detectLibcPath = require.resolve('detect-libc');
  const detectLibcCode = fs.readFileSync(detectLibcPath, 'utf8');
  const processModPath = require.resolve('detect-libc/lib/process.js');
  const processModCode = fs.readFileSync(processModPath, 'utf8');
  const filesystemModPath = require.resolve('detect-libc/lib/filesystem.js');
  const filesystemModCode = fs.readFileSync(filesystemModPath, 'utf8');
  const elfModPath = require.resolve('detect-libc/lib/elf.js');
  const elfModCode = fs.readFileSync(elfModPath, 'utf8');

  const createIsolatedDetectLibc = (platform, mocks = {}) => {
    const modules = {};
    const customProcess = {
      platform,
      arch: 'x64',
      report: mocks.report || undefined,
      versions: process.versions,
      env: {},
    };

    const customRequire = (id) => {
      if (id === './process') {
        if (!modules['./process']) {
          const mod = { exports: {} };
          const ctx = vm.createContext({
            process: customProcess,
            module: mod,
            exports: mod.exports,
            require: customRequire,
          });
          vm.runInContext(processModCode, ctx);
          modules['./process'] = mod.exports;
        }
        return modules['./process'];
      }
      if (id === './filesystem') {
        if (!modules['./filesystem']) {
          const mod = { exports: {} };
          const ctx = vm.createContext({
            fs: mocks.fs || fs,
            Buffer,
            module: mod,
            exports: mod.exports,
            require: (reqId) => {
              if (reqId === 'fs') return mocks.fs || fs;
              return require(reqId);
            },
          });
          vm.runInContext(filesystemModCode, ctx);
          modules['./filesystem'] = mod.exports;
        }
        return modules['./filesystem'];
      }
      if (id === './elf') {
        if (!modules['./elf']) {
          const mod = { exports: {} };
          const ctx = vm.createContext({
            module: mod,
            exports: mod.exports,
            require: customRequire,
          });
          vm.runInContext(elfModCode, ctx);
          modules['./elf'] = mod.exports;
        }
        return modules['./elf'];
      }
      if (id === 'child_process') {
        return mocks.childProcess || {
          exec: (_cmd, cb) => cb(new Error('command not available')),
          execSync: () => {
            throw new Error('command not available');
          },
        };
      }
      return require(id);
    };

    const mod = { exports: {} };
    const ctx = vm.createContext({
      require: customRequire,
      process: customProcess,
      module: mod,
      exports: mod.exports,
      Buffer,
      Promise,
      Error,
    });
    vm.runInContext(detectLibcCode, ctx);
    return mod.exports;
  };

  // Test Darwin (macOS)
  const darwinInstance = createIsolatedDetectLibc('darwin');
  assert.equal(darwinInstance.familySync(), null, 'familySync() on darwin must be null');
  assert.notEqual(darwinInstance.familySync(), '', 'familySync() on darwin must not be empty string');
  assert.notEqual(darwinInstance.familySync(), 'unknown', 'familySync() on darwin must not be "unknown"');
  assert.equal(darwinInstance.versionSync(), null, 'versionSync() on darwin must be null');
  // Critical trap: isNonGlibcLinuxSync() returns FALSE on macOS, not TRUE
  assert.equal(
    darwinInstance.isNonGlibcLinuxSync(),
    false,
    'isNonGlibcLinuxSync() on darwin must be false'
  );

  // Test Win32 (Windows)
  const win32Instance = createIsolatedDetectLibc('win32');
  assert.equal(win32Instance.familySync(), null, 'familySync() on win32 must be null');
  assert.equal(win32Instance.versionSync(), null, 'versionSync() on win32 must be null');
  assert.equal(
    win32Instance.isNonGlibcLinuxSync(),
    false,
    'isNonGlibcLinuxSync() on win32 must be false'
  );

  // Demonstrate why naive conditional selection fails:
  // Naive pattern: if (isNonGlibcLinuxSync()) useMusl(); else useGlibc();
  const naiveSelectBinary = (libcMod) => {
    if (libcMod.isNonGlibcLinuxSync()) {
      return 'musl-binary';
    }
    return 'glibc-binary'; // BUG: macOS and Windows wrongly end up here!
  };
  assert.equal(naiveSelectBinary(darwinInstance), 'glibc-binary'); // Naive failure demonstrated
}

// ============================================================================
// 3. Multi-Tier Fallback Hierarchy & ELF vs Version Asymmetry
// ============================================================================
// Tier 1: /proc/self/exe (ELF PT_INTERP)
// Tier 2: /usr/bin/ldd (filesystem inspection)
// Tier 3: process.report.getReport() (Node diagnostic report)
// Tier 4: child_process exec (getconf / ldd)
//
// Traps:
// 1) ELF PT_INTERP identifies libc family ('glibc' or 'musl') without spawning
//    child processes or checking /usr/bin/ldd.
// 2) ELF PT_INTERP does NOT contain glibc version numbers; versionSync() can never
//    resolve from Tier 1 alone and must fall back.
// 3) In a distroless musl container (no ldd, no getconf), familySync() succeeds via
//    ELF or process.report.sharedObjects, but versionSync() returns null.
{
  const detectLibcPath = require.resolve('detect-libc');
  const detectLibcCode = fs.readFileSync(detectLibcPath, 'utf8');
  const processModCode = fs.readFileSync(require.resolve('detect-libc/lib/process.js'), 'utf8');
  const elfModCode = fs.readFileSync(require.resolve('detect-libc/lib/elf.js'), 'utf8');

  // Helper to build a minimal 64-bit ELF binary buffer with PT_INTERP
  const buildMockElf = (interpreterStr) => {
    const interpBuf = Buffer.from(interpreterStr + '\0', 'utf8');
    const headerSize = 64;
    const phtEntrySize = 56;
    const phtOffset = headerSize;
    const interpOffset = headerSize + phtEntrySize;
    const totalSize = interpOffset + interpBuf.length;

    const buf = Buffer.alloc(totalSize);
    // ELF magic: 0x7f 'E' 'L' 'F'
    buf[0] = 0x7f;
    buf[1] = 0x45;
    buf[2] = 0x4c;
    buf[3] = 0x46;
    buf[4] = 2; // 64-bit
    buf[5] = 1; // Little endian
    buf[6] = 1; // Original ELF version

    // e_phoff at 0x20 (uint64)
    buf.writeBigUInt64LE(BigInt(phtOffset), 0x20);
    // e_phentsize at 0x36 (uint16)
    buf.writeUInt16LE(phtEntrySize, 0x36);
    // e_phnum at 0x38 (uint16)
    buf.writeUInt16LE(1, 0x38);

    // Program Header 0: PT_INTERP (type = 3)
    buf.writeUInt32LE(3, phtOffset); // p_type = PT_INTERP
    buf.writeBigUInt64LE(BigInt(interpOffset), phtOffset + 8); // p_offset
    buf.writeBigUInt64LE(BigInt(interpBuf.length), phtOffset + 32); // p_filesz

    // Write interpreter string
    interpBuf.copy(buf, interpOffset);
    return buf;
  };

  // 3a. Verify Musl detection from ELF PT_INTERP
  {
    const muslElf = buildMockElf('/lib/ld-musl-x86_64.so.1');
    const modules = {};
    const customProcess = {
      platform: 'linux',
      arch: 'x64',
      report: undefined,
      versions: process.versions,
      env: {},
    };

    const customRequire = (id) => {
      if (id === './process') {
        if (!modules['./process']) {
          const mod = { exports: {} };
          vm.runInContext(processModCode, vm.createContext({ process: customProcess, module: mod, exports: mod.exports }));
          modules['./process'] = mod.exports;
        }
        return modules['./process'];
      }
      if (id === './filesystem') {
        return {
          LDD_PATH: '/usr/bin/ldd',
          SELF_PATH: '/proc/self/exe',
          readFileSync: (p) => {
            if (p === '/proc/self/exe') return muslElf;
            throw new Error('ENOENT');
          },
          readFile: (p) => {
            if (p === '/proc/self/exe') return Promise.resolve(muslElf);
            return Promise.reject(new Error('ENOENT'));
          },
        };
      }
      if (id === './elf') {
        if (!modules['./elf']) {
          const mod = { exports: {} };
          vm.runInContext(elfModCode, vm.createContext({ module: mod, exports: mod.exports }));
          modules['./elf'] = mod.exports;
        }
        return modules['./elf'];
      }
      if (id === 'child_process') {
        return {
          exec: (_cmd, cb) => cb(new Error('exec disabled')),
          execSync: () => {
            throw new Error('execSync disabled');
          },
        };
      }
      return require(id);
    };

    const mod = { exports: {} };
    vm.runInContext(
      detectLibcCode,
      vm.createContext({
        require: customRequire,
        process: customProcess,
        module: mod,
        exports: mod.exports,
        Buffer,
        Promise,
        Error,
      })
    );

    assert.equal(mod.exports.familySync(), MUSL, 'familySync() must detect musl from ELF header');
    assert.equal(mod.exports.isNonGlibcLinuxSync(), true, 'isNonGlibcLinuxSync() must be true for musl');
    // Version cannot be determined from ELF alone without ldd or child_process
    assert.equal(mod.exports.versionSync(), null, 'versionSync() must be null when only ELF is available');
  }

  // 3b. Verify GLIBC detection from ELF PT_INTERP
  {
    const glibcElf = buildMockElf('/lib64/ld-linux-x86-64.so.2');
    const modules = {};
    const customProcess = {
      platform: 'linux',
      arch: 'x64',
      report: undefined,
      versions: process.versions,
      env: {},
    };

    const customRequire = (id) => {
      if (id === './process') {
        if (!modules['./process']) {
          const mod = { exports: {} };
          vm.runInContext(processModCode, vm.createContext({ process: customProcess, module: mod, exports: mod.exports }));
          modules['./process'] = mod.exports;
        }
        return modules['./process'];
      }
      if (id === './filesystem') {
        return {
          LDD_PATH: '/usr/bin/ldd',
          SELF_PATH: '/proc/self/exe',
          readFileSync: (p) => {
            if (p === '/proc/self/exe') return glibcElf;
            throw new Error('ENOENT');
          },
          readFile: (p) => {
            if (p === '/proc/self/exe') return Promise.resolve(glibcElf);
            return Promise.reject(new Error('ENOENT'));
          },
        };
      }
      if (id === './elf') {
        if (!modules['./elf']) {
          const mod = { exports: {} };
          vm.runInContext(elfModCode, vm.createContext({ module: mod, exports: mod.exports }));
          modules['./elf'] = mod.exports;
        }
        return modules['./elf'];
      }
      if (id === 'child_process') {
        return {
          exec: (_cmd, cb) => cb(new Error('exec disabled')),
          execSync: () => {
            throw new Error('execSync disabled');
          },
        };
      }
      return require(id);
    };

    const mod = { exports: {} };
    vm.runInContext(
      detectLibcCode,
      vm.createContext({
        require: customRequire,
        process: customProcess,
        module: mod,
        exports: mod.exports,
        Buffer,
        Promise,
        Error,
      })
    );

    assert.equal(mod.exports.familySync(), GLIBC, 'familySync() must detect glibc from ELF header');
    assert.equal(mod.exports.isNonGlibcLinuxSync(), false, 'isNonGlibcLinuxSync() must be false for glibc');
    // Version cannot be determined from ELF header alone
    assert.equal(mod.exports.versionSync(), null, 'versionSync() must be null when only ELF is available');
  }
}

// ============================================================================
// 4. Process Report Diagnostic Probing & excludeNetwork Mutability
// ============================================================================
// When /proc/self/exe and /usr/bin/ldd fail (e.g. strict sandboxes / chroot):
// Tier 3 checks process.report.getReport().
//
// Traps:
// 1) detect-libc sets process.report.excludeNetwork = true before getReport()
//    and restores the original value afterwards.
// 2) On glibc: report.header.glibcVersionRuntime yields both GLIBC family and version string.
// 3) On musl: report.sharedObjects containing 'ld-musl-' yields MUSL family, but version is null.
{
  const detectLibcPath = require.resolve('detect-libc');
  const detectLibcCode = fs.readFileSync(detectLibcPath, 'utf8');
  const processModCode = fs.readFileSync(require.resolve('detect-libc/lib/process.js'), 'utf8');
  const elfModCode = fs.readFileSync(require.resolve('detect-libc/lib/elf.js'), 'utf8');

  // 4a. glibc via process.report
  {
    let excludeNetworkObservedDuringGetReport = null;
    const mockReport = {
      excludeNetwork: false,
      getReport: () => {
        excludeNetworkObservedDuringGetReport = mockReport.excludeNetwork;
        return {
          header: {
            glibcVersionRuntime: '2.35',
          },
          sharedObjects: ['/lib/x86_64-linux-gnu/libc.so.6'],
        };
      },
    };

    const customProcess = {
      platform: 'linux',
      arch: 'x64',
      report: mockReport,
      versions: process.versions,
      env: {},
    };

    const modules = {};
    const customRequire = (id) => {
      if (id === './process') {
        if (!modules['./process']) {
          const mod = { exports: {} };
          vm.runInContext(processModCode, vm.createContext({ process: customProcess, module: mod, exports: mod.exports }));
          modules['./process'] = mod.exports;
        }
        return modules['./process'];
      }
      if (id === './filesystem') {
        return {
          LDD_PATH: '/usr/bin/ldd',
          SELF_PATH: '/proc/self/exe',
          readFileSync: () => {
            throw new Error('ENOENT');
          },
          readFile: () => Promise.reject(new Error('ENOENT')),
        };
      }
      if (id === './elf') {
        if (!modules['./elf']) {
          const mod = { exports: {} };
          vm.runInContext(elfModCode, vm.createContext({ module: mod, exports: mod.exports }));
          modules['./elf'] = mod.exports;
        }
        return modules['./elf'];
      }
      if (id === 'child_process') {
        return {
          exec: (_cmd, cb) => cb(new Error('exec disabled')),
          execSync: () => {
            throw new Error('execSync disabled');
          },
        };
      }
      return require(id);
    };

    const mod = { exports: {} };
    vm.runInContext(
      detectLibcCode,
      vm.createContext({
        require: customRequire,
        process: customProcess,
        module: mod,
        exports: mod.exports,
        Buffer,
        Promise,
        Error,
      })
    );

    assert.equal(mod.exports.familySync(), GLIBC);
    assert.equal(mod.exports.versionSync(), '2.35');
    assert.equal(mod.exports.isNonGlibcLinuxSync(), false);
    // Verify excludeNetwork was set to true during getReport() and restored to false
    assert.equal(excludeNetworkObservedDuringGetReport, true, 'excludeNetwork must be true during report generation');
    assert.equal(mockReport.excludeNetwork, false, 'excludeNetwork must be restored after report generation');
  }

  // 4b. musl via process.report sharedObjects
  {
    const mockReport = {
      excludeNetwork: false,
      getReport: () => ({
        header: {},
        sharedObjects: ['/lib/ld-musl-x86_64.so.1'],
      }),
    };

    const customProcess = {
      platform: 'linux',
      arch: 'x64',
      report: mockReport,
      versions: process.versions,
      env: {},
    };

    const modules = {};
    const customRequire = (id) => {
      if (id === './process') {
        if (!modules['./process']) {
          const mod = { exports: {} };
          vm.runInContext(processModCode, vm.createContext({ process: customProcess, module: mod, exports: mod.exports }));
          modules['./process'] = mod.exports;
        }
        return modules['./process'];
      }
      if (id === './filesystem') {
        return {
          LDD_PATH: '/usr/bin/ldd',
          SELF_PATH: '/proc/self/exe',
          readFileSync: () => {
            throw new Error('ENOENT');
          },
          readFile: () => Promise.reject(new Error('ENOENT')),
        };
      }
      if (id === './elf') {
        if (!modules['./elf']) {
          const mod = { exports: {} };
          vm.runInContext(elfModCode, vm.createContext({ module: mod, exports: mod.exports }));
          modules['./elf'] = mod.exports;
        }
        return modules['./elf'];
      }
      if (id === 'child_process') {
        return {
          exec: (_cmd, cb) => cb(new Error('exec disabled')),
          execSync: () => {
            throw new Error('execSync disabled');
          },
        };
      }
      return require(id);
    };

    const mod = { exports: {} };
    vm.runInContext(
      detectLibcCode,
      vm.createContext({
        require: customRequire,
        process: customProcess,
        module: mod,
        exports: mod.exports,
        Buffer,
        Promise,
        Error,
      })
    );

    assert.equal(mod.exports.familySync(), MUSL, 'familySync() must detect musl from sharedObjects in report');
    assert.equal(mod.exports.isNonGlibcLinuxSync(), true, 'isNonGlibcLinuxSync() must be true for musl');
    // MUSL does not expose version in process.report -> returns null
    assert.equal(mod.exports.versionSync(), null, 'versionSync() must be null for musl via report');
  }
}

// ============================================================================
// 5. In-Memory Caching & Sync/Async Parity
// ============================================================================
{
  assert.equal(GLIBC, 'glibc');
  assert.equal(MUSL, 'musl');

  const syncFam = familySync();
  const asyncFam = await family();
  assert.equal(syncFam, asyncFam, 'familySync() must match await family()');

  const syncVer = versionSync();
  const asyncVer = await version();
  assert.equal(syncVer, asyncVer, 'versionSync() must match await version()');

  const syncNonGlibc = isNonGlibcLinuxSync();
  const asyncNonGlibc = await isNonGlibcLinux();
  assert.equal(syncNonGlibc, asyncNonGlibc, 'isNonGlibcLinuxSync() must match await isNonGlibcLinux()');
}

console.log('Contract verified: all detect-libc configuration, platform guard, and fallback assertions passed.');