workbite 0.1.19 → 0.1.20

package/lib/archive.js

@@ -1,334 +1,334 @@
-'use strict';
-// ZIP/TAR structural parsers reused from the StackBite npm bootstrapper (same
-// owner, proprietary): every member is bounded and checked before the OS tar
-// command sees the archive. WorkBite archives have no wrapping root directory.
-const fs = require('node:fs/promises');
-const { createReadStream, createWriteStream } = require('node:fs');
-const { createGunzip, createInflateRaw } = require('node:zlib');
-const { Transform, Writable } = require('node:stream');
-const { pipeline } = require('node:stream/promises');
-const { spawn } = require('node:child_process');
-const path = require('node:path');
-const { stripVTControlCharacters } = require('node:util');
-const { LIMITS, fail, memberPath } = require('./common');
-const utf8 = new TextDecoder('utf-8', { fatal: true });
-const crcTable = Uint32Array.from({ length: 256 }, (_, value) => {
-  for (let bit = 0; bit < 8; bit++) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
-  return value >>> 0;
-});
-const TOP_DIRECTORIES = Object.freeze(['workstack', 'stackbite', 'licenses']);
-const BUNDLE = 'bundle.json';
-
-async function readAt(file, offset, length) {
-  const bytes = Buffer.alloc(length);
-  const { bytesRead } = await file.read(bytes, 0, length, offset);
-  if (bytesRead !== length) fail('Truncated release archive');
-  return bytes;
-}
-// Top level is exactly workstack/ stackbite/ licenses/ and one bundle.json file; no links at all.
-function validateEntries(entries, windows) {
-  if (!entries.length || entries.length > LIMITS.members) fail('Invalid archive member count');
-  const names = new Map();
-  let expanded = 0, bundle = false;
-  for (const entry of entries) {
-    entry.name = memberPath(entry.name);
-    if (entry.kind !== 'file' && entry.kind !== 'directory') fail('Archive links and special members are not allowed');
-    const top = entry.name.split('/')[0];
-    if (entry.name === BUNDLE) {
-      if (entry.kind !== 'file') fail('bundle.json must be a regular file');
-      bundle = true;
-    } else if (!TOP_DIRECTORIES.includes(top) || (entry.name === top && entry.kind !== 'directory')) {
-      fail('Archive member is outside the WorkBite layout');
-    }
-    const key = windows ? entry.name.toLowerCase() : entry.name;
-    if (names.has(key)) fail('Duplicate archive member');
-    names.set(key, entry);
-    expanded += entry.size;
-    if (entry.size < 0 || entry.size > LIMITS.member || expanded > LIMITS.expanded) fail('Archive expansion exceeds limit');
-  }
-  if (!bundle) fail('Archive has no bundle.json');
-  for (const entry of entries) {
-    for (let parent = path.posix.dirname(entry.name); parent !== '.'; parent = path.posix.dirname(parent)) {
-      const ancestor = names.get(windows ? parent.toLowerCase() : parent);
-      if (ancestor && ancestor.kind !== 'directory') fail('Archive file is another member parent');
-    }
-  }
-  return entries;
-}
-async function zipEntries(archive) {
-  const file = await fs.open(archive, 'r');
-  const signal = AbortSignal.timeout(LIMITS.timeout);
-  try {
-    const size = (await file.stat()).size;
-    const tailStart = Math.max(0, size - 65557);
-    const tail = await readAt(file, tailStart, size - tailStart);
-    const end = tail.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
-    if (end < 0 || end + 22 > tail.length) fail('Invalid ZIP directory');
-    const count = tail.readUInt16LE(end + 10), directorySize = tail.readUInt32LE(end + 12), offset = tail.readUInt32LE(end + 16);
-    if (tail.readUInt16LE(end + 4) || tail.readUInt16LE(end + 6) || tail.readUInt16LE(end + 8) !== count
-        || count === 65535 || count > LIMITS.members || directorySize > 16 * 1024 * 1024
-        || offset + directorySize !== tailStart + end || end + 22 + tail.readUInt16LE(end + 20) !== tail.length) fail('Unsafe ZIP directory');
-    const central = await readAt(file, offset, directorySize);
-    const entries = [], ranges = [];
-    let position = 0, totalExpanded = 0;
-    for (let index = 0; index < count; index++) {
-      signal.throwIfAborted();
-      if (position + 46 > central.length || central.readUInt32LE(position) !== 0x02014b50) fail('Invalid ZIP member');
-      const flags = central.readUInt16LE(position + 8), method = central.readUInt16LE(position + 10);
-      const compressed = central.readUInt32LE(position + 20), expanded = central.readUInt32LE(position + 24);
-      totalExpanded += expanded;
-      if (totalExpanded > LIMITS.expanded) fail('ZIP total expansion exceeds limit');
-      const nameSize = central.readUInt16LE(position + 28), extraSize = central.readUInt16LE(position + 30), commentSize = central.readUInt16LE(position + 32);
-      const localOffset = central.readUInt32LE(position + 42), mode = central.readUInt32LE(position + 38) >>> 16;
-      if (!nameSize || nameSize > 1024 || position + 46 + nameSize + extraSize + commentSize > central.length
-          || central.readUInt16LE(position + 34) || (flags & ~0x080e) || ![0, 8].includes(method)
-          || expanded > LIMITS.member || ![0, 0o100000, 0o040000].includes(mode & 0o170000) || (mode & 0o7000)) fail('Unsupported ZIP member');
-      const rawName = central.subarray(position + 46, position + 46 + nameSize);
-      if (!(flags & 0x0800) && rawName.some(value => value > 127)) fail('Ambiguous ZIP filename encoding');
-      const name = utf8.decode(rawName);
-      const directory = name.endsWith('/');
-      if (directory && (expanded || compressed)) fail('Invalid ZIP directory member');
-      const directoryMode = (mode & 0o170000) === 0o040000 || !!(central.readUInt32LE(position + 38) & 16);
-      if (directoryMode && !directory) fail('ZIP directory identity mismatch');
-      const local = await readAt(file, localOffset, 30);
-      const localNameSize = local.readUInt16LE(26), localExtraSize = local.readUInt16LE(28);
-      const dataStart = localOffset + 30 + localNameSize + localExtraSize;
-      if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== method
-          || localNameSize !== nameSize || dataStart + compressed > offset
-          || !(await readAt(file, localOffset + 30, localNameSize)).equals(rawName)) fail('ZIP local/central identity mismatch');
-      if (!(flags & 8) && (local.readUInt32LE(14) !== central.readUInt32LE(position + 16)
-          || local.readUInt32LE(18) !== compressed || local.readUInt32LE(22) !== expanded)) fail('ZIP local size mismatch');
-      if (!directory) {
-        // Bound the actual inflated bytes, not only the central-directory claim,
-        // before handing the same archive to the native extraction command.
-        if (method === 0 && compressed !== expanded) fail('Invalid stored ZIP size');
-        let actualSize = 0, crc = 0xffffffff;
-        const sink = new Writable({ write(chunk, encoding, callback) {
-          actualSize += chunk.length;
-          if (actualSize > expanded) return callback(new Error('ZIP expansion exceeds declared size'));
-          for (const byte of chunk) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 255];
-          callback();
-        } });
-        if (compressed) {
-          const input = createReadStream(archive, { start: dataStart, end: dataStart + compressed - 1 });
-          if (method === 8) await pipeline(input, createInflateRaw(), sink, { signal });
-          else await pipeline(input, sink, { signal });
-        }
-        if (actualSize !== expanded || ((crc ^ 0xffffffff) >>> 0) !== central.readUInt32LE(position + 16)) fail('ZIP content size/CRC mismatch');
-      }
-      // Reject Unicode-path/ZIP64 extra fields: native tar must use the same name
-      // and sizes checked here, without a second interpretation of this entry.
-      for (const extra of [central.subarray(position + 46 + nameSize, position + 46 + nameSize + extraSize),
-        await readAt(file, localOffset + 30 + localNameSize, localExtraSize)]) {
-        for (let at = 0; at < extra.length;) {
-          if (at + 4 > extra.length) fail('Invalid ZIP extra field');
-          const kind = extra.readUInt16LE(at), length = extra.readUInt16LE(at + 2);
-          if (![0x5455, 0x7875].includes(kind) || at + 4 + length > extra.length) fail('Unsupported ZIP extension');
-          at += 4 + length;
-        }
-      }
-      ranges.push([localOffset, dataStart + compressed]);
-      entries.push({ name, kind: directory ? 'directory' : 'file', size: expanded });
-      position += 46 + nameSize + extraSize + commentSize;
-    }
-    if (position !== central.length) fail('Extra ZIP directory records');
-    ranges.sort((a, b) => a[0] - b[0]);
-    if (ranges.some((range, index) => index && range[0] < ranges[index - 1][1])) fail('Overlapping ZIP members');
-    return entries;
-  } finally { await file.close(); }
-}
-function tarNumber(bytes) {
-  const value = bytes.toString('ascii').replace(/\0.*$/, '').trim();
-  if (value && !/^[0-7]+$/.test(value)) fail('Unsupported TAR numeric field');
-  const result = Number.parseInt(value || '0', 8);
-  if (!Number.isSafeInteger(result)) fail('Invalid TAR size');
-  return result;
-}
-function tarText(bytes) { return utf8.decode(bytes.subarray(0, bytes.indexOf(0) < 0 ? bytes.length : bytes.indexOf(0))); }
-function paxFields(bytes) {
-  const fields = {};
-  for (let offset = 0; offset < bytes.length;) {
-    const space = bytes.indexOf(32, offset);
-    if (space < 0 || !/^\d+$/.test(bytes.subarray(offset, space).toString())) fail('Invalid TAR PAX length');
-    const length = Number(bytes.subarray(offset, space).toString());
-    if (!Number.isSafeInteger(length) || length <= space - offset + 2 || offset + length > bytes.length || bytes[offset + length - 1] !== 10) fail('Invalid TAR PAX record');
-    const record = utf8.decode(bytes.subarray(space + 1, offset + length - 1));
-    const equal = record.indexOf('=');
-    const key = record.slice(0, equal), value = record.slice(equal + 1);
-    if (equal < 1 || !['path', 'linkpath', 'mtime', 'atime', 'ctime'].includes(key) || Object.hasOwn(fields, key)) fail('Unsupported TAR PAX field');
-    fields[key] = value;
-    offset += length;
-  }
-  return fields;
-}
-async function tarEntries(archive) {
-  const file = await fs.open(archive, 'r');
-  try {
-    const total = (await file.stat()).size;
-    const entries = [];
-    let offset = 0, pax = null, headers = 0;
-    while (offset + 512 <= total) {
-      const header = await readAt(file, offset, 512);
-      offset += 512;
-      if (header.every(value => value === 0)) {
-        if (pax || offset + 512 > total) fail('Truncated TAR trailer');
-        for (let at = offset; at < total; at += 65536) {
-          if (!(await readAt(file, at, Math.min(65536, total - at))).every(value => value === 0)) fail('Extra TAR payload after trailer');
-        }
-        return entries;
-      }
-      if (++headers > LIMITS.members * 2) fail('Too many TAR headers');
-      if (header.subarray(257, 263).toString('ascii') !== 'ustar\0') fail('Unsupported TAR header format');
-      let checksum = 0;
-      for (let index = 0; index < 512; index++) checksum += index >= 148 && index < 156 ? 32 : header[index];
-      if (checksum !== tarNumber(header.subarray(148, 156))) fail('Invalid TAR checksum');
-      const size = tarNumber(header.subarray(124, 136));
-      const kind = String.fromCharCode(header[156]);
-      if (size > (kind === 'x' ? 65536 : LIMITS.member) || offset + Math.ceil(size / 512) * 512 > total
-          || tarNumber(header.subarray(100, 108)) & 0o7000) fail('Unsafe TAR size or permissions');
-      if (kind === 'x') {
-        if (pax) fail('Chained TAR PAX headers');
-        pax = paxFields(await readAt(file, offset, size));
-      } else {
-        if (!['\0', '0', '5', '2'].includes(kind) || (kind !== '0' && kind !== '\0' && size)) fail('Unsupported TAR member');
-        const prefix = tarText(header.subarray(345, 500));
-        const name = pax && Object.hasOwn(pax, 'path') ? pax.path : (prefix ? prefix + '/' : '') + tarText(header.subarray(0, 100));
-        entries.push({ name, kind: kind === '5' ? 'directory' : kind === '2' ? 'link' : 'file', size,
-          link: pax && Object.hasOwn(pax, 'linkpath') ? pax.linkpath : tarText(header.subarray(157, 257)) });
-        pax = null;
-      }
-      offset += Math.ceil(size / 512) * 512;
-    }
-    fail('TAR trailer is missing');
-  } finally { await file.close(); }
-}
-async function boundedGunzip(archive, destination) {
-  let size = 0;
-  const bounded = new Transform({ transform(chunk, encoding, callback) {
-    size += chunk.length;
-    callback(size > LIMITS.expanded ? new Error('TAR expansion exceeds limit') : null, chunk);
-  } });
-  await pipeline(createReadStream(archive), createGunzip(), bounded,
-    createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal: AbortSignal.timeout(LIMITS.timeout) });
-}
-function nativeTar() {
-  return process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : '/usr/bin/tar';
-}
-// Diagnostics are untrusted subprocess output or paths. Never echo URLs, auth
-// headers, credential assignments or terminal control sequences back to a terminal.
-function diagnosticText(value, maximum = 4096) {
-  return stripVTControlCharacters(String(value))
-    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
-    .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/gi, '[redacted URL]')
-    .replace(/\b(?:authorization|proxy-authorization|cookie|set-cookie)\s*[:=].*/gi, '[redacted credentials]')
-    .replace(/\b(?:bearer|basic)\s+\S+/gi, '[redacted credentials]')
-    .replace(/\b([\w.-]*(?:token|password|passwd|secret|credential|api[_-]?key)[\w.-]*)\s*[:=]\s*(?:"[^"]*(?:"|$)|'[^']*(?:'|$)|[^\s]*)/gi, '$1=[redacted]')
-    .slice(0, maximum);
-}
-function extractionError(reason, destination, { code = null, signal = null, stderr = '', truncated = false, spawnCode } = {}) {
-  const detail = diagnosticText(stderr);
-  const permission = /permission denied|operation not permitted|read-only file system|access is denied/i.test(detail)
-    || ['EACCES', 'EPERM', 'EROFS'].includes(spawnCode);
-  const storage = /no space left|disk (?:is )?full|quota exceeded|stale file handle|input\/output error/i.test(detail)
-    || ['ENOSPC', 'EDQUOT', 'ESTALE', 'EIO'].includes(spawnCode);
-  const hint = permission ? ' Check destination permissions, mount options and NFS access.'
-    : storage ? ' Check free space, quota and filesystem/NFS health.' : '';
-  const error = new Error(`${reason} (exit code: ${code ?? 'none'}, signal: ${diagnosticText(signal ?? 'none', 64)}${spawnCode ? `, spawn: ${diagnosticText(spawnCode, 64)}` : ''}); destination: ${diagnosticText(path.resolve(destination))}.${hint}${detail ? ` stderr: ${detail}${truncated ? ' [truncated]' : ''}` : ''}`);
-  error.exitCode = code;
-  error.signal = signal;
-  if (spawnCode) error.code = spawnCode;
-  return error;
-}
-async function extractArchive(archive, destination, spec, { spawnImpl = spawn, timeout = LIMITS.timeout } = {}) {
-  let input = archive;
-  const windows = spec.asset.endsWith('.zip');
-  if (!windows) { input = archive + '.tar'; await boundedGunzip(archive, input); }
-  const entries = windows ? await zipEntries(input) : await tarEntries(input);
-  validateEntries(entries, windows);
-  await new Promise((resolve, reject) => {
-    let child, timer, closeTimer, errorBytes = 0, captured = 0, stopped, processCode;
-    let started = false, settled = false;
-    const chunks = [];
-    const details = (code, signal, spawnCode) => ({ code, signal, spawnCode,
-      stderr: Buffer.concat(chunks).toString('utf8'), truncated: errorBytes > 4096 });
-    const finish = (error, unknown = false) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      clearTimeout(closeTimer);
-      if (child) {
-        child.removeListener('spawn', onSpawn);
-        child.removeListener('error', onError);
-        child.removeListener('close', onClose);
-        child.stderr.removeListener('data', onData);
-        // A late kill error must remain handled without retaining this attempt's
-        // callbacks or changing its already settled cleanup authority.
-        child.on('error', () => {});
-        if (unknown) { child.unref?.(); child.stderr.destroy(); }
-        child = undefined;
-      }
-      chunks.length = 0;
-      if (error) reject(error);
-      else resolve();
-    };
-    const spawnFailure = error => {
-      const failure = extractionError(error.code === 'ENOENT'
-        ? 'Native tar is unavailable; install the operating system tar command'
-        : 'Native tar could not start', destination, details(null, null, error.code));
-      finish(failure);
-    };
-    const stop = reason => {
-      if (settled || stopped) return;
-      stopped = reason;
-      // A process blocked in filesystem I/O may not close even after SIGKILL.
-      // Arm the grace before kill: it can throw, return false, or emit events
-      // synchronously. Only close proves the destination can be cleaned up.
-      closeTimer = setTimeout(() => {
-        const error = extractionError(`${stopped}; tar did not close after termination; staging retained for safety`,
-          destination, details(null, null, processCode));
-        error.extractionMayBeRunning = true;
-        finish(error, true);
-      }, 1000);
-      try { child.kill('SIGKILL'); }
-      catch (error) { if (!settled) processCode ||= error.code; }
-    };
-    const onSpawn = () => { if (!settled) started = true; };
-    const onError = error => {
-      if (settled) return;
-      // Node leaves pid undefined when spawn is refused. A pid, a spawn event,
-      // or an attempted kill makes an error insufficient proof of termination.
-      if (!started && child.pid === undefined && !stopped) { spawnFailure(error); return; }
-      processCode ||= error.code;
-      stop('Native tar process failed');
-    };
-    const onData = chunk => {
-      if (settled) return;
-      started = true;
-      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-      errorBytes += bytes.length;
-      if (captured < 65536) {
-        const part = Buffer.from(bytes.subarray(0, 65536 - captured));
-        chunks.push(part); captured += part.length;
-      }
-      if (errorBytes > 65536) stop('Native tar stderr exceeded its diagnostic limit');
-    };
-    // Wait for close after killing tar so staging cleanup cannot race extraction.
-    const onClose = (code, signal) => {
-      if (settled) return;
-      if (!stopped && code === 0 && !signal) finish();
-      else finish(extractionError(stopped || 'Native tar rejected the release archive', destination, details(code, signal, processCode)));
-    };
-    try {
-      child = spawnImpl(nativeTar(), ['-xf', input, '-C', destination, '--no-same-owner', '--no-same-permissions'],
-        { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
-    } catch (error) { spawnFailure(error); return; }
-    started = child.pid !== undefined && child.pid !== null;
-    timer = setTimeout(() => stop('Native tar extraction timed out'), Math.min(timeout, LIMITS.timeout));
-    child.once('spawn', onSpawn);
-    child.on('error', onError);
-    child.once('close', onClose);
-    child.stderr.on('data', onData);
-  });
-  return entries;
-}
-module.exports = { validateEntries, zipEntries, tarEntries, extractArchive, nativeTar, diagnosticText, TOP_DIRECTORIES, BUNDLE };
+'use strict';
+// ZIP/TAR structural parsers reused from the StackBite npm bootstrapper (same
+// owner, proprietary): every member is bounded and checked before the OS tar
+// command sees the archive. WorkBite archives have no wrapping root directory.
+const fs = require('node:fs/promises');
+const { createReadStream, createWriteStream } = require('node:fs');
+const { createGunzip, createInflateRaw } = require('node:zlib');
+const { Transform, Writable } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const { stripVTControlCharacters } = require('node:util');
+const { LIMITS, fail, memberPath } = require('./common');
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+const crcTable = Uint32Array.from({ length: 256 }, (_, value) => {
+  for (let bit = 0; bit < 8; bit++) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
+  return value >>> 0;
+});
+const TOP_DIRECTORIES = Object.freeze(['workstack', 'stackbite', 'licenses']);
+const BUNDLE = 'bundle.json';
+
+async function readAt(file, offset, length) {
+  const bytes = Buffer.alloc(length);
+  const { bytesRead } = await file.read(bytes, 0, length, offset);
+  if (bytesRead !== length) fail('Truncated release archive');
+  return bytes;
+}
+// Top level is exactly workstack/ stackbite/ licenses/ and one bundle.json file; no links at all.
+function validateEntries(entries, windows) {
+  if (!entries.length || entries.length > LIMITS.members) fail('Invalid archive member count');
+  const names = new Map();
+  let expanded = 0, bundle = false;
+  for (const entry of entries) {
+    entry.name = memberPath(entry.name);
+    if (entry.kind !== 'file' && entry.kind !== 'directory') fail('Archive links and special members are not allowed');
+    const top = entry.name.split('/')[0];
+    if (entry.name === BUNDLE) {
+      if (entry.kind !== 'file') fail('bundle.json must be a regular file');
+      bundle = true;
+    } else if (!TOP_DIRECTORIES.includes(top) || (entry.name === top && entry.kind !== 'directory')) {
+      fail('Archive member is outside the WorkBite layout');
+    }
+    const key = windows ? entry.name.toLowerCase() : entry.name;
+    if (names.has(key)) fail('Duplicate archive member');
+    names.set(key, entry);
+    expanded += entry.size;
+    if (entry.size < 0 || entry.size > LIMITS.member || expanded > LIMITS.expanded) fail('Archive expansion exceeds limit');
+  }
+  if (!bundle) fail('Archive has no bundle.json');
+  for (const entry of entries) {
+    for (let parent = path.posix.dirname(entry.name); parent !== '.'; parent = path.posix.dirname(parent)) {
+      const ancestor = names.get(windows ? parent.toLowerCase() : parent);
+      if (ancestor && ancestor.kind !== 'directory') fail('Archive file is another member parent');
+    }
+  }
+  return entries;
+}
+async function zipEntries(archive) {
+  const file = await fs.open(archive, 'r');
+  const signal = AbortSignal.timeout(LIMITS.timeout);
+  try {
+    const size = (await file.stat()).size;
+    const tailStart = Math.max(0, size - 65557);
+    const tail = await readAt(file, tailStart, size - tailStart);
+    const end = tail.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+    if (end < 0 || end + 22 > tail.length) fail('Invalid ZIP directory');
+    const count = tail.readUInt16LE(end + 10), directorySize = tail.readUInt32LE(end + 12), offset = tail.readUInt32LE(end + 16);
+    if (tail.readUInt16LE(end + 4) || tail.readUInt16LE(end + 6) || tail.readUInt16LE(end + 8) !== count
+        || count === 65535 || count > LIMITS.members || directorySize > 16 * 1024 * 1024
+        || offset + directorySize !== tailStart + end || end + 22 + tail.readUInt16LE(end + 20) !== tail.length) fail('Unsafe ZIP directory');
+    const central = await readAt(file, offset, directorySize);
+    const entries = [], ranges = [];
+    let position = 0, totalExpanded = 0;
+    for (let index = 0; index < count; index++) {
+      signal.throwIfAborted();
+      if (position + 46 > central.length || central.readUInt32LE(position) !== 0x02014b50) fail('Invalid ZIP member');
+      const flags = central.readUInt16LE(position + 8), method = central.readUInt16LE(position + 10);
+      const compressed = central.readUInt32LE(position + 20), expanded = central.readUInt32LE(position + 24);
+      totalExpanded += expanded;
+      if (totalExpanded > LIMITS.expanded) fail('ZIP total expansion exceeds limit');
+      const nameSize = central.readUInt16LE(position + 28), extraSize = central.readUInt16LE(position + 30), commentSize = central.readUInt16LE(position + 32);
+      const localOffset = central.readUInt32LE(position + 42), mode = central.readUInt32LE(position + 38) >>> 16;
+      if (!nameSize || nameSize > 1024 || position + 46 + nameSize + extraSize + commentSize > central.length
+          || central.readUInt16LE(position + 34) || (flags & ~0x080e) || ![0, 8].includes(method)
+          || expanded > LIMITS.member || ![0, 0o100000, 0o040000].includes(mode & 0o170000) || (mode & 0o7000)) fail('Unsupported ZIP member');
+      const rawName = central.subarray(position + 46, position + 46 + nameSize);
+      if (!(flags & 0x0800) && rawName.some(value => value > 127)) fail('Ambiguous ZIP filename encoding');
+      const name = utf8.decode(rawName);
+      const directory = name.endsWith('/');
+      if (directory && (expanded || compressed)) fail('Invalid ZIP directory member');
+      const directoryMode = (mode & 0o170000) === 0o040000 || !!(central.readUInt32LE(position + 38) & 16);
+      if (directoryMode && !directory) fail('ZIP directory identity mismatch');
+      const local = await readAt(file, localOffset, 30);
+      const localNameSize = local.readUInt16LE(26), localExtraSize = local.readUInt16LE(28);
+      const dataStart = localOffset + 30 + localNameSize + localExtraSize;
+      if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== method
+          || localNameSize !== nameSize || dataStart + compressed > offset
+          || !(await readAt(file, localOffset + 30, localNameSize)).equals(rawName)) fail('ZIP local/central identity mismatch');
+      if (!(flags & 8) && (local.readUInt32LE(14) !== central.readUInt32LE(position + 16)
+          || local.readUInt32LE(18) !== compressed || local.readUInt32LE(22) !== expanded)) fail('ZIP local size mismatch');
+      if (!directory) {
+        // Bound the actual inflated bytes, not only the central-directory claim,
+        // before handing the same archive to the native extraction command.
+        if (method === 0 && compressed !== expanded) fail('Invalid stored ZIP size');
+        let actualSize = 0, crc = 0xffffffff;
+        const sink = new Writable({ write(chunk, encoding, callback) {
+          actualSize += chunk.length;
+          if (actualSize > expanded) return callback(new Error('ZIP expansion exceeds declared size'));
+          for (const byte of chunk) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 255];
+          callback();
+        } });
+        if (compressed) {
+          const input = createReadStream(archive, { start: dataStart, end: dataStart + compressed - 1 });
+          if (method === 8) await pipeline(input, createInflateRaw(), sink, { signal });
+          else await pipeline(input, sink, { signal });
+        }
+        if (actualSize !== expanded || ((crc ^ 0xffffffff) >>> 0) !== central.readUInt32LE(position + 16)) fail('ZIP content size/CRC mismatch');
+      }
+      // Reject Unicode-path/ZIP64 extra fields: native tar must use the same name
+      // and sizes checked here, without a second interpretation of this entry.
+      for (const extra of [central.subarray(position + 46 + nameSize, position + 46 + nameSize + extraSize),
+        await readAt(file, localOffset + 30 + localNameSize, localExtraSize)]) {
+        for (let at = 0; at < extra.length;) {
+          if (at + 4 > extra.length) fail('Invalid ZIP extra field');
+          const kind = extra.readUInt16LE(at), length = extra.readUInt16LE(at + 2);
+          if (![0x5455, 0x7875].includes(kind) || at + 4 + length > extra.length) fail('Unsupported ZIP extension');
+          at += 4 + length;
+        }
+      }
+      ranges.push([localOffset, dataStart + compressed]);
+      entries.push({ name, kind: directory ? 'directory' : 'file', size: expanded });
+      position += 46 + nameSize + extraSize + commentSize;
+    }
+    if (position !== central.length) fail('Extra ZIP directory records');
+    ranges.sort((a, b) => a[0] - b[0]);
+    if (ranges.some((range, index) => index && range[0] < ranges[index - 1][1])) fail('Overlapping ZIP members');
+    return entries;
+  } finally { await file.close(); }
+}
+function tarNumber(bytes) {
+  const value = bytes.toString('ascii').replace(/\0.*$/, '').trim();
+  if (value && !/^[0-7]+$/.test(value)) fail('Unsupported TAR numeric field');
+  const result = Number.parseInt(value || '0', 8);
+  if (!Number.isSafeInteger(result)) fail('Invalid TAR size');
+  return result;
+}
+function tarText(bytes) { return utf8.decode(bytes.subarray(0, bytes.indexOf(0) < 0 ? bytes.length : bytes.indexOf(0))); }
+function paxFields(bytes) {
+  const fields = {};
+  for (let offset = 0; offset < bytes.length;) {
+    const space = bytes.indexOf(32, offset);
+    if (space < 0 || !/^\d+$/.test(bytes.subarray(offset, space).toString())) fail('Invalid TAR PAX length');
+    const length = Number(bytes.subarray(offset, space).toString());
+    if (!Number.isSafeInteger(length) || length <= space - offset + 2 || offset + length > bytes.length || bytes[offset + length - 1] !== 10) fail('Invalid TAR PAX record');
+    const record = utf8.decode(bytes.subarray(space + 1, offset + length - 1));
+    const equal = record.indexOf('=');
+    const key = record.slice(0, equal), value = record.slice(equal + 1);
+    if (equal < 1 || !['path', 'linkpath', 'mtime', 'atime', 'ctime'].includes(key) || Object.hasOwn(fields, key)) fail('Unsupported TAR PAX field');
+    fields[key] = value;
+    offset += length;
+  }
+  return fields;
+}
+async function tarEntries(archive) {
+  const file = await fs.open(archive, 'r');
+  try {
+    const total = (await file.stat()).size;
+    const entries = [];
+    let offset = 0, pax = null, headers = 0;
+    while (offset + 512 <= total) {
+      const header = await readAt(file, offset, 512);
+      offset += 512;
+      if (header.every(value => value === 0)) {
+        if (pax || offset + 512 > total) fail('Truncated TAR trailer');
+        for (let at = offset; at < total; at += 65536) {
+          if (!(await readAt(file, at, Math.min(65536, total - at))).every(value => value === 0)) fail('Extra TAR payload after trailer');
+        }
+        return entries;
+      }
+      if (++headers > LIMITS.members * 2) fail('Too many TAR headers');
+      if (header.subarray(257, 263).toString('ascii') !== 'ustar\0') fail('Unsupported TAR header format');
+      let checksum = 0;
+      for (let index = 0; index < 512; index++) checksum += index >= 148 && index < 156 ? 32 : header[index];
+      if (checksum !== tarNumber(header.subarray(148, 156))) fail('Invalid TAR checksum');
+      const size = tarNumber(header.subarray(124, 136));
+      const kind = String.fromCharCode(header[156]);
+      if (size > (kind === 'x' ? 65536 : LIMITS.member) || offset + Math.ceil(size / 512) * 512 > total
+          || tarNumber(header.subarray(100, 108)) & 0o7000) fail('Unsafe TAR size or permissions');
+      if (kind === 'x') {
+        if (pax) fail('Chained TAR PAX headers');
+        pax = paxFields(await readAt(file, offset, size));
+      } else {
+        if (!['\0', '0', '5', '2'].includes(kind) || (kind !== '0' && kind !== '\0' && size)) fail('Unsupported TAR member');
+        const prefix = tarText(header.subarray(345, 500));
+        const name = pax && Object.hasOwn(pax, 'path') ? pax.path : (prefix ? prefix + '/' : '') + tarText(header.subarray(0, 100));
+        entries.push({ name, kind: kind === '5' ? 'directory' : kind === '2' ? 'link' : 'file', size,
+          link: pax && Object.hasOwn(pax, 'linkpath') ? pax.linkpath : tarText(header.subarray(157, 257)) });
+        pax = null;
+      }
+      offset += Math.ceil(size / 512) * 512;
+    }
+    fail('TAR trailer is missing');
+  } finally { await file.close(); }
+}
+async function boundedGunzip(archive, destination) {
+  let size = 0;
+  const bounded = new Transform({ transform(chunk, encoding, callback) {
+    size += chunk.length;
+    callback(size > LIMITS.expanded ? new Error('TAR expansion exceeds limit') : null, chunk);
+  } });
+  await pipeline(createReadStream(archive), createGunzip(), bounded,
+    createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal: AbortSignal.timeout(LIMITS.timeout) });
+}
+function nativeTar() {
+  return process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : '/usr/bin/tar';
+}
+// Diagnostics are untrusted subprocess output or paths. Never echo URLs, auth
+// headers, credential assignments or terminal control sequences back to a terminal.
+function diagnosticText(value, maximum = 4096) {
+  return stripVTControlCharacters(String(value))
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/gi, '[redacted URL]')
+    .replace(/\b(?:authorization|proxy-authorization|cookie|set-cookie)\s*[:=].*/gi, '[redacted credentials]')
+    .replace(/\b(?:bearer|basic)\s+\S+/gi, '[redacted credentials]')
+    .replace(/\b([\w.-]*(?:token|password|passwd|secret|credential|api[_-]?key)[\w.-]*)\s*[:=]\s*(?:"[^"]*(?:"|$)|'[^']*(?:'|$)|[^\s]*)/gi, '$1=[redacted]')
+    .slice(0, maximum);
+}
+function extractionError(reason, destination, { code = null, signal = null, stderr = '', truncated = false, spawnCode } = {}) {
+  const detail = diagnosticText(stderr);
+  const permission = /permission denied|operation not permitted|read-only file system|access is denied/i.test(detail)
+    || ['EACCES', 'EPERM', 'EROFS'].includes(spawnCode);
+  const storage = /no space left|disk (?:is )?full|quota exceeded|stale file handle|input\/output error/i.test(detail)
+    || ['ENOSPC', 'EDQUOT', 'ESTALE', 'EIO'].includes(spawnCode);
+  const hint = permission ? ' Check destination permissions, mount options and NFS access.'
+    : storage ? ' Check free space, quota and filesystem/NFS health.' : '';
+  const error = new Error(`${reason} (exit code: ${code ?? 'none'}, signal: ${diagnosticText(signal ?? 'none', 64)}${spawnCode ? `, spawn: ${diagnosticText(spawnCode, 64)}` : ''}); destination: ${diagnosticText(path.resolve(destination))}.${hint}${detail ? ` stderr: ${detail}${truncated ? ' [truncated]' : ''}` : ''}`);
+  error.exitCode = code;
+  error.signal = signal;
+  if (spawnCode) error.code = spawnCode;
+  return error;
+}
+async function extractArchive(archive, destination, spec, { spawnImpl = spawn, timeout = LIMITS.timeout } = {}) {
+  let input = archive;
+  const windows = spec.asset.endsWith('.zip');
+  if (!windows) { input = archive + '.tar'; await boundedGunzip(archive, input); }
+  const entries = windows ? await zipEntries(input) : await tarEntries(input);
+  validateEntries(entries, windows);
+  await new Promise((resolve, reject) => {
+    let child, timer, closeTimer, errorBytes = 0, captured = 0, stopped, processCode;
+    let started = false, settled = false;
+    const chunks = [];
+    const details = (code, signal, spawnCode) => ({ code, signal, spawnCode,
+      stderr: Buffer.concat(chunks).toString('utf8'), truncated: errorBytes > 4096 });
+    const finish = (error, unknown = false) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(closeTimer);
+      if (child) {
+        child.removeListener('spawn', onSpawn);
+        child.removeListener('error', onError);
+        child.removeListener('close', onClose);
+        child.stderr.removeListener('data', onData);
+        // A late kill error must remain handled without retaining this attempt's
+        // callbacks or changing its already settled cleanup authority.
+        child.on('error', () => {});
+        if (unknown) { child.unref?.(); child.stderr.destroy(); }
+        child = undefined;
+      }
+      chunks.length = 0;
+      if (error) reject(error);
+      else resolve();
+    };
+    const spawnFailure = error => {
+      const failure = extractionError(error.code === 'ENOENT'
+        ? 'Native tar is unavailable; install the operating system tar command'
+        : 'Native tar could not start', destination, details(null, null, error.code));
+      finish(failure);
+    };
+    const stop = reason => {
+      if (settled || stopped) return;
+      stopped = reason;
+      // A process blocked in filesystem I/O may not close even after SIGKILL.
+      // Arm the grace before kill: it can throw, return false, or emit events
+      // synchronously. Only close proves the destination can be cleaned up.
+      closeTimer = setTimeout(() => {
+        const error = extractionError(`${stopped}; tar did not close after termination; staging retained for safety`,
+          destination, details(null, null, processCode));
+        error.extractionMayBeRunning = true;
+        finish(error, true);
+      }, 1000);
+      try { child.kill('SIGKILL'); }
+      catch (error) { if (!settled) processCode ||= error.code; }
+    };
+    const onSpawn = () => { if (!settled) started = true; };
+    const onError = error => {
+      if (settled) return;
+      // Node leaves pid undefined when spawn is refused. A pid, a spawn event,
+      // or an attempted kill makes an error insufficient proof of termination.
+      if (!started && child.pid === undefined && !stopped) { spawnFailure(error); return; }
+      processCode ||= error.code;
+      stop('Native tar process failed');
+    };
+    const onData = chunk => {
+      if (settled) return;
+      started = true;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      errorBytes += bytes.length;
+      if (captured < 65536) {
+        const part = Buffer.from(bytes.subarray(0, 65536 - captured));
+        chunks.push(part); captured += part.length;
+      }
+      if (errorBytes > 65536) stop('Native tar stderr exceeded its diagnostic limit');
+    };
+    // Wait for close after killing tar so staging cleanup cannot race extraction.
+    const onClose = (code, signal) => {
+      if (settled) return;
+      if (!stopped && code === 0 && !signal) finish();
+      else finish(extractionError(stopped || 'Native tar rejected the release archive', destination, details(code, signal, processCode)));
+    };
+    try {
+      child = spawnImpl(nativeTar(), ['-xf', input, '-C', destination, '--no-same-owner', '--no-same-permissions'],
+        { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+    } catch (error) { spawnFailure(error); return; }
+    started = child.pid !== undefined && child.pid !== null;
+    timer = setTimeout(() => stop('Native tar extraction timed out'), Math.min(timeout, LIMITS.timeout));
+    child.once('spawn', onSpawn);
+    child.on('error', onError);
+    child.once('close', onClose);
+    child.stderr.on('data', onData);
+  });
+  return entries;
+}
+module.exports = { validateEntries, zipEntries, tarEntries, extractArchive, nativeTar, diagnosticText, TOP_DIRECTORIES, BUNDLE };