sandboxedjs 0.1.94 → 0.1.95

package/bin/sandboxedjs-pack.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Build and sign a `.sbjs` application package.
+ *
+ *   sandboxedjs-pack keygen --out publisher.key --publisher "Your Name"
+ *   sandboxedjs-pack build ./app-dir --out officesuite-0.1.0.sbjs --key publisher.key
+ *   sandboxedjs-pack inspect officesuite-0.1.0.sbjs
+ *
+ * The directory must contain an `app.json` describing the application. What
+ * the packer adds is `META/manifest.json` — a sha256 for every file — and
+ * `META/signature.json`, an Ed25519 signature over that manifest's bytes.
+ *
+ * The private key never leaves the machine that signs, and is written with
+ * mode 600. There is no key recovery: a lost signing key means publishing
+ * under a new one, which every container then has to be told to trust.
+ */
+
+import { createHash, generateKeyPairSync, sign as signBytes, createPrivateKey, createPublicKey } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+
+const [command, ...rest] = process.argv.slice(2);
+const flags = parseFlags(rest);
+
+try {
+  switch (command) {
+    case "keygen": await keygen(); break;
+    case "build": await build(); break;
+    case "inspect": await inspect(); break;
+    case "help": case "--help": case "-h": case undefined: usage(); break;
+    default:
+      console.error(`sandboxedjs-pack: unknown command ${command}`);
+      usage();
+      process.exit(2);
+  }
+} catch (error) {
+  console.error(`sandboxedjs-pack: ${error.message}`);
+  process.exit(1);
+}
+
+function usage() {
+  console.log(`sandboxedjs-pack — build and sign .sbjs application packages
+
+  keygen  --out KEY --publisher NAME
+  build   DIR --out FILE.sbjs --key KEY [--unsigned]
+  inspect FILE.sbjs
+
+A .sbjs is a zip: the application's files, plus META/manifest.json listing a
+sha256 for each of them, plus META/signature.json signing that manifest.
+\`pm\` checks both before installing, and refuses a package whose signing key
+the container does not trust.`);
+}
+
+// ------------------------------------------------------------------ keygen
+
+async function keygen() {
+  const out = flags.out ?? "publisher.key";
+  const publisher = flags.publisher;
+  if (!publisher) throw new Error("keygen needs --publisher, the name packages are signed as");
+
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const secret = {
+    format: "sandboxedjs-publisher-key",
+    publisher,
+    privateKey: privateKey.export({ type: "pkcs8", format: "der" }).toString("base64"),
+    publicKey: publicKey.export({ type: "spki", format: "der" }).toString("base64"),
+    createdAt: new Date().toISOString(),
+  };
+  writeFileSync(out, `${JSON.stringify(secret, null, 2)}\n`, { mode: 0o600 });
+
+  const print = fingerprint(secret.publicKey);
+  console.log(`Wrote ${out} (keep it secret; there is no recovery)`);
+  console.log(`publisher:   ${publisher}`);
+  console.log(`fingerprint: ${print}`);
+  console.log(`public key:  ${secret.publicKey}`);
+  console.log("");
+  console.log("Containers trust it with:");
+  console.log(`  pm trust add ${JSON.stringify(publisher)} ${secret.publicKey}`);
+}
+
+// ------------------------------------------------------------------- build
+
+async function build() {
+  const directory = resolve(rest.find((argument) => !argument.startsWith("--")) ?? ".");
+  const manifestPath = join(directory, "app.json");
+  let app;
+  try {
+    app = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`cannot read ${manifestPath}: ${error.message}`);
+  }
+  for (const field of ["name", "version"]) {
+    if (typeof app[field] !== "string" || !app[field]) {
+      throw new Error(`app.json has no ${field}`);
+    }
+  }
+
+  const files = collect(directory).filter((path) => !path.startsWith("META/"));
+  if (!files.includes("app.json")) throw new Error("app.json must be in the package");
+  for (const binary of app.bins ?? []) {
+    if (!files.includes(binary.path)) {
+      /* Caught here rather than at install time, where the package is already
+       * on someone else's machine. */
+      throw new Error(`app.json declares the command ${binary.name} at ${binary.path}, which is not in ${directory}`);
+    }
+  }
+
+  const digests = {};
+  const contents = new Map();
+  for (const path of files) {
+    const bytes = readFileSync(join(directory, path));
+    contents.set(path, bytes);
+    digests[path] = createHash("sha256").update(bytes).digest("hex");
+  }
+
+  const manifest = {
+    format: "sandboxedjs-package",
+    schemaVersion: 1,
+    app,
+    files: digests,
+    built: new Date().toISOString(),
+  };
+  /* The signature covers these exact bytes, so they are written once and used
+   * both for signing and for the archive. Re-serialising before signing would
+   * risk signing a different string than the one shipped. */
+  const manifestBytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+  contents.set("META/manifest.json", manifestBytes);
+
+  if (!flags.unsigned) {
+    const keyPath = flags.key;
+    if (!keyPath) {
+      throw new Error("build needs --key, or --unsigned to publish without a publisher");
+    }
+    const key = JSON.parse(readFileSync(keyPath, "utf8"));
+    const privateKey = createPrivateKey({
+      key: Buffer.from(key.privateKey, "base64"), format: "der", type: "pkcs8",
+    });
+    const signature = {
+      format: "sandboxedjs-signature",
+      schemaVersion: 1,
+      algorithm: "ed25519",
+      publisher: key.publisher,
+      publicKey: key.publicKey
+        ?? createPublicKey(privateKey).export({ type: "spki", format: "der" }).toString("base64"),
+      signature: signBytes(null, manifestBytes, privateKey).toString("base64"),
+    };
+    contents.set("META/signature.json", Buffer.from(`${JSON.stringify(signature, null, 2)}\n`));
+  }
+
+  const out = flags.out ?? `${app.name}-${app.version}.sbjs`;
+  mkdirSync(dirname(resolve(out)), { recursive: true });
+  const archive = zip(contents, new Set((app.bins ?? []).map((binary) => binary.path)));
+  writeFileSync(out, archive);
+
+  const digest = createHash("sha256").update(archive).digest("hex");
+  console.log(`${out}  ${(archive.length / 1024).toFixed(1)} kB`);
+  console.log(`  ${app.name} ${app.version}, ${files.length} files`);
+  console.log(`  sha256: ${digest}`);
+  console.log(flags.unsigned ? "  unsigned" : `  signed by ${JSON.parse(readFileSync(flags.key, "utf8")).publisher}`);
+  /* What the registry index needs, so publishing is copy and paste. */
+  console.log("\nRegistry entry:");
+  console.log(JSON.stringify({
+    name: app.name, version: app.version, summary: app.summary,
+    filename: basename(out), sha256: digest, size: archive.length,
+    bins: app.bins ?? [], services: app.services ?? [], requires: app.requires ?? [],
+    docs: app.docs, license: app.license,
+  }, null, 2));
+}
+
+// ----------------------------------------------------------------- inspect
+
+async function inspect() {
+  const file = rest.find((argument) => !argument.startsWith("--"));
+  if (!file) throw new Error("inspect needs a .sbjs file");
+  const bytes = readFileSync(file);
+  const entries = readZip(bytes);
+  const manifestEntry = entries.find((entry) => entry.name === "META/manifest.json");
+  if (!manifestEntry) throw new Error(`${file} has no META/manifest.json`);
+  const manifest = JSON.parse(manifestEntry.data.toString("utf8"));
+  const signatureEntry = entries.find((entry) => entry.name === "META/signature.json");
+
+  console.log(`${manifest.app.name} ${manifest.app.version}`);
+  if (manifest.app.summary) console.log(`  ${manifest.app.summary}`);
+  console.log(`  built: ${manifest.built ?? "unknown"}`);
+  console.log(`  files: ${Object.keys(manifest.files).length}`);
+
+  let mismatched = 0;
+  for (const entry of entries) {
+    if (entry.name.startsWith("META/")) continue;
+    const actual = createHash("sha256").update(entry.data).digest("hex");
+    if (manifest.files[entry.name] !== actual) {
+      console.log(`  ALTERED: ${entry.name}`);
+      mismatched += 1;
+    }
+  }
+  console.log(mismatched === 0 ? "  every file matches the manifest" : `  ${mismatched} files do not match`);
+
+  if (!signatureEntry) {
+    console.log("  unsigned: this package has no publisher");
+    return;
+  }
+  const signature = JSON.parse(signatureEntry.data.toString("utf8"));
+  console.log(`  signed by: ${signature.publisher ?? "unnamed"}`);
+  console.log(`  fingerprint: ${fingerprint(signature.publicKey)}`);
+  const { verify } = await import("node:crypto");
+  const valid = verify(
+    null, manifestEntry.data,
+    createPublicKey({ key: Buffer.from(signature.publicKey, "base64"), format: "der", type: "spki" }),
+    Buffer.from(signature.signature, "base64"),
+  );
+  console.log(valid ? "  signature: valid" : "  signature: DOES NOT MATCH");
+  if (!valid || mismatched > 0) process.exitCode = 1;
+}
+
+// ------------------------------------------------------------------ pieces
+
+function collect(root, prefix = "") {
+  const out = [];
+  for (const entry of readdirSync(join(root, prefix), { withFileTypes: true })) {
+    const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...collect(root, path));
+    } else if (entry.isFile()) {
+      out.push(path);
+    }
+  }
+  return out.sort();
+}
+
+function fingerprint(publicKey) {
+  return createHash("sha256")
+    .update(Buffer.from(publicKey, "base64"))
+    .digest("hex")
+    .slice(0, 32)
+    .replace(/(.{4})(?=.)/g, "$1-");
+}
+
+function parseFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) continue;
+    const name = argument.slice(2);
+    if (name.includes("=")) {
+      const [key, value] = name.split("=");
+      flags[key] = value;
+    } else if (args[index + 1] && !args[index + 1].startsWith("--")) {
+      flags[name] = args[index + 1];
+      index += 1;
+    } else {
+      flags[name] = true;
+    }
+  }
+  return flags;
+}
+
+/** A zip with deflate, and the executable bit on declared binaries. */
+function zip(contents, executables) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+
+  for (const [name, data] of contents) {
+    const nameBytes = Buffer.from(name, "utf8");
+    const compressed = deflateRawSync(data);
+    const crc = crc32(data);
+    const mode = executables.has(name) ? 0o100755 : 0o100644;
+
+    const local = Buffer.alloc(30 + nameBytes.length);
+    /* Offsets are the zip specification's, exactly: writing the CRC two bytes
+     * late put it where the compressed size belongs, which our own reader
+     * ignored and `unzip` rejected as "bad CRC". */
+    local.writeUInt32LE(0x04034b50, 0); // signature
+    local.writeUInt16LE(20, 4);         // version needed
+    local.writeUInt16LE(0, 6);          // flags
+    local.writeUInt16LE(8, 8);          // deflate
+    local.writeUInt16LE(0x0021, 10);    // a fixed time, so two builds of the
+    local.writeUInt16LE(0x5a21, 12);    // same input produce the same package
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(compressed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(0, 28);         // extra length
+    nameBytes.copy(local, 30);
+    locals.push(local, compressed);
+
+    const entry = Buffer.alloc(46 + nameBytes.length);
+    entry.writeUInt32LE(0x02014b50, 0); // signature
+    entry.writeUInt16LE(0x031e, 4);     // made by: unix, so the mode is read
+    entry.writeUInt16LE(20, 6);         // version needed
+    entry.writeUInt16LE(0, 8);          // flags
+    entry.writeUInt16LE(8, 10);         // deflate
+    entry.writeUInt16LE(0x0021, 12);    // time
+    entry.writeUInt16LE(0x5a21, 14);    // date
+    entry.writeUInt32LE(crc, 16);
+    entry.writeUInt32LE(compressed.length, 20);
+    entry.writeUInt32LE(data.length, 24);
+    entry.writeUInt16LE(nameBytes.length, 28);
+    entry.writeUInt16LE(0, 30);         // extra length
+    entry.writeUInt16LE(0, 32);         // comment length
+    entry.writeUInt16LE(0, 34);         // disk number
+    entry.writeUInt16LE(0, 36);         // internal attributes
+    /* External attributes: the unix mode lives in the high 16 bits, and
+     * `<< 16` overflows a signed 32-bit int in JavaScript -- writeUInt32LE
+     * then refuses the negative number rather than storing the bits. */
+    entry.writeUInt32LE((mode * 0x10000) >>> 0, 38);
+    entry.writeUInt32LE(offset, 42);
+    nameBytes.copy(entry, 46);
+    central.push(entry);
+
+    offset += local.length + compressed.length;
+  }
+
+  const directory = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(contents.size, 8);
+  end.writeUInt16LE(contents.size, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, directory, end]);
+}
+
+/** Minimal central-directory reader, for `inspect`. */
+function readZip(bytes) {
+  const entries = [];
+  let end = bytes.length - 22;
+  while (end >= 0 && bytes.readUInt32LE(end) !== 0x06054b50) end -= 1;
+  if (end < 0) throw new Error("not a zip archive");
+  const count = bytes.readUInt16LE(end + 10);
+  let at = bytes.readUInt32LE(end + 16);
+
+  for (let index = 0; index < count; index += 1) {
+    if (bytes.readUInt32LE(at) !== 0x02014b50) throw new Error("damaged central directory");
+    const method = bytes.readUInt16LE(at + 10);
+    const compressedSize = bytes.readUInt32LE(at + 20);
+    const nameLength = bytes.readUInt16LE(at + 28);
+    const extraLength = bytes.readUInt16LE(at + 30);
+    const commentLength = bytes.readUInt16LE(at + 32);
+    const localOffset = bytes.readUInt32LE(at + 42);
+    const name = bytes.toString("utf8", at + 46, at + 46 + nameLength);
+
+    const localNameLength = bytes.readUInt16LE(localOffset + 26);
+    const localExtraLength = bytes.readUInt16LE(localOffset + 28);
+    const start = localOffset + 30 + localNameLength + localExtraLength;
+    const raw = bytes.subarray(start, start + compressedSize);
+    entries.push({ name, data: method === 0 ? raw : inflateRawSync(raw) });
+    at += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+function crc32(buffer) {
+  let crc = ~0;
+  for (const byte of buffer) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+  }
+  return (~crc) >>> 0;
+}

package/dist/agent.d.cts

@@ -1,4 +1,4 @@
-import { C as Container } from './container-C3cgcnXZ.cjs';
+import { C as Container } from './container-CPwyHoUy.cjs';
 import './contracts-B6SHFjma.cjs';
 
 /**

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import { C as Container } from './container-WEYRUg6Q.js';
+import { C as Container } from './container-CFieZcbe.js';
 import './contracts-B6SHFjma.js';
 
 /**

package/dist/{container-WEYRUg6Q.d.ts → container-CFieZcbe.d.ts}

@@ -1455,6 +1455,15 @@ interface ContainerOptions {
     /** CPU count reported by `nproc` and `/proc/cpuinfo`. Default 4. */
     cpus?: number;
     network?: NetworkOptions;
+    /**
+     * Applications to install before the container is handed back, by name or
+     * `name@version` — the same specifiers `pm install` takes.
+     *
+     * These are programs, not language packages: `pip` and `npm` install those.
+     * Installing needs the registry to be reachable, so a container with
+     * outbound access turned off has to carry them another way.
+     */
+    modules?: string[];
     timezone?: string;
     /** Default wall-clock limit for `exec`. Omit for no limit. */
     timeoutMs?: number;

package/dist/{container-C3cgcnXZ.d.cts → container-CPwyHoUy.d.cts}

@@ -1455,6 +1455,15 @@ interface ContainerOptions {
     /** CPU count reported by `nproc` and `/proc/cpuinfo`. Default 4. */
     cpus?: number;
     network?: NetworkOptions;
+    /**
+     * Applications to install before the container is handed back, by name or
+     * `name@version` — the same specifiers `pm install` takes.
+     *
+     * These are programs, not language packages: `pip` and `npm` install those.
+     * Installing needs the registry to be reachable, so a container with
+     * outbound access turned off has to carry them another way.
+     */
+    modules?: string[];
     timezone?: string;
     /** Default wall-clock limit for `exec`. Omit for no limit. */
     timeoutMs?: number;