@deployowl/guard

@deployowl/guard

Enterprise-grade, platform-agnostic bot detection and security middleware.

Security Notice (v2.2.0+)

This version removes a hardcoded shared secret (DEPLOYOWL_SUPER_SECRET_2026_XYZ) that was embedded in published source code. Previous versions (≤2.1.0) allowed anyone to forge reports and impersonate the SDK.

Behavior	v2.1.0	v2.2.0+
Hardcoded secret in published code	Present	Removed
Decision reporting to security.deployowl.com	Auto-on, undocumented	Opt-in (reporting: true + reportingSecret)
Enrichment calls to enrich.deployowl.com	Used hardcoded secret	Uses apiKey only
API key in URL query string	?apiKey=... in config fetch	Header only

Installation

npm install @deployowl/guard

Usage

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)
• Cloudflare headers (when running in a CF Worker)
• Authentication: apiKey only (no shared secret)
• 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, not hardcoded)
• 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 hardcoded secrets in published code.
• 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

MIT