@wopr-network/platform-core 1.68.0 → 1.69.0

package/src/server/container.ts

@@ -0,0 +1,237 @@
+/**
+ * PlatformContainer — the central DI container for platform-core.
+ *
+ * Products compose a container at boot time, enabling only the feature
+ * slices they need. Nullable sub-containers (fleet, crypto, stripe,
+ * gateway, hotPool) let each product opt in without pulling unused deps.
+ */
+
+import type Docker from "dockerode";
+import type { Pool } from "pg";
+import type Stripe from "stripe";
+import type { IUserRoleRepository } from "../auth/user-role-repository.js";
+import type { ICryptoChargeRepository } from "../billing/crypto/charge-store.js";
+import type { IWebhookSeenRepository } from "../billing/webhook-seen-repository.js";
+import type { ILedger } from "../credits/ledger.js";
+import type { ITenantCustomerRepository } from "../credits/tenant-customer-repository.js";
+import type { DrizzleDb } from "../db/index.js";
+import type { FleetManager } from "../fleet/fleet-manager.js";
+import type { IProfileStore } from "../fleet/profile-store.js";
+import type { IServiceKeyRepository } from "../gateway/service-key-repository.js";
+import type { ProductConfig } from "../product-config/repository-types.js";
+import type { ProxyManagerInterface } from "../proxy/types.js";
+import type { IOrgMemberRepository } from "../tenancy/org-member-repository.js";
+import type { OrgService } from "../tenancy/org-service.js";
+import type { BootConfig } from "./boot-config.js";
+
+// ---------------------------------------------------------------------------
+// Feature sub-containers
+// ---------------------------------------------------------------------------
+
+export interface FleetServices {
+  manager: FleetManager;
+  docker: Docker;
+  proxy: ProxyManagerInterface;
+  profileStore: IProfileStore;
+  serviceKeyRepo: IServiceKeyRepository;
+}
+
+export interface CryptoServices {
+  chargeRepo: ICryptoChargeRepository;
+  webhookSeenRepo: IWebhookSeenRepository;
+}
+
+export interface StripeServices {
+  stripe: Stripe;
+  webhookSecret: string;
+  customerRepo: ITenantCustomerRepository;
+  processor: { handleWebhook(payload: Buffer, signature: string): Promise<unknown> };
+}
+
+export interface GatewayServices {
+  serviceKeyRepo: IServiceKeyRepository;
+}
+
+export interface HotPoolServices {
+  /** Will be typed properly when extracted from nemoclaw. */
+  poolManager: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Main container
+// ---------------------------------------------------------------------------
+
+export interface PlatformContainer {
+  db: DrizzleDb;
+  pool: Pool;
+  productConfig: ProductConfig;
+  creditLedger: ILedger;
+  orgMemberRepo: IOrgMemberRepository;
+  orgService: OrgService;
+  userRoleRepo: IUserRoleRepository;
+
+  /** Null when the product does not use fleet management. */
+  fleet: FleetServices | null;
+  /** Null when the product does not accept crypto payments. */
+  crypto: CryptoServices | null;
+  /** Null when the product does not use Stripe billing. */
+  stripe: StripeServices | null;
+  /** Null when the product does not expose a metered inference gateway. */
+  gateway: GatewayServices | null;
+  /** Null when the product does not use a hot-pool of pre-provisioned instances. */
+  hotPool: HotPoolServices | null;
+}
+
+// ---------------------------------------------------------------------------
+// buildContainer — construct a PlatformContainer from a BootConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a fully-wired PlatformContainer from a declarative BootConfig.
+ *
+ * Construction order mirrors the proven boot sequence from product index.ts
+ * files: DB pool -> Drizzle -> migrations -> productConfig -> credit ledger
+ * -> org repos -> org service -> user role repo -> feature services.
+ *
+ * Feature sub-containers (fleet, crypto, stripe, gateway) are only
+ * constructed when their corresponding feature flag is enabled in
+ * `bootConfig.features`. Disabled features yield `null`.
+ */
+export async function buildContainer(bootConfig: BootConfig): Promise<PlatformContainer> {
+  if (!bootConfig.databaseUrl) {
+    throw new Error("buildContainer: databaseUrl is required");
+  }
+
+  // 1. Database pool
+  const { Pool: PgPool } = await import("pg");
+  const pool: Pool = new PgPool({ connectionString: bootConfig.databaseUrl });
+
+  // 2. Drizzle ORM instance
+  const { createDb } = await import("../db/index.js");
+  const db = createDb(pool);
+
+  // 3. Run Drizzle migrations
+  const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+  const path = await import("node:path");
+  const migrationsFolder = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../drizzle");
+  await migrate(db as never, { migrationsFolder });
+
+  // 4. Bootstrap product config from DB (auto-seeds from presets if needed)
+  const { platformBoot } = await import("../product-config/boot.js");
+  const { config: productConfig } = await platformBoot({ slug: bootConfig.slug, db });
+
+  // 5. Credit ledger
+  const { DrizzleLedger } = await import("../credits/ledger.js");
+  const creditLedger: ILedger = new DrizzleLedger(db as never);
+  await creditLedger.seedSystemAccounts();
+
+  // 6. Org repositories + OrgService
+  const { DrizzleOrgMemberRepository } = await import("../tenancy/org-member-repository.js");
+  const { DrizzleOrgRepository } = await import("../tenancy/drizzle-org-repository.js");
+  const { OrgService: OrgServiceClass } = await import("../tenancy/org-service.js");
+  const { BetterAuthUserRepository } = await import("../db/auth-user-repository.js");
+
+  const orgMemberRepo: IOrgMemberRepository = new DrizzleOrgMemberRepository(db as never);
+  const orgRepo = new DrizzleOrgRepository(db as never);
+  const authUserRepo = new BetterAuthUserRepository(pool);
+  const orgService = new OrgServiceClass(orgRepo, orgMemberRepo, db as never, {
+    userRepo: authUserRepo,
+  });
+
+  // 7. User role repository
+  const { DrizzleUserRoleRepository } = await import("../auth/user-role-repository.js");
+  const userRoleRepo: IUserRoleRepository = new DrizzleUserRoleRepository(db as never);
+
+  // 8. Fleet services (when enabled)
+  let fleet: FleetServices | null = null;
+  if (bootConfig.features.fleet) {
+    const { FleetManager: FleetManagerClass } = await import("../fleet/fleet-manager.js");
+    const { ProfileStore } = await import("../fleet/profile-store.js");
+    const { ProxyManager } = await import("../proxy/manager.js");
+    const { DrizzleServiceKeyRepository } = await import("../gateway/service-key-repository.js");
+    const DockerModule = await import("dockerode");
+    const DockerClass = DockerModule.default ?? DockerModule;
+
+    const docker: Docker = new (DockerClass as new () => Docker)();
+    const fleetDataDir = productConfig.fleet?.fleetDataDir ?? "/data/fleet";
+    const profileStore: IProfileStore = new ProfileStore(fleetDataDir);
+    const proxy: ProxyManagerInterface = new ProxyManager();
+    const serviceKeyRepo: IServiceKeyRepository = new DrizzleServiceKeyRepository(db as never);
+    const manager: FleetManager = new FleetManagerClass(
+      docker,
+      profileStore,
+      undefined, // platformDiscovery
+      undefined, // networkPolicy
+      proxy,
+    );
+
+    fleet = { manager, docker, proxy, profileStore, serviceKeyRepo };
+  }
+
+  // 9. Crypto services (when enabled)
+  let crypto: CryptoServices | null = null;
+  if (bootConfig.features.crypto) {
+    const { DrizzleCryptoChargeRepository } = await import("../billing/crypto/charge-store.js");
+    const { DrizzleWebhookSeenRepository } = await import("../billing/drizzle-webhook-seen-repository.js");
+
+    const chargeRepo: ICryptoChargeRepository = new DrizzleCryptoChargeRepository(db as never);
+    const webhookSeenRepo: IWebhookSeenRepository = new DrizzleWebhookSeenRepository(db as never);
+
+    crypto = { chargeRepo, webhookSeenRepo };
+  }
+
+  // 10. Stripe services (when enabled)
+  let stripe: StripeServices | null = null;
+  if (bootConfig.features.stripe && bootConfig.stripeSecretKey) {
+    const StripeModule = await import("stripe");
+    const StripeClass = StripeModule.default;
+    const stripeClient: Stripe = new StripeClass(bootConfig.stripeSecretKey);
+
+    const { DrizzleTenantCustomerRepository } = await import("../billing/stripe/tenant-store.js");
+    const { loadCreditPriceMap } = await import("../billing/stripe/credit-prices.js");
+    const { StripePaymentProcessor } = await import("../billing/stripe/stripe-payment-processor.js");
+
+    const customerRepo = new DrizzleTenantCustomerRepository(db as never);
+    const priceMap = loadCreditPriceMap();
+    const processor = new StripePaymentProcessor({
+      stripe: stripeClient,
+      tenantRepo: customerRepo,
+      webhookSecret: bootConfig.stripeWebhookSecret ?? "",
+      priceMap,
+      creditLedger,
+    });
+
+    stripe = {
+      stripe: stripeClient,
+      webhookSecret: bootConfig.stripeWebhookSecret ?? "",
+      customerRepo,
+      processor,
+    };
+  }
+
+  // 11. Gateway services (when enabled)
+  let gateway: GatewayServices | null = null;
+  if (bootConfig.features.gateway) {
+    const { DrizzleServiceKeyRepository } = await import("../gateway/service-key-repository.js");
+    const serviceKeyRepo: IServiceKeyRepository = new DrizzleServiceKeyRepository(db as never);
+    gateway = { serviceKeyRepo };
+  }
+
+  // hotPool: not yet implemented — needs nemoclaw extraction
+  const hotPool: HotPoolServices | null = null;
+
+  return {
+    db,
+    pool,
+    productConfig,
+    creditLedger,
+    orgMemberRepo,
+    orgService,
+    userRoleRepo,
+    fleet,
+    crypto,
+    stripe,
+    gateway,
+    hotPool,
+  };
+}

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,62 @@
+/**
+ * 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
+    }
+  }
+
+  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);
+  });
+});