@remodex/rmx 1.0.2

package/src/server/management/android-remote-routes.ts

@@ -0,0 +1,390 @@
+import { networkInterfaces, hostname as readHostname } from "node:os";
+import {
+  createAndroidRemoteStore,
+  type AndroidRemoteState,
+  type AndroidRemoteStore,
+} from "../../android-remote/store";
+import {
+  androidRemoteGatewayUrls,
+  type AndroidRemoteGatewayController,
+  type AndroidRemoteGatewayLifecycleStatus,
+} from "../../android-remote/gateway";
+import type {
+  AndroidRemoteCloudflareFailure,
+  AndroidRemoteCloudflareState,
+} from "../../android-remote/cloudflare-tunnel";
+import {
+  CloudflareProvisioningError,
+  ManagedAndroidRemoteCloudflareProvisioner,
+  type AndroidRemoteCloudflareProvisioner,
+} from "../../android-remote/cloudflare-provisioning";
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBodyOr } from "./body";
+import type { ManagementContext } from "./context";
+import { isPlainRecord } from "./shared";
+
+export type AndroidRemoteClientDTO = {
+  id: string;
+  label: string;
+  deviceType: "mobile";
+  os: string;
+  address?: string;
+  scopes: string[];
+  createdAt: string;
+  lastSeenAt?: string;
+  online: boolean;
+};
+
+export type AndroidRemoteStatusDTO = {
+  version: 1;
+  controlEnabled: boolean;
+  keepAwake: boolean;
+  pairingAvailable: boolean;
+  gateway: {
+    status: AndroidRemoteGatewayLifecycleStatus;
+    backgroundServer: "current-process";
+    port: number;
+    error?: string;
+  };
+  reachableAddresses: string[];
+  tunnel: {
+    configuration: {
+      mode: "quick" | "named";
+      namedHostname?: string;
+      hasNamedTunnelToken: boolean;
+    };
+    runtime: {
+      mode: "quick" | "named";
+      status: AndroidRemoteCloudflareState["status"];
+      publicUrl: string | null;
+      error: AndroidRemoteCloudflareFailure | null;
+    };
+  };
+  desktop: {
+    id: "desktop";
+    label: string;
+    platform: NodeJS.Platform;
+    address: string;
+    online: true;
+  };
+  clients: AndroidRemoteClientDTO[];
+};
+
+export type AndroidRemotePairingDTO = {
+  version: 1;
+  id: string;
+  expiresAt: string;
+  qrPayload: string;
+};
+
+export function androidRemoteReachableAddresses(
+  port = 10105,
+  interfaces = networkInterfaces(),
+): string[] {
+  return androidRemoteGatewayUrls(port, interfaces);
+}
+
+function routeController(ctx: ManagementContext): AndroidRemoteGatewayController | undefined {
+  return ctx.deps.androidRemoteController;
+}
+
+function routeCloudflareProvisioner(ctx: ManagementContext): AndroidRemoteCloudflareProvisioner {
+  return ctx.deps.androidRemoteCloudflareProvisioner ?? new ManagedAndroidRemoteCloudflareProvisioner();
+}
+
+function cloudflareProvisioningError(error: unknown): { status: number; body: { error: string; code: string } } {
+  if (error instanceof CloudflareProvisioningError) {
+    const status = error.code === "invalid_input" || error.code === "hostname_outside_zone"
+      ? 400
+      : error.code === "authorization_failed" || error.code === "permission_missing"
+      ? 403
+      : error.code === "zone_not_found"
+        ? 404
+        : error.code === "rate_limited"
+          ? 429
+          : error.code === "cloudflare_unavailable" || error.code === "invalid_response"
+            ? 502
+            : 409;
+    return { status, body: { error: error.message, code: error.code } };
+  }
+  if (error instanceof TypeError) {
+    return { status: 400, body: { error: error.message, code: "invalid_input" } };
+  }
+  return {
+    status: 502,
+    body: { error: "Cloudflare could not complete the request. Try again.", code: "cloudflare_unavailable" },
+  };
+}
+
+async function statusDTO(
+  ctx: ManagementContext,
+  state: AndroidRemoteState,
+): Promise<AndroidRemoteStatusDTO> {
+  const controller = routeController(ctx);
+  const gateway = controller?.status() ?? {
+    status: "stopped" as const,
+    port: 10105,
+    backgroundServer: "current-process" as const,
+  };
+  const reachableAddresses = controller?.localUrls()
+    ?? androidRemoteReachableAddresses(gateway.port);
+  const pairingAddresses = controller?.pairingUrls() ?? [];
+  const onlineClientIds = controller?.onlineClientIds() ?? new Set<string>();
+  const configuration = controller
+    ? await controller.cloudflareConfiguration()
+    : {
+        mode: state.settings.tunnelMode,
+        ...(state.settings.namedTunnelHostname
+          ? { namedHostname: state.settings.namedTunnelHostname }
+          : {}),
+        hasNamedTunnelToken: false,
+      };
+  const tunnelState = controller?.cloudflareState() ?? {
+    mode: state.settings.tunnelMode,
+    status: "stopped" as const,
+    publicUrl: null,
+    error: null,
+  };
+  return {
+    version: 1,
+    controlEnabled: state.settings.controlEnabled,
+    keepAwake: state.settings.keepAwake,
+    pairingAvailable: gateway.status === "ready"
+      && (pairingAddresses.length > 0 || tunnelState.status === "ready"),
+    gateway,
+    reachableAddresses,
+    tunnel: {
+      configuration,
+      runtime: tunnelState,
+    },
+    desktop: {
+      id: "desktop",
+      label: readHostname() || "Remodex Desktop",
+      platform: process.platform,
+      address: reachableAddresses[0] ?? `http://127.0.0.1:${gateway.port}`,
+      online: true,
+    },
+    clients: state.clients.map(client => ({
+      id: client.id,
+      label: client.label,
+      deviceType: client.deviceType,
+      os: client.os,
+      scopes: [...client.scopes],
+      createdAt: client.createdAt,
+      online: onlineClientIds.has(client.id),
+      ...(client.address ? { address: client.address } : {}),
+      ...(client.lastSeenAt ? { lastSeenAt: client.lastSeenAt } : {}),
+    })),
+  };
+}
+
+function routeStore(ctx: ManagementContext): AndroidRemoteStore {
+  return ctx.deps.androidRemoteStore ?? createAndroidRemoteStore();
+}
+
+export async function handleAndroidRemoteRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config } = ctx;
+  if (url.pathname === "/api/android-remote" && req.method === "GET") {
+    return jsonResponse(await statusDTO(ctx, routeStore(ctx).read()), 200, req, config);
+  }
+
+  if (url.pathname === "/api/android-remote/pairing" && req.method === "POST") {
+    const controller = routeController(ctx);
+    if (!controller) {
+      return jsonResponse({ error: "Android Remote gateway is unavailable" }, 503, req, config);
+    }
+    try {
+      const invitation = controller.createPairingInvitation(readHostname() || "Remodex Desktop");
+      const response: AndroidRemotePairingDTO = {
+        version: 1,
+        id: invitation.id,
+        expiresAt: invitation.expiresAt,
+        qrPayload: invitation.qrPayload,
+      };
+      return jsonResponse(response, 201, req, config);
+    } catch {
+      return jsonResponse({ error: "Android Remote gateway is not ready" }, 409, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/android-remote/settings" && req.method === "PUT") {
+    const body = await readManagementJsonBodyOr(req, null);
+    if (!isPlainRecord(body)) {
+      return jsonResponse({ error: "settings body must be an object" }, 400, req, config);
+    }
+    const keys = Object.keys(body);
+    if (keys.length === 0 || keys.some(key => key !== "controlEnabled" && key !== "keepAwake")) {
+      return jsonResponse({ error: "provide controlEnabled and/or keepAwake only" }, 400, req, config);
+    }
+    if (("controlEnabled" in body && typeof body.controlEnabled !== "boolean")
+      || ("keepAwake" in body && typeof body.keepAwake !== "boolean")) {
+      return jsonResponse({ error: "Android Remote settings must be boolean" }, 400, req, config);
+    }
+    const next = routeStore(ctx).updateSettings({
+      ...(typeof body.controlEnabled === "boolean" ? { controlEnabled: body.controlEnabled } : {}),
+      ...(typeof body.keepAwake === "boolean" ? { keepAwake: body.keepAwake } : {}),
+    });
+    try {
+      await routeController(ctx)?.applySettings(next.settings);
+    } catch {
+      // The controller records a safe error state. Return that honest state so the
+      // dashboard can explain that the saved switch is on but the gateway failed.
+    }
+    return jsonResponse(await statusDTO(ctx, next), 200, req, config);
+  }
+
+  if (url.pathname === "/api/android-remote/cloudflare/discover" && req.method === "POST") {
+    const body = await readManagementJsonBodyOr(req, null);
+    if (!isPlainRecord(body)
+      || Object.keys(body).some(key => key !== "apiToken")
+      || typeof body.apiToken !== "string") {
+      return jsonResponse({ error: "provide a Cloudflare API token only", code: "invalid_input" }, 400, req, config);
+    }
+    try {
+      const discovery = await routeCloudflareProvisioner(ctx).discover(body.apiToken);
+      return jsonResponse(discovery, 200, req, config);
+    } catch (error) {
+      const failure = cloudflareProvisioningError(error);
+      return jsonResponse(failure.body, failure.status, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/android-remote/cloudflare/provision" && req.method === "POST") {
+    // This call creates a tunnel and DNS record in the user's Cloudflare account.
+    // A raw admin token can be read by local agents, so only the browser session
+    // minted by the dashboard is accepted as evidence of the user's Connect click.
+    if (ctx.principal !== "gui-session") {
+      return jsonResponse({
+        error: "Open the dashboard and choose Connect to authorize changes to Cloudflare.",
+        code: "dashboard_session_required",
+      }, 403, req, config);
+    }
+    const controller = routeController(ctx);
+    if (!controller) {
+      return jsonResponse({ error: "Android Remote gateway is unavailable" }, 503, req, config);
+    }
+    const body = await readManagementJsonBodyOr(req, null);
+    const allowed = new Set(["apiToken", "accountId", "zoneId", "hostname"]);
+    if (!isPlainRecord(body)
+      || Object.keys(body).some(key => !allowed.has(key))
+      || typeof body.apiToken !== "string"
+      || typeof body.accountId !== "string"
+      || typeof body.zoneId !== "string"
+      || typeof body.hostname !== "string") {
+      return jsonResponse({ error: "provide the selected Cloudflare account, domain, and hostname", code: "invalid_input" }, 400, req, config);
+    }
+    try {
+      const provisioned = await routeCloudflareProvisioner(ctx).provision({
+        apiToken: body.apiToken,
+        accountId: body.accountId,
+        zoneId: body.zoneId,
+        hostname: body.hostname,
+      });
+      routeStore(ctx).updateSettings({ controlEnabled: true });
+      await controller.configureCloudflareTunnel({
+        mode: "named",
+        namedHostname: provisioned.hostname,
+        token: provisioned.connectorToken,
+      });
+      return jsonResponse(await statusDTO(ctx, routeStore(ctx).read()), 200, req, config);
+    } catch (error) {
+      const failure = cloudflareProvisioningError(error);
+      return jsonResponse(failure.body, failure.status, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/android-remote/tunnel" && req.method === "PUT") {
+    const controller = routeController(ctx);
+    if (!controller) {
+      return jsonResponse({ error: "Android Remote gateway is unavailable" }, 503, req, config);
+    }
+    const body = await readManagementJsonBodyOr(req, null);
+    if (!isPlainRecord(body)) {
+      return jsonResponse({ error: "tunnel body must be an object" }, 400, req, config);
+    }
+    if (body.mode !== "quick" && body.mode !== "named") {
+      return jsonResponse({ error: "tunnel mode must be quick or named" }, 400, req, config);
+    }
+    const allowed = body.mode === "quick"
+      ? new Set(["mode"])
+      : new Set(["mode", "hostname", "token"]);
+    if (Object.keys(body).some(key => !allowed.has(key))) {
+      return jsonResponse({ error: "tunnel body contains unsupported fields" }, 400, req, config);
+    }
+    if (body.mode === "named" && typeof body.hostname !== "string") {
+      return jsonResponse({ error: "Named Tunnel requires a hostname" }, 400, req, config);
+    }
+    if ("token" in body && typeof body.token !== "string") {
+      return jsonResponse({ error: "connector token must be a string" }, 400, req, config);
+    }
+    try {
+      await controller.configureCloudflareTunnel({
+        mode: body.mode,
+        ...(typeof body.hostname === "string" ? { namedHostname: body.hostname } : {}),
+        ...(typeof body.token === "string" ? { token: body.token } : {}),
+      });
+      return jsonResponse(await statusDTO(ctx, routeStore(ctx).read()), 200, req, config);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Tunnel configuration failed";
+      return jsonResponse({ error: message }, error instanceof TypeError ? 400 : 409, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/android-remote/tunnel/retry" && req.method === "POST") {
+    const controller = routeController(ctx);
+    if (!controller) {
+      return jsonResponse({ error: "Android Remote gateway is unavailable" }, 503, req, config);
+    }
+    try {
+      await controller.retryCloudflareTunnel();
+      return jsonResponse(await statusDTO(ctx, routeStore(ctx).read()), 200, req, config);
+    } catch (error) {
+      return jsonResponse({ error: error instanceof Error ? error.message : "Tunnel retry failed" }, 409, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/android-remote/tunnel/token" && req.method === "DELETE") {
+    const controller = routeController(ctx);
+    if (!controller) {
+      return jsonResponse({ error: "Android Remote gateway is unavailable" }, 503, req, config);
+    }
+    try {
+      await controller.removeCloudflareTunnelToken();
+      return jsonResponse(await statusDTO(ctx, routeStore(ctx).read()), 200, req, config);
+    } catch {
+      return jsonResponse({ error: "Could not remove the connector token" }, 409, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/android-remote/tunnel/domain" && req.method === "DELETE") {
+    const controller = routeController(ctx);
+    if (!controller) {
+      return jsonResponse({ error: "Android Remote gateway is unavailable" }, 503, req, config);
+    }
+    try {
+      await controller.disconnectCloudflareNamedTunnel();
+      return jsonResponse(await statusDTO(ctx, routeStore(ctx).read()), 200, req, config);
+    } catch {
+      return jsonResponse({ error: "Could not disconnect the named domain" }, 409, req, config);
+    }
+  }
+
+  const revokeMatch = url.pathname.match(/^\/api\/android-remote\/clients\/([^/]+)$/);
+  if (revokeMatch && req.method === "DELETE") {
+    let id: string;
+    try {
+      id = decodeURIComponent(revokeMatch[1]);
+    } catch {
+      return jsonResponse({ error: "invalid client id encoding" }, 400, req, config);
+    }
+    if (!/^[a-zA-Z0-9._-]{1,128}$/.test(id)) {
+      return jsonResponse({ error: "invalid client id" }, 400, req, config);
+    }
+    const result = routeStore(ctx).revokeClient(id);
+    if (!result.removed) return jsonResponse({ error: "client not found" }, 404, req, config);
+    routeController(ctx)?.revokeClient(id);
+    return jsonResponse(await statusDTO(ctx, result.state), 200, req, config);
+  }
+
+  return null;
+}

package/src/server/management/api-access.ts

@@ -0,0 +1,141 @@
+import type { OcxConfig } from "../../types";
+import { probeHostname } from "../proxy-liveness";
+
+export interface ApiAccessEndpoints {
+  baseUrl: string;
+  responsesEndpoint: string;
+  chatCompletionsEndpoint: string;
+  messagesEndpoint: string;
+  modelsEndpoint: string;
+  claudeCodeEnabled: boolean;
+  /** Back-compat alias for older GUI clients. */
+  endpoint: string;
+}
+
+export type BuildApiAccessEndpointsOptions = {
+  /** Full request URL (preferred when the bind host is a wildcard). */
+  requestUrl?: string | URL | null;
+  /** Raw `Host` header from the inbound request. */
+  requestHost?: string | null;
+  /** Raw `Origin` header from the inbound request. */
+  requestOrigin?: string | null;
+};
+
+function isWildcardBindHost(hostname: string | undefined): boolean {
+  const trimmed = (hostname ?? "").trim();
+  return !trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]";
+}
+
+/** Bracket bare IPv6 literals for URL authority composition. */
+export function formatAuthorityHost(hostname: string): string {
+  const trimmed = hostname.trim();
+  if (!trimmed) return "127.0.0.1";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
+  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+}
+
+function hostnameFromAuthority(authority: string): string | null {
+  const raw = authority.trim();
+  if (!raw) return null;
+  if (raw.startsWith("[")) {
+    const end = raw.indexOf("]");
+    if (end > 0) return raw.slice(1, end) || null;
+    return null;
+  }
+  // Host headers for IPv6 are bracketed; treat multi-colon values as unusable.
+  if (raw.includes(":") && raw.split(":").length > 2) return null;
+  const colon = raw.lastIndexOf(":");
+  if (colon > 0 && /^\d+$/.test(raw.slice(colon + 1))) {
+    return raw.slice(0, colon) || null;
+  }
+  return raw;
+}
+
+function originBaseUrl(raw: string): string | null {
+  try {
+    const url = new URL(raw);
+    if (!url.hostname || isWildcardBindHost(url.hostname)) return null;
+    return `${url.protocol}//${url.host}/v1`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prefer the client's request host/origin when the proxy is bound to a wildcard.
+ * Falls back to loopback only when no usable request context is available.
+ */
+export function resolveApiAccessBaseUrl(
+  config: Pick<OcxConfig, "hostname" | "port">,
+  opts: BuildApiAccessEndpointsOptions = {},
+): string {
+  const port = config.port ?? 10100;
+
+  if (!isWildcardBindHost(config.hostname)) {
+    return `http://${probeHostname(config.hostname)}:${port}/v1`;
+  }
+
+  const fromOrigin = opts.requestOrigin ? originBaseUrl(opts.requestOrigin) : null;
+  if (fromOrigin) return fromOrigin;
+
+  if (opts.requestUrl) {
+    try {
+      const url = typeof opts.requestUrl === "string" ? new URL(opts.requestUrl) : opts.requestUrl;
+      if (url.hostname && !isWildcardBindHost(url.hostname)) {
+        return `${url.protocol}//${url.host}/v1`;
+      }
+    } catch {
+      /* ignore malformed request URL */
+    }
+  }
+
+  const hostHeader = opts.requestHost?.trim();
+  if (hostHeader) {
+    const hostname = hostnameFromAuthority(hostHeader);
+    if (hostname && !isWildcardBindHost(hostname)) {
+      // Preserve an explicit port from the Host header; otherwise use the bind port.
+      const hasPort = hostHeader.startsWith("[")
+        ? /\]:\d+$/.test(hostHeader)
+        : /:\d+$/.test(hostHeader) && hostHeader.split(":").length === 2;
+      const authority = hasPort
+        ? (hostHeader.startsWith("[") ? hostHeader : hostHeader)
+        : `${formatAuthorityHost(hostname)}:${port}`;
+      return `http://${authority}/v1`;
+    }
+  }
+
+  return `http://127.0.0.1:${port}/v1`;
+}
+
+/** @deprecated Prefer resolveApiAccessBaseUrl; retained for focused host-format tests. */
+export function resolveApiAccessDisplayHost(
+  configHostname: string | undefined,
+  opts: BuildApiAccessEndpointsOptions = {},
+): string {
+  if (!isWildcardBindHost(configHostname)) {
+    return probeHostname(configHostname);
+  }
+  try {
+    return new URL(resolveApiAccessBaseUrl({ hostname: configHostname, port: 10100 }, opts)).hostname
+      || "127.0.0.1";
+  } catch {
+    return "127.0.0.1";
+  }
+}
+
+export function buildApiAccessEndpoints(
+  config: OcxConfig,
+  opts: BuildApiAccessEndpointsOptions = {},
+): ApiAccessEndpoints {
+  const baseUrl = resolveApiAccessBaseUrl(config, opts);
+  const responsesEndpoint = `${baseUrl}/responses`;
+  return {
+    baseUrl,
+    responsesEndpoint,
+    chatCompletionsEndpoint: `${baseUrl}/chat/completions`,
+    messagesEndpoint: `${baseUrl}/messages`,
+    modelsEndpoint: `${baseUrl}/models`,
+    claudeCodeEnabled: config.claudeCode?.enabled !== false,
+    endpoint: responsesEndpoint,
+  };
+}

package/src/server/management/api-key-usage.ts

@@ -0,0 +1,167 @@
+import {
+  currentUsageLogRevision,
+  readUsageSnapshotForManagement,
+  usageLogRevisionKey,
+  type PersistedUsageEntry,
+} from "../../usage/log";
+
+/**
+ * Per-key usage as the API tab renders it.
+ *
+ * A discriminated union rather than numbers with a flag beside them: when two
+ * config entries share an id there IS no per-key total, and an optional marker
+ * next to `requests7d: 7` invites a consumer to render the 7 anyway.
+ */
+export type ApiKeyUsage =
+  | { ambiguous: true }
+  | { ambiguous?: false; requests7d: number; totalRequests: number; lastUsedAt?: string };
+
+export interface ApiKeyUsageSnapshot {
+  rollup: Map<string, ApiKeyUsage>;
+  historyTruncated?: true;
+  /**
+   * Earliest row carrying a recognized `admissionKind`. A property of the DATA
+   * SET, not of a key, so it is singular and lives beside the map: it is what
+   * lets the GUI tell "this key was used zero times" from "nothing is
+   * attributable yet". Keyed on the kind rather than on `apiKeyId`, because an
+   * environment or loopback row is attributed traffic with no configured key.
+   */
+  attributionSince?: string;
+}
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * A timestamp we can actually do date arithmetic with.
+ *
+ * `usage.jsonl` is hand-editable and JSON permits numbers outside the Date
+ * range: `1e309` survives normalization and then throws `RangeError` from
+ * `toISOString()`. Since the caller catches to protect key management, one bad
+ * row would have zeroed the rollup for EVERY key — active keys reported as
+ * unused is exactly the wrong answer to hand someone deciding what to delete.
+ */
+function usableTimestamp(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Number.isNaN(new Date(value).getTime()) ? null : value;
+}
+
+/**
+ * Pure: one pass over an already-read snapshot, so it is unit-testable without
+ * touching the filesystem.
+ *
+ * Rows are bucketed only when `admissionKind === "configured"`. Keying on
+ * `apiKeyId` alone would let a hand-edited entry whose id is `loopback` absorb
+ * traffic it never admitted.
+ */
+export function rollupApiKeyUsage(
+  entries: PersistedUsageEntry[],
+  configuredIds: string[],
+  now: number = Date.now(),
+): ApiKeyUsageSnapshot {
+  const duplicated = new Set<string>();
+  const seen = new Set<string>();
+  for (const id of configuredIds) {
+    if (seen.has(id)) duplicated.add(id);
+    seen.add(id);
+  }
+
+  const totals = new Map<string, { requests7d: number; totalRequests: number; lastUsedAt?: string }>();
+  let attributionSince: number | undefined;
+  const cutoff = now - SEVEN_DAYS_MS;
+
+  for (const entry of entries) {
+    if (!entry.admissionKind) continue;
+    const timestamp = usableTimestamp(entry.timestamp);
+    if (timestamp !== null && (attributionSince === undefined || timestamp < attributionSince)) {
+      attributionSince = timestamp;
+    }
+    if (entry.admissionKind !== "configured" || !entry.apiKeyId) continue;
+
+    const bucket = totals.get(entry.apiKeyId) ?? { requests7d: 0, totalRequests: 0 };
+    // The request happened even if its clock reading is unusable, so it still
+    // counts toward the total; only the time-based fields are skipped.
+    bucket.totalRequests += 1;
+    if (timestamp !== null) {
+      if (timestamp >= cutoff) bucket.requests7d += 1;
+      const iso = new Date(timestamp).toISOString();
+      if (!bucket.lastUsedAt || iso > bucket.lastUsedAt) bucket.lastUsedAt = iso;
+    }
+    totals.set(entry.apiKeyId, bucket);
+  }
+
+  const rollup = new Map<string, ApiKeyUsage>();
+  for (const id of configuredIds) {
+    if (duplicated.has(id)) {
+      rollup.set(id, { ambiguous: true });
+      continue;
+    }
+    rollup.set(id, totals.get(id) ?? { requests7d: 0, totalRequests: 0 });
+  }
+  return {
+    rollup,
+    ...(attributionSince !== undefined ? { attributionSince: new Date(attributionSince).toISOString() } : {}),
+  };
+}
+
+/**
+ * Rollup cache keyed by the exact usage-log revision, mirroring the /api/usage
+ * summary cache. Without it, every key-list read reparses an append-only log
+ * that only ever grows — and the GUI fetches this route on mount and after every
+ * create/rename/delete. The compact rollup is a handful of counters per key, so
+ * caching it costs nothing; a new row changes the revision and invalidates it.
+ */
+let rollupCache: { revisionKey: string; expiresAt: number; snapshot: ApiKeyUsageSnapshot } | null = null;
+
+/**
+ * The rollup is a function of the log AND of the clock: a request ages out of
+ * the seven-day window with no write to bump the file revision, so a purely
+ * revision-keyed entry would report a stale `requests7d` indefinitely.
+ *
+ * A minute is the whole rule. Deriving the exact next-transition instant would
+ * mean tracking the OLDEST counted request per key, which the compact rollup
+ * deliberately does not keep — and a count that can be at most 60s stale is
+ * already far tighter than the window it describes.
+ */
+const ROLLUP_CACHE_TTL_MS = 60_000;
+
+/** Test seam: the cache is module state and would otherwise leak between cases. */
+export function clearApiKeyUsageCacheForTests(): void {
+  rollupCache = null;
+}
+
+/**
+ * Reads the durable usage snapshot the way /api/usage does, then rolls it up.
+ *
+ * Never throws: an unreadable snapshot yields empty rollups and no
+ * `attributionSince`. Key management working matters more than usage numbers
+ * being present, and the GUI already treats an absent field as "no data".
+ */
+export async function readApiKeyUsageRollup(configuredIds: string[], maxReadBytes?: number): Promise<ApiKeyUsageSnapshot> {
+  // JSON rather than a joined string: ids are only validated as non-empty
+  // strings, so `["a\0b","c"]` and `["a","b\0c"]` join to the same value and one
+  // config could be served the other's cached rollup.
+  const idsKey = JSON.stringify([configuredIds, maxReadBytes]);
+  const now = Date.now();
+  try {
+    const observedKey = `${usageLogRevisionKey(currentUsageLogRevision())}|${idsKey}`;
+    if (rollupCache?.revisionKey === observedKey && now < rollupCache.expiresAt) {
+      return rollupCache.snapshot;
+    }
+
+    const snapshot = await readUsageSnapshotForManagement(maxReadBytes);
+    const rolled = {
+      ...rollupApiKeyUsage(snapshot.entries, configuredIds, now),
+      ...(snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated ? { historyTruncated: true as const } : {}),
+    };
+    rollupCache = {
+      revisionKey: `${usageLogRevisionKey(snapshot.revision)}|${idsKey}`,
+      expiresAt: now + ROLLUP_CACHE_TTL_MS,
+      snapshot: rolled,
+    };
+    return rolled;
+  } catch {
+    const rollup = new Map<string, ApiKeyUsage>();
+    for (const id of configuredIds) rollup.set(id, { requests7d: 0, totalRequests: 0 });
+    return { rollup };
+  }
+}