guardrail-sdk 0.1.0

package/dist/collector.d.ts

@@ -0,0 +1,21 @@
+import type { SdkEvent, ResolvedConfig } from "./types.js";
+/**
+ * Collects SDK events in-memory and sends them in batches to the GuardRail API.
+ * Also tracks blocked IPs returned by the server.
+ */
+export declare class EventCollector {
+    private config;
+    private queue;
+    private blockedIps;
+    private timer;
+    private flushing;
+    constructor(config: ResolvedConfig);
+    /** Add an event to the queue. Triggers immediate flush if batch is full. */
+    push(event: SdkEvent): void;
+    /** Check if an IP is in the blocked list. */
+    isBlocked(ip: string): boolean;
+    /** Send queued events to the GuardRail API. */
+    flush(): Promise<void>;
+    /** Stop the collector and flush remaining events. */
+    destroy(): Promise<void>;
+}

package/dist/collector.js

@@ -0,0 +1,87 @@
+/**
+ * Collects SDK events in-memory and sends them in batches to the GuardRail API.
+ * Also tracks blocked IPs returned by the server.
+ */
+export class EventCollector {
+    config;
+    queue = [];
+    blockedIps = new Set();
+    timer = null;
+    flushing = false;
+    constructor(config) {
+        this.config = config;
+        // Start periodic flush
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, this.config.flushIntervalMs);
+        // Ensure timer doesn't prevent process exit
+        if (this.timer && typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /** Add an event to the queue. Triggers immediate flush if batch is full. */
+    push(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.config.maxBatchSize) {
+            void this.flush();
+        }
+    }
+    /** Check if an IP is in the blocked list. */
+    isBlocked(ip) {
+        return this.blockedIps.has(ip);
+    }
+    /** Send queued events to the GuardRail API. */
+    async flush() {
+        if (this.flushing || this.queue.length === 0)
+            return;
+        this.flushing = true;
+        const batch = this.queue.splice(0, this.config.maxBatchSize);
+        try {
+            const res = await fetch(`${this.config.apiUrl}/api/events`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.config.projectKey}`,
+                },
+                body: JSON.stringify({ events: batch }),
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                // Update blocked IPs from server response
+                if (data.blockedIps && Array.isArray(data.blockedIps)) {
+                    for (const entry of data.blockedIps) {
+                        this.blockedIps.add(entry.ip);
+                    }
+                }
+                if (this.config.debug) {
+                    console.error(`[guardrail-sdk] Flushed ${batch.length} events. Blocked IPs: ${this.blockedIps.size}`);
+                }
+            }
+            else {
+                // API error — put events back in queue for retry
+                this.queue.unshift(...batch);
+                if (this.config.debug) {
+                    console.error(`[guardrail-sdk] Flush failed (${res.status}). ${batch.length} events re-queued.`);
+                }
+            }
+        }
+        catch (err) {
+            // Network error — put events back in queue for retry
+            this.queue.unshift(...batch);
+            if (this.config.debug) {
+                console.error(`[guardrail-sdk] Flush error: ${err instanceof Error ? err.message : "Unknown error"}. ${batch.length} events re-queued.`);
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /** Stop the collector and flush remaining events. */
+    async destroy() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { GuardrailConfig } from "./types.js";
+export type { GuardrailConfig, SdkEvent, SdkEventType } from "./types.js";
+/**
+ * Express/Connect middleware for GuardRail runtime monitoring.
+ *
+ * Usage:
+ * ```ts
+ * import { guardrail } from 'guardrail-sdk'
+ *
+ * app.use(guardrail({
+ *   projectKey: process.env.GUARDRAIL_PROJECT_KEY
+ * }))
+ * ```
+ */
+export declare function guardrail(config: GuardrailConfig): (req: {
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    headers: Record<string, string | string[] | undefined>;
+    method?: string;
+    path?: string;
+    url?: string;
+}, res: {
+    statusCode: number;
+    status: (code: number) => {
+        json: (body: unknown) => void;
+    };
+    end: (...args: unknown[]) => unknown;
+}, next: () => void) => void;

package/dist/index.js

@@ -0,0 +1,99 @@
+import { EventCollector } from "./collector.js";
+const DEFAULT_API_URL = "https://guardrail-seven.vercel.app";
+const DEFAULT_FLUSH_INTERVAL_MS = 30_000;
+const DEFAULT_MAX_BATCH_SIZE = 50;
+/** Auth endpoint patterns */
+const AUTH_PATTERNS = [
+    /\/login/i,
+    /\/signin/i,
+    /\/sign-in/i,
+    /\/auth/i,
+    /\/api\/auth/i,
+    /\/api\/login/i,
+    /\/session/i,
+];
+function isAuthEndpoint(path) {
+    return AUTH_PATTERNS.some((p) => p.test(path));
+}
+function resolveConfig(config) {
+    return {
+        projectKey: config.projectKey,
+        apiUrl: config.apiUrl || DEFAULT_API_URL,
+        flushIntervalMs: config.flushIntervalMs || DEFAULT_FLUSH_INTERVAL_MS,
+        maxBatchSize: config.maxBatchSize || DEFAULT_MAX_BATCH_SIZE,
+        debug: config.debug || false,
+    };
+}
+/**
+ * Express/Connect middleware for GuardRail runtime monitoring.
+ *
+ * Usage:
+ * ```ts
+ * import { guardrail } from 'guardrail-sdk'
+ *
+ * app.use(guardrail({
+ *   projectKey: process.env.GUARDRAIL_PROJECT_KEY
+ * }))
+ * ```
+ */
+export function guardrail(config) {
+    if (!config.projectKey) {
+        console.error("[guardrail-sdk] Missing projectKey. Set GUARDRAIL_PROJECT_KEY environment variable.");
+        // Return no-op middleware
+        return function guardrailNoOp(_req, _res, next) {
+            next();
+        };
+    }
+    const resolved = resolveConfig(config);
+    const collector = new EventCollector(resolved);
+    if (resolved.debug) {
+        console.error("[guardrail-sdk] Initialized with Express middleware");
+    }
+    // Express middleware signature
+    return function guardrailMiddleware(req, res, next) {
+        const ip = req.ip || req.socket?.remoteAddress || "";
+        const userAgent = req.headers["user-agent"] || "";
+        const path = req.path || req.url || "";
+        const now = new Date().toISOString();
+        // Block denied IPs
+        if (collector.isBlocked(ip)) {
+            res.status(403).json({ error: "Access denied" });
+            return;
+        }
+        // Track auth endpoint responses
+        if (isAuthEndpoint(path) && req.method === "POST") {
+            const origEnd = res.end;
+            res.end = function (...args) {
+                const status = res.statusCode;
+                if (status === 401 || status === 403) {
+                    collector.push({
+                        type: "auth.login_failed",
+                        timestamp: now,
+                        ip,
+                        userAgent,
+                        metadata: { path, method: req.method },
+                    });
+                }
+                else if (status >= 200 && status < 300) {
+                    collector.push({
+                        type: "auth.login_success",
+                        timestamp: now,
+                        ip,
+                        userAgent,
+                        metadata: { path, method: req.method },
+                    });
+                }
+                return origEnd.apply(res, args);
+            };
+        }
+        // Track all API requests
+        collector.push({
+            type: "api.request",
+            timestamp: now,
+            ip,
+            userAgent,
+            metadata: { path, method: req.method },
+        });
+        next();
+    };
+}

package/dist/next.d.ts

@@ -0,0 +1,25 @@
+import type { GuardrailConfig } from "./types.js";
+export type { GuardrailConfig, SdkEvent, SdkEventType } from "./types.js";
+/**
+ * Next.js middleware for GuardRail runtime monitoring.
+ *
+ * Usage in middleware.ts:
+ * ```ts
+ * import { guardrailMiddleware } from 'guardrail-sdk/next'
+ *
+ * const guardrail = guardrailMiddleware({
+ *   projectKey: process.env.GUARDRAIL_PROJECT_KEY!,
+ * })
+ *
+ * export async function middleware(request: Request) {
+ *   const blocked = guardrail(request)
+ *   if (blocked) return blocked
+ * }
+ * ```
+ *
+ * Note: Next.js middleware cannot access response status codes,
+ * so auth.login_failed/success events cannot be auto-detected.
+ * For auth event tracking, call the GuardRail API directly from
+ * your API route handlers.
+ */
+export declare function guardrailMiddleware(config: GuardrailConfig): (request: Request) => Response | null;

package/dist/next.js

@@ -0,0 +1,110 @@
+import { EventCollector } from "./collector.js";
+const DEFAULT_API_URL = "https://guardrail-seven.vercel.app";
+const DEFAULT_FLUSH_INTERVAL_MS = 30_000;
+const DEFAULT_MAX_BATCH_SIZE = 50;
+const AUTH_PATTERNS = [
+    /\/login/i,
+    /\/signin/i,
+    /\/sign-in/i,
+    /\/auth/i,
+    /\/api\/auth/i,
+    /\/api\/login/i,
+    /\/session/i,
+];
+function isAuthEndpoint(path) {
+    return AUTH_PATTERNS.some((p) => p.test(path));
+}
+function resolveConfig(config) {
+    return {
+        projectKey: config.projectKey,
+        apiUrl: config.apiUrl || DEFAULT_API_URL,
+        flushIntervalMs: config.flushIntervalMs || DEFAULT_FLUSH_INTERVAL_MS,
+        maxBatchSize: config.maxBatchSize || DEFAULT_MAX_BATCH_SIZE,
+        debug: config.debug || false,
+    };
+}
+// Singleton collector (Next.js middleware runs in edge runtime, persists across requests)
+let collector = null;
+function getCollector(config) {
+    if (!collector) {
+        collector = new EventCollector(config);
+    }
+    return collector;
+}
+/**
+ * Next.js middleware for GuardRail runtime monitoring.
+ *
+ * Usage in middleware.ts:
+ * ```ts
+ * import { guardrailMiddleware } from 'guardrail-sdk/next'
+ *
+ * const guardrail = guardrailMiddleware({
+ *   projectKey: process.env.GUARDRAIL_PROJECT_KEY!,
+ * })
+ *
+ * export async function middleware(request: Request) {
+ *   const blocked = guardrail(request)
+ *   if (blocked) return blocked
+ * }
+ * ```
+ *
+ * Note: Next.js middleware cannot access response status codes,
+ * so auth.login_failed/success events cannot be auto-detected.
+ * For auth event tracking, call the GuardRail API directly from
+ * your API route handlers.
+ */
+export function guardrailMiddleware(config) {
+    if (!config.projectKey) {
+        console.error("[guardrail-sdk] Missing projectKey. Set GUARDRAIL_PROJECT_KEY environment variable.");
+        return function guardrailNoOp() {
+            return null;
+        };
+    }
+    const resolved = resolveConfig(config);
+    if (resolved.debug) {
+        console.error("[guardrail-sdk] Initialized with Next.js middleware");
+    }
+    /**
+     * Call this function inside your Next.js middleware.
+     * Returns a Response if the IP is blocked, or null to continue.
+     */
+    return function guardrail(request) {
+        const c = getCollector(resolved);
+        const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+            request.headers.get("x-real-ip") ||
+            "";
+        const userAgent = request.headers.get("user-agent") || "";
+        let pathname;
+        try {
+            pathname = new URL(request.url).pathname;
+        }
+        catch {
+            pathname = request.url;
+        }
+        // Block denied IPs
+        if (c.isBlocked(ip)) {
+            return new Response(JSON.stringify({ error: "Access denied" }), {
+                status: 403,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const now = new Date().toISOString();
+        // Track API requests
+        c.push({
+            type: "api.request",
+            timestamp: now,
+            ip,
+            userAgent,
+            metadata: { path: pathname, method: request.method },
+        });
+        // Track auth endpoints (request-only, since we can't see response status)
+        if (isAuthEndpoint(pathname) && request.method === "POST") {
+            // We log as a generic auth attempt — the server-side analyzer
+            // will use the api.request pattern combined with other signals
+            if (resolved.debug) {
+                console.error(`[guardrail-sdk] Auth endpoint hit: ${pathname} from ${ip}`);
+            }
+        }
+        return null; // Continue to next middleware
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+export type SdkEventType = "auth.login_failed" | "auth.login_success" | "api.request";
+export interface SdkEvent {
+    type: SdkEventType;
+    timestamp: string;
+    ip: string;
+    userAgent: string;
+    metadata: Record<string, unknown>;
+}
+export interface GuardrailConfig {
+    /** Project key from GuardRail dashboard (gr_sk_...) */
+    projectKey: string;
+    /** API URL override (default: https://guardrail-seven.vercel.app) */
+    apiUrl?: string;
+    /** Batch flush interval in ms (default: 30000) */
+    flushIntervalMs?: number;
+    /** Max events per batch (default: 50) */
+    maxBatchSize?: number;
+    /** Enable debug logging to stderr (default: false) */
+    debug?: boolean;
+}
+export interface ResolvedConfig {
+    projectKey: string;
+    apiUrl: string;
+    flushIntervalMs: number;
+    maxBatchSize: number;
+    debug: boolean;
+}
+export interface BlockedIpEntry {
+    ip: string;
+    blockedAt: string;
+}
+export interface FlushResponse {
+    received: number;
+    blockedIps: BlockedIpEntry[];
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "guardrail-sdk",
+  "version": "0.1.0",
+  "description": "GuardRail runtime security monitoring SDK — detect brute force, suspicious logins, and traffic spikes",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./next": "./dist/next.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}