siteshield 0.1.0 → 0.1.1

package/README.md

@@ -1,27 +1,33 @@
-# SiteShield Next.js adapter
+# SiteShield
 
-SiteShield's Node.js security engine and Next.js request adapter. This is an early MVP for team demonstrations, not a complete edge firewall. It makes local decisions and can report restricted events asynchronously to a separately deployed SiteShield API.
+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.
 
-## Install
+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`.
 
-```sh
-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
 ```
 
-Create `proxy.ts` in a Next.js 16 app (Node.js runtime):
+`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, createApiEventReporter } from 'siteshield/next';
+import { createNextShield } from 'siteshield/next';
 
 const shield = createNextShield({
-  siteId: process.env.SITESHIELD_SITE_ID!,
-  policy: { mode: 'monitor' },
+  siteId: 'my-project',
+  policy: { mode: 'enforce', maxRequests: 30, windowMs: 60_000 },
   getClientIp: (request) => request.headers.get('x-company-client-ip') ?? undefined,
-  eventReporter: createApiEventReporter(
-    process.env.SITESHIELD_API_URL!,
-    process.env.SITESHIELD_SITE_KEY!,
-  ),
 });
 
 export async function proxy(request: NextRequest, event: NextFetchEvent) {
@@ -31,6 +37,19 @@ export async function proxy(request: NextRequest, event: NextFetchEvent) {
 export const config = { matcher: ['/api/:path*', '/login'] };
 ```
 
-The example IP header is **not** automatically trustworthy. Only use it if your ingress overwrites client-supplied headers and prevents direct origin access. A missing/invalid IP or counter-store failure produces HTTP 503, never a silent allow. `mode: 'monitor'` records would-be restrictions without enforcing them; test and set `mode: 'enforce'` when ready. The local in-memory counter default is only appropriate for a single instance. For multiple instances, pass a shared `RedisCounterStore` via `counterStore` (exported from `siteshield/counters`).
+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 API URL, site ID, and site key must be server-only environment variables (never `NEXT_PUBLIC_`). The central SiteShield API must be deployed and configured separately. Do not expose this package as a substitute for network/edge DDoS protection. The WordPress plugin is distributed separately from this npm 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/package.json

@@ -1,23 +1,42 @@
 {
   "name": "siteshield",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Reusable bot-protection engine and Next.js adapter",
   "type": "module",
-  "engines": { "node": ">=20" },
-  "publishConfig": { "access": "public" },
-  "files": ["dist"],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     "./next": {
       "types": "./dist/integrations/next.d.ts",
       "import": "./dist/integrations/next.js"
     },
-    "./core": {
-      "types": "./dist/core/engine.d.ts",
-      "import": "./dist/core/engine.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"
   }
 }