siteshield 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# SiteShield
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SiteShield is a reusable Node.js bot-protection library for Next.js. This repository is **only the npm package**: it has no Next.js application, dashboard, API server, or WordPress plugin. Create a separate Next.js project to integrate and test it.
+
+The current public release is [`siteshield@0.1.0`](https://www.npmjs.com/package/siteshield). Install it in your Next.js project with `npm install siteshield`.
+
+## Structure
+
+```text
+src/core/                  Security decisions, policies and counters
+src/integrations/next.ts   Next.js request adapter and optional event reporter
+tsconfig.json              Package build configuration
+tsconfig.test.json         Test compilation configuration
+package.json               npm exports and scripts
+```
+
+`dist/` is generated by the build and contains the code published to npm. `node_modules/` and `dist-test/` are generated local files.
+
+## Integrate in a separate Next.js project
+
+For Next.js 16 on Node.js, create `proxy.ts` in that other project:
+
+```ts
+import { NextResponse, type NextRequest, type NextFetchEvent } from 'next/server';
+import { createNextShield } from 'siteshield/next';
+
+const shield = createNextShield({
+  siteId: 'my-project',
+  policy: { mode: 'enforce', maxRequests: 30, windowMs: 60_000 },
+  getClientIp: (request) => request.headers.get('x-company-client-ip') ?? undefined,
+});
+
+export async function proxy(request: NextRequest, event: NextFetchEvent) {
+  return (await shield(request, event)) ?? NextResponse.next();
+}
+
+export const config = { matcher: ['/api/:path*', '/login'] };
+```
+
+The IP header is only illustrative. Use it **only** if a trusted reverse proxy overwrites it and direct origin access is prevented. A loopback-only resolver returning `127.0.0.1` is useful for local testing but must never be used in production. Missing trusted IPs and counter failures return 503.
+
+Default counters are in memory, suitable for one process and local demonstrations. For multiple instances, pass a shared `RedisCounterStore` from `siteshield/counters`. `mode: 'monitor'` records would-be restrictions without enforcing them; `mode: 'enforce'` returns 429 for rate limits and 403 for blocks. This is not an edge firewall or a substitute for DDoS protection.
+
+`createApiEventReporter` sends restricted events to a separately hosted SiteShield API. This repository does not provide or deploy that API. Keep site credentials server-side and never use `NEXT_PUBLIC_` for secrets.
+
+## Develop and release
+
+```powershell
+npm install
+npm test
+npm run build
+npm run pack:package
+```
+
+The package created by `npm run pack:package` can be installed into your separate Next.js project for testing. Published versions are immutable: bump the root `package.json` version before `npm run publish:package`. Publishing needs ownership of the `siteshield` npm package and npm account verification.

package/dist/core/counters.d.ts

@@ -0,0 +1,35 @@
+export declare function counterSitePrefix(siteId: string): string;
+export declare function counterKey(siteId: string, ip: string): string;
+export interface CounterSnapshot {
+    requests: number;
+    loginAttempts: number;
+}
+export interface CounterStore {
+    record(key: string, now: number, requestWindowMs: number, isLogin: boolean, loginWindowMs: number): Promise<CounterSnapshot>;
+    reset(prefix?: string): Promise<void>;
+}
+/** Deterministic store for local development and unit tests. */
+export declare class MemoryCounterStore implements CounterStore {
+    private readonly entries;
+    record(key: string, now: number, requestWindowMs: number, isLogin: boolean, loginWindowMs: number): Promise<CounterSnapshot>;
+    reset(prefix?: string): Promise<void>;
+}
+export interface RedisEvalClient {
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+    scanIterator(options: {
+        MATCH: string;
+        COUNT: number;
+    }): AsyncIterable<string[]>;
+    del(key: string): Promise<number>;
+}
+/** Redis-backed sliding windows. The Lua script makes trim/add/count atomic across API instances. */
+export declare class RedisCounterStore implements CounterStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisEvalClient, prefix?: string);
+    record(key: string, now: number, requestWindowMs: number, isLogin: boolean, loginWindowMs: number): Promise<CounterSnapshot>;
+    reset(prefix?: string): Promise<void>;
+}

package/dist/core/counters.js

@@ -0,0 +1,91 @@
+import { createHash, randomUUID } from "node:crypto";
+export function counterSitePrefix(siteId) {
+    return `${createHash("sha256").update(siteId).digest("hex")}:`;
+}
+export function counterKey(siteId, ip) {
+    return `${counterSitePrefix(siteId)}${createHash("sha256").update(ip).digest("hex")}`;
+}
+/** Deterministic store for local development and unit tests. */
+export class MemoryCounterStore {
+    entries = new Map();
+    async record(key, now, requestWindowMs, isLogin, loginWindowMs) {
+        const entry = this.entries.get(key) ?? { requests: [], loginAttempts: [] };
+        entry.requests = entry.requests.filter((at) => now - at < requestWindowMs);
+        entry.loginAttempts = entry.loginAttempts.filter((at) => now - at < loginWindowMs);
+        entry.requests.push(now);
+        if (isLogin)
+            entry.loginAttempts.push(now);
+        this.entries.set(key, entry);
+        return {
+            requests: entry.requests.length,
+            loginAttempts: entry.loginAttempts.length,
+        };
+    }
+    async reset(prefix) {
+        if (!prefix)
+            this.entries.clear();
+        else
+            for (const key of this.entries.keys())
+                if (key.startsWith(prefix))
+                    this.entries.delete(key);
+    }
+}
+/** Redis-backed sliding windows. The Lua script makes trim/add/count atomic across API instances. */
+export class RedisCounterStore {
+    client;
+    prefix;
+    constructor(client, prefix = "siteshield:counter:") {
+        this.client = client;
+        this.prefix = prefix;
+        if (!/^[a-zA-Z0-9:_-]+$/.test(prefix))
+            throw new Error("Invalid Redis counter namespace");
+    }
+    async record(key, now, requestWindowMs, isLogin, loginWindowMs) {
+        const requestKey = `${this.prefix}{${key}}:requests`;
+        const loginKey = `${this.prefix}{${key}}:logins`;
+        const script = `
+      local clock = redis.call('TIME')
+      local now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)
+      local requestWindow = tonumber(ARGV[2])
+      local loginWindow = tonumber(ARGV[3])
+      redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - requestWindow)
+      redis.call('ZADD', KEYS[1], now, ARGV[4])
+      redis.call('EXPIRE', KEYS[1], math.ceil(requestWindow / 1000) + 60)
+      redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now - loginWindow)
+      if ARGV[5] == '1' then
+        redis.call('ZADD', KEYS[2], now, ARGV[4])
+        redis.call('EXPIRE', KEYS[2], math.ceil(loginWindow / 1000) + 60)
+      end
+      return { redis.call('ZCARD', KEYS[1]), redis.call('ZCARD', KEYS[2]) }
+    `;
+        const result = await this.client.eval(script, {
+            keys: [requestKey, loginKey],
+            arguments: [
+                String(now),
+                String(requestWindowMs),
+                String(loginWindowMs),
+                `${now}:${randomUUID()}`,
+                isLogin ? "1" : "0",
+            ],
+        });
+        if (!Array.isArray(result) ||
+            result.length !== 2 ||
+            result.some((value) => !Number.isSafeInteger(value) || Number(value) < 0))
+            throw new Error("Invalid Redis counter response");
+        const values = result;
+        return { requests: Number(values[0]), loginAttempts: Number(values[1]) };
+    }
+    async reset(prefix) {
+        if (prefix && !/^[a-f0-9]{64}:$/.test(prefix))
+            throw new Error("Invalid counter reset prefix");
+        const pattern = prefix ? `${this.prefix}{${prefix}*}:*` : `${this.prefix}*`;
+        for await (const keys of this.client.scanIterator({
+            MATCH: pattern,
+            COUNT: 100,
+        })) {
+            // Delete individually to remain compatible with Redis Cluster hash slots.
+            for (const key of keys)
+                await this.client.del(key);
+        }
+    }
+}

package/dist/core/engine.d.ts

@@ -0,0 +1,9 @@
+import type { Evaluation, RequestContext, SitePolicy } from "./types.js";
+import { type CounterStore } from "./counters.js";
+export declare class SecurityEngine {
+    private readonly policy;
+    private readonly counters;
+    constructor(policy?: Partial<SitePolicy>, counters?: CounterStore);
+    evaluate(request: RequestContext): Promise<Evaluation>;
+    reset(siteId?: string): Promise<void>;
+}

package/dist/core/engine.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { counterKey, counterSitePrefix, MemoryCounterStore } from "./counters.js";
+const defaultPolicy = {
+    mode: "enforce",
+    windowMs: 60_000,
+    maxRequests: 60,
+    loginPaths: ["/wp-login.php", "/wp-admin", "/api/auth/login", "/login"],
+    loginWindowMs: 60_000,
+    maxLoginAttempts: 8,
+    blockScore: 5,
+    limitScore: 3,
+};
+export class SecurityEngine {
+    policy;
+    counters;
+    constructor(policy = {}, counters = new MemoryCounterStore()) {
+        this.policy = { ...defaultPolicy, ...policy };
+        this.counters = counters;
+    }
+    async evaluate(request) {
+        const now = request.now ?? Date.now();
+        const key = counterKey(request.siteId, request.ip);
+        const isLogin = this.policy.loginPaths.some((path) => request.path === path || request.path.startsWith(`${path}/`));
+        const counter = await this.counters.record(key, now, this.policy.windowMs, isLogin, this.policy.loginWindowMs);
+        const reasons = [];
+        let score = 0;
+        const crawler = this.policy.trustedCrawler
+            ? await this.policy.trustedCrawler(request)
+            : false;
+        if (crawler) {
+            reasons.push("verified crawler");
+        }
+        else {
+            if (counter.requests > this.policy.maxRequests) {
+                score += 3;
+                reasons.push("request rate exceeded");
+            }
+            if (isLogin && counter.loginAttempts > this.policy.maxLoginAttempts) {
+                score += 4;
+                reasons.push("login attempt rate exceeded");
+            }
+            if (!request.userAgent ||
+                /bot|crawler|spider|scrapy|curl|python-requests/i.test(request.userAgent)) {
+                score += 1;
+                reasons.push("automated user agent");
+            }
+            if (request.method.toUpperCase() === "POST" && isLogin)
+                score += 1;
+        }
+        let decision = score >= this.policy.blockScore
+            ? "block"
+            : score >= this.policy.limitScore
+                ? "limit"
+                : "allow";
+        if (this.policy.mode === "monitor" && decision !== "allow")
+            decision = "monitor";
+        const event = {
+            id: randomUUID(),
+            siteId: request.siteId,
+            timestamp: new Date(now).toISOString(),
+            request: {
+                siteId: request.siteId,
+                ip: request.ip,
+                method: request.method,
+                path: request.path,
+                userAgent: request.userAgent,
+            },
+            decision,
+            score,
+            reasons,
+            counters: counter,
+        };
+        return { decision, score, reasons, event };
+    }
+    reset(siteId) {
+        return this.counters.reset(siteId ? counterSitePrefix(siteId) : undefined);
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,39 @@
+export type Decision = "allow" | "monitor" | "limit" | "block";
+export interface RequestContext {
+    siteId: string;
+    ip: string;
+    method: string;
+    path: string;
+    userAgent?: string;
+    now?: number;
+}
+export interface SitePolicy {
+    mode: "monitor" | "enforce";
+    windowMs: number;
+    maxRequests: number;
+    loginPaths: string[];
+    loginWindowMs: number;
+    maxLoginAttempts: number;
+    blockScore: number;
+    limitScore: number;
+    trustedCrawler?: (request: RequestContext) => boolean | Promise<boolean>;
+}
+export interface SecurityEvent {
+    id: string;
+    siteId: string;
+    timestamp: string;
+    request: Omit<RequestContext, "now">;
+    decision: Decision;
+    score: number;
+    reasons: string[];
+    counters: {
+        requests: number;
+        loginAttempts: number;
+    };
+}
+export interface Evaluation {
+    decision: Decision;
+    score: number;
+    reasons: string[];
+    event: SecurityEvent;
+}

package/dist/core/types.js

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

package/dist/integrations/next.d.ts

@@ -0,0 +1,15 @@
+import type { CounterStore } from '../core/counters.js';
+import type { Evaluation, SitePolicy } from '../core/types.js';
+export interface NextShieldOptions {
+    siteId: string;
+    policy?: Partial<SitePolicy>;
+    counterStore?: CounterStore;
+    eventReporter?: (evaluation: Evaluation) => Promise<void>;
+    /** Must return an IP from a source sanitized by your hosting platform, never arbitrary client headers. */
+    getClientIp: (request: Request) => string | undefined;
+}
+/** Use this from Next.js middleware/proxy. Return undefined to continue the request. */
+export declare function createNextShield(options: NextShieldOptions): (request: Request, event?: {
+    waitUntil(promise: Promise<unknown>): void;
+}) => Promise<Response | undefined>;
+export declare function createApiEventReporter(apiUrl: string, siteKey: string): (evaluation: Evaluation) => Promise<void>;

package/dist/integrations/next.js

@@ -0,0 +1,74 @@
+import { SecurityEngine } from '../core/engine.js';
+import { isIP } from 'node:net';
+function requestContext(request, siteId, ip) {
+    const url = new URL(request.url);
+    return {
+        siteId,
+        ip,
+        method: request.method,
+        path: url.pathname,
+        userAgent: request.headers.get('user-agent') ?? undefined
+    };
+}
+function enforcementResponse(evaluation, retryAfter) {
+    if (evaluation.decision === 'limit') {
+        return new Response(JSON.stringify({ error: 'rate_limited', requestId: evaluation.event.id }), {
+            status: 429,
+            headers: { 'content-type': 'application/json', 'cache-control': 'no-store', 'retry-after': String(retryAfter), 'x-siteshield-decision': 'limit' }
+        });
+    }
+    return new Response(JSON.stringify({ error: 'request_blocked', requestId: evaluation.event.id }), {
+        status: 403,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-siteshield-decision': 'block' }
+    });
+}
+/** Use this from Next.js middleware/proxy. Return undefined to continue the request. */
+export function createNextShield(options) {
+    if (!options.siteId?.trim())
+        throw new Error('siteId is required');
+    if (!options.getClientIp)
+        throw new Error('getClientIp is required');
+    const engine = new SecurityEngine(options.policy, options.counterStore);
+    const retryAfter = Math.ceil((options.policy?.windowMs ?? 60_000) / 1000);
+    return async function siteShield(request, event) {
+        let evaluation;
+        try {
+            const ip = options.getClientIp(request);
+            if (!ip || !isIP(ip))
+                throw new Error('A trusted client IP is required');
+            evaluation = await engine.evaluate(requestContext(request, options.siteId, ip));
+        }
+        catch {
+            // Counter/identity failures are not disguised as successful protection.
+            return Response.json({ error: 'protection_unavailable' }, { status: 503, headers: { 'cache-control': 'no-store' } });
+        }
+        if (options.eventReporter && evaluation.decision !== 'allow') {
+            const report = Promise.resolve().then(() => options.eventReporter(evaluation)).catch(() => undefined);
+            event?.waitUntil(report);
+        }
+        if (evaluation.decision === 'allow' || evaluation.decision === 'monitor')
+            return undefined;
+        return enforcementResponse(evaluation, retryAfter);
+    };
+}
+export function createApiEventReporter(apiUrl, siteKey) {
+    const url = new URL(apiUrl);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('Invalid API URL');
+    if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+        throw new Error('Use HTTPS for non-local API URLs');
+    if (!siteKey?.trim())
+        throw new Error('siteKey is required');
+    const endpoint = new URL('/v1/events', apiUrl).toString();
+    return async (evaluation) => {
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-siteshield-key': siteKey },
+            body: JSON.stringify(evaluation.event),
+            signal: AbortSignal.timeout(1500),
+            redirect: 'error'
+        });
+        if (!response.ok)
+            throw new Error(`SiteShield event API returned ${response.status}`);
+    };
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "siteshield",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Reusable bot-protection engine and Next.js adapter",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./next": {
+      "types": "./dist/integrations/next.d.ts",
+      "import": "./dist/integrations/next.js"
+    },
+    "./counters": {
+      "types": "./dist/core/counters.d.ts",
+      "import": "./dist/core/counters.js"
+    },
+    "./core": {
+      "types": "./dist/core/engine.d.ts",
+      "import": "./dist/core/engine.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"for (const p of ['dist','dist-test']) require('node:fs').rmSync(p,{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "build:package": "npm run build",
+    "pack:package": "npm run build && npm pack",
+    "publish:package": "npm run build && npm publish --access public",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/core/*.test.js dist-test/integrations/*.test.js",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.7.2"
+  }
+}