@wopr-network/platform-core 1.68.0 → 1.70.0

package/src/server/index.ts

@@ -0,0 +1,92 @@
+/**
+ * platform-core server entry point.
+ *
+ * Re-exports types, the test helper, and provides bootPlatformServer() —
+ * the single-call boot function products use to go from a declarative
+ * BootConfig to a running Hono server with DI container.
+ */
+
+import { Hono } from "hono";
+import type { BootConfig, BootResult } from "./boot-config.js";
+import { buildContainer } from "./container.js";
+import { type BackgroundHandles, gracefulShutdown, startBackgroundServices } from "./lifecycle.js";
+import { mountRoutes } from "./mount-routes.js";
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export type { BootConfig, BootResult, FeatureFlags, RoutePlugin } from "./boot-config.js";
+export type {
+  CryptoServices,
+  FleetServices,
+  GatewayServices,
+  HotPoolServices,
+  PlatformContainer,
+  StripeServices,
+} from "./container.js";
+export { buildContainer } from "./container.js";
+export { type BackgroundHandles, gracefulShutdown, startBackgroundServices } from "./lifecycle.js";
+export { type MountConfig, mountRoutes } from "./mount-routes.js";
+export { createTestContainer } from "./test-container.js";
+
+// ---------------------------------------------------------------------------
+// bootPlatformServer
+// ---------------------------------------------------------------------------
+
+/**
+ * Boot a fully-wired platform server from a declarative config.
+ *
+ * 1. Builds the DI container (DB, migrations, product config, feature slices)
+ * 2. Creates a Hono app and mounts shared routes
+ * 3. Returns start/stop lifecycle hooks
+ *
+ * Products call this from their index.ts:
+ * ```ts
+ * const { app, container, start, stop } = await bootPlatformServer({
+ *   slug: "paperclip",
+ *   databaseUrl: process.env.DATABASE_URL!,
+ *   provisionSecret: process.env.PROVISION_SECRET!,
+ *   features: { fleet: true, crypto: true, stripe: true, gateway: true, hotPool: false },
+ * });
+ * await start();
+ * ```
+ */
+export async function bootPlatformServer(config: BootConfig): Promise<BootResult> {
+  const container = await buildContainer(config);
+  const app = new Hono();
+
+  mountRoutes(
+    app,
+    container,
+    {
+      provisionSecret: config.provisionSecret,
+      cryptoServiceKey: config.cryptoServiceKey,
+      platformDomain: container.productConfig.product?.domain ?? "localhost",
+    },
+    config.routes,
+  );
+
+  let handles: BackgroundHandles | null = null;
+  let server: { close: () => void } | null = null;
+
+  return {
+    app,
+    container,
+    start: async (port?: number) => {
+      const { serve } = await import("@hono/node-server");
+      const listenPort = port ?? config.port ?? 3001;
+      const hostname = config.host ?? "0.0.0.0";
+
+      server = serve({ fetch: app.fetch, hostname, port: listenPort }, async () => {
+        handles = await startBackgroundServices(container);
+      });
+    },
+    stop: async () => {
+      if (server) server.close();
+      if (handles) {
+        await gracefulShutdown(container, handles);
+      }
+    },
+  };
+}

package/src/server/lifecycle.ts

@@ -0,0 +1,72 @@
+/**
+ * Lifecycle management — background services and graceful shutdown.
+ *
+ * Products currently handle background tasks in their serve() callbacks.
+ * This module provides a standard interface for starting and stopping
+ * those tasks so bootPlatformServer can manage them uniformly.
+ */
+
+import type { PlatformContainer } from "./container.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BackgroundHandles {
+  intervals: ReturnType<typeof setInterval>[];
+  unsubscribes: (() => void)[];
+}
+
+// ---------------------------------------------------------------------------
+// startBackgroundServices
+// ---------------------------------------------------------------------------
+
+/**
+ * Start background services that run after the server is listening.
+ *
+ * Currently a thin scaffold — the hooks exist so products can migrate their
+ * background tasks (fleet updater, notification worker, caddy hydration,
+ * health monitor) incrementally without changing the boot contract.
+ */
+export async function startBackgroundServices(container: PlatformContainer): Promise<BackgroundHandles> {
+  const handles: BackgroundHandles = { intervals: [], unsubscribes: [] };
+
+  // Caddy proxy hydration (if fleet + proxy are enabled)
+  if (container.fleet?.proxy) {
+    try {
+      await container.fleet.proxy.start?.();
+    } catch {
+      // Non-fatal — proxy sync will retry on next health tick
+    }
+  }
+
+  // Hot pool manager (if enabled)
+  if (container.hotPool) {
+    try {
+      const poolHandles = await container.hotPool.start();
+      handles.unsubscribes.push(poolHandles.stop);
+    } catch {
+      // Non-fatal — pool will be empty but claiming falls back to cold create
+    }
+  }
+
+  return handles;
+}
+
+// ---------------------------------------------------------------------------
+// gracefulShutdown
+// ---------------------------------------------------------------------------
+
+/**
+ * Graceful shutdown: clear intervals, call unsubscribe hooks, close the
+ * database connection pool.
+ */
+export async function gracefulShutdown(container: PlatformContainer, handles: BackgroundHandles): Promise<void> {
+  for (const interval of handles.intervals) {
+    clearInterval(interval);
+  }
+  for (const unsub of handles.unsubscribes) {
+    unsub();
+  }
+  await container.pool.end();
+}

package/src/server/middleware/__tests__/admin-auth.test.ts

@@ -0,0 +1,67 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import { createAdminAuthMiddleware } from "../admin-auth.js";
+
+function createApp(adminApiKey: string) {
+  const app = new Hono();
+  app.use("/admin/*", createAdminAuthMiddleware({ adminApiKey }));
+  app.get("/admin/status", (c) => c.json({ ok: true }));
+  return app;
+}
+
+describe("createAdminAuthMiddleware", () => {
+  const API_KEY = "test-admin-key-abc123";
+
+  it("returns 401 without Authorization header", async () => {
+    const app = createApp(API_KEY);
+    const res = await app.request("/admin/status");
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toContain("Unauthorized");
+  });
+
+  it("returns 401 with wrong API key", async () => {
+    const app = createApp(API_KEY);
+    const res = await app.request("/admin/status", {
+      headers: { authorization: "Bearer wrong-key" },
+    });
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toContain("invalid admin credentials");
+  });
+
+  it("passes through with correct API key (timing-safe)", async () => {
+    const app = createApp(API_KEY);
+    const res = await app.request("/admin/status", {
+      headers: { authorization: `Bearer ${API_KEY}` },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+  });
+
+  it("rejects keys of different length (timing-safe length check)", async () => {
+    const app = createApp(API_KEY);
+    // Key with same prefix but different length
+    const res = await app.request("/admin/status", {
+      headers: { authorization: `Bearer ${API_KEY}extra` },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 503 when admin key is not configured (fail-closed)", async () => {
+    const app = createApp("");
+    const res = await app.request("/admin/status", {
+      headers: { authorization: "Bearer anything" },
+    });
+    expect(res.status).toBe(503);
+  });
+
+  it("rejects non-Bearer auth schemes", async () => {
+    const app = createApp(API_KEY);
+    const res = await app.request("/admin/status", {
+      headers: { authorization: `Basic ${API_KEY}` },
+    });
+    expect(res.status).toBe(401);
+  });
+});

package/src/server/middleware/__tests__/tenant-proxy.test.ts

@@ -0,0 +1,308 @@
+import { Hono } from "hono";
+import { beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+import type { ProxyRoute } from "../../../proxy/types.js";
+import { createTestContainer } from "../../test-container.js";
+import {
+  buildUpstreamHeaders,
+  createTenantProxyMiddleware,
+  extractTenantSubdomain,
+  type ProxyUserInfo,
+  type TenantProxyConfig,
+} from "../tenant-proxy.js";
+
+// ---------------------------------------------------------------------------
+// extractTenantSubdomain unit tests
+// ---------------------------------------------------------------------------
+
+describe("extractTenantSubdomain", () => {
+  const domain = "example.com";
+
+  it("extracts a valid subdomain", () => {
+    expect(extractTenantSubdomain("alice.example.com", domain)).toBe("alice");
+  });
+
+  it("returns null for the root domain", () => {
+    expect(extractTenantSubdomain("example.com", domain)).toBeNull();
+  });
+
+  it("returns null for reserved subdomains", () => {
+    expect(extractTenantSubdomain("app.example.com", domain)).toBeNull();
+    expect(extractTenantSubdomain("api.example.com", domain)).toBeNull();
+    expect(extractTenantSubdomain("admin.example.com", domain)).toBeNull();
+  });
+
+  it("returns null for nested subdomains", () => {
+    expect(extractTenantSubdomain("deep.alice.example.com", domain)).toBeNull();
+  });
+
+  it("strips port before matching", () => {
+    expect(extractTenantSubdomain("alice.example.com:3000", domain)).toBe("alice");
+  });
+
+  it("returns null for non-matching domain", () => {
+    expect(extractTenantSubdomain("alice.other.com", domain)).toBeNull();
+  });
+
+  it("returns null for invalid subdomain characters", () => {
+    expect(extractTenantSubdomain("al!ce.example.com", domain)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildUpstreamHeaders unit tests
+// ---------------------------------------------------------------------------
+
+describe("buildUpstreamHeaders", () => {
+  it("copies only allowlisted headers and injects platform headers", () => {
+    const incoming = new Headers({
+      "content-type": "application/json",
+      "x-evil-header": "should-not-pass",
+      host: "alice.example.com",
+    });
+    const user: ProxyUserInfo = { id: "u1", email: "a@b.com", name: "Alice" };
+    const result = buildUpstreamHeaders(incoming, user, "alice");
+
+    expect(result.get("content-type")).toBe("application/json");
+    expect(result.get("x-evil-header")).toBeNull();
+    expect(result.get("x-platform-user-id")).toBe("u1");
+    expect(result.get("x-platform-tenant")).toBe("alice");
+    expect(result.get("x-platform-user-email")).toBe("a@b.com");
+    expect(result.get("x-platform-user-name")).toBe("Alice");
+    expect(result.get("host")).toBe("alice.example.com");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createTenantProxyMiddleware integration tests
+// ---------------------------------------------------------------------------
+
+describe("createTenantProxyMiddleware", () => {
+  const DOMAIN = "example.com";
+  let resolveUser: Mock<(req: Request) => Promise<ProxyUserInfo | undefined>>;
+  let config: TenantProxyConfig;
+
+  beforeEach(() => {
+    resolveUser = vi.fn<(req: Request) => Promise<ProxyUserInfo | undefined>>();
+    config = { platformDomain: DOMAIN, resolveUser };
+  });
+
+  function createApp(container: ReturnType<typeof createTestContainer>) {
+    const app = new Hono();
+    app.use("/*", createTenantProxyMiddleware(container, config));
+    app.get("/fallthrough", (c) => c.json({ fallthrough: true }));
+    return app;
+  }
+
+  it("passes through non-tenant requests (no subdomain)", async () => {
+    const container = createTestContainer();
+    const app = createApp(container);
+    const res = await app.request("http://example.com/fallthrough");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.fallthrough).toBe(true);
+    // resolveUser should not be called for non-tenant requests
+    expect(resolveUser).not.toHaveBeenCalled();
+  });
+
+  it("returns 401 for unauthenticated tenant requests", async () => {
+    const container = createTestContainer({
+      fleet: {
+        profileStore: { list: vi.fn().mockResolvedValue([]) } as never,
+        proxy: { getRoutes: vi.fn().mockReturnValue([]) } as never,
+        manager: {} as never,
+        docker: {} as never,
+        serviceKeyRepo: {} as never,
+      },
+    });
+    resolveUser.mockResolvedValue(undefined);
+    const app = createApp(container);
+
+    const res = await app.request("http://alice.example.com/dashboard", {
+      headers: { host: "alice.example.com" },
+    });
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toContain("Authentication required");
+  });
+
+  it("returns 503 when fleet services are not available", async () => {
+    const container = createTestContainer({ fleet: null });
+    const app = createApp(container);
+
+    const res = await app.request("http://alice.example.com/dashboard", {
+      headers: { host: "alice.example.com" },
+    });
+    expect(res.status).toBe(503);
+    const body = await res.json();
+    expect(body.error).toContain("Fleet services unavailable");
+  });
+
+  it("returns 403 when user is not a member of the tenant", async () => {
+    const mockProfile = { name: "alice", tenantId: "tenant-1" };
+    const container = createTestContainer({
+      fleet: {
+        profileStore: { list: vi.fn().mockResolvedValue([mockProfile]) } as never,
+        proxy: {
+          getRoutes: vi
+            .fn()
+            .mockReturnValue([{ subdomain: "alice", upstreamHost: "127.0.0.1", upstreamPort: 4000, healthy: true }]),
+        } as never,
+        manager: {} as never,
+        docker: {} as never,
+        serviceKeyRepo: {} as never,
+      },
+      orgMemberRepo: {
+        findMember: vi.fn().mockResolvedValue(null),
+        listMembers: vi.fn(),
+        addMember: vi.fn(),
+        updateMemberRole: vi.fn(),
+        removeMember: vi.fn(),
+        countAdminsAndOwners: vi.fn(),
+        listInvites: vi.fn(),
+        createInvite: vi.fn(),
+        findInviteById: vi.fn(),
+        findInviteByToken: vi.fn(),
+        deleteInvite: vi.fn(),
+        deleteAllMembers: vi.fn(),
+        deleteAllInvites: vi.fn(),
+        listOrgsByUser: vi.fn(),
+        markInviteAccepted: vi.fn(),
+      },
+    });
+    resolveUser.mockResolvedValue({ id: "user-99", email: "user@test.com" });
+    const app = createApp(container);
+
+    const res = await app.request("http://alice.example.com/dashboard", {
+      headers: { host: "alice.example.com" },
+    });
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toContain("not a member");
+  });
+
+  it("proxies correctly when authorized", async () => {
+    const mockProfile = { name: "alice", tenantId: "tenant-1" };
+    const upstreamRoute: ProxyRoute = {
+      instanceId: "inst-1",
+      subdomain: "alice",
+      upstreamHost: "127.0.0.1",
+      upstreamPort: 4000,
+      healthy: true,
+    };
+    const container = createTestContainer({
+      fleet: {
+        profileStore: { list: vi.fn().mockResolvedValue([mockProfile]) } as never,
+        proxy: { getRoutes: vi.fn().mockReturnValue([upstreamRoute]) } as never,
+        manager: {} as never,
+        docker: {} as never,
+        serviceKeyRepo: {} as never,
+      },
+      orgMemberRepo: {
+        findMember: vi.fn().mockResolvedValue({ orgId: "tenant-1", userId: "user-1", role: "member" }),
+        listMembers: vi.fn(),
+        addMember: vi.fn(),
+        updateMemberRole: vi.fn(),
+        removeMember: vi.fn(),
+        countAdminsAndOwners: vi.fn(),
+        listInvites: vi.fn(),
+        createInvite: vi.fn(),
+        findInviteById: vi.fn(),
+        findInviteByToken: vi.fn(),
+        deleteInvite: vi.fn(),
+        deleteAllMembers: vi.fn(),
+        deleteAllInvites: vi.fn(),
+        listOrgsByUser: vi.fn(),
+        markInviteAccepted: vi.fn(),
+      },
+    });
+    resolveUser.mockResolvedValue({ id: "user-1", email: "user@test.com" });
+
+    // Mock global fetch to simulate upstream response
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ upstream: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    try {
+      const app = createApp(container);
+      const res = await app.request("http://alice.example.com/api/data?q=1", {
+        headers: { host: "alice.example.com" },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.upstream).toBe(true);
+
+      // Verify fetch was called with the correct upstream URL
+      const fetchCall = (globalThis.fetch as Mock).mock.calls[0];
+      expect(fetchCall[0]).toBe("http://127.0.0.1:4000/api/data?q=1");
+
+      // Verify platform headers were injected
+      const headers = fetchCall[1].headers as Headers;
+      expect(headers.get("x-platform-user-id")).toBe("user-1");
+      expect(headers.get("x-platform-tenant")).toBe("alice");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("returns 502 when upstream fetch fails", async () => {
+    const mockProfile = { name: "bob", tenantId: "user-1" };
+    const upstreamRoute: ProxyRoute = {
+      instanceId: "inst-2",
+      subdomain: "bob",
+      upstreamHost: "127.0.0.1",
+      upstreamPort: 4001,
+      healthy: true,
+    };
+    const container = createTestContainer({
+      fleet: {
+        profileStore: { list: vi.fn().mockResolvedValue([mockProfile]) } as never,
+        proxy: { getRoutes: vi.fn().mockReturnValue([upstreamRoute]) } as never,
+        manager: {} as never,
+        docker: {} as never,
+        serviceKeyRepo: {} as never,
+      },
+    });
+    // tenantId === userId means personal tenant, so validateTenantAccess returns true
+    resolveUser.mockResolvedValue({ id: "user-1" });
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+
+    try {
+      const app = createApp(container);
+      const res = await app.request("http://bob.example.com/test", {
+        headers: { host: "bob.example.com" },
+      });
+      expect(res.status).toBe(502);
+      const body = await res.json();
+      expect(body.error).toContain("Bad Gateway");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("returns 404 when subdomain has no upstream route", async () => {
+    const container = createTestContainer({
+      fleet: {
+        profileStore: { list: vi.fn().mockResolvedValue([]) } as never,
+        proxy: { getRoutes: vi.fn().mockReturnValue([]) } as never,
+        manager: {} as never,
+        docker: {} as never,
+        serviceKeyRepo: {} as never,
+      },
+    });
+    resolveUser.mockResolvedValue({ id: "user-1" });
+    const app = createApp(container);
+
+    const res = await app.request("http://ghost.example.com/test", {
+      headers: { host: "ghost.example.com" },
+    });
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toContain("Tenant not found");
+  });
+});

package/src/server/middleware/admin-auth.ts

@@ -0,0 +1,51 @@
+/**
+ * Admin auth middleware — timing-safe API key verification.
+ *
+ * Factory function that creates a Hono middleware handler requiring
+ * a valid admin API key in the Authorization header. Uses
+ * `crypto.timingSafeEqual` to prevent timing side-channel attacks.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+import type { MiddlewareHandler } from "hono";
+
+export interface AdminAuthConfig {
+  adminApiKey: string;
+}
+
+/**
+ * Create an admin auth middleware that validates Bearer tokens
+ * against the configured admin API key using timing-safe comparison.
+ *
+ * Fail-closed: if the key is empty or missing, all requests are rejected.
+ */
+export function createAdminAuthMiddleware(config: AdminAuthConfig): MiddlewareHandler {
+  const { adminApiKey } = config;
+
+  return async (c, next) => {
+    // Fail closed: if no admin key is configured, reject everything
+    if (!adminApiKey) {
+      return c.json({ error: "Admin authentication not configured" }, 503);
+    }
+
+    const authHeader = c.req.header("authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      return c.json({ error: "Unauthorized: admin authentication required" }, 401);
+    }
+
+    const token = authHeader.slice("Bearer ".length).trim();
+    if (!token) {
+      return c.json({ error: "Unauthorized: admin authentication required" }, 401);
+    }
+
+    // Timing-safe comparison: both buffers must be the same length
+    const tokenBuf = Buffer.from(token);
+    const keyBuf = Buffer.from(adminApiKey);
+
+    if (tokenBuf.length !== keyBuf.length || !timingSafeEqual(tokenBuf, keyBuf)) {
+      return c.json({ error: "Unauthorized: invalid admin credentials" }, 401);
+    }
+
+    return next();
+  };
+}