@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/fleet/profile-schema.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { discoveryConfigSchema } from "../discovery/types.js";
+import { imageSchema } from "./types.js";
+/** Release channels for bot deployments */
+export const releaseChannelSchema = z.enum(["stable", "canary", "staging"]);
+/** Restart policy for bot containers */
+export const restartPolicySchema = z.enum(["no", "always", "on-failure", "unless-stopped"]);
+/** Health check configuration */
+export const healthCheckSchema = z.object({
+    endpoint: z.string().default("/health"),
+    intervalSeconds: z.number().int().positive().default(30),
+    timeoutSeconds: z.number().int().positive().default(5),
+    retries: z.number().int().nonnegative().default(3),
+});
+/** Volume mount configuration */
+export const volumeMountSchema = z.object({
+    host: z.string(),
+    container: z.string(),
+    readonly: z.boolean().default(false),
+});
+/** Bot profile template schema — validated when loading YAML templates */
+export const profileTemplateSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    channel: z.object({
+        plugin: z.string().min(1),
+        config: z.record(z.string(), z.string()).default(() => ({})),
+    }),
+    provider: z.object({
+        plugin: z.string().min(1),
+        config: z.record(z.string(), z.string()).default(() => ({})),
+    }),
+    release: releaseChannelSchema,
+    image: imageSchema,
+    restartPolicy: restartPolicySchema.default("unless-stopped"),
+    healthCheck: healthCheckSchema.default(() => ({
+        endpoint: "/health",
+        intervalSeconds: 30,
+        timeoutSeconds: 5,
+        retries: 3,
+    })),
+    volumes: z.array(volumeMountSchema).default(() => []),
+    env: z.record(z.string(), z.string()).default(() => ({})),
+    /** Optional P2P discovery configuration. Defaults to enabled with no extra topics. */
+    discovery: discoveryConfigSchema.optional(),
+});

package/dist/fleet/profile-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fleet/profile-schema.test.js

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { profileTemplateSchema } from "./profile-schema.js";
+describe("profileTemplateSchema", () => {
+    const validTemplate = {
+        name: "stable-discord",
+        description: "Primary user-facing Discord bot",
+        channel: {
+            plugin: "@wopr-network/wopr-plugin-channel-discord",
+            config: { DISCORD_TOKEN: "test-discord-token" },
+        },
+        provider: {
+            plugin: "@wopr-network/wopr-plugin-provider-anthropic",
+            config: { ANTHROPIC_API_KEY: "test-anthropic-key" },
+        },
+        release: "stable",
+        image: "ghcr.io/wopr-network/wopr:stable",
+    };
+    it("accepts a valid template with all required fields", () => {
+        const result = profileTemplateSchema.safeParse(validTemplate);
+        expect(result.success).toBe(true);
+    });
+    it("applies defaults for optional fields", () => {
+        const result = profileTemplateSchema.parse(validTemplate);
+        expect(result.restartPolicy).toBe("unless-stopped");
+        expect(result.healthCheck).toEqual({
+            endpoint: "/health",
+            intervalSeconds: 30,
+            timeoutSeconds: 5,
+            retries: 3,
+        });
+        expect(result.volumes).toEqual([]);
+        expect(result.env).toEqual({});
+    });
+    it("accepts all release channel values", () => {
+        for (const release of ["stable", "canary", "staging"]) {
+            const result = profileTemplateSchema.safeParse({ ...validTemplate, release });
+            expect(result.success).toBe(true);
+        }
+    });
+    it("rejects an invalid release channel", () => {
+        const result = profileTemplateSchema.safeParse({ ...validTemplate, release: "nightly" });
+        expect(result.success).toBe(false);
+    });
+    it("rejects missing name", () => {
+        const { name: _, ...noName } = validTemplate;
+        const result = profileTemplateSchema.safeParse(noName);
+        expect(result.success).toBe(false);
+    });
+    it("rejects empty name", () => {
+        const result = profileTemplateSchema.safeParse({ ...validTemplate, name: "" });
+        expect(result.success).toBe(false);
+    });
+    it("rejects missing channel", () => {
+        const { channel: _, ...noChannel } = validTemplate;
+        const result = profileTemplateSchema.safeParse(noChannel);
+        expect(result.success).toBe(false);
+    });
+    it("rejects missing provider", () => {
+        const { provider: _, ...noProvider } = validTemplate;
+        const result = profileTemplateSchema.safeParse(noProvider);
+        expect(result.success).toBe(false);
+    });
+    it("rejects missing image", () => {
+        const { image: _, ...noImage } = validTemplate;
+        const result = profileTemplateSchema.safeParse(noImage);
+        expect(result.success).toBe(false);
+    });
+    it("accepts valid restart policies", () => {
+        for (const restartPolicy of ["no", "always", "on-failure", "unless-stopped"]) {
+            const result = profileTemplateSchema.safeParse({ ...validTemplate, restartPolicy });
+            expect(result.success).toBe(true);
+        }
+    });
+    it("accepts volume mounts", () => {
+        const result = profileTemplateSchema.parse({
+            ...validTemplate,
+            volumes: [{ host: "/data/bot", container: "/app/data", readonly: true }],
+        });
+        expect(result.volumes).toHaveLength(1);
+        expect(result.volumes[0].readonly).toBe(true);
+    });
+    it("defaults volume readonly to false", () => {
+        const result = profileTemplateSchema.parse({
+            ...validTemplate,
+            volumes: [{ host: "/data/bot", container: "/app/data" }],
+        });
+        expect(result.volumes[0].readonly).toBe(false);
+    });
+    it("accepts custom health check", () => {
+        const result = profileTemplateSchema.parse({
+            ...validTemplate,
+            healthCheck: { endpoint: "/ready", intervalSeconds: 10, timeoutSeconds: 2, retries: 5 },
+        });
+        expect(result.healthCheck.endpoint).toBe("/ready");
+        expect(result.healthCheck.intervalSeconds).toBe(10);
+    });
+    it("accepts channel config with empty config", () => {
+        const result = profileTemplateSchema.parse({
+            ...validTemplate,
+            channel: { plugin: "some-plugin" },
+        });
+        expect(result.channel.config).toEqual({});
+    });
+});

package/dist/fleet/profile-store.d.ts

@@ -0,0 +1,21 @@
+import { type BotProfile } from "./types.js";
+export interface IProfileStore {
+    init(): Promise<void>;
+    save(profile: BotProfile): Promise<void>;
+    get(id: string): Promise<BotProfile | null>;
+    list(): Promise<BotProfile[]>;
+    delete(id: string): Promise<boolean>;
+}
+/**
+ * Persists bot profiles as YAML files in a data directory.
+ */
+export declare class ProfileStore implements IProfileStore {
+    private readonly dataDir;
+    constructor(dataDir: string);
+    init(): Promise<void>;
+    private safePath;
+    save(profile: BotProfile): Promise<void>;
+    get(id: string): Promise<BotProfile | null>;
+    list(): Promise<BotProfile[]>;
+    delete(id: string): Promise<boolean>;
+}

package/dist/fleet/profile-store.js

@@ -0,0 +1,76 @@
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import yaml from "js-yaml";
+import { botProfileSchema } from "./types.js";
+/**
+ * Persists bot profiles as YAML files in a data directory.
+ */
+export class ProfileStore {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    async init() {
+        await mkdir(this.dataDir, { recursive: true });
+    }
+    safePath(id) {
+        // UUID validation - primary defense
+        const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (!UUID_RE.test(id)) {
+            throw new Error(`Invalid profile ID: must be a UUID (got: ${id})`);
+        }
+        // Path resolution - safety net against traversal
+        const resolved = resolve(this.dataDir, `${id}.yaml`);
+        const baseDir = resolve(this.dataDir);
+        if (!resolved.startsWith(`${baseDir}${sep}`) && resolved !== baseDir) {
+            throw new Error(`Path traversal detected: ${id}`);
+        }
+        return resolved;
+    }
+    async save(profile) {
+        await this.init();
+        const content = yaml.dump(profile, { sortKeys: true });
+        await writeFile(this.safePath(profile.id), content, "utf-8");
+    }
+    async get(id) {
+        const filePath = this.safePath(id); // Validate ID first - throws on invalid
+        try {
+            const content = await readFile(filePath, "utf-8");
+            const raw = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+            return botProfileSchema.parse(raw);
+        }
+        catch {
+            // Only catch file system errors (file not found, permission denied, etc.)
+            // safePath() validation errors propagate before try block
+            return null;
+        }
+    }
+    async list() {
+        await this.init();
+        const files = await readdir(this.dataDir);
+        const profiles = [];
+        for (const file of files) {
+            if (!file.endsWith(".yaml"))
+                continue;
+            const content = await readFile(join(this.dataDir, file), "utf-8");
+            const raw = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+            const parsed = botProfileSchema.safeParse(raw);
+            if (parsed.success) {
+                profiles.push(parsed.data);
+            }
+        }
+        return profiles;
+    }
+    async delete(id) {
+        const filePath = this.safePath(id); // Validate ID first - throws on invalid
+        try {
+            await rm(filePath);
+            return true;
+        }
+        catch {
+            // Only catch file system errors
+            // safePath() validation errors propagate before try block
+            return false;
+        }
+    }
+}

package/dist/fleet/profile-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fleet/profile-store.test.js

@@ -0,0 +1,161 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { ProfileStore } from "./profile-store.js";
+describe("ProfileStore Path Traversal Protection", () => {
+    let testDataDir;
+    let store;
+    beforeEach(async () => {
+        testDataDir = mkdtempSync(join(tmpdir(), "profile-store-test-"));
+        store = new ProfileStore(testDataDir);
+        await store.init();
+    });
+    afterEach(() => {
+        rmSync(testDataDir, { recursive: true, force: true });
+    });
+    describe("Valid UUIDs", () => {
+        test("should accept valid lowercase UUID", async () => {
+            const validId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+            const profile = {
+                id: validId,
+                tenantId: "test-tenant",
+                name: "test-bot",
+                description: "Test profile",
+                image: "ghcr.io/wopr-network/test:latest",
+                env: {},
+                restartPolicy: "unless-stopped",
+                releaseChannel: "stable",
+                updatePolicy: "manual",
+            };
+            await expect(store.save(profile)).resolves.not.toThrow();
+            const retrieved = await store.get(validId);
+            expect(retrieved).toEqual(profile);
+            await expect(store.delete(validId)).resolves.toBe(true);
+        });
+        test("should accept valid uppercase UUID", async () => {
+            const validId = "A1B2C3D4-E5F6-7890-ABCD-EF1234567890";
+            const profile = {
+                id: validId,
+                tenantId: "test-tenant",
+                name: "test-bot",
+                description: "Test profile",
+                image: "ghcr.io/wopr-network/test:latest",
+                env: {},
+                restartPolicy: "unless-stopped",
+                releaseChannel: "stable",
+                updatePolicy: "manual",
+            };
+            await expect(store.save(profile)).resolves.not.toThrow();
+            const retrieved = await store.get(validId);
+            expect(retrieved).toEqual(profile);
+        });
+        test("should accept valid mixed-case UUID", async () => {
+            const validId = "a1B2c3D4-e5F6-7890-AbCd-Ef1234567890";
+            const profile = {
+                id: validId,
+                tenantId: "test-tenant",
+                name: "test-bot",
+                description: "Test profile",
+                image: "ghcr.io/wopr-network/test:latest",
+                env: {},
+                restartPolicy: "unless-stopped",
+                releaseChannel: "stable",
+                updatePolicy: "manual",
+            };
+            await expect(store.save(profile)).resolves.not.toThrow();
+        });
+    });
+    describe("Path Traversal Attacks", () => {
+        test("should reject Unix path traversal (../../etc/passwd)", async () => {
+            const maliciousId = "../../etc/passwd";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject Windows path traversal (..\\..\\windows\\system32)", async () => {
+            const maliciousId = "..\\..\\windows\\system32";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject mixed path separators (../..\\etc/passwd)", async () => {
+            const maliciousId = "../..\\etc/passwd";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject absolute paths (/etc/passwd)", async () => {
+            const maliciousId = "/etc/passwd";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject Windows absolute paths (C:\\windows\\system32)", async () => {
+            const maliciousId = "C:\\windows\\system32";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject URL-encoded traversal (%2e%2e%2f)", async () => {
+            const maliciousId = "%2e%2e%2f%2e%2e%2fetc%2fpasswd";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject null byte injection (../../etc/passwd\\0)", async () => {
+            const maliciousId = "../../etc/passwd\0.yaml";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject path traversal in delete()", async () => {
+            const maliciousId = "../../etc/passwd";
+            await expect(store.delete(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject path traversal in save()", async () => {
+            const profile = {
+                id: "../../etc/passwd",
+                tenantId: "test-tenant",
+                name: "test-bot",
+                description: "Malicious profile",
+                image: "ghcr.io/wopr-network/test:latest",
+                env: {},
+                restartPolicy: "unless-stopped",
+                releaseChannel: "stable",
+                updatePolicy: "manual",
+            };
+            await expect(store.save(profile)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+    });
+    describe("Invalid ID Formats", () => {
+        test("should reject empty string", async () => {
+            await expect(store.get("")).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject non-UUID string", async () => {
+            await expect(store.get("not-a-uuid")).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject UUID with wrong segment lengths", async () => {
+            const invalidId = "a1b2c3d4-e5f6-7890-abcd-ef12345678901"; // one extra char
+            await expect(store.get(invalidId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject UUID with invalid characters", async () => {
+            const invalidId = "a1b2c3d4-e5f6-7890-abcd-ef12345678gg"; // 'gg' not hex
+            await expect(store.get(invalidId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject UUID missing dashes", async () => {
+            const invalidId = "a1b2c3d4e5f67890abcdef1234567890";
+            await expect(store.get(invalidId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject SQL injection attempt", async () => {
+            const maliciousId = "'; DROP TABLE profiles; --";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+        test("should reject command injection attempt", async () => {
+            const maliciousId = "; rm -rf /";
+            await expect(store.get(maliciousId)).rejects.toThrow("Invalid profile ID: must be a UUID");
+        });
+    });
+    describe("Edge Cases", () => {
+        test("should handle get() returning null for non-existent valid UUID", async () => {
+            const validId = "00000000-0000-0000-0000-000000000000";
+            const result = await store.get(validId);
+            expect(result).toBeNull();
+        });
+        test("should handle delete() returning false for non-existent valid UUID", async () => {
+            const validId = "00000000-0000-0000-0000-000000000000";
+            const result = await store.delete(validId);
+            expect(result).toBe(false);
+        });
+        test("should handle list() without crashing on protected store", async () => {
+            const profiles = await store.list();
+            expect(Array.isArray(profiles)).toBe(true);
+        });
+    });
+});

package/dist/fleet/recovery-manager.d.ts

@@ -0,0 +1,79 @@
+import type { AdminNotifier, RecoveryReport } from "./admin-notifier.js";
+import type { IBotInstanceRepository } from "./bot-instance-repository.js";
+import type { IBotProfileRepository } from "./bot-profile-repository.js";
+import type { NodeConnectionManager } from "./node-connection-manager.js";
+import type { INodeRepository } from "./node-repository.js";
+import type { IRecoveryRepository } from "./recovery-repository.js";
+import type { RecoveryEvent, RecoveryItem } from "./repository-types.js";
+/**
+ * Core recovery orchestrator — handles node failure recovery.
+ *
+ * Recovery flow:
+ * 1. Mark dead node as "recovering"
+ * 2. Get all tenants assigned to dead node
+ * 3. Sort by tier priority (paid before free)
+ * 4. For each tenant:
+ *    a. Find best target node (most free capacity)
+ *    b. Download hot backup on target node
+ *    c. Import and start container on target node
+ *    d. Verify running
+ *    e. Update routing (reassign tenant to new node)
+ * 5. Mark dead node as "offline"
+ * 6. Notify admin
+ */
+export declare class RecoveryManager {
+    private readonly recoveryRepo;
+    private readonly botInstanceRepo;
+    private readonly botProfileRepo;
+    private readonly nodeRepo;
+    private readonly nodeConnections;
+    private readonly notifier;
+    constructor(recoveryRepo: IRecoveryRepository, botInstanceRepo: IBotInstanceRepository, botProfileRepo: IBotProfileRepository, nodeRepo: INodeRepository, nodeConnections: NodeConnectionManager, notifier: AdminNotifier);
+    /**
+     * Get tenants assigned to a node with tier priority sorting
+     * Priority: enterprise > pro > starter > free
+     */
+    private getTenantsWithTierPriority;
+    /**
+     * Trigger recovery of all tenants on a dead node
+     */
+    triggerRecovery(deadNodeId: string, trigger: "heartbeat_timeout" | "manual"): Promise<RecoveryReport>;
+    /**
+     * Recover a single tenant
+     */
+    private recoverTenant;
+    /**
+     * Record a recovery item in the database
+     */
+    private recordItem;
+    /**
+     * Retry recovery for waiting tenants (after new capacity added)
+     */
+    retryWaiting(recoveryEventId: string): Promise<RecoveryReport>;
+    /**
+     * Check all open recovery events for waiting items and either retry them
+     * or mark them as failed if they've exceeded the retry/time cap.
+     *
+     * Called automatically when capacity may have changed (node registered, bot destroyed).
+     */
+    checkAndRetryWaiting(): Promise<void>;
+    /**
+     * Mark waiting items as "failed" and notify admin.
+     */
+    private failExpiredWaitingItems;
+    /**
+     * Check if all items in an event are resolved and mark event as "completed" if so.
+     */
+    private finalizeEventIfComplete;
+    /**
+     * Get recovery event history
+     */
+    listEvents(limit?: number): Promise<RecoveryEvent[]>;
+    /**
+     * Get recovery items for a specific event
+     */
+    getEventDetails(eventId: string): Promise<{
+        event: RecoveryEvent | undefined;
+        items: RecoveryItem[];
+    }>;
+}