@advicenxt/sbp-server 0.1.0

package/dist/validation.js

@@ -0,0 +1,205 @@
+/**
+ * SBP Input Validation
+ * Zod schemas for all JSON-RPC params and protocol messages
+ */
+import { z } from "zod";
+// ============================================================================
+// DECAY MODEL SCHEMAS
+// ============================================================================
+const ExponentialDecaySchema = z.object({
+    type: z.literal("exponential"),
+    half_life_ms: z.number().positive(),
+});
+const LinearDecaySchema = z.object({
+    type: z.literal("linear"),
+    rate_per_ms: z.number().positive(),
+});
+const StepDecaySchema = z.object({
+    type: z.literal("step"),
+    steps: z
+        .array(z.object({
+        at_ms: z.number().nonnegative(),
+        intensity: z.number().min(0).max(1),
+    }))
+        .min(1),
+});
+const ImmortalDecaySchema = z.object({
+    type: z.literal("immortal"),
+});
+const DecayModelSchema = z.discriminatedUnion("type", [
+    ExponentialDecaySchema,
+    LinearDecaySchema,
+    StepDecaySchema,
+    ImmortalDecaySchema,
+]);
+// ============================================================================
+// TAG FILTER SCHEMAS
+// ============================================================================
+const TagFilterSchema = z
+    .object({
+    any: z.array(z.string()).optional(),
+    all: z.array(z.string()).optional(),
+    none: z.array(z.string()).optional(),
+})
+    .strict();
+// ============================================================================
+// CONDITION SCHEMAS
+// ============================================================================
+const ThresholdConditionSchema = z.object({
+    type: z.literal("threshold"),
+    trail: z.string().min(1),
+    signal_type: z.string().min(1),
+    tags: TagFilterSchema.optional(),
+    aggregation: z.enum(["sum", "max", "avg", "count", "any"]),
+    operator: z.enum([">=", ">", "<=", "<", "==", "!="]),
+    value: z.number(),
+});
+const RateConditionSchema = z.object({
+    type: z.literal("rate"),
+    trail: z.string().min(1),
+    signal_type: z.string().min(1),
+    metric: z.enum(["emissions_per_second", "intensity_delta"]),
+    window_ms: z.number().positive(),
+    operator: z.enum([">=", ">", "<=", "<"]),
+    value: z.number(),
+});
+const PatternConditionSchema = z.object({
+    type: z.literal("pattern"),
+    sequence: z
+        .array(z.object({
+        trail: z.string().min(1),
+        signal_type: z.string().min(1),
+        min_intensity: z.number().min(0).max(1).optional(),
+    }))
+        .min(1),
+    window_ms: z.number().positive(),
+    ordered: z.boolean().optional(),
+});
+// Recursive condition schema using z.lazy for composite self-reference
+const ScentConditionSchema = z.lazy(() => z.union([
+    ThresholdConditionSchema,
+    z.object({
+        type: z.literal("composite"),
+        operator: z.enum(["and", "or", "not"]),
+        conditions: z.array(ScentConditionSchema).min(1),
+    }),
+    RateConditionSchema,
+    PatternConditionSchema,
+]));
+// ============================================================================
+// OPERATION PARAM SCHEMAS
+// ============================================================================
+export const EmitParamsSchema = z.object({
+    trail: z.string().min(1, "Trail must be a non-empty string"),
+    type: z.string().min(1, "Type must be a non-empty string"),
+    intensity: z.number().min(0).max(1, "Intensity must be between 0 and 1"),
+    decay: DecayModelSchema.optional(),
+    payload: z.record(z.unknown()).optional(),
+    tags: z.array(z.string()).optional(),
+    merge_strategy: z.enum(["reinforce", "replace", "max", "add", "new"]).optional(),
+    source_agent: z.string().optional(),
+});
+export const SniffParamsSchema = z.object({
+    trails: z.array(z.string()).optional(),
+    types: z.array(z.string()).optional(),
+    min_intensity: z.number().min(0).max(1).optional(),
+    max_age_ms: z.number().positive().optional(),
+    tags: TagFilterSchema.optional(),
+    limit: z.number().int().positive().max(10000).optional(),
+    include_evaporated: z.boolean().optional(),
+});
+export const RegisterScentParamsSchema = z.object({
+    scent_id: z.string().min(1, "Scent ID must be a non-empty string"),
+    agent_endpoint: z.string().optional().default(""),
+    condition: ScentConditionSchema,
+    cooldown_ms: z.number().int().nonnegative().optional(),
+    activation_payload: z.record(z.unknown()).optional(),
+    trigger_mode: z.enum(["level", "edge_rising", "edge_falling"]).optional(),
+    hysteresis: z.number().nonnegative().optional(),
+    max_execution_ms: z.number().positive().optional(),
+    context_trails: z.array(z.string()).optional(),
+});
+export const DeregisterScentParamsSchema = z.object({
+    scent_id: z.string().min(1),
+});
+export const EvaporateParamsSchema = z.object({
+    trail: z.string().optional(),
+    types: z.array(z.string()).optional(),
+    older_than_ms: z.number().positive().optional(),
+    below_intensity: z.number().min(0).max(1).optional(),
+    tags: TagFilterSchema.optional(),
+});
+export const InspectParamsSchema = z.object({
+    include: z.array(z.enum(["trails", "scents", "stats"])).optional(),
+});
+export const SubscribeParamsSchema = z.object({
+    scent_id: z.string().min(1),
+});
+export const UnsubscribeParamsSchema = z.object({
+    scent_id: z.string().min(1),
+});
+// ============================================================================
+// JSON-RPC ENVELOPE SCHEMA
+// ============================================================================
+export const JsonRpcRequestSchema = z.object({
+    jsonrpc: z.literal("2.0"),
+    id: z.union([z.string(), z.number()]),
+    method: z.string().min(1),
+    params: z.unknown().optional().default({}),
+});
+// ============================================================================
+// VALIDATION HELPER
+// ============================================================================
+/** Map of method names to their param schemas */
+const METHOD_SCHEMAS = {
+    "sbp/emit": EmitParamsSchema,
+    "sbp/sniff": SniffParamsSchema,
+    "sbp/register_scent": RegisterScentParamsSchema,
+    "sbp/deregister_scent": DeregisterScentParamsSchema,
+    "sbp/evaporate": EvaporateParamsSchema,
+    "sbp/inspect": InspectParamsSchema,
+    "sbp/subscribe": SubscribeParamsSchema,
+    "sbp/unsubscribe": UnsubscribeParamsSchema,
+};
+/**
+ * Validate a JSON-RPC request envelope.
+ * Returns the parsed request or a JSON-RPC error.
+ */
+export function validateEnvelope(body) {
+    const result = JsonRpcRequestSchema.safeParse(body);
+    if (!result.success) {
+        return {
+            ok: false,
+            error: {
+                code: -32600,
+                message: "Invalid JSON-RPC request",
+                data: result.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+            },
+        };
+    }
+    return { ok: true, request: result.data };
+}
+/**
+ * Validate method-specific params.
+ * Returns the parsed params or a JSON-RPC error.
+ */
+export function validateParams(method, params) {
+    const schema = METHOD_SCHEMAS[method];
+    if (!schema) {
+        // Unknown methods are handled by the RPC router, not here
+        return { ok: true, params };
+    }
+    const result = schema.safeParse(params);
+    if (!result.success) {
+        return {
+            ok: false,
+            error: {
+                code: -32602,
+                message: `Invalid params for ${method}`,
+                data: result.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+            },
+        };
+    }
+    return { ok: true, params: result.data };
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/eslint.config.js

@@ -0,0 +1,26 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+      parserOptions: {
+        project: './tsconfig.eslint.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
+  }
+);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@advicenxt/sbp-server",
+  "version": "0.1.0",
+  "description": "Stigmergic Blackboard Protocol - Server Implementation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "sbp-server": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sbp",
+    "stigmergy",
+    "blackboard",
+    "multi-agent",
+    "coordination",
+    "pheromone"
+  ],
+  "author": "SBP Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AdviceNXT/sbp.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://sbp.dev",
+  "bugs": {
+    "url": "https://github.com/AdviceNXT/sbp/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "fastify": "^4.26.0",
+    "uuid": "^13.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^20.11.0",
+    "@types/uuid": "^11.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "globals": "^14.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,89 @@
+/**
+ * SBP Authentication Middleware
+ * Basic API key authentication for the SBP server
+ */
+
+import type { FastifyRequest, FastifyReply, HookHandlerDoneFunction } from "fastify";
+
+export interface AuthOptions {
+    /** List of valid API keys */
+    apiKeys?: string[];
+    /** Whether authentication is required (default: false) */
+    requireAuth?: boolean;
+}
+
+/** Paths that skip authentication */
+const PUBLIC_PATHS = ["/health"];
+
+/**
+ * Create a Fastify onRequest hook for API key authentication.
+ *
+ * Checks the `Authorization: Bearer <key>` header against the
+ * configured list of API keys. Returns 401 with SBP error code
+ * -32005 (UNAUTHORIZED) if the key is missing or invalid.
+ */
+export function createAuthHook(options: AuthOptions) {
+    const { apiKeys = [], requireAuth = false } = options;
+
+    return function authHook(
+        request: FastifyRequest,
+        reply: FastifyReply,
+        done: HookHandlerDoneFunction
+    ): void {
+        // Skip auth if not required
+        if (!requireAuth || apiKeys.length === 0) {
+            done();
+            return;
+        }
+
+        // Skip auth for public paths and OPTIONS
+        const url = request.url.split("?")[0];
+        if (PUBLIC_PATHS.includes(url) || request.method === "OPTIONS") {
+            done();
+            return;
+        }
+
+        // Extract bearer token
+        const authHeader = request.headers.authorization;
+        if (!authHeader) {
+            reply.status(401).send({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32005,
+                    message: "Unauthorized: Missing Authorization header",
+                },
+            });
+            return;
+        }
+
+        const parts = authHeader.split(" ");
+        if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer") {
+            reply.status(401).send({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32005,
+                    message: "Unauthorized: Invalid Authorization header format. Expected: Bearer <api-key>",
+                },
+            });
+            return;
+        }
+
+        const token = parts[1];
+        if (!apiKeys.includes(token)) {
+            reply.status(401).send({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32005,
+                    message: "Unauthorized: Invalid API key",
+                },
+            });
+            return;
+        }
+
+        // Valid key — attach agent info from token position (optional extension point)
+        done();
+    };
+}

package/src/blackboard.test.ts

@@ -0,0 +1,287 @@
+/**
+ * SBP Server Tests
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { Blackboard } from "../src/blackboard.js";
+
+describe("Blackboard", () => {
+  let bb: Blackboard;
+
+  beforeEach(() => {
+    bb = new Blackboard();
+  });
+
+  describe("emit", () => {
+    it("should create a new pheromone", () => {
+      const result = bb.emit({
+        trail: "test.signals",
+        type: "event",
+        intensity: 0.8,
+      });
+
+      expect(result.action).toBe("created");
+      expect(result.new_intensity).toBe(0.8);
+      expect(result.pheromone_id).toBeDefined();
+    });
+
+    it("should reinforce existing pheromone with same payload", () => {
+      bb.emit({
+        trail: "test.signals",
+        type: "event",
+        intensity: 0.5,
+        payload: { id: 1 },
+      });
+
+      const result = bb.emit({
+        trail: "test.signals",
+        type: "event",
+        intensity: 0.8,
+        payload: { id: 1 },
+        merge_strategy: "reinforce",
+      });
+
+      expect(result.action).toBe("reinforced");
+      expect(result.new_intensity).toBe(0.8);
+    });
+
+    it("should create new pheromone with merge_strategy=new", () => {
+      bb.emit({
+        trail: "test.signals",
+        type: "event",
+        intensity: 0.5,
+      });
+
+      bb.emit({
+        trail: "test.signals",
+        type: "event",
+        intensity: 0.8,
+        merge_strategy: "new",
+      });
+
+      expect(bb.size).toBe(2);
+    });
+
+    it("should clamp intensity to [0, 1]", () => {
+      const result1 = bb.emit({
+        trail: "test",
+        type: "a",
+        intensity: 1.5,
+      });
+      expect(result1.new_intensity).toBe(1);
+
+      const result2 = bb.emit({
+        trail: "test",
+        type: "b",
+        intensity: -0.5,
+      });
+      expect(result2.new_intensity).toBe(0);
+    });
+  });
+
+  describe("sniff", () => {
+    beforeEach(() => {
+      bb.emit({ trail: "market.signals", type: "volatility", intensity: 0.8 });
+      bb.emit({ trail: "market.signals", type: "momentum", intensity: 0.5 });
+      bb.emit({ trail: "market.orders", type: "large", intensity: 0.6 });
+    });
+
+    it("should return all pheromones when no filter", () => {
+      const result = bb.sniff();
+      expect(result.pheromones.length).toBe(3);
+    });
+
+    it("should filter by trail", () => {
+      const result = bb.sniff({ trails: ["market.signals"] });
+      expect(result.pheromones.length).toBe(2);
+      expect(result.pheromones.every((p) => p.trail === "market.signals")).toBe(true);
+    });
+
+    it("should filter by type", () => {
+      const result = bb.sniff({ types: ["volatility"] });
+      expect(result.pheromones.length).toBe(1);
+      expect(result.pheromones[0].type).toBe("volatility");
+    });
+
+    it("should filter by min_intensity", () => {
+      const result = bb.sniff({ min_intensity: 0.7 });
+      expect(result.pheromones.length).toBe(1);
+      expect(result.pheromones[0].current_intensity).toBeGreaterThanOrEqual(0.7);
+    });
+
+    it("should return aggregates", () => {
+      const result = bb.sniff();
+      expect(result.aggregates["market.signals/volatility"]).toBeDefined();
+      expect(result.aggregates["market.signals/volatility"].count).toBe(1);
+      expect(result.aggregates["market.signals/volatility"].max_intensity).toBeCloseTo(0.8, 1);
+    });
+
+    it("should sort by intensity descending", () => {
+      const result = bb.sniff();
+      for (let i = 1; i < result.pheromones.length; i++) {
+        expect(result.pheromones[i - 1].current_intensity).toBeGreaterThanOrEqual(
+          result.pheromones[i].current_intensity
+        );
+      }
+    });
+  });
+
+  describe("registerScent", () => {
+    it("should register a new scent", () => {
+      const result = bb.registerScent({
+        scent_id: "test-scent",
+        agent_endpoint: "http://localhost:8080",
+        condition: {
+          type: "threshold",
+          trail: "test",
+          signal_type: "event",
+          aggregation: "max",
+          operator: ">=",
+          value: 0.5,
+        },
+      });
+
+      expect(result.status).toBe("registered");
+      expect(result.scent_id).toBe("test-scent");
+    });
+
+    it("should update existing scent", () => {
+      bb.registerScent({
+        scent_id: "test-scent",
+        agent_endpoint: "http://localhost:8080",
+        condition: {
+          type: "threshold",
+          trail: "test",
+          signal_type: "event",
+          aggregation: "max",
+          operator: ">=",
+          value: 0.5,
+        },
+      });
+
+      const result = bb.registerScent({
+        scent_id: "test-scent",
+        agent_endpoint: "http://localhost:9090",
+        condition: {
+          type: "threshold",
+          trail: "test",
+          signal_type: "event",
+          aggregation: "max",
+          operator: ">=",
+          value: 0.7,
+        },
+      });
+
+      expect(result.status).toBe("updated");
+    });
+
+    it("should report current condition state", () => {
+      bb.emit({ trail: "test", type: "event", intensity: 0.8 });
+
+      const result = bb.registerScent({
+        scent_id: "test-scent",
+        agent_endpoint: "http://localhost:8080",
+        condition: {
+          type: "threshold",
+          trail: "test",
+          signal_type: "event",
+          aggregation: "max",
+          operator: ">=",
+          value: 0.5,
+        },
+      });
+
+      expect(result.current_condition_state.met).toBe(true);
+    });
+  });
+
+  describe("deregisterScent", () => {
+    it("should deregister existing scent", () => {
+      bb.registerScent({
+        scent_id: "test-scent",
+        agent_endpoint: "http://localhost:8080",
+        condition: {
+          type: "threshold",
+          trail: "test",
+          signal_type: "event",
+          aggregation: "max",
+          operator: ">=",
+          value: 0.5,
+        },
+      });
+
+      const result = bb.deregisterScent({ scent_id: "test-scent" });
+      expect(result.status).toBe("deregistered");
+    });
+
+    it("should return not_found for unknown scent", () => {
+      const result = bb.deregisterScent({ scent_id: "unknown" });
+      expect(result.status).toBe("not_found");
+    });
+  });
+
+  describe("evaporate", () => {
+    beforeEach(() => {
+      bb.emit({ trail: "a", type: "x", intensity: 0.1 });
+      bb.emit({ trail: "a", type: "y", intensity: 0.5 });
+      bb.emit({ trail: "b", type: "x", intensity: 0.8 });
+    });
+
+    it("should evaporate by trail", () => {
+      const result = bb.evaporate({ trail: "a" });
+      expect(result.evaporated_count).toBe(2);
+      expect(bb.size).toBe(1);
+    });
+
+    it("should evaporate by intensity threshold", () => {
+      const result = bb.evaporate({ below_intensity: 0.3 });
+      expect(result.evaporated_count).toBe(1);
+    });
+  });
+
+  describe("gc", () => {
+    it("should remove evaporated pheromones", async () => {
+      // Create pheromone with very short half-life
+      bb.emit({
+        trail: "test",
+        type: "event",
+        intensity: 0.5,
+        decay: { type: "linear", rate_per_ms: 1 }, // Decays to 0 in 500ms
+      });
+
+      expect(bb.size).toBe(1);
+
+      // Wait for decay
+      await new Promise((resolve) => setTimeout(resolve, 600));
+
+      const removed = bb.gc();
+      expect(removed).toBe(1);
+      expect(bb.size).toBe(0);
+    });
+  });
+
+  describe("inspect", () => {
+    it("should return stats", () => {
+      bb.emit({ trail: "test", type: "event", intensity: 0.5 });
+      bb.registerScent({
+        scent_id: "s1",
+        agent_endpoint: "http://localhost",
+        condition: { type: "threshold", trail: "test", signal_type: "event", aggregation: "max", operator: ">=", value: 0.1 },
+      });
+
+      const result = bb.inspect({ include: ["stats"] });
+      expect(result.stats).toBeDefined();
+      expect(result.stats!.total_pheromones).toBe(1);
+      expect(result.stats!.total_scents).toBe(1);
+    });
+
+    it("should return trails info", () => {
+      bb.emit({ trail: "a", type: "x", intensity: 0.5 });
+      bb.emit({ trail: "a", type: "y", intensity: 0.3 });
+
+      const result = bb.inspect({ include: ["trails"] });
+      expect(result.trails).toBeDefined();
+      expect(result.trails!.find((t) => t.name === "a")?.pheromone_count).toBe(2);
+    });
+  });
+});