@ghalex/kvbox-server 0.2.0 → 0.3.0

package/dist/kvbox-server.js

@@ -39,6 +39,10 @@ function paths(home = kvboxHome()) {
     cli: join(home, "cli.json"),
     ssh: join(home, "ssh"),
     sshKey: join(home, "ssh", "id_ed25519"),
+    /** The host's self-signed TLS identity for the control plane (`kvbox-server join`): pinned there by fingerprint. */
+    tls: join(home, "tls"),
+    tlsKey: join(home, "tls", "key.pem"),
+    tlsCert: join(home, "tls", "cert.pem"),
     bin: join(home, "bin"),
     firecracker: join(home, "bin", "firecracker"),
     /** Firecracker's snapshot-editor, from the same release: merges a diff snapshot onto a full memory image. */
@@ -92,7 +96,7 @@ function paths(home = kvboxHome()) {
 }
 
 // src/core/config.ts
-import { readFile, writeFile } from "node:fs/promises";
+import { chmod, readFile, rename, writeFile } from "node:fs/promises";
 import { z } from "zod";
 
 // ../shared/src/sizes.ts
@@ -113,6 +117,7 @@ function shown(ref) {
   return ref.display ?? ref.name;
 }
 var LOCAL_OWNER_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}$/;
+var REALM_RE = /^[A-Za-z0-9.-]{1,128}$/;
 var OWNER_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}(@[A-Za-z0-9.-]{1,128})?$/;
 function localOwner() {
   try {
@@ -123,6 +128,15 @@ function localOwner() {
   const env = process.env["USER"];
   return env !== void 0 && LOCAL_OWNER_RE.test(env) ? env : "kvbox";
 }
+function inScope(owner, scope) {
+  if (scope === null) return true;
+  if (typeof scope === "string") return owner === scope;
+  return realmOf(owner) === scope.realm;
+}
+function realmOf(owner) {
+  const at = owner.indexOf("@");
+  return at === -1 ? null : owner.slice(at + 1);
+}
 function parseRef(text, caller) {
   const slash = text.indexOf("/");
   if (slash === -1) return { owner: caller, name: text, display: text };
@@ -131,6 +145,10 @@ function parseRef(text, caller) {
   if (!OWNER_RE.test(owner) || name.length === 0 || name.includes("/")) {
     throw new KvboxError(`invalid box reference "${text}": use <name> or <owner>/<name>`);
   }
+  const realm = realmOf(caller);
+  if (realm !== null && realmOf(owner) !== realm) {
+    throw new KvboxError(`invalid box reference "${text}": ${owner} is not in your realm`);
+  }
   return { owner, name, display: owner === caller ? name : text };
 }
 function refKey(ref) {
@@ -144,6 +162,16 @@ var PricingSchema = z.object({
   ramGibHour: z.number().nonnegative(),
   diskGibHour: z.number().nonnegative()
 });
+var ControlPlaneSchema = z.object({
+  url: z.string().url(),
+  /** The realm name: boxes the control plane creates are owned by `<user>@<name>`, a directory name on disk. */
+  name: z.string().regex(REALM_RE),
+  /** Minted at join; every HTTPS call from the control plane carries it as a bearer. */
+  secret: z.string().min(1),
+  /** The address the control plane reaches this host at. */
+  advertise: z.string().min(1),
+  port: z.number().int().positive().default(7777)
+});
 var ConfigSchema = z.object({
   kernel: z.string(),
   rootfs: z.string(),
@@ -156,8 +184,17 @@ var ConfigSchema = z.object({
   defaultSize: z.enum(SIZE_NAMES).default(DEFAULT_SIZE),
   /** Who boxes made over the local socket belong to: the Unix user running the server unless set here. No `@`, no `/`. */
   owner: z.string().regex(LOCAL_OWNER_RE, "owner: letters, digits, '.', '_', '-'; no '@' or '/'").default(localOwner),
-  pricing: PricingSchema.optional()
+  pricing: PricingSchema.optional(),
+  /** Absent until the host joins a control plane; then the server also listens on HTTPS. */
+  controlPlane: ControlPlaneSchema.optional()
 });
+async function saveConfig(cfg, p = paths()) {
+  const parsed = ConfigSchema.parse(cfg);
+  const tmp = `${p.config}.tmp`;
+  await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", { mode: 384 });
+  await chmod(tmp, 384);
+  await rename(tmp, p.config);
+}
 function defaultConfig(p = paths()) {
   return ConfigSchema.parse({
     kernel: p.kernel,
@@ -181,9 +218,152 @@ async function loadConfig(p = paths()) {
   }
 }
 
-// src/core/network.ts
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+// src/core/controlPlane.ts
+import { X509Certificate } from "node:crypto";
+import { chmod as chmod2, mkdir, readFile as readFile2 } from "node:fs/promises";
+import { hostname as osHostname } from "node:os";
+import { request } from "undici";
+
+// ../shared/src/api.ts
+import { z as z2 } from "zod";
+var SizeSchema = z2.enum(SIZE_NAMES);
+var BoxStatusSchema = z2.enum(["running", "standby", "hibernated", "stopped", "unknown"]);
+var MachineSchema = z2.object({
+  /** Host-unique short id (the tap is `kv-<id>`). Missing only on a box made before ids that has not restarted since. */
+  id: z2.string().optional(),
+  name: z2.string(),
+  /** Who the box belongs to; names are unique per owner. A bare name is local to the host, `user@control-plane` later. */
+  owner: z2.string(),
+  ip: z2.string(),
+  mac: z2.string(),
+  pid: z2.number().int().nullable(),
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  diskBytes: z2.number().int(),
+  // the box's own writable disk, as the guest sees it
+  diskUsedBytes: z2.number().int(),
+  // what that sparse file really occupies on the host
+  base: z2.string().nullable(),
+  // base image version the box runs on (null: pre-overlay box with its own copy)
+  createdAt: z2.string(),
+  source: z2.string(),
+  // "base" or "snapshot:<name>"
+  status: BoxStatusSchema
+});
+var CreateMachineRequest = z2.object({
+  name: z2.string().optional(),
+  /** Ignored over the local socket (the caller is the host owner); the control plane sets it over HTTPS. */
+  owner: z2.string().optional(),
+  size: SizeSchema.optional(),
+  from: z2.string().optional(),
+  force: z2.boolean().optional()
+});
+var RescaleMachineRequest = z2.object({
+  size: SizeSchema.optional(),
+  vcpu: z2.number().int().min(1).max(64).optional(),
+  memMib: z2.number().int().min(256).optional(),
+  diskGib: z2.number().int().min(1).optional()
+});
+var SnapshotSchema = z2.object({
+  name: z2.string(),
+  owner: z2.string(),
+  source: z2.string(),
+  // the box it was taken from, as owner/name
+  base: z2.string(),
+  // base image version the overlay stacks on; a restore needs the same one
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  sizeBytes: z2.number().int(),
+  // what vmstate + mem + overlay really occupy on the host
+  createdAt: z2.string()
+});
+var CreateSnapshotRequest = z2.object({
+  box: z2.string(),
+  name: z2.string()
+});
+var CapacitySchema = z2.object({
+  hostMemMib: z2.number().int(),
+  hostCores: z2.number().int(),
+  reservedMemMib: z2.number().int(),
+  reservedVcpu: z2.number().int(),
+  running: z2.number().int()
+});
+var HealthSchema = z2.object({
+  ok: z2.literal(true),
+  version: z2.string(),
+  pid: z2.number().int(),
+  /** Base image version new boxes get (null when the host has no usable base image yet); absent from older servers. */
+  base: z2.string().nullable().optional(),
+  /** Owner that boxes made over the local socket get (the Unix user running the server); absent from older servers. */
+  owner: z2.string().optional()
+});
+var MachineUsageSchema = z2.object({
+  name: z2.string(),
+  owner: z2.string(),
+  status: BoxStatusSchema,
+  window: z2.object({ from: z2.string(), to: z2.string() }),
+  /** standby and hibernated default to 0 so a newer CLI reads an older server's answer. */
+  seconds: z2.object({
+    running: z2.number().int(),
+    standby: z2.number().int().default(0),
+    hibernated: z2.number().int().default(0),
+    stopped: z2.number().int()
+  }),
+  vcpuHours: z2.number(),
+  ramGibHours: z2.number(),
+  diskGibHours: z2.number(),
+  cost: z2.object({ amount: z2.number(), currency: z2.string() }).optional(),
+  /** Stops the server did not witness (Firecracker died, host rebooted) and dated to when it noticed. */
+  estimatedStops: z2.number().int(),
+  historyFrom: z2.string().nullable()
+});
+var ApiErrorSchema = z2.object({
+  error: z2.string()
+});
+var CloudUserSchema = z2.object({
+  /** The handle: what hosts file boxes under (`<username>@<control plane>`). Lowercase, no `@` or `/`. */
+  username: z2.string(),
+  /** Display name, free text ("Alexandru Ghiura"). */
+  name: z2.string(),
+  /** Login identity, unique. */
+  email: z2.string(),
+  role: z2.enum(["admin", "user"]),
+  createdAt: z2.string()
+});
+var LoginRequestSchema = z2.object({
+  email: z2.string().min(1),
+  password: z2.string().min(1),
+  publicKey: z2.string().optional()
+});
+var SignupRequestSchema = z2.object({
+  username: z2.string().min(1),
+  name: z2.string().min(1),
+  email: z2.string().min(1),
+  password: z2.string().min(1)
+});
+var LoginResponseSchema = z2.object({
+  token: z2.string(),
+  user: CloudUserSchema
+});
+var HostJoinRequestSchema = z2.object({
+  token: z2.string().min(1),
+  name: z2.string().min(1),
+  url: z2.string().url(),
+  fingerprint: z2.string().regex(/^([0-9A-F]{2}:){31}[0-9A-F]{2}$/),
+  publicAddress: z2.string().min(1)
+});
+var HostJoinResponseSchema = z2.object({
+  hostSecret: z2.string(),
+  controlPlane: z2.object({ name: z2.string() })
+});
+var CloudHostSchema = z2.object({
+  name: z2.string(),
+  url: z2.string(),
+  publicAddress: z2.string(),
+  joinedAt: z2.string(),
+  lastSeenAt: z2.string().nullable(),
+  capacity: CapacitySchema.nullable()
+});
 
 // src/core/exec.ts
 import { execFile } from "node:child_process";
@@ -209,7 +389,127 @@ async function run(argv, opts = {}) {
   }
 }
 
+// src/core/controlPlane.ts
+var DEFAULT_HTTPS_PORT = 7777;
+async function ensureTlsCert(p = paths()) {
+  const have = await readFile2(p.tlsCert, "utf8").catch(() => null);
+  const haveKey = await readFile2(p.tlsKey).then(() => true, () => false);
+  if (have === null || !haveKey) {
+    await mkdir(p.tls, { recursive: true, mode: 448 });
+    try {
+      await run([
+        "openssl",
+        "req",
+        "-x509",
+        "-newkey",
+        "ec",
+        "-pkeyopt",
+        "ec_paramgen_curve:prime256v1",
+        "-nodes",
+        "-keyout",
+        p.tlsKey,
+        "-out",
+        p.tlsCert,
+        "-subj",
+        "/CN=kvbox-host",
+        "-days",
+        "3650"
+      ]);
+    } catch (err) {
+      throw new KvboxError(`could not make the host's certificate (is openssl installed?): ${err.message}`);
+    }
+    await chmod2(p.tlsKey, 384);
+  }
+  const pem = await readFile2(p.tlsCert, "utf8");
+  return { fingerprint: new X509Certificate(pem).fingerprint256 };
+}
+function isPrivateAddress(ip) {
+  const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(ip);
+  if (!m) return false;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  return a === 10 || a === 127 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127;
+}
+async function defaultAdvertise() {
+  const { stdout } = await run(["ip", "-4", "route", "get", "1.1.1.1"]).catch((err) => {
+    throw new KvboxError(`cannot tell this host's address (${err.message}); pass --advertise <host-or-ip>`);
+  });
+  const m = /\bsrc\s+(\S+)/.exec(stdout);
+  if (!m) throw new KvboxError("cannot tell this host's address from its routes; pass --advertise <host-or-ip>");
+  return m[1];
+}
+async function joinControlPlane(opts, p = paths(), guessAddress = defaultAdvertise) {
+  const url = opts.url.replace(/\/+$/, "");
+  const port = opts.port ?? DEFAULT_HTTPS_PORT;
+  const cfg = await loadConfig(p);
+  if (cfg.controlPlane) throw new KvboxError(`this host has already joined ${cfg.controlPlane.name} (${cfg.controlPlane.url}); run kvbox-server leave first`);
+  let advertise = opts.advertise;
+  if (advertise === void 0) {
+    advertise = await guessAddress();
+    if (isPrivateAddress(advertise)) {
+      throw new KvboxError(
+        `${advertise} is a private address: a control plane on the internet cannot reach this host there.
+  Pass --advertise <public host or ip>, or --advertise ${advertise} if the control plane is on the same network.`
+      );
+    }
+  }
+  const name = opts.name ?? osHostname();
+  const { fingerprint } = await ensureTlsCert(p);
+  const hostUrl = `https://${advertise}:${port}`;
+  const body = { token: opts.token, name, url: hostUrl, fingerprint, publicAddress: advertise };
+  const res = await request(`${url}/hosts/join`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    headersTimeout: 1e4,
+    bodyTimeout: 1e4
+  }).catch((err) => {
+    throw new KvboxError(`cannot reach ${url} (${err.message})`);
+  });
+  const text = await res.body.text();
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    throw new KvboxError(errorIn(text) ?? `control plane answered ${res.statusCode}`);
+  }
+  const parsed = HostJoinResponseSchema.safeParse(jsonOrNull(text));
+  if (!parsed.success) throw new KvboxError(`${url} did not answer like a kvbox control plane`);
+  if (!REALM_RE.test(parsed.data.controlPlane.name)) {
+    throw new KvboxError(`${url} calls itself "${parsed.data.controlPlane.name}", which cannot name a realm (letters, digits, '.', '-')`);
+  }
+  await saveConfig({ ...cfg, controlPlane: { url, name: parsed.data.controlPlane.name, secret: parsed.data.hostSecret, advertise, port } }, p);
+  return { hostName: name, controlPlane: parsed.data.controlPlane.name, hostUrl };
+}
+async function leaveControlPlane(p = paths()) {
+  const cfg = await loadConfig(p);
+  const cp = cfg.controlPlane;
+  if (!cp) throw new KvboxError("this host has not joined a control plane");
+  const told = await request(`${cp.url}/hosts/self`, {
+    method: "DELETE",
+    headers: { authorization: `Bearer ${cp.secret}` },
+    headersTimeout: 3e3,
+    bodyTimeout: 3e3
+  }).then(async (res) => {
+    await res.body.dump();
+    return res.statusCode >= 200 && res.statusCode < 300;
+  }).catch(() => false);
+  const { controlPlane: _gone, ...rest } = cfg;
+  await saveConfig(rest, p);
+  return { controlPlane: cp.name, told };
+}
+function jsonOrNull(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function errorIn(text) {
+  const v = jsonOrNull(text);
+  if (v && typeof v === "object" && typeof v.error === "string") return v.error;
+  return void 0;
+}
+
 // src/core/network.ts
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 var TAP_PREFIX = "kv-";
 var PRIVILEGED_SCRIPT = "/usr/local/lib/kvbox/net-setup.sh";
 function tapName(box) {
@@ -275,41 +575,42 @@ function macFor(ip) {
 }
 
 // src/listen.ts
-import { rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
+import { readFile as readFile6, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
+import { createServer as createHttpsServer } from "node:https";
 import { createAdaptorServer } from "@hono/node-server";
 
 // src/core/state.ts
 import { randomBytes } from "node:crypto";
-import { mkdir, readFile as readFile2, readdir, writeFile as writeFile2 } from "node:fs/promises";
-import { z as z2 } from "zod";
-var MachineMetaSchema = z2.object({
+import { mkdir as mkdir2, readFile as readFile3, readdir, writeFile as writeFile2 } from "node:fs/promises";
+import { z as z3 } from "zod";
+var MachineMetaSchema = z3.object({
   /**
    * Host-unique, minted at `kvbox new` (fresh or restored) and kept for the box's life; the tap is
    * `kv-<id>`. Absent only on a box that predates ids and is still running on its `kv-<name>` tap:
    * `migrateBoxIds` gives stopped ones theirs at server start, a running one gets it when it next starts.
    */
-  id: z2.string().optional(),
-  name: z2.string(),
+  id: z3.string().optional(),
+  name: z3.string(),
   /** Part of the box's identity: machines/<owner>/<name>. See refs.ts. */
-  owner: z2.string(),
-  ip: z2.string(),
-  mac: z2.string(),
-  pid: z2.number().int().nullable(),
+  owner: z3.string(),
+  ip: z3.string(),
+  mac: z3.string(),
+  pid: z3.number().int().nullable(),
   // null: stopped on purpose, disk kept
-  vcpu: z2.number().int(),
-  memMib: z2.number().int(),
-  createdAt: z2.string(),
-  source: z2.string(),
+  vcpu: z3.number().int(),
+  memMib: z3.number().int(),
+  createdAt: z3.string(),
+  source: z3.string(),
   /** Base image version (assets/rootfs-<version>.ext4) the box overlays. Absent: a pre-overlay box with its own disk.ext4. */
-  base: z2.string().optional(),
+  base: z3.string().optional(),
   /**
    * Snapshots taken since this VM started (boot or restore). Firecracker resets its dirty-page bitmap at
    * each one, so when this is > 0 the next diff is only standalone merged onto `mem.base`; if that file
    * is missing the lineage is broken and the next snapshot has to be a full dump. Absent: 0.
    */
-  memSnapshots: z2.number().int().optional(),
+  memSnapshots: z3.number().int().optional(),
   /** `kvbox pause`: Firecracker is alive but the VM is frozen (standby). Absent: not paused. */
-  paused: z2.boolean().optional()
+  paused: z3.boolean().optional()
 });
 function newBoxId(taken) {
   for (; ; ) {
@@ -317,25 +618,25 @@ function newBoxId(taken) {
     if (!taken.has(id)) return id;
   }
 }
-var SnapshotMetaSchema = z2.object({
-  name: z2.string(),
-  owner: z2.string(),
+var SnapshotMetaSchema = z3.object({
+  name: z3.string(),
+  owner: z3.string(),
   /** The box it was taken from, as owner/name. */
-  source: z2.string(),
-  base: z2.string(),
-  vcpu: z2.number().int(),
-  memMib: z2.number().int(),
-  sizeBytes: z2.number().int(),
-  createdAt: z2.string()
+  source: z3.string(),
+  base: z3.string(),
+  vcpu: z3.number().int(),
+  memMib: z3.number().int(),
+  sizeBytes: z3.number().int(),
+  createdAt: z3.string()
 });
 async function ensureLayout(p = paths()) {
   for (const dir of [p.home, p.ssh, p.bin, p.assets, p.machines, p.snapshots]) {
-    await mkdir(dir, { recursive: true, mode: 448 });
+    await mkdir2(dir, { recursive: true, mode: 448 });
   }
   return p;
 }
 async function readJson(file, schema) {
-  return schema.parse(JSON.parse(await readFile2(file, "utf8")));
+  return schema.parse(JSON.parse(await readFile3(file, "utf8")));
 }
 async function listDirs(dir) {
   try {
@@ -351,7 +652,7 @@ async function readMachineMeta(ref, p = paths()) {
 }
 async function writeMachineMeta(meta, p = paths()) {
   const m = p.machine(meta.owner, meta.name);
-  await mkdir(m.dir, { recursive: true });
+  await mkdir2(m.dir, { recursive: true });
   await writeFile2(m.meta, JSON.stringify(meta, null, 2) + "\n");
 }
 async function listMachineRefs(p = paths()) {
@@ -362,7 +663,7 @@ async function readSnapshotMeta(ref, p = paths()) {
 }
 async function writeSnapshotMeta(meta, p = paths()) {
   const s = p.snapshot(meta.owner, meta.name);
-  await mkdir(s.dir, { recursive: true });
+  await mkdir2(s.dir, { recursive: true });
   await writeFile2(s.meta, JSON.stringify(meta, null, 2) + "\n");
 }
 async function listSnapshotRefs(p = paths()) {
@@ -389,7 +690,7 @@ function pidAlive(pid) {
 
 // src/core/migrate.ts
 import { existsSync as existsSync2 } from "node:fs";
-import { mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rename, writeFile as writeFile3 } from "node:fs/promises";
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, rename as rename2, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join2 } from "node:path";
 
 // src/core/db.ts
@@ -492,8 +793,8 @@ async function migrateOwnerLayout(owner, p = paths()) {
       // a restored box names its snapshot: that moved under the same owner
       source: typeof meta["source"] === "string" && meta["source"].startsWith("snapshot:") && !meta["source"].includes("/") ? `snapshot:${owner}/${meta["source"].slice("snapshot:".length)}` : meta["source"]
     }));
-    await mkdir2(p.ownerMachines(owner), { recursive: true, mode: 448 });
-    await rename(from, to);
+    await mkdir3(p.ownerMachines(owner), { recursive: true, mode: 448 });
+    await rename2(from, to);
     done.boxes.push(name);
   }
   for (const name of await oldDepthEntries(p.snapshots)) {
@@ -508,8 +809,8 @@ async function migrateOwnerLayout(owner, p = paths()) {
       owner,
       source: typeof meta["source"] === "string" && !meta["source"].includes("/") ? `${owner}/${meta["source"]}` : meta["source"]
     }));
-    await mkdir2(p.ownerSnapshots(owner), { recursive: true, mode: 448 });
-    await rename(from, to);
+    await mkdir3(p.ownerSnapshots(owner), { recursive: true, mode: 448 });
+    await rename2(from, to);
     done.snapshots.push(name);
   }
   return done;
@@ -525,7 +826,7 @@ async function oldDepthEntries(root) {
   return entries.filter((e) => e.isDirectory() && existsSync2(join2(root, e.name, "meta.json"))).map((e) => e.name).sort();
 }
 async function patchJson(file, patch) {
-  const raw = JSON.parse(await readFile3(file, "utf8"));
+  const raw = JSON.parse(await readFile4(file, "utf8"));
   await writeFile3(file, JSON.stringify(patch(raw), null, 2) + "\n");
 }
 async function migrateBoxIds(p = paths()) {
@@ -561,7 +862,7 @@ async function adoptBoxId(meta, taken, p = paths()) {
 // src/core/machines.ts
 import { spawn } from "node:child_process";
 import { closeSync as closeSync2, existsSync as existsSync3, openSync as openSync2, statSync } from "node:fs";
-import { link, mkdir as mkdir3, readFile as readFile4, realpath, rm, truncate, writeFile as writeFile4 } from "node:fs/promises";
+import { link, mkdir as mkdir4, readFile as readFile5, realpath, rm, truncate, writeFile as writeFile4 } from "node:fs/promises";
 import { basename } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
@@ -617,8 +918,12 @@ function setIdentity(udsPath, id, timeoutMs) {
 
 // src/core/capacity.ts
 import { cpus, totalmem } from "node:os";
+
+// ../shared/src/capacity.ts
 var MEM_HEADROOM_MIB = 2048;
 var VCPU_OVERSUBSCRIPTION = 2;
+
+// src/core/capacity.ts
 function hostResources() {
   return { memMib: Math.floor(totalmem() / 1024 ** 2), cores: cpus().length };
 }
@@ -676,7 +981,7 @@ async function assertRoomFor(vcpu, memMib, force, p = paths()) {
 }
 
 // src/core/firecracker.ts
-import { Agent, request } from "undici";
+import { Agent, request as request2 } from "undici";
 var FirecrackerClient = class {
   constructor(socketPath) {
     this.socketPath = socketPath;
@@ -685,7 +990,7 @@ var FirecrackerClient = class {
   socketPath;
   agent;
   async call(method, path, body) {
-    const res = await request(`http://localhost${path}`, {
+    const res = await request2(`http://localhost${path}`, {
       dispatcher: this.agent,
       method,
       headers: body === void 0 ? {} : { "content-type": "application/json" },
@@ -878,8 +1183,8 @@ async function readAllMeta(p) {
   }
   return metas;
 }
-async function listMachines(owner, p = paths()) {
-  return (await readAllMeta(p)).filter((m) => owner === null || m.owner === owner).map((m) => toMachine(m, p));
+async function listMachines(scope, p = paths()) {
+  return (await readAllMeta(p)).filter((m) => inScope(m.owner, scope)).map((m) => toMachine(m, p));
 }
 async function getMachine(ref, p = paths()) {
   return toMachine(await readMeta(ref, p), p);
@@ -945,7 +1250,7 @@ async function waitFor(pred, timeoutMs, stepMs = 50) {
 }
 async function tailOf(file, lines = 5) {
   try {
-    return (await readFile4(file, "utf8")).trim().split("\n").slice(-lines).join("\n");
+    return (await readFile5(file, "utf8")).trim().split("\n").slice(-lines).join("\n");
   } catch {
     return "";
   }
@@ -1044,11 +1349,11 @@ async function currentBaseVersion(p = paths()) {
   return (await currentBase(await loadConfig(p), p)).version;
 }
 async function namesOverlayAbsolutely(vmstate) {
-  return (await readFile4(vmstate)).includes(`/${OVERLAY_REL}`);
+  return (await readFile5(vmstate)).includes(`/${OVERLAY_REL}`);
 }
 async function readPubkeyB64(p) {
   try {
-    return Buffer.from((await readFile4(`${p.sshKey}.pub`, "utf8")).trim()).toString("base64");
+    return Buffer.from((await readFile5(`${p.sshKey}.pub`, "utf8")).trim()).toString("base64");
   } catch {
     throw new KvboxError(`SSH key missing at ${p.sshKey}.pub; run install-server.sh`);
   }
@@ -1076,7 +1381,7 @@ async function createMachine(req, owner, p = paths()) {
   const base = await currentBase(cfg, p);
   await assertOverlayCapable(base.file, base.version);
   await ensureHostNetwork(cfg);
-  await mkdir3(m.dir, { recursive: true, mode: 448 });
+  await mkdir4(m.dir, { recursive: true, mode: 448 });
   let tapCreated = false;
   try {
     await createOverlay(m.overlay, size.diskGib);
@@ -1124,7 +1429,7 @@ async function restoreMachine(fromText, owner, req, cfg, p) {
   const m = p.machine(owner, name);
   const s = p.snapshot(from.owner, from.name);
   await ensureHostNetwork(cfg);
-  await mkdir3(m.dir, { recursive: true, mode: 448 });
+  await mkdir4(m.dir, { recursive: true, mode: 448 });
   let tapCreated = false;
   let pid;
   try {
@@ -1282,7 +1587,7 @@ async function hibernateMachine(ref, p = paths()) {
   if (meta.base === void 0) throw new KvboxError(`box ${shown(ref)} was made before overlays and runs on its own disk copy; it cannot be hibernated`);
   const m = p.machine(ref.owner, ref.name);
   await rm(m.hibernateDir, { recursive: true, force: true });
-  await mkdir3(m.hibernateDir, { recursive: true, mode: 448 });
+  await mkdir4(m.hibernateDir, { recursive: true, mode: 448 });
   const fc = new FirecrackerClient(m.sock);
   try {
     try {
@@ -1417,6 +1722,10 @@ async function destroyMachine(ref, p = paths()) {
 
 // src/core/usage.ts
 var HOUR_MS = 36e5;
+function ledgerState(status) {
+  if (status === "unknown") throw new Error("a box on this host cannot be in state unknown");
+  return status;
+}
 var round = (n, places) => Math.round(n * 10 ** places) / 10 ** places;
 function computeUsage(events, w) {
   const sorted = [...events].sort((a, b) => a.at < b.at ? -1 : a.at > b.at ? 1 : 0);
@@ -1465,7 +1774,7 @@ async function machineUsage(ref, since, p = paths()) {
   let events = usageEventsFor(boxId, box.createdAt, p);
   if (events.length === 0) {
     insertUsageEvent(
-      { boxId, owner: box.owner, name: box.name, at: now, state: box.status, by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
+      { boxId, owner: box.owner, name: box.name, at: now, state: ledgerState(box.status), by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
       p
     );
     events = usageEventsFor(boxId, box.createdAt, p);
@@ -1479,7 +1788,7 @@ async function seedUsageLedger(p = paths()) {
     const boxId = box.id ?? `${box.owner}/${box.name}`;
     if (usageEventsFor(boxId, box.createdAt, p).length > 0) continue;
     insertUsageEvent(
-      { boxId, owner: box.owner, name: box.name, at: (/* @__PURE__ */ new Date()).toISOString(), state: box.status, by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
+      { boxId, owner: box.owner, name: box.name, at: (/* @__PURE__ */ new Date()).toISOString(), state: ledgerState(box.status), by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
       p
     );
     seeded += 1;
@@ -1503,16 +1812,46 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.2.0" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.3.0" : void 0);
 
 // src/caller.ts
-function resolveCaller() {
+import { createHash, timingSafeEqual } from "node:crypto";
+var OWNER_HEADER = "x-kvbox-owner";
+function resolveCaller(opts = {}) {
+  const cp = opts.controlPlane;
+  if (!cp) {
+    return async (c, next) => {
+      const cfg = await loadConfig();
+      c.set("owner", cfg.owner);
+      c.set("listScope", cfg.owner);
+      await next();
+    };
+  }
+  const expected = digest(cp.secret);
   return async (c, next) => {
-    const cfg = await loadConfig();
-    c.set("owner", cfg.owner);
+    const m = /^Bearer\s+(\S+)$/i.exec(c.req.header("authorization") ?? "");
+    if (!m || !timingSafeEqual(digest(m[1]), expected)) return c.json({ error: "not authorized" }, 401);
+    const user = c.req.header(OWNER_HEADER);
+    if (user === void 0) {
+      const path = c.req.path.replace(/\/$/, "");
+      const realmListing = c.req.method === "GET" && (path === "/machines" || path === "/snapshots");
+      if (!realmListing && /^\/(machines|snapshots)(\/|$)/.test(c.req.path)) {
+        return c.json({ error: "X-Kvbox-Owner header required" }, 400);
+      }
+      c.set("owner", "");
+      c.set("listScope", { realm: cp.name });
+    } else {
+      if (!LOCAL_OWNER_RE.test(user)) return c.json({ error: "X-Kvbox-Owner: letters, digits, '.', '_', '-'" }, 400);
+      const owner = `${user}@${cp.name}`;
+      c.set("owner", owner);
+      c.set("listScope", owner);
+    }
     await next();
   };
 }
+function digest(secret) {
+  return createHash("sha256").update(secret).digest();
+}
 
 // src/routes/capacity.ts
 import { Hono } from "hono";
@@ -1524,141 +1863,9 @@ function capacityRoutes() {
 
 // src/routes/machines.ts
 import { Hono as Hono2 } from "hono";
-
-// ../shared/src/api.ts
-import { z as z3 } from "zod";
-var SizeSchema = z3.enum(SIZE_NAMES);
-var BoxStatusSchema = z3.enum(["running", "standby", "hibernated", "stopped"]);
-var MachineSchema = z3.object({
-  /** Host-unique short id (the tap is `kv-<id>`). Missing only on a box made before ids that has not restarted since. */
-  id: z3.string().optional(),
-  name: z3.string(),
-  /** Who the box belongs to; names are unique per owner. A bare name is local to the host, `user@control-plane` later. */
-  owner: z3.string(),
-  ip: z3.string(),
-  mac: z3.string(),
-  pid: z3.number().int().nullable(),
-  vcpu: z3.number().int(),
-  memMib: z3.number().int(),
-  diskBytes: z3.number().int(),
-  // the box's own writable disk, as the guest sees it
-  diskUsedBytes: z3.number().int(),
-  // what that sparse file really occupies on the host
-  base: z3.string().nullable(),
-  // base image version the box runs on (null: pre-overlay box with its own copy)
-  createdAt: z3.string(),
-  source: z3.string(),
-  // "base" or "snapshot:<name>"
-  status: BoxStatusSchema
-});
-var CreateMachineRequest = z3.object({
-  name: z3.string().optional(),
-  /** Ignored over the local socket (the caller is the host owner); the control plane sets it over HTTPS. */
-  owner: z3.string().optional(),
-  size: SizeSchema.optional(),
-  from: z3.string().optional(),
-  force: z3.boolean().optional()
-});
-var RescaleMachineRequest = z3.object({
-  size: SizeSchema.optional(),
-  vcpu: z3.number().int().min(1).max(64).optional(),
-  memMib: z3.number().int().min(256).optional(),
-  diskGib: z3.number().int().min(1).optional()
-});
-var SnapshotSchema = z3.object({
-  name: z3.string(),
-  owner: z3.string(),
-  source: z3.string(),
-  // the box it was taken from, as owner/name
-  base: z3.string(),
-  // base image version the overlay stacks on; a restore needs the same one
-  vcpu: z3.number().int(),
-  memMib: z3.number().int(),
-  sizeBytes: z3.number().int(),
-  // what vmstate + mem + overlay really occupy on the host
-  createdAt: z3.string()
-});
-var CreateSnapshotRequest = z3.object({
-  box: z3.string(),
-  name: z3.string()
-});
-var CapacitySchema = z3.object({
-  hostMemMib: z3.number().int(),
-  hostCores: z3.number().int(),
-  reservedMemMib: z3.number().int(),
-  reservedVcpu: z3.number().int(),
-  running: z3.number().int()
-});
-var HealthSchema = z3.object({
-  ok: z3.literal(true),
-  version: z3.string(),
-  pid: z3.number().int(),
-  /** Base image version new boxes get (null when the host has no usable base image yet); absent from older servers. */
-  base: z3.string().nullable().optional(),
-  /** Owner that boxes made over the local socket get (the Unix user running the server); absent from older servers. */
-  owner: z3.string().optional()
-});
-var MachineUsageSchema = z3.object({
-  name: z3.string(),
-  owner: z3.string(),
-  status: BoxStatusSchema,
-  window: z3.object({ from: z3.string(), to: z3.string() }),
-  /** standby and hibernated default to 0 so a newer CLI reads an older server's answer. */
-  seconds: z3.object({
-    running: z3.number().int(),
-    standby: z3.number().int().default(0),
-    hibernated: z3.number().int().default(0),
-    stopped: z3.number().int()
-  }),
-  vcpuHours: z3.number(),
-  ramGibHours: z3.number(),
-  diskGibHours: z3.number(),
-  cost: z3.object({ amount: z3.number(), currency: z3.string() }).optional(),
-  /** Stops the server did not witness (Firecracker died, host rebooted) and dated to when it noticed. */
-  estimatedStops: z3.number().int(),
-  historyFrom: z3.string().nullable()
-});
-var ApiErrorSchema = z3.object({
-  error: z3.string()
-});
-var CloudUserSchema = z3.object({
-  name: z3.string(),
-  role: z3.enum(["admin", "user"]),
-  createdAt: z3.string()
-});
-var LoginRequestSchema = z3.object({
-  name: z3.string().min(1),
-  password: z3.string().min(1),
-  publicKey: z3.string().optional()
-});
-var LoginResponseSchema = z3.object({
-  token: z3.string(),
-  user: CloudUserSchema
-});
-var HostJoinRequestSchema = z3.object({
-  token: z3.string().min(1),
-  name: z3.string().min(1),
-  url: z3.string().url(),
-  fingerprint: z3.string().regex(/^([0-9A-F]{2}:){31}[0-9A-F]{2}$/),
-  publicAddress: z3.string().min(1)
-});
-var HostJoinResponseSchema = z3.object({
-  hostSecret: z3.string(),
-  controlPlane: z3.object({ name: z3.string() })
-});
-var CloudHostSchema = z3.object({
-  name: z3.string(),
-  url: z3.string(),
-  publicAddress: z3.string(),
-  joinedAt: z3.string(),
-  lastSeenAt: z3.string().nullable(),
-  capacity: CapacitySchema.nullable()
-});
-
-// src/routes/machines.ts
 function machineRoutes() {
   const r = new Hono2();
-  r.get("/", async (c) => c.json(await listMachines(c.get("owner"))));
+  r.get("/", async (c) => c.json(await listMachines(c.get("listScope"))));
   r.post("/", async (c) => {
     const body = CreateMachineRequest.parse(await c.req.json().catch(() => ({})));
     return c.json(await createMachine(body, c.get("owner")), 201);
@@ -1696,7 +1903,7 @@ import { Hono as Hono3 } from "hono";
 
 // src/core/snapshots.ts
 import { existsSync as existsSync4 } from "node:fs";
-import { link as link2, mkdir as mkdir4, readdir as readdir3, rename as rename2, rm as rm2, stat } from "node:fs/promises";
+import { link as link2, mkdir as mkdir5, readdir as readdir3, rename as rename3, rm as rm2, stat } from "node:fs/promises";
 var NAME_RE2 = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 function toSnapshot(meta) {
   return {
@@ -1710,10 +1917,10 @@ function toSnapshot(meta) {
     createdAt: meta.createdAt
   };
 }
-async function listSnapshots(owner, p = paths()) {
+async function listSnapshots(scope, p = paths()) {
   const out = [];
   for (const ref of await listSnapshotRefs(p)) {
-    if (owner !== null && ref.owner !== owner) continue;
+    if (!inScope(ref.owner, scope)) continue;
     try {
       out.push(toSnapshot(await readSnapshotMeta(ref, p)));
     } catch (err) {
@@ -1755,7 +1962,7 @@ async function saveSnapshot(req, owner, p = paths()) {
   if (existsSync4(s.dir)) throw new KvboxError(`snapshot ${req.name} already exists`);
   const cfg = await loadConfig(p);
   const m = p.machine(box.owner, box.name);
-  await mkdir4(s.dir, { recursive: true, mode: 448 });
+  await mkdir5(s.dir, { recursive: true, mode: 448 });
   const fc = new FirecrackerClient(m.sock);
   let lineageTouched = false;
   try {
@@ -1811,7 +2018,7 @@ async function mergeOntoPrevious(previous, diffFile, editor) {
   const merged = `${diffFile}.merged`;
   await run(["cp", "--sparse=always", "--reflink=auto", previous, merged]);
   await run([editor, "edit-memory", "rebase", "--memory-path", merged, "--diff-path", diffFile]);
-  await rename2(merged, diffFile);
+  await rename3(merged, diffFile);
 }
 async function deleteSnapshot(ref, p = paths()) {
   const dir = p.snapshot(ref.owner, ref.name).dir;
@@ -1822,7 +2029,7 @@ async function deleteSnapshot(ref, p = paths()) {
 // src/routes/snapshots.ts
 function snapshotRoutes() {
   const r = new Hono3();
-  r.get("/", async (c) => c.json(await listSnapshots(c.get("owner"))));
+  r.get("/", async (c) => c.json(await listSnapshots(c.get("listScope"))));
   r.post("/", async (c) => {
     const body = CreateSnapshotRequest.parse(await c.req.json());
     return c.json(await saveSnapshot(body, c.get("owner")), 201);
@@ -1835,9 +2042,9 @@ function snapshotRoutes() {
 }
 
 // src/app.ts
-function createApp() {
+function createApp(opts = {}) {
   const app = new Hono4();
-  app.use(resolveCaller());
+  app.use(resolveCaller(opts));
   app.get(
     "/health",
     async (c) => c.json({
@@ -1888,22 +2095,60 @@ async function listen(opts = {}) {
   });
   await writeFile5(p.serverPid, `${process.pid}
 `);
+  let https;
+  let httpsServer;
+  const cp = cfg.controlPlane;
+  if (cp) {
+    const [key, cert] = await Promise.all([readFile6(p.tlsKey), readFile6(p.tlsCert)]).catch((err) => {
+      throw new KvboxError(`joined ${cp.name} but the host's certificate is missing (${err.message}); run kvbox-server leave, then join again`);
+    });
+    httpsServer = createAdaptorServer({
+      fetch: createApp({ controlPlane: { name: cp.name, secret: cp.secret } }).fetch,
+      createServer: createHttpsServer,
+      serverOptions: { key, cert }
+    });
+    const port = opts.httpsPort ?? cp.port;
+    await new Promise((resolve, reject) => {
+      httpsServer.once("error", reject);
+      httpsServer.listen(port, "0.0.0.0", () => resolve());
+    }).catch(async (err) => {
+      server.close();
+      await rm3(socketPath, { force: true });
+      await rm3(p.serverPid, { force: true });
+      throw new KvboxError(`cannot listen on port ${port} for ${cp.name} (${err.message})`);
+    });
+    const bound = httpsServer.address().port;
+    https = { port: bound, url: `https://${cp.advertise}:${bound}` };
+  }
+  const close = async () => {
+    await Promise.all([
+      new Promise((resolve) => server.close(() => resolve())),
+      httpsServer ? new Promise((resolve) => httpsServer.close(() => resolve())) : void 0
+    ]);
+    await rm3(socketPath, { force: true });
+    await rm3(p.serverPid, { force: true });
+  };
   const shutdown2 = async () => {
     server.close();
+    httpsServer?.close();
     await rm3(socketPath, { force: true });
     await rm3(p.serverPid, { force: true });
     process.exit(0);
   };
   process.once("SIGINT", () => void shutdown2());
   process.once("SIGTERM", () => void shutdown2());
-  return { socketPath, server };
+  return https ? { socketPath, server, https, close } : { socketPath, server, close };
 }
 
 // src/index.ts
 var program = new Command("kvbox-server").description("kvbox host daemon: owns Firecracker and ~/.kvbox, serves the kvbox API").version(VERSION, "-v, --version").showHelpAfterError();
 program.command("start", { isDefault: true }).description("serve the API on the local Unix socket (foreground)").option("--socket <path>", "socket to listen on (default: $KVBOX_HOME/server.sock)").action(async (opts) => {
-  const { socketPath } = await listen(opts.socket ? { socketPath: opts.socket } : {});
+  const { socketPath, https } = await listen(opts.socket ? { socketPath: opts.socket } : {});
   console.log(`kvbox-server ${VERSION} listening on ${socketPath} (pid ${process.pid})`);
+  if (https) {
+    const cfg = await loadConfig(paths());
+    console.log(`control plane ${cfg.controlPlane?.name}: answering on ${https.url}`);
+  }
   try {
     const cfg = await loadConfig(paths());
     const state = await ensureHostNetwork(cfg);
@@ -1912,6 +2157,17 @@ program.command("start", { isDefault: true }).description("serve the API on the
     console.error(`warning: host network not ready (${err.message}); run: kvbox-server net up`);
   }
 });
+program.command("join <control-plane-url>").description("register this host with a control plane (needs a one-time token minted there); it answers the control plane from its next start").requiredOption("--token <token>", "one-time join token from the control plane").option("--advertise <host-or-ip>", "address the control plane reaches this host at (default: this host's default-route address)").option("--name <name>", "how the control plane lists this host (default: hostname)").action(async (url, opts) => {
+  const joined = await joinControlPlane({ url, ...opts }, paths());
+  console.log(`joined ${joined.controlPlane} as host ${joined.hostName}`);
+  console.log(`it answers the control plane on ${joined.hostUrl} from its next start: run \`kvbox server stop\`; the next kvbox command starts it again`);
+  console.log(`make sure port ${new URL(joined.hostUrl).port} is reachable from the control plane`);
+});
+program.command("leave").description("forget the control plane this host joined; the HTTPS port closes at the next start").action(async () => {
+  const left = await leaveControlPlane(paths());
+  console.log(`left ${left.controlPlane}; the HTTPS port closes at the next start`);
+  if (!left.told) console.log(`(the control plane could not be told; remove this host there)`);
+});
 program.command("net <action>").description("host network: up | down | status (bridge, forwarding, NAT; uses sudo)").action(async (action) => {
   if (!["up", "down", "status"].includes(action)) throw new KvboxError("net: expected up, down or status");
   const cfg = await loadConfig(paths());