@deployowl/guard 2.2.2

package/README.md

@@ -0,0 +1,77 @@
+# @deployowl/guard
+
+Enterprise-grade, platform-agnostic bot detection and security middleware.
+
+## Installation
+
+```
+npm install @deployowl/guard
+```
+
+## Usage
+
+```js
+import { OwlGuard } from "@deployowl/guard";
+
+const owlguard = new OwlGuard({
+  apiKey: "owl_live_xxx",       // Optional: enables enrichment signals
+  blockScore: 80,               // Bot score threshold for 403 block
+  challengeScore: 50,           // Bot score threshold for JS challenge
+});
+
+const result = await owlguard.decision(request);
+
+if (result.blocked) {
+  return new Response(result.reason, { status: result.status });
+}
+// Continue to your handler
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | OwlGuard install key. Enables enrichment signals. |
+| `blockScore` | `number` | `80` | Bot score threshold for hard 403 block. |
+| `challengeScore` | `number` | `50` | Bot score threshold for JS proof-of-work challenge. |
+| `rateLimit` | `object` | `{windowMs: 60000, max: 120}` | Per-IP rate limiting. |
+| `bypassPaths` | `string[]` | `[]` | Path prefixes that skip all checks. |
+| `allowlist` | `object` | — | IP/apiKey allowlist. |
+| `denylist` | `object` | — | IP/ASN denylist. |
+| `geo` | `object` | — | Country-level geo fencing. |
+| `validation` | `object` | — | Body size, methods, content-types. |
+| `challenge` | `object` | `{difficulty: "000"}` | SHA-256 proof-of-work config. |
+| `log` | `string` | `"warn"` | Verbosity: `none`/`block`/`warn`/`info`. |
+| `reporting` | `boolean` | `false` | **Opt-in**: send blocked-decision events to reporting worker. |
+| `reportingSecret` | `string` | — | **Required when `reporting: true`**. Obtain from dashboard. |
+
+## What Data Is Sent
+
+### Enrichment — to `enrich.deployowl.com/enrich` (when `apiKey` is set)
+
+- End-user IP address (for threat scoring)
+- Request headers (when running inside an edge worker)
+- **Authentication:** apiKey only
+- **Purpose:** Obtain threatScore, country, ASN, Tor/VPN flags
+
+### Decision Reporting — to `security.deployowl.com` (only when `reporting: true`)
+
+- IP, country, pathname, method, block reason, score
+- **Authentication:** `reportingSecret` (config-provided)
+- **Purpose:** Analytics, billing, dashboard visibility
+
+### Remote Config — to `api.deployowl.com/api/v1/config` (when `apiKey` is set)
+
+- API key sent via `X-API-Key` header only (not URL)
+- **Purpose:** Fetch WAF rules, rate limits, custom routes
+
+## Privacy & Security
+
+- **No environment variables collected.**
+- **No dependency manifests collected.**
+- Reporting is **opt-in** and requires a user-provided secret.
+- API keys are sent via headers, never URL query strings.
+
+## License
+
+Proprietary © DeployOwl. All rights reserved.

package/adapters/cloudflare-kv.js

@@ -0,0 +1,57 @@
+/**
+ * owlguard — adapters/cloudflare-kv.js
+ * Pre-built storage adapter for Cloudflare KV namespaces.
+ *
+ * Usage (Cloudflare Worker):
+ *   import { CloudflareKVAdapter } from "owlguard/adapters/cloudflare-kv";
+ *
+ *   // In your wrangler.toml, bind a KV namespace:
+ *   // [[kv_namespaces]]
+ *   // binding = "OWL_RATE_LIMIT"
+ *   // id = "your-kv-namespace-id"
+ *
+ *   const owl = new OwlGuard({
+ *     storage: new CloudflareKVAdapter(env.OWL_RATE_LIMIT),
+ *   });
+ *
+ * This gives you globally-consistent rate limiting across all Cloudflare
+ * Worker isolates — every edge location shares the same KV counter.
+ */
+
+export class CloudflareKVAdapter {
+  /**
+   * @param {object} namespace — A Cloudflare KV namespace binding.
+   */
+  constructor(namespace) {
+    this._kv = namespace;
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<{ ts: number, count: number } | null>}
+   */
+  async get(key) {
+    try {
+      const value = await this._kv.get(key, { type: "json" });
+      return value ?? null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {{ ts: number, count: number }} value
+   * @param {number} ttlSeconds
+   * @returns {Promise<void>}
+   */
+  async put(key, value, ttlSeconds) {
+    try {
+      await this._kv.put(key, JSON.stringify(value), {
+        expirationTtl: Math.ceil(ttlSeconds),
+      });
+    } catch (_) {
+      // Write failure — degrade gracefully
+    }
+  }
+}

package/adapters/redis.js

@@ -0,0 +1,61 @@
+/**
+ * owlguard — adapters/redis.js
+ * Pre-built storage adapter for Redis.
+ *
+ * Compatible with both:
+ *  - node-redis (v4+): client.setEx(key, ttl, value)
+ *  - ioredis:          client.setex(key, ttl, value)  [lowercase]
+ *
+ * Usage:
+ *   import { createClient } from "redis";
+ *   import { RedisAdapter } from "owlguard/adapters/redis";
+ *
+ *   const redis = createClient({ url: process.env.REDIS_URL });
+ *   await redis.connect();
+ *
+ *   const owl = new OwlGuard({
+ *     storage: new RedisAdapter(redis),
+ *   });
+ */
+
+export class RedisAdapter {
+  /**
+   * @param {object} client — A redis or ioredis client instance.
+   */
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<{ ts: number, count: number } | null>}
+   */
+  async get(key) {
+    try {
+      const raw = await this._client.get(key);
+      return raw ? JSON.parse(raw) : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {{ ts: number, count: number }} value
+   * @param {number} ttlSeconds
+   * @returns {Promise<void>}
+   */
+  async put(key, value, ttlSeconds) {
+    try {
+      const serialized = JSON.stringify(value);
+      // Support both node-redis (setEx) and ioredis (setex)
+      if (typeof this._client.setEx === "function") {
+        await this._client.setEx(key, ttlSeconds, serialized);
+      } else {
+        await this._client.setex(key, ttlSeconds, serialized);
+      }
+    } catch (_) {
+      // Write failure — degrade gracefully, rate limiting continues in-memory
+    }
+  }
+}

package/dist/index.js

@@ -0,0 +1,100 @@
+var Z=Object.defineProperty;var q=(e,t)=>()=>(e&&(t=e(e=0)),t);var ee=(e,t)=>{for(var n in t)Z(e,n,{get:t[n],enumerable:!0})};var X={};ee(X,{computeSignature:()=>N,verifyHandshake:()=>ue});async function N(e,t){let n=new TextEncoder,o=n.encode(t),a=n.encode(e),s=await crypto.subtle.importKey("raw",o,{name:"HMAC",hash:"SHA-256"},!1,["sign"]),r=await crypto.subtle.sign("HMAC",s,a);return Array.from(new Uint8Array(r)).map(l=>l.toString(16).padStart(2,"0")).join("")}async function ue(e,t){let n=e["x-owlguard-signature"],o=e["x-owlguard-timestamp"];if(!n||!o)return!1;let a=parseInt(o,10);if(isNaN(a)||Math.abs(Date.now()-a)>5*60*1e3)return!1;try{let r=await N(o,t);return n===r}catch{return!1}}var U=q(()=>{});function M(e){if(e&&typeof e.ip=="string"&&typeof e.method=="string")return{ip:e.ip??"unknown",country:e.country??null,asn:e.asn??null,userAgent:e.userAgent??"",method:e.method??"GET",pathname:e.pathname??"/",headers:A(e.headers??{}),bodySize:e.bodySize??0,cookie:e.cookie??""};if(e&&typeof e.cf<"u"){let t=new URL(e.url),n=Object.fromEntries(e.headers);return{ip:e.headers.get("CF-Connecting-IP")??"unknown",country:e.cf?.country??null,asn:e.cf?.asn??null,userAgent:e.headers.get("user-agent")??"",method:e.method,pathname:t.pathname,headers:A(n),bodySize:Number(e.headers.get("content-length")??0),cookie:e.headers.get("cookie")??"",cfRaw:{"cf-ipcountry":e.cf?.country??null,"cf-threat-score":e.cf?.threatScore!=null?String(e.cf.threatScore):null,"cf-asn":e.cf?.asn!=null?String(e.cf.asn):null,"cf-bot-score":e.cf?.botManagement?.score!=null?String(e.cf.botManagement.score):null}}}if(e&&typeof e.headers?.get=="function"){let t=new URL(e.url),n=Object.fromEntries(e.headers);return{ip:e.headers.get("x-forwarded-for")?.split(",")[0]?.trim()??e.headers.get("x-real-ip")??"unknown",country:e.headers.get("cf-ipcountry")??null,asn:null,userAgent:e.headers.get("user-agent")??"",method:e.method,pathname:t.pathname,headers:A(n),bodySize:Number(e.headers.get("content-length")??0),cookie:e.headers.get("cookie")??"",cfRaw:null}}if(e&&e.socket!==void 0){let t=e.headers.host??"localhost",n=new URL(e.url??"/",`http://${t}`);return{ip:e.headers["x-forwarded-for"]?.split(",")[0]?.trim()??e.socket?.remoteAddress??"unknown",country:e.headers["cf-ipcountry"]??null,asn:null,userAgent:e.headers["user-agent"]??"",method:e.method??"GET",pathname:n.pathname,headers:A(e.headers),bodySize:Number(e.headers["content-length"]??0),cookie:e.headers.cookie??"",cfRaw:null}}return console.warn("[OwlGuard] Could not detect request platform. Pass a Cloudflare Request, Node IncomingMessage, or a normalized context object."),{ip:"unknown",country:null,asn:null,userAgent:"",method:"GET",pathname:"/",headers:{},bodySize:0,cookie:"",cfRaw:null}}function A(e){let t={};for(let[n,o]of Object.entries(e))t[n.toLowerCase()]=o;return t}var v=class{constructor(){this._store=new Map}async get(t){return this._store.get(t)??null}async put(t,n,o){this._store.set(t,n),this._prune(o*1e3)}_prune(t){let n=Date.now()-t;for(let[o,a]of this._store.entries())a.ts<n&&this._store.delete(o)}};var k={none:0,block:1,warn:2,info:3},C={block:"\u{1F6AB} [OwlGuard] BLOCKED",challenge:"\u{1F989} [OwlGuard] CHALLENGED",allow:"\u2705 [OwlGuard] ALLOWED",skip:"\u23ED\uFE0F  [OwlGuard] SKIPPED"},T=class{constructor(t="warn"){this.level=k[t]??k.warn}block(t,n,o){this.level<k.block||console.warn(`${C.block} | reason=${t} ip=${n.ip} method=${n.method} path=${n.pathname} score=${o}`)}challenge(t,n,o){this.level<k.warn||console.warn(`${C.challenge} | reason=${t} ip=${n.ip} method=${n.method} path=${n.pathname} score=${o}`)}allow(t,n,o){this.level<k.info||console.info(`${C.allow} | reason=${t} ip=${n.ip} method=${n.method} path=${n.pathname} score=${o}`)}skip(t,n){this.level<k.info||console.info(`${C.skip} | reason=${t} ip=${n.ip} path=${n.pathname}`)}};async function j(e,t,n={}){let o=n.windowMs??6e4,a=n.max??120,s=`owlguard:rl:${e}`,r=Date.now(),i=Math.ceil(o/1e3),l=null;try{l=await t.get(s)}catch{return!1}let d=1,c=r;l&&r-l.ts<o&&(d=l.count+1,c=l.ts);try{await t.put(s,{ts:c,count:d},i)}catch{return!1}return d>a}function F(e){return e.split(".").reduce((t,n)=>(t<<8)+parseInt(n,10),0)>>>0}function te(e,t){if(!t.includes("/"))return e===t;let[n,o]=t.split("/"),a=parseInt(o,10);if(isNaN(a)||a<0||a>32)return!1;let s=a===0?0:-1<<32-a>>>0,r=F(e),i=F(n);return(r&s)===(i&s)}function x(e){if(e=e.split("%")[0],e.includes(".")){let r=e.lastIndexOf(":"),i=e.slice(r+1),l=e.slice(0,r),c=F(i).toString(16).padStart(8,"0");e=l+":"+c.slice(0,4)+":"+c.slice(4)}let t=e.split("::");if(t.length>2)return null;let n=t[0]?t[0].split(":"):[],o=t[1]?t[1].split(":"):[],a=8-n.length-o.length;if(a<0)return null;let s=[...n,...Array(a).fill("0"),...o];return s.length!==8?null:s.map(r=>r.padStart(4,"0")).join("")}function ne(e,t){if(!t.includes("/")){let c=x(e),u=x(t);return c!==null&&u!==null&&c===u}let[n,o]=t.split("/"),a=parseInt(o,10);if(isNaN(a)||a<0||a>128)return!1;let s=x(e),r=x(n);if(!s||!r)return!1;let i=BigInt("0x"+s),l=BigInt("0x"+r),d=a===0?0n:~0n<<BigInt(128-a)&0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFn;return(i&d)===(l&d)}function oe(e,t){return!e||!t?!1:e.includes(":")?ne(e,t):te(e,t)}function E(e,t){return!e||!Array.isArray(t)||t.length===0?!1:t.some(n=>oe(e,n))}function B(e,t={}){if(!t||Object.keys(t).length===0)return{allowed:!1,reason:""};if(t.ips?.length&&E(e.ip,t.ips))return{allowed:!0,reason:"allowlist_ip"};let n=t.apiKeys;if(n?.header&&n?.values?.length){let o=e.headers[n.header.toLowerCase()];if(o&&n.values.includes(o))return{allowed:!0,reason:"allowlist_apikey"}}return{allowed:!1,reason:""}}function R(e,t={}){return!t||Object.keys(t).length===0?{denied:!1,reason:""}:t.ips?.length&&E(e.ip,t.ips)?{denied:!0,reason:"denylist_ip"}:t.asns?.length&&e.asn&&t.asns.includes(Number(e.asn))?{denied:!0,reason:"denylist_asn"}:{denied:!1,reason:""}}function I(e,t={}){return!t||Object.keys(t).length===0?{blocked:!1,reason:""}:t.deny?.length&&e&&t.deny.includes(e)?{blocked:!0,reason:"geo_deny"}:t.allow?.length&&(!e||!t.allow.includes(e))?{blocked:!0,reason:"geo_allow"}:{blocked:!1,reason:""}}var ae=["GET","POST","PUT","DELETE","PATCH","HEAD","OPTIONS"],re=["POST","PUT","PATCH"];function G(e,t={}){if(!t||Object.keys(t).length===0)return{valid:!0,status:200,reason:""};if(!(t.allowedMethods??ae).includes(e.method?.toUpperCase()))return{valid:!1,status:405,reason:"method_not_allowed"};if(t.maxBodySize!=null&&e.bodySize>t.maxBodySize)return{valid:!1,status:413,reason:"body_too_large"};if(t.allowedContentTypes?.length&&re.includes(e.method?.toUpperCase())){let o=(e.headers["content-type"]??"").split(";")[0].trim().toLowerCase();if(o&&!t.allowedContentTypes.map(s=>s.toLowerCase().trim()).some(s=>o.startsWith(s)))return{valid:!1,status:415,reason:"content_type_not_allowed"}}return{valid:!0,status:200,reason:""}}var se=[/googlebot/i,/bingbot/i,/slurp/i,/duckduckbot/i,/facebookexternalhit/i,/twitterbot/i,/linkedinbot/i,/whatsapp/i,/applebot/i],ie=[/bot/i,/crawl/i,/spider/i,/scrape/i,/curl/i,/python-requests/i,/axios/i,/wget/i,/go-http-client/i,/headlesschrome/i,/phantomjs/i,/selenium/i,/puppeteer/i,/playwright/i,/java\//i,/ruby/i,/libwww/i],le=[/\/\.env/i,/\/wp-admin/i,/\/wp-login/i,/\/phpmyadmin/i,/\/xmlrpc\.php/i,/\/config\./i,/\/\.git/i,/\/admin/i,/\/shell/i,/\/passwd/i];function K(e,t={},n=null){let o=e.userAgent??"",a=e.headers.accept??"",s=e.headers["accept-language"]??"",r=e.pathname??"",i=t.goodBots??se,l=t.badUaPatterns??ie,d=t.suspiciousPaths??le;if(i.some(u=>u.test(o)))return-1;let c=0;return o?l.some(u=>u.test(o))&&(c+=60):c+=40,s||(c+=15),(!a||a==="*/*")&&(c+=10),d.some(u=>u.test(r))&&(c+=50),n&&(n.threatScore!=null&&(c+=Math.round(n.threatScore/100*60)),n.botScore!=null&&(c+=Math.round((1-n.botScore/99)*60)),n.isTor&&(c+=40),n.isVpn&&(c+=20)),Math.min(c,100)}var ce="https://enrich.deployowl.com/enrich";async function z(e,t,n=50){let{ip:o,cfRaw:a}=e;if(!t||!o||o==="unknown")return null;let s=new AbortController,r=setTimeout(()=>s.abort(),n);try{let i=await fetch(ce,{method:"POST",signal:s.signal,headers:{"content-type":"application/json","x-owl-api-key":t},body:JSON.stringify({ip:o,cfHeaders:a??{}})});if(!i.ok)return null;let l=await i.json();return{threatScore:l.threatScore??null,country:l.country??null,asn:l.asn??null,isTor:l.isTor??!1,isVpn:l.isVpn??!1,botScore:l.botScore??null}}catch{return null}finally{clearTimeout(r)}}async function H(e,t){let n=new TextEncoder,o=await crypto.subtle.importKey("raw",n.encode(t),{name:"HMAC",hash:"SHA-256"},!1,["sign"]),a=await crypto.subtle.sign("HMAC",o,n.encode(e));return Array.prototype.map.call(new Uint8Array(a),s=>("00"+s.toString(16)).slice(-2)).join("")}async function V(e={}){let t=e.difficulty??"000",n=e.title??"Checking your browser...",o=e.message??"Please wait while we verify your request.",a=e.signingSecret??"default_waf_secret",s=e.ip??"",r=crypto.randomUUID?crypto.randomUUID():Math.random().toString(36).slice(2)+Date.now().toString(36),i=Date.now(),l=`${r}:${i}:${s}`,d=await H(l,a),c=`${r}.${i}.${d}`;return`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${O(n)}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      background: #f9fafb;
+      color: #374151;
+    }
+    .card {
+      background: #fff;
+      border: 1px solid #e5e7eb;
+      border-radius: 12px;
+      padding: 2.5rem 3rem;
+      text-align: center;
+      max-width: 420px;
+      width: 90%;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.08);
+    }
+    .owl { font-size: 3rem; margin-bottom: 1rem; }
+    h1 { font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; }
+    p  { font-size: 0.9rem; color: #6b7280; margin-bottom: 1.5rem; }
+    .progress {
+      height: 4px;
+      background: #e5e7eb;
+      border-radius: 2px;
+      overflow: hidden;
+    }
+    .progress-bar {
+      height: 100%;
+      width: 0%;
+      background: #6366f1;
+      border-radius: 2px;
+      transition: width 0.3s ease;
+      animation: pulse 1.5s ease-in-out infinite;
+    }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50%       { opacity: 0.6; }
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="owl">\u{1F989}</div>
+    <h1>${O(n)}</h1>
+    <p>${O(o)}</p>
+    <div class="progress"><div class="progress-bar" id="bar"></div></div>
+  </div>
+
+  <script>
+    (async () => {
+      const challenge   = ${JSON.stringify(c)};
+      const difficulty  = ${JSON.stringify(t)};
+      const bar         = document.getElementById("bar");
+      const maxAttempts = 2_000_000;
+
+      for (let n = 0; n < maxAttempts; n++) {
+        // Yield to browser every 500 iterations to keep UI responsive
+        if (n % 500 === 0) {
+          bar.style.width = Math.min((n / 50000) * 100, 95) + "%";
+          await new Promise(r => setTimeout(r, 0));
+        }
+
+        const buf = await crypto.subtle.digest(
+          "SHA-256",
+          new TextEncoder().encode(challenge + n)
+        );
+        const hex = Array.from(new Uint8Array(buf))
+          .map(b => b.toString(16).padStart(2, "0"))
+          .join("");
+
+        if (hex.startsWith(difficulty)) {
+          bar.style.width = "100%";
+          // SameSite=Lax: safe for top-level nav, blocked on cross-site subrequests
+          document.cookie =
+            "_owl_cleared=" + btoa(challenge + ":" + n + ":" + difficulty) +
+            "; path=/; SameSite=Lax";
+          // Small delay so progress bar visually completes
+          await new Promise(r => setTimeout(r, 300));
+          location.reload();
+          return;
+        }
+      }
+
+      // Exhausted attempts without solving \u2014 reload anyway (rare edge case)
+      location.reload();
+    })();
+  </script>
+</body>
+</html>`}async function W(e,t="000",n="default_waf_secret"){let a=(e.cookie??"").match(/(?:^|;)\s*_owl_cleared=([^;]+)/);if(!a)return!1;let s;try{s=atob(a[1])}catch{return!1}let r=s.split(":");if(r.length<3)return!1;let i=r[r.length-1],l=r[r.length-2],d=r.slice(0,r.length-2).join(":");if(i!==t)return!1;let c=d.split(".");if(c.length!==3)return!1;let[u,b,w]=c,g=parseInt(b);if(isNaN(g))return!1;let h=Date.now();if(h-g>3e5||h-g<-6e4)return!1;let f=e.ip??"",P=`${u}:${g}:${f}`,D=await H(P,n);if(w!==D){let p=`${u}:${g}:`,m=await H(p,n);if(w!==m)return!1}try{let p=new TextEncoder,m=await crypto.subtle.digest("SHA-256",p.encode(d+l));return Array.prototype.map.call(new Uint8Array(m),S=>("00"+S.toString(16)).slice(-2)).join("").startsWith(t)}catch{return!1}}function O(e){return String(e).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#x27;")}async function Y(e,t,n,o){if((t.bypassPaths??[]).some(p=>e.pathname.startsWith(p)))return o.skip("bypass",e),$("bypass");if(await j(e.ip,n,t.rateLimit))return o.block("rate_limited",e,0),y(429,"rate_limited",0);let{allowed:r,reason:i}=B(e,t.allowlist);if(r)return o.allow(i,e,0),$(i);let{denied:l,reason:d}=R(e,t.denylist);if(l)return o.block(d,e,0),y(403,d,0);let{blocked:c,reason:u}=I(e.country,t.geo);if(c)return o.block(u,e,0),y(403,u,0);let{valid:b,status:w,reason:g}=G(e,t.validation);if(!b)return o.block(g,e,0),y(w,g,0);let h=null;if(t.apiKey){let p=t.enrichmentTimeout??50;if(h=await z(e,t.apiKey,p),h?.country&&(e.country=h.country),h?.asn&&t.denylist?.asns?.length){let m={...e,asn:h.asn},{denied:_,reason:S}=R(m,t.denylist);if(_)return o.block(S,e,0),y(403,S,0)}if(h?.country&&h.country!==e.country){let{blocked:m,reason:_}=I(h.country,t.geo);if(m)return o.block(_,e,0),y(403,_,0)}}let f=K(e,t.scorer,h);if(f===-1)return o.allow("good_bot",e,-1),$("good_bot",-1);let P=t.blockScore??80;if(f>=P)return o.block("bot_score_block",e,f),y(403,"bot_score_block",f);let D=t.challengeScore??50;if(f>=D){let p=t.challenge?.difficulty??"000",m=t.challenge?.signingSecret||t.apiKey||"default_waf_secret";if(!await W(e,p,m))return o.challenge("bot_score_challenge",e,f),await de(f,t.challenge,e.ip,m)}return o.allow("allow",e,f),$("allow",f)}function $(e,t=0){return{blocked:!1,status:200,reason:e,score:t,html:null}}function y(e,t,n){return{blocked:!0,status:e,reason:t,score:n,html:null}}async function de(e,t={},n="",o=""){return{blocked:!0,status:200,reason:"challenge",score:e,html:await V({...t,ip:n,signingSecret:o})}}var L="https://security.deployowl.com";async function J(e,t,n,o){if(!n||!o||!L||L.startsWith("__"))return;let a=new AbortController,s=setTimeout(()=>a.abort(),2e3);try{await fetch(L,{method:"POST",signal:a.signal,headers:{"content-type":"application/json","x-owl-secret":o,"x-owl-api-key":n},body:JSON.stringify({ts:Date.now(),apiKey:n,ip:t.ip,country:t.country,pathname:t.pathname,method:t.method,blocked:e.blocked,reason:e.reason,score:e.score})})}catch{}finally{clearTimeout(s)}}U();var Q=class{constructor(t={}){this._config=t,this._store=t.storage??new v,this._logger=new T(t.log??"warn"),this._callbacks=[],this._remoteConfig=null,this._remoteConfigAt=0,this._remoteConfigTtl=15*60*1e3,this._quotaExceeded=!1,t.apiKey||(t.log??"warn")!=="none"&&console.info("[OwlGuard] No apiKey provided. Enrichment signals (threatScore, Tor, VPN, ASN) will be skipped. Get a key at https://deployowl.com")}async _fetchRemoteConfig(){if(this._config.apiKey)try{let n=await fetch("https://api.deployowl.com/api/v1/config",{method:"GET",headers:{"X-API-Key":this._config.apiKey}});if(n.status===402){this._quotaExceeded=!0,this._remoteConfigAt=Date.now();return}if(n.ok){let o=await n.json();this._remoteConfig=o,this._quotaExceeded=!!o.quotaExceeded,this._remoteConfigAt=Date.now()}}catch(t){this._logger.info(`[OwlGuard] Failed to fetch remote config: ${t.message}`)}}onDecision(t){return typeof t=="function"&&this._callbacks.push(t),this}async decision(t,n=null){let o=M(t),a=n,s=Date.now();!this._quotaExceeded&&this._config.remoteConfig===!0&&s-this._remoteConfigAt>=this._remoteConfigTtl&&await this._fetchRemoteConfig();let r={...this._config,...this._remoteConfig||{}};if(this._quotaExceeded&&(r.apiKey=null),r.apiKey)try{let{verifyHandshake:l}=await Promise.resolve().then(()=>(U(),X));if(await l(o.headers,r.apiKey)){let c=o.headers["x-owlguard-decision"]||"allow",u=o.headers["x-owlguard-reason"]||"allowed",b=parseInt(o.headers["x-owlguard-score"]||"0",10),w={blocked:c==="block",status:c==="block"?403:200,reason:u,score:isNaN(b)?0:b,html:null};return this._logger.info(`[HANDSHAKE BYPASS] Trusted Edge verdict: ${c} (score: ${w.score})`,o),w}}catch(l){this._logger.info(`[HANDSHAKE BYPASS] Handshake verification skipped: ${l.message}`)}let i=await Y(o,r,this._store,this._logger);return r.dryRun&&i.blocked&&(this._logger.info(`[DRY RUN] Would have blocked: ${i.reason} (score: ${i.score})`,o),i.blocked=!1,i.simulated=!0),this._fireCallbacks(i,o,a,r.apiKey),i}_fireCallbacks(t,n,o,a){let s=this._callbacks.map(l=>Promise.resolve().then(()=>l(t,n)).catch(()=>{})),r=a&&t.blocked&&this._config.reporting&&this._config.reportingSecret?J(t,n,a,this._config.reportingSecret).catch(()=>{}):Promise.resolve(),i=Promise.allSettled([...s,r]);o&&typeof o.waitUntil=="function"&&o.waitUntil(i)}};export{Q as OwlGuard,N as computeSignature};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deployowl/guard",
+  "version": "2.2.2",
+  "description": "Enterprise-grade, platform-agnostic bot detection and security middleware",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./types/index.d.ts"
+    },
+    "./adapters/redis": {
+      "import": "./adapters/redis.js",
+      "types": "./types/adapters.d.ts"
+    },
+    "./adapters/cloudflare-kv": {
+      "import": "./adapters/cloudflare-kv.js",
+      "types": "./types/adapters.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "adapters/",
+    "types/"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --format=esm --outfile=dist/index.js --minify --platform=neutral",
+    "dev": "esbuild src/index.js --bundle --format=esm --outfile=dist/index.js --platform=neutral --watch"
+  },
+  "keywords": [
+    "security",
+    "bot-detection",
+    "middleware",
+    "rate-limiting",
+    "geo-blocking",
+    "waf"
+  ],
+  "author": "OwlGuard",
+  "license": "Proprietary",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.21.5"
+  }
+}

package/types/adapters.d.ts

@@ -0,0 +1,64 @@
+/**
+ * owlguard — TypeScript type declarations for storage adapters.
+ */
+
+import type { StorageAdapter } from "./index.js";
+
+// ── Redis Adapter ─────────────────────────────────────────────────────────────
+
+/**
+ * Minimal interface for a Redis client.
+ * Compatible with both `ioredis` and `node-redis` (v4+).
+ */
+export interface RedisLike {
+  get(key: string): Promise<string | null>;
+  setEx(key: string, ttlSeconds: number, value: string): Promise<unknown>;
+}
+
+/**
+ * Pre-built storage adapter for Redis.
+ * Works with ioredis and node-redis (v4+).
+ *
+ * @example
+ * import { createClient } from "redis";
+ * import { RedisAdapter } from "owlguard/adapters/redis";
+ *
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ *
+ * const owl = new OwlGuard({
+ *   storage: new RedisAdapter(redis),
+ * });
+ */
+export declare class RedisAdapter implements StorageAdapter {
+  constructor(client: RedisLike);
+  get(key: string): Promise<{ ts: number; count: number } | null>;
+  put(key: string, value: { ts: number; count: number }, ttlSeconds: number): Promise<void>;
+}
+
+// ── Cloudflare KV Adapter ─────────────────────────────────────────────────────
+
+/**
+ * Minimal interface for a Cloudflare KV namespace.
+ */
+export interface CloudflareKVNamespace {
+  get(key: string, options: { type: "json" }): Promise<unknown>;
+  put(key: string, value: string, options: { expirationTtl: number }): Promise<void>;
+}
+
+/**
+ * Pre-built storage adapter for Cloudflare KV.
+ *
+ * @example
+ * // In your Cloudflare Worker:
+ * import { CloudflareKVAdapter } from "owlguard/adapters/cloudflare-kv";
+ *
+ * const owl = new OwlGuard({
+ *   storage: new CloudflareKVAdapter(env.OWL_RATE_LIMIT),
+ * });
+ */
+export declare class CloudflareKVAdapter implements StorageAdapter {
+  constructor(namespace: CloudflareKVNamespace);
+  get(key: string): Promise<{ ts: number; count: number } | null>;
+  put(key: string, value: { ts: number; count: number }, ttlSeconds: number): Promise<void>;
+}

package/types/index.d.ts

@@ -0,0 +1,233 @@
+/**
+ * owlguard — TypeScript type declarations
+ * Full types for the OwlGuard npm package public API.
+ */
+
+// ── Storage Adapter ───────────────────────────────────────────────────────────
+
+export interface StorageAdapter {
+  /** Retrieve a stored value by key. Returns null if not found. */
+  get(key: string): Promise<{ ts: number; count: number } | null>;
+  /** Store a value with a TTL in seconds. */
+  put(key: string, value: { ts: number; count: number }, ttlSeconds: number): Promise<void>;
+}
+
+// ── Configuration ─────────────────────────────────────────────────────────────
+
+export interface AllowlistApiKeysConfig {
+  /** The header name to check (e.g. "x-api-key"). */
+  header: string;
+  /** Values that are unconditionally trusted. */
+  values: string[];
+}
+
+export interface AllowlistConfig {
+  /** IPv4, IPv6, or CIDR ranges to unconditionally allow (e.g. "10.0.0.0/8"). */
+  ips?: string[];
+  /** API key header config for unconditional trust. */
+  apiKeys?: AllowlistApiKeysConfig;
+}
+
+export interface DenylistConfig {
+  /** IPv4, IPv6, or CIDR ranges to unconditionally block. */
+  ips?: string[];
+  /** ASN numbers to block entire ISPs or datacenters. */
+  asns?: number[];
+}
+
+export interface GeoConfig {
+  /**
+   * If set, ONLY these ISO 3166-1 alpha-2 country codes are allowed.
+   * Checked after geo.deny.
+   */
+  allow?: string[];
+  /** ISO 3166-1 alpha-2 country codes to always block. Checked first. */
+  deny?: string[];
+}
+
+export interface ScorerConfig {
+  /** UA patterns for verified good bots — always allowed (score = -1). */
+  goodBots?: RegExp[];
+  /** UA patterns that raise the bot suspicion score. */
+  badUaPatterns?: RegExp[];
+  /** Path patterns that raise the bot suspicion score. */
+  suspiciousPaths?: RegExp[];
+}
+
+export interface RateLimitConfig {
+  /** Sliding window duration in milliseconds. Default: 60000 (1 minute). */
+  windowMs?: number;
+  /** Maximum requests per window per IP. Default: 120. */
+  max?: number;
+}
+
+export interface ValidationConfig {
+  /** Maximum allowed body size in bytes. */
+  maxBodySize?: number;
+  /** Allowed HTTP methods. Default: GET, POST, PUT, DELETE, PATCH. */
+  allowedMethods?: string[];
+  /** Allowed Content-Type values (checked on POST, PUT, PATCH). */
+  allowedContentTypes?: string[];
+}
+
+export interface ChallengeConfig {
+  /**
+   * SHA-256 leading-zero difficulty.
+   * "00" ≈ 10ms, "000" ≈ 200ms (default), "0000" ≈ 3s.
+   */
+  difficulty?: string;
+  /** Title text shown on the challenge page. */
+  title?: string;
+  /** Body message shown on the challenge page. */
+  message?: string;
+}
+
+export interface OwlGuardConfig {
+  /**
+   * Your OwlGuard install key (owl_live_xxx).
+   * Optional — enrichment signals are skipped without it.
+   */
+  apiKey?: string;
+
+  /**
+   * External storage adapter for globally-consistent rate limiting.
+   * If omitted, OwlGuard uses an in-memory store (per-instance).
+   * For multi-instance deployments, provide a Redis or Cloudflare KV adapter.
+   */
+  storage?: StorageAdapter;
+
+  /**
+   * Path prefixes that skip ALL security checks.
+   * Use for webhooks, health probes, etc.
+   * e.g. ["/api/webhook", "/healthz"]
+   */
+  bypassPaths?: string[];
+
+  /** Requests matching any allowlist entry are unconditionally allowed. */
+  allowlist?: AllowlistConfig;
+
+  /** Requests matching any denylist entry are hard-blocked (403). */
+  denylist?: DenylistConfig;
+
+  /** Country-level geo fencing using ISO 3166-1 alpha-2 codes. */
+  geo?: GeoConfig;
+
+  /**
+   * Bot score threshold for a hard 403 block.
+   * Range: 0–100. Default: 80.
+   */
+  blockScore?: number;
+
+  /**
+   * Bot score threshold for a JS proof-of-work challenge.
+   * Range: 0–100. Default: 50.
+   */
+  challengeScore?: number;
+
+  /** Override the default bot scoring patterns. */
+  scorer?: ScorerConfig;
+
+  /** Rate limiting configuration. */
+  rateLimit?: RateLimitConfig;
+
+  /** Request shape validation. */
+  validation?: ValidationConfig;
+
+  /** JS proof-of-work challenge page configuration. */
+  challenge?: ChallengeConfig;
+
+  /**
+   * Console log verbosity.
+   * - "none"  — silent
+   * - "block" — hard blocks only
+   * - "warn"  — blocks + challenges (default)
+   * - "info"  — everything
+   */
+  log?: "none" | "block" | "warn" | "info";
+}
+
+// ── Decision Result ───────────────────────────────────────────────────────────
+
+/** All possible machine-readable reason keys returned in DecisionResult. */
+export type DecisionReason =
+  | "bypass"
+  | "allowlist_ip"
+  | "allowlist_apikey"
+  | "denylist_ip"
+  | "denylist_asn"
+  | "geo_deny"
+  | "geo_allow"
+  | "method_not_allowed"
+  | "body_too_large"
+  | "content_type_not_allowed"
+  | "rate_limited"
+  | "good_bot"
+  | "bot_score_block"
+  | "challenge"
+  | "allow";
+
+export interface DecisionResult {
+  /** True if the request should be stopped. */
+  blocked: boolean;
+  /** HTTP status to return (200, 403, 429, 405, 413, 415). */
+  status: number;
+  /** Machine-readable reason key. */
+  reason: DecisionReason;
+  /**
+   * Bot suspicion score at time of decision.
+   * Range: 0–100. -1 means verified good bot.
+   */
+  score: number;
+  /**
+   * Challenge page HTML. Only present when reason === "challenge".
+   * Return this as an HTML response with status 200.
+   */
+  html: string | null;
+}
+
+// ── Normalized Request Context (internal, exposed for onDecision) ─────────────
+
+export interface OwlContext {
+  ip: string;
+  country: string | null;
+  asn: number | null;
+  userAgent: string;
+  method: string;
+  pathname: string;
+  headers: Record<string, string>;
+  bodySize: number;
+  cookie: string;
+  cfRaw: Record<string, string | null> | null;
+}
+
+// ── OwlGuard Class ─────────────────────────────────────────────────────────────
+
+/** Callback invoked after every security decision. Never blocks the response. */
+export type OnDecisionCallback = (result: DecisionResult, ctx: OwlContext) => void | Promise<void>;
+
+export declare class OwlGuard {
+  constructor(config?: OwlGuardConfig);
+
+  /**
+   * Register a callback invoked after every security decision.
+   * Fires asynchronously — never blocks or delays the decision result.
+   * Use for logging, analytics, or billing integrations.
+   *
+   * @example
+   * owl.onDecision((result, ctx) => {
+   *   if (result.blocked) console.log(`Blocked ${ctx.ip}: ${result.reason}`);
+   * });
+   */
+  onDecision(fn: OnDecisionCallback): this;
+
+  /**
+   * Evaluates a request and returns a security decision.
+   *
+   * Accepts any of:
+   * - Cloudflare Worker Request
+   * - Node.js http.IncomingMessage
+   * - Generic fetch-API Request
+   * - Pre-normalized OwlContext object
+   */
+  decision(request: Request | import("http").IncomingMessage | OwlContext | object): Promise<DecisionResult>;
+}