@wopr-network/platform-core 1.13.0 → 1.13.1

package/src/api/routes/admin-backups.ts

@@ -0,0 +1,134 @@
+import { Hono } from "hono";
+import type { AuthEnv } from "../../auth/index.js";
+import type { IBackupStatusStore } from "../../backup/backup-status-store.js";
+import type { SpacesClient } from "../../backup/spaces-client.js";
+import { logger } from "../../config/logger.js";
+import type { AdminAuditLogger } from "./admin-audit-helper.js";
+import { safeAuditLog } from "./admin-audit-helper.js";
+
+/**
+ * Validate that a remotePath belongs to the given container.
+ * Normalizes the path, rejects traversal segments, and checks that the containerId
+ * appears as the leading non-empty segment.
+ */
+export function isRemotePathOwnedBy(remotePath: string, containerId: string): boolean {
+  const normalized = remotePath.replace(/\\/g, "/");
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments.length === 0) return false;
+  if (segments.some((s) => s === ".." || s === ".")) return false;
+  return segments[0] === containerId;
+}
+
+/**
+ * Create admin backup routes.
+ *
+ * @param storeFactory - factory for the backup status store
+ * @param spacesFactory - factory for the S3/Spaces client
+ * @param auditLogger - optional admin audit logger
+ */
+export function createAdminBackupRoutes(
+  storeFactory: () => IBackupStatusStore,
+  spacesFactory: () => SpacesClient,
+  auditLogger?: () => AdminAuditLogger,
+): Hono<AuthEnv> {
+  const routes = new Hono<AuthEnv>();
+
+  routes.get("/", async (c) => {
+    const store = storeFactory();
+    const staleOnly = c.req.query("stale") === "true";
+    const entries = staleOnly ? await store.listStale() : await store.listAll();
+    return c.json({
+      backups: entries,
+      total: entries.length,
+      staleCount: entries.filter((e) => e.isStale).length,
+    });
+  });
+
+  routes.get("/alerts/stale", async (c) => {
+    const store = storeFactory();
+    const stale = await store.listStale();
+    return c.json({
+      alerts: stale.map((e) => ({
+        containerId: e.containerId,
+        nodeId: e.nodeId,
+        lastBackupAt: e.lastBackupAt,
+        lastBackupSuccess: e.lastBackupSuccess,
+        lastBackupError: e.lastBackupError,
+      })),
+      count: stale.length,
+    });
+  });
+
+  routes.get("/:containerId", async (c) => {
+    const store = storeFactory();
+    const containerId = c.req.param("containerId");
+    const entry = await store.get(containerId);
+    if (!entry) {
+      return c.json({ error: "No backup status found for this container" }, 404);
+    }
+    return c.json(entry);
+  });
+
+  routes.get("/:containerId/snapshots", async (c) => {
+    const store = storeFactory();
+    const containerId = c.req.param("containerId");
+    const entry = await store.get(containerId);
+    if (!entry) {
+      return c.json({ error: "No backup status found for this container" }, 404);
+    }
+
+    try {
+      const spaces = spacesFactory();
+      const prefix = `nightly/${entry.nodeId}/${containerId}/`;
+      const objects = await spaces.list(prefix);
+      return c.json({
+        containerId,
+        snapshots: objects.map((o) => ({
+          path: o.path,
+          date: o.date,
+          sizeMb: Math.round((o.size / (1024 * 1024)) * 100) / 100,
+        })),
+      });
+    } catch (err) {
+      logger.error(`Failed to list snapshots for ${containerId}`, { err });
+      return c.json({ error: "Failed to list backup snapshots" }, 500);
+    }
+  });
+
+  routes.post("/:containerId/restore", async (c) => {
+    const containerId = c.req.param("containerId");
+
+    let body: { remotePath?: string; targetNodeId?: string };
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+
+    if (!body.remotePath) {
+      return c.json({ error: "remotePath is required" }, 400);
+    }
+
+    if (!isRemotePathOwnedBy(body.remotePath, containerId)) {
+      return c.json({ error: "remotePath does not belong to this container" }, 403);
+    }
+
+    safeAuditLog(auditLogger, {
+      adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+      action: "backup.restore",
+      category: "config",
+      details: { containerId, remotePath: body.remotePath, targetNodeId: body.targetNodeId ?? "auto" },
+      outcome: "success",
+    });
+
+    return c.json({
+      ok: true,
+      message: `Restore initiated for ${containerId} from ${body.remotePath}`,
+      containerId,
+      remotePath: body.remotePath,
+      targetNodeId: body.targetNodeId ?? "auto",
+    });
+  });
+
+  return routes;
+}

package/src/api/routes/admin-compliance.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import type { EvidenceCollector } from "../../compliance/evidence-collector.js";
+
+/**
+ * Create admin compliance routes.
+ *
+ * GET /evidence?from=ISO&to=ISO — Generate SOC 2 evidence report for the given period.
+ * Defaults to last 90 days if no params provided.
+ */
+export function createAdminComplianceRoutes(getCollector: () => EvidenceCollector): Hono {
+  const routes = new Hono();
+
+  routes.get("/evidence", async (c) => {
+    const now = new Date();
+    const ninetyDaysAgo = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000);
+
+    const fromParam = c.req.query("from");
+    const toParam = c.req.query("to");
+
+    if (fromParam !== undefined && Number.isNaN(new Date(fromParam).getTime())) {
+      return c.json({ error: "Invalid 'from' date" }, 400);
+    }
+    if (toParam !== undefined && Number.isNaN(new Date(toParam).getTime())) {
+      return c.json({ error: "Invalid 'to' date" }, 400);
+    }
+
+    const from = fromParam ?? ninetyDaysAgo.toISOString();
+    const to = toParam ?? now.toISOString();
+
+    const report = await getCollector().collect({ from, to });
+    return c.json(report);
+  });
+
+  return routes;
+}

package/src/api/routes/admin-credits.ts

@@ -0,0 +1,280 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import type { AuthEnv } from "../../auth/index.js";
+import type { ICreditLedger } from "../../credits/index.js";
+import { Credit, InsufficientBalanceError } from "../../credits/index.js";
+import type { AdminAuditLogger } from "./admin-audit-helper.js";
+import { safeAuditLog } from "./admin-audit-helper.js";
+
+const tenantIdSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-zA-Z0-9_-]+$/);
+
+const TENANT_ID_ERROR = "tenantId must be 1-128 alphanumeric characters, hyphens, or underscores";
+
+function parseTenantId(c: { req: { param: (k: string) => string } }): { ok: true; tenant: string } | { ok: false } {
+  const result = tenantIdSchema.safeParse(c.req.param("tenantId"));
+  if (!result.success) return { ok: false };
+  return { ok: true, tenant: result.data };
+}
+
+function parseIntParam(value: string | undefined): number | undefined {
+  if (value == null || value === "") return undefined;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * Create admin credit API routes.
+ * Pass a ledger directly or a factory for lazy init.
+ */
+export function createAdminCreditApiRoutes(
+  ledgerOrFactory: ICreditLedger | (() => ICreditLedger),
+  auditLogger?: () => AdminAuditLogger,
+): Hono<AuthEnv> {
+  const ledgerFactory = typeof ledgerOrFactory === "function" ? ledgerOrFactory : () => ledgerOrFactory;
+  const routes = new Hono<AuthEnv>();
+
+  routes.post("/:tenantId/grant", async (c) => {
+    const ledger = ledgerFactory();
+    const parsed = parseTenantId(c);
+    if (!parsed.ok) return c.json({ error: TENANT_ID_ERROR }, 400);
+    const tenant = parsed.tenant;
+
+    let body: Record<string, unknown>;
+    try {
+      body = (await c.req.json()) as Record<string, unknown>;
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+
+    const amountCents = body.amount_cents;
+    const reason = body.reason;
+
+    if (typeof amountCents !== "number" || !Number.isInteger(amountCents) || amountCents <= 0) {
+      return c.json({ error: "amount_cents must be a positive integer" }, 400);
+    }
+
+    if (typeof reason !== "string" || !reason.trim()) {
+      return c.json({ error: "reason is required and must be non-empty" }, 400);
+    }
+
+    try {
+      const user = c.get("user");
+      const adminUser = user?.id ?? "unknown";
+      let result: Awaited<ReturnType<typeof ledger.credit>>;
+      try {
+        result = await ledger.credit(
+          tenant,
+          Credit.fromCents(amountCents),
+          "admin_grant",
+          reason,
+          undefined,
+          undefined,
+          adminUser,
+        );
+      } catch (err) {
+        safeAuditLog(auditLogger, {
+          adminUser,
+          action: "credits.grant",
+          category: "credits",
+          targetTenant: tenant,
+          details: { amount_cents: amountCents, reason, error: String(err) },
+          outcome: "failure",
+        });
+        throw err;
+      }
+      safeAuditLog(auditLogger, {
+        adminUser,
+        action: "credits.grant",
+        category: "credits",
+        targetTenant: tenant,
+        details: { amount_cents: amountCents, reason },
+        outcome: "success",
+      });
+      return c.json(result, 201);
+    } catch (err) {
+      return c.json({ error: err instanceof Error ? err.message : "Internal server error" }, 500);
+    }
+  });
+
+  routes.post("/:tenantId/refund", async (c) => {
+    const ledger = ledgerFactory();
+    const parsed = parseTenantId(c);
+    if (!parsed.ok) return c.json({ error: TENANT_ID_ERROR }, 400);
+    const tenant = parsed.tenant;
+
+    let body: Record<string, unknown>;
+    try {
+      body = (await c.req.json()) as Record<string, unknown>;
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+
+    const amountCents = body.amount_cents;
+    const reason = body.reason;
+
+    if (typeof amountCents !== "number" || !Number.isInteger(amountCents) || amountCents <= 0) {
+      return c.json({ error: "amount_cents must be a positive integer" }, 400);
+    }
+
+    if (typeof reason !== "string" || !reason.trim()) {
+      return c.json({ error: "reason is required and must be non-empty" }, 400);
+    }
+
+    try {
+      const user = c.get("user");
+      const adminUser = user?.id ?? "unknown";
+      let result: Awaited<ReturnType<typeof ledger.credit>>;
+      try {
+        result = await ledger.credit(tenant, Credit.fromCents(amountCents), "admin_grant", reason);
+      } catch (err) {
+        safeAuditLog(auditLogger, {
+          adminUser,
+          action: "credits.refund",
+          category: "credits",
+          targetTenant: tenant,
+          details: { amount_cents: amountCents, reason, error: String(err) },
+          outcome: "failure",
+        });
+        throw err;
+      }
+      safeAuditLog(auditLogger, {
+        adminUser,
+        action: "credits.refund",
+        category: "credits",
+        targetTenant: tenant,
+        details: { amount_cents: amountCents, reason },
+        outcome: "success",
+      });
+      return c.json(result, 201);
+    } catch (err) {
+      if (err instanceof InsufficientBalanceError) {
+        return c.json({ error: err.message, current_balance: err.currentBalance }, 400);
+      }
+      return c.json({ error: err instanceof Error ? err.message : "Internal server error" }, 500);
+    }
+  });
+
+  routes.post("/:tenantId/correction", async (c) => {
+    const ledger = ledgerFactory();
+    const parsed = parseTenantId(c);
+    if (!parsed.ok) return c.json({ error: TENANT_ID_ERROR }, 400);
+    const tenant = parsed.tenant;
+
+    let body: Record<string, unknown>;
+    try {
+      body = (await c.req.json()) as Record<string, unknown>;
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+
+    const amountCents = body.amount_cents;
+    const reason = body.reason;
+
+    if (typeof amountCents !== "number" || !Number.isInteger(amountCents) || amountCents === 0) {
+      return c.json({ error: "amount_cents must be a non-zero integer" }, 400);
+    }
+
+    if (typeof reason !== "string" || !reason.trim()) {
+      return c.json({ error: "reason is required and must be non-empty" }, 400);
+    }
+
+    try {
+      const user = c.get("user");
+      const adminUser = user?.id ?? "unknown";
+      let result: Awaited<ReturnType<typeof ledger.credit>>;
+      try {
+        if (amountCents >= 0) {
+          result = await ledger.credit(tenant, Credit.fromCents(amountCents), "promo", reason);
+        } else {
+          result = await ledger.debit(tenant, Credit.fromCents(Math.abs(amountCents)), "correction", reason);
+        }
+      } catch (err) {
+        safeAuditLog(auditLogger, {
+          adminUser,
+          action: "credits.correction",
+          category: "credits",
+          targetTenant: tenant,
+          details: { amount_cents: amountCents, reason, error: String(err) },
+          outcome: "failure",
+        });
+        throw err;
+      }
+      safeAuditLog(auditLogger, {
+        adminUser,
+        action: "credits.correction",
+        category: "credits",
+        targetTenant: tenant,
+        details: { amount_cents: amountCents, reason },
+        outcome: "success",
+      });
+      return c.json(result, 201);
+    } catch (err) {
+      if (err instanceof InsufficientBalanceError) {
+        return c.json({ error: err.message, current_balance: err.currentBalance }, 400);
+      }
+      return c.json({ error: err instanceof Error ? err.message : "Internal server error" }, 500);
+    }
+  });
+
+  routes.get("/:tenantId/balance", async (c) => {
+    const ledger = ledgerFactory();
+    const parsed = parseTenantId(c);
+    if (!parsed.ok) return c.json({ error: TENANT_ID_ERROR }, 400);
+    const tenant = parsed.tenant;
+
+    try {
+      const balance = await ledger.balance(tenant);
+      return c.json({ tenant, balance_credits: balance });
+    } catch {
+      return c.json({ error: "Internal server error" }, 500);
+    }
+  });
+
+  routes.get("/:tenantId/transactions", async (c) => {
+    const ledger = ledgerFactory();
+    const parsed = parseTenantId(c);
+    if (!parsed.ok) return c.json({ error: TENANT_ID_ERROR }, 400);
+    const tenant = parsed.tenant;
+    const typeParam = c.req.query("type");
+
+    const filters = {
+      type: typeParam,
+      limit: parseIntParam(c.req.query("limit")),
+      offset: parseIntParam(c.req.query("offset")),
+    };
+
+    try {
+      const entries = await ledger.history(tenant, filters);
+      return c.json({ entries, total: entries.length });
+    } catch {
+      return c.json({ error: "Internal server error" }, 500);
+    }
+  });
+
+  routes.get("/:tenantId/adjustments", async (c) => {
+    const ledger = ledgerFactory();
+    const parsed = parseTenantId(c);
+    if (!parsed.ok) return c.json({ error: TENANT_ID_ERROR }, 400);
+    const tenant = parsed.tenant;
+    const typeParam = c.req.query("type");
+
+    const filters = {
+      type: typeParam,
+      limit: parseIntParam(c.req.query("limit")),
+      offset: parseIntParam(c.req.query("offset")),
+    };
+
+    try {
+      const entries = await ledger.history(tenant, filters);
+      return c.json({ entries, total: entries.length });
+    } catch {
+      return c.json({ error: "Internal server error" }, 500);
+    }
+  });
+
+  return routes;
+}

package/src/api/routes/admin-gpu.ts

@@ -0,0 +1,202 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import type { AuthEnv } from "../../auth/index.js";
+import type { AdminAuditLogger } from "./admin-audit-helper.js";
+import { safeAuditLog } from "./admin-audit-helper.js";
+
+/** Minimal interface for GPU node repository. */
+export interface IGpuNodeRepository {
+  list(): Promise<unknown[]>;
+  getById(nodeId: string): Promise<{ dropletId?: string | number | null; status?: string } | null>;
+}
+
+/** Minimal interface for GPU node provisioner. */
+export interface IGpuNodeProvisioner {
+  provision(opts: { region?: string; size?: string; name?: string }): Promise<{
+    nodeId: string;
+    dropletId?: string | number | null;
+    region?: string;
+    size?: string;
+    monthlyCostCents?: number;
+  }>;
+  destroy(nodeId: string): Promise<void>;
+}
+
+/** Minimal interface for DO API client. */
+export interface IDOClient {
+  listRegions(): Promise<unknown[]>;
+  listSizes(): Promise<unknown[]>;
+  rebootDroplet(dropletId: number): Promise<void>;
+}
+
+export interface AdminGpuDeps {
+  gpuNodeRepo: () => IGpuNodeRepository;
+  gpuNodeProvisioner: () => IGpuNodeProvisioner;
+  doClient: () => IDOClient;
+  auditLogger?: () => AdminAuditLogger;
+  logger?: { error(msg: string, meta?: Record<string, unknown>): void };
+}
+
+/**
+ * Create admin GPU node management routes.
+ * Static routes (/regions, /sizes) are registered BEFORE parameterized routes (/:nodeId).
+ */
+export function createAdminGpuRoutes(deps: AdminGpuDeps): Hono<AuthEnv> {
+  const routes = new Hono<AuthEnv>();
+
+  routes.get("/", async (c) => {
+    const nodes = await deps.gpuNodeRepo().list();
+    return c.json({ success: true, nodes, count: nodes.length });
+  });
+
+  routes.post("/", async (c) => {
+    try {
+      const body = await c.req.json();
+      const parsed = z
+        .object({
+          region: z.string().min(1).max(20).optional(),
+          size: z.string().min(1).max(50).optional(),
+          name: z
+            .string()
+            .min(1)
+            .max(63)
+            .regex(/^[a-zA-Z0-9][a-zA-Z0-9-]*$/)
+            .optional(),
+        })
+        .parse(body);
+
+      const provisioner = deps.gpuNodeProvisioner();
+      const result = await provisioner.provision(parsed);
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "gpu.provision",
+        category: "config",
+        details: {
+          nodeId: result.nodeId,
+          dropletId: result.dropletId,
+          region: result.region,
+          size: result.size,
+          monthlyCostCents: result.monthlyCostCents,
+        },
+      });
+
+      return c.json({ success: true, node: result }, 201);
+    } catch (err) {
+      if (err instanceof z.ZodError) {
+        return c.json({ success: false, error: err.issues }, 400);
+      }
+      if (err instanceof Error && err.message.includes("DO_API_TOKEN")) {
+        return c.json(
+          { success: false, error: "GPU provisioning not configured. Set DO_API_TOKEN environment variable." },
+          503,
+        );
+      }
+      deps.logger?.error("GPU node provisioning failed", { err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.get("/regions", async (c) => {
+    try {
+      const regions = await deps.doClient().listRegions();
+      return c.json({ success: true, regions });
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("DO_API_TOKEN")) {
+        return c.json(
+          { success: false, error: "GPU provisioning not configured. Set DO_API_TOKEN environment variable." },
+          503,
+        );
+      }
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.get("/sizes", async (c) => {
+    try {
+      const sizes = await deps.doClient().listSizes();
+      return c.json({ success: true, sizes });
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("DO_API_TOKEN")) {
+        return c.json(
+          { success: false, error: "GPU provisioning not configured. Set DO_API_TOKEN environment variable." },
+          503,
+        );
+      }
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.get("/:nodeId", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+    const node = await deps.gpuNodeRepo().getById(nodeId);
+    if (!node) {
+      return c.json({ success: false, error: "GPU node not found" }, 404);
+    }
+    return c.json({ success: true, node });
+  });
+
+  routes.delete("/:nodeId", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      const node = await deps.gpuNodeRepo().getById(nodeId);
+      if (!node) {
+        return c.json({ success: false, error: "GPU node not found" }, 404);
+      }
+      if (node.status === "provisioning" || node.status === "bootstrapping") {
+        return c.json(
+          {
+            success: false,
+            error: `Cannot destroy GPU node in ${node.status} state — wait until provisioning/bootstrapping completes`,
+          },
+          409,
+        );
+      }
+
+      await deps.gpuNodeProvisioner().destroy(nodeId);
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "gpu.destroy",
+        category: "config",
+        details: { nodeId },
+      });
+
+      return c.json({ success: true });
+    } catch (err) {
+      deps.logger?.error("GPU node destruction failed", { nodeId, err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.post("/:nodeId/reboot", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      const node = await deps.gpuNodeRepo().getById(nodeId);
+      if (!node) {
+        return c.json({ success: false, error: "GPU node not found" }, 404);
+      }
+      if (!node.dropletId) {
+        return c.json({ success: false, error: "GPU node has no droplet assigned" }, 400);
+      }
+
+      await deps.doClient().rebootDroplet(Number(node.dropletId));
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "gpu.reboot",
+        category: "config",
+        details: { nodeId, dropletId: node.dropletId },
+      });
+
+      return c.json({ success: true, message: `Reboot initiated for GPU node ${nodeId}` });
+    } catch (err) {
+      deps.logger?.error("GPU node reboot failed", { nodeId, err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  return routes;
+}