scip-query 0.19.4 → 0.19.6

package/scripts/build-scip-windows.mjs

@@ -1,78 +1,197 @@
 #!/usr/bin/env node
 import { execFileSync } from 'node:child_process';
-import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  createWindowsSidecarProvenance,
+  DEFAULT_SCIP_REPOSITORY,
+  DEFAULT_SCIP_TAG,
+  PINNED_GO_VERSION,
+  verifyWindowsSidecarProvenance,
+  WINDOWS_SIDECAR_BUILD,
+  WINDOWS_SIDECAR_PROVENANCE_FILE,
+  WINDOWS_SIDECAR_TARGETS,
+} from './scip-windows-provenance.mjs';
 
-const SCIP_VERSION = process.env.SCIP_VERSION ?? 'v0.8.1';
-const SCIP_REPO_URL = process.env.SCIP_REPO_URL ?? 'https://github.com/scip-code/scip.git';
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const VENDOR_DIR = join(ROOT, 'packages', 'scip-windows');
 
-const TARGETS = [
-  { goarch: 'amd64', packageArch: 'x64' },
-  { goarch: 'arm64', packageArch: 'arm64' },
-];
+export function buildScipWindowsSidecar(
+  {
+    root = ROOT,
+    sourceRepository = process.env.SCIP_REPO_URL ?? DEFAULT_SCIP_REPOSITORY,
+    sourceTag = process.env.SCIP_VERSION ?? DEFAULT_SCIP_TAG,
+    expectedGoVersion = process.env.SCIP_GO_VERSION ?? PINNED_GO_VERSION,
+  } = {},
+  runtime = createBuildRuntime(),
+) {
+  const sidecarDir = join(root, 'packages', 'scip-windows');
+  const sidecarPackage = JSON.parse(runtime.readFile(join(sidecarDir, 'package.json'), 'utf8'));
+  runtime.assertAvailable('git');
+  runtime.assertAvailable('go');
 
-function run(binary, args, options = {}) {
-  console.log(`$ ${binary} ${args.join(' ')}`);
-  execFileSync(binary, args, {
-    stdio: 'inherit',
-    ...options,
-  });
-}
-
-function assertAvailable(binary) {
-  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const workDir = runtime.makeTempDirectory(join(runtime.tempDirectory(), 'scip-query-scip-'));
   try {
-    execFileSync(probe, [binary], { stdio: 'ignore' });
-  } catch {
-    throw new Error(`Required command not found on PATH: ${binary}`);
-  }
-}
+    const checkoutDir = join(workDir, 'scip');
+    const artifactDir = join(workDir, 'artifacts');
+    runtime.mkdir(artifactDir);
+
+    const goVersion = parseGoVersion(
+      runtime.run('go', ['version'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }),
+    );
+    if (goVersion !== expectedGoVersion) {
+      throw new Error(
+        `Go toolchain mismatch: expected ${expectedGoVersion}, received ${goVersion}. ` +
+          `Install the pinned toolchain or intentionally update the provenance contract.`,
+      );
+    }
 
-assertAvailable('git');
-assertAvailable('go');
+    runtime.run('git', ['clone', '--depth', '1', '--branch', sourceTag, sourceRepository, checkoutDir], {
+      stdio: 'inherit',
+    });
+    const sourceCommit = runtime
+      .run('git', ['rev-parse', 'HEAD'], {
+        cwd: checkoutDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      .trim();
+
+    runtime.copyFile(join(checkoutDir, 'LICENSE'), join(artifactDir, 'LICENSE.scip'));
+    runtime.writeFile(
+      join(artifactDir, 'README.md'),
+      renderSidecarReadme({ sourceRepository, sourceTag, sourceCommit, goVersion }),
+    );
 
-const workDir = mkdtempSync(join(tmpdir(), 'scip-query-scip-'));
+    for (const target of WINDOWS_SIDECAR_TARGETS) {
+      const outputPath = join(artifactDir, target.filename);
+      runtime.run('go', ['build', ...WINDOWS_SIDECAR_BUILD.flags, '-o', outputPath, WINDOWS_SIDECAR_BUILD.package], {
+        cwd: checkoutDir,
+        env: {
+          ...process.env,
+          ...WINDOWS_SIDECAR_BUILD.environment,
+          GOARCH: target.goarch,
+        },
+        stdio: 'inherit',
+      });
+    }
 
-try {
-  const checkoutDir = join(workDir, 'scip');
-  run('git', ['clone', '--depth', '1', '--branch', SCIP_VERSION, SCIP_REPO_URL, checkoutDir]);
-  mkdirSync(VENDOR_DIR, { recursive: true });
-  copyFileSync(join(checkoutDir, 'LICENSE'), join(VENDOR_DIR, 'LICENSE.scip'));
-  writeFileSync(
-    join(VENDOR_DIR, 'README.md'),
-    [
-      '# Windows scip.exe npm sidecar',
-      '',
-      `These binaries are built from ${SCIP_REPO_URL} at ${SCIP_VERSION}.`,
-      'They are bundled in the OS-gated `scip-query-scip-windows` npm package. The main',
-      '`scip-query` package declares that sidecar as an optional dependency, so npm',
-      'installs it automatically on Windows and `reindex` works without Go or WSL.',
-      '',
-      'Run `npm run build:scip-windows` to rebuild the binaries. Publishing the main',
-      'package verifies the version pin, builds missing binaries, and publishes the',
-      'matching sidecar first.',
-      '',
-    ].join('\n'),
-  );
+    const manifest = createWindowsSidecarProvenance({
+      sidecarDir: artifactDir,
+      packageName: sidecarPackage.name,
+      packageVersion: sidecarPackage.version,
+      sourceRepository,
+      sourceTag,
+      sourceCommit,
+      goVersion,
+      readFile: runtime.readFile,
+    });
+    runtime.writeFile(join(artifactDir, WINDOWS_SIDECAR_PROVENANCE_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
 
-  for (const target of TARGETS) {
-    const outputPath = join(VENDOR_DIR, `scip-win32-${target.packageArch}.exe`);
-    mkdirSync(VENDOR_DIR, { recursive: true });
+    for (const file of [
+      'LICENSE.scip',
+      'README.md',
+      ...WINDOWS_SIDECAR_TARGETS.map((target) => target.filename),
+      WINDOWS_SIDECAR_PROVENANCE_FILE,
+    ]) {
+      runtime.promoteFile(join(artifactDir, file), join(sidecarDir, file));
+    }
 
-    run('go', ['build', '-trimpath', '-ldflags=-s -w', '-o', outputPath, './cmd/scip'], {
-      cwd: checkoutDir,
-      env: {
-        ...process.env,
-        CGO_ENABLED: '0',
-        GOOS: 'windows',
-        GOARCH: target.goarch,
-      },
+    const verified = verifyWindowsSidecarProvenance({
+      sidecarDir,
+      expectedSourceRepository: sourceRepository,
+      expectedSourceTag: sourceTag,
+      expectedGoVersion,
+      readFile: runtime.readFile,
     });
+    runtime.log(
+      `Built and verified ${verified.package.name}@${verified.package.version} from ${sourceTag} (${sourceCommit.slice(0, 12)}).`,
+    );
+    return verified;
+  } finally {
+    runtime.removeTree(workDir);
+  }
+}
+
+export function createBuildRuntime() {
+  return {
+    assertAvailable(binary) {
+      const probe = process.platform === 'win32' ? 'where' : 'which';
+      try {
+        execFileSync(probe, [binary], { stdio: 'ignore' });
+      } catch {
+        throw new Error(`Required command not found on PATH: ${binary}`);
+      }
+    },
+    copyFile: copyFileSync,
+    log: console.log,
+    makeTempDirectory: mkdtempSync,
+    mkdir(path) {
+      mkdirSync(path, { recursive: true });
+    },
+    promoteFile(source, destination) {
+      mkdirSync(dirname(destination), { recursive: true });
+      const staging = join(dirname(destination), `.${basename(destination)}.${process.pid}.tmp`);
+      try {
+        copyFileSync(source, staging);
+        renameSync(staging, destination);
+      } finally {
+        rmSync(staging, { force: true });
+      }
+    },
+    readFile: readFileSync,
+    removeTree(path) {
+      rmSync(path, { recursive: true, force: true });
+    },
+    run(binary, args, options = {}) {
+      console.log(`$ ${binary} ${args.join(' ')}`);
+      return execFileSync(binary, args, options);
+    },
+    tempDirectory: tmpdir,
+    writeFile: writeFileSync,
+  };
+}
+
+export function parseGoVersion(output) {
+  const match = /\b(go\d+(?:\.\d+){1,2}(?:[a-z0-9.-]*)?)\b/.exec(String(output));
+  if (!match) {
+    throw new Error(`Could not parse Go toolchain version from: ${String(output).trim()}`);
+  }
+  return match[1];
+}
+
+export function renderSidecarReadme({ sourceRepository, sourceTag, sourceCommit, goVersion }) {
+  return [
+    '# Windows scip.exe npm sidecar',
+    '',
+    `These binaries are built from ${sourceRepository} at ${sourceTag}`,
+    `(${sourceCommit}) with ${goVersion}.`,
+    'They are bundled in the OS-gated `scip-query-scip-windows` npm package. The main',
+    '`scip-query` package declares that sidecar as an optional dependency, so npm',
+    'installs it automatically on Windows and `reindex` works without Go or WSL.',
+    '',
+    `\`${WINDOWS_SIDECAR_PROVENANCE_FILE}\` binds the package version and exact source,`,
+    'toolchain, build flags, target machine, file size, and SHA-256 for both binaries.',
+    'Build, pack, and publish checks reject missing or mismatched evidence.',
+    '',
+    'Run `npm run build:scip-windows` to rebuild the binaries and provenance manifest.',
+    'Review and commit the manifest change before release. Publishing the main package',
+    'verifies the version pin and the complete sidecar provenance before any registry',
+    'decision.',
+    '',
+  ].join('\n');
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  try {
+    buildScipWindowsSidecar();
+  } catch (error) {
+    console.error(`Windows sidecar build FAILED:\n  - ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
   }
-} finally {
-  rmSync(workDir, { recursive: true, force: true });
 }

package/scripts/scip-windows-provenance.mjs

@@ -0,0 +1,364 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const WINDOWS_SIDECAR_PROVENANCE_KIND = 'scip-query-windows-sidecar-provenance';
+export const WINDOWS_SIDECAR_PROVENANCE_VERSION = 1;
+export const WINDOWS_SIDECAR_PROVENANCE_FILE = 'provenance.json';
+export const DEFAULT_SCIP_REPOSITORY = 'https://github.com/scip-code/scip.git';
+export const DEFAULT_SCIP_TAG = 'v0.8.1';
+export const PINNED_GO_VERSION = 'go1.26.4';
+
+export const WINDOWS_SIDECAR_BUILD = Object.freeze({
+  command: 'go build',
+  package: './cmd/scip',
+  flags: Object.freeze(['-trimpath', '-ldflags=-s -w']),
+  environment: Object.freeze({
+    CGO_ENABLED: '0',
+    GOOS: 'windows',
+  }),
+});
+
+export const WINDOWS_SIDECAR_TARGETS = Object.freeze([
+  Object.freeze({
+    goarch: 'amd64',
+    packageArch: 'x64',
+    filename: 'scip-win32-x64.exe',
+    peMachine: 'AMD64',
+    peMachineCode: 0x8664,
+  }),
+  Object.freeze({
+    goarch: 'arm64',
+    packageArch: 'arm64',
+    filename: 'scip-win32-arm64.exe',
+    peMachine: 'ARM64',
+    peMachineCode: 0xaa64,
+  }),
+]);
+
+export class WindowsSidecarProvenanceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'WindowsSidecarProvenanceError';
+    this.code = code;
+  }
+}
+
+export function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function inspectPortableExecutable(bytes, filename = '<binary>') {
+  if (!Buffer.isBuffer(bytes) || bytes.length < 0x40) {
+    throw provenanceError('malformed-binary', `${filename} is too short to be a PE executable.`);
+  }
+  if (bytes[0] !== 0x4d || bytes[1] !== 0x5a) {
+    throw provenanceError('malformed-binary', `${filename} is missing the DOS MZ signature.`);
+  }
+
+  const peOffset = bytes.readUInt32LE(0x3c);
+  if (!Number.isSafeInteger(peOffset) || peOffset < 0x40 || peOffset + 26 > bytes.length) {
+    throw provenanceError('malformed-binary', `${filename} has an invalid PE header offset.`);
+  }
+  if (
+    bytes[peOffset] !== 0x50 ||
+    bytes[peOffset + 1] !== 0x45 ||
+    bytes[peOffset + 2] !== 0 ||
+    bytes[peOffset + 3] !== 0
+  ) {
+    throw provenanceError('malformed-binary', `${filename} is missing the PE signature.`);
+  }
+
+  const machineCode = bytes.readUInt16LE(peOffset + 4);
+  const target = WINDOWS_SIDECAR_TARGETS.find((candidate) => candidate.peMachineCode === machineCode);
+  if (!target) {
+    throw provenanceError(
+      'wrong-architecture',
+      `${filename} has unsupported PE machine 0x${machineCode.toString(16).padStart(4, '0')}.`,
+    );
+  }
+
+  const optionalHeaderMagic = bytes.readUInt16LE(peOffset + 24);
+  if (optionalHeaderMagic !== 0x20b) {
+    throw provenanceError(
+      'malformed-binary',
+      `${filename} is not a PE32+ executable (optional-header magic 0x${optionalHeaderMagic
+        .toString(16)
+        .padStart(4, '0')}).`,
+    );
+  }
+
+  return {
+    peMachine: target.peMachine,
+    peMachineCode: `0x${machineCode.toString(16).padStart(4, '0')}`,
+  };
+}
+
+export function inspectWindowsSidecarBinary(file, readFile = readFileSync) {
+  const bytes = readFile(file);
+  const pe = inspectPortableExecutable(bytes, file);
+  return {
+    size: bytes.length,
+    sha256: sha256(bytes),
+    ...pe,
+  };
+}
+
+export function createWindowsSidecarProvenance({
+  sidecarDir,
+  packageName,
+  packageVersion,
+  sourceRepository = DEFAULT_SCIP_REPOSITORY,
+  sourceTag = DEFAULT_SCIP_TAG,
+  sourceCommit,
+  goVersion = PINNED_GO_VERSION,
+  readFile = readFileSync,
+}) {
+  if (!isCommit(sourceCommit)) {
+    throw provenanceError('invalid-build-input', `Source commit must be a full 40-character Git commit.`);
+  }
+
+  return {
+    kind: WINDOWS_SIDECAR_PROVENANCE_KIND,
+    schemaVersion: WINDOWS_SIDECAR_PROVENANCE_VERSION,
+    package: {
+      name: packageName,
+      version: packageVersion,
+    },
+    source: {
+      repository: sourceRepository,
+      tag: sourceTag,
+      commit: sourceCommit,
+    },
+    toolchain: {
+      goVersion,
+    },
+    build: {
+      command: WINDOWS_SIDECAR_BUILD.command,
+      package: WINDOWS_SIDECAR_BUILD.package,
+      flags: [...WINDOWS_SIDECAR_BUILD.flags],
+      environment: {
+        ...WINDOWS_SIDECAR_BUILD.environment,
+      },
+    },
+    binaries: WINDOWS_SIDECAR_TARGETS.map((target) => {
+      const inspected = inspectWindowsSidecarBinary(join(sidecarDir, target.filename), readFile);
+      if (inspected.peMachine !== target.peMachine) {
+        throw provenanceError(
+          'wrong-architecture',
+          `${target.filename} declares ${target.packageArch} but contains ${inspected.peMachine}.`,
+        );
+      }
+      return {
+        filename: target.filename,
+        target: {
+          goos: 'windows',
+          goarch: target.goarch,
+          packageArch: target.packageArch,
+        },
+        size: inspected.size,
+        sha256: inspected.sha256,
+        peMachine: inspected.peMachine,
+        peMachineCode: inspected.peMachineCode,
+      };
+    }),
+  };
+}
+
+export function verifyWindowsSidecarProvenance({
+  sidecarDir,
+  expectedSourceRepository = DEFAULT_SCIP_REPOSITORY,
+  expectedSourceTag = DEFAULT_SCIP_TAG,
+  expectedGoVersion = PINNED_GO_VERSION,
+  readFile = readFileSync,
+}) {
+  const packageRecord = parseJsonFile(join(sidecarDir, 'package.json'), 'sidecar package', readFile);
+  const manifest = parseJsonFile(
+    join(sidecarDir, WINDOWS_SIDECAR_PROVENANCE_FILE),
+    'sidecar provenance manifest',
+    readFile,
+  );
+  const decoded = decodeWindowsSidecarProvenance(manifest);
+
+  requireEqual(decoded.package.name, packageRecord.name, 'package name');
+  requireEqual(decoded.package.version, packageRecord.version, 'package version');
+  requireEqual(decoded.source.repository, expectedSourceRepository, 'SCIP source repository');
+  requireEqual(decoded.source.tag, expectedSourceTag, 'SCIP source tag');
+  requireEqual(decoded.toolchain.goVersion, expectedGoVersion, 'pinned Go version');
+  requireBuildContract(decoded.build);
+
+  const entries = new Map(decoded.binaries.map((binary) => [binary.filename, binary]));
+  for (const target of WINDOWS_SIDECAR_TARGETS) {
+    const expected = entries.get(target.filename);
+    if (!expected) {
+      throw provenanceError('malformed-manifest', `Manifest is missing ${target.filename}.`);
+    }
+
+    requireEqual(expected.target.goos, 'windows', `${target.filename} GOOS`);
+    requireEqual(expected.target.goarch, target.goarch, `${target.filename} GOARCH`);
+    requireEqual(expected.target.packageArch, target.packageArch, `${target.filename} package arch`);
+    requireEqual(expected.peMachine, target.peMachine, `${target.filename} PE machine`);
+    requireEqual(
+      expected.peMachineCode,
+      `0x${target.peMachineCode.toString(16).padStart(4, '0')}`,
+      `${target.filename} PE machine code`,
+    );
+
+    let actual;
+    try {
+      actual = inspectWindowsSidecarBinary(join(sidecarDir, target.filename), readFile);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        throw provenanceError('missing-binary', `${target.filename} is missing.`);
+      }
+      throw error;
+    }
+    requireEqual(actual.peMachine, target.peMachine, `${target.filename} actual PE machine`);
+    requireEqual(actual.size, expected.size, `${target.filename} byte size`);
+    requireEqual(actual.sha256, expected.sha256, `${target.filename} SHA-256`);
+  }
+
+  return decoded;
+}
+
+export function decodeWindowsSidecarProvenance(value) {
+  const record = requireRecord(value, 'manifest');
+  requireEqual(record.kind, WINDOWS_SIDECAR_PROVENANCE_KIND, 'manifest kind');
+  if (record.schemaVersion !== WINDOWS_SIDECAR_PROVENANCE_VERSION) {
+    throw provenanceError(
+      'unsupported-manifest',
+      `Unsupported Windows sidecar provenance schema ${String(record.schemaVersion)}; expected ${WINDOWS_SIDECAR_PROVENANCE_VERSION}.`,
+    );
+  }
+
+  const packageRecord = requireRecord(record.package, 'package');
+  const source = requireRecord(record.source, 'source');
+  const toolchain = requireRecord(record.toolchain, 'toolchain');
+  const build = requireRecord(record.build, 'build');
+  if (!Array.isArray(record.binaries) || record.binaries.length !== WINDOWS_SIDECAR_TARGETS.length) {
+    throw provenanceError(
+      'malformed-manifest',
+      `binaries must contain exactly ${WINDOWS_SIDECAR_TARGETS.length} entries.`,
+    );
+  }
+
+  const binaries = record.binaries.map((value, index) => {
+    const binary = requireRecord(value, `binaries[${index}]`);
+    const target = requireRecord(binary.target, `binaries[${index}].target`);
+    requireNonEmptyString(binary.filename, `binaries[${index}].filename`);
+    requireNonEmptyString(target.goos, `binaries[${index}].target.goos`);
+    requireNonEmptyString(target.goarch, `binaries[${index}].target.goarch`);
+    requireNonEmptyString(target.packageArch, `binaries[${index}].target.packageArch`);
+    requirePositiveSafeInteger(binary.size, `binaries[${index}].size`);
+    if (typeof binary.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(binary.sha256)) {
+      throw provenanceError('malformed-manifest', `binaries[${index}].sha256 must be lowercase SHA-256.`);
+    }
+    requireNonEmptyString(binary.peMachine, `binaries[${index}].peMachine`);
+    if (typeof binary.peMachineCode !== 'string' || !/^0x[a-f0-9]{4}$/.test(binary.peMachineCode)) {
+      throw provenanceError(
+        'malformed-manifest',
+        `binaries[${index}].peMachineCode must be a four-digit hexadecimal code.`,
+      );
+    }
+    return binary;
+  });
+
+  requireNonEmptyString(packageRecord.name, 'package.name');
+  requireNonEmptyString(packageRecord.version, 'package.version');
+  requireNonEmptyString(source.repository, 'source.repository');
+  requireNonEmptyString(source.tag, 'source.tag');
+  if (!isCommit(source.commit)) {
+    throw provenanceError('malformed-manifest', `source.commit must be a full 40-character Git commit.`);
+  }
+  requireNonEmptyString(toolchain.goVersion, 'toolchain.goVersion');
+  requireNonEmptyString(build.command, 'build.command');
+  requireNonEmptyString(build.package, 'build.package');
+  if (!Array.isArray(build.flags) || !build.flags.every((flag) => typeof flag === 'string')) {
+    throw provenanceError('malformed-manifest', `build.flags must be an array of strings.`);
+  }
+  requireRecord(build.environment, 'build.environment');
+
+  const filenames = binaries.map((binary) => binary.filename);
+  if (new Set(filenames).size !== filenames.length) {
+    throw provenanceError('malformed-manifest', `binaries contains duplicate filenames.`);
+  }
+
+  return {
+    ...record,
+    package: packageRecord,
+    source,
+    toolchain,
+    build,
+    binaries,
+  };
+}
+
+function requireBuildContract(build) {
+  requireEqual(build.command, WINDOWS_SIDECAR_BUILD.command, 'build command');
+  requireEqual(build.package, WINDOWS_SIDECAR_BUILD.package, 'build package');
+  if (JSON.stringify(build.flags) !== JSON.stringify(WINDOWS_SIDECAR_BUILD.flags)) {
+    throw provenanceError(
+      'build-input-mismatch',
+      `Build flags do not match the pinned contract (${WINDOWS_SIDECAR_BUILD.flags.join(' ')}).`,
+    );
+  }
+  const environment = requireRecord(build.environment, 'build.environment');
+  requireEqual(environment.CGO_ENABLED, WINDOWS_SIDECAR_BUILD.environment.CGO_ENABLED, 'CGO_ENABLED');
+  requireEqual(environment.GOOS, WINDOWS_SIDECAR_BUILD.environment.GOOS, 'GOOS');
+}
+
+function parseJsonFile(file, label, readFile) {
+  let bytes;
+  try {
+    bytes = readFile(file);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw provenanceError(
+        label === 'sidecar provenance manifest' ? 'missing-manifest' : 'missing-package',
+        `${label} is missing at ${file}.`,
+      );
+    }
+    throw error;
+  }
+  try {
+    return JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw provenanceError('malformed-manifest', `${label} is not valid JSON at ${file}.`);
+  }
+}
+
+function requireRecord(value, field) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw provenanceError('malformed-manifest', `${field} must be an object.`);
+  }
+  return value;
+}
+
+function requireNonEmptyString(value, field) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw provenanceError('malformed-manifest', `${field} must be a non-empty string.`);
+  }
+}
+
+function requirePositiveSafeInteger(value, field) {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+    throw provenanceError('malformed-manifest', `${field} must be a positive safe integer.`);
+  }
+}
+
+function requireEqual(actual, expected, field) {
+  if (actual !== expected) {
+    throw provenanceError(
+      'build-input-mismatch',
+      `${field} mismatch: expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}.`,
+    );
+  }
+}
+
+function isCommit(value) {
+  return typeof value === 'string' && /^[a-f0-9]{40}$/.test(value);
+}
+
+function provenanceError(code, message) {
+  return new WindowsSidecarProvenanceError(code, message);
+}

package/scripts/verify-scip-windows.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_SCIP_REPOSITORY,
+  DEFAULT_SCIP_TAG,
+  PINNED_GO_VERSION,
+  verifyWindowsSidecarProvenance,
+} from './scip-windows-provenance.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const sidecarDir = resolve(root, 'packages', 'scip-windows');
+
+try {
+  const manifest = verifyWindowsSidecarProvenance({
+    sidecarDir,
+    expectedSourceRepository: process.env.SCIP_REPO_URL ?? DEFAULT_SCIP_REPOSITORY,
+    expectedSourceTag: process.env.SCIP_VERSION ?? DEFAULT_SCIP_TAG,
+    expectedGoVersion: process.env.SCIP_GO_VERSION ?? PINNED_GO_VERSION,
+  });
+  console.log(
+    `Verified ${manifest.package.name}@${manifest.package.version}: ${manifest.source.tag} (${manifest.source.commit.slice(0, 12)}), ${manifest.toolchain.goVersion}, ${manifest.binaries.length} PE binaries.`,
+  );
+} catch (error) {
+  console.error(
+    `Windows sidecar provenance check FAILED:\n  - ${error instanceof Error ? error.message : String(error)}`,
+  );
+  process.exitCode = 1;
+}