permaura 1.3.1

package/README.md

@@ -0,0 +1,43 @@
+# permaura
+
+Run the [Permaura](https://permaura.com) gateway with one command. **Give your AI agents permission, not keys.**
+
+```bash
+# Install + run, then paste the URL/token into the console:
+npx -y permaura start
+
+# Or connect it to your account (grab the pairing code from permaura.com → Connect a gateway):
+npx -y permaura start --pair PGW-XXXXXXXXXX
+
+# Drive the gateway you just started:
+npx -y permaura status
+npx -y permaura grant --agent my-agent --resource db1 --allow uptime
+npx -y permaura stop
+
+# Just fetch the latest binary and exit, or print versions:
+npx -y permaura upgrade
+npx -y permaura --version
+```
+
+`npx -y permaura` on its own prints the help and starts nothing. Starting a gateway is always `start`.
+
+It downloads the prebuilt binary (to `~/.permaura/bin/permaura`), starts it on `http://127.0.0.1:8787`, and, with `--pair`, enrolls it against your permaura.com account so your console goes live automatically. No copy/paste of URLs or tokens.
+
+This package is a launcher, not a second CLI: every command other than `start` and `upgrade` is handed to the binary untouched, so `npx -y permaura <anything>` is the same program you get from `curl -fsSL https://permaura.com/install | sh`.
+
+Every run checks the release manifest and swaps in a newer binary when one ships (the manifest's Ed25519 signature is verified against a pinned release key, the download against the SHA-256 in it, and the swap is atomic so a running gateway is never disturbed). Pass `--no-upgrade` (or set `PERMAURA_NO_UPGRADE=1`) to pin the cached binary.
+
+Press **Ctrl-C** to stop a gateway running in the foreground.
+
+### Environment overrides
+
+| Var | Default | Purpose |
+|---|---|---|
+| `PERMAURA_ADDR` | `127.0.0.1:8787` | address the gateway listens on |
+| `PERMAURA_API` | `https://permaura.com` | account/pairing endpoint |
+| `PERMAURA_MANIFEST_URL` | dist `manifests/gateway.json` | release manifest to check for upgrades |
+| `PERMAURA_NO_UPGRADE` | (unset) | set to `1` to skip the auto-upgrade check |
+
+macOS, Linux and Windows, on arm64 and x64.
+
+> The gateway is a single self-contained binary. Source and releases: https://github.com/pixelitemedia/permaura-dist

package/bin/cli.mjs

@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+// permaura — the dead-easy way to run the Permaura gateway.
+//   npx -y permaura start                 # install-or-upgrade, run, print URL + token
+//   npx -y permaura start --pair PGW-XXXX # …and connect it to your permaura.com account
+//   npx -y permaura status                # …or any other permaura command, against a running one
+//   npx -y permaura upgrade               # just fetch the latest binary and exit
+//   npx -y permaura                       # print this and start nothing
+//
+// Zero dependencies: it reads the release manifest, downloads the prebuilt binary from the public
+// dist release, verifies its SHA-256, and runs it. Every run checks the manifest and swaps in a
+// newer binary when one ships (skip with --no-upgrade / PERMAURA_NO_UPGRADE=1).
+//
+// This is a launcher, not a second CLI. Everything but the install/upgrade half is handed to the
+// binary verbatim, so there is exactly one implementation of every command — including `--pair`,
+// which the binary performs itself once it is up.
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import http from "node:http";
+import crypto from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+
+import {
+  platformKey,
+  binaryFilename,
+  compareVersions,
+  sweepOldBinaries,
+  swapBinaryIntoPlace,
+  verifyDetachedSignature,
+} from "./lib.mjs";
+
+// The single source of truth for "what's the latest gateway": a static JSON in the public dist repo.
+// Overridable for staging/testing via PERMAURA_MANIFEST_URL.
+const MANIFEST_URL =
+  process.env.PERMAURA_MANIFEST_URL ||
+  "https://raw.githubusercontent.com/pixelitemedia/permaura-dist/main/manifests/gateway.json";
+const ADDR = process.env.PERMAURA_ADDR || "127.0.0.1:8787";
+// The same `~/.permaura` the gateway itself resolves (PERMAURA_HOME override kept, D6).
+const DIR = process.env.PERMAURA_HOME || path.join(os.homedir(), ".permaura");
+const BIN = path.join(DIR, "bin", binaryFilename(platformKey()));
+// Where a clean-bootstrapping gateway drops the per-install operator bearer it just minted (0600).
+// There is deliberately no constant fallback: a predictable token would be a public operator
+// credential on the very gateway the user is about to put real secrets into.
+const TOKEN_FILE = path.join(DIR, "operator.token");
+
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+const ok = (s) => console.log(`${C.green("✓")} ${s}`);
+const step = (s) => console.log(`${C.cyan("→")} ${s}`);
+const warn = (s) => console.log(`${C.yellow("!")} ${s}`);
+
+/**
+ * The binary's own subcommands. The launcher keeps the list so a typo costs nothing: a mistyped
+ * command is rejected here, before anything downloads a binary or binds a port. It is the same list
+ * the binary's clap definition carries, and the two drift only when a command is added — at which
+ * point the worst case is that the new one has to be run through the installed binary directly.
+ */
+const KNOWN = new Set([
+  "start",
+  "stop",
+  "upgrade",
+  "init",
+  "status",
+  "agent",
+  "grant",
+  "audit",
+  "pending",
+  "approve",
+  "deny",
+  "vault",
+  "policy",
+  "connection",
+  "approver",
+  "help",
+]);
+
+/** The two global flags that take a value, so their value is never mistaken for the subcommand. */
+const VALUE_FLAGS = new Set(["--url", "--token"]);
+
+const USAGE = `permaura — the dead-easy way to run the Permaura gateway.
+
+Usage:
+  npx -y permaura start                  install-or-upgrade, run, print URL + token
+  npx -y permaura start --pair PGW-XXXX   …and connect it to your permaura.com account
+  npx -y permaura upgrade                 just fetch the latest binary and exit
+  npx -y permaura <command> [args…]       run any other permaura command against a gateway
+  npx -y permaura --version               print the launcher + installed-binary versions
+  npx -y permaura --help                  print this
+
+Commands (${[...KNOWN].sort().join(", ")}) are the binary's own — run
+\`npx -y permaura help <command>\` for one of them.
+
+Launcher options:
+  --no-upgrade    run the cached binary without checking for a newer one
+                  (same as PERMAURA_NO_UPGRADE=1)
+  --version, -v   print versions and exit
+  --help, -h      print this and exit
+
+Environment:
+  PERMAURA_HOME       where the binary, store and operator token live (default ~/.permaura)
+  PERMAURA_ADDR       address the gateway binds (default 127.0.0.1:8787)
+  PERMAURA_API        account API base (default https://permaura.com)
+  PERMAURA_NO_UPGRADE set to 1 to skip the upgrade check
+`;
+
+/**
+ * Work out what this invocation is: which subcommand (if any), and which of the launcher's own flags
+ * were given before it.
+ *
+ * NO arguments prints help and starts nothing. A multi-command tool that boots a long-running server
+ * when invoked bare is a surprise, and this is the first command most people type. An unrecognised
+ * subcommand is an ERROR for the same reason it always was — `--help`, and every typo, used to
+ * silently boot a gateway and bind a port.
+ *
+ * Everything else is forwarded to the binary untouched (minus the launcher-only flags), so the
+ * binary's own parser owns global flags, per-command flags and `--help` after a subcommand.
+ */
+function parseArgs(argv) {
+  let cmd = null;
+  let noUpgrade = process.env.PERMAURA_NO_UPGRADE === "1";
+  let showVersion = false;
+  let showHelp = false;
+  const forward = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (VALUE_FLAGS.has(a)) {
+      forward.push(a);
+      if (i + 1 < argv.length) forward.push(argv[++i]);
+      continue;
+    }
+    if (a === "--no-upgrade") {
+      // Launcher-only: the binary has never heard of it, so it must not be forwarded.
+      noUpgrade = true;
+      continue;
+    }
+    if (!cmd && (a === "--version" || a === "-v")) {
+      showVersion = true;
+      continue;
+    }
+    if (!cmd && (a === "--help" || a === "-h")) {
+      showHelp = true;
+      continue;
+    }
+    if (!cmd && !a.startsWith("-")) cmd = a;
+    forward.push(a);
+  }
+  return { cmd, forward, noUpgrade, showVersion, showHelp };
+}
+
+/** This package's own version, read from the sibling package.json. */
+function cliVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** The installed binary's version (`permaura-gateway 0.1.1` → `0.1.1`), or null if absent/unreadable. */
+function installedVersion() {
+  if (!fs.existsSync(BIN)) return null;
+  try {
+    const out = spawnSync(BIN, ["--version"], { encoding: "utf8", timeout: 5000 });
+    const m = /(\d+\.\d+\.\d+[^\s]*)/.exec(out.stdout || "");
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/** https normally; plain http honoured so a PERMAURA_MANIFEST_URL override can point at a local test server (the release smoke does). */
+function requester(u) {
+  return u.startsWith("http://") ? http : https;
+}
+
+function httpGet(url, { json = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const go = (u, redirects = 0) => {
+      requester(u)
+        .get(u, { headers: { "User-Agent": "permaura-gateway-cli" } }, (res) => {
+          if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+            res.resume();
+            if (redirects > 10) return reject(new Error("too many redirects"));
+            return go(res.headers.location, redirects + 1);
+          }
+          if (res.statusCode !== 200) {
+            res.resume();
+            return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+          }
+          const chunks = [];
+          res.on("data", (d) => chunks.push(d));
+          res.on("end", () => {
+            const buf = Buffer.concat(chunks);
+            if (json) {
+              try {
+                resolve(JSON.parse(buf.toString("utf8")));
+              } catch (e) {
+                reject(new Error(`bad manifest JSON: ${e.message}`));
+              }
+            } else {
+              resolve(buf);
+            }
+          });
+        })
+        .on("error", reject);
+    };
+    go(url);
+  });
+}
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const go = (u, redirects = 0) => {
+      requester(u)
+        .get(u, { headers: { "User-Agent": "permaura-gateway-cli" } }, (res) => {
+          if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+            res.resume();
+            if (redirects > 10) return reject(new Error("too many redirects"));
+            return go(res.headers.location, redirects + 1);
+          }
+          if (res.statusCode !== 200) {
+            res.resume();
+            return reject(new Error(`download failed: HTTP ${res.statusCode}`));
+          }
+          const file = fs.createWriteStream(dest);
+          res.pipe(file);
+          file.on("finish", () => file.close(() => resolve()));
+          file.on("error", (e) => reject(e));
+        })
+        .on("error", reject);
+    };
+    go(url);
+  });
+}
+
+function sha256File(p) {
+  return crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+}
+
+/**
+ * The pinned release signing key (Ed25519, SPKI PEM) — `pmrel-2026a`, generated 2026-08-03.
+ *
+ * Why this matters: `asset.sha256` comes from the SAME manifest as `asset.url`. That is integrity
+ * against a corrupted download, not authenticity — anyone who can change the manifest changes both
+ * numbers and the checksum cheerfully confirms their binary. Only a signature made by a key we pinned
+ * out-of-band says "Permaura built this".
+ *
+ * `PERMAURA_RELEASE_PUBKEY` overrides this, which is how the tests drive a throwaway key. An override
+ * cannot weaken anything: any non-empty key still demands a valid signature.
+ */
+const PINNED_RELEASE_PUBKEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAKqPdId97cJ1iXDNMq767UseY9eMKe7jBSOKNzjQp76Q=
+-----END PUBLIC KEY-----`;
+
+const RELEASE_PUBKEY_PEM = (process.env.PERMAURA_RELEASE_PUBKEY ?? "").trim() || PINNED_RELEASE_PUBKEY_PEM;
+
+/** With a key configured, a valid signature is REQUIRED. Without one, we cannot verify anything yet. */
+const REQUIRE_SIGNATURE = RELEASE_PUBKEY_PEM.length > 0;
+
+/**
+ * Verify a detached Ed25519 signature over the EXACT manifest bytes.
+ *
+ * Detached-over-raw-bytes on purpose: signing a field *inside* the JSON would mean canonicalising it
+ * first, and every canonicalisation bug is a signature bypass. The bytes we verify are the bytes we
+ * parse.
+ *
+ * Returns true when verified, false when no key is configured (nothing to verify against), and throws
+ * when a key IS configured and the signature is missing or bad — that is an attack, not a hiccup.
+ */
+async function verifyManifestSignature(rawManifest, sigUrl) {
+  if (!REQUIRE_SIGNATURE) return false;
+
+  let sigB64;
+  try {
+    sigB64 = (await httpGet(sigUrl)).toString("utf8").trim();
+  } catch (e) {
+    throw new Error(
+      `the release manifest is not signed (${e.message}). Refusing to install: a signature is required once a release key is pinned.`,
+    );
+  }
+
+  // The crypto itself lives in lib.mjs so it is testable without a network; it throws on every failure.
+  return verifyDetachedSignature(rawManifest, sigB64, RELEASE_PUBKEY_PEM);
+}
+
+/**
+ * Ensure `BIN` is present and (unless suppressed) up to date with the manifest. Returns the version
+ * now installed. `force` re-downloads even when the versions match (the explicit `upgrade` command).
+ *
+ * Failure modes never leave the user worse off: if the manifest can't be fetched but a binary is
+ * already cached, we keep running the cached one; only a first install with no network is fatal.
+ */
+async function ensureBinary({ noUpgrade, force }) {
+  const key = platformKey();
+  if (!key) {
+    throw new Error(
+      `unsupported platform ${process.platform}/${process.arch} — prebuilt gateways cover macOS, Linux and Windows on arm64/x64. https://permaura.com/docs`,
+    );
+  }
+  fs.mkdirSync(path.join(DIR, "bin"), { recursive: true });
+
+  // Sweep binaries parked by a previous rename-aside upgrade (D9 cleanup-on-start; no-op when no
+  // live binary exists — a lone .old may be the only working copy after a failed swap).
+  sweepOldBinaries(BIN);
+
+  const have = installedVersion();
+  const haveBinary = fs.existsSync(BIN);
+
+  let manifest;
+  let manifestVerified = false;
+  try {
+    // Fetch the RAW bytes so the signature covers exactly what we parse (see verifyManifestSignature).
+    const rawManifest = await httpGet(MANIFEST_URL);
+    manifestVerified = await verifyManifestSignature(rawManifest, `${MANIFEST_URL}.sig`);
+    try {
+      manifest = JSON.parse(rawManifest.toString("utf8"));
+    } catch (e) {
+      throw new Error(`bad manifest JSON: ${e.message}`);
+    }
+  } catch (e) {
+    // A signature failure is never "the network was flaky" — it must not fall back to a cached binary
+    // and carry on as though nothing happened.
+    if (REQUIRE_SIGNATURE && /signature|signed|release key/i.test(e.message)) throw e;
+    if (haveBinary && !force) {
+      warn(`Couldn't check for updates (${e.message}); using the cached gateway${have ? ` ${have}` : ""}.`);
+      return have;
+    }
+    throw new Error(`could not fetch the release manifest: ${e.message}`);
+  }
+  if (!REQUIRE_SIGNATURE) {
+    warn(
+      "This build cannot verify that the gateway binary came from Permaura — no release key is pinned yet. The download is checksummed, but a checksum from an unsigned manifest only proves the file arrived intact, not who made it.",
+    );
+  }
+
+  const asset = manifest?.assets?.[key];
+  if (!asset?.url) {
+    if (haveBinary && !force) {
+      warn(`Manifest has no ${key} build; using the cached gateway${have ? ` ${have}` : ""}.`);
+      return have;
+    }
+    throw new Error(`the manifest has no build for ${key}`);
+  }
+
+  const latest = manifest.version;
+  const needsUpdate = force || !haveBinary || !have || compareVersions(have, latest) < 0;
+  if (!needsUpdate) {
+    ok(noUpgrade ? `Using cached gateway ${have} (upgrade check skipped).` : `Gateway ${have} is up to date.`);
+    return have;
+  }
+  if (noUpgrade && haveBinary) {
+    warn(`A newer gateway (${latest}) is available; skipping because --no-upgrade.`);
+    return have;
+  }
+
+  step(
+    haveBinary
+      ? `Updating the gateway ${have ?? "?"} → ${latest} (${key})…`
+      : `Downloading the Permaura gateway ${latest} (${key})…`,
+  );
+  const tmp = `${BIN}.download`;
+  await download(asset.url, tmp);
+
+  // Fail closed on a missing checksum. Warning and installing anyway made the one check we DO have
+  // optional at the attacker's discretion: strip the sha256 field and the guard politely stands aside.
+  if (!asset.sha256) {
+    fs.rmSync(tmp, { force: true });
+    throw new Error(
+      `the manifest has no sha256 for ${key}, so the download cannot be checked. Refusing to install an unverifiable binary.`,
+    );
+  }
+  const got = sha256File(tmp);
+  if (got.toLowerCase() !== String(asset.sha256).toLowerCase()) {
+    fs.rmSync(tmp, { force: true });
+    throw new Error(`checksum mismatch for the downloaded binary (expected ${asset.sha256}, got ${got})`);
+  }
+
+  fs.chmodSync(tmp, 0o755);
+  // Rename-aside swap (the rustup pattern, D9): park the current binary at `.old`, move the verified
+  // download into place, restore the parked copy if that fails — a runnable binary exists at BIN on
+  // every exit path. A gateway already running the old inode keeps working on every platform; the
+  // sweep above collects parked files on a later run.
+  swapBinaryIntoPlace(BIN, tmp);
+  // Quarantine is macOS's own "you didn't make this" flag, so stripping it from an artifact we could
+  // not authenticate throws away the last check standing. Once a release key is pinned this only runs
+  // for a signature-verified binary; until then it must still run, because the gateway binary is not
+  // notarized and Gatekeeper would otherwise refuse to execute it at all — removing the strip today
+  // would simply break every macOS install. Un-gating it is part of the signing work, not separate
+  // from it (see HANDBACK, § H-04).
+  if (process.platform === "darwin" && (manifestVerified || !REQUIRE_SIGNATURE)) {
+    try {
+      spawnSync("xattr", ["-d", "com.apple.quarantine", BIN], { stdio: "ignore" });
+    } catch {
+      /* not fatal */
+    }
+  }
+  ok(`Installed gateway ${latest} to ${BIN}`);
+  return latest;
+}
+
+/**
+ * The operator bearer for this install: an explicit PERMAURA_TOKEN, else the one the gateway minted
+ * into `operator.token` on clean bootstrap. Returns null when neither exists — a gateway initialised
+ * by an older build has a bearer we can't read, and inventing a shared one is exactly the hole this
+ * closes. Callers degrade to manual pairing instead.
+ */
+function readOperatorToken() {
+  if (process.env.PERMAURA_TOKEN) return process.env.PERMAURA_TOKEN;
+  try {
+    return fs.readFileSync(TOKEN_FILE, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function healthz(addr) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://${addr}/healthz`, (res) => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on("error", () => resolve(false));
+    req.setTimeout(1500, () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+
+async function waitHealthz(addr, tries = 20) {
+  for (let i = 0; i < tries; i++) {
+    if (await healthz(addr)) return true;
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+/**
+ * Best-effort graceful stop: `POST /v1/shutdown` (operator-authed, loopback-only) asks the gateway to
+ * drain in-flight requests and exit on its own. Resolves true on 202. Falls through to the caller's
+ * hard kill on any failure — e.g. a clean (non-seeded) gateway where the demo token isn't valid.
+ */
+function postShutdown(addr, token) {
+  return new Promise((resolve) => {
+    const [host, port] = addr.split(":");
+    const req = http.request(
+      {
+        method: "POST",
+        host,
+        port: port || 80,
+        path: "/v1/shutdown",
+        headers: { Authorization: `Bearer ${token}` },
+        timeout: 1500,
+      },
+      (res) => {
+        res.resume();
+        resolve(res.statusCode === 202);
+      },
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.end();
+  });
+}
+
+async function main() {
+  const { cmd, forward, noUpgrade, showVersion, showHelp } = parseArgs(process.argv.slice(2));
+
+  if (showHelp) {
+    console.log(USAGE);
+    return;
+  }
+
+  if (showVersion) {
+    console.log(`permaura (launcher) ${cliVersion()}`);
+    const have = installedVersion();
+    console.log(`permaura (binary) ${have ?? "(not installed)"}`);
+    return;
+  }
+
+  if (!cmd) {
+    if (forward.length) {
+      // Arguments but no command — a mistyped flag. It must not fall through to the bare-invocation
+      // help and exit 0, and it certainly must not start anything.
+      console.error(`${C.red("✗")} unknown argument${forward.length > 1 ? "s" : ""}: ${forward.join(", ")}\n`);
+      console.error(USAGE);
+      process.exitCode = 2;
+      return;
+    }
+    // Bare `permaura`: say what it does, start nothing.
+    console.log(USAGE);
+    return;
+  }
+
+  if (!KNOWN.has(cmd)) {
+    // Exit before anything binds a port or downloads a binary — a mistyped command should cost
+    // nothing.
+    console.error(`${C.red("✗")} unknown command: ${cmd}\n`);
+    console.error(USAGE);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (cmd === "upgrade") {
+    const v = await ensureBinary({ noUpgrade: false, force: true });
+    ok(`permaura is at ${v}.`);
+    return;
+  }
+
+  await ensureBinary({ noUpgrade, force: false });
+
+  // Everything that is not `start` is a short-lived command against a gateway: hand it straight to
+  // the binary, share this terminal, and exit with whatever it exits with.
+  if (cmd !== "start") {
+    const child = spawn(BIN, forward, { stdio: "inherit" });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (e) => {
+      console.error(`${C.red("✗")} could not run ${BIN}: ${e.message}`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  step(`Starting gateway at http://${ADDR}…`);
+  // PERMAURA_ADDR is the launcher's default bind; an explicit `--addr` in `forward` still wins,
+  // because clap ranks a flag above its env fallback.
+  const child = spawn(BIN, forward, {
+    env: { ...process.env, PERMAURA_ADDR: ADDR },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout.on("data", (d) => process.stdout.write(C.dim(d.toString())));
+  child.stderr.on("data", (d) => process.stderr.write(C.dim(d.toString())));
+  child.on("exit", (code) => {
+    console.log(`gateway exited (${code ?? 0})`);
+    process.exit(code ?? 0);
+  });
+
+  if (!(await waitHealthz(ADDR))) {
+    console.error(`${C.red("✗")} the gateway did not become healthy at http://${ADDR}`);
+    child.kill();
+    process.exit(1);
+  }
+  ok(`Gateway running at http://${ADDR}`);
+
+  const token = readOperatorToken();
+  const pairing = forward.some((a) => a === "--pair" || a.startsWith("--pair="));
+  if (!token) {
+    // The gateway is up and healthy — only adding it to an account needs the bearer. Say so plainly
+    // rather than guessing at a token.
+    warn(
+      `This gateway was initialised by an earlier build, so its operator token isn't readable here.\n    Re-pair from Console → Settings → Gateways, or re-run with PERMAURA_TOKEN=<token> set.`,
+    );
+  } else if (!pairing) {
+    // With --pair the binary reports the enrolment itself, success or failure, and prints these two
+    // lines when it fails. Printing them here as well would be the same instruction twice.
+    console.log(
+      `\nAdd it in the console → Settings → Gateways:\n    URL:   http://${ADDR}\n    Token: ${token}`,
+    );
+  }
+
+  console.log(C.dim("\nGateway is running. Press Ctrl-C to stop."));
+  process.on("SIGINT", async () => {
+    // Graceful first: /v1/shutdown lets the gateway drain and exit cleanly. This matters most on
+    // Windows, where child.kill() is an abrupt TerminateProcess; on Unix the foreground Ctrl-C
+    // already reached the child too, so this is belt-and-braces. The child's exit handler ends the
+    // process; the unref'd timer hard-kills if draining wedges. Without a readable token the
+    // authenticated drain isn't available, so fall straight through to the signal.
+    const accepted = token ? await postShutdown(ADDR, token) : false;
+    if (!accepted) child.kill("SIGINT");
+    setTimeout(() => {
+      child.kill();
+      process.exit(0);
+    }, 5000).unref();
+  });
+}
+
+main().catch((e) => {
+  console.error(C.red("✗"), e.message);
+  process.exit(1);
+});

package/bin/lib.mjs

@@ -0,0 +1,187 @@
+// Helpers shared by cli.mjs and the test suite. The naming/version helpers are pure; the
+// swap/sweep helpers take an injectable fs so their failure paths are table-testable under
+// `node --test` (a rename that fails mid-swap can't be provoked with the real fs).
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The manifest asset key for a platform/arch pair: darwin|linux|win32 × arm64|amd64.
+ * Node reports x64 where the manifest says amd64 (the release matrix keeps the Go-style
+ * `amd64` convention). Returns null for anything we don't ship.
+ */
+export function platformKey(platform = process.platform, arch = process.arch) {
+  const os = { darwin: "darwin", linux: "linux", win32: "win32" }[platform];
+  const cpu = { arm64: "arm64", x64: "amd64" }[arch];
+  return os && cpu ? `${os}-${cpu}` : null;
+}
+
+/** The installed binary's filename for a manifest key: `.exe` on Windows, bare elsewhere. */
+export function binaryFilename(key) {
+  return key && key.startsWith("win32-") ? "permaura.exe" : "permaura";
+}
+
+/**
+ * The release asset name for a manifest key (what CI stages and the manifest URLs point at):
+ * `permaura-<key>`, plus `.exe` for Windows so the download is double-click-safe.
+ */
+export function assetName(key) {
+  const suffix = key && key.startsWith("win32-") ? ".exe" : "";
+  return `permaura-${key}${suffix}`;
+}
+
+/**
+ * Sweep binaries parked by a previous rename-aside upgrade (D9 cleanup-on-start). Only sweeps when
+ * a live binary exists at `binPath`: after a failed swap the newest `.old` may be the only working
+ * copy on disk, and it must survive until a later successful swap replaces it. Best-effort — on
+ * Windows a still-running old gateway keeps its file locked and is collected on a later run.
+ */
+export function sweepOldBinaries(binPath, fsOps = fs) {
+  if (!fsOps.existsSync(binPath)) return;
+  const dir = path.dirname(binPath);
+  const base = path.basename(binPath);
+  for (const f of fsOps.readdirSync(dir)) {
+    if (f.startsWith(`${base}.old`)) {
+      try {
+        fsOps.rmSync(path.join(dir, f), { force: true });
+      } catch {
+        /* locked by a running process — leave it for next time */
+      }
+    }
+  }
+}
+
+/**
+ * Rename-aside swap (D9, the rustup pattern): park the current binary at `.old` (Windows can't
+ * overwrite a running executable but CAN rename it), then move the verified download into place.
+ * If that final rename fails, the parked binary is restored — there is a runnable binary at
+ * `binPath` on every exit path, success or throw.
+ */
+export function swapBinaryIntoPlace(binPath, tmpPath, fsOps = fs) {
+  const oldPath = `${binPath}.old`;
+  let parkedAt = null;
+  if (fsOps.existsSync(binPath)) {
+    try {
+      fsOps.rmSync(oldPath, { force: true });
+      fsOps.renameSync(binPath, oldPath);
+      parkedAt = oldPath;
+    } catch {
+      // `.old` itself is a locked running binary: park under a unique name instead.
+      const unique = `${binPath}.old-${Date.now()}`;
+      fsOps.renameSync(binPath, unique);
+      parkedAt = unique;
+    }
+  }
+  try {
+    fsOps.renameSync(tmpPath, binPath);
+  } catch (e) {
+    if (parkedAt) {
+      try {
+        fsOps.renameSync(parkedAt, binPath);
+      } catch {
+        /* restore failed — surface the original swap error below */
+      }
+    }
+    throw e;
+  }
+}
+
+/**
+ * Compare versions by semver precedence. `<0` if a<b, `0` equal, `>0` if a>b.
+ *
+ * The pre-release suffix is part of the order, not noise to be discarded. It used to be dropped, so
+ * `1.2.5-dev.1` compared EQUAL to the released `1.2.5` and the upgrade was never offered — a
+ * dev build of a version permanently masked that version's real release, on exactly the machines
+ * most likely to be running one.
+ */
+export function compareVersions(a, b) {
+  const split = (v) => {
+    const s = String(v ?? "0").replace(/^v/, "");
+    const i = s.indexOf("-");
+    return i === -1 ? [s, ""] : [s.slice(0, i), s.slice(i + 1)];
+  };
+  const [coreA, preA] = split(a);
+  const [coreB, preB] = split(b);
+  const nums = (c) => c.split(".").map((n) => parseInt(n, 10) || 0);
+  const pa = nums(coreA);
+  const pb = nums(coreB);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return comparePreRelease(preA, preB);
+}
+
+/**
+ * Semver §11.4 precedence for the pre-release part, over equal numeric cores.
+ *
+ * A version WITH a pre-release ranks below the same version without one; between two of them,
+ * identifiers are compared dot-by-dot, numerically when both are numeric, and a numeric identifier
+ * ranks below an alphanumeric one. A shorter run of identifiers loses when it is a prefix of the
+ * longer, which is what makes `1.0.0-rc` older than `1.0.0-rc.1`.
+ */
+function comparePreRelease(a, b) {
+  if (a === b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  const ia = a.split(".");
+  const ib = b.split(".");
+  for (let i = 0; i < Math.max(ia.length, ib.length); i++) {
+    const x = ia[i];
+    const y = ib[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xNum = /^\d+$/.test(x);
+    const yNum = /^\d+$/.test(y);
+    if (xNum && yNum) {
+      const d = parseInt(x, 10) - parseInt(y, 10);
+      if (d !== 0) return d < 0 ? -1 : 1;
+    } else if (xNum !== yNum) {
+      return xNum ? -1 : 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Verify a detached Ed25519 signature over the EXACT bytes of a release manifest.
+ *
+ * Detached-over-raw-bytes on purpose: signing a field *inside* the JSON would mean canonicalising the
+ * document first, and canonicalisation bugs are signature bypasses. The bytes verified here are the
+ * bytes the caller parses.
+ *
+ * Throws on every failure rather than returning false, so a caller cannot accidentally treat an
+ * unverified manifest as verified by ignoring a return value.
+ */
+export function verifyDetachedSignature(rawBytes, sigB64, publicKeyPem) {
+  let key;
+  try {
+    key = crypto.createPublicKey(publicKeyPem);
+  } catch (e) {
+    throw new Error(`the pinned release key is not a valid public key: ${e.message}`);
+  }
+  if (key.asymmetricKeyType !== "ed25519") {
+    // Guards against a pinned key of the wrong type quietly selecting a different algorithm.
+    throw new Error(`the pinned release key must be ed25519, got ${key.asymmetricKeyType}`);
+  }
+  let sig;
+  try {
+    sig = Buffer.from(String(sigB64).trim(), "base64");
+  } catch {
+    throw new Error("the manifest signature is not valid base64");
+  }
+  // Ed25519 signatures are exactly 64 bytes; a wrong length is malformed, not merely invalid.
+  if (sig.length !== 64) {
+    throw new Error(`the manifest signature is malformed (expected 64 bytes, got ${sig.length})`);
+  }
+  // Ed25519 verifies in one shot: algorithm null, no pre-hashing.
+  if (!crypto.verify(null, Buffer.from(rawBytes), key, sig)) {
+    throw new Error(
+      "the release manifest's signature did not verify against the pinned Permaura release key",
+    );
+  }
+  return true;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "permaura",
+  "version": "1.3.1",
+  "description": "Run the Permaura gateway with one command. Give your AI agents permission, not keys. `npx -y permaura start --pair <code>` installs the gateway, starts it, and connects it to your permaura.com account.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "permaura": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://permaura.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pixelitemedia/permaura-dist.git"
+  },
+  "keywords": [
+    "permaura",
+    "ai",
+    "agents",
+    "mcp",
+    "gateway",
+    "security",
+    "capabilities",
+    "permissions"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}