@kvbox/server 0.5.5 → 0.5.7

package/dist/kvbox-server.js

@@ -102,7 +102,7 @@ function paths(home = kvboxHome()) {
 
 // src/core/config.ts
 import { chmod, readFile, rename, writeFile } from "node:fs/promises";
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // ../shared/src/sizes.ts
 var SIZES = {
@@ -116,6 +116,107 @@ function isSizeName(value) {
   return value in SIZES;
 }
 
+// ../shared/src/usage.ts
+import { z } from "zod";
+var PricingSchema = z.object({
+  currency: z.string().min(1),
+  vcpuHour: z.number().nonnegative(),
+  ramGibHour: z.number().nonnegative(),
+  diskGibHour: z.number().nonnegative()
+});
+var HOUR_MS = 36e5;
+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);
+  const from = Date.parse(w.from);
+  const to = Date.parse(w.to);
+  const ms = { running: 0, standby: 0, hibernated: 0, stopped: 0 };
+  let vcpuHours = 0;
+  let ramGibHours = 0;
+  let diskGibHours = 0;
+  sorted.forEach((e, i) => {
+    const start = Math.max(Date.parse(e.at), from);
+    const next = sorted[i + 1];
+    const end = Math.min(next === void 0 ? to : Date.parse(next.at), to);
+    if (end <= start) return;
+    const h = (end - start) / HOUR_MS;
+    ms[e.state] += end - start;
+    if (e.state === "running") vcpuHours += h * e.vcpu;
+    if (e.state === "running" || e.state === "standby") ramGibHours += h * e.memMib / 1024;
+    diskGibHours += h * e.diskGib;
+  });
+  const totals = {
+    seconds: {
+      running: Math.round(ms.running / 1e3),
+      standby: Math.round(ms.standby / 1e3),
+      hibernated: Math.round(ms.hibernated / 1e3),
+      stopped: Math.round(ms.stopped / 1e3)
+    },
+    vcpuHours: round(vcpuHours, 3),
+    ramGibHours: round(ramGibHours, 3),
+    diskGibHours: round(diskGibHours, 3),
+    estimatedStops: sorted.filter((e) => e.state === "stopped" && e.by === "server" && e.at >= w.from).length,
+    historyFrom: sorted[0]?.at ?? null
+  };
+  if (w.pricing !== void 0) totals.cost = { amount: round(costOf(totals, w.pricing), 4), currency: w.pricing.currency };
+  return totals;
+}
+function costOf(t, pricing) {
+  return t.vcpuHours * pricing.vcpuHour + t.ramGibHours * pricing.ramGibHour + t.diskGibHours * pricing.diskGibHour;
+}
+function sumUsage(items, pricing) {
+  const sum = {
+    seconds: { running: 0, standby: 0, hibernated: 0, stopped: 0 },
+    vcpuHours: 0,
+    ramGibHours: 0,
+    diskGibHours: 0
+  };
+  for (const t of items) {
+    for (const s of Object.keys(sum.seconds)) sum.seconds[s] += t.seconds[s];
+    sum.vcpuHours += t.vcpuHours;
+    sum.ramGibHours += t.ramGibHours;
+    sum.diskGibHours += t.diskGibHours;
+  }
+  sum.vcpuHours = round(sum.vcpuHours, 3);
+  sum.ramGibHours = round(sum.ramGibHours, 3);
+  sum.diskGibHours = round(sum.diskGibHours, 3);
+  if (pricing !== void 0) sum.cost = { amount: round(costOf(sum, pricing), 4), currency: pricing.currency };
+  return sum;
+}
+function usageWindow(since, until, now = /* @__PURE__ */ new Date()) {
+  const parse = (name, value) => {
+    const t = Date.parse(value);
+    if (Number.isNaN(t)) throw new Error(`${name}: "${value}" is not a date; write it like 2026-10-19 or 2026-10-19T08:00:00Z`);
+    return new Date(t).toISOString();
+  };
+  const from = since === void 0 ? new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString() : parse("since", since);
+  const to = until === void 0 ? now.toISOString() : parse("until", until);
+  return { from, to };
+}
+function groupUsage(rows, window, pricing, live = /* @__PURE__ */ new Map()) {
+  const byBox = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const key = r.ledger === void 0 ? r.boxId : `${r.ledger}:${r.boxId}`;
+    const list = byBox.get(key);
+    if (list === void 0) byBox.set(key, [r]);
+    else list.push(r);
+  }
+  const out = [];
+  for (const events of byBox.values()) {
+    events.sort((a, b) => a.at < b.at ? -1 : a.at > b.at ? 1 : 0);
+    const first = events[0];
+    const last = events[events.length - 1];
+    const id = last.boxId;
+    const removed = last.by === "rm" && !live.has(id);
+    const to = removed && last.at < window.to ? last.at : window.to;
+    if (first.at >= to || removed && last.at <= window.from) continue;
+    const totals = computeUsage(events, { from: window.from, to, pricing });
+    const status = live.get(id) ?? (removed ? "removed" : last.state);
+    out.push({ id, name: last.name, owner: last.owner, status, ...totals });
+  }
+  return out.sort((a, b) => a.owner.localeCompare(b.owner) || a.name.localeCompare(b.name) || (a.historyFrom ?? "").localeCompare(b.historyFrom ?? ""));
+}
+
 // src/core/refs.ts
 import { userInfo } from "node:os";
 function shown(ref) {
@@ -161,41 +262,35 @@ function refKey(ref) {
 }
 
 // src/core/config.ts
-var PricingSchema = z.object({
-  currency: z.string().min(1),
-  vcpuHour: z.number().nonnegative(),
-  ramGibHour: z.number().nonnegative(),
-  diskGibHour: z.number().nonnegative()
-});
-var ControlPlaneSchema = z.object({
-  url: z.string().url(),
+var ControlPlaneSchema = z2.object({
+  url: z2.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),
+  name: z2.string().regex(REALM_RE),
   /** Minted at join; every HTTPS call from the control plane carries it as a bearer. */
-  secret: z.string().min(1),
+  secret: z2.string().min(1),
   /** The address the control plane reaches this host at. */
-  advertise: z.string().min(1),
-  port: z.number().int().positive().default(7777)
+  advertise: z2.string().min(1),
+  port: z2.number().int().positive().default(7777)
 });
-var RelaySchema = z.object({
-  name: z.string().min(1),
-  publicIp: z.string().min(1),
-  tunnelIp: z.string().min(1),
+var RelaySchema = z2.object({
+  name: z2.string().min(1),
+  publicIp: z2.string().min(1),
+  tunnelIp: z2.string().min(1),
   /** `<relay-ip>:<port>` the tunnel dials. */
-  endpoint: z.string().min(1)
+  endpoint: z2.string().min(1)
 });
-var ConfigSchema = z.object({
-  kernel: z.string(),
-  rootfs: z.string(),
-  firecracker: z.string(),
-  snapshotEditor: z.string().optional(),
+var ConfigSchema = z2.object({
+  kernel: z2.string(),
+  rootfs: z2.string(),
+  firecracker: z2.string(),
+  snapshotEditor: z2.string().optional(),
   // default: bin/snapshot-editor next to firecracker
-  bridge: z.string().default("kvbox0"),
-  subnet: z.string().default("172.30.0.0/24"),
-  gateway: z.string().default("172.30.0.1"),
-  defaultSize: z.enum(SIZE_NAMES).default(DEFAULT_SIZE),
+  bridge: z2.string().default("kvbox0"),
+  subnet: z2.string().default("172.30.0.0/24"),
+  gateway: z2.string().default("172.30.0.1"),
+  defaultSize: z2.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),
+  owner: z2.string().regex(LOCAL_OWNER_RE, "owner: letters, digits, '.', '_', '-'; no '@' or '/'").default(localOwner),
   pricing: PricingSchema.optional(),
   /** Absent until the host joins a control plane; then the server also listens on HTTPS. */
   controlPlane: ControlPlaneSchema.optional(),
@@ -239,247 +334,321 @@ 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({
+import { z as z3 } from "zod";
+var SizeSchema = z3.enum(SIZE_NAMES);
+var BoxStatusSchema = z3.enum(["running", "standby", "hibernated", "stopped", "unknown"]);
+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: z2.string(),
-  name: z2.string(),
+  id: z3.string(),
+  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: 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(),
+  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: z2.number().int(),
+  diskUsedBytes: z3.number().int(),
   // what that sparse file really occupies on the host
-  base: z2.string(),
+  base: z3.string(),
   // base image version the box's overlay stacks on
-  createdAt: z2.string(),
-  source: z2.string(),
+  createdAt: z3.string(),
+  source: z3.string(),
   // "base" or "snapshot:<name>"
   status: BoxStatusSchema,
   /**
    * Public TCP port on the host that reaches the box's SSH while it runs (#49). Only boxes made
    * through a control plane have one; the control plane adds the host's address for `connect` (#21).
    */
-  sshPort: z2.number().int().optional(),
+  sshPort: z3.number().int().optional(),
   /**
    * Where `ssh` reaches the box from outside: the host's public address and that port (#21). Only
    * the control plane fills it in (a host does not know its own public address); absent for a box
    * whose host reported no port or did not answer.
    */
-  ssh: z2.object({ host: z2.string(), port: z2.number().int(), user: z2.string() }).optional(),
+  ssh: z3.object({ host: z3.string(), port: z3.number().int(), user: z3.string() }).optional(),
   /** Whether the owner slug is a user or an org. Only the control plane knows; it fills it in on `GET /machines`. */
-  ownerKind: z2.enum(["user", "org"]).optional()
+  ownerKind: z3.enum(["user", "org"]).optional()
 });
-var CreateMachineRequest = z2.object({
-  name: z2.string().optional(),
+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: z2.string().optional(),
+  owner: z3.string().optional(),
   size: SizeSchema.optional(),
-  from: z2.string().optional(),
-  force: z2.boolean().optional(),
+  from: z3.string().optional(),
+  force: z3.boolean().optional(),
   /**
    * Extra authorized_keys lines for the box, on top of the host's own key: the control plane sends
    * its SSH CA as one `cert-authority …` line (#51). Written into the box's authorized_keys at every
    * boot (#49); a host older than that ignores them.
    */
-  sshKeys: z2.array(z2.string()).optional()
+  sshKeys: z3.array(z3.string()).optional()
 });
-var SetSshKeysRequest = z2.object({
-  sshKeys: z2.array(z2.string())
+var SetSshKeysRequest = z3.object({
+  sshKeys: z3.array(z3.string())
 });
-var RescaleMachineRequest = z2.object({
+var RescaleMachineRequest = z3.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()
+  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 = z2.object({
-  name: z2.string(),
-  owner: z2.string(),
-  source: z2.string(),
+var SnapshotSchema = z3.object({
+  name: z3.string(),
+  owner: z3.string(),
+  source: z3.string(),
   // the box it was taken from, as owner/name
-  base: z2.string(),
+  base: z3.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(),
+  vcpu: z3.number().int(),
+  memMib: z3.number().int(),
+  sizeBytes: z3.number().int(),
   // what vmstate + mem + overlay really occupy on the host
-  createdAt: z2.string()
+  createdAt: z3.string()
 });
-var CreateSnapshotRequest = z2.object({
-  box: z2.string(),
-  name: z2.string()
+var CreateSnapshotRequest = z3.object({
+  box: z3.string(),
+  name: z3.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 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 = z2.object({
-  ok: z2.literal(true),
-  version: z2.string(),
-  pid: z2.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). */
-  base: z2.string().nullable(),
+  base: z3.string().nullable(),
   /** Owner that boxes made over the local socket get (the Unix user running the server). */
-  owner: z2.string(),
+  owner: z3.string(),
   /** The control plane this host joined (null when none). */
-  controlPlane: z2.object({
+  controlPlane: z3.object({
     /** Realm name, e.g. kvbox.sh. */
-    name: z2.string(),
-    url: z2.string(),
+    name: z3.string(),
+    url: z3.string(),
     /** Where this host answers the control plane. */
-    hostUrl: z2.string()
+    hostUrl: z3.string()
   }).nullable(),
   /** The relay this host reaches the internet through (#50); null when it has its own public address. Older servers omit it. */
-  relay: z2.object({
-    name: z2.string(),
+  relay: z3.object({
+    name: z3.string(),
     /** The public IP the relay owns for this host. */
-    publicIp: z2.string(),
+    publicIp: z3.string(),
     /** The relay's WireGuard endpoint the tunnel dials. */
-    endpoint: z2.string()
+    endpoint: z3.string()
   }).nullable().optional()
 });
-var MachineUsageSchema = z2.object({
-  name: z2.string(),
-  owner: z2.string(),
+var MachineUsageSchema = z3.object({
+  name: z3.string(),
+  owner: z3.string(),
   status: BoxStatusSchema,
-  window: z2.object({ from: z2.string(), to: z2.string() }),
-  seconds: z2.object({
-    running: z2.number().int(),
-    standby: z2.number().int(),
-    hibernated: z2.number().int(),
-    stopped: z2.number().int()
+  window: z3.object({ from: z3.string(), to: z3.string() }),
+  seconds: z3.object({
+    running: z3.number().int(),
+    standby: z3.number().int(),
+    hibernated: z3.number().int(),
+    stopped: z3.number().int()
   }),
-  vcpuHours: z2.number(),
-  ramGibHours: z2.number(),
-  diskGibHours: z2.number(),
-  cost: z2.object({ amount: z2.number(), currency: z2.string() }).optional(),
+  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: z2.number().int(),
-  historyFrom: z2.string().nullable()
+  estimatedStops: z3.number().int(),
+  historyFrom: z3.string().nullable()
+});
+var UsageStatusSchema = z3.enum([...BoxStatusSchema.options, "removed"]);
+var BoxUsageSchema = MachineUsageSchema.omit({ window: true, status: true }).extend({
+  /** The host's box id; a name removed and recreated appears twice, with two ids. */
+  id: z3.string(),
+  status: UsageStatusSchema,
+  /** Through a control plane: whether the owner slug is a user's or an org's (what `kvbox ls` shows). */
+  ownerKind: z3.enum(["user", "org"]).optional()
+});
+var UsageReportSchema = z3.object({
+  window: z3.object({ from: z3.string(), to: z3.string() }),
+  boxes: z3.array(BoxUsageSchema),
+  totals: z3.object({
+    seconds: MachineUsageSchema.shape.seconds,
+    vcpuHours: z3.number(),
+    ramGibHours: z3.number(),
+    diskGibHours: z3.number(),
+    cost: z3.object({ amount: z3.number(), currency: z3.string() }).optional()
+  })
+});
+var UsageEventRowSchema = z3.object({
+  id: z3.number().int(),
+  boxId: z3.string(),
+  owner: z3.string(),
+  name: z3.string(),
+  at: z3.string(),
+  state: z3.enum(["running", "standby", "hibernated", "stopped"]),
+  vcpu: z3.number().int(),
+  memMib: z3.number().int(),
+  diskGib: z3.number().int(),
+  by: z3.string()
+});
+var UsageEventsResponseSchema = z3.object({
+  ledger: z3.string().min(1),
+  events: z3.array(UsageEventRowSchema),
+  next: z3.number().int()
 });
-var ApiErrorSchema = z2.object({
-  error: z2.string()
+var ApiErrorSchema = z3.object({
+  error: z3.string()
 });
-var CloudUserSchema = z2.object({
+var ACTIVATED_BY = ["card", "admin"];
+var ActivatedBySchema = z3.enum(ACTIVATED_BY);
+var CloudUserSchema = z3.object({
   /** The handle: what hosts file boxes under (`<username>@<control plane>`). Lowercase, no `@` or `/`. */
-  username: z2.string(),
+  username: z3.string(),
   /** Display name, free text ("Alexandru Ghiura"). */
-  name: z2.string(),
+  name: z3.string(),
   /** Login identity, unique. */
-  email: z2.string(),
-  role: z2.enum(["admin", "user"]),
-  createdAt: z2.string()
+  email: z3.string(),
+  role: z3.enum(["admin", "user"]),
+  createdAt: z3.string(),
+  /**
+   * False until a card is on file or an admin activates the account (#74): then only `/me` and
+   * `/logout` answer. Admins are never gated. A control plane older than #74 does not send these and
+   * gates nobody, hence the defaults: a newer CLI must still parse its answers.
+   */
+  active: z3.boolean().default(true),
+  activatedBy: ActivatedBySchema.nullable().default(null)
 });
 var ORG_ROLES = ["owner", "admin", "member"];
-var OrgRoleSchema = z2.enum(ORG_ROLES);
-var CloudOrgSchema = z2.object({
-  slug: z2.string(),
+var OrgRoleSchema = z3.enum(ORG_ROLES);
+var CloudOrgSchema = z3.object({
+  slug: z3.string(),
   /** Display name; the slug never changes, this may. */
-  name: z2.string(),
-  createdAt: z2.string()
+  name: z3.string(),
+  createdAt: z3.string(),
+  /** An org pays for itself (#74): off until it has a card or an admin activates it; its boxes are 402. Defaults as on CloudUser. */
+  active: z3.boolean().default(true),
+  activatedBy: ActivatedBySchema.nullable().default(null)
 });
 var OrgMembershipSchema = CloudOrgSchema.extend({ role: OrgRoleSchema });
-var OrgMemberSchema = z2.object({
-  username: z2.string(),
-  name: z2.string(),
+var OrgMemberSchema = z3.object({
+  username: z3.string(),
+  name: z3.string(),
   role: OrgRoleSchema,
-  addedAt: z2.string()
+  addedAt: z3.string()
 });
-var OrgDetailSchema = CloudOrgSchema.extend({ members: z2.array(OrgMemberSchema) });
-var CreateOrgRequestSchema = z2.object({
-  slug: z2.string().min(1),
-  name: z2.string().min(1)
+var OrgDetailSchema = CloudOrgSchema.extend({ members: z3.array(OrgMemberSchema) });
+var CreateOrgRequestSchema = z3.object({
+  slug: z3.string().min(1),
+  name: z3.string().min(1)
 });
-var RenameOrgRequestSchema = z2.object({ name: z2.string().min(1) });
-var AddMemberRequestSchema = z2.object({
-  username: z2.string().min(1),
+var RenameOrgRequestSchema = z3.object({ name: z3.string().min(1) });
+var AddMemberRequestSchema = z3.object({
+  username: z3.string().min(1),
   role: OrgRoleSchema.default("member")
 });
-var SetRoleRequestSchema = z2.object({ role: OrgRoleSchema });
-var MeResponseSchema = CloudUserSchema.extend({ orgs: z2.array(OrgMembershipSchema) });
-var LoginRequestSchema = z2.object({
-  email: z2.string().min(1),
-  password: z2.string().min(1),
-  publicKey: z2.string().optional()
+var SetRoleRequestSchema = z3.object({ role: OrgRoleSchema });
+var MeResponseSchema = CloudUserSchema.extend({ orgs: z3.array(OrgMembershipSchema) });
+var BalanceSchema = z3.object({
+  slug: z3.string(),
+  balance: z3.number(),
+  currency: z3.string(),
+  topUps: z3.number(),
+  spent: z3.number(),
+  /** The first moment usage counts from: the slug's first top-up; null when it has none. */
+  since: z3.string().nullable(),
+  /** When the slug ran out and its boxes were hibernated (the `sweep-credit` job); null in good standing. Absent from a control plane older than this field. */
+  suspendedAt: z3.string().nullable().default(null)
 });
-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 TopUpRequestSchema = z3.object({
+  slug: z3.string().min(1),
+  /** In the control plane's currency; negative corrects a mistake. */
+  amount: z3.number().finite(),
+  note: z3.string().max(200).optional()
+});
+var TopUpSchema = z3.object({
+  id: z3.string(),
+  slug: z3.string(),
+  amount: z3.number(),
+  currency: z3.string(),
+  source: z3.enum(["admin", "card", "trial"]),
+  note: z3.string().nullable(),
+  at: z3.string()
+});
+var LoginRequestSchema = z3.object({
+  email: z3.string().min(1),
+  password: z3.string().min(1),
+  publicKey: z3.string().optional()
 });
-var LoginResponseSchema = z2.object({
-  token: z2.string(),
+var SignupRequestSchema = z3.object({
+  username: z3.string().min(1),
+  name: z3.string().min(1),
+  email: z3.string().min(1),
+  password: z3.string().min(1)
+});
+var LoginResponseSchema = z3.object({
+  token: z3.string(),
   user: CloudUserSchema,
-  sshCert: z2.string().optional(),
-  sshCertExpires: z2.string().optional(),
+  sshCert: z3.string().optional(),
+  sshCertExpires: z3.string().optional(),
   /** Whose boxes the certificate opens: `<slug>@<realm>` for the user and each org they are in (orgs phase 4). */
-  sshCertPrincipals: z2.array(z2.string()).optional()
+  sshCertPrincipals: z3.array(z3.string()).optional()
 });
-var SshCertRequestSchema = z2.object({
-  publicKey: z2.string().min(1)
+var SshCertRequestSchema = z3.object({
+  publicKey: z3.string().min(1)
 });
-var SshCertResponseSchema = z2.object({
-  cert: z2.string(),
-  expires: z2.string(),
-  principals: z2.array(z2.string())
+var SshCertResponseSchema = z3.object({
+  cert: z3.string(),
+  expires: z3.string(),
+  principals: z3.array(z3.string())
 });
-var SshCaResponseSchema = z2.object({
-  publicKey: z2.string(),
+var SshCaResponseSchema = z3.object({
+  publicKey: z3.string(),
   /** CAs replaced by `ca rotate` (#55), newest first; a box still holding one of these has not had `kvbox server trust-ca` run on its host. */
-  retired: z2.array(z2.object({ publicKey: z2.string(), retiredAt: z2.string() })).optional()
+  retired: z3.array(z3.object({ publicKey: z3.string(), retiredAt: z3.string() })).optional()
 });
-var HostSshCaResponseSchema = z2.object({
-  publicKey: z2.string()
+var HostSshCaResponseSchema = z3.object({
+  publicKey: z3.string()
 });
-var CloudCaSchema = z2.object({
-  controlPlane: z2.string(),
-  publicKey: z2.string(),
-  fingerprint: z2.string()
+var CloudCaSchema = z3.object({
+  controlPlane: z3.string(),
+  publicKey: z3.string(),
+  fingerprint: z3.string()
 });
-var TrustCaRequestSchema = z2.object({
-  publicKey: z2.string().min(1)
+var TrustCaRequestSchema = z3.object({
+  publicKey: z3.string().min(1)
 });
-var SshKeysAppliedSchema = z2.enum(["now", "start", "wake", "resume", "later"]);
-var TrustCaReportSchema = z2.object({
-  publicKey: z2.string(),
-  fingerprint: z2.string(),
+var SshKeysAppliedSchema = z3.enum(["now", "start", "wake", "resume", "later"]);
+var TrustCaReportSchema = z3.object({
+  publicKey: z3.string(),
+  fingerprint: z3.string(),
   /** The guest trusts the CA now. */
-  updated: z2.array(z2.string()),
+  updated: z3.array(z3.string()),
   /** meta.json has the line; the guest gets it at `when`. */
-  pending: z2.array(z2.object({ box: z2.string(), when: SshKeysAppliedSchema, why: z2.string().optional() })),
-  failed: z2.array(z2.object({ box: z2.string(), error: z2.string() })),
+  pending: z3.array(z3.object({ box: z3.string(), when: SshKeysAppliedSchema, why: z3.string().optional() })),
+  failed: z3.array(z3.object({ box: z3.string(), error: z3.string() })),
   /** Local boxes, untouched: they trust the host's key only. */
-  local: z2.number().int()
+  local: z3.number().int()
 });
-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 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 = z2.object({
-  hostSecret: z2.string(),
-  controlPlane: z2.object({ name: z2.string() })
+var HostJoinResponseSchema = z3.object({
+  hostSecret: z3.string(),
+  controlPlane: z3.object({ name: z3.string() })
 });
-var CloudHostSchema = z2.object({
-  name: z2.string(),
-  url: z2.string(),
-  publicAddress: z2.string(),
-  joinedAt: z2.string(),
-  lastSeenAt: z2.string().nullable(),
+var CloudHostSchema = z3.object({
+  name: z3.string(),
+  url: z3.string(),
+  publicAddress: z3.string(),
+  joinedAt: z3.string(),
+  lastSeenAt: z3.string().nullable(),
   capacity: CapacitySchema.nullable()
 });
 
@@ -809,24 +978,24 @@ function macFor(ip) {
 import { chmod as chmod3, mkdir as mkdir2, rm, writeFile as writeFile2 } from "node:fs/promises";
 
 // ../shared/src/relay.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var RELAY_TUNNEL_GATEWAY = "10.77.0.1";
 var IPV4_RE = /^(\d{1,3})(\.\d{1,3}){3}$/;
 var WG_KEY_RE = /^[A-Za-z0-9+/]{43}=$/;
-var RelayJoinSchema = z3.object({
-  v: z3.literal(1),
+var RelayJoinSchema = z4.object({
+  v: z4.literal(1),
   /** How the relay lists this host. */
-  name: z3.string().regex(/^[a-z0-9][a-z0-9-]{0,30}$/),
+  name: z4.string().regex(/^[a-z0-9][a-z0-9-]{0,30}$/),
   /** `<relay-primary-ip>:<port>`, the WireGuard endpoint the host dials. */
-  relay: z3.string().regex(/^(\d{1,3})(\.\d{1,3}){3}:\d{1,5}$/),
+  relay: z4.string().regex(/^(\d{1,3})(\.\d{1,3}){3}:\d{1,5}$/),
   /** The relay's WireGuard public key. */
-  relayKey: z3.string().regex(WG_KEY_RE),
+  relayKey: z4.string().regex(WG_KEY_RE),
   /** This host's address inside the tunnel. */
-  tunnelIp: z3.string().regex(IPV4_RE),
+  tunnelIp: z4.string().regex(IPV4_RE),
   /** This host's WireGuard private key, generated on the relay, kept nowhere else. */
-  privateKey: z3.string().regex(WG_KEY_RE),
+  privateKey: z4.string().regex(WG_KEY_RE),
   /** The extra public IPv4 the relay owns for this host; what the host advertises to the control plane. */
-  publicIp: z3.string().regex(IPV4_RE)
+  publicIp: z4.string().regex(IPV4_RE)
 });
 function decodeRelayJoin(text) {
   let parsed;
@@ -900,44 +1069,44 @@ import { createAdaptorServer } from "@hono/node-server";
 // src/core/state.ts
 import { randomBytes } from "node:crypto";
 import { mkdir as mkdir3, readFile as readFile4, readdir, writeFile as writeFile3 } from "node:fs/promises";
-import { z as z4 } from "zod";
-var MachineMetaSchema = z4.object({
+import { z as z5 } from "zod";
+var MachineMetaSchema = z5.object({
   /** Host-unique, minted at `kvbox new` (fresh or restored) and kept for the box's life; the tap is `kv-<id>`. */
-  id: z4.string(),
-  name: z4.string(),
+  id: z5.string(),
+  name: z5.string(),
   /** Part of the box's identity: machines/<owner>/<name>. See refs.ts. */
-  owner: z4.string(),
-  ip: z4.string(),
-  mac: z4.string(),
-  pid: z4.number().int().nullable(),
+  owner: z5.string(),
+  ip: z5.string(),
+  mac: z5.string(),
+  pid: z5.number().int().nullable(),
   // null: stopped on purpose, disk kept
-  vcpu: z4.number().int(),
-  memMib: z4.number().int(),
-  createdAt: z4.string(),
-  source: z4.string(),
+  vcpu: z5.number().int(),
+  memMib: z5.number().int(),
+  createdAt: z5.string(),
+  source: z5.string(),
   /** Base image version (assets/rootfs-<version>.ext4) the box's overlay stacks on. */
-  base: z4.string(),
+  base: z5.string(),
   /**
    * 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: z4.number().int().optional(),
+  memSnapshots: z5.number().int().optional(),
   /** `kvbox pause`: Firecracker is alive but the VM is frozen (standby). Absent: not paused. */
-  paused: z4.boolean().optional(),
+  paused: z5.boolean().optional(),
   /**
    * authorized_keys lines the box gets on top of the host's own key, as the control plane sent them
    * at `new` (#49). kvbox-init rewrites authorized_keys from the kernel cmdline at every boot, so
    * `start` has to send the same lines again. Absent: host key only.
    */
-  sshKeys: z4.array(z4.string()).optional(),
+  sshKeys: z5.array(z5.string()).optional(),
   /**
    * The guest's authorized_keys may not match `sshKeys`: they changed while the box was not running,
    * or its agent could not take them (#55, #63). Cleared by a push through kvbox-agent or a boot.
    */
-  sshKeysStale: z4.boolean().optional(),
+  sshKeysStale: z5.boolean().optional(),
   /** Public port on the host DNATed to the box's SSH while it runs (#49); fixed for the box's life. Absent: none. */
-  sshPort: z4.number().int().optional()
+  sshPort: z5.number().int().optional()
 });
 function newBoxId(taken) {
   for (; ; ) {
@@ -945,16 +1114,16 @@ function newBoxId(taken) {
     if (!taken.has(id)) return id;
   }
 }
-var SnapshotMetaSchema = z4.object({
-  name: z4.string(),
-  owner: z4.string(),
+var SnapshotMetaSchema = z5.object({
+  name: z5.string(),
+  owner: z5.string(),
   /** The box it was taken from, as owner/name. */
-  source: z4.string(),
-  base: z4.string(),
-  vcpu: z4.number().int(),
-  memMib: z4.number().int(),
-  sizeBytes: z4.number().int(),
-  createdAt: z4.string()
+  source: z5.string(),
+  base: z5.string(),
+  vcpu: z5.number().int(),
+  memMib: z5.number().int(),
+  sizeBytes: z5.number().int(),
+  createdAt: z5.string()
 });
 async function ensureLayout(p = paths()) {
   for (const dir of [p.home, p.ssh, p.bin, p.assets, p.machines, p.snapshots]) {
@@ -1016,7 +1185,7 @@ function pidAlive(pid) {
 }
 
 // src/app.ts
-import { Hono as Hono5 } from "hono";
+import { Hono as Hono6 } from "hono";
 
 // ../shared/src/version.ts
 import { createRequire } from "node:module";
@@ -1031,7 +1200,7 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.5.5" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.5.7" : void 0);
 
 // src/caller.ts
 import { createHash as createHash2, timingSafeEqual } from "node:crypto";
@@ -1214,7 +1383,12 @@ var MIGRATIONS = [
      disk_gib integer not null,
      by text not null
    );
-   create index usage_events_box_at on usage_events (box_id, at);`
+   create index usage_events_box_at on usage_events (box_id, at);`,
+  // The ledger's identity (#42): a control plane keys pulled rows by it, so a re-join is recognised
+  // and a fresh ledger (KVBOX_HOME wiped) restarts its cursor instead of waiting for ids it already saw.
+  `create table ledger (id text not null);
+   insert into ledger (id) values (lower(hex(randomblob(16))));
+   create index usage_events_at on usage_events (at);`
 ];
 var handles = /* @__PURE__ */ new Map();
 function openDb(p = paths()) {
@@ -1277,6 +1451,22 @@ function usageEventsFor(boxId, since, p = paths()) {
   const rows = openDb(p).prepare("select * from usage_events where box_id = ? and at >= ? order by at, id").all(boxId, since);
   return rows.map(fromRaw);
 }
+var withId = (r) => ({ ...fromRaw(r), id: r.id });
+function ledgerId(p = paths()) {
+  return openDb(p).prepare("select id from ledger").get().id;
+}
+function usageEventsAfter(after, limit, scope, p = paths()) {
+  const db = openDb(p);
+  const rows = scope === null ? db.prepare("select * from usage_events where id > ? order by id limit ?").all(after, limit) : typeof scope === "string" ? db.prepare("select * from usage_events where id > ? and owner = ? order by id limit ?").all(after, scope, limit) : db.prepare("select * from usage_events where id > ? and substr(owner, -length(?)) = ? order by id limit ?").all(after, `@${scope.realm}`, `@${scope.realm}`, limit);
+  return rows.map(withId);
+}
+function usageEventsInScope(scope, window, p = paths()) {
+  const rows = openDb(p).prepare(
+    `select * from usage_events where at < ? and (at >= ? or id in (select max(id) from usage_events where at < ? group by box_id))
+       order by at, id`
+  ).all(window.to, window.from, window.from);
+  return rows.filter((r) => inScope(r.owner, scope)).map(withId);
+}
 
 // src/core/firecracker.ts
 import { Agent, request as request2 } from "undici";
@@ -2105,46 +2295,6 @@ function capacityRoutes() {
 import { Hono as Hono2 } from "hono";
 
 // src/core/usage.ts
-var HOUR_MS = 36e5;
-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);
-  const from = Date.parse(w.from);
-  const to = Date.parse(w.to);
-  const ms = { running: 0, standby: 0, hibernated: 0, stopped: 0 };
-  let vcpuHours = 0;
-  let ramGibHours = 0;
-  let diskGibHours = 0;
-  sorted.forEach((e, i) => {
-    const start = Math.max(Date.parse(e.at), from);
-    const next = sorted[i + 1];
-    const end = Math.min(next === void 0 ? to : Date.parse(next.at), to);
-    if (end <= start) return;
-    const h = (end - start) / HOUR_MS;
-    ms[e.state] += end - start;
-    if (e.state === "running") vcpuHours += h * e.vcpu;
-    if (e.state === "running" || e.state === "standby") ramGibHours += h * e.memMib / 1024;
-    diskGibHours += h * e.diskGib;
-  });
-  const totals = {
-    seconds: {
-      running: Math.round(ms.running / 1e3),
-      standby: Math.round(ms.standby / 1e3),
-      hibernated: Math.round(ms.hibernated / 1e3),
-      stopped: Math.round(ms.stopped / 1e3)
-    },
-    vcpuHours: round(vcpuHours, 3),
-    ramGibHours: round(ramGibHours, 3),
-    diskGibHours: round(diskGibHours, 3),
-    estimatedStops: sorted.filter((e) => e.state === "stopped" && e.by === "server" && e.at >= w.from).length,
-    historyFrom: sorted[0]?.at ?? null
-  };
-  if (w.pricing !== void 0) {
-    const amount = vcpuHours * w.pricing.vcpuHour + ramGibHours * w.pricing.ramGibHour + diskGibHours * w.pricing.diskGibHour;
-    totals.cost = { amount: round(amount, 4), currency: w.pricing.currency };
-  }
-  return totals;
-}
 async function machineUsage(ref, since, p = paths()) {
   const box = await getMachine(ref, p);
   const cfg = await loadConfig(p);
@@ -2153,6 +2303,12 @@ async function machineUsage(ref, since, p = paths()) {
   const window = { from: since ?? box.createdAt, to: now };
   return { name: box.name, owner: box.owner, status: box.status, window, ...computeUsage(events, { ...window, pricing: cfg.pricing }) };
 }
+async function usageReport(scope, window, p = paths()) {
+  const cfg = await loadConfig(p);
+  const live = new Map((await listMachines(scope, p)).map((m) => [m.id, m.status]));
+  const boxes = groupUsage(usageEventsInScope(scope, window, p), window, cfg.pricing, live);
+  return { window, boxes, totals: sumUsage(boxes, cfg.pricing) };
+}
 
 // src/routes/machines.ts
 function machineRoutes() {
@@ -2350,9 +2506,38 @@ function sshRoutes(opts = {}) {
   return r;
 }
 
+// src/routes/usage.ts
+import { Hono as Hono5 } from "hono";
+var PULL_LIMIT = 1e3;
+function usageRoutes(opts = {}) {
+  const r = new Hono5();
+  r.get("/", async (c) => {
+    let window;
+    try {
+      window = usageWindow(c.req.query("since"), c.req.query("until"));
+    } catch (err) {
+      throw new KvboxError(err.message);
+    }
+    return c.json(await usageReport(c.get("listScope"), window));
+  });
+  r.get("/events", async (c) => {
+    const after = whole(c.req.query("after") ?? "0", "after");
+    const limit = Math.min(whole(c.req.query("limit") ?? String(PULL_LIMIT), "limit") || PULL_LIMIT, PULL_LIMIT);
+    const scope = opts.controlPlane === void 0 ? null : c.get("listScope");
+    const events = usageEventsAfter(after, limit, scope);
+    return c.json({ ledger: ledgerId(), events, next: events.length === 0 ? after : events[events.length - 1].id });
+  });
+  return r;
+}
+function whole(value, name) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new KvboxError(`${name}: expected a whole number, got "${value}"`);
+  return n;
+}
+
 // src/app.ts
 function createApp(opts = {}) {
-  const app = new Hono5();
+  const app = new Hono6();
   app.use(resolveCaller(opts));
   app.get("/health", async (c) => {
     const cfg = await loadConfig();
@@ -2371,6 +2556,7 @@ function createApp(opts = {}) {
   app.route("/snapshots", snapshotRoutes());
   app.route("/capacity", capacityRoutes());
   app.route("/ssh", sshRoutes(opts));
+  app.route("/usage", usageRoutes(opts));
   app.notFound((c) => c.json({ error: `no route: ${c.req.method} ${c.req.path}` }, 404));
   app.onError((err, c) => {
     if (err instanceof NotFoundError) return c.json({ error: err.message }, 404);