epaperclip 0.0.0-stage → 1.0.0-rc3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenSourcx
+
+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/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# epaperclip
 
-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.
+Installs [ePaperclip](https://github.com/OpenSourcx/papercliped-engine) on a Proxmox VE host: a console on port 443 that people sign in to with their Proxmox accounts, and its engine (Paperclip) as a locked-down service on loopback. Proxmox's own web interface on port 8006 is never changed.
+
+In the Proxmox host's shell, as root:
+
+```sh
+npx epaperclip install
+```
+
+or `npm install -g epaperclip`, then `epaperclip install`.
+
+| Command | Does |
+| --- | --- |
+| `epaperclip install` | install, or upgrade to this package's version |
+| `epaperclip status` | version, whether both services run and answer, where the data is |
+| `epaperclip rollback` | go back to the previous version |
+| `epaperclip uninstall` | remove it, keeping data and settings (`--purge` removes those too) |
+
+This package carries the signed release (the tarball, its manifest and Ed25519 signature) and the project's public key. The command verifies the signature and the checksum and refuses to unpack anything that doesn't match. A release candidate is on the `next` tag (`npx epaperclip@next install`). It carries the same installer as the release download and the Debian package. It checks the host first and changes nothing if something is missing. It brings its own pinned, checksum-verified Node.js and installs the engine from its lockfile, so it needs internet access. It test-starts everything and rolls back by itself if the new version doesn't come up. Node.js on the host is only used to start this command.
+
+Requirements: Proxmox VE 8 or newer, 4 GB of memory recommended (2 GB minimum), about 3 GB of free disk. Full guide: [docs/INSTALL.md](https://github.com/OpenSourcx/papercliped-engine/blob/main/docs/INSTALL.md).
+
+MIT licensed.

package/bin/epaperclip.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// epaperclip install | status | rollback | uninstall [--purge]
+// Verifies the signed release this package carries (payload/epaperclip.tar.gz, its manifest and Ed25519 signature, against
+// the public key pinned beside them), unpacks it to a private temporary folder and runs the installer inside (the same one
+// as the release download and the Debian package). It must run as root on a Proxmox VE host. Nothing is unpacked or run
+// unless the signature, the manifest's SHA-256 and its version all check out. Node.js is only needed to start this command: the
+// installer brings its own pinned, checksum-verified Node.js for the services.
+import { spawnSync } from "node:child_process";
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { accessSync, constants, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+
+const payload = new URL("../payload/", import.meta.url).pathname;
+const usage = `usage: epaperclip <command>
+
+  install              install ePaperclip, or upgrade it to this package's version
+  status               version, whether both services run and answer, where the data is
+  rollback             go back to the previous version
+  uninstall [--purge]  remove it (keeps data and settings; --purge removes those too)
+
+Run as root in the Proxmox host's shell, for example: sudo npx epaperclip install
+Guide: https://github.com/OpenSourcx/papercliped-engine/blob/main/docs/INSTALL.md`;
+
+const fail = (msg, code = 1) => { console.error(`epaperclip: ${msg}`); process.exit(code); };
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") { console.log(usage); process.exit(cmd ? 0 : 2); }
+if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+  try { console.log(JSON.parse(readFileSync(join(payload, "epaperclip.manifest.json"), "utf8")).version); } catch { console.log("unknown"); }
+  process.exit(0);
+}
+
+const flags = { install: [], status: ["--status"], rollback: ["--rollback"], uninstall: ["--uninstall"] }[cmd];
+if (!flags) fail(`unknown command '${cmd}'\n\n${usage}`, 2);
+let args = [...flags, ...rest];
+if (cmd === "uninstall" && rest.includes("--purge")) args = ["--purge", ...rest.filter((a) => a !== "--purge")];
+
+const onPath = (name) => (process.env.PATH ?? "").split(delimiter).concat("/usr/bin", "/usr/sbin").some((d) => {
+  try { accessSync(join(d, name), constants.X_OK); return true; } catch { return false; }
+});
+if (process.platform !== "linux") fail("ePaperclip installs on a Proxmox VE host (Linux); this is " + process.platform);
+if (typeof process.getuid === "function" && process.getuid() !== 0) fail(`run as root, for example: sudo npx epaperclip ${[cmd, ...rest].join(" ")}`);
+if (!onPath("pveversion")) fail("this isn't a Proxmox VE host (pveversion wasn't found). Run it in the Proxmox host's own shell.");
+
+// Fail closed: the signature over the manifest, then the manifest's SHA-256 and file name against the tarball.
+const read = (f) => { try { return readFileSync(join(payload, f)); } catch { return null; } };
+const [tarball, manifest, signature, key] = ["epaperclip.tar.gz", "epaperclip.manifest.json", "epaperclip.manifest.sig", "release-signing.pub"].map(read);
+if (!key) fail("this package carries no release-signing key, so nothing can be verified and nothing was installed. The maintainer must run scripts/release-keygen.mjs and publish a package built with deploy/release-signing.pub");
+if (!tarball || !manifest || !signature) fail("this package is incomplete or unsigned (the release, its manifest or its signature is missing), so nothing was installed; reinstall the package");
+let signed = false;
+try { signed = verify(null, manifest, createPublicKey(key), Buffer.from(signature.toString("utf8").replace(/\s+/g, ""), "base64")); } catch { /* not valid */ }
+if (!signed) fail("the release's signature is not valid for the pinned key, so nothing was installed (the package was not signed by the project, or was altered)");
+let m;
+try { m = JSON.parse(manifest.toString("utf8")); } catch { fail("the signed manifest can't be read, so nothing was installed"); }
+if (m.name !== "epaperclip.tar.gz" || !/^[0-9a-f]{64}$/.test(m.sha256 ?? "") || !/^[0-9]{1,6}\.[0-9]{1,6}\.[0-9]{1,6}(-[0-9A-Za-z.]{1,40})?$/.test(m.version ?? "")) fail("the signed manifest is not for this release file, so nothing was installed");
+if (createHash("sha256").update(tarball).digest("hex") !== m.sha256 || (typeof m.size === "number" && m.size !== tarball.length)) fail("the release in this package doesn't match its signed checksum, so nothing was installed");
+
+const work = mkdtempSync(join(tmpdir(), "epaperclip-npm-"));
+const cleanup = () => rmSync(work, { recursive: true, force: true });
+const x = spawnSync("tar", ["-xzf", join(payload, "epaperclip.tar.gz"), "--no-same-owner", "-C", work], { stdio: "inherit" });
+if (x.error || x.status !== 0) { cleanup(); fail("couldn't unpack the release"); }
+const installer = join(work, "epaperclip", "deploy", "install.sh");
+try { accessSync(installer, constants.R_OK); } catch { cleanup(); fail("the release is incomplete (deploy/install.sh is missing)"); }
+const r = spawnSync("bash", [installer, ...args], { stdio: "inherit" });
+cleanup();
+if (r.error) fail(`couldn't run the installer: ${r.error.message}`);
+process.exit(r.status ?? 1);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "epaperclip",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc3",
+  "description": "Install ePaperclip on a Proxmox VE host: the console on port 443, signed in with Proxmox accounts, and its engine on loopback.",
+  "license": "MIT",
+  "author": "OpenSourcx",
+  "homepage": "https://github.com/OpenSourcx/papercliped-engine/blob/main/docs/INSTALL.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenSourcx/papercliped-engine.git",
+    "directory": "npm/epaperclip"
+  },
+  "keywords": [
+    "proxmox",
+    "pve",
+    "paperclip",
+    "agents",
+    "installer"
+  ],
+  "type": "module",
+  "bin": {
+    "epaperclip": "bin/epaperclip.js"
+  },
+  "files": [
+    "bin/epaperclip.js",
+    "payload/",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "linux"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepack": "node scripts/prepack.mjs"
+  }
+}

package/payload/epaperclip.manifest.json

@@ -0,0 +1,7 @@
+{
+  "format": 1,
+  "name": "epaperclip.tar.gz",
+  "version": "1.0.0-rc3",
+  "sha256": "a7dbd2ed0adac74a5cc7406c38ef69e94306a0c86fcf5b844b766f6f75204cf0",
+  "size": 1609280
+}

package/payload/epaperclip.manifest.sig

@@ -0,0 +1 @@
+7/VouQPeIevNM11nEuO/uOFbsyniaJ+36Y+2JMcYIukGdND3Fd8G667MJMQ4I7fH6+EQ2U755qZwCD2mJLA4Cw==

package/payload/release-signing.pub

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAUKvQFShqx/jCwgZZn+6ereMKFhDKzDGcr5lut7r2sds=
+-----END PUBLIC KEY-----