@advicenxt/sbp-server 0.1.0

package/src/decay.ts

@@ -0,0 +1,103 @@
+/**
+ * Decay computation utilities
+ */
+
+import type { DecayModel, Pheromone } from "./types.js";
+
+/**
+ * Compute the current intensity of a pheromone after decay
+ */
+export function computeIntensity(pheromone: Pheromone, now: number): number {
+  const elapsed = now - pheromone.last_reinforced_at;
+
+  if (elapsed <= 0) {
+    return pheromone.initial_intensity;
+  }
+
+  switch (pheromone.decay_model.type) {
+    case "exponential": {
+      const halfLife = pheromone.decay_model.half_life_ms;
+      return pheromone.initial_intensity * Math.pow(0.5, elapsed / halfLife);
+    }
+
+    case "linear": {
+      const rate = pheromone.decay_model.rate_per_ms;
+      return Math.max(0, pheromone.initial_intensity - rate * elapsed);
+    }
+
+    case "step": {
+      const steps = pheromone.decay_model.steps;
+      // Find the applicable step (steps should be sorted by at_ms)
+      for (let i = steps.length - 1; i >= 0; i--) {
+        if (elapsed >= steps[i].at_ms) {
+          return steps[i].intensity;
+        }
+      }
+      return pheromone.initial_intensity;
+    }
+
+    case "immortal":
+      return pheromone.initial_intensity;
+
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Check if a pheromone has evaporated below its floor
+ */
+export function isEvaporated(pheromone: Pheromone, now: number): boolean {
+  return computeIntensity(pheromone, now) < pheromone.ttl_floor;
+}
+
+/**
+ * Get the default decay model
+ */
+export function defaultDecay(): DecayModel {
+  return { type: "exponential", half_life_ms: 300000 }; // 5 minutes
+}
+
+/**
+ * Estimate time until pheromone evaporates
+ */
+export function timeToEvaporation(pheromone: Pheromone, now: number): number | null {
+  const currentIntensity = computeIntensity(pheromone, now);
+
+  if (currentIntensity <= pheromone.ttl_floor) {
+    return 0; // Already evaporated
+  }
+
+  switch (pheromone.decay_model.type) {
+    case "exponential": {
+      // Solve: ttl_floor = current * 0.5^(t/halfLife)
+      // t = halfLife * log2(current / ttl_floor)
+      const halfLife = pheromone.decay_model.half_life_ms;
+      const ratio = currentIntensity / pheromone.ttl_floor;
+      return halfLife * Math.log2(ratio);
+    }
+
+    case "linear": {
+      // Solve: ttl_floor = current - rate * t
+      // t = (current - ttl_floor) / rate
+      const rate = pheromone.decay_model.rate_per_ms;
+      if (rate <= 0) return null;
+      return (currentIntensity - pheromone.ttl_floor) / rate;
+    }
+
+    case "step": {
+      // Find next step below threshold
+      const steps = pheromone.decay_model.steps;
+      const elapsed = now - pheromone.last_reinforced_at;
+      for (const step of steps) {
+        if (step.at_ms > elapsed && step.intensity < pheromone.ttl_floor) {
+          return step.at_ms - elapsed;
+        }
+      }
+      return null; // May never evaporate with given steps
+    }
+
+    case "immortal":
+      return null; // Never evaporates
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * SBP Server - Public API
+ */
+
+export { Blackboard, type BlackboardOptions, type TriggerHandler } from "./blackboard.js";
+export { SbpServer, type ServerOptions } from "./server.js";
+export { type PheromoneStore, MemoryStore, createStore, type StoreType } from "./store.js";
+export * from "./types.js";
+export { computeIntensity, isEvaporated, defaultDecay, timeToEvaporation } from "./decay.js";
+export { evaluateCondition, createSnapshot } from "./conditions.js";
+export { createAuthHook, type AuthOptions } from "./auth.js";
+export { createRateLimitHook, type RateLimitOptions } from "./rate-limiter.js";
+export {
+    validateEnvelope,
+    validateParams,
+    EmitParamsSchema,
+    SniffParamsSchema,
+    RegisterScentParamsSchema,
+    DeregisterScentParamsSchema,
+    EvaporateParamsSchema,
+    InspectParamsSchema,
+    JsonRpcRequestSchema,
+} from "./validation.js";
+

package/src/rate-limiter.ts

@@ -0,0 +1,104 @@
+/**
+ * SBP Rate Limiting Middleware
+ * Token bucket rate limiter per agent ID
+ */
+
+import type { FastifyRequest, FastifyReply, HookHandlerDoneFunction } from "fastify";
+
+export interface RateLimitOptions {
+    /** Maximum requests per window (default: 1000) */
+    maxRequests?: number;
+    /** Window duration in milliseconds (default: 60000 = 1 minute) */
+    windowMs?: number;
+    /** Maximum scent registrations per agent (default: 100) */
+    maxScentRegistrations?: number;
+}
+
+interface TokenBucket {
+    tokens: number;
+    lastRefill: number;
+}
+
+/**
+ * Create a Fastify onRequest hook for rate limiting.
+ *
+ * Uses a token bucket algorithm per agent ID (from `Sbp-Agent-Id` header).
+ * Returns JSON-RPC error code -32004 (RATE_LIMITED) when the limit is exceeded.
+ */
+export function createRateLimitHook(options: RateLimitOptions = {}) {
+    const maxRequests = options.maxRequests ?? 1000;
+    const windowMs = options.windowMs ?? 60000;
+    const buckets = new Map<string, TokenBucket>();
+
+    // Periodic cleanup of stale buckets (every 5 minutes)
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [key, bucket] of buckets.entries()) {
+            if (now - bucket.lastRefill > windowMs * 5) {
+                buckets.delete(key);
+            }
+        }
+    }, 300000);
+
+    // Allow GC to clean up the interval if the server is stopped
+    if (cleanupInterval.unref) {
+        cleanupInterval.unref();
+    }
+
+    return function rateLimitHook(
+        request: FastifyRequest,
+        reply: FastifyReply,
+        done: HookHandlerDoneFunction
+    ): void {
+        // Skip rate limiting for health checks and OPTIONS
+        const url = request.url.split("?")[0];
+        if (url === "/health" || request.method === "OPTIONS") {
+            done();
+            return;
+        }
+
+        // Identify the agent
+        const agentId = (request.headers["sbp-agent-id"] as string) || request.ip || "anonymous";
+
+        // Get or create token bucket
+        const now = Date.now();
+        let bucket = buckets.get(agentId);
+
+        if (!bucket) {
+            bucket = { tokens: maxRequests, lastRefill: now };
+            buckets.set(agentId, bucket);
+        }
+
+        // Refill tokens based on elapsed time
+        const elapsed = now - bucket.lastRefill;
+        const refillRate = maxRequests / windowMs;
+        bucket.tokens = Math.min(maxRequests, bucket.tokens + elapsed * refillRate);
+        bucket.lastRefill = now;
+
+        // Check if request is allowed
+        if (bucket.tokens < 1) {
+            const retryAfterMs = Math.ceil((1 - bucket.tokens) / refillRate);
+            reply
+                .status(429)
+                .header("Retry-After", Math.ceil(retryAfterMs / 1000).toString())
+                .send({
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: {
+                        code: -32004,
+                        message: "Rate limited: Too many requests",
+                        data: {
+                            retry_after_ms: retryAfterMs,
+                            limit: maxRequests,
+                            window_ms: windowMs,
+                        },
+                    },
+                });
+            return;
+        }
+
+        // Consume a token
+        bucket.tokens -= 1;
+        done();
+    };
+}

package/src/server.integration.test.ts

@@ -0,0 +1,436 @@
+/**
+ * SBP Server Integration Tests
+ * Tests HTTP endpoints, validation, auth, and session management
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import Fastify from "fastify";
+import { SbpServer } from "./server.js";
+
+// -- Helpers --
+
+function rpc(method: string, params: unknown = {}, id: number | string = 1) {
+    return { jsonrpc: "2.0", id, method, params };
+}
+
+// -- Test Suites --
+
+describe("SBP Server Integration", () => {
+    let server: SbpServer;
+    let app: ReturnType<typeof Fastify>;
+
+    beforeAll(async () => {
+        server = new SbpServer({ port: 0, host: "localhost", logging: false });
+        // Access internal Fastify app for inject() testing
+        app = (server as unknown as { app: ReturnType<typeof Fastify> }).app;
+        await app.ready();
+    });
+
+    afterAll(async () => {
+        await server.stop();
+    });
+
+    // ========================================================================
+    // Health endpoint
+    // ========================================================================
+
+    describe("GET /health", () => {
+        it("returns status ok", async () => {
+            const res = await app.inject({ method: "GET", url: "/health" });
+            expect(res.statusCode).toBe(200);
+            const body = res.json();
+            expect(body.status).toBe("ok");
+            expect(body.version).toBe("0.1.0");
+        });
+    });
+
+    // ========================================================================
+    // JSON-RPC envelope validation
+    // ========================================================================
+
+    describe("JSON-RPC Envelope", () => {
+        it("rejects malformed JSON", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                headers: { "Content-Type": "application/json" },
+                body: "not json{",
+            });
+            expect(res.statusCode).toBe(400); // Fastify returns 400 for unparseable body
+        });
+
+        it("rejects missing jsonrpc field", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: { id: 1, method: "sbp/sniff", params: {} },
+            });
+            const body = res.json();
+            expect(body.error).toBeDefined();
+            expect(body.error.code).toBe(-32600);
+        });
+
+        it("rejects unknown method", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/unknown"),
+            });
+            const body = res.json();
+            expect(body.error).toBeDefined();
+            expect(body.error.code).toBe(-32601);
+        });
+    });
+
+    // ========================================================================
+    // sbp/emit
+    // ========================================================================
+
+    describe("sbp/emit", () => {
+        it("creates a new pheromone", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "test/integration",
+                    type: "signal",
+                    intensity: 0.8,
+                }),
+            });
+            const body = res.json();
+            expect(body.result).toBeDefined();
+            expect(body.result.action).toBe("created");
+            expect(body.result.pheromone_id).toBeTruthy();
+            expect(body.result.new_intensity).toBe(0.8);
+        });
+
+        it("validates intensity range", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "test",
+                    type: "signal",
+                    intensity: 2.0, // Invalid: > 1
+                }),
+            });
+            const body = res.json();
+            expect(body.error).toBeDefined();
+            expect(body.error.code).toBe(-32602);
+        });
+
+        it("rejects empty trail", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "",
+                    type: "signal",
+                    intensity: 0.5,
+                }),
+            });
+            const body = res.json();
+            expect(body.error).toBeDefined();
+            expect(body.error.code).toBe(-32602);
+        });
+
+        it("supports merge strategies", async () => {
+            // First emit
+            await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "merge/test",
+                    type: "alpha",
+                    intensity: 0.5,
+                    merge_strategy: "new",
+                }),
+            });
+
+            // Second emit with replace
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "merge/test",
+                    type: "alpha",
+                    intensity: 0.9,
+                    merge_strategy: "replace",
+                }),
+            });
+            const body = res.json();
+            expect(body.result.action).toBe("replaced");
+        });
+    });
+
+    // ========================================================================
+    // sbp/sniff
+    // ========================================================================
+
+    describe("sbp/sniff", () => {
+        beforeEach(async () => {
+            // Emit a test pheromone
+            await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "sniff/test",
+                    type: "data",
+                    intensity: 0.7,
+                    tags: ["important"],
+                }),
+            });
+        });
+
+        it("returns pheromones matching trail filter", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/sniff", {
+                    trails: ["sniff/test"],
+                }),
+            });
+            const body = res.json();
+            expect(body.result).toBeDefined();
+            expect(body.result.pheromones.length).toBeGreaterThan(0);
+            expect(body.result.pheromones[0].trail).toBe("sniff/test");
+        });
+
+        it("filters by min_intensity", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/sniff", {
+                    trails: ["sniff/test"],
+                    min_intensity: 0.99,
+                }),
+            });
+            const body = res.json();
+            expect(body.result.pheromones.length).toBe(0);
+        });
+
+        it("filters by type", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/sniff", {
+                    trails: ["sniff/test"],
+                    types: ["nonexistent"],
+                }),
+            });
+            const body = res.json();
+            expect(body.result.pheromones.length).toBe(0);
+        });
+
+        it("includes aggregates", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/sniff", { trails: ["sniff/test"] }),
+            });
+            const body = res.json();
+            expect(body.result.aggregates).toBeDefined();
+        });
+    });
+
+    // ========================================================================
+    // sbp/register_scent + sbp/deregister_scent
+    // ========================================================================
+
+    describe("sbp/register_scent & sbp/deregister_scent", () => {
+        it("registers a scent", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/register_scent", {
+                    scent_id: "test-scent-1",
+                    condition: {
+                        type: "threshold",
+                        trail: "test",
+                        signal_type: "alert",
+                        aggregation: "any",
+                        operator: ">=",
+                        value: 0.5,
+                    },
+                }),
+            });
+            const body = res.json();
+            expect(body.result.scent_id).toBe("test-scent-1");
+            expect(body.result.status).toBe("registered");
+        });
+
+        it("deregisters a scent", async () => {
+            // Register first
+            await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/register_scent", {
+                    scent_id: "to-deregister",
+                    condition: {
+                        type: "threshold",
+                        trail: "test",
+                        signal_type: "alert",
+                        aggregation: "any",
+                        operator: ">=",
+                        value: 0.5,
+                    },
+                }),
+            });
+
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/deregister_scent", { scent_id: "to-deregister" }),
+            });
+            const body = res.json();
+            expect(body.result.status).toBe("deregistered");
+        });
+
+        it("returns not_found for unknown scent", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/deregister_scent", { scent_id: "doesnt-exist" }),
+            });
+            const body = res.json();
+            expect(body.result.status).toBe("not_found");
+        });
+    });
+
+    // ========================================================================
+    // sbp/evaporate
+    // ========================================================================
+
+    describe("sbp/evaporate", () => {
+        it("evaporates pheromones by trail", async () => {
+            // Emit
+            await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/emit", {
+                    trail: "evap/test",
+                    type: "temp",
+                    intensity: 0.5,
+                }),
+            });
+
+            // Evaporate
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/evaporate", { trail: "evap/test" }),
+            });
+            const body = res.json();
+            expect(body.result.evaporated_count).toBeGreaterThan(0);
+
+            // Verify gone
+            const sniffRes = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/sniff", { trails: ["evap/test"] }),
+            });
+            expect(sniffRes.json().result.pheromones.length).toBe(0);
+        });
+    });
+
+    // ========================================================================
+    // sbp/inspect
+    // ========================================================================
+
+    describe("sbp/inspect", () => {
+        it("returns trails, scents, and stats", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/inspect", {
+                    include: ["trails", "scents", "stats"],
+                }),
+            });
+            const body = res.json();
+            expect(body.result.trails).toBeDefined();
+            expect(body.result.scents).toBeDefined();
+            expect(body.result.stats).toBeDefined();
+            expect(body.result.stats.uptime_ms).toBeGreaterThanOrEqual(0);
+        });
+    });
+
+    // ========================================================================
+    // Session management
+    // ========================================================================
+
+    describe("Session Management", () => {
+        it("assigns session ID when none provided", async () => {
+            const res = await app.inject({
+                method: "POST",
+                url: "/sbp",
+                payload: rpc("sbp/sniff"),
+            });
+            const sessionId = res.headers["sbp-session-id"];
+            expect(sessionId).toBeTruthy();
+        });
+    });
+});
+
+// ============================================================================
+// Authentication Tests
+// ============================================================================
+
+describe("SBP Server Authentication", () => {
+    let server: SbpServer;
+    let app: ReturnType<typeof Fastify>;
+
+    beforeAll(async () => {
+        server = new SbpServer({
+            port: 0,
+            host: "localhost",
+            logging: false,
+            auth: { apiKeys: ["test-key-123", "test-key-456"], requireAuth: true },
+        });
+        app = (server as unknown as { app: ReturnType<typeof Fastify> }).app;
+        await app.ready();
+    });
+
+    afterAll(async () => {
+        await server.stop();
+    });
+
+    it("rejects requests without Authorization header", async () => {
+        const res = await app.inject({
+            method: "POST",
+            url: "/sbp",
+            payload: rpc("sbp/sniff"),
+        });
+        expect(res.statusCode).toBe(401);
+        const body = res.json();
+        expect(body.error.code).toBe(-32005);
+    });
+
+    it("rejects invalid API key", async () => {
+        const res = await app.inject({
+            method: "POST",
+            url: "/sbp",
+            headers: { Authorization: "Bearer wrong-key" },
+            payload: rpc("sbp/sniff"),
+        });
+        expect(res.statusCode).toBe(401);
+    });
+
+    it("accepts valid API key", async () => {
+        const res = await app.inject({
+            method: "POST",
+            url: "/sbp",
+            headers: { Authorization: "Bearer test-key-123" },
+            payload: rpc("sbp/sniff"),
+        });
+        expect(res.statusCode).toBe(200);
+        expect(res.json().result).toBeDefined();
+    });
+
+    it("allows health check without auth", async () => {
+        const res = await app.inject({
+            method: "GET",
+            url: "/health",
+        });
+        expect(res.statusCode).toBe(200);
+    });
+});