gspace 0.0.0-stage → 0.1.2

package/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,61 @@
+Third-party notices for the Gspace native backend
+
+These notices cover embedded CLI11 and nlohmann/json code. Python dependency
+wheels carry their own license metadata. This file does not assign a license
+to Gspace itself.
+
+
+CLI11 2.5.0
+===========
+
+CLI11 2.2 Copyright (c) 2017-2025 University of Cincinnati, developed by Henry
+Schreiner under NSF AWARD 1414736. All rights reserved.
+
+Redistribution and use in source and binary forms of CLI11, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+nlohmann/json 3.12.0
+====================
+
+MIT License
+
+Copyright (c) 2013-2025 Niels Lohmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/gspace.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../lib/bootstrap.js';
+
+main(process.argv.slice(2)).then(code => {
+  process.exitCode = code;
+}).catch(error => {
+  console.error(`Gspace: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/bootstrap.js

@@ -0,0 +1,409 @@
+import { constants, promises as fs, createReadStream } from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { createHash, randomBytes } from 'crypto';
+import { spawn, execFile } from 'child_process';
+import { promisify } from 'util';
+import { Readable } from 'stream';
+import { requestHTTPS, cancelBody } from './https.js';
+import { extractBundle, validateFiles, verifyBundle } from './bundle.js';
+
+const VERSION = '0.1.2';
+const DAY = 24 * 60 * 60 * 1000;
+const MAX_ARTIFACT = 256 * 1024 * 1024;
+const nonce = () => randomBytes(12).toString('hex');
+const uid = () => process.getuid();
+const execFileAsync = promisify(execFile);
+
+export async function availableSpace(directory, statfs = fs.statfs) {
+  if (typeof statfs === 'function') {
+    const space = await statfs(directory);
+    return space.bavail * space.bsize;
+  }
+  // Ubuntu 22.04's Node 12 predates fs.statfs. GNU df is part of the base
+  // workstation; use an absolute path and argument vector, never a shell.
+  const result = await execFileAsync('/usr/bin/df', ['--output=avail', '--block-size=1', '--', directory], {
+    env: { ...process.env, LC_ALL: 'C' }, timeout: 10000, maxBuffer: 65536,
+  });
+  const match = /^\s*Avail\s*\n\s*(\d+)\s*$/.exec(result.stdout);
+  const bytes = match && Number(match[1]);
+  if (!match || !Number.isSafeInteger(bytes)) throw new Error('Cannot determine available goinfre space.');
+  return bytes;
+}
+
+async function exists(file) {
+  try { await fs.lstat(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function safeDirectory(directory, create = false) {
+  if (!path.isAbsolute(directory)) throw new Error('Expected an absolute runtime directory.');
+  let current = path.parse(directory).root;
+  for (const part of directory.slice(current.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    if (create) {
+      try { await fs.mkdir(current, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    }
+    const info = await fs.lstat(current);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`Unsafe directory: ${current}`);
+  }
+  return directory;
+}
+
+async function privateDirectory(directory) {
+  await safeDirectory(directory, true);
+  const info = await fs.lstat(directory);
+  if (info.uid !== uid() || (info.mode & 0o022)) throw new Error(`Runtime directory must be owned by you and not writable by others: ${directory}`);
+  return directory;
+}
+
+export async function environment(env = process.env) {
+  if (process.platform !== 'linux' || process.arch !== 'x64') throw new Error('Gspace currently supports Linux x86_64.');
+  if (!env.HOME || !path.isAbsolute(env.HOME)) throw new Error('HOME must be an absolute existing directory.');
+  if (!env.USER || !/^[A-Za-z0-9_.-]+$/.test(env.USER) || ['.', '..'].includes(env.USER)) throw new Error('USER is missing or unsafe.');
+  const home = await fs.realpath(env.HOME);
+  await safeDirectory(home);
+  for (const candidate of [env.GOINFRE, `/goinfre/${env.USER}`, path.join(home, 'goinfre')]) {
+    if (!candidate || !path.isAbsolute(candidate)) continue;
+    try {
+      await fs.access(candidate, constants.W_OK | constants.X_OK);
+      const goinfre = await fs.realpath(candidate);
+      if (!(await fs.stat(goinfre)).isDirectory()) continue;
+      if (goinfre === home || goinfre === '/') throw new Error('Goinfre must be separate from HOME and /.');
+      await safeDirectory(goinfre);
+      const info = await fs.stat(goinfre);
+      if (info.uid !== uid() || (info.mode & 0o022)) throw new Error('Goinfre must be owned by you and not writable by others.');
+      return { home, goinfre, root: path.join(goinfre, '.gspace'), env: { ...env, HOME: home, GOINFRE: goinfre } };
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR', 'EACCES'].includes(error.code)) throw error;
+    }
+  }
+  throw new Error('No writable goinfre found. Set GOINFRE or prepare /goinfre/$USER or ~/goinfre.');
+}
+
+async function readJSON(file, fallback = null) {
+  if (!await exists(file)) return fallback;
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.uid !== uid() || info.size > 1024 * 1024 || info.nlink !== 1) throw new Error(`Unsafe metadata: ${file}`);
+    return JSON.parse(await handle.readFile('utf8'));
+  } finally { await handle.close(); }
+}
+
+async function atomicJSON(file, value) {
+  await privateDirectory(path.dirname(file));
+  if (await exists(file)) {
+    const info = await fs.lstat(file);
+    if (!info.isFile() || info.uid !== uid() || info.nlink !== 1) throw new Error(`Unsafe metadata destination: ${file}`);
+  }
+  const temporary = `${file}.tmp-${nonce()}`;
+  const handle = await fs.open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(JSON.stringify(value, null, 2) + '\n');
+    await handle.sync();
+    await handle.close();
+    await fs.rename(temporary, file);
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await fs.unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+function asURL(location) {
+  if (/^https?:|^file:/.test(location)) return new URL(location);
+  return pathToFileURL(path.resolve(location));
+}
+
+export async function fetchHTTPS(url, timeout = 60000, request = requestHTTPS, headers = {}) {
+  const deadline = Date.now() + timeout;
+  for (let redirects = 0; redirects <= 5; redirects++) {
+    url = new URL(url);
+    if (url.protocol !== 'https:' || url.username || url.password) throw new Error('Release downloads require HTTPS without embedded credentials.');
+    const response = await request(url, { timeout: Math.max(1, deadline - Date.now()), redirect: 'manual', headers });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get('location');
+      await cancelBody(response);
+      if (!location) throw new Error('Release redirect has no destination.');
+      url = new URL(location, url);
+      continue;
+    }
+    if (!response.ok) {
+      await cancelBody(response);
+      throw new Error(`Release download failed: HTTP ${response.status}`);
+    }
+    return response;
+  }
+  throw new Error('Too many release redirects.');
+}
+
+async function fetchBytes(url, limit) {
+  if (url.protocol === 'file:') {
+    const info = await fs.stat(fileURLToPath(url));
+    if (!info.isFile() || info.size > limit) throw new Error('Release file is oversized or not a file.');
+    return fs.readFile(fileURLToPath(url));
+  }
+  if (url.protocol !== 'https:') throw new Error('Remote releases require HTTPS. Use a local file URL for offline installs.');
+  const response = await fetchHTTPS(url);
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > limit) throw new Error('Release metadata exceeds its size limit.');
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function artifact(value, source) {
+  if (!value || !/^[a-f0-9]{64}$/.test(value.sha256) || !Number.isSafeInteger(value.size) || value.size <= 0 || value.size > MAX_ARTIFACT || typeof value.url !== 'string') throw new Error('Invalid release artifact metadata.');
+  const url = new URL(value.url, source);
+  if (source.protocol === 'https:' && url.protocol !== 'https:') throw new Error('Remote manifests cannot reference local or insecure artifacts.');
+  if (!['https:', 'file:'].includes(url.protocol)) throw new Error('Unsupported artifact URL.');
+  return { ...value, url: url.href };
+}
+
+export function validateManifest(value, source) {
+  if (!value || value.schema_version !== 2 || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(value.version)) throw new Error('Unsupported release manifest.');
+  const platform = value.platforms && value.platforms['linux-x86_64'];
+  if (!platform || !/^2\.\d+$/.test(platform.glibc_min)) throw new Error('Release lacks a supported Linux x86_64 bundle.');
+  const unpacked = validateFiles(platform.files);
+  if (unpacked !== platform.unpacked_size) throw new Error('Invalid unpacked size.');
+  return { schema_version: 2, version: value.version, bundle: artifact(platform.bundle, source), files: platform.files, unpacked_size: unpacked, glibc_min: platform.glibc_min };
+}
+
+export async function sha256(file) {
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size > MAX_ARTIFACT) throw new Error('Unsafe runtime artifact.');
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(null, { fd: handle.fd, autoClose: false })) hash.update(chunk);
+    return hash.digest('hex');
+  } finally { await handle.close(); }
+}
+
+const RANGE_SIZE = 1024 * 1024;
+
+async function downloadRanges(value, handle, first, request) {
+  async function copy(response, start, end) {
+    if (response.status !== 206 || response.headers.get('content-range') !== `bytes ${start}-${end}/${value.size}`) {
+      await cancelBody(response);
+      throw new Error('Invalid artifact byte range.');
+    }
+    let position = start;
+    for await (const chunk of response.body) {
+      if (position + chunk.length > end + 1) throw new Error('Artifact byte range exceeds its declared size.');
+      let offset = 0;
+      while (offset < chunk.length) {
+        const { bytesWritten } = await handle.write(chunk, offset, chunk.length - offset, position);
+        if (!bytesWritten) throw new Error('Unable to write artifact byte range.');
+        offset += bytesWritten;
+        position += bytesWritten;
+      }
+    }
+    if (position !== end + 1) throw new Error('Truncated artifact byte range.');
+  }
+  await copy(first, 0, 0);
+  let next = 1;
+  const workers = Array.from({ length: Math.min(8, Math.ceil((value.size - 1) / RANGE_SIZE)) }, async () => {
+    while (next < value.size) {
+      const start = next;
+      next += RANGE_SIZE;
+      const end = Math.min(value.size, start + RANGE_SIZE) - 1;
+      await copy(await request(start, end), start, end);
+    }
+  });
+  // Settle all writers before closing/removing an unsuccessful download.
+  const results = await Promise.allSettled(workers);
+  const failure = results.find(result => result.status === 'rejected');
+  if (failure) throw failure.reason;
+}
+
+export async function downloadVerified(value, destination, transport = requestHTTPS) {
+  if (!Number.isSafeInteger(value.size) || value.size <= 0 || value.size > MAX_ARTIFACT || !/^[a-f0-9]{64}$/.test(value.sha256)) throw new Error('Invalid release artifact metadata.');
+  const url = new URL(value.url);
+  const temporary = `${destination}.download-${nonce()}`;
+  const handle = await fs.open(temporary, 'wx', 0o600);
+  try {
+    let stream;
+    let ranged = false;
+    if (url.protocol === 'file:') stream = createReadStream(fileURLToPath(url));
+    else if (url.protocol === 'https:') {
+      const request = (start, end) => fetchHTTPS(url, 600000, transport, { Range: `bytes=${start}-${end}` });
+      const response = value.size > RANGE_SIZE ? await request(0, 0) : await fetchHTTPS(url, 600000, transport);
+      if (response.status === 206 && value.size > RANGE_SIZE) {
+        await downloadRanges(value, handle, response, request);
+        ranged = true;
+      } else {
+        // Servers without range support can return the entire file as HTTP 200.
+        if (response.status !== 200) { await cancelBody(response); throw new Error('Unexpected artifact response.'); }
+        stream = Readable.from(response.body);
+      }
+    } else throw new Error('Artifact requires HTTPS or a local file URL.');
+    const hash = createHash('sha256');
+    let total = 0;
+    if (!ranged) {
+      for await (const chunk of stream) {
+        total += chunk.length;
+        if (total > value.size || total > MAX_ARTIFACT) { stream.destroy(); throw new Error('Artifact exceeds its declared size.'); }
+        hash.update(chunk);
+        await handle.writeFile(chunk);
+      }
+      if (total !== value.size || hash.digest('hex') !== value.sha256) throw new Error('Artifact checksum or size mismatch; refusing execution.');
+    } else if ((await handle.stat()).size !== value.size || await sha256(temporary) !== value.sha256) {
+      throw new Error('Artifact checksum or size mismatch; refusing execution.');
+    }
+    await handle.sync();
+    await handle.close();
+    if (await exists(destination)) throw new Error('Refusing to overwrite an existing runtime artifact.');
+    await fs.link(temporary, destination);
+    await fs.unlink(temporary);
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await fs.unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+export function run(executable, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { shell: false, stdio: options.stdio === undefined ? 'inherit' : options.stdio, env: options.env || process.env });
+    const forward = signal => { if (!child.killed) child.kill(signal); };
+    const onInt = () => forward('SIGINT'), onTerm = () => forward('SIGTERM');
+    process.on('SIGINT', onInt); process.on('SIGTERM', onTerm);
+    const remove = () => { process.off('SIGINT', onInt); process.off('SIGTERM', onTerm); };
+    child.once('error', error => { remove(); reject(new Error(`Cannot start ${executable}: ${error.message}`)); });
+    child.once('exit', (code, signal) => { remove(); resolve(code === null ? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1) : code); });
+  });
+}
+
+async function lock(root) {
+  const directory = path.join(root, 'runtime', 'install.lock');
+  await privateDirectory(path.dirname(directory));
+  try { await fs.mkdir(directory, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    await safeDirectory(directory);
+    const info = await readJSON(path.join(directory, 'owner.json'));
+    if (info && info.hostname === os.hostname() && Number.isSafeInteger(info.pid) && info.pid > 1) {
+      let alive = true;
+      try { process.kill(info.pid, 0); } catch (failure) { if (failure.code === 'ESRCH') alive = false; }
+      if (!alive) {
+        await fs.rename(directory, `${directory}.stale-${nonce()}`);
+        return lock(root);
+      }
+    }
+    throw new Error('Another installation is running, or an interrupted install lock needs manual review.');
+  }
+  await atomicJSON(path.join(directory, 'owner.json'), { pid: process.pid, hostname: os.hostname() });
+  return async () => { await fs.unlink(path.join(directory, 'owner.json')); await fs.rmdir(directory); };
+}
+
+async function currentRuntime(root) {
+  const value = await readJSON(path.join(root, 'runtime', 'current.json'));
+  if (!value) return null;
+  // Reinstall experimental wheel-based runtimes using the standalone bundle.
+  if (value.schema_version === 1) return null;
+  if (value.schema_version !== 2 || typeof value.id !== 'string' || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?-[a-f0-9]{16}(?:-[a-f0-9]{24})?$/.test(value.id) || !/^[a-f0-9]{64}$/.test(value.manifest_hash)) throw new Error('Corrupted runtime metadata.');
+  const directory = path.join(root, 'runtime', value.id);
+  await safeDirectory(directory);
+  await verifyBundle(directory, value.files);
+  const backend = path.join(directory, 'bin', 'gspace-core');
+  return { ...value, directory, backend, tui: path.join(directory, 'tui', 'gspace-tui') };
+}
+
+async function prepareRuntime(context, manifest, manifestHash, logFd) {
+  const available = await availableSpace(context.goinfre);
+  const libc = process.report.getReport().header.glibcVersionRuntime;
+  const minimum = Number(manifest.glibc_min.split('.')[1]);
+  if (!libc || Number(libc.split('.')[0]) !== 2 || Number(libc.split('.')[1]) < minimum) throw new Error(`This release requires Linux glibc ${manifest.glibc_min} or newer.`);
+  if (available < manifest.bundle.size + manifest.unpacked_size + 64 * 1024 * 1024) throw new Error('Not enough goinfre space to download and unpack the runtime safely.');
+  const id = `${manifest.version}-${manifestHash.slice(0, 16)}`;
+  const directory = path.join(context.root, 'runtime', id);
+  // An incomplete version stays quarantined; a fresh installation gets a unique name.
+  const actualId = await exists(directory) ? `${id}-${nonce()}` : id;
+  const destination = path.join(context.root, 'runtime', actualId);
+  await privateDirectory(destination);
+  const archive = path.join(context.root, 'runtime', `${actualId}.tar.gz`);
+  console.error(`Downloading Gspace (${(manifest.bundle.size / 1048576).toFixed(1)} MiB)…`);
+  try {
+    await downloadVerified(manifest.bundle, archive);
+    console.error('Unpacking Gspace…');
+    await extractBundle(archive, destination, manifest.files);
+  } finally { await fs.unlink(archive).catch(() => {}); }
+  const backend = path.join(destination, 'bin', 'gspace-core');
+  const tui = path.join(destination, 'tui', 'gspace-tui');
+  const runtimeEnv = { ...context.env, PYTHONDONTWRITEBYTECODE: '1' };
+  delete runtimeEnv.PYTHONPATH;
+  delete runtimeEnv.PYTHONHOME;
+  await verifyBundle(destination, manifest.files);
+  if (await run(backend, ['--version'], { env: runtimeEnv, stdio: ['ignore', logFd, logFd] })) throw new Error('Downloaded backend did not start; see the bootstrap log.');
+  if (await run(tui, ['--version'], { env: runtimeEnv, stdio: ['ignore', logFd, logFd] })) throw new Error('Interface validation failed; see the bootstrap log.');
+  const result = { schema_version: 2, id: actualId, version: manifest.version, files: manifest.files, manifest_hash: manifestHash };
+  await atomicJSON(path.join(context.root, 'runtime', 'current.json'), result);
+  return currentRuntime(context.root);
+}
+
+export async function main(args, env = process.env) {
+  if (args.length === 1 && args[0] === '--version') { console.log(`gspace ${VERSION}`); return 0; }
+  if (env.GSPACE_CORE) {
+    if (args.length) return run(env.GSPACE_CORE, args, { env });
+    console.error('Launching Gspace…');
+    return run(env.GSPACE_TUI_PYTHON || env.GSPACE_PYTHON || 'python3', ['-m', 'gspace_tui', '--backend', env.GSPACE_CORE], { env });
+  }
+  const context = await environment(env);
+  await privateDirectory(context.root);
+  await privateDirectory(path.join(context.root, 'runtime'));
+  const logs = await privateDirectory(path.join(context.root, 'logs'));
+  const logPath = path.join(logs, 'bootstrap.log');
+  const log = await fs.open(logPath, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+  let releaseLock;
+  let runtime;
+  try {
+    const logInfo = await log.stat();
+    if (!logInfo.isFile() || logInfo.uid !== uid() || logInfo.nlink !== 1) throw new Error('Unsafe bootstrap log.');
+    releaseLock = await lock(context.root);
+    runtime = await currentRuntime(context.root);
+    const config = JSON.parse(await fs.readFile(new URL('../release.json', import.meta.url), 'utf8'));
+    const location = env.GSPACE_RELEASE_MANIFEST || config.manifest;
+    const forceUpdate = args[0] === '--update';
+    if (forceUpdate) args = args.slice(1);
+    const cacheFile = path.join(context.root, 'runtime', 'update.json');
+    let cache;
+    try { cache = await readJSON(cacheFile, {}); } catch { cache = {}; }
+    if (!runtime || forceUpdate || (location && Date.now() - (cache.checked_at || 0) >= DAY)) {
+      if (!location && !runtime) throw new Error('No release source configured. Set GSPACE_RELEASE_MANIFEST to a local manifest.json or HTTPS URL, or use GSPACE_CORE for a development build.');
+      if (location) {
+        try {
+          const source = asURL(location);
+          const raw = await fetchBytes(source, 1024 * 1024);
+          const manifest = validateManifest(JSON.parse(raw.toString('utf8')), source);
+          const hash = createHash('sha256').update(raw).digest('hex');
+          if (!runtime || runtime.manifest_hash !== hash) {
+            if (!runtime) console.error(`Gspace is not installed on this workstation.\nUsing ${context.goinfre}`);
+            runtime = await prepareRuntime(context, manifest, hash, log.fd);
+          }
+          await atomicJSON(cacheFile, { checked_at: Date.now(), location, version: manifest.version });
+        } catch (error) {
+          await log.appendFile(`${new Date().toISOString()} ${error.stack || error.message}\n`);
+          if (!runtime) throw error;
+          console.error('Update unavailable; using the existing verified runtime.');
+          await atomicJSON(cacheFile, { checked_at: Date.now(), location, last_error: error.message });
+        }
+      }
+    }
+  } catch (error) {
+    throw new Error(`${error.message}\nDetails: ${logPath}`);
+  } finally {
+    if (releaseLock) await releaseLock();
+    await log.close();
+  }
+  const runtimeEnv = { ...context.env, GSPACE_CORE: runtime.backend, PYTHONDONTWRITEBYTECODE: '1', PIP_NO_CACHE_DIR: '1' };
+  delete runtimeEnv.PYTHONPATH;
+  delete runtimeEnv.PYTHONHOME;
+  if (args.length) return run(runtime.backend, args, { env: runtimeEnv });
+  console.error('Launching Gspace…');
+  return run(runtime.tui, ['--backend', runtime.backend], { env: runtimeEnv });
+}

package/lib/bundle.js

@@ -0,0 +1,151 @@
+import { constants, createReadStream, promises as fs } from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { createGunzip } from 'zlib';
+
+export const MAX_UNPACKED = 512 * 1024 * 1024;
+const digest = /^[a-f0-9]{64}$/;
+
+function safePath(value) {
+  return typeof value === 'string' && value.length <= 255 &&
+    /^[A-Za-z0-9_.+@/-]+$/.test(value) &&
+    value.split('/').every(part => part && part !== '.' && part !== '..');
+}
+
+export function validateFiles(files) {
+  if (!Array.isArray(files) || !files.length || files.length > 4096) throw new Error('Invalid bundle file inventory.');
+  const names = new Set();
+  let total = 0;
+  for (const file of files) {
+    if (!safePath(file.path) || names.has(file.path) || !digest.test(file.sha256) ||
+        !Number.isSafeInteger(file.size) || file.size < 0 || typeof file.executable !== 'boolean') {
+      throw new Error('Unsafe or duplicate bundle file metadata.');
+    }
+    names.add(file.path);
+    total += file.size;
+    if (total > MAX_UNPACKED) throw new Error('Bundle exceeds unpacked size limit.');
+  }
+  for (const name of names) {
+    const parts = name.split('/');
+    while (parts.pop() && parts.length) {
+      if (names.has(parts.join('/'))) throw new Error('Bundle file conflicts with a directory.');
+    }
+  }
+  for (const name of ['bin/gspace-core', 'tui/gspace-tui']) {
+    if (!files.some(file => file.path === name && file.executable && file.size > 0)) throw new Error(`Bundle lacks ${name}.`);
+  }
+  return total;
+}
+
+function octal(bytes) {
+  const text = bytes.toString('ascii').replace(/\0.*$/s, '').trim();
+  if (!/^[0-7]+$/.test(text)) throw new Error('Invalid tar number.');
+  return Number.parseInt(text, 8);
+}
+
+// Our release builder emits USTAR regular files only. Links, devices, extended
+// headers, duplicates and unlisted entries are deliberately unsupported.
+export async function extractBundle(archive, destination, files) {
+  const total = validateFiles(files);
+  const directoryInfo = await fs.lstat(destination);
+  if (!directoryInfo.isDirectory() || directoryInfo.uid !== process.getuid() || (directoryInfo.mode & 0o022) || (await fs.readdir(destination)).length) throw new Error('Bundle destination must be an empty private directory.');
+  const expected = new Map(files.map(file => [file.path, file]));
+  const seen = new Set();
+  const input = createReadStream(archive);
+  const unpacker = createGunzip();
+  input.on('error', error => unpacker.destroy(error));
+  input.pipe(unpacker);
+  const iterator = unpacker[Symbol.asyncIterator]();
+  let pending = Buffer.alloc(0), offset = 0, expanded = 0;
+  // Header and padding overhead are bounded separately from file payloads.
+  const limit = total + files.length * 1024 + 10240;
+  async function read(length, eof = false) {
+    const output = Buffer.alloc(length);
+    let written = 0;
+    while (written < length) {
+      if (offset === pending.length) {
+        const next = await iterator.next();
+        if (next.done) {
+          if (eof && written === 0) return null;
+          throw new Error('Truncated bundle archive.');
+        }
+        pending = next.value;
+        offset = 0;
+        expanded += pending.length;
+        if (expanded > limit) throw new Error('Bundle exceeds unpacked size limit.');
+      }
+      const count = Math.min(length - written, pending.length - offset);
+      pending.copy(output, written, offset, offset + count);
+      offset += count;
+      written += count;
+    }
+    return output;
+  }
+  try {
+    let finished = false, zeroBlocks = 0;
+    for (;;) {
+      const header = await read(512, true);
+      if (!header) break;
+      if (header.every(byte => byte === 0)) { finished = true; zeroBlocks++; continue; }
+      if (finished) throw new Error('Unexpected data after tar terminator.');
+      let checksum = 0;
+      for (let index = 0; index < 512; index++) checksum += index >= 148 && index < 156 ? 32 : header[index];
+      if (checksum !== octal(header.subarray(148, 156)) || header.toString('ascii', 257, 263) !== 'ustar\0' || header.toString('ascii', 263, 265) !== '00') throw new Error('Invalid USTAR header.');
+      const field = (start, end) => header.subarray(start, end).toString('utf8').replace(/\0.*$/s, '');
+      const prefix = field(345, 500);
+      const name = (prefix ? prefix + '/' : '') + field(0, 100);
+      const file = expected.get(name);
+      if (!safePath(name) || !file || seen.has(name) || ![0, 48].includes(header[156]) || field(157, 257)) throw new Error('Unsafe, duplicate or unlisted archive entry.');
+      if (octal(header.subarray(124, 136)) !== file.size) throw new Error('Archive file size mismatch.');
+      seen.add(name);
+      const target = path.join(destination, name);
+      // Destination is a freshly created private directory. No archive entries
+      // can create symlinks, and exclusive opens never replace an existing file.
+      await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+      const output = await fs.open(target, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, file.executable ? 0o700 : 0o600);
+      const hash = createHash('sha256');
+      try {
+        for (let remaining = file.size; remaining > 0;) {
+          const bytes = await read(Math.min(65536, remaining));
+          hash.update(bytes);
+          await output.writeFile(bytes);
+          remaining -= bytes.length;
+        }
+        if (hash.digest('hex') !== file.sha256) throw new Error('Unpacked file checksum mismatch.');
+        await output.sync();
+      } finally { await output.close(); }
+      const padding = await read((512 - file.size % 512) % 512);
+      if (padding.some(byte => byte !== 0)) throw new Error('Invalid tar padding.');
+    }
+    if (zeroBlocks < 2 || seen.size !== expected.size) throw new Error('Incomplete bundle archive.');
+  } finally {
+    input.destroy();
+    unpacker.destroy();
+  }
+}
+
+export async function verifyBundle(directory, files) {
+  validateFiles(files);
+  const expected = new Map(files.map(file => [file.path, file]));
+  let count = 0;
+  async function visit(relative) {
+    const location = path.join(directory, relative);
+    const info = await fs.lstat(location);
+    if (info.uid !== process.getuid() || (info.mode & 0o022)) throw new Error('Unsafe runtime ownership or permissions.');
+    if (info.isDirectory()) {
+      for (const entry of await fs.readdir(location)) await visit(relative ? `${relative}/${entry}` : entry);
+      return;
+    }
+    const file = expected.get(relative);
+    if (!file || !info.isFile() || info.nlink !== 1 || info.size !== file.size || Boolean(info.mode & 0o111) !== file.executable) throw new Error('Installed runtime checksum mismatch or unexpected file; refusing execution.');
+    const handle = await fs.open(location, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const hash = createHash('sha256');
+      for await (const bytes of createReadStream(null, { fd: handle.fd, autoClose: false })) hash.update(bytes);
+      if (hash.digest('hex') !== file.sha256) throw new Error('Installed runtime checksum mismatch; refusing execution.');
+    } finally { await handle.close(); }
+    count++;
+  }
+  await visit('');
+  if (count !== files.length) throw new Error('Installed runtime is incomplete; refusing execution.');
+}

package/lib/https.js

@@ -0,0 +1,38 @@
+import https from 'https';
+
+// Node 12 has HTTPS and async iterable streams, but no fetch/AbortSignal API.
+// Keep TLS verification enabled and leave all redirect policy to the caller.
+export function requestHTTPS(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    let incoming;
+    const request = https.get(url, { headers: options.headers || {} }, response => {
+      incoming = response;
+      response.once('end', clear);
+      response.once('close', clear);
+      response.once('error', clear);
+      // Match the small response interface used by the bootstrap and tests.
+      response.cancel = async () => { response.destroy(); clear(); };
+      resolve({
+        status: response.statusCode,
+        ok: response.statusCode >= 200 && response.statusCode < 300,
+        headers: { get: name => {
+          const value = response.headers[name.toLowerCase()];
+          return Array.isArray(value) ? value.join(', ') : value || null;
+        } },
+        body: response,
+      });
+    });
+    const timer = setTimeout(() => {
+      const error = new Error('Release download timed out.');
+      request.destroy(error);
+      if (incoming) incoming.destroy(error);
+    }, options.timeout || 60000);
+    timer.unref();
+    function clear() { clearTimeout(timer); }
+    request.once('error', error => { clear(); reject(error); });
+  });
+}
+
+export async function cancelBody(response) {
+  if (response.body) await response.body.cancel();
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "gspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Gspace launcher for 1337/42 Linux workstations",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Seraph919/Gspace.git",
+    "directory": "npm"
+  },
+  "type": "module",
+  "bin": {
+    "gspace": "bin/gspace.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "release.json",
+    "THIRD_PARTY_NOTICES.txt"
+  ],
+  "engines": {
+    "node": ">=12.22.9"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/release.json

@@ -0,0 +1 @@
+{"manifest": "https://github.com/Seraph919/gspace-releases/releases/latest/download/manifest.json"}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.