permaura 1.3.39 → 1.3.41

package/bin/cli.mjs

@@ -24,6 +24,7 @@ import { spawn, spawnSync } from "node:child_process";
 import {
   platformKey,
   binaryFilename,
+  shutdownIfProven,
   sweepOldBinaries,
   swapBinaryIntoPlace,
   upgradePlan,
@@ -489,37 +490,6 @@ async function waitHealthz(addr, tries = 20) {
   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));
 
@@ -623,9 +593,9 @@ async function main() {
     // 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;
+    // process; the unref'd timer hard-kills if draining wedges. Without a readable token, or when the
+    // listener does not prove it holds it, nothing is sent and the signal goes to our own child.
+    const accepted = token ? await shutdownIfProven(ADDR, token) : false;
     if (!accepted) child.kill("SIGINT");
     setTimeout(() => {
       child.kill();

package/bin/lib.mjs

@@ -4,6 +4,7 @@
 
 import crypto from "node:crypto";
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 
 /**
@@ -227,3 +228,84 @@ export function verifyDetachedSignatureAny(rawBytes, sigB64, publicKeyPems) {
 export function verifyDetachedSignature(rawBytes, sigB64, publicKeyPem) {
   return verifyDetachedSignatureAny(rawBytes, sigB64, [publicKeyPem]);
 }
+
+// ── Proof that the listener holds the operator token (AG-01) ────────────────────────────────────
+//
+// `permaura_core::health_proof` byte for byte: a fresh challenge to `/health` with no bearer, answered with lowercase hex HMAC-SHA256 keyed with the token's UTF-8 bytes over `permaura-health-proof:<port>:<challenge>`; only then is the token sent.
+
+export const CHALLENGE_HEADER = "x-permaura-challenge";
+export const PROOF_HEADER = "x-permaura-proof";
+
+/** A fresh challenge: 32 random bytes as 64 lowercase hex characters. */
+export function newChallenge() {
+  return crypto.randomBytes(32).toString("hex");
+}
+
+/** The proof a gateway listening on `port` and holding `token` gives for `challenge`, or null. */
+export function healthProof(token, port, challenge) {
+  if (!token || typeof challenge !== "string" || !/^[A-Za-z0-9_-]{16,64}$/.test(challenge)) return null;
+  return crypto
+    .createHmac("sha256", Buffer.from(token, "utf8"))
+    .update(`permaura-health-proof:${port}:${challenge}`, "utf8")
+    .digest("hex");
+}
+
+/** Whether `offered` is that proof. Constant-time, exact match only. */
+export function verifyHealthProof(token, port, challenge, offered) {
+  const expected = healthProof(token, port, challenge);
+  if (!expected || typeof offered !== "string") return false;
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(offered.trim(), "utf8");
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+/** `host:port` (IPv6 hosts in brackets) as the parts `http.request` takes. */
+function splitAddr(addr) {
+  const i = addr.lastIndexOf(":");
+  return { host: addr.slice(0, i).replace(/^\[|\]$/g, ""), port: Number(addr.slice(i + 1)) || 80 };
+}
+
+/** One request to `addr`, resolving to the response (body drained) or null on any failure. */
+function request(addr, options, timeoutMs) {
+  const { host, port } = splitAddr(addr);
+  return new Promise((resolve) => {
+    const req = http.request({ host, port, timeout: timeoutMs, ...options }, (res) => {
+      res.resume();
+      resolve(res);
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.end();
+  });
+}
+
+/** Whether the listener on `addr` proves it holds `token`, asked with a challenge and nothing else. */
+export async function proveListener(addr, token, timeoutMs = 1500) {
+  const challenge = newChallenge();
+  const res = await request(
+    addr,
+    { method: "GET", path: "/health", headers: { [CHALLENGE_HEADER]: challenge } },
+    timeoutMs,
+  );
+  const offered = res?.headers?.[PROOF_HEADER];
+  return verifyHealthProof(token, splitAddr(addr).port, challenge, typeof offered === "string" ? offered : null);
+}
+
+/**
+ * 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, and false on anything else, the
+ * caller then signalling its own child instead. The token goes only to a listener that has just proved
+ * it already holds it: whatever holds the port may not be the child at all.
+ */
+export async function shutdownIfProven(addr, token, timeoutMs = 1500) {
+  if (!token || !(await proveListener(addr, token, timeoutMs))) return false;
+  const res = await request(
+    addr,
+    { method: "POST", path: "/v1/shutdown", headers: { Authorization: `Bearer ${token}` } },
+    timeoutMs,
+  );
+  return res?.statusCode === 202;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "permaura",
-  "version": "1.3.39",
+  "version": "1.3.41",
   "description": "Run the Permaura gateway with one command. Give your AI agents permission, not keys. `npm i -g permaura` then `permaura start --pair <code>` installs the gateway, starts it, and connects it to your permaura.com account.",
   "license": "Apache-2.0",
   "type": "module",